akarisub 0.2.2 → 1.0.0

package/README.md

@@ -49,10 +49,10 @@ deno add jsr:@altq/akarisub
 
 ## Usage
 
-By default all you need to do is copy the files from the `dist/` folder of the repository into the same folder as where your JS runs, then do:
+In most bundler-based projects, no manual worker setup is required. AkariSub resolves the WASM glue and binary relative to the package module URL, so bundlers such as Vite, webpack, and Rollup can emit the assets automatically.
 
 ```js
-import AkariSub from './index.js'
+import AkariSub from 'akarisub'
 
 const renderer = new AkariSub({
   video: document.querySelector('video'),
@@ -60,29 +60,21 @@ const renderer = new AkariSub({
 })
 ```
 
-`Note:` while the `dist/` folder includes a UMD dist it still uses modern syntax. If you want backwards compatibility with older browsers I recommend you run it tru babel.
-
-If you use a bundler like Vite, you can instead do:
+If your app serves package files in a way that does not expose those emitted assets to the browser, you can still provide the public fallback by copying the WASM file and its JS glue to `/akarisub/`:
 
-```js
-import AkariSub from 'akarisub'
-import workerUrl from 'akarisub/worker?url'
-import wasmUrl from 'akarisub/worker.wasm?url'
-
-const renderer = new AkariSub({
-  video: document.querySelector('video'),
-  subContent: subtitleString,
-  workerUrl,
-  wasmUrl
-})
+```bash
+mkdir -p public/akarisub
+cp node_modules/akarisub/pkg/akarisub.wasm node_modules/akarisub/pkg/akarisub.js public/akarisub/
 ```
 
+The worker is created from the package module URL. `workerUrl`, `wasmUrl`, and `glueUrl` remain in the option type for overrides and do not need to be set in bundler-based apps.
+
 ## Using only with canvas
 
 You're also able to use it without any video. However, that requires you to set the time the subtitles should render at yourself. Disable `onDemandRender` (it relies on video frame callbacks) and drive the clock manually:
 
 ```js
-import AkariSub from './index.js'
+import AkariSub from 'akarisub'
 
 const renderer = new AkariSub({
   canvas: document.querySelector('canvas'),
@@ -94,6 +86,36 @@ const renderer = new AkariSub({
 renderer.setCurrentTime(true, 15)
 ```
 
+Custom canvases stay on the main thread by default. Set both `offscreenRender: true` and `rawAssImageGpu: true` to opt into worker WebGL2 raw-mask composition when dense overlays benefit from it.
+
+### Timing semantics
+
+AkariSub sends libass an integer millisecond timestamp. Fractional media times are floored to the current millisecond, matching libass's `Start <= now < Start + Duration` event boundaries. `timeOffset` and `renderAhead` are measured in seconds.
+
+By default, `adaptiveTiming` predicts the media time at which a completed canvas paint will become visible, compensating bounded rendering and delivery latency. Pause and seek frames always use the exact media timestamp. Set `adaptiveTiming: false` when deterministic frame sampling is more important than compensating live presentation latency.
+
+For frame-locked VOD playback, provide the encoded video's presentation timestamps in seconds. AkariSub prepares a small window of full subtitle bitmaps and commits the matching bitmap inside `requestVideoFrameCallback`, which keeps fast `\t` and `\move` animation sampling aligned with libass:
+
+```js
+const frameTimeline = new Float64Array([0, 0.041708, 0.083417])
+const renderer = new AkariSub({
+  video,
+  subContent,
+  frameTimeline,
+  framePrefetch: 2
+})
+
+// Timelines can also arrive after renderer construction.
+renderer.setFrameTimeline(frameTimeline)
+renderer.setFrameTimeline(null) // return to adaptive continuous-time rendering
+```
+
+Use timestamps from the encoded rendition the browser plays, normalized to the browser media clock. Passing a timeline remains optional; cache misses and unsupported paths automatically use normal adaptive rendering.
+
+If the browser timeline is normalized from decode time rather than the first display PTS, preserve that initial B-frame reorder gap in the array and set `frameTimeline.subtitleTimeOffset` to the first frame timestamp. AkariSub uses the unmodified array to locate the visible video frame, then removes the offset only when sampling libass.
+
+`subtitleTimeOffset` is signed. When the source video starts after the container subtitle clock, subtract that source lead from the reorder offset. For example, an encoded reorder gap of `0.083422` seconds and a source video start of `0.007` seconds use `subtitleTimeOffset = 0.076422`, so the first displayed frame is sampled by libass at `0.007` just like mpv.
+
 ## Changing subtitles
 
 You're not limited to only display the subtitle file you referenced in your options. You're able to dynamically change subtitles on the fly. There's four methods that you can use for this specifically:
@@ -133,6 +155,7 @@ console.log(stats)
 //   maxRenderTime: 8.32,
 //   minRenderTime: 0.12,
 //   lastRenderTime: 1.23,
+//   timingCompensationMs: 4.8,
 //   renderFps: 60,
 //   usingWorker: true,
 //   offscreenRender: true,
@@ -155,22 +178,23 @@ console.log(`Events: ${eventCount}, Styles: ${styleCount}`)
 
 **Stats Reference:**
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `framesRendered` | number | Total frames rendered since reset |
-| `framesDropped` | number | Frames dropped due to slow rendering |
-| `avgRenderTime` | number | Average render time in milliseconds |
-| `maxRenderTime` | number | Maximum render time in milliseconds |
-| `minRenderTime` | number | Minimum render time in milliseconds |
-| `lastRenderTime` | number | Most recent render time in milliseconds |
-| `renderFps` | number | Estimated render FPS based on timing |
-| `usingWorker` | boolean | Whether using Web Worker |
-| `offscreenRender` | boolean | Whether offscreen rendering is enabled |
-| `onDemandRender` | boolean | Whether on-demand rendering is enabled |
-| `pendingRenders` | number | Number of pending render operations |
-| `totalEvents` | number | Total subtitle events in current track |
-| `cacheHits` | number | Number of cache hits (unchanged frames) |
-| `cacheMisses` | number | Number of cache misses (rendered frames) |
+| Property               | Type    | Description                                                             |
+| ---------------------- | ------- | ----------------------------------------------------------------------- |
+| `framesRendered`       | number  | Total frames rendered since reset                                       |
+| `framesDropped`        | number  | Frames dropped due to slow rendering                                    |
+| `avgRenderTime`        | number  | Average render time in milliseconds                                     |
+| `maxRenderTime`        | number  | Maximum render time in milliseconds                                     |
+| `minRenderTime`        | number  | Minimum render time in milliseconds                                     |
+| `lastRenderTime`       | number  | Most recent render time in milliseconds                                 |
+| `timingCompensationMs` | number  | Automatically learned presentation-latency compensation in milliseconds |
+| `renderFps`            | number  | Estimated render FPS based on timing                                    |
+| `usingWorker`          | boolean | Whether using Web Worker                                                |
+| `offscreenRender`      | boolean | Whether offscreen rendering is enabled                                  |
+| `onDemandRender`       | boolean | Whether on-demand rendering is enabled                                  |
+| `pendingRenders`       | number  | Number of pending render operations                                     |
+| `totalEvents`          | number  | Total subtitle events in current track                                  |
+| `cacheHits`            | number  | Number of cache hits (unchanged frames)                                 |
+| `cacheMisses`          | number  | Number of cache misses (rendered frames)                                |
 
 ## GPU Rendering
 
@@ -198,173 +222,180 @@ if (renderer.isUsingGPURenderer) {
 
 The default options are best, and automatically fallback to the next fastest options in line, when the API's they use are unsupported. You can however forcefully change this behavior by specifying options.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `video` | HTMLVideoElement | - | Video to use as target for rendering and event listeners |
-| `canvas` | HTMLCanvasElement | - | Canvas to use for manual handling (optional if video is provided) |
-| `blendMode` | `'js'` \| `'wasm'` | `'wasm'` | Image blending mode. WASM is better for low-end devices, JS for hardware acceleration |
-| `asyncRender` | boolean | auto | Render via ImageBitmap. Defaults to `true` on Canvas2D paths and `false` when a GPU renderer is active (raw buffers upload with fewer copies) or on WebKit |
-| `offscreenRender` | boolean | `true` | Render fully on the worker, greatly reduces CPU usage |
-| `onDemandRender` | boolean | `true` | Render subtitles as the video player renders frames |
-| `targetFps` | number | `24` | Target FPS when not using onDemandRender |
-| `timeOffset` | number | `0` | Subtitle time offset in seconds |
-| `debug` | boolean | `false` | Enable debug logging |
-| `prescaleFactor` | number | `1.0` | Scale factor for subtitles canvas |
-| `prescaleHeightLimit` | number | `1080` | Height limit for prescaling in pixels |
-| `maxRenderHeight` | number | `0` | Maximum render height (0 = no limit) |
-| `dropAllAnimations` | boolean | `false` | Discard all animated tags for performance |
-| `dropAllBlur` | boolean | `false` | Drop all blur effects (~10x performance gain) |
-| `clampPos` | boolean | `false` | Clamp `\pos` values to script resolution |
-| `renderAhead` | number | `0.008` | Extra seconds to render ahead, compensates pipeline latency |
-| `workerUrl` | string | `'akarisub-worker.js'` | URL to the worker script |
-| `wasmUrl` | string | `'akarisub-worker.wasm'` | URL to the WASM binary |
-| `subUrl` | string | - | URL of the subtitle file to play |
-| `subContent` | string \| Uint8Array \| ArrayBuffer | - | Content of the subtitle file to play |
-| `encryptedSubContent` | EncryptedSubtitleContent | - | AES-GCM encrypted subtitle payload, decrypted inside the worker |
-| `fonts` | (string \| Uint8Array)[] | - | Array of font URLs or Uint8Arrays to force load |
-| `availableFonts` | Record<string, string \| Uint8Array> | `{'liberation sans': './default.woff2'}` | Available fonts map (lowercase name → URL/data) |
-| `fallbackFonts` | string[] | `['liberation sans']` | Fallback font families in order, used for the fontconfig cascade |
-| `useLocalFonts` | boolean | `true` | Use Local Font Access API if available |
-| `libassMemoryLimit` | number | `128` | libass bitmap cache memory limit in MiB |
-| `libassGlyphLimit` | number | `2048` | libass glyph cache limit |
-| `fullTrackWarmup` | boolean | `false` | Pre-render early track windows after load to warm libass caches |
-| `onCanvasFallback` | function | - | Callback when no GPU renderer is available (Canvas2D fallback) |
+| Option                | Type                                 | Default                                  | Description                                                                                                                                                |
+| --------------------- | ------------------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `video`               | HTMLVideoElement                     | -                                        | Video to use as target for rendering and event listeners                                                                                                   |
+| `canvas`              | HTMLCanvasElement                    | -                                        | Canvas to use for manual handling (optional if video is provided)                                                                                          |
+| `blendMode`           | `'js'` \| `'wasm'`                   | `'wasm'`                                 | Image blending mode. WASM is better for low-end devices, JS for hardware acceleration                                                                      |
+| `asyncRender`         | boolean                              | auto                                     | Render via ImageBitmap. Defaults to `true` on Canvas2D paths and `false` when a GPU renderer is active (raw buffers upload with fewer copies) or on WebKit |
+| `offscreenRender`     | boolean                              | automatic                                | Render fully on the worker; enabled for video-managed canvases and disabled for custom canvases                                                            |
+| `rawAssImageGpu`      | boolean                              | `false`                                  | Compose raw libass masks with worker WebGL2 when offscreen rendering is active                                                                              |
+| `onDemandRender`      | boolean                              | `true`                                   | Render subtitles as the video player renders frames                                                                                                        |
+| `adaptiveTiming`      | boolean                              | `true`                                   | Compensate measured queue, worker, bitmap, IPC, and paint latency while video is playing; pause and seek renders remain frame-exact                        |
+| `frameTimeline`       | FrameTimeline                        | -                                        | Encoded browser-frame timestamps plus optional media/subtitle clock offsets; enables frame-locked libass sampling                                          |
+| `framePrefetch`       | number                               | `2`                                      | Number of exact subtitle-frame bitmaps to prepare ahead (`0` disables preparation, maximum `24`)                                                           |
+| `targetFps`           | number                               | `24`                                     | Target FPS when not using onDemandRender                                                                                                                   |
+| `timeOffset`          | number                               | `0`                                      | Subtitle time offset in seconds                                                                                                                            |
+| `debug`               | boolean                              | `false`                                  | Enable debug logging                                                                                                                                       |
+| `prescaleFactor`      | number                               | `1.0`                                    | Scale factor for subtitles canvas                                                                                                                          |
+| `prescaleHeightLimit` | number                               | `1080`                                   | Height limit for prescaling in pixels                                                                                                                      |
+| `maxRenderHeight`     | number                               | `0`                                      | Maximum render height (0 = no limit)                                                                                                                       |
+| `dropAllAnimations`   | boolean                              | `false`                                  | Discard all animated tags for performance                                                                                                                  |
+| `dropAllBlur`         | boolean                              | `false`                                  | Drop all blur effects (~10x performance gain)                                                                                                              |
+| `clampPos`            | boolean                              | `false`                                  | Clamp `\pos` values to script resolution                                                                                                                   |
+| `renderAhead`         | number                               | `0`                                      | Optional extra seconds to render ahead, in addition to adaptive timing; also applies when `onDemandRender` is disabled                                     |
+| `workerUrl`           | string                               | package worker URL                       | Optional worker script URL. Defaults to the package worker module URL                                                                                      |
+| `wasmUrl`             | string                               | package WASM URL                         | Optional WASM binary URL. Defaults to the URL resolved from `import.meta.url`                                                                              |
+| `glueUrl`             | string                               | package glue URL                         | Optional WASM glue script URL. Defaults to the URL resolved from `import.meta.url`                                                                         |
+| `subUrl`              | string                               | -                                        | URL of the subtitle file to play                                                                                                                           |
+| `subContent`          | string \| Uint8Array \| ArrayBuffer  | -                                        | Content of the subtitle file to play                                                                                                                       |
+| `encryptedSubContent` | EncryptedSubtitleContent             | -                                        | AES-GCM encrypted subtitle payload, decrypted inside the worker                                                                                            |
+| `fonts`               | (string \| Uint8Array)[]             | -                                        | Array of font URLs or Uint8Arrays to force load                                                                                                            |
+| `availableFonts`      | Record<string, string \| Uint8Array> | liberation sans from package assets      | Available fonts map (lowercase name → URL/data)                                                                                                            |
+| `fallbackFonts`       | string[]                             | `['liberation sans']`                    | Fallback font families in order, used for the fontconfig cascade                                                                                           |
+| `useLocalFonts`       | boolean                              | `true`                                   | Use Local Font Access API if available                                                                                                                     |
+| `libassMemoryLimit`   | number                               | `128`                                    | libass bitmap cache memory limit in MiB                                                                                                                    |
+| `libassGlyphLimit`    | number                               | `2048`                                   | libass glyph cache limit                                                                                                                                   |
+| `fullTrackWarmup`     | boolean                              | `false`                                  | Pre-render early track windows after load to warm libass caches                                                                                            |
+| `onCanvasFallback`    | function                             | -                                        | Callback when no GPU renderer is available (Canvas2D fallback)                                                                                             |
 
 ## Methods
 
 ### Track Management
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `setTrackByUrl(url)` | `url: string` | Load subtitle from URL |
-| `setTrack(content)` | `content: string \| Uint8Array \| ArrayBuffer` | Set subtitle from content |
-| `setEncryptedTrack(content)` | `content: EncryptedSubtitleContent` | Set subtitle from an encrypted payload (decrypted in the worker) |
-| `freeTrack()` | - | Remove current subtitles |
+| Method                       | Parameters                                     | Description                                                      |
+| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| `setTrackByUrl(url)`         | `url: string`                                  | Load subtitle from URL                                           |
+| `setTrack(content)`          | `content: string \| Uint8Array \| ArrayBuffer` | Set subtitle from content                                        |
+| `setEncryptedTrack(content)` | `content: EncryptedSubtitleContent`            | Set subtitle from an encrypted payload (decrypted in the worker) |
+| `freeTrack()`                | -                                              | Remove current subtitles                                         |
 
 ### Playback Control
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `setIsPaused(isPaused)` | `isPaused: boolean` | Set playback pause state |
-| `setRate(rate)` | `rate: number` | Set playback rate (speed multiplier) |
-| `setCurrentTime(isPaused?, currentTime?, rate?)` | `isPaused?: boolean, currentTime?: number, rate?: number` | Set current time, playback state and rate |
+| Method                                           | Parameters                                                | Description                                   |
+| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- |
+| `setIsPaused(isPaused)`                          | `isPaused: boolean`                                       | Set playback pause state                      |
+| `setRate(rate)`                                  | `rate: number`                                            | Set playback rate (speed multiplier)          |
+| `setCurrentTime(isPaused?, currentTime?, rate?)` | `isPaused?: boolean, currentTime?: number, rate?: number` | Set current time, playback state and rate     |
+| `setFrameTimeline(frameTimes)`                   | `ArrayLike<number> \| null`                               | Replace or disable the encoded-frame timeline |
 
 ### Video & Canvas
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `setVideo(video)` | `video: HTMLVideoElement` | Change target video element |
-| `resize(width?, height?, top?, left?, force?)` | `width?: number, height?: number, top?: number, left?: number, force?: boolean` | Resize the canvas |
+| Method                                         | Parameters                                                                      | Description                 |
+| ---------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------- |
+| `setVideo(video)`                              | `video: HTMLVideoElement`                                                       | Change target video element |
+| `resize(width?, height?, top?, left?, force?)` | `width?: number, height?: number, top?: number, left?: number, force?: boolean` | Resize the canvas           |
 
 ### Event Management
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `createEvent(event)` | `event: Partial<ASSEvent>` | `void` | Create a new ASS event |
-| `setEvent(event, index)` | `event: Partial<ASSEvent>, index: number` | `void` | Overwrite event at index |
-| `removeEvent(index)` | `index: number` | `void` | Remove event at index |
-| `getEvents()` | - | `Promise<ASSEvent[]>` | Get all ASS events |
-| `getEventCount()` | - | `Promise<number>` | Get event count (lightweight) |
+| Method                   | Parameters                                | Returns               | Description                   |
+| ------------------------ | ----------------------------------------- | --------------------- | ----------------------------- |
+| `createEvent(event)`     | `event: Partial<ASSEvent>`                | `void`                | Create a new ASS event        |
+| `setEvent(event, index)` | `event: Partial<ASSEvent>, index: number` | `void`                | Overwrite event at index      |
+| `removeEvent(index)`     | `index: number`                           | `void`                | Remove event at index         |
+| `getEvents()`            | -                                         | `Promise<ASSEvent[]>` | Get all ASS events            |
+| `getEventCount()`        | -                                         | `Promise<number>`     | Get event count (lightweight) |
 
 ### Style Management
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `createStyle(style)` | `style: Partial<ASSStyle>` | `void` | Create a new ASS style |
-| `setStyle(style, index)` | `style: Partial<ASSStyle>, index: number` | `void` | Overwrite style at index |
-| `removeStyle(index)` | `index: number` | `void` | Remove style at index |
-| `getStyles()` | - | `Promise<ASSStyle[]>` | Get all ASS styles |
-| `getStyleCount()` | - | `Promise<number>` | Get style count (lightweight) |
-| `styleOverride(style)` | `style: Partial<ASSStyle>` | `void` | Set a style override |
-| `disableStyleOverride()` | - | `void` | Disable style override |
+| Method                   | Parameters                                | Returns               | Description                   |
+| ------------------------ | ----------------------------------------- | --------------------- | ----------------------------- |
+| `createStyle(style)`     | `style: Partial<ASSStyle>`                | `void`                | Create a new ASS style        |
+| `setStyle(style, index)` | `style: Partial<ASSStyle>, index: number` | `void`                | Overwrite style at index      |
+| `removeStyle(index)`     | `index: number`                           | `void`                | Remove style at index         |
+| `getStyles()`            | -                                         | `Promise<ASSStyle[]>` | Get all ASS styles            |
+| `getStyleCount()`        | -                                         | `Promise<number>`     | Get style count (lightweight) |
+| `styleOverride(style)`   | `style: Partial<ASSStyle>`                | `void`                | Set a style override          |
+| `disableStyleOverride()` | -                                         | `void`                | Disable style override        |
 
 ### Font Management
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `addFont(font)` | `font: string \| Uint8Array` | Add a font to the renderer |
-| `setDefaultFont(font)` | `font: string` | Change the default font family |
+| Method                 | Parameters                   | Description                    |
+| ---------------------- | ---------------------------- | ------------------------------ |
+| `addFont(font)`        | `font: string \| Uint8Array` | Add a font to the renderer     |
+| `setDefaultFont(font)` | `font: string`               | Change the default font family |
 
 ### Statistics & Debugging
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `getStats()` | - | `Promise<PerformanceStats>` | Get performance statistics |
-| `resetStats()` | - | `Promise<void>` | Reset statistics counters |
-| `getEventCount()` | - | `Promise<number>` | Get event count (lightweight) |
-| `getStyleCount()` | - | `Promise<number>` | Get style count (lightweight) |
+| Method            | Parameters | Returns                     | Description                   |
+| ----------------- | ---------- | --------------------------- | ----------------------------- |
+| `getStats()`      | -          | `Promise<PerformanceStats>` | Get performance statistics    |
+| `resetStats()`    | -          | `Promise<void>`             | Reset statistics counters     |
+| `getEventCount()` | -          | `Promise<number>`           | Get event count (lightweight) |
+| `getStyleCount()` | -          | `Promise<number>`           | Get style count (lightweight) |
 
 ### Lifecycle
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `destroy(err?)` | `err?: Error \| string` | Destroy the renderer and cleanup |
-| `sendMessage(target, data?, transferable?)` | `target: string, data?: Record<string, any>, transferable?: Transferable[]` | Send data to worker |
+| Method                                      | Parameters                                                                  | Description                      |
+| ------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- |
+| `destroy(err?)`                             | `err?: Error \| string`                                                     | Destroy the renderer and cleanup |
+| `sendMessage(target, data?, transferable?)` | `target: string, data?: Record<string, any>, transferable?: Transferable[]` | Send data to worker              |
 
 ## Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `debug` | boolean | Enable/disable debug logging |
-| `prescaleFactor` | number | Scale factor for subtitles |
-| `prescaleHeightLimit` | number | Height limit for prescaling |
-| `maxRenderHeight` | number | Maximum render height |
-| `timeOffset` | number | Subtitle time offset in seconds |
-| `renderAhead` | number | Extra seconds to render ahead of the video clock |
-| `busy` | boolean | Whether the renderer is currently busy |
-| `rendererType` | `'webgpu'` \| `'webgl2'` \| `'canvas2d'` | Active renderer backend (read-only) |
-| `isUsingGPURenderer` | boolean | Whether a hardware-accelerated renderer is active (read-only) |
-| `isUsingWebGPU` | boolean | *Deprecated* - use `rendererType === 'webgpu'` |
+| Property              | Type                                     | Description                                                   |
+| --------------------- | ---------------------------------------- | ------------------------------------------------------------- |
+| `debug`               | boolean                                  | Enable/disable debug logging                                  |
+| `prescaleFactor`      | number                                   | Scale factor for subtitles                                    |
+| `prescaleHeightLimit` | number                                   | Height limit for prescaling                                   |
+| `maxRenderHeight`     | number                                   | Maximum render height                                         |
+| `timeOffset`          | number                                   | Subtitle time offset in seconds                               |
+| `renderAhead`         | number                                   | Optional extra seconds to render ahead of the video clock     |
+| `framePrefetch`       | number                                   | Number of exact subtitle frames prepared ahead                |
+| `busy`                | boolean                                  | Whether the renderer is currently busy                        |
+| `rendererType`        | `'webgpu'` \| `'webgl2'` \| `'canvas2d'` | Active renderer backend (read-only)                           |
+| `isUsingGPURenderer`  | boolean                                  | Whether a hardware-accelerated renderer is active (read-only) |
+| `isUsingWebGPU`       | boolean                                  | _Deprecated_ - use `rendererType === 'webgpu'`                |
 
 ## Type Definitions
 
 ### ASSEvent
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `Start` | number | Start time in milliseconds |
-| `Duration` | number | Duration in milliseconds |
-| `Style` | string | Style name |
-| `Name` | string | Character name (informational) |
-| `MarginL` | number | Left margin override in pixels |
-| `MarginR` | number | Right margin override in pixels |
-| `MarginV` | number | Bottom margin override in pixels |
-| `Effect` | string | Transition effect |
-| `Text` | string | Subtitle text content |
-| `ReadOrder` | number | Read order number |
-| `Layer` | number | Z-index layer |
-| `_index` | number | Internal index (optional) |
+| Property    | Type   | Description                      |
+| ----------- | ------ | -------------------------------- |
+| `Start`     | number | Start time in milliseconds       |
+| `Duration`  | number | Duration in milliseconds         |
+| `Style`     | string | Style name                       |
+| `Name`      | string | Character name (informational)   |
+| `MarginL`   | number | Left margin override in pixels   |
+| `MarginR`   | number | Right margin override in pixels  |
+| `MarginV`   | number | Bottom margin override in pixels |
+| `Effect`    | string | Transition effect                |
+| `Text`      | string | Subtitle text content            |
+| `ReadOrder` | number | Read order number                |
+| `Layer`     | number | Z-index layer                    |
+| `_index`    | number | Internal index (optional)        |
 
 ### ASSStyle
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `Name` | string | Style name (case sensitive) |
-| `FontName` | string | Font family name |
-| `FontSize` | number | Font size |
-| `PrimaryColour` | number | Primary color (RGBA as uint32) |
-| `SecondaryColour` | number | Secondary color (RGBA as uint32) |
-| `OutlineColour` | number | Outline color (RGBA as uint32) |
-| `BackColour` | number | Background/shadow color (RGBA as uint32) |
-| `Bold` | number | Bold (-1 = true, 0 = false) |
-| `Italic` | number | Italic (-1 = true, 0 = false) |
-| `Underline` | number | Underline (-1 = true, 0 = false) |
-| `StrikeOut` | number | StrikeOut (-1 = true, 0 = false) |
-| `ScaleX` | number | Width scale (percent) |
-| `ScaleY` | number | Height scale (percent) |
-| `Spacing` | number | Extra spacing between characters (pixels) |
-| `Angle` | number | Rotation angle (degrees) |
-| `BorderStyle` | number | Border style (1 = outline + shadow, 3 = opaque box) |
-| `Outline` | number | Outline width (0-4 pixels) |
-| `Shadow` | number | Shadow depth (0-4 pixels) |
-| `Alignment` | number | Alignment (1-9, numpad style) |
-| `MarginL` | number | Left margin (pixels) |
-| `MarginR` | number | Right margin (pixels) |
-| `MarginV` | number | Vertical margin (pixels) |
-| `Encoding` | number | Font encoding |
-| `treat_fontname_as_pattern` | number | Treat font name as pattern |
-| `Blur` | number | Blur amount |
-| `Justify` | number | Text justification |
+| Property                    | Type   | Description                                         |
+| --------------------------- | ------ | --------------------------------------------------- |
+| `Name`                      | string | Style name (case sensitive)                         |
+| `FontName`                  | string | Font family name                                    |
+| `FontSize`                  | number | Font size                                           |
+| `PrimaryColour`             | number | Primary color (RGBA as uint32)                      |
+| `SecondaryColour`           | number | Secondary color (RGBA as uint32)                    |
+| `OutlineColour`             | number | Outline color (RGBA as uint32)                      |
+| `BackColour`                | number | Background/shadow color (RGBA as uint32)            |
+| `Bold`                      | number | Bold (-1 = true, 0 = false)                         |
+| `Italic`                    | number | Italic (-1 = true, 0 = false)                       |
+| `Underline`                 | number | Underline (-1 = true, 0 = false)                    |
+| `StrikeOut`                 | number | StrikeOut (-1 = true, 0 = false)                    |
+| `ScaleX`                    | number | Width scale (percent)                               |
+| `ScaleY`                    | number | Height scale (percent)                              |
+| `Spacing`                   | number | Extra spacing between characters (pixels)           |
+| `Angle`                     | number | Rotation angle (degrees)                            |
+| `BorderStyle`               | number | Border style (1 = outline + shadow, 3 = opaque box) |
+| `Outline`                   | number | Outline width (0-4 pixels)                          |
+| `Shadow`                    | number | Shadow depth (0-4 pixels)                           |
+| `Alignment`                 | number | Alignment (1-9, numpad style)                       |
+| `MarginL`                   | number | Left margin (pixels)                                |
+| `MarginR`                   | number | Right margin (pixels)                               |
+| `MarginV`                   | number | Vertical margin (pixels)                            |
+| `Encoding`                  | number | Font encoding                                       |
+| `treat_fontname_as_pattern` | number | Treat font name as pattern                          |
+| `Blur`                      | number | Blur amount                                         |
+| `Justify`                   | number | Text justification                                  |
 
 # How to build?
 
@@ -395,10 +426,10 @@ git clone --recursive https://github.com/altqx/akarisub.git
 ```bash
 mise install      # installs emsdk, bun, cmake
 bun install       # JS dependencies
-make              # builds the static libs (fribidi, freetype, harfbuzz, fontconfig, libass, ...) and the WASM worker
-bun run build     # builds the WASM worker, TypeScript declarations and JS bundles
+make              # builds the static libs (fribidi, freetype, harfbuzz, fontconfig, libass, ...) and the WASM glue
+bun run build     # builds the WASM glue and TypeScript
 ```
 
 - If on macOS with libtool from brew, `LIBTOOLIZE=glibtoolize make`
-- Incremental rebuilds of the worker only: `bun run build:wasm` (or `make worker`)
-- Artifacts are in `dist/`
+- Incremental rebuilds of the WASM glue only: `bun run build:wasm` (or `make worker`)
+- Artifacts are in `pkg/` (WASM glue and binary) and `dist/` (TypeScript)