waveform-analysis 0.1.74 → 0.1.75

package/src/animation/core/owner.ts

@@ -0,0 +1,9 @@
+import type { AnimationObjectKey } from '../types'
+
+/** Each controller owns one closure; external IDs are never shared scheduler keys. */
+export function createAnimationOwner(): (key: AnimationObjectKey) => string {
+  const owner = ++nextOwner
+  return (key) => JSON.stringify([owner, key.kind, key.id, key.scope])
+}
+
+let nextOwner = 0

package/src/animation/core/propertyGroups.ts

@@ -0,0 +1,143 @@
+import type { AnimationTrack, AnimationValue } from './types'
+import type { ValidatedAnimationConfig, AnimationTrackContext } from './validation'
+import { copyAnimationValue } from './validation'
+import { addValues, subtractValues, mapValue, interpolateValue, directedProgress } from './values'
+
+export interface PropertyTask {
+  config: ValidatedAnimationConfig
+  fail(error: unknown): void
+}
+interface Entry {
+  task: PropertyTask
+  from: AnimationValue
+  to: AnimationValue
+  value: AnimationValue
+  committed: AnimationValue
+}
+interface Group {
+  target: Record<string, AnimationValue>
+  property: string
+  base: AnimationValue
+  offset: AnimationValue
+  ordinary?: Entry
+  additive: Set<Entry>
+}
+
+/** Object identity, never user series IDs, determines numeric property ownership. */
+export class PropertyGroups {
+  #groups = new Map<object, Map<string, Group>>()
+  #entries = new Map<PropertyTask, [Group, Entry][]>()
+
+  #get(track: AnimationTrack): Group | undefined {
+    return this.#groups.get(track.target)?.get(track.property)
+  }
+  #end(entry: Entry): AnimationValue {
+    const { direction, loop } = entry.task.config
+    return directedProgress(1, loop === Infinity ? 0 : loop - 1, direction) === 1
+      ? entry.to
+      : entry.from
+  }
+  context = (track: AnimationTrack): AnimationTrackContext | undefined => {
+    const group = this.#get(track)
+    if (!group) return undefined
+    let from = addValues(group.ordinary ? this.#end(group.ordinary) : group.base, group.offset)
+    for (const entry of group.additive)
+      from = addValues(from, subtractValues(this.#end(entry), entry.from))
+    return { additiveFrom: from, baseLoop: group.ordinary?.task.config.loop ?? 1 }
+  }
+  conflicts(config: ValidatedAnimationConfig): Set<PropertyTask> {
+    const tasks = new Set<PropertyTask>()
+    if (!config.additive)
+      for (const track of config.tracks) {
+        const group = this.#get(track)
+        if (group?.ordinary) tasks.add(group.ordinary.task)
+        group?.additive.forEach((entry) => tasks.add(entry.task))
+      }
+    return tasks
+  }
+  capture(config: ValidatedAnimationConfig): AnimationTrack[] {
+    return config.tracks.map((track) => ({
+      ...track,
+      from: copyAnimationValue(
+        config.additive
+          ? (this.context(track)?.additiveFrom ?? track.target[track.property])
+          : this.#get(track)
+            ? track.target[track.property]
+            : (track.from ?? track.target[track.property]),
+      ),
+    }))
+  }
+  bind(task: PropertyTask): void {
+    const entries: [Group, Entry][] = []
+    for (const track of task.config.tracks) {
+      let group = this.#get(track)
+      if (!group) {
+        const base = copyAnimationValue(track.target[track.property])
+        group = {
+          target: track.target,
+          property: track.property,
+          base,
+          offset: mapValue(base, () => 0),
+          additive: new Set(),
+        }
+        const properties = this.#groups.get(track.target) ?? new Map<string, Group>()
+        properties.set(track.property, group)
+        this.#groups.set(track.target, properties)
+      }
+      const from = copyAnimationValue(track.from!)
+      const entry = {
+        task,
+        from,
+        to: track.to,
+        value: task.config.additive ? mapValue(from, () => 0) : from,
+        committed: task.config.additive ? mapValue(from, () => 0) : group.base,
+      }
+      if (task.config.additive) group.additive.add(entry)
+      else group.ordinary = entry
+      entries.push([group, entry])
+    }
+    this.#entries.set(task, entries)
+  }
+  setProgress(task: PropertyTask, progress: number): void {
+    for (const [, entry] of this.#entries.get(task) ?? []) {
+      const value = interpolateValue(entry.from, entry.to, progress)
+      entry.value = copyAnimationValue(
+        task.config.additive ? subtractValues(value, entry.from) : value,
+      )
+    }
+  }
+  flush(): void {
+    for (const properties of this.#groups.values())
+      for (const group of properties.values()) {
+        try {
+          let value = addValues(group.ordinary?.value ?? group.base, group.offset)
+          for (const entry of group.additive) value = addValues(value, entry.value)
+          group.target[group.property] = copyAnimationValue(value)
+          // Private values are replaced, never mutated or exposed through the target snapshot.
+          if (group.ordinary) group.ordinary.committed = group.ordinary.value
+          for (const entry of group.additive) entry.committed = entry.value
+        } catch (error) {
+          const tasks = new Set([
+            ...(group.ordinary ? [group.ordinary.task] : []),
+            ...[...group.additive].map((entry) => entry.task),
+          ])
+          for (const task of tasks) task.fail(error)
+        }
+      }
+  }
+  detach(task: PropertyTask): void {
+    for (const [group, entry] of this.#entries.get(task) ?? []) {
+      if (group.ordinary === entry) {
+        group.base = entry.committed
+        group.ordinary = undefined
+      }
+      if (group.additive.delete(entry)) group.offset = addValues(group.offset, entry.committed)
+      if (!group.ordinary && !group.additive.size) {
+        // The last flush already contains committed contributions. Release the whole group.
+        this.#groups.get(group.target)?.delete(group.property)
+        if (!this.#groups.get(group.target)?.size) this.#groups.delete(group.target)
+      }
+    }
+    this.#entries.delete(task)
+  }
+}

package/src/animation/core/task.ts

@@ -0,0 +1,153 @@
+import type { AnimationFrame, AnimationState } from './types'
+import type { ValidatedAnimationConfig } from './validation'
+import { directedProgress, equalValues } from './values'
+import { PropertyGroups } from './propertyGroups'
+import { notify, reportAnimationError } from './errors'
+
+/** Internal timeline; standalone and managed animations share exactly the same semantics. */
+export class AnimationTask {
+  state: AnimationState = 'PENDING'
+  #started = false
+  #startTime = 0
+  #pauseTime = 0
+  #pausedTotal = 0
+  #reasons = new Set<string>()
+  #previousState: AnimationState = 'PENDING'
+  #iteration = 0
+  #terminate?: () => void
+
+  constructor(
+    readonly config: ValidatedAnimationConfig,
+    private groups: PropertyGroups,
+  ) {}
+  get ended() {
+    return this.state === 'FINISHED' || this.state === 'ABORTED'
+  }
+  get unchanged() {
+    return !this.config.force && this.config.tracks.every((t) => equalValues(t.from!, t.to))
+  }
+  setTermination(callback: () => void) {
+    this.#terminate = callback
+  }
+  start(time: number, synchronous = false): void {
+    if (this.#started || this.ended) throw new Error('Animation can only start once')
+    this.#started = true
+    this.#startTime = time
+    if (this.#reasons.size) this.#pauseTime = time
+    if (synchronous || this.config.duration === 0 || this.unchanged) {
+      this.finish()
+      return
+    }
+    try {
+      this.config.initialize?.()
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+  deadline(time: number): number {
+    if (this.ended || this.#reasons.size) return Infinity
+    return Math.max(time, this.#startTime + this.config.delay + this.#pausedTotal)
+  }
+  prepare(time: number): { progress: number; frame: AnimationFrame } | undefined {
+    if (!this.#started || this.ended || this.#reasons.size) return
+    const elapsed = time - this.#startTime - this.config.delay - this.#pausedTotal
+    if (elapsed < 0) return
+    this.state = 'RUNNING'
+    const { duration, loop, direction } = this.config
+    const terminal = elapsed >= duration * loop
+    this.#iteration = terminal ? loop - 1 : Math.floor(elapsed / duration)
+    const rawProgress = terminal ? 1 : (elapsed % duration) / duration
+    const directed = directedProgress(rawProgress, this.#iteration, direction)
+    const frame = { rawProgress, directedProgress: directed, iteration: this.#iteration, terminal }
+    try {
+      const progress = terminal ? directed : this.config.easing(directed)
+      if (!Number.isFinite(progress)) throw new RangeError('Easing returned a nonfinite value')
+      this.groups.setProgress(this, progress)
+      return { progress, frame }
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+  deliver(progress: number, frame: AnimationFrame): void {
+    if (this.ended) return
+    try {
+      this.config.during?.(progress, frame)
+    } catch (error) {
+      this.fail(error)
+      return
+    }
+    if (frame.terminal && !this.ended) this.#complete('FINISHED')
+  }
+  tick(time: number): boolean {
+    const next = this.prepare(time)
+    if (next) {
+      this.groups.flush()
+      this.deliver(next.progress, next.frame)
+    }
+    return this.ended
+  }
+  pause(time: number, reason = 'manual'): void {
+    if (this.ended || this.#reasons.has(reason)) return
+    if (!this.#reasons.size) {
+      this.#previousState = this.state
+      this.#pauseTime = time
+      this.state = 'PAUSED'
+    }
+    this.#reasons.add(reason)
+  }
+  resume(time: number, reason = 'manual'): void {
+    if (this.ended || !this.#reasons.delete(reason) || this.#reasons.size) return
+    this.#pausedTotal += time - this.#pauseTime
+    this.state = this.#previousState
+  }
+  finish(time?: number): void {
+    if (this.ended) return
+    const { loop, direction } = this.config
+    if (loop === Infinity && time !== undefined && this.#started) {
+      const elapsed = Math.max(
+        0,
+        (this.#reasons.size ? this.#pauseTime : time) -
+          this.#startTime -
+          this.config.delay -
+          this.#pausedTotal,
+      )
+      this.#iteration = Math.floor(elapsed / this.config.duration)
+    }
+    const iteration = loop === Infinity ? this.#iteration : loop - 1
+    const progress = directedProgress(1, iteration, direction)
+    try {
+      this.groups.setProgress(this, progress)
+      this.groups.flush()
+    } catch (error) {
+      this.fail(error)
+      return
+    }
+    this.deliver(progress, {
+      rawProgress: 1,
+      directedProgress: progress,
+      iteration,
+      terminal: true,
+    })
+  }
+  abort(): void {
+    if (!this.ended) this.#complete('ABORTED')
+  }
+  /** Detach without callbacks/old terminal frames for owner-level commit barriers. */
+  settle(state: 'FINISHED' | 'ABORTED', notifyUser = true): () => void {
+    if (this.ended) return () => {}
+    this.state = state
+    this.groups.detach(this)
+    this.#terminate?.()
+    const callback = () =>
+      notify(this.config, state === 'FINISHED' ? this.config.done : this.config.aborted)
+    if (notifyUser) callback()
+    return callback
+  }
+  #complete(state: 'FINISHED' | 'ABORTED') {
+    this.settle(state)
+  }
+  fail(error: unknown) {
+    this.abort()
+    reportAnimationError(this.config, error)
+  }
+}

package/src/animation/core/types.ts

@@ -0,0 +1,81 @@
+/** Numeric output only: geometry strings and typed arrays are not animation values. */
+export type AnimationValue = number | number[] | number[][]
+export type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
+export type AnimationState = 'PENDING' | 'RUNNING' | 'PAUSED' | 'FINISHED' | 'ABORTED'
+export type EasingFunction = (progress: number) => number
+export type EasingFamily =
+  'quad' | 'cubic' | 'quart' | 'quint' | 'sine' | 'expo' | 'circ' | 'back' | 'elastic' | 'bounce'
+export type EasingType = 'linear' | `${EasingFamily}${'In' | 'Out' | 'InOut'}`
+
+export interface AnimationFrame {
+  rawProgress: number
+  directedProgress: number
+  /** Zero-based iteration. */
+  iteration: number
+  /** Natural completion or explicit finish; abort never produces a terminal frame. */
+  terminal: boolean
+}
+
+export interface AnimationTrack {
+  target: Record<string, AnimationValue>
+  property: string
+  /** Omitted ordinary starts are captured at registration; additive starts are derived. */
+  from?: AnimationValue
+  to: AnimationValue
+}
+
+/** All time values are milliseconds. Validation precedes initialization and replacement. */
+export interface AnimationConfig {
+  initialize?: () => void
+  tracks?: AnimationTrack[]
+  /** Defaults to 1000ms; zero completes synchronously without delay. */
+  duration?: number
+  /** First iteration only, defaults to 0ms. */
+  delay?: number
+  /** Defaults to linear; custom functions may overshoot. */
+  easing?: EasingType | EasingFunction
+  /** Defaults to 1; false means once, true means infinite, numbers are positive integers. */
+  loop?: number | boolean
+  /** Defaults to normal; direction is applied before easing. */
+  direction?: AnimationDirection
+  /** Defaults to false; does not override component disable/fallback policies. */
+  force?: boolean
+  /** Defaults to false; additive tracks and their bases must not loop. */
+  additive?: boolean
+  during?: (easedProgress: number, frame: AnimationFrame) => void
+  done?: () => void
+  aborted?: () => void
+  onError?: (error: unknown) => void
+}
+
+export interface AnimationHandle {
+  readonly id: string
+  readonly state: AnimationState
+  pause(): void
+  resume(): void
+  abort(): void
+  finish(): void
+}
+
+/** RAF functions must be provided together, or both omitted for static completion. */
+export interface AnimationScheduler {
+  now(): number
+  requestFrame?: (callback: (time: number) => void) => number
+  cancelFrame?: (id: number) => void
+  setTimer(callback: () => void, delay: number): unknown
+  clearTimer(id: unknown): void
+}
+
+/** Structural contract for injected Animator implementations (ENG-09). */
+export interface Animator {
+  animate(config: AnimationConfig, id?: string): AnimationHandle
+  remove(id: string): void
+  pause(id: string): void
+  resume(id: string): void
+  pauseAll(): void
+  resumeAll(): void
+  finishAll(): void
+  clear(): void
+  getAnimationCount(): number
+  destroy(): void
+}

package/src/animation/core/validation.ts

@@ -0,0 +1,173 @@
+import { getEasingFunction } from './easing'
+import { equalValues } from './values'
+import type {
+  AnimationConfig,
+  AnimationDirection,
+  AnimationScheduler,
+  AnimationTrack,
+  AnimationValue,
+  EasingFunction,
+} from './types'
+
+export interface ValidatedAnimationConfig extends AnimationConfig {
+  tracks: AnimationTrack[]
+  duration: number
+  delay: number
+  easing: EasingFunction
+  /** Infinity represents loop=true internally; numeric Infinity is rejected as input. */
+  loop: number
+  direction: AnimationDirection
+  force: boolean
+  additive: boolean
+}
+
+/** A future property-group registry supplies this read-only snapshot before registration. */
+export interface AnimationTrackContext {
+  /** Direction-aware baseEnd + committedOffset + sum(activeEndDelta). */
+  additiveFrom: AnimationValue
+  baseLoop: number | boolean
+}
+
+function object(value: unknown, label: string): void {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`)
+  }
+}
+
+function time(value: unknown, label: string): asserts value is number {
+  if (typeof value !== 'number') throw new TypeError(`${label} must be a number`)
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be finite and nonnegative`)
+  }
+}
+
+function iterations(value: unknown): number {
+  if (value === true) return Infinity
+  if (value === false) return 1
+  if (typeof value !== 'number') throw new TypeError('loop must be a number or boolean')
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new RangeError('loop must be a finite positive integer')
+  }
+  return value
+}
+
+/** Validate and copy without changing any input array, including empty and nested arrays. */
+export function copyAnimationValue(value: unknown, label = 'value'): AnimationValue {
+  const number = (item: unknown): number => {
+    if (typeof item !== 'number') throw new TypeError(`${label} must contain numbers`)
+    if (!Number.isFinite(item)) throw new RangeError(`${label} must contain finite numbers`)
+    return item
+  }
+  if (typeof value === 'number') return number(value)
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be numeric`)
+  const nested = value.length > 0 && Array.isArray(value[0])
+  if (!nested) return Array.from(value, number)
+  return Array.from(value, (item: unknown) => {
+    if (!Array.isArray(item)) throw new TypeError(`${label} has mixed dimensions`)
+    return Array.from(item, number)
+  })
+}
+
+/** Compare already validated numeric values without allocating another endpoint snapshot. */
+export function sameShape(a: AnimationValue, b: AnimationValue): boolean {
+  if (typeof a === 'number' || typeof b === 'number') {
+    return typeof a === 'number' && typeof b === 'number'
+  }
+  return a.length === b.length && a.every((item, i) => sameShape(item, b[i]))
+}
+
+/**
+ * Pure preflight: no target writes, callback execution, ownership changes or scheduling.
+ * The caller must finish preflight before cancelling any existing task.
+ * Omitted ordinary from remains omitted so replacement can capture the current composite.
+ */
+export function validateAnimationConfig(
+  config: AnimationConfig,
+  context?: (track: AnimationTrack) => AnimationTrackContext | undefined,
+): ValidatedAnimationConfig {
+  object(config, 'config')
+  const duration = config.duration === undefined ? 1000 : config.duration
+  const delay = config.delay === undefined ? 0 : config.delay
+  time(duration, 'duration')
+  time(delay, 'delay')
+  const loop = iterations(config.loop === undefined ? 1 : config.loop)
+  if (duration === 0 && loop === Infinity) {
+    throw new RangeError('Zero duration cannot loop infinitely')
+  }
+  const direction = config.direction === undefined ? 'normal' : config.direction
+  if (!['normal', 'reverse', 'alternate', 'alternate-reverse'].includes(direction)) {
+    throw new TypeError('Unknown animation direction')
+  }
+  for (const field of ['force', 'additive'] as const) {
+    if (config[field] !== undefined && typeof config[field] !== 'boolean') {
+      throw new TypeError(`${field} must be boolean`)
+    }
+  }
+  for (const field of ['initialize', 'during', 'done', 'aborted', 'onError'] as const) {
+    if (config[field] !== undefined && typeof config[field] !== 'function') {
+      throw new TypeError(`${field} must be a function`)
+    }
+  }
+  const easing = getEasingFunction(config.easing === undefined ? 'linear' : config.easing)
+  const additive = config.additive === undefined ? false : config.additive
+  if (additive && loop !== 1) throw new RangeError('Additive tracks cannot loop')
+  if (config.tracks !== undefined && !Array.isArray(config.tracks)) {
+    throw new TypeError('tracks must be an array')
+  }
+  const seen = new Map<object, Set<string>>()
+  const tracks: AnimationTrack[] = []
+  for (const track of config.tracks ?? []) {
+    object(track, 'track')
+    object(track.target, 'track.target')
+    if (typeof track.property !== 'string') throw new TypeError('property must be a string')
+    const properties = seen.get(track.target) ?? new Set<string>()
+    if (properties.has(track.property)) throw new TypeError('Duplicate target/property')
+    properties.add(track.property)
+    seen.set(track.target, properties)
+    const current = copyAnimationValue(track.target[track.property], 'target value')
+    const to = copyAnimationValue(track.to, 'to')
+    const from = track.from === undefined ? undefined : copyAnimationValue(track.from, 'from')
+    if (!sameShape(current, to) || (from !== undefined && !sameShape(from, to))) {
+      throw new TypeError('Track values must have identical shapes')
+    }
+    const group = additive ? context?.(track) : undefined
+    if (group) {
+      if (iterations(group.baseLoop) !== 1) throw new RangeError('Additive base cannot loop')
+      const start = copyAnimationValue(group.additiveFrom, 'additiveFrom')
+      if (!sameShape(start, to) || (from !== undefined && !equalValues(from, start))) {
+        throw new TypeError('Additive from must match the derived start')
+      }
+    } else if (additive && from !== undefined && !equalValues(from, current)) {
+      throw new TypeError('Additive from must match the fixed base')
+    }
+    tracks.push({ target: track.target, property: track.property, from, to })
+  }
+  return {
+    ...config,
+    tracks,
+    duration,
+    delay,
+    loop,
+    direction,
+    easing,
+    additive,
+    force: config.force === undefined ? false : config.force,
+  }
+}
+
+/** Validate injection without calling the clock, requesting frames or installing timers. */
+export function validateAnimationScheduler(scheduler: AnimationScheduler): void {
+  object(scheduler, 'scheduler')
+  for (const field of ['now', 'setTimer', 'clearTimer'] as const) {
+    if (typeof scheduler[field] !== 'function') throw new TypeError(`${field} must be a function`)
+  }
+  const hasRequest = scheduler.requestFrame !== undefined
+  const hasCancel = scheduler.cancelFrame !== undefined
+  if (
+    hasRequest !== hasCancel ||
+    (hasRequest &&
+      (typeof scheduler.requestFrame !== 'function' || typeof scheduler.cancelFrame !== 'function'))
+  ) {
+    throw new TypeError('requestFrame and cancelFrame must be supplied together as functions')
+  }
+}

package/src/animation/core/values.ts

@@ -0,0 +1,38 @@
+import type { AnimationDirection, AnimationValue } from './types'
+
+export function mapValue(a: AnimationValue, fn: (value: number) => number): AnimationValue {
+  return combineValues(a, a, fn)
+}
+export function combineValues(
+  a: AnimationValue,
+  b: AnimationValue,
+  fn: (a: number, b: number) => number,
+): AnimationValue {
+  if (typeof a === 'number') return fn(a, b as number)
+  return a.map((value, i) =>
+    typeof value === 'number'
+      ? fn(value, (b as number[])[i])
+      : value.map((item, j) => fn(item, (b as number[][])[i][j])),
+  ) as AnimationValue
+}
+export const addValues = (a: AnimationValue, b: AnimationValue) =>
+  combineValues(a, b, (x, y) => x + y)
+export const subtractValues = (a: AnimationValue, b: AnimationValue) =>
+  combineValues(a, b, (x, y) => x - y)
+export const interpolateValue = (a: AnimationValue, b: AnimationValue, p: number) =>
+  combineValues(a, b, (x, y) => (p === 0 ? x : p === 1 ? y : (1 - p) * x + p * y))
+export function equalValues(a: AnimationValue, b: AnimationValue): boolean {
+  if (typeof a === 'number' || typeof b === 'number') return a === b
+  return a.length === b.length && a.every((value, i) => equalValues(value, b[i]))
+}
+export function directedProgress(
+  p: number,
+  iteration: number,
+  direction: AnimationDirection,
+): number {
+  const reverse =
+    direction === 'reverse' ||
+    (direction === 'alternate' && iteration % 2 === 1) ||
+    (direction === 'alternate-reverse' && iteration % 2 === 0)
+  return reverse ? 1 - p : p
+}

package/src/animation/presets/annotation.ts

@@ -0,0 +1,66 @@
+import type { AnimationConfig } from '../core/types'
+import type {
+  AnimationBinding,
+  AnnotationAnimationOptions,
+  AnnotationAnimationState,
+} from '../types'
+import {
+  annotationEasing,
+  isAnnotationEffect,
+  clampProgress,
+  presetConfig,
+  validateBinding,
+} from './shared'
+
+function annotationConfig(
+  binding: AnimationBinding<AnnotationAnimationState>,
+  options: AnnotationAnimationOptions,
+  appear: boolean,
+): AnimationConfig {
+  validateBinding(binding)
+  const type = options.type ?? 'scale'
+  if (!isAnnotationEffect(type)) throw new TypeError('Unknown annotation effect')
+  const easing = options.easing ?? annotationEasing[type]
+  const final = {
+    opacity: appear ? 1 : 0,
+    scale: !appear && (type === 'scale' || type === 'bounce') ? 0 : 1,
+    offsetY: !appear && type === 'slide-in' ? 8 : 0,
+  }
+  let from: AnnotationAnimationState | undefined
+  return presetConfig(
+    { ...options, easing },
+    {
+      initialize: () => {
+        from = { ...binding.read() }
+        if (!Object.values(from).every(Number.isFinite))
+          throw new RangeError('Invalid annotation state')
+      },
+      during: (p, frame) => {
+        if (frame.terminal) {
+          binding.write({ ...final })
+          return
+        }
+        const start = from ?? final
+        const interpolate = (key: keyof AnnotationAnimationState) =>
+          (1 - p) * start[key] + p * final[key]
+        binding.write({
+          opacity: clampProgress(interpolate('opacity')),
+          scale: Math.max(0, interpolate('scale')),
+          offsetY: interpolate('offsetY'),
+        })
+      },
+    },
+  )
+}
+export function createAnnotationAppearAnimation(
+  binding: AnimationBinding<AnnotationAnimationState>,
+  options: AnnotationAnimationOptions = {},
+): AnimationConfig {
+  return annotationConfig(binding, options, true)
+}
+export function createAnnotationDisappearAnimation(
+  binding: AnimationBinding<AnnotationAnimationState>,
+  options: AnnotationAnimationOptions = {},
+): AnimationConfig {
+  return annotationConfig(binding, options, false)
+}