@pibbl/core 0.0.1

package/dist/lib/animation/definition.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/animation/definition.ts"],
+  "sourcesContent": ["import { withSignalWriteForbidden } from '../signals/graph.js';\nimport { easing } from './easing.js';\nimport {\n  createSpringRecord,\n  resolveSpringStart,\n  sampleSpring,\n  type SpringDefinitionRecord,\n} from './spring.js';\nimport type {\n  PibblAnimationDefinition,\n  PibblAnimationOptions,\n  PibblAnimationSampleInput,\n  PibblEasing,\n  PibblInterpolator,\n  PibblKeyframesOptions,\n  PibblSpringOptions,\n  PibblStepperOptions,\n  PibblTweenOptions,\n} from './types.js';\n\ndeclare const seekableDefinitionActivationBrand: unique symbol;\n\ninterface BaseDefinitionRecord {\n  readonly duration: number;\n  readonly debugName: string | undefined;\n}\n\ninterface TweenDefinitionRecord<T> extends BaseDefinitionRecord {\n  readonly kind: 'tween';\n  readonly hasFrom: boolean;\n  readonly from: T | undefined;\n  readonly to: T;\n  readonly easing: PibblEasing;\n  readonly interpolate: PibblInterpolator<T> | undefined;\n}\n\ninterface KeyframesDefinitionRecord<T> extends BaseDefinitionRecord {\n  readonly kind: 'keyframes';\n  readonly values: readonly T[];\n  readonly offsets: readonly number[];\n  readonly easings: readonly PibblEasing[];\n  readonly interpolate: PibblInterpolator<T> | undefined;\n}\n\ninterface CustomDefinitionRecord<T> extends BaseDefinitionRecord {\n  readonly kind: 'custom';\n  readonly sample: (input: PibblAnimationSampleInput<T>) => T;\n}\n\nexport interface StepperDefinitionRecord<T> extends BaseDefinitionRecord {\n  readonly kind: 'stepper';\n  readonly stepMilliseconds: number;\n  readonly maxElapsedMilliseconds: number;\n  readonly initial: (currentValue: T) => unknown;\n  readonly step: (state: unknown, deltaMilliseconds: number) => unknown;\n  readonly read: (state: unknown) => T;\n  readonly done: ((state: unknown) => boolean) | undefined;\n}\n\nexport type DefinitionRecord<T> =\n  | TweenDefinitionRecord<T>\n  | KeyframesDefinitionRecord<T>\n  | CustomDefinitionRecord<T>\n  | StepperDefinitionRecord<T>\n  | SpringDefinitionRecord;\n\n/** @internal Opaque activation-time state for one seekable track instance. */\nexport interface SeekableDefinitionActivation<T> {\n  readonly [seekableDefinitionActivationBrand]: T;\n  readonly duration: number;\n  readonly initialValue: T;\n}\n\n/** @internal Callback-free knowledge about a seekable definition boundary. */\nexport type SeekableDefinitionBoundaryValue<T> =\n  | { readonly kind: 'known'; readonly value: T }\n  | { readonly kind: 'unknown' };\n\ninterface SeekableDefinitionActivationRecord<T> {\n  readonly definition: PibblAnimationDefinition<T>;\n  readonly definitionRecord: Exclude<DefinitionRecord<T>, StepperDefinitionRecord<T>>;\n  readonly initialValue: T;\n}\n\nconst definitionRecords = new WeakMap<\n  PibblAnimationDefinition<unknown>,\n  DefinitionRecord<unknown>\n>();\nconst seekableActivationRecords = new WeakMap<\n  SeekableDefinitionActivation<unknown>,\n  SeekableDefinitionActivationRecord<unknown>\n>();\nlet keyframeDefinitions = 0;\nlet keyframeStorageArrayAllocations = 0;\nlet keyframeSamples = 0;\nlet keyframeSampleArrayAllocations = 0;\nlet keyframeSampleDepth = 0;\n\nexport interface AnimationDefinitionPerformanceSnapshot {\n  readonly keyframeDefinitions: number;\n  readonly keyframeStorageArrayAllocations: number;\n  readonly keyframeSamples: number;\n  readonly keyframeSampleArrayAllocations: number;\n}\n\n/** @internal Deterministic structural counters for normalized keyframe sampling. */\nexport function animationDefinitionPerformanceSnapshot():\nAnimationDefinitionPerformanceSnapshot {\n  return Object.freeze({\n    keyframeDefinitions,\n    keyframeStorageArrayAllocations,\n    keyframeSamples,\n    keyframeSampleArrayAllocations,\n  });\n}\n\nfunction definitionLabel(debugName: string | undefined): string {\n  return debugName === undefined ? 'Pibbl animation definition' :\n    `Pibbl animation definition \"${debugName}\"`;\n}\n\nfunction assertDuration(duration: number, debugName: string | undefined): void {\n  if (!Number.isFinite(duration) || duration < 0) {\n    throw new RangeError(`${definitionLabel(debugName)} duration must be finite and nonnegative.`);\n  }\n}\n\nfunction assertFiniteNumber(value: number, message: string): void {\n  if (!Number.isFinite(value)) throw new RangeError(message);\n}\n\nconst MUTATING_MAP_METHODS = new Set<PropertyKey>(['set', 'delete', 'clear']);\nconst MUTATING_SET_METHODS = new Set<PropertyKey>(['add', 'delete', 'clear']);\nconst MUTATING_DATE_METHODS = new Set<PropertyKey>([\n  'setDate', 'setFullYear', 'setHours', 'setMilliseconds', 'setMinutes',\n  'setMonth', 'setSeconds', 'setTime', 'setUTCDate', 'setUTCFullYear',\n  'setUTCHours', 'setUTCMilliseconds', 'setUTCMinutes', 'setUTCMonth',\n  'setUTCSeconds', 'setYear',\n]);\n\nfunction immutableBuiltin<T extends object>(\n  target: T,\n  mutatingMethods: ReadonlySet<PropertyKey>,\n): T {\n  return new Proxy(target, {\n    get(current, key) {\n      if (mutatingMethods.has(key)) {\n        return (): never => {\n          throw new TypeError('Cannot mutate an animation definition snapshot.');\n        };\n      }\n      const member = Reflect.get(current, key, current);\n      return typeof member === 'function' && key !== 'constructor' ?\n        member.bind(current) : member;\n    },\n    set(): false {\n      return false;\n    },\n    defineProperty(): false {\n      return false;\n    },\n    deleteProperty(): false {\n      return false;\n    },\n  });\n}\n\nfunction rememberIdentity<T extends object>(\n  value: T,\n  seen: WeakMap<object, unknown>,\n): T {\n  seen.set(value, value);\n  return value;\n}\n\nfunction hasOwnProperties(value: object, allowed: ReadonlySet<PropertyKey>): boolean {\n  return Reflect.ownKeys(value).some(key => !allowed.has(key));\n}\n\nfunction hasOnlyDataProperties(value: object, allowed: ReadonlySet<PropertyKey>): boolean {\n  return Reflect.ownKeys(value).every(key => {\n    if (allowed.has(key)) return true;\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    return descriptor !== undefined && 'value' in descriptor;\n  });\n}\n\nconst ARRAY_OWN_KEYS = new Set<PropertyKey>(['length']);\nconst REGEXP_OWN_KEYS = new Set<PropertyKey>(['lastIndex']);\nconst snapshotsRequiringIsolation = new WeakSet<object>();\n\nfunction requiresIsolation(value: unknown): value is object {\n  return (typeof value === 'object' && value !== null || typeof value === 'function') &&\n    snapshotsRequiringIsolation.has(value as object);\n}\n\nfunction propagateIsolation(snapshot: object, value: unknown): void {\n  if (requiresIsolation(value)) snapshotsRequiringIsolation.add(snapshot);\n}\n\nfunction isArrayIndex(key: PropertyKey): boolean {\n  return typeof key === 'string' && /^(?:0|[1-9]\\d*)$/u.test(key);\n}\n\nfunction cloneTypedArray(\n  value: ArrayBufferView,\n  buffer?: ArrayBuffer,\n): ArrayBufferView {\n  if (value instanceof DataView) {\n    if (buffer !== undefined) {\n      return new DataView(buffer, value.byteOffset, value.byteLength);\n    }\n    const bytes = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);\n    return new DataView(bytes);\n  }\n  const TypedArray = value.constructor as unknown as {\n    new (source: ArrayBufferView): ArrayBufferView;\n    new (buffer: ArrayBuffer, byteOffset: number, length: number): ArrayBufferView;\n  };\n  return buffer === undefined ? new TypedArray(value) :\n    new TypedArray(\n      buffer,\n      value.byteOffset,\n      (value as ArrayBufferView & { readonly length: number }).length,\n    );\n}\n\n/**\n * Definitions retain values after their caller has moved on. The context is\n * shared across one definition so aliases and cycles remain aliases and cycles\n * in its immutable snapshot. Only categories with stable, inspectable cloning\n * semantics are copied. Reconstructable values that cannot themselves be\n * frozen are marked so only the containing paths are rematerialized before a\n * callback or terminal return. Functions, classes, accessors, and opaque host\n * values (notably WeakMap, WeakSet, Promise, and host handles) remain usable\n * identity values because cloning them can manufacture an invalid receiver or\n * change their behavior; an absolute snapshot guarantee for those values\n * requires an explicit public clone contract that Pibbl does not currently\n * provide.\n */\nfunction snapshotAnimationValue<T>(\n  value: T,\n  seen: WeakMap<object, unknown>,\n  isolateStoredValue = false,\n): T {\n  if (value === null || typeof value === 'function' || typeof value !== 'object') {\n    return value;\n  }\n  const existing = seen.get(value);\n  if (existing !== undefined) return existing as T;\n  if (isolateStoredValue && !requiresIsolation(value)) {\n    seen.set(value, value);\n    return value;\n  }\n\n  if (value instanceof Date) {\n    if (hasOwnProperties(value, new Set())) return rememberIdentity(value, seen) as T;\n    const snapshot = immutableBuiltin(new Date(value.getTime()), MUTATING_DATE_METHODS);\n    seen.set(value, snapshot);\n    return snapshot as T;\n  }\n  if (value instanceof Map) {\n    if (hasOwnProperties(value, new Set())) return rememberIdentity(value, seen) as T;\n    const target = new Map();\n    const snapshot = immutableBuiltin(target, MUTATING_MAP_METHODS);\n    seen.set(value, snapshot);\n    for (const [key, entry] of value) {\n      const keySnapshot = snapshotAnimationValue(key, seen, isolateStoredValue);\n      const entrySnapshot = snapshotAnimationValue(entry, seen, isolateStoredValue);\n      target.set(keySnapshot, entrySnapshot);\n      propagateIsolation(snapshot, keySnapshot);\n      propagateIsolation(snapshot, entrySnapshot);\n    }\n    return snapshot as T;\n  }\n  if (value instanceof Set) {\n    if (hasOwnProperties(value, new Set())) return rememberIdentity(value, seen) as T;\n    const target = new Set();\n    const snapshot = immutableBuiltin(target, MUTATING_SET_METHODS);\n    seen.set(value, snapshot);\n    for (const entry of value) {\n      const entrySnapshot = snapshotAnimationValue(entry, seen, isolateStoredValue);\n      target.add(entrySnapshot);\n      propagateIsolation(snapshot, entrySnapshot);\n    }\n    return snapshot as T;\n  }\n  if (Array.isArray(value)) {\n    const ownKeys = Reflect.ownKeys(value);\n    if (Object.getPrototypeOf(value) !== Array.prototype ||\n      ownKeys.some(key => !ARRAY_OWN_KEYS.has(key) && !isArrayIndex(key)) ||\n      !hasOnlyDataProperties(value, ARRAY_OWN_KEYS)) {\n      return rememberIdentity(value, seen) as T;\n    }\n    const snapshot: unknown[] = new Array(value.length);\n    if (keyframeSampleDepth > 0) keyframeSampleArrayAllocations++;\n    seen.set(value, snapshot);\n    for (const key of ownKeys) {\n      if (ARRAY_OWN_KEYS.has(key)) continue;\n      const descriptor = Object.getOwnPropertyDescriptor(value, key);\n      if (descriptor === undefined || !('value' in descriptor)) continue;\n      const itemSnapshot = snapshotAnimationValue(\n        descriptor.value,\n        seen,\n        isolateStoredValue,\n      );\n      Object.defineProperty(snapshot, key, {\n        configurable: false,\n        enumerable: descriptor.enumerable,\n        writable: false,\n        value: itemSnapshot,\n      });\n      propagateIsolation(snapshot, itemSnapshot);\n    }\n    return Object.freeze(snapshot) as T;\n  }\n\n  if (value instanceof RegExp) {\n    if (hasOwnProperties(value, REGEXP_OWN_KEYS)) return rememberIdentity(value, seen) as T;\n    const snapshot = new RegExp(value.source, value.flags);\n    snapshot.lastIndex = value.lastIndex;\n    seen.set(value, snapshot);\n    snapshotsRequiringIsolation.add(snapshot);\n    return snapshot as T;\n  }\n\n  if (ArrayBuffer.isView(value)) {\n    const ownKeys = Reflect.ownKeys(value);\n    if (ownKeys.some(key => !isArrayIndex(key))) return rememberIdentity(value, seen) as T;\n    const buffer = value.buffer instanceof ArrayBuffer ?\n      snapshotAnimationValue(value.buffer, seen, isolateStoredValue) : undefined;\n    const snapshot = cloneTypedArray(value, buffer);\n    seen.set(value, snapshot);\n    snapshotsRequiringIsolation.add(snapshot);\n    return snapshot as T;\n  }\n\n  if (value instanceof ArrayBuffer) {\n    const snapshot = value.slice(0);\n    seen.set(value, snapshot);\n    snapshotsRequiringIsolation.add(snapshot);\n    return snapshot as T;\n  }\n\n  const prototype = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null ||\n    !hasOnlyDataProperties(value, new Set())) {\n    return rememberIdentity(value, seen) as T;\n  }\n  const snapshot = Object.create(prototype) as Record<PropertyKey, unknown>;\n  seen.set(value, snapshot);\n  for (const key of Reflect.ownKeys(value)) {\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    if (descriptor === undefined) continue;\n    const propertySnapshot = snapshotAnimationValue(\n      descriptor.value,\n      seen,\n      isolateStoredValue,\n    );\n    Object.defineProperty(snapshot, key, {\n      configurable: false,\n      enumerable: descriptor.enumerable,\n      writable: false,\n      value: propertySnapshot,\n    });\n    propagateIsolation(snapshot, propertySnapshot);\n  }\n  return Object.freeze(snapshot) as T;\n}\n\nfunction isolateStoredAnimationValue<T>(\n  value: T,\n  seen: WeakMap<object, unknown>,\n): T {\n  return snapshotAnimationValue(value, seen, true);\n}\n\n/** @internal Captures a committed output value for a playback activation. */\nexport function snapshotAnimationActivationValue<T>(\n  value: T,\n  seen: WeakMap<object, unknown> = new WeakMap(),\n): T {\n  return snapshotAnimationValue(value, seen);\n}\n\nfunction validateSampledValue<T>(sampled: T, debugName: string | undefined): T {\n  if (typeof sampled === 'number' && !Number.isFinite(sampled)) {\n    throw new RangeError(`${definitionLabel(debugName)} sampled value must be finite.`);\n  }\n  return sampled;\n}\n\nfunction createDefinition<T>(record: DefinitionRecord<T>): PibblAnimationDefinition<T> {\n  const definition = Object.freeze({}) as PibblAnimationDefinition<T>;\n  definitionRecords.set(\n    definition as PibblAnimationDefinition<unknown>,\n    Object.freeze(record) as DefinitionRecord<unknown>,\n  );\n  return definition;\n}\n\nfunction hasOwn(object: object, key: PropertyKey): boolean {\n  return Object.prototype.hasOwnProperty.call(object, key);\n}\n\nfunction callback<T>(\n  debugName: string | undefined,\n  callback: () => T,\n): T {\n  return withSignalWriteForbidden(\n    `${definitionLabel(debugName)} callbacks cannot write to signals.`,\n    callback,\n  );\n}\n\nfunction sampledProgress(duration: number, localTime: number): {\n  readonly localTime: number;\n  readonly progress: number;\n} {\n  assertFiniteNumber(localTime, 'Pibbl animation sample localTime must be finite.');\n  if (duration === 0) return Object.freeze({ localTime: 0, progress: 1 });\n  const normalizedLocalTime = Math.min(duration, Math.max(0, localTime));\n  return Object.freeze({\n    localTime: normalizedLocalTime,\n    progress: normalizedLocalTime / duration,\n  });\n}\n\nfunction interpolate<T>(\n  from: T,\n  to: T,\n  progress: number,\n  custom: PibblInterpolator<T> | undefined,\n  debugName: string | undefined,\n): T {\n  if (custom === undefined && (typeof from !== 'number' || typeof to !== 'number')) {\n    throw new TypeError(`${definitionLabel(debugName)} requires an explicit interpolator for nonnumeric values.`);\n  }\n  let sampled: T;\n  if (custom === undefined) {\n    sampled = ((from as unknown as number) +\n      ((to as unknown as number) - (from as unknown as number)) * progress) as T;\n  } else {\n    const isolated = new WeakMap<object, unknown>();\n    const isolatedFrom = isolateStoredAnimationValue(from, isolated);\n    const isolatedTo = isolateStoredAnimationValue(to, isolated);\n    sampled = callback(debugName, () => custom(isolatedFrom, isolatedTo, progress));\n  }\n  return validateSampledValue(sampled, debugName);\n}\n\nfunction easedProgress(\n  ease: PibblEasing,\n  progress: number,\n  debugName: string | undefined,\n): number {\n  const eased = callback(debugName, () => ease(progress));\n  if (!Number.isFinite(eased)) {\n    throw new RangeError(`${definitionLabel(debugName)} easing result must be finite.`);\n  }\n  return eased;\n}\n\nfunction normalizeOffsets(\n  values: readonly unknown[],\n  offsets: readonly number[] | undefined,\n  debugName: string | undefined,\n): readonly number[] {\n  if (offsets === undefined) {\n    return Object.freeze(values.map((_, index) => index / (values.length - 1)));\n  }\n  if (offsets.length !== values.length) {\n    throw new RangeError(`${definitionLabel(debugName)} keyframe offsets must match the values length.`);\n  }\n  const snapshot = [...offsets];\n  for (const offset of snapshot) {\n    if (!Number.isFinite(offset) || offset < 0 || offset > 1) {\n      throw new RangeError(`${definitionLabel(debugName)} keyframe offsets must be finite values within [0, 1].`);\n    }\n  }\n  if (snapshot[0] !== 0) {\n    throw new RangeError(`${definitionLabel(debugName)} keyframe offsets must start at 0.`);\n  }\n  if (snapshot.at(-1) !== 1) {\n    throw new RangeError(`${definitionLabel(debugName)} keyframe offsets must end at 1.`);\n  }\n  for (let index = 1; index < snapshot.length; index++) {\n    if (snapshot[index] < snapshot[index - 1]) {\n      throw new RangeError(`${definitionLabel(debugName)} keyframe offsets must be nondecreasing.`);\n    }\n  }\n  return Object.freeze(snapshot);\n}\n\nfunction normalizeEasings(\n  easingOption: PibblEasing | readonly PibblEasing[] | undefined,\n  segmentCount: number,\n  debugName: string | undefined,\n): readonly PibblEasing[] {\n  if (Array.isArray(easingOption)) {\n    if (easingOption.length !== segmentCount) {\n      throw new RangeError(`${definitionLabel(debugName)} keyframe easing list must have one entry per segment.`);\n    }\n    if (easingOption.some(ease => typeof ease !== 'function')) {\n      throw new TypeError(`${definitionLabel(debugName)} keyframe easings must be functions.`);\n    }\n    return Object.freeze([...easingOption]);\n  }\n  const ease = easingOption ?? easing.linear;\n  if (typeof ease !== 'function') {\n    throw new TypeError(`${definitionLabel(debugName)} easing must be a function.`);\n  }\n  return Object.freeze(Array.from({ length: segmentCount }, () => ease));\n}\n\n/**\n * Returns an opaque immutable tween definition.\n *\n * @param options - Start and end values, duration, easing, and interpolation settings. See\n * {@link PibblTweenOptions} .\n * @returns An immutable tween definition. See {@link PibblAnimationDefinition}.\n *\n * @see {@link PibblTweenOptions}\n * @see {@link PibblAnimationDefinition}\n */\nexport function tween<T>(options: Readonly<PibblTweenOptions<T>>): PibblAnimationDefinition<T> {\n  assertDuration(options.duration, options.debugName);\n  if (typeof options.easing !== 'undefined' && typeof options.easing !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} easing must be a function.`);\n  }\n  if (typeof options.interpolate !== 'undefined' && typeof options.interpolate !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} interpolator must be a function.`);\n  }\n  const hasFrom = hasOwn(options, 'from');\n  const snapshots = new WeakMap<object, unknown>();\n  return createDefinition({\n    kind: 'tween',\n    duration: options.duration,\n    debugName: options.debugName,\n    hasFrom,\n    from: hasFrom ? snapshotAnimationValue(options.from as T, snapshots) : undefined,\n    to: snapshotAnimationValue(options.to, snapshots),\n    easing: options.easing ?? easing.linear,\n    interpolate: options.interpolate,\n  });\n}\n\n/**\n * Returns an opaque immutable keyframe definition.\n *\n * @param options - Keyframe values, timing, easing, and interpolation settings. See\n * {@link PibblKeyframesOptions} .\n * @returns An immutable animation definition sampling the keyframes. See\n * {@link PibblAnimationDefinition} .\n *\n * @see {@link PibblKeyframesOptions}\n * @see {@link PibblAnimationDefinition}\n */\nexport function keyframes<T>(\n  options: Readonly<PibblKeyframesOptions<T>>,\n): PibblAnimationDefinition<T> {\n  assertDuration(options.duration, options.debugName);\n  if (options.values.length < 2) {\n    throw new RangeError(`${definitionLabel(options.debugName)} keyframes require at least two values.`);\n  }\n  if (typeof options.interpolate !== 'undefined' && typeof options.interpolate !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} interpolator must be a function.`);\n  }\n  const snapshots = new WeakMap<object, unknown>();\n  const values = Object.freeze(options.values.map(value => snapshotAnimationValue(value, snapshots)));\n  const offsets = normalizeOffsets(values, options.offsets, options.debugName);\n  const easings = normalizeEasings(options.easing, values.length - 1, options.debugName);\n  keyframeDefinitions++;\n  keyframeStorageArrayAllocations += 3;\n  return createDefinition({\n    kind: 'keyframes',\n    duration: options.duration,\n    debugName: options.debugName,\n    values,\n    offsets,\n    easings,\n    interpolate: options.interpolate,\n  });\n}\n\n/**\n * Returns an opaque immutable analytic one-dimensional spring definition.\n *\n * @param options - Target, initial conditions, and spring parameters. See {@link PibblSpringOptions}\n * .\n * @returns An analytic numeric spring definition. See {@link PibblAnimationDefinition}.\n *\n * @see {@link PibblSpringOptions}\n * @see {@link PibblAnimationDefinition}\n */\nexport function spring(\n  options: Readonly<PibblSpringOptions>,\n): PibblAnimationDefinition<number> {\n  return createDefinition(createSpringRecord(options));\n}\n\n/**\n * Returns an opaque immutable definition from a custom seekable sampler.\n *\n * @param options - Duration and pure sampling callback for the animation. See\n * {@link PibblAnimationOptions} .\n * @returns An immutable, seekable animation definition. See {@link PibblAnimationDefinition}.\n *\n * @see {@link PibblAnimationOptions}\n * @see {@link PibblAnimationDefinition}\n */\nexport function defineAnimation<T>(\n  options: Readonly<PibblAnimationOptions<T>>,\n): PibblAnimationDefinition<T> {\n  assertDuration(options.duration, options.debugName);\n  if (typeof options.sample !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} sample must be a function.`);\n  }\n  return createDefinition({\n    kind: 'custom',\n    duration: options.duration,\n    debugName: options.debugName,\n    sample: options.sample,\n  });\n}\n\n/**\n * Returns an opaque immutable stepper definition. Steppers are evaluated by\n * the playback engine, not by the seekable sampler.\n *\n * @param options - Initial state, fixed-step integration, value reader, and completion predicate.\n * See {@link PibblStepperOptions} .\n * @returns A stateful animation definition advanced by fixed simulation steps. See\n * {@link PibblAnimationDefinition} .\n *\n * @see {@link PibblStepperOptions}\n * @see {@link PibblAnimationDefinition}\n */\nexport function stepper<State, T>(\n  options: Readonly<PibblStepperOptions<State, T>>,\n): PibblAnimationDefinition<T> {\n  if (typeof options.initial !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} stepper initial must be a function.`);\n  }\n  if (typeof options.step !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} stepper step must be a function.`);\n  }\n  if (typeof options.read !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} stepper read must be a function.`);\n  }\n  if (typeof options.done !== 'undefined' && typeof options.done !== 'function') {\n    throw new TypeError(`${definitionLabel(options.debugName)} stepper done must be a function.`);\n  }\n  if (!Number.isFinite(options.stepMilliseconds) || options.stepMilliseconds <= 0) {\n    throw new RangeError(`${definitionLabel(options.debugName)} stepper stepMilliseconds must be finite and positive.`);\n  }\n  const maxElapsedMilliseconds = options.maxElapsedMilliseconds ?? 100;\n  if (!Number.isFinite(maxElapsedMilliseconds) || maxElapsedMilliseconds <= 0) {\n    throw new RangeError(`${definitionLabel(options.debugName)} stepper maxElapsedMilliseconds must be finite and positive.`);\n  }\n  return createDefinition({\n    kind: 'stepper',\n    duration: Number.POSITIVE_INFINITY,\n    debugName: options.debugName,\n    stepMilliseconds: options.stepMilliseconds,\n    maxElapsedMilliseconds,\n    initial: options.initial as (currentValue: T) => unknown,\n    step: options.step as (state: unknown, deltaMilliseconds: number) => unknown,\n    read: options.read as (state: unknown) => T,\n    done: options.done as ((state: unknown) => boolean) | undefined,\n  });\n}\n\n/** @internal Returns the private immutable record associated with a definition. */\nexport function getDefinitionRecord<T>(\n  definition: PibblAnimationDefinition<T>,\n): DefinitionRecord<T> {\n  const record = definitionRecords.get(definition as PibblAnimationDefinition<unknown>);\n  if (record === undefined) throw new TypeError('Expected a Pibbl animation definition.');\n  return record as DefinitionRecord<T>;\n}\n\n/** @internal Samples a non-stepper definition from its activation snapshot. */\nexport function sampleSeekableDefinition<T>(\n  definition: PibblAnimationDefinition<T>,\n  input: Readonly<Pick<PibblAnimationSampleInput<T>, 'initialValue' | 'localTime'>>,\n): T {\n  const record = getDefinitionRecord(definition);\n  if (record.kind === 'stepper') {\n    throw new TypeError(\n      `${definitionLabel(record.debugName)} is stateful and requires the stateful program evaluator.`,\n    );\n  }\n  if (record.kind === 'spring') {\n    const resolved = resolveSpringStart(record, input.initialValue as number);\n    const timing = sampledProgress(resolved.duration, input.localTime);\n    return sampleSpring(resolved, timing.localTime / 1000).position as T;\n  }\n  const timing = sampledProgress(record.duration, input.localTime);\n  if (record.kind === 'custom') {\n    const sampled = callback(record.debugName, () => record.sample(Object.freeze({\n      initialValue: input.initialValue,\n      localTime: timing.localTime,\n      progress: timing.progress,\n    })));\n    return validateSampledValue(sampled, record.debugName);\n  }\n  if (record.kind === 'tween') {\n    const from = record.hasFrom ? record.from as T : input.initialValue;\n    return interpolate(\n      from,\n      record.to,\n      easedProgress(record.easing, timing.progress, record.debugName),\n      record.interpolate,\n      record.debugName,\n    );\n  }\n\n  keyframeSamples++;\n  keyframeSampleDepth++;\n  try {\n    return sampleKeyframe(record, timing);\n  } finally {\n    keyframeSampleDepth--;\n  }\n}\n\nfunction sampleKeyframe<T>(\n  record: KeyframesDefinitionRecord<T>,\n  timing: { readonly progress: number },\n): T {\n  let segment = 0;\n  for (let index = 1; index < record.offsets.length; index++) {\n    if (record.offsets[index] <= timing.progress) segment = index;\n    else break;\n  }\n  if (segment === record.values.length - 1) {\n    return validateSampledValue(\n      isolateStoredAnimationValue(record.values[segment], new WeakMap()),\n      record.debugName,\n    );\n  }\n  const start = record.offsets[segment];\n  const end = record.offsets[segment + 1];\n  return interpolate(\n    record.values[segment],\n    record.values[segment + 1],\n    easedProgress(record.easings[segment], (timing.progress - start) / (end - start), record.debugName),\n    record.interpolate,\n    record.debugName,\n  );\n}\n\n/**\n * @internal Resolves activation-dependent definition data exactly once for a\n * track instance. Stateful definitions use a separate playback-owned record.\n */\nexport function activateSeekableDefinition<T>(\n  definition: PibblAnimationDefinition<T>,\n  initialValue: T,\n  seen: WeakMap<object, unknown> = new WeakMap(),\n): SeekableDefinitionActivation<T> {\n  const definitionRecord = getDefinitionRecord(definition);\n  if (definitionRecord.kind === 'stepper') {\n    throw new TypeError(\n      'Stateful animation definitions require the stateful program evaluator.',\n    );\n  }\n  const snapshot = snapshotAnimationActivationValue(initialValue, seen);\n  const resolved = definitionRecord.kind === 'spring' ?\n    resolveSpringStart(definitionRecord, snapshot as number) : definitionRecord;\n  const activation = Object.freeze({\n    duration: resolved.duration,\n    initialValue: snapshot,\n  }) as SeekableDefinitionActivation<T>;\n  seekableActivationRecords.set(\n    activation as SeekableDefinitionActivation<unknown>,\n    Object.freeze({\n      definition,\n      definitionRecord: resolved,\n      initialValue: snapshot,\n    }) as SeekableDefinitionActivationRecord<unknown>,\n  );\n  return activation;\n}\n\n/** @internal Samples a definition from one retained activation record. */\nexport function sampleActivatedSeekableDefinition<T>(\n  activation: SeekableDefinitionActivation<T>,\n  localTime: number,\n): T {\n  const activationRecord = seekableActivationRecords.get(\n    activation as SeekableDefinitionActivation<unknown>,\n  ) as SeekableDefinitionActivationRecord<T> | undefined;\n  if (activationRecord === undefined) {\n    throw new TypeError('Expected a seekable Pibbl animation definition activation.');\n  }\n  const record = activationRecord.definitionRecord;\n  if (record.kind === 'spring') {\n    const timing = sampledProgress(record.duration, localTime);\n    return sampleSpring(record, timing.localTime / 1000).position as T;\n  }\n  return sampleSeekableDefinition(activationRecord.definition, {\n    initialValue: activationRecord.initialValue,\n    localTime,\n  });\n}\n\n/**\n * @internal Returns a boundary value only when the normalized definition makes\n * it exact without invoking user easing, interpolation, or sampling callbacks.\n */\nexport function getSeekableDefinitionBoundaryValue<T>(\n  activation: SeekableDefinitionActivation<T>,\n  boundary: 'start' | 'end',\n): SeekableDefinitionBoundaryValue<T> {\n  const activationRecord = seekableActivationRecords.get(\n    activation as SeekableDefinitionActivation<unknown>,\n  ) as SeekableDefinitionActivationRecord<T> | undefined;\n  if (activationRecord === undefined) {\n    throw new TypeError('Expected a seekable Pibbl animation definition activation.');\n  }\n  const record = activationRecord.definitionRecord;\n  if (record.kind === 'spring') {\n    return Object.freeze({\n      kind: 'known' as const,\n      value: (boundary === 'start' ? record.from : record.to) as T,\n    });\n  }\n  if (record.kind === 'keyframes') {\n    if (boundary === 'end') {\n      return Object.freeze({ kind: 'known' as const, value: record.values.at(-1)! });\n    }\n    if (record.interpolate === undefined && record.easings[0] === easing.linear) {\n      return Object.freeze({ kind: 'known' as const, value: record.values[0]! });\n    }\n    return Object.freeze({ kind: 'unknown' as const });\n  }\n  if (record.kind === 'tween' && record.interpolate === undefined &&\n    record.easing === easing.linear) {\n    return Object.freeze({\n      kind: 'known' as const,\n      value: boundary === 'start' ?\n        (record.hasFrom ? record.from as T : activationRecord.initialValue) : record.to,\n    });\n  }\n  return Object.freeze({ kind: 'unknown' as const });\n}\n\n/**\n * @internal Returns a callback-free boundary that does not depend on a track's\n * activation value. This lets discovery recover known terminal state after an\n * earlier opaque custom value.\n */\nexport function getStaticSeekableDefinitionBoundaryValue<T>(\n  definition: PibblAnimationDefinition<T>,\n  boundary: 'start' | 'end',\n): SeekableDefinitionBoundaryValue<T> {\n  const record = getDefinitionRecord(definition);\n  if (record.kind === 'spring' && record.hasFrom) {\n    return Object.freeze({\n      kind: 'known' as const,\n      value: (boundary === 'start' ? record.from : record.to) as T,\n    });\n  }\n  if (record.kind === 'keyframes') {\n    if (boundary === 'end') {\n      return Object.freeze({ kind: 'known' as const, value: record.values.at(-1)! });\n    }\n    if (record.interpolate === undefined && record.easings[0] === easing.linear) {\n      return Object.freeze({ kind: 'known' as const, value: record.values[0]! });\n    }\n  }\n  if (record.kind === 'tween' && record.interpolate === undefined &&\n    record.easing === easing.linear) {\n    if (boundary === 'end') {\n      return Object.freeze({ kind: 'known' as const, value: record.to });\n    }\n    if (record.hasFrom) {\n      return Object.freeze({ kind: 'known' as const, value: record.from as T });\n    }\n  }\n  return Object.freeze({ kind: 'unknown' as const });\n}\n"],
+  "mappings": "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",
+  "names": ["snapshot", "callback", "ease", "timing"]
+}

package/dist/lib/animation/easing.d.ts

@@ -0,0 +1,55 @@
+import type { tween } from "./definition.js";
+import type { PibblEasing } from './types.js';
+declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): PibblEasing;
+declare function steps(count: number, position?: 'start' | 'end'): PibblEasing;
+/**
+ * Built-in easing functions for mapping normalized animation progress.
+ *
+ * @see {@link PibblEasing}
+ * @see {@link tween}
+ */
+export declare const easing: Readonly<{
+    /**
+     * Returns clamped progress unchanged. See {@link PibblEasing}.
+     * @param progress - Input progress, clamped to the interval [0, 1].
+     * @returns The clamped progress.
+     */
+    linear: (progress: number) => number;
+    /**
+     * Creates a cubic Bézier easing; control-point x coordinates must be finite and within [0, 1].
+     * See {@link PibblEasing}.
+     * @param x1 - First control point horizontal coordinate, in [0, 1].
+     * @param y1 - Finite first control point vertical coordinate.
+     * @param x2 - Second control point horizontal coordinate, in [0, 1].
+     * @param y2 - Finite second control point vertical coordinate.
+     * @returns A cubic Bézier easing function. See {@link PibblEasing}.
+     */
+    cubicBezier: typeof cubicBezier;
+    /**
+     * Accelerates from rest using the CSS ease-in control points. See {@link easing}.
+     * @param progress - Input progress, clamped to [0, 1].
+     * @returns Eased progress. See {@link PibblEasing}.
+     */
+    easeIn: PibblEasing;
+    /**
+     * Decelerates toward rest using the CSS ease-out control points. See {@link easing}.
+     * @param progress - Input progress, clamped to [0, 1].
+     * @returns Eased progress. See {@link PibblEasing}.
+     */
+    easeOut: PibblEasing;
+    /**
+     * Accelerates then decelerates using the CSS ease-in-out control points. See {@link easing}.
+     * @param progress - Input progress, clamped to [0, 1].
+     * @returns Eased progress. See {@link PibblEasing}.
+     */
+    easeInOut: PibblEasing;
+    /**
+     * Creates a stepped easing with a positive integer count and start or end jump placement. See
+     * {@link easing}.
+     * @param count - Positive integer number of steps.
+     * @param position - Whether jumps occur at the start or end of each interval; defaults to end.
+     * @returns A stepped easing function. See {@link PibblEasing}.
+     */
+    steps: typeof steps;
+}>;
+export {};

package/dist/lib/animation/easing.js

@@ -0,0 +1,112 @@
+const NEWTON_ITERATIONS = 8;
+const BISECTION_ITERATIONS = 50;
+function clampProgress(progress) {
+  return Math.min(1, Math.max(0, progress));
+}
+function assertFiniteControl(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`Pibbl cubic bezier ${name} must be finite.`);
+  }
+}
+function sampleCurve(t, first, second) {
+  const inverse = 1 - t;
+  return 3 * inverse * inverse * t * first + 3 * inverse * t * t * second + t * t * t;
+}
+function sampleDerivative(t, first, second) {
+  const inverse = 1 - t;
+  return 3 * inverse * inverse * first + 6 * inverse * t * (second - first) + 3 * t * t * (1 - second);
+}
+function cubicBezier(x1, y1, x2, y2) {
+  assertFiniteControl(x1, "x1");
+  assertFiniteControl(y1, "y1");
+  assertFiniteControl(x2, "x2");
+  assertFiniteControl(y2, "y2");
+  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {
+    throw new RangeError("Pibbl cubic bezier x1 and x2 must be within [0, 1].");
+  }
+  return (input) => {
+    const progress = clampProgress(input);
+    if (progress === 0 || progress === 1) return progress;
+    let parameter = progress;
+    for (let iteration = 0; iteration < NEWTON_ITERATIONS; iteration++) {
+      const x = sampleCurve(parameter, x1, x2) - progress;
+      const slope = sampleDerivative(parameter, x1, x2);
+      if (Math.abs(slope) < 1e-7) break;
+      const candidate = parameter - x / slope;
+      if (candidate < 0 || candidate > 1) break;
+      parameter = candidate;
+    }
+    let lower = 0;
+    let upper = 1;
+    for (let iteration = 0; iteration < BISECTION_ITERATIONS; iteration++) {
+      const x = sampleCurve(parameter, x1, x2);
+      if (x < progress) lower = parameter;
+      else upper = parameter;
+      parameter = (lower + upper) / 2;
+    }
+    return sampleCurve(parameter, y1, y2);
+  };
+}
+function steps(count, position = "end") {
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new RangeError("Pibbl steps count must be a positive integer.");
+  }
+  if (position !== "start" && position !== "end") {
+    throw new TypeError('Pibbl steps position must be "start" or "end".');
+  }
+  return (input) => {
+    const progress = clampProgress(input);
+    if (position === "start") {
+      return Math.min(1, (Math.floor(progress * count) + 1) / count);
+    }
+    return progress === 1 ? 1 : Math.floor(progress * count) / count;
+  };
+}
+const easing = Object.freeze({
+  /**
+   * Returns clamped progress unchanged. See {@link PibblEasing}.
+   * @param progress - Input progress, clamped to the interval [0, 1].
+   * @returns The clamped progress.
+   */
+  linear: (progress) => clampProgress(progress),
+  /**
+   * Creates a cubic Bézier easing; control-point x coordinates must be finite and within [0, 1].
+   * See {@link PibblEasing}.
+   * @param x1 - First control point horizontal coordinate, in [0, 1].
+   * @param y1 - Finite first control point vertical coordinate.
+   * @param x2 - Second control point horizontal coordinate, in [0, 1].
+   * @param y2 - Finite second control point vertical coordinate.
+   * @returns A cubic Bézier easing function. See {@link PibblEasing}.
+   */
+  cubicBezier,
+  /**
+   * Accelerates from rest using the CSS ease-in control points. See {@link easing}.
+   * @param progress - Input progress, clamped to [0, 1].
+   * @returns Eased progress. See {@link PibblEasing}.
+   */
+  easeIn: cubicBezier(0.42, 0, 1, 1),
+  /**
+   * Decelerates toward rest using the CSS ease-out control points. See {@link easing}.
+   * @param progress - Input progress, clamped to [0, 1].
+   * @returns Eased progress. See {@link PibblEasing}.
+   */
+  easeOut: cubicBezier(0, 0, 0.58, 1),
+  /**
+   * Accelerates then decelerates using the CSS ease-in-out control points. See {@link easing}.
+   * @param progress - Input progress, clamped to [0, 1].
+   * @returns Eased progress. See {@link PibblEasing}.
+   */
+  easeInOut: cubicBezier(0.42, 0, 0.58, 1),
+  /**
+   * Creates a stepped easing with a positive integer count and start or end jump placement. See
+   * {@link easing}.
+   * @param count - Positive integer number of steps.
+   * @param position - Whether jumps occur at the start or end of each interval; defaults to end.
+   * @returns A stepped easing function. See {@link PibblEasing}.
+   */
+  steps
+});
+export {
+  easing
+};
+//# sourceMappingURL=easing.js.map

package/dist/lib/animation/easing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/animation/easing.ts"],
+  "sourcesContent": ["import type { tween } from './definition.js';\nimport type { PibblEasing } from './types.js';\n\nconst NEWTON_ITERATIONS = 8;\nconst BISECTION_ITERATIONS = 50;\n\nfunction clampProgress(progress: number): number {\n  return Math.min(1, Math.max(0, progress));\n}\n\nfunction assertFiniteControl(value: number, name: string): void {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`Pibbl cubic bezier ${name} must be finite.`);\n  }\n}\n\nfunction sampleCurve(t: number, first: number, second: number): number {\n  const inverse = 1 - t;\n  return 3 * inverse * inverse * t * first +\n    3 * inverse * t * t * second +\n    t * t * t;\n}\n\nfunction sampleDerivative(t: number, first: number, second: number): number {\n  const inverse = 1 - t;\n  return 3 * inverse * inverse * first +\n    6 * inverse * t * (second - first) +\n    3 * t * t * (1 - second);\n}\n\nfunction cubicBezier(\n  x1: number,\n  y1: number,\n  x2: number,\n  y2: number,\n): PibblEasing {\n  assertFiniteControl(x1, 'x1');\n  assertFiniteControl(y1, 'y1');\n  assertFiniteControl(x2, 'x2');\n  assertFiniteControl(y2, 'y2');\n  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {\n    throw new RangeError('Pibbl cubic bezier x1 and x2 must be within [0, 1].');\n  }\n\n  return (input: number): number => {\n    const progress = clampProgress(input);\n    if (progress === 0 || progress === 1) return progress;\n\n    let parameter = progress;\n    for (let iteration = 0; iteration < NEWTON_ITERATIONS; iteration++) {\n      const x = sampleCurve(parameter, x1, x2) - progress;\n      const slope = sampleDerivative(parameter, x1, x2);\n      if (Math.abs(slope) < 1e-7) break;\n      const candidate = parameter - x / slope;\n      if (candidate < 0 || candidate > 1) break;\n      parameter = candidate;\n    }\n\n    let lower = 0;\n    let upper = 1;\n    for (let iteration = 0; iteration < BISECTION_ITERATIONS; iteration++) {\n      const x = sampleCurve(parameter, x1, x2);\n      if (x < progress) lower = parameter;\n      else upper = parameter;\n      parameter = (lower + upper) / 2;\n    }\n    return sampleCurve(parameter, y1, y2);\n  };\n}\n\nfunction steps(count: number, position: 'start' | 'end' = 'end'): PibblEasing {\n  if (!Number.isInteger(count) || count <= 0) {\n    throw new RangeError('Pibbl steps count must be a positive integer.');\n  }\n  if (position !== 'start' && position !== 'end') {\n    throw new TypeError('Pibbl steps position must be \"start\" or \"end\".');\n  }\n\n  return (input: number): number => {\n    const progress = clampProgress(input);\n    if (position === 'start') {\n      return Math.min(1, (Math.floor(progress * count) + 1) / count);\n    }\n    return progress === 1 ? 1 : Math.floor(progress * count) / count;\n  };\n}\n\n/**\n * Built-in easing functions for mapping normalized animation progress.\n *\n * @see {@link PibblEasing}\n * @see {@link tween}\n */\nexport const easing = Object.freeze({\n  /**\n   * Returns clamped progress unchanged. See {@link PibblEasing}.\n   * @param progress - Input progress, clamped to the interval [0, 1].\n   * @returns The clamped progress.\n   */\n  linear: (progress: number): number => clampProgress(progress),\n  /**\n   * Creates a cubic B\u00E9zier easing; control-point x coordinates must be finite and within [0, 1].\n   * See {@link PibblEasing}.\n   * @param x1 - First control point horizontal coordinate, in [0, 1].\n   * @param y1 - Finite first control point vertical coordinate.\n   * @param x2 - Second control point horizontal coordinate, in [0, 1].\n   * @param y2 - Finite second control point vertical coordinate.\n   * @returns A cubic B\u00E9zier easing function. See {@link PibblEasing}.\n   */\n  cubicBezier,\n  /**\n   * Accelerates from rest using the CSS ease-in control points. See {@link easing}.\n   * @param progress - Input progress, clamped to [0, 1].\n   * @returns Eased progress. See {@link PibblEasing}.\n   */\n  easeIn: cubicBezier(0.42, 0, 1, 1),\n  /**\n   * Decelerates toward rest using the CSS ease-out control points. See {@link easing}.\n   * @param progress - Input progress, clamped to [0, 1].\n   * @returns Eased progress. See {@link PibblEasing}.\n   */\n  easeOut: cubicBezier(0, 0, 0.58, 1),\n  /**\n   * Accelerates then decelerates using the CSS ease-in-out control points. See {@link easing}.\n   * @param progress - Input progress, clamped to [0, 1].\n   * @returns Eased progress. See {@link PibblEasing}.\n   */\n  easeInOut: cubicBezier(0.42, 0, 0.58, 1),\n  /**\n   * Creates a stepped easing with a positive integer count and start or end jump placement. See\n   * {@link easing}.\n   * @param count - Positive integer number of steps.\n   * @param position - Whether jumps occur at the start or end of each interval; defaults to end.\n   * @returns A stepped easing function. See {@link PibblEasing}.\n   */\n  steps,\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/animation/evaluate.d.ts

@@ -0,0 +1,118 @@
+import { type SignalCommitBatch } from '../signals/graph.js';
+import type { WritableSignal } from '../signals/types.js';
+import type { PibblAnimationProgram } from './types.js';
+declare const programActivationBrand: unique symbol;
+/** @internal Opaque state retained for one activated program run. */
+export interface ProgramActivation {
+    readonly [programActivationBrand]: true;
+}
+export type ProgramTraversalDirection = 'forward' | 'reverse';
+export interface ProgramEvaluationInput {
+    readonly previousTime: number | undefined;
+    readonly time: number;
+    readonly direction: ProgramTraversalDirection;
+    readonly frameId: number;
+    readonly writer: object;
+    readonly batch: SignalCommitBatch;
+}
+interface ProgramMilestoneBase {
+    readonly programTime: number;
+    readonly frameId: number;
+    readonly registration: object;
+    readonly programPath: readonly number[];
+    readonly iteration: number;
+}
+export interface ProgramMarkerMilestone extends ProgramMilestoneBase {
+    readonly kind: 'marker';
+    readonly marker: string;
+}
+export interface ProgramIterationMilestone extends ProgramMilestoneBase {
+    readonly kind: 'iteration';
+}
+export type ProgramMilestone = ProgramMarkerMilestone | ProgramIterationMilestone;
+export interface ProgramTerminalState {
+    readonly duration: number | undefined;
+    readonly atStart: boolean;
+    readonly atEnd: boolean;
+    readonly reached: boolean;
+}
+export interface ProgramEvaluationResult {
+    readonly batch: SignalCommitBatch;
+    readonly milestones: readonly ProgramMilestone[];
+    readonly steppers: readonly ProgramStepperTrace[];
+    readonly terminal: ProgramTerminalState;
+}
+/** @internal Immutable fixed-step facts emitted without application callbacks. */
+export interface ProgramStepperTrace {
+    readonly programPath: readonly number[];
+    readonly repeatIterations: readonly number[];
+    readonly appliedSteps: number;
+    readonly retainedRemainderMilliseconds: number;
+    readonly clampedElapsedMilliseconds: number;
+    readonly discardedElapsedMilliseconds: number;
+    readonly terminal: {
+        readonly step: number;
+        readonly time: number;
+    } | undefined;
+}
+export interface TrackStartSnapshot {
+    readonly programPath: readonly number[];
+    readonly repeatIterations: readonly number[];
+    readonly initialValue: unknown;
+    readonly duration: number;
+}
+export interface ActiveStepperSnapshot {
+    readonly programPath: readonly number[];
+    readonly repeatIterations: readonly number[];
+    readonly wholeSteps: number;
+    readonly retainedRemainderMilliseconds: number;
+    readonly appliedElapsedMilliseconds: number;
+    readonly discardedElapsedMilliseconds: number;
+}
+export interface TerminalStepperSnapshot {
+    readonly programPath: readonly number[];
+    readonly repeatIterations: readonly number[];
+    readonly terminalStep: number;
+    readonly terminalTime: number;
+}
+export interface ProgramActivationRecord {
+    readonly program: PibblAnimationProgram;
+    readonly registration: object;
+    readonly originalValues: ReadonlyMap<WritableSignal<unknown>, unknown>;
+    readonly trackStarts: readonly TrackStartSnapshot[];
+    readonly activeSteppers: readonly ActiveStepperSnapshot[];
+    readonly terminalSteppers: readonly TerminalStepperSnapshot[];
+    readonly terminalDuration: number | undefined;
+}
+export interface AnimationEvaluationOwnershipSnapshot {
+    readonly activeStepperStates: number;
+    readonly acquiredStepperStates: number;
+    readonly releasedStepperStates: number;
+}
+/** @internal Exact ownership counters for retained and current-frame stepper state. */
+export declare function animationEvaluationOwnershipSnapshot(): AnimationEvaluationOwnershipSnapshot;
+/** Captures one program token, its committed outputs, and registration identity. */
+export declare function activateProgram(program: PibblAnimationProgram, registration: object): ProgramActivation;
+/** @internal Forks engine-owned activation state for an outer transaction. */
+export declare function forkProgramActivation(activation: ProgramActivation): ProgramActivation;
+/** @internal Publishes one successfully committed activation fork and consumes it. */
+export declare function adoptProgramActivationFork(activation: ProgramActivation, fork: ProgramActivation): void;
+/** @internal Validates one current committed activation snapshot without retaining it. */
+export declare function preflightProgramActivation(program: PibblAnimationProgram): void;
+/** Evaluates one ordinary advance without committing staged output values. */
+export declare function evaluateProgram(activation: ProgramActivation, input: ProgramEvaluationInput): ProgramEvaluationResult;
+/** Rebuilds activation starts from the original run snapshot before sampling. */
+export declare function seekProgram(activation: ProgramActivation, input: ProgramEvaluationInput): ProgramEvaluationResult;
+export interface ProgramFinishInput {
+    readonly previousTime: number | undefined;
+    readonly frameId: number;
+    readonly writer: object;
+    readonly batch: SignalCommitBatch;
+}
+/** Replays a finite program to its exact known terminal state. */
+export declare function finishProgram(activation: ProgramActivation, input: ProgramFinishInput): ProgramEvaluationResult;
+/** Releases every resource retained by one activated program run. */
+export declare function releaseProgramActivation(activation: ProgramActivation): void;
+/** @internal Immutable diagnostic view of one private activation snapshot. */
+export declare function getProgramActivationRecord(activation: ProgramActivation): ProgramActivationRecord;
+export {};