refactor(jassub): [PKG-JASSUB-04] migrate owned TypeScript and preserve public types

packages/artplayer-plugin-jassub/types/README.md

@@ -0,0 +1,67 @@
+# JASSUB type compatibility
+
+The root and `/legacy` declarations retain the complete npm 1.0.0 and 1.1.0 type
+shape, including known mistakes. Existing TypeScript consumers do not need to
+change imports as part of this migration. Both releases used the same declarations.
+The generated online-editor global also preserves this historical surface.
+
+For accurate types, explicitly opt into the additive entry:
+
+```ts
+import jassub from 'artplayer-plugin-jassub/runtime'
+
+const register = jassub({
+  workerUrl: '/assets/jassub-worker.js',
+  wasmUrl: '/assets/jassub-worker.wasm',
+  modernWasmUrl: '/assets/jassub-worker-modern.wasm',
+  subUrl: '/subtitles.ass',
+})
+// Add register to the existing Artplayer plugins option.
+// When called with an Artplayer, it synchronously returns { name, instance }.
+```
+
+`/runtime` uses the same JavaScript file as the root entry. It does not change
+defaults, wrap instances, download resources differently or introduce a second
+implementation. URLs are optional because the vendor has defaults; this does not
+mean its default relative URLs will exist on your site. Continue hosting compatible
+worker, WASM and font files and supplying the paths your deployment needs.
+
+| Area | Historical root types | Accurate `/runtime` types and existing JavaScript |
+| --- | --- | --- |
+| Factory options | Required, with three required URLs | Optional options; optional resource URLs |
+| Instance resize | force, width, height, top, left | width, height, top, left, force |
+| resize/setVideo/destroy | Promise<void> | Synchronous; no-argument calls return void |
+| sendMessage | Unchecked extension | Promise<void>, resolves after posting, not after Worker completion |
+| Events/styles | Unchecked extension | Typed callbacks and partial mutation objects |
+| ASS event Style | Unchecked extension | Numeric libass style index |
+| ASS Start/Duration | Unchecked extension | Milliseconds; setCurrentTime uses seconds |
+| Unknown fields/methods | Existing any indexes | Named supported fields; unknown members rejected |
+
+Switching to `/runtime` intentionally changes type inference. For example,
+`instance.resize(640, 360, 0, 0, true)` describes the actual call order.
+`await instance.destroy()` remains legal JavaScript, but `.then()` on that result
+never worked at runtime. Resource teardown completion is not represented by a Promise.
+The callback error channel is `Error | ErrorEvent | null`; an error may omit the data.
+The currently frozen vendor has a request timeout/error bug that throws before user
+callbacks run. PKG-JASSUB-07 tracks the fix; typing that channel does not fix or guarantee
+callback delivery. Query outputs do not contain the upstream npm declaration's `_index`.
+
+The accurate instance extends EventTarget and preserves its normal listener APIs.
+`destroy(error)` returns the original Error, or converts a nonempty string to Error;
+an empty string is returned unchanged. Repeated direct destruction and construction/
+video clock failures remain separate vendor lifecycle work, documented in ARCHITECTURE.md.
+
+NodeNext ESM retains the root declaration's historical CommonJS namespace behavior.
+If existing code uses the root namespace's `.default` to satisfy that declaration,
+keep that form or opt into `/runtime`, whose conditional `.d.mts` is directly callable.
+CommonJS accurate types use `import jassub = require('artplayer-plugin-jassub/runtime')`.
+Do not invent `jassub.default`: the current JavaScript factory has no self alias.
+Older TypeScript resolves `/legacy` and `/runtime` through exact typesVersions mappings.
+Existing direct declaration paths are retained; no wildcard remaps unrelated paths.
+
+Maintain `runtime-api.d.ts` against the frozen wrapper and worker behavior, not a new
+upstream version. Keep CJS/ESM entry aliases synchronized. Run `yarn test:jassub-types`,
+`yarn test:jassub-types-package`, `yarn test:jassub`, and `yarn typecheck` after changes.
+The package runner installs actual historical archives and the candidate outside the
+workspace, checks strict positive/negative consumers, and verifies artifact identity.
+This is type/distribution evidence, not browser playback or final release acceptance.

packages/artplayer-plugin-jassub/types/runtime-api.d.ts

@@ -0,0 +1,155 @@
+// Core exposes a default constructor in Node10/ESM and export= in NodeNext CJS.
+// Extract the same instance without requiring esModuleInterop in consumers.
+type CoreModule = typeof import('artplayer')
+type Artplayer = CoreModule extends { default: { prototype: infer Instance } }
+  ? Instance
+  : CoreModule extends { prototype: infer Instance } ? Instance : never
+
+export type FontSource = string | Uint8Array
+
+/** Options are read when the registrar runs; the host supplies video by default. */
+export interface RuntimeOption {
+  video?: HTMLVideoElement | null
+  canvas?: HTMLCanvasElement
+  blendMode?: 'js' | 'wasm'
+  asyncRender?: boolean
+  offscreenRender?: boolean
+  onDemandRender?: boolean
+  targetFps?: number
+  timeOffset?: number
+  debug?: boolean
+  prescaleFactor?: number
+  prescaleHeightLimit?: number
+  maxRenderHeight?: number
+  dropAllAnimations?: boolean
+  dropAllBlur?: boolean
+  workerUrl?: string
+  wasmUrl?: string
+  legacyWasmUrl?: string
+  modernWasmUrl?: string
+  subUrl?: string
+  subContent?: string
+  fonts?: FontSource[]
+  availableFonts?: Record<string, FontSource>
+  fallbackFont?: string
+  useLocalFonts?: boolean
+  libassMemoryLimit?: number
+  libassGlyphLimit?: number
+}
+
+/** Fields actually serialized by the frozen worker's getEvents response. */
+export interface AssEvent {
+  /** Milliseconds; distinct from setCurrentTime's seconds. */
+  Start: number
+  Duration: number
+  /** Numeric libass style index, not the ASS text format's style name. */
+  Style: number
+  Name: string
+  MarginL: number
+  MarginR: number
+  MarginV: number
+  Effect: string
+  Text: string
+  ReadOrder: number
+  Layer: number
+}
+
+/** Fields actually serialized by the frozen worker's getStyles response. */
+export interface AssStyle {
+  Name: string
+  FontName: string
+  FontSize: number
+  PrimaryColour: number
+  SecondaryColour: number
+  OutlineColour: number
+  BackColour: number
+  Bold: number
+  Italic: number
+  Underline: number
+  StrikeOut: number
+  ScaleX: number
+  ScaleY: number
+  Spacing: number
+  Angle: number
+  BorderStyle: number
+  Outline: number
+  Shadow: number
+  Alignment: number
+  MarginL: number
+  MarginR: number
+  MarginV: number
+  Encoding: number
+  treat_fontname_as_pattern: number
+  Blur: number
+  Justify: number
+}
+
+/** Worker mutation handlers assign supplied keys; unspecified fields are not sent. */
+export type AssEventInput = Partial<AssEvent>
+export type AssStyleInput = Partial<AssStyle>
+
+/** Timeout errors and native Worker error events are separate channels. */
+export type WorkerRequestError = Error | ErrorEvent
+/**
+ * Success supplies null plus an array. Error payloads are absent.
+ * The frozen vendor currently throws before notifying this callback on request
+ * errors/timeouts; PKG-JASSUB-07 owns that defect. These types do not guarantee
+ * callback delivery or claim that the error path has been repaired.
+ */
+export type EventsCallback = (error: WorkerRequestError | null, events?: AssEvent[]) => void
+export type StylesCallback = (error: WorkerRequestError | null, styles?: AssStyle[]) => void
+
+export interface RuntimeEventMap {
+  ready: CustomEvent<null>
+  error: ErrorEvent
+}
+
+/** The actual vendor EventTarget instance, rather than an adapter copy. */
+export interface RuntimeInstance extends EventTarget {
+  timeOffset: number
+  debug: boolean
+  prescaleFactor: number
+  prescaleHeightLimit: number
+  maxRenderHeight: number
+  /** Present when the selected rendering path uses demand/busy state. */
+  busy?: boolean
+  /** These two fields were explicitly exposed by npm jassub 1.8.8. */
+  _canvas: HTMLCanvasElement
+  _ctx: CanvasRenderingContext2D | false | null
+
+  resize: (width?: number, height?: number, top?: number, left?: number, force?: boolean) => void
+  setVideo: (video: HTMLVideoElement) => void
+  runBenchmark: () => void
+  setTrackByUrl: (url: string) => void
+  setTrack: (content: string) => void
+  freeTrack: () => void
+  setIsPaused: (isPaused: boolean) => void
+  setRate: (rate: number) => void
+  /** Current time is measured in seconds. */
+  setCurrentTime: (isPaused?: boolean, currentTime?: number, rate?: number) => void
+  createEvent: (event: AssEventInput) => void
+  setEvent: (event: AssEventInput, index: number) => void
+  removeEvent: (index: number) => void
+  getEvents: (callback: EventsCallback) => void
+  createStyle: (style: AssStyleInput) => void
+  setStyle: (style: AssStyleInput, index: number) => void
+  removeStyle: (index: number) => void
+  getStyles: (callback: StylesCallback) => void
+  styleOverride: (style: AssStyleInput) => void
+  disableStyleOverride: () => void
+  setDefaultFont: (font: string) => void
+  addFont: (font: FontSource) => void
+  /** Resolves after posting the message; it is not a Worker-operation acknowledgement. */
+  sendMessage: (target: string, data?: Record<string, unknown> | null, transferable?: Transferable[]) => Promise<void>
+  destroy: (() => void) & ((error: Error) => Error) & ((error: string) => Error | '') & ((error: Error | string | undefined) => Error | '' | undefined)
+
+  addEventListener: (<Name extends keyof RuntimeEventMap>(type: Name, listener: (this: RuntimeInstance, event: RuntimeEventMap[Name]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions) => void)
+  removeEventListener: (<Name extends keyof RuntimeEventMap>(type: Name, listener: (this: RuntimeInstance, event: RuntimeEventMap[Name]) => void, options?: boolean | EventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions) => void)
+}
+
+export interface RuntimeResult {
+  name: 'artplayerPluginJassub'
+  instance: RuntimeInstance
+}
+
+export type RuntimeFactory = (option?: RuntimeOption) => (art: Artplayer) => RuntimeResult

packages/artplayer-plugin-jassub/types/runtime.d.cts

@@ -0,0 +1,20 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginJassub: RuntimeFactory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginJassub {
+  type FontSource = import('./runtime-api.js').FontSource
+  type RuntimeOption = import('./runtime-api.js').RuntimeOption
+  type AssEvent = import('./runtime-api.js').AssEvent
+  type AssStyle = import('./runtime-api.js').AssStyle
+  type AssEventInput = import('./runtime-api.js').AssEventInput
+  type AssStyleInput = import('./runtime-api.js').AssStyleInput
+  type WorkerRequestError = import('./runtime-api.js').WorkerRequestError
+  type EventsCallback = import('./runtime-api.js').EventsCallback
+  type StylesCallback = import('./runtime-api.js').StylesCallback
+  type RuntimeEventMap = import('./runtime-api.js').RuntimeEventMap
+  type RuntimeInstance = import('./runtime-api.js').RuntimeInstance
+  type RuntimeResult = import('./runtime-api.js').RuntimeResult
+  type RuntimeFactory = import('./runtime-api.js').RuntimeFactory
+}
+export = artplayerPluginJassub

packages/artplayer-plugin-jassub/types/runtime.d.mts

@@ -0,0 +1,5 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginJassub: RuntimeFactory
+export default artplayerPluginJassub
+export type { AssEvent, AssEventInput, AssStyle, AssStyleInput, EventsCallback, FontSource, RuntimeEventMap, RuntimeFactory, RuntimeInstance, RuntimeOption, RuntimeResult, StylesCallback, WorkerRequestError } from './runtime-api.js'

packages/artplayer-plugin-jassub/types/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginJassub: RuntimeFactory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginJassub {
+  type FontSource = import('./runtime-api.js').FontSource
+  type RuntimeOption = import('./runtime-api.js').RuntimeOption
+  type AssEvent = import('./runtime-api.js').AssEvent
+  type AssStyle = import('./runtime-api.js').AssStyle
+  type AssEventInput = import('./runtime-api.js').AssEventInput
+  type AssStyleInput = import('./runtime-api.js').AssStyleInput
+  type WorkerRequestError = import('./runtime-api.js').WorkerRequestError
+  type EventsCallback = import('./runtime-api.js').EventsCallback
+  type StylesCallback = import('./runtime-api.js').StylesCallback
+  type RuntimeEventMap = import('./runtime-api.js').RuntimeEventMap
+  type RuntimeInstance = import('./runtime-api.js').RuntimeInstance
+  type RuntimeResult = import('./runtime-api.js').RuntimeResult
+  type RuntimeFactory = import('./runtime-api.js').RuntimeFactory
+}
+export = artplayerPluginJassub