libbitsub 1.10.1 → 1.11.0

package/examples/react/README.md

@@ -0,0 +1,60 @@
+# React + libbitsub
+
+## Install
+
+```bash
+npm install libbitsub react react-dom
+```
+
+## Hook recipe
+
+```tsx
+import { useRef } from 'react'
+import { useBitSub } from 'libbitsub/react'
+
+export function VideoWithBitmaps({ src, subUrl }: { src: string; subUrl: string }) {
+  const videoRef = useRef<HTMLVideoElement>(null)
+  const { error } = useBitSub(videoRef, {
+    subUrl,
+    fileName: subUrl,
+    displaySettings: { scale: 1.05, bottomPadding: 4 },
+    onEvent: (event) => {
+      if (event.type === 'cue-change') {
+        console.log('cue', event.cue)
+      }
+    }
+  })
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <video ref={videoRef} src={src} controls playsInline style={{ width: '100%' }} />
+      {error ? <p role='alert'>{error.message}</p> : null}
+    </div>
+  )
+}
+```
+
+## Overlay component recipe
+
+```tsx
+import { useRef } from 'react'
+import { BitSubOverlay } from 'libbitsub/react'
+
+export function Player({ src, subUrl }: { src: string; subUrl: string }) {
+  const videoRef = useRef<HTMLVideoElement>(null)
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <video ref={videoRef} src={src} controls playsInline />
+      <BitSubOverlay videoRef={videoRef} subUrl={subUrl} displaySettings={{ aspectMode: 'cover' }} />
+    </div>
+  )
+}
+```
+
+## Notes
+
+- Prefer **either** `useBitSub` **or** `BitSubOverlay` on the same video — not both.
+- Parent should be non-static (`relative` is enough) so the canvas overlay can position correctly.
+- Changing `subUrl` / content identity disposes and recreates the renderer; layout-only `displaySettings` updates are applied in place.
+- Call sites that need imperative control can read `controller` from `useBitSub` (`load`, `clear`, `setDisplaySettings`).

package/examples/shaka/README.md

@@ -0,0 +1,61 @@
+# Shaka Player + libbitsub
+
+## Install
+
+```bash
+npm install libbitsub shaka-player
+```
+
+## Recipe
+
+```ts
+import shaka from 'shaka-player'
+import { attachBitSubToShaka } from 'libbitsub/shaka'
+
+shaka.polyfill.installAll()
+
+const video = document.getElementById('video') as HTMLVideoElement
+const player = new shaka.Player()
+await player.attach(video)
+await player.load('/media/manifest.mpd')
+
+// Bitmap tracks are external overlays (not Shaka TextTrack objects).
+const bitsub = attachBitSubToShaka(player, {
+  subUrl: '/subs/movie.sup',
+  prefetchWindow: { before: 1, after: 2 },
+  onError: (error) => console.error(error)
+})
+
+// Switch tracks at runtime:
+bitsub.load({
+  subUrl: '/subs/movie.idx', // companion .sub inferred / provide subUrl to .sub
+  idxUrl: '/subs/movie.idx',
+  fileName: 'movie.sub'
+})
+
+// Prefer explicit VobSub pair:
+bitsub.load({
+  subUrl: '/subs/movie.sub',
+  idxUrl: '/subs/movie.idx'
+})
+
+bitsub.setDisplaySettings({ safeArea: 5, opacity: 0.95 })
+
+// Cleanup
+bitsub.dispose()
+await player.destroy()
+```
+
+## HTML sketch
+
+```html
+<div style="position: relative">
+  <video id="video" controls playsinline></video>
+</div>
+```
+
+## Notes
+
+- Uses `player.getMediaElement()` and requires an `HTMLVideoElement`.
+- Listens for Shaka `loaded` / `unloading` when available to rebind or clear.
+- Keep using Shaka's native text pipeline for WebVTT/TTML; use libbitsub only for PGS/VobSub/MKS bitmaps.

package/examples/videojs/README.md

@@ -0,0 +1,55 @@
+# Video.js + libbitsub
+
+## Install
+
+```bash
+npm install libbitsub video.js
+```
+
+## Recipe
+
+```ts
+import videojs from 'video.js'
+import 'video.js/dist/video-js.css'
+import { registerBitSubPlugin } from 'libbitsub/videojs'
+
+registerBitSubPlugin(videojs)
+
+const player = videojs('my-video', {
+  controls: true,
+  sources: [{ src: '/media/movie.mp4', type: 'video/mp4' }]
+})
+
+// Autoload a PGS track when the plugin starts:
+const bitsub = player.bitsub({
+  subUrl: '/subs/movie.sup',
+  displaySettings: { aspectMode: 'cover', bottomPadding: 6 },
+  onEvent: (event) => console.log('bitsub', event)
+})
+
+// Or load later (e.g. after the user picks a language):
+bitsub.load({
+  subUrl: '/subs/movie.eng.sup',
+  fileName: 'movie.eng.sup'
+})
+
+bitsub.setDisplaySettings({ scale: 1.1 })
+bitsub.clear()
+
+// Plugin resources are released with the player:
+// player.dispose()
+```
+
+## HTML sketch
+
+```html
+<video id="my-video" class="video-js vjs-big-play-centered" playsinline></video>
+```
+
+Ensure the player container can host an absolutely positioned canvas (Video.js already uses non-static positioning on its root).
+
+## Notes
+
+- Resolves the tech `<video>` element via `player.tech(true)` with a DOM fallback.
+- Rebinds on `loadeddata` if the tech element is replaced.
+- Emits `bitsubload` / `bitsubclear` on the player for light app wiring.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libbitsub",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "author": "altqx",
   "license": "MIT",
   "description": "High-performance WASM renderer for graphical subtitles (PGS and VobSub)",
@@ -17,48 +17,104 @@
     "rust",
     "rendering",
     "video",
-    "player"
+    "player",
+    "videojs",
+    "shaka",
+    "hls.js",
+    "react"
   ],
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     },
     "./pkg": {
+      "types": "./pkg/libbitsub.d.ts",
       "import": "./pkg/libbitsub.js",
-      "types": "./pkg/libbitsub.d.ts"
+      "default": "./pkg/libbitsub.js"
+    },
+    "./videojs": {
+      "types": "./dist/integrations/videojs.d.ts",
+      "import": "./dist/integrations/videojs.js",
+      "default": "./dist/integrations/videojs.js"
+    },
+    "./shaka": {
+      "types": "./dist/integrations/shaka.d.ts",
+      "import": "./dist/integrations/shaka.js",
+      "default": "./dist/integrations/shaka.js"
+    },
+    "./hlsjs": {
+      "types": "./dist/integrations/hlsjs.d.ts",
+      "import": "./dist/integrations/hlsjs.js",
+      "default": "./dist/integrations/hlsjs.js"
+    },
+    "./react": {
+      "types": "./dist/integrations/react.d.ts",
+      "import": "./dist/integrations/react.js",
+      "default": "./dist/integrations/react.js"
+    },
+    "./integrations": {
+      "types": "./dist/integrations/index.d.ts",
+      "import": "./dist/integrations/index.js",
+      "default": "./dist/integrations/index.js"
     }
   },
   "files": [
     "dist",
     "pkg",
-    "src/wrapper.ts"
+    "src/wrapper.ts",
+    "src/integrations",
+    "examples"
   ],
   "scripts": {
     "build:wasm": "wasm-pack build --target web --out-dir pkg",
     "build:wasm:release": "wasm-pack build --release --target web --out-dir pkg",
     "build:wasm:bundler": "wasm-pack build --target bundler --out-dir pkg-bundler",
-    "build:ts": "tsgo",
+    "build:ts": "tsc",
     "build": "bun run build:wasm:release && bun run build:ts",
     "clean": "rm -rf pkg pkg-bundler dist target",
-    "test": "cargo test",
+    "test": "cargo test --workspace",
+    "test:ts": "bun test src/ts",
+    "test:visual": "bun tests/visual/run.mjs",
+    "test:all": "bun run test && bun run test:ts && bun run test:visual",
     "test:wasm": "wasm-pack test --headless --chrome",
     "format": "cargo fmt && prettier . --write"
   },
   "devDependencies": {
-    "@typescript/native-preview": "^7.0.0-dev.20260524.1",
-    "prettier": "^3.8.3",
-    "typescript": "^6.0.3"
+    "@types/react": "^19.2.17",
+    "prettier": "^3.9.6",
+    "react": "^19.2.8",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "hls.js": ">=1.0.0",
+    "react": ">=18.0.0",
+    "shaka-player": ">=4.0.0",
+    "video.js": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "hls.js": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "shaka-player": {
+      "optional": true
+    },
+    "video.js": {
+      "optional": true
+    }
   },
-  "peerDependencies": {},
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
-    "@webgpu/types": "^0.1.70"
+    "@webgpu/types": "^0.1.71"
   }
 }

package/pkg/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 Jaruwit Jaiya
+Copyright (c) 2024 David Schulte, and Libpgs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/pkg/README.md

@@ -11,6 +11,7 @@ Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js)
 - 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 +19,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
 
@@ -39,14 +41,14 @@ For pure Rust parser/rendering logic:
 
 ```toml
 [dependencies]
-libbitsub-core = "1.10.0"
+libbitsub-core = "1.10.1"
 ```
 
 For WASM bindings from Rust:
 
 ```toml
 [dependencies]
-libbitsub = "1.10.0"
+libbitsub = "1.10.1"
 ```
 
 For JavaScript package managers:
@@ -67,11 +69,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 +112,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.
@@ -207,16 +332,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 +416,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 +503,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 +533,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 +602,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`, 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
 
@@ -581,6 +701,25 @@ console.log({
 
 WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, or `onWarning` if you need to observe backend changes.
 
+## 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
 
 - Worker mode is shared, but subtitle parser state is isolated per renderer session.
@@ -594,10 +733,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.
 - `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 +747,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
 
@@ -639,7 +782,9 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 
 #### `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.
@@ -652,7 +797,10 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 
 #### `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.
@@ -687,6 +835,8 @@ interface VideoSubtitleOptions {
     before?: number
     after?: number
   }
+  streamingLoad?: boolean // default true — progressive URL loads
+  rangeRequests?: boolean // default true — use HTTP Range when supported
   onEvent?: (event: SubtitleRendererEvent) => void
 }
 ```