Time-Provider ~ Animation Frame API Addon

Description

This is the Animation Frame API addon for Time-Provider.
Extends the library by exposing the animation frame API (scheduleFrame) through a dedicated (scheduler.animation) facade.

Just like the plugin packages, this addon is tree-shakable.
It is split into a default (system/real-time) entry point and a deterministic one, so each import pulls in only the code it needs:

• @time-provider/addon-animation-frame - for a system (real time) Time-Provider created via @time-provider/core. scheduler.animation passes through to the real requestAnimationFrame/cancelAnimationFrame or throws a clear error otherwise (e.g. plain Node.js, which has no native equivalent).
• @time-provider/addon-animation-frame/deterministic - for a deterministic Time-Provider (fixed/manual/sequential) created via @time-provider/core/deterministic. scheduler.animation is simulated against that runtime's own clock.
  Registered callbacks fires once this runtime's own "now" has moved forward by at least one simulated frame duration.

Usage

import { createTimeProvider } from "@time-provider/core";
import { createTimeProvider as createDeterministicTimeProvider } from "@time-provider/core/deterministic";
import { plugin } from "@time-provider/plugin-native";
import { plugin as deterministicPlugin } from "@time-provider/plugin-native/deterministic";
import { addon } from "@time-provider/addon-animation-frame";
import { addon as deterministicAddon } from "@time-provider/addon-animation-frame/deterministic";

// System: real requestAnimationFrame (or a clear error outside a browser)
const timeProvider = createTimeProvider.for(plugin).use(addon).create();
timeProvider.scheduler.animation.scheduleFrame(() => console.log("Frame!"));

// Deterministic: simulated against the runtime's own clock
const manual = createDeterministicTimeProvider
  .for(deterministicPlugin)
  .use(deterministicAddon)
  .asManual()
  .withInitialTime(0)
  .create();
manual.scheduler.animation.scheduleFrame(() => console.log("Frame!"));
manual.clock.advance({ milliseconds: 20 });

You can configure the simulated frame rate by chaining .withHostFramesRate(...) on the builder right after .use(...):

const manual = createDeterministicTimeProvider
  .for(deterministicPlugin)
  .use(deterministicAddon)
  .withHostFramesRate(90) //now simulating an animation frame API with 90 FPS
  .asManual()
  .withInitialTime(0)
  .create();

With the compat addon

Compose @time-provider/addon-compat before this addon and its .compat facade also gets requestAnimationFrame/cancelAnimationFrame, delegating to scheduleFrame and to the handle's dispose(). They are declared as an optional compat? on WithAnimationFrameApi, since they are only there when both addons are composed.

License

MIT