@banou/media-player 0.8.21 → 0.10.0

package/dist/react/components/chrome.d.ts

@@ -3,12 +3,12 @@ export type ChromeProps = {
     ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void);
     /** Absent means render no video element: the media belongs to someone else and arrives as children. */
     onVideoRef?: (element: HTMLVideoElement | null) => void;
-    onCanvasRef: (element: HTMLCanvasElement | null) => void;
+    onSubtitleRef: (element: HTMLDivElement | null) => void;
     /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
     overlay?: ReactNode;
     /** False draws no control bar at all, leaving the picture, the title and the overlay. */
     controls?: boolean;
     children?: ReactNode;
 };
-export declare const Chrome: ({ ref, onVideoRef, onCanvasRef, overlay, controls, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Chrome: ({ ref, onVideoRef, onSubtitleRef, overlay, controls, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Chrome;

package/dist/react/components/overlay.d.ts

@@ -1,4 +1,4 @@
-export declare const Overlay: ({ onCanvasRef }: {
-    onCanvasRef: (element: HTMLCanvasElement | null) => void;
+export declare const Overlay: ({ onSubtitleRef }: {
+    onSubtitleRef: (element: HTMLDivElement | null) => void;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Overlay;

package/dist/react/hooks/use-picture-in-picture.d.ts

@@ -13,5 +13,10 @@ export type PictureInPicture = {
  * hidden mirror. Where it does not, and the engine is Gecko, the same composite becomes the picture
  * in the page so that the BROWSER'S own picture in picture control carries the subtitles with it,
  * which it otherwise cannot: it takes a video element, and the subtitles live on a canvas above one.
+ *
+ * The second argument is the subtitle LAYER, not that canvas. From jassub 2 the canvas belongs to the
+ * renderer and is replaced on every pipeline rebuild, so only the layer lives long enough to hold.
  */
-export declare const usePictureInPicture: (video: HTMLVideoElement | null, canvas: HTMLCanvasElement | null) => PictureInPicture;
+export declare const usePictureInPicture: (video: HTMLVideoElement | null, 
+/** The subtitle layer, not the canvas: see `PictureInPictureOptions.subtitles`. */
+subtitles: HTMLElement | null) => PictureInPicture;

package/dist/react/hooks/use-playback.d.ts

@@ -3,6 +3,6 @@ import type { MediaPlayerLocalOptions } from '../video-player';
  * Owns the engine for the life of a source: start, teardown, and every piece of state the pipeline
  * discovers. Nothing is mirrored in React state, so the store is the only place any of it lives.
  */
-export declare const usePlayback: (video: HTMLVideoElement | null, canvas: HTMLCanvasElement | null, 
+export declare const usePlayback: (video: HTMLVideoElement | null, subtitles: HTMLElement | null, 
 /** null when the media is remote: there are no bytes, so there is no pipeline to run. */
 options: MediaPlayerLocalOptions | null) => void;

package/dist/react/hooks/use-thumbnails.d.ts

@@ -9,4 +9,15 @@ export type UseSeekThumbnailsOptions = {
     /** When omitted the whole file is treated as readable, which is the case for a local file. */
     downloadedRanges?: DownloadedRange[];
 };
-export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => ThumbnailImage[];
+export type SeekThumbnails = {
+    thumbnails: ThumbnailImage[];
+    /**
+     * Where the viewer is pointing on the seekbar, so that preview is decoded next.
+     *
+     * Stable for the life of the hook, so it can be published to the store once and called from a
+     * pointermove without re-rendering anything. A no-op until the generator boots, and on a source
+     * that brings its own storyboard.
+     */
+    requestThumbnail: (time: number | undefined) => void;
+};
+export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => SeekThumbnails;

package/dist/react/player.d.ts

@@ -5,6 +5,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     indexes: import("..").MediaIndex[];
     thumbnails: import("..").ThumbnailImage[];
     thumbnailAt?: (time: number) => import("..").ThumbnailImage | undefined;
+    requestThumbnail: (time: number | undefined) => void;
     subtitleTracks: import("./source-feature").TrackChoice[];
     selectedSubtitleTrack: string | number | undefined;
     selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;

package/dist/react/source-feature.d.ts

@@ -76,6 +76,17 @@ export type SourceState = {
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *
@@ -163,6 +174,17 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.21",
+  "version": "0.10.0",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",
@@ -34,9 +34,8 @@
     "build-lib": "shx rm -rf dist/ && vp build -c vite.lib.config.ts && npm run types",
     "prepublishOnly": "npm run build-lib",
     "types": "tsc -p tsconfig.lib.json",
-    "copy-assets": "shx mkdir -p public && npm run copy-libav && npm run copy-libass",
+    "copy-assets": "shx mkdir -p public && npm run copy-libav",
     "copy-libav": "shx cp node_modules/libav-wasm/build/worker.js public/libav-worker.js && shx cp node_modules/libav-wasm/build/libav.wasm public/libav.wasm && shx cp node_modules/libav-wasm/build/libav-jspi.wasm public/libav-jspi.wasm",
-    "copy-libass": "shx cp node_modules/jassub/dist/jassub-worker.js public/jassub-worker.js && shx cp node_modules/jassub/dist/jassub-worker.wasm public/jassub-worker.wasm && shx cp node_modules/jassub/dist/jassub-worker-modern.wasm public/jassub-worker-modern.wasm && shx cp node_modules/jassub/dist/default.woff2 public/default.woff2",
     "test": "npm run fixtures && vp test run",
     "fixtures": "node scripts/fixture.mjs"
   },
@@ -45,7 +44,7 @@
     "@videojs/core": "10.0.0-beta.26",
     "@videojs/react": "10.0.0-beta.26",
     "ass-compiler": "^0.1.16",
-    "jassub": "^1.8.6",
+    "jassub": "^2.5.16",
     "libav-wasm": "^0.8.4",
     "osra": "^0.6.12",
     "react-feather": "^2.0.10",

package/src/lib/engine/picture-in-picture.ts

@@ -27,8 +27,15 @@ export type PictureInPictureMode = 'window' | 'burn-in'
 
 export type PictureInPictureOptions = {
   video: HTMLVideoElement
-  /** The subtitle canvas. jassub sizes it to the video's content rect, so it maps 1:1. */
-  canvas: HTMLCanvasElement
+  /**
+   * The subtitle LAYER, not the canvas inside it.
+   *
+   * From jassub 2 the canvas is created and removed by the subtitle renderer, one per pipeline
+   * build, so an element captured here would stop being the one being painted the moment the audio
+   * track changed. The layer is what React owns for the life of the player, so hiding and restoring
+   * it stays correct across a rebuild, and the canvas is looked up per frame.
+   */
+  subtitles: HTMLElement
   maxWidth?: number
   /** Where the mirror is mounted. It must be in the document. Defaults to the video's parent. */
   container?: HTMLElement
@@ -87,7 +94,7 @@ export const pictureInPictureMode = (): PictureInPictureMode | null => {
 
 /** Takes over the document's Media Session play/pause handlers while a session is open. */
 export const createPictureInPicture = (options: PictureInPictureOptions): PictureInPictureController => {
-  const { video, canvas } = options
+  const { video, subtitles } = options
   const mode = options.mode ?? pictureInPictureMode() ?? 'window'
   const maxWidth = options.maxWidth ?? (mode === 'burn-in' ? BURN_IN_MAX_WIDTH : DEFAULT_MAX_WIDTH)
 
@@ -112,9 +119,12 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
 
   const draw = (composite: HTMLCanvasElement, context: CanvasRenderingContext2D) => {
     context.drawImage(video, 0, 0, composite.width, composite.height)
-    // drawImage throws on a zero-sized source, which the canvas is until jassub has painted
-    if (canvas.width > 0 && canvas.height > 0) {
-      context.drawImage(canvas, 0, 0, composite.width, composite.height)
+    // Resolved per frame: the renderer replaces this element on every pipeline rebuild. A canvas
+    // jassub has transferred reports the size of the last frame its worker committed, so the zero
+    // check still keeps drawImage off a source with no dimensions to read.
+    const surface = subtitles.querySelector('canvas')
+    if (surface && surface.width > 0 && surface.height > 0) {
+      context.drawImage(surface, 0, 0, composite.width, composite.height)
     }
   }
 
@@ -254,18 +264,23 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
    * The real element is dimmed, never `display: none`: jassub sizes the subtitle canvas from its
    * `offsetWidth`/`offsetHeight`, and a collapsed box silently yields a composite with no subtitles
    * in it, which is exactly the thing being asked for.
+   *
+   * The LAYER is what gets hidden, rather than the canvas inside it. The canvas is replaced whenever
+   * the pipeline is rebuilt, so hiding that would leave the replacement visible over the composite
+   * (doubled subtitles) and would restore `display` onto an element that is no longer in the tree
+   * (subtitles gone for the rest of the session). The layer outlives both.
    */
   const present = (mirror: HTMLVideoElement) => {
     const videoOpacity = video.style.opacity
-    const canvasDisplay = canvas.style.display
+    const subtitlesDisplay = subtitles.style.display
     mirror.style.cssText =
       'position:absolute;inset:0;width:100%;height:100%;object-fit:contain;background:#000;z-index:1'
     video.style.opacity = '0'
-    canvas.style.display = 'none'
+    subtitles.style.display = 'none'
     restore = () => {
       restore = undefined
       video.style.opacity = videoOpacity
-      canvas.style.display = canvasDisplay
+      subtitles.style.display = subtitlesDisplay
     }
   }
 

package/src/lib/engine/playback.ts

@@ -13,7 +13,14 @@ export type MediaIndex = { pos: number, timestamp: number }
 
 export type PlaybackOptions = {
   videoElement: HTMLVideoElement
-  canvasElement: HTMLCanvasElement
+  /**
+   * The subtitle layer. The renderer creates its own canvas inside it, one per jassub instance.
+   *
+   * Renamed from `canvasElement` in the jassub 2 migration, deliberately: passing a canvas here now
+   * means jassub transfers it to a worker and deletes it on teardown, so a caller that kept handing
+   * over an element it owns has to see a type error rather than a runtime one.
+   */
+  subtitleContainer: HTMLElement
   read: (offset: number, size: number) => Promise<ArrayBuffer>
   length: number
   /** serves BOTH `libav.wasm` and `libav-jspi.wasm`; libav-wasm picks one on `WebAssembly.Suspending` */
@@ -114,7 +121,7 @@ export const terminateRemuxer = (remuxer: { worker: Worker, destroy: () => Promi
 
 export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackController> => {
   const {
-    videoElement, canvasElement, read, length, publicPath, libavWorkerUrl,
+    videoElement, subtitleContainer, read, length, publicPath, libavWorkerUrl,
     jassubWorkerUrl, jassubWasmUrl, jassubLegacyWasmUrl, defaultFontUrl, bufferSize = DEFAULT_BUFFER_SIZE,
     audioStreamIndex, onReady, onError, onRecovered, onSeek, onSubtitleStreams,
     onAudioStreams,
@@ -152,7 +159,7 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
 
     const subtitles = createSubtitleRenderer({
       video: videoElement,
-      canvas: canvasElement,
+      container: subtitleContainer,
       workerUrl: jassubWorkerUrl,
       wasmUrl: jassubWasmUrl,
       legacyWasmUrl: jassubLegacyWasmUrl,

package/src/lib/engine/subtitles.ts

@@ -1,4 +1,4 @@
-import type { ASS_Event } from 'jassub'
+import type { ASSEvent } from 'jassub/dist/worker/util'
 import type { Attachment, SubtitleFragment } from 'libav-wasm/build/worker'
 
 import JASSUB from 'jassub'
@@ -9,30 +9,32 @@ export type SubtitleStream = { streamIndex: number, title: string, language: str
 /** -1 turns subtitles off. It frees the track and matches no header, so nothing is set. */
 export const SUBTITLES_OFF = -1
 
-/**
- * jassub's `ASS_Event` types `Style` as a string, which the library it wraps does not agree with:
- * the field is written straight through to libass's `int Style`, an index into the track's style
- * list. Corrected once, here, so a name cannot end up in it again.
- */
-type StyledEvent = Omit<ASS_Event, 'Style'> & { Style: number }
-
-const createEvent = (jassub: JASSUB, event: StyledEvent) => jassub.createEvent(event as unknown as ASS_Event)
-
 type SubtitleHeaderPart = { type: 'header', streamIndex: number, content: string, eventsContent: string, styles: Map<string, number> }
-type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: StyledEvent }
+type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: ASSEvent }
 
 export type SubtitleRendererOptions = {
   video: HTMLVideoElement
-  canvas: HTMLCanvasElement
+  /**
+   * Where the subtitle surface is mounted.
+   *
+   * A container, not the canvas itself. From jassub 2 the canvas belongs to the renderer: the
+   * constructor transfers it to a worker, which an element accepts exactly once for its whole life,
+   * and `destroy()` removes it from the document. Neither is survivable for an element someone else
+   * owns, and this pipeline is rebuilt in place on an audio track change and on an element recovery.
+   * So one canvas is created here per jassub instance, inside this container.
+   *
+   * The live canvas is `container.querySelector('canvas')`, and it is replaced on every rebuild.
+   */
+  container: HTMLElement
   workerUrl: string
   /** The SIMD build, `jassub-worker-modern.wasm`. Used wherever WebAssembly SIMD is available. */
   wasmUrl: string
   /**
-   * The non-SIMD build, `jassub-worker.wasm`, for Safari before 16.4 and anything else without SIMD.
+   * The non-SIMD build, `jassub-worker.wasm`, for anything without WebAssembly SIMD.
    *
-   * Not optional in practice, only in the type. jassub picks `wasmUrl ?? 'jassub-worker.wasm'` when SIMD
-   * is missing, and that bare relative name resolves against the blob: url the worker is built from,
-   * which throws. So leaving this unset does not degrade to the slower build, it fails outright.
+   * Optional in practice as well as in the type, unlike under jassub 1: v2 defaults both wasm urls to
+   * its own files resolved against `import.meta.url`, so leaving this unset degrades to whatever the
+   * bundler emitted rather than failing outright.
    */
   legacyWasmUrl?: string
   /**
@@ -48,10 +50,10 @@ export type SubtitleRendererOptions = {
 /**
  * A url the WORKER will fetch, resolved against the document first.
  *
- * jassub's worker is built from a `blob:` url, so a relative url handed to it resolves against that
- * blob inside the worker and the fetch never lands. For the wasm that fails loudly. For the fallback
- * font it fails in SILENCE: libass is left with no face to draw with, so the track renders nothing at
- * all and the picture simply has no subtitles on it, with no error anywhere to say why.
+ * A relative url handed to the worker resolves against the worker's own url inside it, which is not
+ * the document's. For the wasm that fails loudly. For the fallback font it fails in SILENCE: libass
+ * is left with no face to draw with, so the track renders nothing at all and the picture simply has
+ * no subtitles on it, with no error anywhere to say why.
  *
  * `workerUrl` is deliberately not passed through here. `new Worker()` is called on the main thread,
  * where a relative url already resolves against the document.
@@ -78,9 +80,11 @@ const headerStyles = (content: string) =>
 /**
  * The index libass will resolve this event's style to.
  *
- * jassub types `ASS_Event.Style` as a string and writes it straight through to an `int`, so handing
- * it a style NAME stores 0, which is libass's own default: Arial at size 18, with margins and a drop
- * shadow of its own. Subtitles still appear, in a face and a size the file never asked for.
+ * `ASSEvent.Style` is written straight through to an `int`, so handing it a style NAME stores 0,
+ * which is libass's own default: Arial at size 18, with margins and a drop shadow of its own.
+ * Subtitles still appear, in a face and a size the file never asked for. jassub 1 typed the field as
+ * a string, which is what made that easy to do; jassub 2 types it `number` and agrees with libass,
+ * but the resolution still has to happen somewhere and this is it.
  *
  * Falling back to the header's own "Default", then to 0, is what libass does for a name it cannot
  * find. The leading-`*` strip and the case fold on "Default" are its normalisation, kept so a
@@ -123,23 +127,30 @@ const toDialoguePart = (header: SubtitleHeaderPart, fragment: SubtitleFragment &
     streamIndex: fragment.streamIndex,
     index: dialogueIndex,
     assEvent: {
-      ...event,
+      Name: event.Name ?? '',
+      // libass wants the raw effect field and ass-compiler has already destructured it into an
+      // object, so only the name survives the round trip. That is parity rather than a regression:
+      // jassub 1 was handed the object itself, which reached libass's `char*` as "[object Object]",
+      // and libass matches an effect by a "Banner;" or "Scroll up;" prefix, so neither form has ever
+      // selected one.
+      Effect: event.Effect?.name ?? '',
+      Layer: event.Layer,
+      MarginL: event.MarginL,
+      MarginR: event.MarginR,
+      MarginV: event.MarginV,
       Style: styleIndex(header, event.Style),
-      Effect: event.Effect ?? '',
       Text: event.Text.raw,
-      Duration: (event.End - event.Start) * 1000,
       Start: event.Start * 1000,
-      End: event.End * 1000,
+      Duration: (event.End - event.Start) * 1000,
       ReadOrder: dialogueIndex,
-      _index: dialogueIndex,
-    } as StyledEvent,
+    },
   }
 }
 
 export type SubtitleRenderer = ReturnType<typeof createSubtitleRenderer>
 
 export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
-  const { video, canvas, workerUrl } = options
+  const { video, container, workerUrl } = options
   const wasmUrl = workerFetched(options.wasmUrl)!
   const legacyWasmUrl = workerFetched(options.legacyWasmUrl)
   const defaultFontUrl = workerFetched(options.defaultFontUrl)
@@ -150,31 +161,157 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
   const dialogues = new Map<number, Map<number, SubtitleDialoguePart>>()
   let selected: number | undefined
   let onStreams = options.onStreams
+  /**
+   * Terminal, unlike a null `jassub`.
+   *
+   * `pushFragments` boots on the first header it sees and tests `!jassub` to decide, so a fragment
+   * that lands after teardown (a demuxer read resolving into a torn-down pipeline, which is ordinary
+   * on the `./engine` surface) would start a SECOND worker with a second canvas inside a container
+   * nobody is watching any more. The live canvas is found with `querySelector`, so the stale one
+   * would win and picture in picture would composite a surface that is never painted again.
+   */
+  let destroyed = false
+
+  const rendererFailed = (error: unknown) => {
+    console.warn('the subtitle renderer failed; the file plays without subtitles', error)
+  }
+
+  /**
+   * Run something against the worker, once there is a worker to run it against.
+   *
+   * `instance.renderer` is assigned by the promise `ready` resolves, so nothing can be called before
+   * then and a call made too early throws on `undefined`. Ordering after that is free rather than
+   * something this has to arrange: abslink posts each call synchronously from its proxy's `apply`
+   * trap, and the worker runs the method synchronously in its own message handler, so calls land in
+   * the order they were made whether or not each one is awaited. Reactions registered on one
+   * already-settled promise also run in registration order, so this preserves it too.
+   *
+   * The identity check is what stops a teardown that happened during the boot from talking to a
+   * worker that is on its way out.
+   *
+   * `run` RETURNS its calls rather than dropping them. Every proxied call is a promise that rejects
+   * when the worker throws, which libass does on a header it will not take and once it is over its
+   * glyph or memory limit, and a dropped one surfaces as a bare `unhandledrejection` in the host app
+   * with nothing naming subtitles in it.
+   */
+  const onRenderer = (run: (renderer: JASSUB['renderer']) => unknown) => {
+    const instance = jassub
+    if (!instance) return
+    void instance.ready
+      .then(() => (jassub === instance ? run(instance.renderer) : undefined))
+      .catch(rendererFailed)
+  }
 
-  const tick = setInterval(() => {
-    jassub?.setCurrentTime(video.paused, video.currentTime, video.playbackRate)
-  }, 100)
+  let repaintQueued = false
+  /**
+   * Ask for one frame.
+   *
+   * jassub 2 draws only from `requestVideoFrameCallback`, so a PAUSED video presents no frames and
+   * nothing repaints. Anything that changes what libass would draw has to ask for a frame itself, or
+   * a track switch and a seek while paused both leave the previous line on screen until playback
+   * resumes. jassub 1 needed none of this because the 100ms `setCurrentTime` tick this replaces
+   * redrew unconditionally.
+   *
+   * Coalesced through a microtask because events arrive in bursts of hundreds and one frame covers
+   * the whole burst. The burst is synchronous, so the microtask always runs after all of it, and a
+   * playing video therefore costs at most one extra draw per burst.
+   */
+  const repaint = () => {
+    if (repaintQueued) return
+    repaintQueued = true
+    queueMicrotask(() => {
+      repaintQueued = false
+      const instance = jassub
+      // `videoWidth` is 0 until metadata arrives, and asking jassub to draw then sizes its surface to
+      // nothing. Nothing else is required: this deliberately does NOT skip the draw when the element
+      // is playing. "Playing" is not "presenting frames", and the gap between them is exactly where
+      // subtitles get stuck. A torrent-backed source whose SourceBuffer runs dry keeps `paused` false
+      // while presenting nothing, so a viewer who turns subtitles off mid-stall would watch the line
+      // stay on screen until the buffer refilled. One forced draw per change is far cheaper than
+      // reasoning about which stalls count.
+      if (!instance || !video.videoWidth) return
+      void instance.ready
+        .then(() => {
+          if (jassub !== instance) return undefined
+          return instance.manualRender({
+            expectedDisplayTime: performance.now(),
+            width: video.videoWidth,
+            height: video.videoHeight,
+            mediaTime: video.currentTime,
+          }, true)
+        })
+        .catch(rendererFailed)
+    })
+  }
 
-  const onRateChange = () => jassub?.setRate(video.playbackRate)
+  /**
+   * The element events that change what should be on screen without presenting a frame.
+   *
+   * `loadedmetadata` is the one that is easy to miss and fatal to leave out: the first subtitle
+   * fragments arrive BEFORE the element has parsed metadata, so the repaint they ask for is skipped
+   * for having no `videoWidth` to size a surface from, and if nothing asks again a paused player
+   * shows no subtitles at all. `seeked` covers scrubbing while paused, and `pause` covers landing on
+   * a frame whose line arrived after it was presented.
+   *
+   * Trimming this list was tried and reverted. `['loadedmetadata']` alone fails
+   * `subtitle-paused-repaint.browser.test.tsx`'s turn-off case four runs out of four, while adding
+   * back EITHER of the other two passes. Neither of those events fires in that test, so what the
+   * extra listener buys is timing rather than a trigger, and the honest conclusion is that the clear
+   * after a `freeTrack` is more delicate than it looks. Do not shorten this list without running that
+   * case several times.
+   */
+  const REPAINT_ON = ['loadedmetadata', 'seeked', 'pause'] as const
+  const onRepaintEvent = () => repaint()
 
   const bootJassub = (header: SubtitleHeaderPart) => {
-    jassub = new JASSUB({
-      onDemandRender: false,
-      video,
-      canvas,
-      subContent: header.content,
-      workerUrl,
-      modernWasmUrl: wasmUrl,
-      ...legacyWasmUrl ? { wasmUrl: legacyWasmUrl } : {},
-      fonts: attachments.map(([, data]) => data),
-      availableFonts: {
-        ...Object.fromEntries(attachments),
-        ...(defaultFontUrl ? { 'liberation sans': defaultFontUrl } : {}),
-      },
-    })
-    // jassub 1.8.x binds setRate as the ratechange listener, so the Event becomes the rate
-    video.removeEventListener('ratechange', (jassub as unknown as { _boundSetRate: EventListener })._boundSetRate)
-    video.addEventListener('ratechange', onRateChange)
+    const canvas = document.createElement('canvas')
+    container.append(canvas)
+    try {
+      jassub = new JASSUB({
+        video,
+        canvas,
+        subContent: header.content,
+        workerUrl,
+        modernWasmUrl: wasmUrl,
+        ...legacyWasmUrl ? { wasmUrl: legacyWasmUrl } : {},
+        fonts: attachments.map(([, data]) => data),
+        availableFonts: {
+          ...Object.fromEntries(attachments),
+          ...(defaultFontUrl ? { 'liberation sans': defaultFontUrl } : {}),
+        },
+        // jassub 2 defaults this to 'local', which asks the browser for the local-fonts permission
+        // the first time libass reports a face it does not have. The container ships its own fonts
+        // and a player has no business raising that prompt.
+        queryFonts: false,
+      })
+    } catch (error) {
+      canvas.remove()
+      rendererFailed(error)
+      return
+    }
+    // A boot that fails worker-side rejects `ready`, and jassub's own ResizeObserver awaits `ready`
+    // on every layout change, so an instance left in that state throws a fresh unhandled rejection
+    // for the rest of the session.
+    void jassub.ready.catch(rendererFailed)
+    for (const type of REPAINT_ON) video.addEventListener(type, onRepaintEvent)
+    /*
+     * The default face is the one font jassub loads LAZILY. Attachments are handed to the constructor
+     * and `ready` waits for them, but `availableFonts` is consulted only when libass reports a
+     * missing face part way through a draw, and the fetch that follows lands after the frame that
+     * needed it. Driven by rVFC the next frame picks it up and the cost is one frame of unstyled
+     * text; PAUSED there is no next frame, so the first line stays unpainted until the viewer presses
+     * play. Measured as a RACE rather than a certainty: three runs of subtitle-header.browser.test.tsx
+     * against one repaint scored two blank and one painted.
+     *
+     * `addFonts` is the fix because it is a signal rather than a delay: it resolves when the face is
+     * in libass, which is the moment a repaint is worth asking for.
+     */
+    if (defaultFontUrl) {
+      onRenderer((renderer) => {
+        void Promise.resolve(renderer.addFonts([defaultFontUrl])).then(repaint, rendererFailed)
+      })
+    }
+    repaint()
   }
 
   const pushAttachments = (incoming: Attachment[]) => {
@@ -182,6 +319,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
   }
 
   const pushFragments = (fragments: SubtitleFragment[]) => {
+    const incoming: ASSEvent[] = []
     for (const fragment of fragments) {
       if (fragment.type === 'header') {
         if (headers.has(fragment.streamIndex)) continue
@@ -191,7 +329,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
         streams.push({ streamIndex: fragment.streamIndex, title: fragment.title, language: fragment.language })
         onStreams?.([...streams])
         if (selected === undefined) selected = fragment.streamIndex
-        if (!jassub) bootJassub(header)
+        if (!jassub && !destroyed) bootJassub(header)
       } else {
         const header = headers.get(fragment.streamIndex)
         if (!header) continue
@@ -200,21 +338,31 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
         const part = toDialoguePart(header, fragment)
         if (byIndex.has(part.index)) continue
         byIndex.set(part.index, part)
-        if (selected === fragment.streamIndex && jassub) createEvent(jassub, part.assEvent)
+        if (selected === fragment.streamIndex) incoming.push(part.assEvent)
       }
     }
+    if (!incoming.length) return
+    // one hop for the whole burst rather than one per event
+    onRenderer((renderer) => Promise.all(incoming.map((event) => renderer.createEvent(event))))
+    repaint()
   }
 
   const selectStream = (streamIndex: number | undefined) => {
     const next = streamIndex ?? SUBTITLES_OFF
     if (next === selected || !jassub) return
     selected = next
-    jassub.freeTrack()
     const header = headers.get(next)
-    if (!header) return
-    jassub.setTrack(header.content)
-    for (const part of dialogues.get(next)?.values() ?? []) createEvent(jassub, part.assEvent)
-    jassub.setCurrentTime(video.paused, video.currentTime, video.playbackRate)
+    const events = [...dialogues.get(next)?.values() ?? []].map((part) => part.assEvent)
+    onRenderer((renderer) => {
+      const calls: unknown[] = [renderer.freeTrack()]
+      if (header) {
+        calls.push(renderer.setTrack(header.content))
+        for (const event of events) calls.push(renderer.createEvent(event))
+      }
+      return Promise.all(calls)
+    })
+    // outside the callback so that turning subtitles OFF while paused clears the picture too
+    repaint()
   }
 
   return {
@@ -225,10 +373,14 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
     getSelectedStream: () => selected,
     setOnStreams: (cb: (streams: SubtitleStream[]) => void) => { onStreams = cb },
     destroy: () => {
-      clearInterval(tick)
-      video.removeEventListener('ratechange', onRateChange)
-      jassub?.destroy()
+      destroyed = true
+      const instance = jassub
       jassub = undefined
+      for (const type of REPAINT_ON) video.removeEventListener(type, onRepaintEvent)
+      // jassub removes its own canvas at the top of destroy(), before it awaits anything, so the
+      // element is gone synchronously. The rest is a worker round trip that a dead worker never
+      // answers, which is why nothing here waits for it.
+      void instance?.destroy().catch(() => {})
     },
   }
 }