waveform-analysis 0.1.74 → 0.1.75

package/src/animation/WaveformAnimationController.ts

@@ -0,0 +1,328 @@
+import { Animator, globalAnimator } from './core/Animator'
+import type { AnimationConfig, AnimationHandle, AnimationState } from './core/types'
+import { copyAnimationValue, validateAnimationConfig } from './core/validation'
+import { animationError, notify, reportAnimationError } from './core/errors'
+import { createAnimationOwner } from './core/owner'
+import { createAnimationHandle } from './core/handle'
+import type {
+  AnimationObjectKey,
+  WaveformAnimationControllerOptions,
+  AnimationBinding,
+  ClipAnimationState,
+  LineDrawingOptions,
+  StaggeredLineDrawingOptions,
+  GeometryTransitionInput,
+  GeometryTransitionFrame,
+  DataUpdateOptions,
+  AnnotationAnimationState,
+  AnnotationAnimationOptions,
+} from './types'
+import {
+  createLineDrawingAnimation,
+  createStaggeredLineDrawingAnimations,
+} from './presets/lineDrawing'
+import { createPathTransitionAnimation, createYAxisScaleAnimation } from './presets/transitions'
+import {
+  createAnnotationAppearAnimation,
+  createAnnotationDisappearAnimation,
+} from './presets/annotation'
+
+interface RecordEntry {
+  key: AnimationObjectKey
+  config: AnimationConfig
+  id: string
+  raw?: AnimationHandle
+  state?: AnimationState
+  handle: AnimationHandle
+  release: () => void
+  manualPaused: boolean
+}
+function conflicts(a: AnimationObjectKey, b: AnimationObjectKey): boolean {
+  if (a.kind !== b.kind || a.id !== b.id) return false
+  if (
+    a.kind === 'annotation' &&
+    ['enter', 'leave'].includes(a.scope) &&
+    ['enter', 'leave'].includes(b.scope)
+  )
+    return true
+  if (
+    a.kind === 'series' &&
+    ['enter', 'update'].includes(a.scope) &&
+    ['enter', 'update'].includes(b.scope)
+  )
+    return true
+  return a.scope === b.scope
+}
+
+/** Owner-scoped coordination; it never installs browser listeners or writes DOM. */
+export class WaveformAnimationController {
+  #records = new Map<string, RecordEntry>()
+  #owner = createAnimationOwner()
+  #enabled: boolean
+  #animator: NonNullable<WaveformAnimationControllerOptions['animator']>
+  #barrier = false
+  #disposed = false
+  #paused = new Set<string>()
+  constructor(private options: WaveformAnimationControllerOptions) {
+    if (!options || typeof options.commitFinalState !== 'function')
+      throw new TypeError('commitFinalState is required')
+    this.#enabled = options.enabled ?? true
+    this.#animator = options.animator ?? globalAnimator
+  }
+  #assertOpen(): void {
+    if (this.#barrier) throw animationError('animation-terminating')
+    if (this.#disposed) throw animationError('animation-disposed')
+  }
+  animate(key: AnimationObjectKey, config: AnimationConfig): AnimationHandle {
+    this.#assertOpen()
+    if (
+      !key ||
+      !['series', 'annotation', 'axis', 'custom'].includes(key.kind) ||
+      typeof key.id !== 'string' ||
+      !['enter', 'update', 'leave', 'domain'].includes(key.scope)
+    )
+      throw new TypeError('Invalid animation object key')
+    if (this.#animator instanceof Animator) this.#animator.validate(config)
+    else validateAnimationConfig(config)
+    // Old terminal callbacks may mutate caller-owned arrays before manager registration.
+    // Preserve the group-aware preflight contract without sharing those endpoints.
+    const snapshot = {
+      ...config,
+      tracks: config.tracks?.map((track) => ({
+        ...track,
+        from: track.from === undefined ? undefined : copyAnimationValue(track.from, 'from'),
+        to: copyAnimationValue(track.to, 'to'),
+      })),
+    }
+    const id = this.#owner(key)
+    const olds = [...this.#records.values()].filter((record) => conflicts(record.key, key))
+    const record = { key: { ...key }, config: snapshot, id, manualPaused: false } as RecordEntry
+    const { handle, release } = createAnimationHandle(
+      id,
+      () => record.state ?? record.raw?.state ?? 'PENDING',
+      (method) => {
+        if (method === 'pause') {
+          record.manualPaused = true
+          record.raw?.pause()
+        } else if (method === 'resume') {
+          record.manualPaused = false
+          if (this.#animator instanceof Animator || !this.#paused.size) record.raw?.resume()
+        } else if (method === 'abort') {
+          if (record.raw) record.raw.abort()
+          else this.#finishRecord(record, 'ABORTED')
+        } else record.raw?.finish()
+      },
+    )
+    record.handle = handle
+    record.release = release
+    this.#records.set(id, record)
+    for (const old of olds) {
+      if (key.kind === 'series' && key.scope === 'update' && old.key.scope === 'enter') {
+        try {
+          old.config.during?.(1, {
+            rawProgress: 1,
+            directedProgress: 1,
+            iteration: 0,
+            terminal: true,
+          })
+        } catch (error) {
+          reportAnimationError(old.config, error)
+        }
+      }
+      old.handle.abort()
+    }
+    if (record.state) return record.handle
+    const wrapped: AnimationConfig = {
+      ...snapshot,
+      initialize:
+        this.#animator instanceof Animator
+          ? snapshot.initialize
+          : () => {
+              snapshot.initialize?.()
+              if (this.#paused.size) this.#animator.pause(id)
+            },
+      duration: this.#enabled ? snapshot.duration : 0,
+      loop: this.#enabled ? snapshot.loop : 1,
+      done: () => {
+        if (!this.#barrier) this.#finishRecord(record, 'FINISHED')
+      },
+      aborted: () => {
+        if (!this.#barrier) this.#finishRecord(record, 'ABORTED')
+      },
+      onError: (error) => {
+        reportAnimationError(snapshot, error)
+        if (!this.#barrier && !this.#disposed) this.finishAll()
+      },
+    }
+    try {
+      record.raw =
+        this.#animator instanceof Animator
+          ? this.#animator.animatePaused(
+              wrapped,
+              id,
+              [...this.#paused].map((reason) => this.#ownerPause(reason)),
+            )
+          : this.#animator.animate(wrapped, id)
+    } catch (error) {
+      this.#finishRecord(record, 'ABORTED')
+      throw error
+    }
+    if (this.#animator instanceof Animator)
+      for (const reason of this.#paused) {
+        this.#animator.setPauseReason(this.#ownerPause(reason), true, [id])
+      }
+    else if (this.#paused.size) record.raw.pause()
+    return record.handle
+  }
+  #finishRecord(record: RecordEntry, state: 'FINISHED' | 'ABORTED'): void {
+    if (record.state === 'FINISHED' || record.state === 'ABORTED') return
+    record.state = state
+    if (this.#records.get(record.id) === record) this.#records.delete(record.id)
+    record.release()
+    notify(record.config, state === 'FINISHED' ? record.config.done : record.config.aborted)
+  }
+  animateSeriesEnter(
+    id: string,
+    binding: AnimationBinding<ClipAnimationState>,
+    width: number,
+    options?: LineDrawingOptions,
+  ): AnimationHandle {
+    this.#assertOpen()
+    return this.animate(
+      { kind: 'series', id, scope: 'enter' },
+      createLineDrawingAnimation(binding, width, options),
+    )
+  }
+  animateMultiSeriesEnter(
+    series: readonly { id: string; binding: AnimationBinding<ClipAnimationState>; width: number }[],
+    options?: StaggeredLineDrawingOptions,
+  ): AnimationHandle[] {
+    this.#assertOpen()
+    const configs = createStaggeredLineDrawingAnimations(series, options)
+    return configs.map((config, index) =>
+      this.animate({ kind: 'series', id: series[index].id, scope: 'enter' }, config),
+    )
+  }
+  animateDataUpdate(
+    id: string,
+    input: GeometryTransitionInput,
+    write: (frame: GeometryTransitionFrame) => void,
+    options?: DataUpdateOptions,
+  ): AnimationHandle {
+    this.#assertOpen()
+    return this.animate(
+      { kind: 'series', id, scope: 'update' },
+      createPathTransitionAnimation(input, write, options),
+    )
+  }
+  animateYAxisScale(
+    id: string,
+    binding: AnimationBinding<[number, number]>,
+    to: [number, number],
+    options?: DataUpdateOptions,
+  ): AnimationHandle {
+    this.#assertOpen()
+    return this.animate(
+      { kind: 'axis', id, scope: 'domain' },
+      createYAxisScaleAnimation(binding, to, options),
+    )
+  }
+  animateAnnotationAppear(
+    id: string,
+    binding: AnimationBinding<AnnotationAnimationState>,
+    options?: AnnotationAnimationOptions,
+  ): AnimationHandle {
+    this.#assertOpen()
+    return this.animate(
+      { kind: 'annotation', id, scope: 'enter' },
+      createAnnotationAppearAnimation(binding, options),
+    )
+  }
+  animateAnnotationDisappear(
+    id: string,
+    binding: AnimationBinding<AnnotationAnimationState>,
+    options?: AnnotationAnimationOptions,
+  ): AnimationHandle {
+    this.#assertOpen()
+    return this.animate(
+      { kind: 'annotation', id, scope: 'leave' },
+      createAnnotationDisappearAnimation(binding, options),
+    )
+  }
+  cancel(key: AnimationObjectKey): void {
+    this.#records.get(this.#owner(key))?.handle.abort()
+  }
+  cancelAll(): void {
+    this.#bulk(false, false)
+  }
+  finishAll(): void {
+    this.#bulk(true, true)
+  }
+  /** Adapter category commits are separate from the whole-chart final-state commit. */
+  finishWhere(predicate: (key: AnimationObjectKey) => boolean, commit: () => void): void {
+    this.#bulk(true, true, predicate, commit)
+  }
+  #bulk(
+    finish: boolean,
+    commit: boolean,
+    predicate: (key: AnimationObjectKey) => boolean = () => true,
+    submit = this.options.commitFinalState,
+  ): void {
+    if (this.#barrier || this.#disposed) return
+    this.#barrier = true
+    const records = [...this.#records.values()].filter((record) => predicate(record.key))
+    try {
+      for (const record of records) {
+        if (this.#records.get(record.id) === record) this.#records.delete(record.id)
+        record.raw?.abort()
+      }
+      try {
+        if (commit) submit()
+      } catch (error) {
+        for (const record of records) {
+          this.#finishRecord(record, 'ABORTED')
+          reportAnimationError(record.config, error)
+        }
+        throw error
+      }
+      for (const record of records) this.#finishRecord(record, finish ? 'FINISHED' : 'ABORTED')
+    } finally {
+      this.#barrier = false
+    }
+  }
+  pauseAll(): void {
+    this.setPauseReason('manual-all', true)
+  }
+  resumeAll(): void {
+    this.setPauseReason('manual-all', false)
+  }
+  #ownerPause(reason: string) {
+    return `${this.#owner({ kind: 'custom', id: 'pause', scope: 'domain' })}:${reason}`
+  }
+  setPauseReason(reason: string, pause: boolean): void {
+    if (this.#disposed) return
+    if (pause) this.#paused.add(reason)
+    else this.#paused.delete(reason)
+    if (this.#animator instanceof Animator)
+      this.#animator.setPauseReason(this.#ownerPause(reason), pause, [...this.#records.keys()])
+    else if (pause) this.#records.forEach((record) => record.raw?.pause())
+    else if (!this.#paused.size)
+      this.#records.forEach((record) => {
+        if (!record.manualPaused) record.raw?.resume()
+      })
+  }
+  setEnabled(enabled: boolean): void {
+    if (this.#disposed || this.#enabled === enabled) return
+    this.#enabled = enabled
+    if (!enabled) this.finishAll()
+  }
+  getActiveAnimationCount(): number {
+    return this.#records.size
+  }
+  destroy(): void {
+    if (this.#disposed || this.#barrier) return
+    this.#bulk(false, false)
+    this.#disposed = true
+    this.#paused.clear()
+  }
+}

package/src/animation/core/Animation.ts

@@ -0,0 +1,37 @@
+import type { AnimationConfig, AnimationState } from './types'
+import { validateAnimationConfig } from './validation'
+import { PropertyGroups } from './propertyGroups'
+import { AnimationTask } from './task'
+
+/** Standalone manual timeline; use Animator for concurrent writers and additive groups. */
+export class Animation {
+  readonly #task: AnimationTask
+  constructor(config: AnimationConfig) {
+    const groups = new PropertyGroups()
+    const validated = validateAnimationConfig(config)
+    validated.tracks = groups.capture(validated)
+    this.#task = new AnimationTask(validated, groups)
+    groups.bind(this.#task)
+  }
+  get state(): AnimationState {
+    return this.#task.state
+  }
+  start(time: number): void {
+    this.#task.start(time)
+  }
+  tick(time: number): boolean {
+    return this.#task.tick(time)
+  }
+  pause(time: number): void {
+    this.#task.pause(time)
+  }
+  resume(time: number): void {
+    this.#task.resume(time)
+  }
+  abort(): void {
+    this.#task.abort()
+  }
+  finish(): void {
+    this.#task.finish()
+  }
+}

package/src/animation/core/Animator.ts

@@ -0,0 +1,200 @@
+import type { AnimationConfig, AnimationHandle, AnimationScheduler } from './types'
+import { validateAnimationConfig, validateAnimationScheduler } from './validation'
+import { PropertyGroups } from './propertyGroups'
+import { AnimationTask } from './task'
+import { animationError } from './errors'
+import { createAnimationHandle } from './handle'
+
+function defaultScheduler(): AnimationScheduler {
+  // Constructed only on first animate, never during module import.
+  const raf =
+    typeof globalThis.requestAnimationFrame === 'function' &&
+    typeof globalThis.cancelAnimationFrame === 'function'
+  return {
+    now: () => globalThis.performance?.now() ?? Date.now(),
+    requestFrame: raf ? (callback) => globalThis.requestAnimationFrame(callback) : undefined,
+    cancelFrame: raf ? (id) => globalThis.cancelAnimationFrame(id) : undefined,
+    setTimer: (callback, delay) => setTimeout(callback, delay),
+    clearTimer: (id) => clearTimeout(id as ReturnType<typeof setTimeout>),
+  }
+}
+
+/** Shared numeric task scheduler. Empty, delayed-only and paused queues never spin RAF. */
+export class Animator {
+  #scheduler?: AnimationScheduler
+  readonly #injected: boolean
+  #tasks = new Map<string, AnimationTask>()
+  #groups = new PropertyGroups()
+  #reasons = new Set<string>()
+  #frameId?: number
+  #timerId?: unknown
+  #hasTimer = false
+  #sequence = 0
+  #barrier = false
+  #frameRunning = false
+  constructor(scheduler?: AnimationScheduler) {
+    if (scheduler) validateAnimationScheduler(scheduler)
+    this.#scheduler = scheduler
+    this.#injected = !!scheduler
+  }
+  #clock() {
+    return (this.#scheduler ??= defaultScheduler())
+  }
+  validate(config: AnimationConfig): void {
+    validateAnimationConfig(config, this.#groups.context)
+  }
+  animate(config: AnimationConfig, id?: string): AnimationHandle {
+    return this.animatePaused(config, id, [])
+  }
+  /** Adapter registration with inherited owner reasons, before any scheduling occurs. */
+  animatePaused(
+    config: AnimationConfig,
+    id: string | undefined,
+    reasons: readonly string[],
+  ): AnimationHandle {
+    if (this.#barrier) throw animationError('animation-terminating')
+    if (id !== undefined && typeof id !== 'string')
+      throw new TypeError('Animation id must be string')
+    const validated = validateAnimationConfig(config, this.#groups.context)
+    const conflicts = this.#groups.conflicts(validated) as Set<AnimationTask>
+    if (id !== undefined && this.#tasks.has(id)) conflicts.add(this.#tasks.get(id)!)
+    validated.tracks = this.#groups.capture(validated)
+    const task = new AnimationTask(validated, this.#groups)
+    let key = id
+    if (key === undefined) {
+      do {
+        key = `animation-${++this.#sequence}`
+      } while (this.#tasks.has(key))
+    }
+    const callbacks = [...conflicts].map((old) => old.settle('ABORTED', false))
+    this.#tasks.set(key, task)
+    this.#groups.bind(task)
+    const scheduler = this.#clock()
+    const { handle, release } = createAnimationHandle(
+      key,
+      () => task.state,
+      (method) => {
+        task[method](scheduler.now())
+        this.#schedule()
+      },
+    )
+    task.setTermination(() => {
+      if (this.#tasks.get(key) === task) this.#tasks.delete(key)
+      release()
+      this.#schedule()
+    })
+    for (const reason of new Set([...this.#reasons, ...reasons]))
+      task.pause(scheduler.now(), reason)
+    // The new owner is visible to reentrant requests before old user notifications.
+    callbacks.forEach((callback) => callback())
+    if (!task.ended) task.start(scheduler.now(), !scheduler.requestFrame)
+    this.#schedule()
+    return handle
+  }
+  remove(id: string): void {
+    this.#tasks.get(id)?.abort()
+    this.#schedule()
+  }
+  pause(id: string): void {
+    this.#tasks.get(id)?.pause(this.#clock().now())
+    this.#schedule()
+  }
+  resume(id: string): void {
+    this.#tasks.get(id)?.resume(this.#clock().now())
+    this.#schedule()
+  }
+  pauseAll(): void {
+    this.setPauseReason('manual-all', true)
+  }
+  resumeAll(): void {
+    this.setPauseReason('manual-all', false)
+  }
+  /** Independent adapter-owned pause reasons, including document-hidden and owner scopes. */
+  setPauseReason(reason: string, paused: boolean, ids?: readonly string[]): void {
+    if (!ids) {
+      if (paused) this.#reasons.add(reason)
+      else this.#reasons.delete(reason)
+    }
+    const tasks = ids
+      ? ids.map((id) => this.#tasks.get(id)).filter((task) => !!task)
+      : [...this.#tasks.values()]
+    const time = this.#clock().now()
+    for (const task of tasks) {
+      if (paused) task.pause(time, reason)
+      else task.resume(time, reason)
+    }
+    this.#schedule()
+  }
+  finishAll(): void {
+    this.#bulk('finish')
+  }
+  clear(): void {
+    this.#bulk('abort')
+  }
+  destroy(): void {
+    if (this.#barrier) return
+    this.#bulk('abort')
+    this.#reasons.clear()
+    this.#groups = new PropertyGroups()
+    if (!this.#injected) this.#scheduler = undefined
+  }
+  getAnimationCount(): number {
+    return this.#tasks.size
+  }
+  #bulk(method: 'finish' | 'abort'): void {
+    if (this.#barrier) return
+    this.#barrier = true
+    try {
+      // oxlint-disable-next-line unicorn/no-useless-spread -- Callbacks mutate tasks; snapshot membership.
+      for (const task of [...this.#tasks.values()]) {
+        if (method === 'finish') task.finish(this.#clock().now())
+        else task.abort()
+      }
+    } finally {
+      this.#barrier = false
+      this.#schedule()
+    }
+  }
+  #stop(): void {
+    if (this.#frameId !== undefined) this.#scheduler?.cancelFrame?.(this.#frameId)
+    if (this.#hasTimer) this.#scheduler?.clearTimer(this.#timerId)
+    this.#frameId = undefined
+    this.#timerId = undefined
+    this.#hasTimer = false
+  }
+  #schedule(): void {
+    if (this.#frameRunning || this.#barrier) return
+    this.#stop()
+    if (!this.#tasks.size) return
+    const scheduler = this.#clock()
+    if (!scheduler.requestFrame) return
+    const now = scheduler.now()
+    const deadline = Math.min(...[...this.#tasks.values()].map((task) => task.deadline(now)))
+    if (deadline === Infinity) return
+    if (deadline > now) {
+      this.#hasTimer = true
+      this.#timerId = scheduler.setTimer(() => {
+        this.#hasTimer = false
+        this.#schedule()
+      }, deadline - now)
+    } else this.#frameId = scheduler.requestFrame(() => this.#frame())
+  }
+  #frame(): void {
+    this.#frameId = undefined
+    this.#frameRunning = true
+    const time = this.#clock().now()
+    try {
+      const frames = [...this.#tasks].map(([id, task]) => ({ id, task, next: task.prepare(time) }))
+      this.#groups.flush()
+      for (const { id, task, next } of frames) {
+        if (next && this.#tasks.get(id) === task) task.deliver(next.progress, next.frame)
+      }
+    } finally {
+      this.#frameRunning = false
+      this.#schedule()
+    }
+  }
+}
+
+/** Construction is side-effect free; browser capabilities are read lazily on animate. */
+export const globalAnimator = /* @__PURE__ */ new Animator()

package/src/animation/core/easing.ts

@@ -0,0 +1,74 @@
+import {
+  easeLinear,
+  easeQuadIn,
+  easeQuadOut,
+  easeQuadInOut,
+  easeCubicIn,
+  easeCubicOut,
+  easeCubicInOut,
+  easePolyIn,
+  easePolyOut,
+  easePolyInOut,
+  easeSinIn,
+  easeSinOut,
+  easeSinInOut,
+  easeExpIn,
+  easeExpOut,
+  easeExpInOut,
+  easeCircleIn,
+  easeCircleOut,
+  easeCircleInOut,
+  easeBackIn,
+  easeBackOut,
+  easeBackInOut,
+  easeElasticIn,
+  easeElasticOut,
+  easeElasticInOut,
+  easeBounceIn,
+  easeBounceOut,
+  easeBounceInOut,
+} from 'd3'
+import type { EasingFunction, EasingType } from './types'
+
+const easings: Record<EasingType, EasingFunction> = {
+  linear: easeLinear,
+  quadIn: easeQuadIn,
+  quadOut: easeQuadOut,
+  quadInOut: easeQuadInOut,
+  cubicIn: easeCubicIn,
+  cubicOut: easeCubicOut,
+  cubicInOut: easeCubicInOut,
+  quartIn: easePolyIn.exponent(4),
+  quartOut: easePolyOut.exponent(4),
+  quartInOut: easePolyInOut.exponent(4),
+  quintIn: easePolyIn.exponent(5),
+  quintOut: easePolyOut.exponent(5),
+  quintInOut: easePolyInOut.exponent(5),
+  sineIn: easeSinIn,
+  sineOut: easeSinOut,
+  sineInOut: easeSinInOut,
+  expoIn: easeExpIn,
+  expoOut: easeExpOut,
+  expoInOut: easeExpInOut,
+  circIn: easeCircleIn,
+  circOut: easeCircleOut,
+  circInOut: easeCircleInOut,
+  backIn: easeBackIn,
+  backOut: easeBackOut,
+  backInOut: easeBackInOut,
+  elasticIn: easeElasticIn,
+  elasticOut: easeElasticOut,
+  elasticInOut: easeElasticInOut,
+  bounceIn: easeBounceIn,
+  bounceOut: easeBounceOut,
+  bounceInOut: easeBounceInOut,
+}
+
+/** Preserve custom functions and overshoot; execution errors belong to the task runtime. */
+export function getEasingFunction(easing: EasingType | EasingFunction): EasingFunction {
+  if (typeof easing === 'function') return easing
+  if (typeof easing !== 'string' || !Object.hasOwn(easings, easing)) {
+    throw new TypeError(`Unknown animation easing: ${String(easing)}`)
+  }
+  return easings[easing]
+}

package/src/animation/core/errors.ts

@@ -0,0 +1,24 @@
+import type { AnimationConfig } from './types'
+
+export function animationError(code: 'animation-terminating' | 'animation-disposed'): Error {
+  return Object.assign(new Error(code), { code })
+}
+export function reportAnimationError(config: AnimationConfig, error: unknown): void {
+  try {
+    if (config.onError) config.onError(error)
+    else console.error(error)
+  } catch (reporterError) {
+    try {
+      console.error(reporterError)
+    } catch {
+      /* Reporting must never interrupt peers. */
+    }
+  }
+}
+export function notify(config: AnimationConfig, callback?: () => void): void {
+  try {
+    callback?.()
+  } catch (error) {
+    reportAnimationError(config, error)
+  }
+}

package/src/animation/core/handle.ts

@@ -0,0 +1,34 @@
+import type { AnimationHandle, AnimationState } from './types'
+
+export type AnimationCommand = 'pause' | 'resume' | 'abort' | 'finish'
+
+/** Terminal handles keep only identity/state, never their task, clock or owner. */
+export function createAnimationHandle(
+  id: string,
+  read: () => AnimationState,
+  command: (method: AnimationCommand) => void,
+): { handle: AnimationHandle; release: () => void } {
+  let access: { read: () => AnimationState; command: typeof command } | undefined = {
+    read,
+    command,
+  }
+  let terminalState: AnimationState = 'PENDING'
+  const invoke = (method: AnimationCommand) => access?.command(method)
+  return {
+    handle: {
+      id,
+      get state() {
+        return access?.read() ?? terminalState
+      },
+      pause: () => invoke('pause'),
+      resume: () => invoke('resume'),
+      abort: () => invoke('abort'),
+      finish: () => invoke('finish'),
+    },
+    release: () => {
+      if (!access) return
+      terminalState = access.read()
+      access = undefined
+    },
+  }
+}