libbitsub 1.10.2 → 1.12.0

package/pkg/README.md

@@ -1,6 +1,6 @@
 # libbit(map)sub
 
-High-performance WASM renderer for graphical subtitles (PGS, VobSub, and MKS-embedded VobSub), written in Rust.
+High-performance WASM renderer for graphical subtitles (PGS, VobSub, DVB-SUB, and MKS-embedded VobSub), written in Rust.
 
 Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js), this project was reworked for higher performance and broader format support. It keeps the familiar high-level PGS-oriented API while adding a lower-level parser surface, VobSub support, GPU backends, and worker-backed rendering.
 
@@ -8,9 +8,11 @@ Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js)
 
 - PGS (Blu-ray) subtitle parsing and rendering
 - VobSub (DVD) subtitle parsing and rendering
+- DVB-SUB (ETSI EN 300 743) parsing and rendering via PES/ES and `"DV"` PTS-framed dumps
 - Matroska `.mks` extraction for embedded `S_VOBSUB` tracks
 - WebGPU, WebGL2, and Canvas2D rendering with automatic fallback
 - Worker-backed parsing/rendering for large subtitle files
+- HTTP Range / streaming loads for large `.sup`, `.sub`, `.idx`, and `.mks` assets (progressive indexing where feasible)
 - Rich layout controls: scale, aspect mode, horizontal/vertical offsets, alignment, bottom padding, safe area, opacity
 - Cue metadata and parser introspection APIs
 - Rendered-frame export helpers for ImageData, ImageBitmap, Blob, and custom canvas targets
@@ -18,6 +20,7 @@ Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js)
 - Automatic format detection and unified loading helpers
 - First-class diagnostics with structured error codes, warning hooks, and render/cache snapshots
 - TypeScript support with exported event and metadata types
+- Optional player integrations for Video.js, Shaka Player, hls.js, and React (core stays dependency-free)
 
 ## Showcase
 
@@ -67,11 +70,11 @@ deno add jsr:@altq/libbitsub
 
 In most bundler-based projects, no manual worker setup is required. `libbitsub` now resolves the WASM asset relative to the package module URL, so bundlers such as Vite, webpack, and Rollup can emit the asset automatically.
 
-If your app serves package files in a way that does not expose that emitted WASM asset to the browser, you can still provide the legacy public fallback by copying the WASM file to `/libbitsub/libbitsub_bg.wasm`:
+If your app serves package files in a way that does not expose that emitted WASM asset to the browser, you can still provide the legacy public fallback by copying the WASM file and its JS glue to `/libbitsub/`:
 
 ```bash
 mkdir -p public/libbitsub
-cp node_modules/libbitsub/pkg/libbitsub_bg.wasm public/libbitsub/
+cp node_modules/libbitsub/pkg/libbitsub_bg.wasm node_modules/libbitsub/pkg/libbitsub.js public/libbitsub/
 ```
 
 The worker is still created inline. `workerUrl` remains in the option type only for compatibility and does not change runtime behavior.
@@ -110,6 +113,129 @@ const parser = new PgsParser()
 
 Calling `initWasm()` multiple times is safe (it deduplicates).
 
+### Worker prewarm (TV / players)
+
+On devices where the first subtitle track switch should not pay worker + WASM startup cost (for example TV apps), prewarm the shared parsing worker during app startup:
+
+```ts
+import { warmup, ready, PgsRenderer } from 'libbitsub'
+
+// Fire-and-forget at app boot (safe to call multiple times).
+void warmup()
+
+// Before the user changes tracks, ensure the worker is ready.
+await ready()
+
+const renderer = new PgsRenderer({ video: videoElement, subContent: trackBytes })
+```
+
+`warmup()` and `ready()` share a single worker-init promise with renderer creation. The shared worker is only published after in-worker WASM initialization succeeds. When Web Workers are unavailable, both resolve immediately and renderers use the main thread.
+
+### Range / streaming loads (TV / slow networks)
+
+URL-based loads (`subUrl` / `idxUrl`) use progressive fetch by default:
+
+- Probe HTTP Range support and, for large assets, download with Range chunks when the origin allows it
+- Stream the response body otherwise and report `load-progress` events
+- **PGS (`.sup`)**: feed chunks into the parser as they arrive so cues can be indexed before the full file finishes
+- **VobSub (`.idx` + `.sub`)**: parse the small `.idx` first for timestamps, then stream/Range-download the `.sub` body and attach packets
+- **MKS**: stream/Range-download the container first (Matroska extraction still needs the assembled payload), then parse
+- **In-memory** `subContent` / `idxContent` remains the simple full-buffer path
+
+```ts
+import { PgsRenderer } from 'libbitsub'
+
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  // streamingLoad: true,  // default
+  // rangeRequests: true,  // default
+  onEvent: (event) => {
+    if (event.type === 'load-progress') {
+      console.log(event.strategy, event.loadedBytes, event.totalBytes, event.indexedCues)
+    }
+    if (event.type === 'indexed') {
+      console.log('cues ready', event.metadata.cueCount, event.partial ? '(partial)' : '(final)')
+    }
+  }
+})
+```
+
+Disable progressive behavior when you want a single blocking GET:
+
+```ts
+new PgsRenderer({ video, subUrl, streamingLoad: false, rangeRequests: false })
+```
+
+Low-level helpers are also exported: `probeRangeSupport()`, `fetchSubtitleAsset()`, and `fetchSubtitleText()`.
+
+## Player integrations
+
+Optional adapters ship as **subpath exports**. They wrap the high-level renderers for common players while keeping the core package free of player/React dependencies (peer deps are optional and only needed when you import that adapter).
+
+| Import                   | Adapter                                  | Optional peer       |
+| ------------------------ | ---------------------------------------- | ------------------- |
+| `libbitsub/videojs`      | Video.js plugin (`registerBitSubPlugin`) | `video.js` >= 7     |
+| `libbitsub/shaka`        | `attachBitSubToShaka(player, options)`   | `shaka-player` >= 4 |
+| `libbitsub/hlsjs`        | `attachBitSubToHls(hls, options)`        | `hls.js` >= 1       |
+| `libbitsub/react`        | `useBitSub` / `BitSubOverlay`            | `react` >= 18       |
+| `libbitsub/integrations` | Shared `attachBitSub` controller         | —                   |
+
+Copy-paste recipes live under [`examples/`](./examples).
+
+### Video.js
+
+```ts
+import videojs from 'video.js'
+import { registerBitSubPlugin } from 'libbitsub/videojs'
+
+registerBitSubPlugin(videojs)
+const player = videojs('my-video')
+const bitsub = player.bitsub({ subUrl: '/subs/movie.sup' })
+bitsub.load({ subUrl: '/subs/other.sup' })
+```
+
+### Shaka Player
+
+```ts
+import { attachBitSubToShaka } from 'libbitsub/shaka'
+
+const bitsub = attachBitSubToShaka(player, { subUrl: '/subs/movie.sup' })
+// later
+bitsub.dispose()
+```
+
+### hls.js
+
+```ts
+import Hls from 'hls.js'
+import { attachBitSubToHls } from 'libbitsub/hlsjs'
+
+const hls = new Hls()
+hls.loadSource(url)
+hls.attachMedia(video)
+const bitsub = attachBitSubToHls(hls, { subUrl: '/subs/movie.sup' })
+```
+
+### React
+
+```tsx
+import { useRef } from 'react'
+import { useBitSub } from 'libbitsub/react'
+
+function Player({ src, subUrl }: { src: string; subUrl: string }) {
+  const videoRef = useRef<HTMLVideoElement>(null)
+  useBitSub(videoRef, { subUrl })
+  return (
+    <div style={{ position: 'relative' }}>
+      <video ref={videoRef} src={src} controls playsInline />
+    </div>
+  )
+}
+```
+
+Bitmap PGS/VobSub/MKS tracks are external canvas overlays, not native HTML/TextTrack entries. Prefer deep imports so unused adapters stay out of your bundle.
+
 ## High-level video renderers
 
 The high-level API manages subtitle loading, canvas overlay creation, playback sync, resize handling, worker usage, and renderer fallback.
@@ -131,6 +257,7 @@ const renderer = new PgsRenderer({
   },
   cacheLimit: 32,
   prefetchWindow: { before: 1, after: 2 },
+  frameAwareSync: true,
   onWarning: (warning) => {
     console.warn(warning.code, warning.message, warning.details)
   },
@@ -144,6 +271,33 @@ const renderer = new PgsRenderer({
 renderer.dispose()
 ```
 
+Mount into a fullscreen shell or Shadow DOM root, reuse a player-owned canvas,
+cap high-DPI backing-store cost, or bypass automatic backend selection:
+
+```ts
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  container: shadowRoot, // HTMLElement or ShadowRoot; defaults to video.parentElement
+  canvas: playerOverlayCanvas, // optional; remains mounted after dispose()
+  devicePixelRatioCap: 2,
+  backend: 'webgl2' // 'auto' | 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d'
+})
+```
+
+An explicitly requested GPU or worker backend falls back to Canvas2D if it cannot
+initialize. A supplied `container` takes precedence over the canvas's current parent;
+without one, an already-mounted caller canvas stays in its existing host. Automatic
+selection does not transfer a caller-owned canvas to a worker; request
+`backend: 'worker-offscreen'` explicitly to allow that ownership transfer.
+
+Frame-aware synchronization is enabled by default. On browsers with
+`requestVideoFrameCallback()`, cue lookup uses the `mediaTime` of the frame sent
+to the compositor instead of polling `video.currentTime`. Older browsers fall
+back to `requestAnimationFrame()` automatically; set `frameAwareSync: false` to
+force that compatibility path. The active path is available as
+`renderer.getSynchronizationMode()` and as `getStats().syncMode`.
+
 ### VobSub renderer
 
 ```ts
@@ -165,6 +319,45 @@ renderer.setDebandThreshold(64)
 renderer.setDebandRange(15)
 ```
 
+### DVB renderer
+
+```ts
+import { DvbRenderer } from 'libbitsub'
+
+const renderer = new DvbRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/track.dvb'
+})
+```
+
+DVB dumps use libbitsub framing:
+
+```
+"DV" | pts_90k_be_u32 | payload_len_be_u32 | payload…
+```
+
+`payload` is a PES data field (`0x20 0x00 …`) or raw segments (`sync_byte 0x0F`). Concatenated MPEG PES packets (`00 00 01 BD`) with PTS are also accepted.
+
+The DVB decoder renders bitmap object coding method 0. Character-string and reserved object coding methods are ignored.
+
+### Live / push streams
+
+PGS and DVB renderers can start without a URL or in-memory subtitle file. Push transport or demuxer chunks as they arrive; calls are processed in order even when they are made before renderer initialization completes.
+
+```ts
+import { DvbRenderer } from 'libbitsub'
+
+const renderer = new DvbRenderer({ video: videoElement })
+
+const added = await renderer.append(dvbPesChunk) // newly indexed cues
+const total = await renderer.flush() // finalize trailing input; total indexed cues
+
+await renderer.reset() // clear cues/caches/display, then reuse the same renderer
+await renderer.append(nextChannelChunk)
+```
+
+`append()` accepts `Uint8Array` or `ArrayBuffer` without detaching the caller's buffer. `flush()` discards incomplete trailing bytes; later appends are still accepted. `reset()` keeps the canvas, worker session, render loop, and configuration alive while clearing the stream state. VobSub does not expose the push API because it depends on its `.idx`/container index.
+
 ### Automatic format detection
 
 ```ts
@@ -177,7 +370,7 @@ const renderer = createAutoSubtitleRenderer({
 })
 ```
 
-Automatic detection uses file hints when available and otherwise inspects the binary payload. `.mks` sources are treated as VobSub only when they contain an embedded `S_VOBSUB` track. If the format cannot be identified confidently, it throws instead of silently forcing a parser.
+Automatic detection uses file hints when available and otherwise inspects the binary payload. `.idx` / `idxContent` still means VobSub. Bare `.sub` is content-probed for DVB before VobSub. `.mks` sources are treated as VobSub only when they contain an embedded `S_VOBSUB` track. If the format cannot be identified confidently, it throws instead of silently forcing a parser.
 
 ## Layout controls
 
@@ -207,16 +400,16 @@ renderer.resetDisplaySettings()
 
 `SubtitleDisplaySettings`:
 
-| Field | Type | Range / values | Meaning |
-| --- | --- | --- | --- |
-| `scale` | number | `0.1` to `3.0` | Overall subtitle scale |
-| `aspectMode` | `'stretch' \| 'contain' \| 'cover'` | fixed set | How subtitle screen coordinates map into the visible video box |
-| `verticalOffset` | number | `-50` to `50` | Vertical movement as percent of video height |
-| `horizontalOffset` | number | `-50` to `50` | Horizontal movement as percent of video width |
-| `horizontalAlign` | `'left' \| 'center' \| 'right'` | fixed set | Anchor used when scaling subtitle groups |
-| `bottomPadding` | number | `0` to `50` | Extra padding from the bottom edge |
-| `safeArea` | number | `0` to `25` | Clamp subtitles inside a video-safe area |
-| `opacity` | number | `0.0` to `1.0` | Global subtitle opacity |
+| Field              | Type                                | Range / values | Meaning                                                        |
+| ------------------ | ----------------------------------- | -------------- | -------------------------------------------------------------- |
+| `scale`            | number                              | `0.1` to `3.0` | Overall subtitle scale                                         |
+| `aspectMode`       | `'stretch' \| 'contain' \| 'cover'` | fixed set      | How subtitle screen coordinates map into the visible video box |
+| `verticalOffset`   | number                              | `-50` to `50`  | Vertical movement as percent of video height                   |
+| `horizontalOffset` | number                              | `-50` to `50`  | Horizontal movement as percent of video width                  |
+| `horizontalAlign`  | `'left' \| 'center' \| 'right'`     | fixed set      | Anchor used when scaling subtitle groups                       |
+| `bottomPadding`    | number                              | `0` to `50`    | Extra padding from the bottom edge                             |
+| `safeArea`         | number                              | `0` to `25`    | Clamp subtitles inside a video-safe area                       |
+| `opacity`          | number                              | `0.0` to `1.0` | Global subtitle opacity                                        |
 
 ## Metadata and introspection
 
@@ -291,14 +484,7 @@ Like `UnifiedSubtitleParser.loadAuto()`, this is a low-level in-memory API: pass
 Low-level parser output can be flattened into a single exportable frame for previews, editors, snapshots, fixture generation, or visual diffing.
 
 ```ts
-import {
-  PgsParser,
-  initWasm,
-  renderFrameData,
-  toBlob,
-  toCanvas,
-  toImageBitmap
-} from 'libbitsub'
+import { PgsParser, initWasm, renderFrameData, toBlob, toCanvas, toImageBitmap } from 'libbitsub'
 
 await initWasm()
 
@@ -385,7 +571,7 @@ Structured diagnostic error codes currently include:
 - `WORKER_FALLBACK`
 - `UNKNOWN`
 
-Warnings use a smaller code set focused on non-fatal conditions such as malformed bitmap buffers, worker fallback, and missing PGS palettes during render.
+Warnings use a smaller code set focused on non-fatal conditions such as malformed bitmap buffers, worker fallback, progressive/Range fallback (`RANGE_FALLBACK`), and missing PGS palettes during render.
 
 ## MKS security and corruption checks
 
@@ -415,6 +601,8 @@ const renderer = new PgsRenderer({
   onEvent: (event) => {
     switch (event.type) {
       case 'loading':
+      case 'load-progress':
+      case 'indexed':
       case 'loaded':
       case 'error':
       case 'warning':
@@ -482,17 +670,17 @@ renderer.dispose()
 
 Emitted events:
 
-| Event | Payload |
-| --- | --- |
-| `loading` | subtitle format |
-| `loaded` | subtitle format and parser metadata |
-| `error` | subtitle format and `SubtitleDiagnosticErrorLike` |
-| `warning` | `SubtitleDiagnosticWarning` |
-| `renderer-change` | active backend: `webgpu`, `webgl2`, or `canvas2d` |
-| `worker-state` | whether worker mode is enabled, ready, fallback status, and the active session ID |
-| `cache-change` | cached frame count, pending renders, and configured cache limit |
-| `cue-change` | current cue metadata or `null` when nothing is displayed |
-| `stats` | periodic renderer stats snapshot |
+| Event             | Payload                                                                           |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `loading`         | subtitle format                                                                   |
+| `loaded`          | subtitle format and parser metadata                                               |
+| `error`           | subtitle format and `SubtitleDiagnosticErrorLike`                                 |
+| `warning`         | `SubtitleDiagnosticWarning`                                                       |
+| `renderer-change` | active backend: `webgpu`, `webgl2`, `worker-offscreen`, or `canvas2d`             |
+| `worker-state`    | whether worker mode is enabled, ready, fallback status, and the active session ID |
+| `cache-change`    | cached frame count, pending renders, and configured cache limit                   |
+| `cue-change`      | current cue metadata or `null` when nothing is displayed                          |
+| `stats`           | periodic renderer stats snapshot                                                  |
 
 ## Performance stats
 
@@ -514,6 +702,7 @@ const stats = renderer.getStats()
 - `pendingRenders`
 - `totalEntries`
 - `currentIndex`
+- `syncMode`
 
 `getCacheStats()` adds worker/session state for the current renderer cache, while `getLastRenderInfo()` exposes the most recent render outcome with a status of `rendered`, `cleared`, `pending`, `empty`, or `failed`.
 
@@ -563,23 +752,50 @@ const parser = new UnifiedSubtitleParser({
 parser.loadAuto({ data: subtitleBytes, fileName: 'track.sup' })
 ```
 
-## GPU backends
+## GPU / present backends
 
 libbitsub prefers:
 
-1. WebGPU
-2. WebGL2
-3. Canvas2D
+1. WebGPU (main-thread present)
+2. WebGL2 (main-thread present)
+3. Worker OffscreenCanvas (decode + Canvas2D present off the UI thread)
+4. Canvas2D (main-thread fallback for older TVs)
 
 ```ts
-import { isWebGPUSupported } from 'libbitsub'
+import { getRuntimeCapabilities, isWebGPUSupported } from 'libbitsub'
 
 console.log({
-  webgpu: isWebGPUSupported()
+  webgpu: isWebGPUSupported(),
+  capabilities: getRuntimeCapabilities()
 })
 ```
 
-WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, or `onWarning` if you need to observe backend changes.
+When Worker OffscreenCanvas is selected, composition/present moves into the shared worker —
+not only parsing — which reduces UI stalls during subtitle track switches on constrained devices.
+The existing transferable RGBA path remains for main-thread GPU/Canvas2D present.
+
+Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, `onWarning`, or `getRuntimeCapabilities()`
+to observe or explain the active backend path. Set `offscreenRender: false` to force main-thread
+Canvas2D on the software tier.
+
+## Compatibility & visual regression
+
+A formal suite locks decoder edge cases and backend pixel parity:
+
+- Malformed PGS / VobSub / MKS fixtures
+- Palette edge cases and zero-length RLE runs
+- Alternate display sizes (SD → 4K)
+- Slow worker startup / shared init
+- Pixel-level goldens across software, Canvas2D, WebGL2, and WebGPU
+
+```bash
+bun run test        # Rust core (includes compatibility fixtures)
+bun run test:ts     # TypeScript fixtures, goldens, worker startup
+bun run test:visual # Headless Chromium backend parity
+bun run test:all    # All of the above
+```
+
+Browser/device support matrix (including webOS TV): [docs/COMPATIBILITY.md](./docs/COMPATIBILITY.md).
 
 ## Notes
 
@@ -594,10 +810,13 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 
 - `initWasm(): Promise<void>` initializes the WASM module. Called automatically by high-level renderers and on first import in browser environments. Safe to call multiple times. Only needed explicitly for low-level parser usage.
 - `isWasmInitialized(): boolean` reports whether initialization has completed.
+- `warmup(): Promise<void>` / `ready(): Promise<void>` pre-initialize the shared subtitle worker (including in-worker WASM). Safe to call multiple times; concurrent callers share one init promise. Prefer these in TV/player apps before the first track switch.
+- `isWorkerAvailable(): boolean` / `isWorkerReady(): boolean` report worker support and whether the shared worker has finished initializing.
 - `isWebGPUSupported(): boolean` checks WebGPU support.
-- `detectSubtitleFormat(source: AutoSubtitleSource): 'pgs' | 'vobsub' | null` detects the bitmap subtitle format from file hints or binary data.
-- `createAutoSubtitleRenderer(options: AutoVideoSubtitleOptions): PgsRenderer | VobSubRenderer` creates a high-level renderer after format detection.
+- `detectSubtitleFormat(source: AutoSubtitleSource): 'pgs' | 'vobsub' | 'dvb' | null` detects the bitmap subtitle format from file hints or binary data.
+- `createAutoSubtitleRenderer(options: AutoVideoSubtitleOptions): PgsRenderer | VobSubRenderer | DvbRenderer` creates a high-level renderer after format detection.
 - `openSubtitles(source, options?): Promise<OpenedSubtitles>` initializes WASM, auto-detects the low-level format, and returns a normalized parser handle.
+- `probeRangeSupport(url, options?)` / `fetchSubtitleAsset(url, options?, onChunk?)` / `fetchSubtitleText(url, options?)` perform Range-aware progressive asset downloads for custom loaders.
 - `renderFrameData(frame, options?): SubtitleRenderedFrameData | null` composes a `SubtitleData` frame into exportable pixels.
 - `toCanvas(frame, target?, options?): HTMLCanvasElement | OffscreenCanvas` draws a rendered frame to a new or existing canvas/context.
 - `toImageBitmap(frame, options?): Promise<ImageBitmap>` creates an `ImageBitmap` from a subtitle frame export.
@@ -605,6 +824,7 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `SubtitleDiagnosticError` is the structured error class libbitsub uses for coded diagnostics.
 - `createSubtitleDiagnosticError(...)` and `normalizeSubtitleError(...)` are exported for integrations that want to preserve libbitsub-style error codes.
 - Legacy aliases remain exported: `PGSRenderer`, `VobsubRenderer`, `UnifiedSubtitleRenderer`.
+- Optional integration entry points: `libbitsub/videojs`, `libbitsub/shaka`, `libbitsub/hlsjs`, `libbitsub/react`, `libbitsub/integrations` (see [examples/](./examples) and [references/api.md](./references/api.md)).
 
 ### High-level renderers
 
@@ -625,21 +845,30 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `clearFrameCache(): void` clears the renderer-side and parser-side frame cache.
 - `prefetchRange(startIndex: number, endIndex: number): Promise<void>` prefetches decoded frames for a cue range.
 - `prefetchAroundTime(time: number, before?: number, after?: number): Promise<void>` prefetches around a playback time in seconds.
+- `append(data: Uint8Array | ArrayBuffer): Promise<number>` pushes live bytes and returns newly indexed cues.
+- `flush(): Promise<number>` finalizes trailing input and returns the total cue count.
+- `reset(): Promise<void>` clears live parser, cue, cache, and presentation state for reuse.
 - `dispose(): void` releases DOM, parser, and worker resources.
 
 #### `VobSubRenderer`
 
-- Supports all `PgsRenderer` methods above.
+- Supports the common `PgsRenderer` methods above, except `append()`, `flush()`, and `reset()`.
 - `setDebandEnabled(enabled: boolean): void` enables or disables debanding.
 - `setDebandThreshold(threshold: number): void` updates the deband threshold.
 - `setDebandRange(range: number): void` updates the deband sample range.
 - `debandEnabled: boolean` reports whether debanding is enabled.
 
+#### `DvbRenderer`
+
+- Supports all `PgsRenderer` methods above, including the live push API (no debanding).
+
 ### Low-level parsers
 
 #### `PgsParser`
 
-- `load(data: Uint8Array): number` loads PGS data and returns the cue count.
+- `load(data: Uint8Array): number` loads PGS data and returns the cue count (simple in-memory path).
+- `reset(): void` / `feed(data: Uint8Array): number` / `finishFeed(): number` progressive indexing APIs for streamed chunks.
+- `pendingLen: number` incomplete trailing bytes retained between `feed()` calls.
 - `getTimestamps(): Float64Array` returns cue timestamps in milliseconds.
 - `count: number` returns the number of cues.
 - `findIndexAtTimestamp(timeSeconds: number): number` finds the cue index for a playback time in seconds.
@@ -650,9 +879,18 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `clearCache(): void` clears parser-side caches.
 - `dispose(): void` frees parser resources.
 
+#### `DvbParser`
+
+- Same progressive surface as `PgsParser` for `"DV"`-framed dumps and MPEG PES streams.
+- `load(data: Uint8Array): number` / `feed` / `finishFeed` / `renderAtIndex` / `renderAtTimestamp` / `getMetadata` / `getCueMetadata` / `dispose`.
+- `getEndTimestamps(): Float64Array` returns the page-timeout-aware cue end timestamps in milliseconds.
+
 #### `VobSubParserLowLevel`
 
-- `loadFromData(idxContent: string, subData: Uint8Array): void` loads IDX and SUB data.
+- `loadFromData(idxContent: string, subData: Uint8Array): void` loads IDX and SUB data (simple in-memory path).
+- `loadFromIdx(idxContent: string): void` indexes timestamps from IDX before packet bytes arrive.
+- `attachSubData(subData: Uint8Array): void` attaches `.sub` packets after an IDX-first load.
+- `hasSubData: boolean` whether packet bytes are currently attached.
 - `loadFromSubOnly(subData: Uint8Array): void` loads SUB-only VobSub data.
 - `getTimestamps(): Float64Array`, `count`, `findIndexAtTimestamp()`, `renderAtIndex()`, `renderAtTimestamp()`, `getMetadata()`, `getCueMetadata()`, `clearCache()`, and `dispose()` behave like `PgsParser`.
 - `setDebandEnabled(enabled: boolean): void`, `setDebandThreshold(threshold: number): void`, `setDebandRange(range: number): void`, and `debandEnabled` control debanding.
@@ -662,8 +900,9 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `loadPgs(data: Uint8Array): number` loads PGS data.
 - `loadVobSub(idxContent: string, subData: Uint8Array): void` loads VobSub from IDX and SUB.
 - `loadVobSubOnly(subData: Uint8Array): void` loads SUB-only VobSub data.
+- `loadDvb(data: Uint8Array): number` loads DVB data.
 - `loadAuto(source: AutoSubtitleSource): SubtitleFormatName` detects and loads a supported bitmap subtitle format.
-- `format: 'pgs' | 'vobsub' | null` returns the active format.
+- `format: 'pgs' | 'vobsub' | 'dvb' | null` returns the active format.
 - `getTimestamps()`, `count`, `findIndexAtTimestamp()`, `renderAtIndex()`, `renderAtTimestamp()`, `getMetadata()`, `getCueMetadata()`, `clearCache()`, and `dispose()` are available as on the format-specific parsers.
 
 ### Core option and data types
@@ -673,6 +912,10 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 ```ts
 interface VideoSubtitleOptions {
   video: HTMLVideoElement
+  container?: HTMLElement | ShadowRoot
+  canvas?: HTMLCanvasElement
+  devicePixelRatioCap?: number
+  backend?: 'auto' | 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d'
   subUrl?: string
   subContent?: ArrayBuffer
   workerUrl?: string
@@ -681,12 +924,16 @@ interface VideoSubtitleOptions {
   onError?: (error: Error) => void
   onWebGPUFallback?: () => void
   onWebGL2Fallback?: () => void
+  offscreenRender?: boolean // default true — Worker OffscreenCanvas on Canvas2D tier
+  frameAwareSync?: boolean // default true — sync to presented-frame mediaTime when available
   displaySettings?: Partial<SubtitleDisplaySettings>
   cacheLimit?: number
   prefetchWindow?: {
     before?: number
     after?: number
   }
+  streamingLoad?: boolean // default true — progressive URL loads
+  rangeRequests?: boolean // default true — use HTTP Range when supported
   onEvent?: (event: SubtitleRendererEvent) => void
 }
 ```
@@ -733,7 +980,7 @@ type SubtitleRendererEvent =
   | { type: 'loaded'; format: SubtitleFormatName; metadata: SubtitleParserMetadata }
   | { type: 'error'; format: SubtitleFormatName; error: SubtitleDiagnosticErrorLike }
   | { type: 'warning'; warning: SubtitleDiagnosticWarning }
-  | { type: 'renderer-change'; renderer: 'webgpu' | 'webgl2' | 'canvas2d' }
+  | { type: 'renderer-change'; renderer: 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d' }
   | { type: 'worker-state'; enabled: boolean; ready: boolean; sessionId: string | null; fallback?: boolean }
   | { type: 'cache-change'; cachedFrames: number; pendingRenders: number; cacheLimit: number }
   | { type: 'cue-change'; cue: SubtitleCueMetadata | null }
@@ -766,7 +1013,7 @@ Related diagnostics shapes:
 
 ```ts
 interface SubtitleParserMetadata {
-  format: 'pgs' | 'vobsub'
+  format: 'pgs' | 'vobsub' | 'dvb'
   cueCount: number
   screenWidth: number
   screenHeight: number