libbitsub 1.8.2 → 1.10.0

package/README.md

@@ -11,10 +11,12 @@ 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
-- Rich layout controls: scale, horizontal/vertical offsets, alignment, bottom padding, safe area, opacity
+- 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
 - Frame prefetching and cache control for high-level renderers
 - 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
 
 ## Showcase
@@ -104,13 +106,18 @@ import { PgsRenderer } from 'libbitsub'
 const renderer = new PgsRenderer({
   video: videoElement,
   subUrl: '/subtitles/movie.sup',
+  debug: true,
   displaySettings: {
     scale: 1.1,
+    aspectMode: 'stretch',
     bottomPadding: 4,
     safeArea: 5
   },
   cacheLimit: 32,
   prefetchWindow: { before: 1, after: 2 },
+  onWarning: (warning) => {
+    console.warn(warning.code, warning.message, warning.details)
+  },
   onEvent: (event) => {
     if (event.type === 'worker-state') {
       console.log('worker', event.ready ? 'ready' : 'starting', event.sessionId)
@@ -163,6 +170,7 @@ Both `PgsRenderer` and `VobSubRenderer` support runtime layout changes:
 ```ts
 renderer.setDisplaySettings({
   scale: 1.2,
+  aspectMode: 'stretch',
   verticalOffset: -8,
   horizontalOffset: 2,
   horizontalAlign: 'center',
@@ -175,11 +183,18 @@ const settings = renderer.getDisplaySettings()
 renderer.resetDisplaySettings()
 ```
 
+`aspectMode` controls how the subtitle track's own presentation size is mapped into the video content box:
+
+- `stretch` default behavior, scales X/Y independently.
+- `contain` preserves subtitle bitmap shape and fits the track inside the visible video box.
+- `cover` preserves subtitle bitmap shape while filling the video box.
+
 `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 |
@@ -195,12 +210,15 @@ High-level renderers expose parser and cue metadata:
 const metadata = renderer.getMetadata()
 const currentCue = renderer.getCurrentCueMetadata()
 const cue42 = renderer.getCueMetadata(42)
+const stats = renderer.getStats()
+const cache = renderer.getCacheStats()
+const lastRender = renderer.getLastRenderInfo()
 ```
 
 Low-level parsers expose the same model:
 
 ```ts
-import { PgsParser, UnifiedSubtitleParser, VobSubParserLowLevel } from 'libbitsub'
+import { PgsParser, UnifiedSubtitleParser, VobSubParserLowLevel, openSubtitles } from 'libbitsub'
 
 const vob = new VobSubParserLowLevel()
 vob.loadFromMks(new Uint8Array(mksBuffer))
@@ -208,9 +226,13 @@ vob.loadFromMks(new Uint8Array(mksBuffer))
 const parser = new UnifiedSubtitleParser()
 const detected = parser.loadAuto({ data: subtitleBytes, fileName: 'track.mks' })
 
+const opened = await openSubtitles({ data: subtitleBytes, fileName: 'track.mks' })
+
 console.log(detected)
 console.log(parser.getMetadata())
 console.log(parser.getCueMetadata(0))
+console.log(opened.format)
+opened.dispose()
 ```
 
 Metadata includes:
@@ -221,6 +243,134 @@ Metadata includes:
 - PGS composition count, palette ID, composition state
 - VobSub language, track ID, IDX metadata presence, file position where available
 
+## One-shot auto API
+
+If you do not care whether the input is PGS or VobSub and only want one stable low-level surface, use `openSubtitles()`.
+
+```ts
+import { openSubtitles } from 'libbitsub'
+
+const subtitles = await openSubtitles({
+  data: subtitleBytes,
+  fileName: 'track.sup'
+})
+
+console.log(subtitles.format)
+console.log(subtitles.metadata)
+console.log(subtitles.timestamps)
+
+const frame = subtitles.renderAtTimestamp(120.5)
+const rendered = subtitles.renderFrameDataAtTimestamp(120.5)
+const cue = subtitles.getCueMetadata(0)
+
+subtitles.dispose()
+```
+
+`openSubtitles()` initializes WASM for you, auto-detects the format, loads the subtitle source, and returns a normalized handle with snapshot properties plus shared low-level helpers such as `renderAtIndex()`, `renderAtTimestamp()`, `renderFrameDataAtIndex()`, `renderFrameDataAtTimestamp()`, `getCueMetadata()`, `getLastRenderIssue()`, `clearCache()`, and `dispose()`.
+
+Like `UnifiedSubtitleParser.loadAuto()`, this is a low-level in-memory API: pass binary subtitle content via `data` or `subData`, and optionally include `fileName`, `idxContent`, `idxUrl`, or `subUrl` as format hints or companion metadata.
+
+## Frame export helpers
+
+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'
+
+await initWasm()
+
+const parser = new PgsParser()
+parser.load(new Uint8Array(arrayBuffer))
+
+const subtitleFrame = parser.renderAtTimestamp(120.5)
+const rendered = subtitleFrame ? renderFrameData(subtitleFrame, { crop: 'bounds' }) : null
+
+if (rendered) {
+  const canvas = toCanvas(rendered)
+  const bitmap = await toImageBitmap(rendered)
+  const pngBlob = await toBlob(rendered)
+
+  console.log({
+    width: rendered.imageData.width,
+    height: rendered.imageData.height,
+    offsetX: rendered.offsetX,
+    offsetY: rendered.offsetY,
+    bounds: rendered.bounds,
+    canvas,
+    bitmap,
+    pngBlob
+  })
+}
+```
+
+Parser convenience methods avoid the extra `renderAtTimestamp()` step:
+
+```ts
+const rendered = parser.renderFrameDataAtTimestamp(120.5)
+const fullScreenFrame = parser.renderFrameDataAtIndex(42, { crop: 'screen' })
+```
+
+Cropping modes:
+
+- `bounds` is the default. It returns a tightly cropped composed image and records where that image belongs in the original subtitle presentation area via `offsetX` and `offsetY`.
+- `screen` preserves the full subtitle presentation dimensions, which is useful when you need stable frame sizes for test fixtures or when drawing into a presentation-sized surface.
+
+Drawing behavior:
+
+- `toCanvas(frame)` creates a new canvas sized to the rendered export.
+- Passing an existing canvas target resizes it by default before drawing.
+- Passing an existing 2D context draws in place by default, which is useful when you want subtitles composited into your own pre-sized surface.
+
+## Diagnostics mode
+
+Enable `debug: true` on high-level renderers when you need richer field diagnostics for malformed subtitle files. In debug mode, libbitsub records the most recent render attempt and emits structured warnings in addition to the existing lifecycle events.
+
+```ts
+import { PgsRenderer, SubtitleDiagnosticError } from 'libbitsub'
+
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  debug: true,
+  onWarning: (warning) => {
+    console.warn('[warning]', warning.code, warning.message, warning.details)
+  },
+  onError: (error) => {
+    if (error instanceof SubtitleDiagnosticError) {
+      console.error('[error]', error.code, error.message, error.details)
+      return
+    }
+
+    console.error(error)
+  }
+})
+
+console.log(renderer.getStats())
+console.log(renderer.getCacheStats())
+console.log(renderer.getLastRenderInfo())
+```
+
+Structured diagnostic error codes currently include:
+
+- `UNSUPPORTED_FORMAT`
+- `BAD_IDX`
+- `MISSING_PALETTE`
+- `TRACK_NOT_FOUND`
+- `MISSING_INPUT`
+- `FETCH_FAILED`
+- `INVALID_SUBTITLE_DATA`
+- `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.
+
 ## MKS security and corruption checks
 
 The `.mks` path validates Matroska structure before handing payloads to the VobSub decoder. Embedded subtitle blocks are size-checked, compressed blocks use bounded zlib inflation, and extracted SPU packets are rejected if their declared payload lengths or control offsets are inconsistent. Malformed or oversized `.mks` payloads fail fast instead of being partially decoded.
@@ -251,6 +401,7 @@ const renderer = new PgsRenderer({
       case 'loading':
       case 'loaded':
       case 'error':
+      case 'warning':
       case 'renderer-change':
       case 'worker-state':
       case 'cache-change':
@@ -319,7 +470,8 @@ Emitted events:
 | --- | --- |
 | `loading` | subtitle format |
 | `loaded` | subtitle format and parser metadata |
-| `error` | subtitle format and `Error` |
+| `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 |
@@ -347,6 +499,8 @@ const stats = renderer.getStats()
 - `totalEntries`
 - `currentIndex`
 
+`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`.
+
 ## Low-level APIs
 
 ### PGS parser
@@ -359,7 +513,9 @@ parser.load(new Uint8Array(arrayBuffer))
 
 const timestamps = parser.getTimestamps()
 const frame = parser.renderAtIndex(0)
+const rendered = parser.renderFrameDataAtTimestamp(120.5)
 const metadata = parser.getMetadata()
+const lastIssue = parser.getLastRenderIssue()
 ```
 
 ### VobSub parser
@@ -372,7 +528,9 @@ parser.loadFromData(idxContent, new Uint8Array(subArrayBuffer))
 parser.setDebandEnabled(true)
 
 const frame = parser.renderAtTimestamp(120.5)
+const rendered = parser.renderFrameDataAtIndex(0, { crop: 'screen' })
 const cue = parser.getCueMetadata(0)
+const lastIssue = parser.getLastRenderIssue()
 ```
 
 ### Unified parser
@@ -382,7 +540,10 @@ import { UnifiedSubtitleParser, detectSubtitleFormat } from 'libbitsub'
 
 const format = detectSubtitleFormat({ data: subtitleBytes, fileName: 'track.sup' })
 
-const parser = new UnifiedSubtitleParser()
+const parser = new UnifiedSubtitleParser({
+  debug: true,
+  onWarning: (warning) => console.warn(warning.code, warning.message)
+})
 parser.loadAuto({ data: subtitleBytes, fileName: 'track.sup' })
 ```
 
@@ -395,19 +556,20 @@ libbitsub prefers:
 3. Canvas2D
 
 ```ts
-import { isWebGL2Supported, isWebGPUSupported } from 'libbitsub'
+import { isWebGPUSupported } from 'libbitsub'
 
 console.log({
-  webgpu: isWebGPUSupported(),
-  webgl2: isWebGL2Supported()
+  webgpu: isWebGPUSupported()
 })
 ```
 
+WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, or `onWarning` if you need to observe backend changes.
+
 ## Notes
 
 - Worker mode is shared, but subtitle parser state is isolated per renderer session.
 - Multiple subtitle renderers can coexist without reusing the same parser instance.
-- If worker startup fails, the high-level API falls back to main-thread parsing.
+- If worker startup fails, the high-level API falls back to main-thread parsing and emits a `WORKER_FALLBACK` warning/event when diagnostics are being observed.
 - The library only handles bitmap subtitle formats. It does not parse text subtitle formats such as SRT or ASS.
 
 ## API Reference
@@ -419,6 +581,13 @@ console.log({
 - `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.
+- `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.
+- `toBlob(frame, type?, quality?, options?): Promise<Blob>` encodes a subtitle frame export, defaulting to PNG.
+- `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`.
 
 ### High-level renderers
@@ -430,6 +599,8 @@ console.log({
 - `setDisplaySettings(settings: Partial<SubtitleDisplaySettings>): void` updates layout settings.
 - `resetDisplaySettings(): void` resets layout settings to defaults.
 - `getStats(): SubtitleRendererStats` returns render statistics.
+- `getCacheStats(): SubtitleCacheStats` returns cache occupancy, worker readiness, and session ID details.
+- `getLastRenderInfo(): SubtitleLastRenderInfo | null` returns the last render attempt recorded in debug mode.
 - `getMetadata(): SubtitleParserMetadata | null` returns track-level metadata.
 - `getCurrentCueMetadata(): SubtitleCueMetadata | null` returns the currently displayed cue metadata.
 - `getCueMetadata(index: number): SubtitleCueMetadata | null` returns metadata for a specific cue.
@@ -528,6 +699,7 @@ interface AutoVideoSubtitleOptions extends Omit<VideoVobSubOptions, 'subUrl' | '
 ```ts
 interface SubtitleDisplaySettings {
   scale: number
+  aspectMode: 'stretch' | 'contain' | 'cover'
   verticalOffset: number
   horizontalOffset: number
   horizontalAlign: 'left' | 'center' | 'right'
@@ -543,7 +715,8 @@ interface SubtitleDisplaySettings {
 type SubtitleRendererEvent =
   | { type: 'loading'; format: SubtitleFormatName }
   | { type: 'loaded'; format: SubtitleFormatName; metadata: SubtitleParserMetadata }
-  | { type: 'error'; format: SubtitleFormatName; error: Error }
+  | { type: 'error'; format: SubtitleFormatName; error: SubtitleDiagnosticErrorLike }
+  | { type: 'warning'; warning: SubtitleDiagnosticWarning }
   | { type: 'renderer-change'; renderer: 'webgpu' | 'webgl2' | 'canvas2d' }
   | { type: 'worker-state'; enabled: boolean; ready: boolean; sessionId: string | null; fallback?: boolean }
   | { type: 'cache-change'; cachedFrames: number; pendingRenders: number; cacheLimit: number }
@@ -568,6 +741,11 @@ Both shapes expose:
 - `totalEntries`
 - `currentIndex`
 
+Related diagnostics shapes:
+
+- `SubtitleCacheStats` from `getCacheStats()`.
+- `SubtitleLastRenderInfo` from `getLastRenderInfo()` when `debug` is enabled.
+
 #### `SubtitleParserMetadata`
 
 ```ts

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * @packageDocumentation
  */
 export { PgsRenderer, VobSubRenderer, createAutoSubtitleRenderer, type VideoSubtitleOptions, type VideoVobSubOptions, type SubtitleRendererStats } from './wrapper';
-export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser } from './wrapper';
-export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat, type AutoSubtitleSource, type AutoVideoSubtitleOptions, type SubtitleAspectMode, type SubtitleCueBounds, type SubtitleCueMetadata, type SubtitleData, type SubtitleCompositionData, type SubtitleDisplaySettings, type SubtitleFormatName, type SubtitleHorizontalAlign, type SubtitleParserMetadata, type SubtitleRendererBackend, type SubtitleRendererEvent, type SubtitleRendererStatsSnapshot } from './wrapper';
+export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
+export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError, type AutoSubtitleSource, type AutoVideoSubtitleOptions, type OpenedSubtitles, type SubtitleAspectMode, type SubtitleCacheStats, type SubtitleCueBounds, type SubtitleCueMetadata, type SubtitleData, type SubtitleDiagnosticDetailValue, type SubtitleDiagnosticErrorCode, type SubtitleDiagnosticErrorLike, type SubtitleDiagnosticsOptions, type SubtitleDiagnosticWarning, type SubtitleDiagnosticWarningCode, type SubtitleCompositionData, type SubtitleDisplaySettings, type SubtitleFrameCanvasOptions, type SubtitleFrameCanvasTarget, type SubtitleFrameCropMode, type SubtitleFrameRenderOptions, type SubtitleRenderedFrameData, type SubtitleFormatName, type SubtitleHorizontalAlign, type SubtitleLastRenderInfo, type SubtitleParserMetadata, type SubtitleRendererBackend, type SubtitleRendererEvent, type SubtitleRendererStatsSnapshot } from './wrapper';
 export type { RenderResult, SubtitleFrame, VobSubFrame } from './wrapper';
 export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAGlF,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EACnC,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAGjG,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EACnC,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -6,9 +6,9 @@
 // High-level video-integrated renderers (compatible with old libpgs-js API)
 export { PgsRenderer, VobSubRenderer, createAutoSubtitleRenderer } from './wrapper';
 // Low-level parsers for programmatic use
-export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser } from './wrapper';
+export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
 // Utility exports
-export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat } from './wrapper';
+export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError } from './wrapper';
 // Legacy aliases
 export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4EAA4E;AAC5E,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAI3B,MAAM,WAAW,CAAA;AAElB,yCAAyC;AACzC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAElF,kBAAkB;AAClB,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EAerB,MAAM,WAAW,CAAA;AAKlB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4EAA4E;AAC5E,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAI3B,MAAM,WAAW,CAAA;AAElB,yCAAyC;AACzC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAEjG,kBAAkB;AAClB,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EA6BxB,MAAM,WAAW,CAAA;AAKlB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/ts/diagnostics.d.ts

@@ -0,0 +1,35 @@
+import type { SubtitleDiagnosticDetailValue, SubtitleDiagnosticErrorCode, SubtitleDiagnosticErrorLike, SubtitleDiagnosticWarning, SubtitleDiagnosticWarningCode, SubtitleFormatName } from './types';
+interface SubtitleDiagnosticContext {
+    format?: SubtitleFormatName;
+    details?: Record<string, SubtitleDiagnosticDetailValue>;
+    fallbackCode?: SubtitleDiagnosticErrorCode;
+}
+export declare class SubtitleDiagnosticError extends Error implements SubtitleDiagnosticErrorLike {
+    readonly code: SubtitleDiagnosticErrorCode;
+    readonly format?: SubtitleFormatName;
+    readonly details?: Record<string, SubtitleDiagnosticDetailValue>;
+    readonly cause?: unknown;
+    constructor(code: SubtitleDiagnosticErrorCode, message: string, options?: {
+        format?: SubtitleFormatName;
+        details?: Record<string, SubtitleDiagnosticDetailValue>;
+        cause?: unknown;
+    });
+}
+export declare function createSubtitleDiagnosticError(code: SubtitleDiagnosticErrorCode, message: string, options?: {
+    format?: SubtitleFormatName;
+    details?: Record<string, SubtitleDiagnosticDetailValue>;
+    cause?: unknown;
+}): SubtitleDiagnosticError;
+export declare function normalizeSubtitleError(error: unknown, context?: SubtitleDiagnosticContext): SubtitleDiagnosticError;
+export declare function createSubtitleWarning(code: SubtitleDiagnosticWarningCode, message: string, options?: {
+    format?: SubtitleFormatName;
+    cueIndex?: number;
+    details?: Record<string, SubtitleDiagnosticDetailValue>;
+}): SubtitleDiagnosticWarning;
+export declare function warningFromRenderIssue(renderIssue: string | null | undefined, options?: {
+    format?: SubtitleFormatName;
+    cueIndex?: number;
+}): SubtitleDiagnosticWarning | null;
+export declare function formatSubtitleWarningForConsole(warning: SubtitleDiagnosticWarning): string;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/ts/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/ts/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,6BAA6B,EAC7B,kBAAkB,EACnB,MAAM,SAAS,CAAA;AAEhB,UAAU,yBAAyB;IACjC,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;IACvD,YAAY,CAAC,EAAE,2BAA2B,CAAA;CAC3C;AAED,qBAAa,uBAAwB,SAAQ,KAAM,YAAW,2BAA2B;IACvF,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAA;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;IAChE,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAA;IAEjC,YACE,IAAI,EAAE,2BAA2B,EACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,kBAAkB,CAAA;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;QACvD,KAAK,CAAC,EAAE,OAAO,CAAA;KACX,EAQP;CACF;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,2BAA2B,EACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;IACvD,KAAK,CAAC,EAAE,OAAO,CAAA;CACX,GACL,uBAAuB,CAEzB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,uBAAuB,CAazB;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,6BAA6B,EACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;CACnD,GACL,yBAAyB,CAQ3B;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;CACb,GACL,yBAAyB,GAAG,IAAI,CA4BlC;AAED,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAE1F"}

package/dist/ts/diagnostics.js

@@ -0,0 +1,102 @@
+export class SubtitleDiagnosticError extends Error {
+    code;
+    format;
+    details;
+    cause;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'SubtitleDiagnosticError';
+        this.code = code;
+        this.format = options.format;
+        this.details = options.details;
+        this.cause = options.cause;
+    }
+}
+export function createSubtitleDiagnosticError(code, message, options = {}) {
+    return new SubtitleDiagnosticError(code, message, options);
+}
+export function normalizeSubtitleError(error, context = {}) {
+    if (error instanceof SubtitleDiagnosticError) {
+        return error;
+    }
+    const resolvedError = error instanceof Error ? error : new Error(String(error));
+    const code = inferSubtitleDiagnosticErrorCode(resolvedError.message, context.fallbackCode);
+    return new SubtitleDiagnosticError(code, resolvedError.message, {
+        format: context.format,
+        details: context.details,
+        cause: error
+    });
+}
+export function createSubtitleWarning(code, message, options = {}) {
+    return {
+        code,
+        message,
+        format: options.format,
+        cueIndex: options.cueIndex,
+        details: options.details
+    };
+}
+export function warningFromRenderIssue(renderIssue, options = {}) {
+    const normalizedIssue = renderIssue?.trim().toUpperCase();
+    if (!normalizedIssue)
+        return null;
+    switch (normalizedIssue) {
+        case 'MISSING_PALETTE':
+            return createSubtitleWarning('MISSING_PALETTE', 'PGS cue references a palette that was not available at render time.', {
+                format: options.format,
+                cueIndex: options.cueIndex
+            });
+        case 'INVALID_PACKET':
+            return createSubtitleWarning('INVALID_SUBTITLE_DATA', 'Subtitle packet could not be decoded for the requested cue.', {
+                format: options.format,
+                cueIndex: options.cueIndex
+            });
+        case 'RENDER_CONTEXT_UNAVAILABLE':
+            return createSubtitleWarning('INVALID_SUBTITLE_DATA', 'Subtitle render context could not be assembled for the requested cue.', {
+                format: options.format,
+                cueIndex: options.cueIndex
+            });
+        case 'EMPTY_RENDER':
+            return createSubtitleWarning('INVALID_SUBTITLE_DATA', 'Subtitle cue rendered without any visible bitmap data.', {
+                format: options.format,
+                cueIndex: options.cueIndex
+            });
+        default:
+            return null;
+    }
+}
+export function formatSubtitleWarningForConsole(warning) {
+    return `[libbitsub:${warning.code}] ${warning.message}`;
+}
+function inferSubtitleDiagnosticErrorCode(message, fallbackCode = 'UNKNOWN') {
+    const normalizedMessage = message.toLowerCase();
+    if (normalizedMessage.includes('detect subtitle format') || normalizedMessage.includes('unsupported format')) {
+        return 'UNSUPPORTED_FORMAT';
+    }
+    if (normalizedMessage.includes('no s_vobsub track') || normalizedMessage.includes('track not found')) {
+        return 'TRACK_NOT_FOUND';
+    }
+    if (normalizedMessage.includes('idx') ||
+        normalizedMessage.includes('codecprivate') ||
+        normalizedMessage.includes('filepos')) {
+        return 'BAD_IDX';
+    }
+    if (normalizedMessage.includes('palette')) {
+        return 'MISSING_PALETTE';
+    }
+    if (normalizedMessage.includes('failed to fetch')) {
+        return 'FETCH_FAILED';
+    }
+    if (normalizedMessage.includes('no ') && normalizedMessage.includes('provided')) {
+        return 'MISSING_INPUT';
+    }
+    if (normalizedMessage.includes('invalid') ||
+        normalizedMessage.includes('truncated') ||
+        normalizedMessage.includes('malformed') ||
+        normalizedMessage.includes('subtitle block') ||
+        normalizedMessage.includes('payload')) {
+        return 'INVALID_SUBTITLE_DATA';
+    }
+    return fallbackCode;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/ts/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/ts/diagnostics.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,CAA6B;IACjC,MAAM,CAAqB;IAC3B,OAAO,CAAgD;IAC9C,KAAK,CAAU;IAEjC,YACE,IAAiC,EACjC,OAAe,EACf,OAAO,GAIH,EAAE;QAEN,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;QAC9B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;IAC5B,CAAC;CACF;AAED,MAAM,UAAU,6BAA6B,CAC3C,IAAiC,EACjC,OAAe,EACf,OAAO,GAIH,EAAE;IAEN,OAAO,IAAI,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAC5D,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAc,EACd,OAAO,GAA8B,EAAE;IAEvC,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;QAC7C,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,aAAa,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAC/E,MAAM,IAAI,GAAG,gCAAgC,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE1F,OAAO,IAAI,uBAAuB,CAAC,IAAI,EAAE,aAAa,CAAC,OAAO,EAAE;QAC9D,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,KAAK;KACb,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAmC,EACnC,OAAe,EACf,OAAO,GAIH,EAAE;IAEN,OAAO;QACL,IAAI;QACJ,OAAO;QACP,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAA;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,WAAsC,EACtC,OAAO,GAGH,EAAE;IAEN,MAAM,eAAe,GAAG,WAAW,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACzD,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAA;IAEjC,QAAQ,eAAe,EAAE,CAAC;QACxB,KAAK,iBAAiB;YACpB,OAAO,qBAAqB,CAAC,iBAAiB,EAAE,qEAAqE,EAAE;gBACrH,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAA;QACJ,KAAK,gBAAgB;YACnB,OAAO,qBAAqB,CAAC,uBAAuB,EAAE,6DAA6D,EAAE;gBACnH,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAA;QACJ,KAAK,4BAA4B;YAC/B,OAAO,qBAAqB,CAAC,uBAAuB,EAAE,uEAAuE,EAAE;gBAC7H,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAA;QACJ,KAAK,cAAc;YACjB,OAAO,qBAAqB,CAAC,uBAAuB,EAAE,wDAAwD,EAAE;gBAC9G,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAA;QACJ;YACE,OAAO,IAAI,CAAA;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,OAAkC;IAChF,OAAO,cAAc,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAA;AACzD,CAAC;AAED,SAAS,gCAAgC,CACvC,OAAe,EACf,YAAY,GAAgC,SAAS;IAErD,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;IAE/C,IAAI,iBAAiB,CAAC,QAAQ,CAAC,wBAAwB,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC7G,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IAED,IAAI,iBAAiB,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACrG,OAAO,iBAAiB,CAAA;IAC1B,CAAC;IAED,IACE,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC;QACjC,iBAAiB,CAAC,QAAQ,CAAC,cAAc,CAAC;QAC1C,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,EACrC,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1C,OAAO,iBAAiB,CAAA;IAC1B,CAAC;IAED,IAAI,iBAAiB,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAClD,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAChF,OAAO,eAAe,CAAA;IACxB,CAAC;IAED,IACE,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC;QACrC,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC;QACvC,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC;QACvC,iBAAiB,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAC5C,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,EACrC,CAAC;QACD,OAAO,uBAAuB,CAAA;IAChC,CAAC;IAED,OAAO,YAAY,CAAA;AACrB,CAAC"}

package/dist/ts/frame-export.d.ts

@@ -0,0 +1,6 @@
+import type { SubtitleData, SubtitleFrameCanvasOptions, SubtitleFrameCanvasTarget, SubtitleFrameRenderOptions, SubtitleRenderedFrameData } from './types';
+export declare function renderFrameData(frame: SubtitleData, options?: SubtitleFrameRenderOptions): SubtitleRenderedFrameData | null;
+export declare function toCanvas(frame: SubtitleData | SubtitleRenderedFrameData, target?: SubtitleFrameCanvasTarget, options?: SubtitleFrameCanvasOptions): HTMLCanvasElement | OffscreenCanvas;
+export declare function toImageBitmap(frame: SubtitleData | SubtitleRenderedFrameData, options?: SubtitleFrameRenderOptions): Promise<ImageBitmap>;
+export declare function toBlob(frame: SubtitleData | SubtitleRenderedFrameData, type?: string, quality?: number, options?: SubtitleFrameRenderOptions): Promise<Blob>;
+//# sourceMappingURL=frame-export.d.ts.map

package/dist/ts/frame-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-export.d.ts","sourceRoot":"","sources":["../../src/ts/frame-export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,0BAA0B,EAC1B,yBAAyB,EAEzB,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAA;AA4IhB,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,0BAA+B,GAAG,yBAAyB,GAAG,IAAI,CAoD/H;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,YAAY,GAAG,yBAAyB,EAC/C,MAAM,CAAC,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,iBAAiB,GAAG,eAAe,CAyCrC;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,GAAG,yBAAyB,EAC/C,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,WAAW,CAAC,CAqBtB;AAED,wBAAsB,MAAM,CAC1B,KAAK,EAAE,YAAY,GAAG,yBAAyB,EAC/C,IAAI,GAAE,MAAoB,EAC1B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAyBf"}