anim-engine 0.1.2 → 0.2.0

package/README.md

@@ -1,4 +1,13 @@
-# anim-engine
+<h1 align="center">anim-engine</h1>
+
+<div align="center">
+
+[![NPM Version](https://img.shields.io/npm/v/anim-engine.svg)](https://www.npmjs.com/package/anim-engine)
+[![License](https://img.shields.io/npm/l/anim-engine.svg)](https://github.com/LukeCarlThompson/anim-engine/blob/main/packages/anim-engine/LICENSE)
+[![CI](https://github.com/LukeCarlThompson/anim-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/LukeCarlThompson/anim-engine/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+
+</div>
 
 **Renderer-agnostic animation for JavaScript runtimes.** A fast, lightweight, pure-numeric animation engine.
 
@@ -33,7 +42,7 @@ ESM only. Tree-shakeable — import only what you use.
 ```ts
 import { createAnimation, getTicker } from "anim-engine";
 
-// The ticker drives all animations. Start it once.
+// The ticker drives all animations. Start it once or drive it with an external ticker.
 getTicker().start();
 
 const anim = createAnimation({
@@ -63,28 +72,28 @@ By restricting itself to numeric values, the engine eliminates string parsing, c
 
 ## Key advantages
 
-|                              |                                                                                                                |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| ⚡ **Fast**                  | 1.7–9.9× faster than GSAP across tweens, keyframes, and concurrent animations (see [benchmarks](#benchmarks)). |
-| 🪶 **Lightweight**           | Tree-shakeable ESM — import only what you use. No DOM, no canvas, no dependencies.                             |
-| 🎯 **Numbers only**          | A single numeric type for all values. No strings, no transforms, no branches. Predictable performance.         |
-| 🔌 **Renderer-agnostic**     | Feed values to PixiJS, ThreeJS, DOM, canvas2d, or WebGL. Same API everywhere.                                  |
-| 🧩 **Composable models**     | Animations, keyframes, and timelines compose cleanly — put tweens inside timelines, nest keyframes anywhere.   |
-| 🔄 **Continuous primitives** | Spring, smooth damp, and lerp chase live targets with zero setup — pass `() => value` for dynamic targets.     |
-| 🚫 **No GC pressure**        | Zero object allocations in hot update paths. State is mutated in place.                                        |
-| 🎨 **Perceptual color**      | Oklab interpolation via `lerpOklab` — no muddy browns. Compose it into any `onUpdate`.                         |
-| 📐 **TypeScript-first**      | Full type exports, exhaustive discriminated unions, no `any`.                                                  |
-| 🔧 **Ticker control**        | Bring your own game loop or use the built-in rAF ticker. Explicit — never auto-starts.                         |
+|                              |                                                                                                                                     |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| ⚡ **Fast**                  | 1.7–7.5× faster than GSAP overall; 3.0–6.2× when comparing equivalent `onUpdate` callback dispatch (see [benchmarks](#benchmarks)). |
+| 🪶 **Lightweight**           | Tree-shakeable ESM — import only what you use. No DOM, no canvas, no dependencies.                                                  |
+| 🎯 **Numbers only**          | A single numeric type for all values. No strings, no transforms, no branches. Predictable performance.                              |
+| 🔌 **Renderer-agnostic**     | Feed values to PixiJS, ThreeJS, DOM, canvas2d, or WebGL. Same API everywhere.                                                       |
+| 🧩 **Composable models**     | Animations, keyframes, and timelines compose cleanly — put tweens inside timelines, nest keyframes anywhere.                        |
+| 🔄 **Continuous primitives** | Spring, smooth damp, and lerp chase live targets with zero setup — pass `() => value` for dynamic targets.                          |
+| 🚫 **No GC pressure**        | Zero object allocations in hot update paths. State is mutated in place.                                                             |
+| 🎨 **Perceptual color**      | Oklab interpolation via `lerpOklab` — no muddy browns. Compose it into any `onUpdate`.                                              |
+| 📐 **TypeScript-first**      | Full type exports, exhaustive discriminated unions, no `any`.                                                                       |
+| 🔧 **Ticker control**        | Bring your own game loop or use the built-in rAF ticker. Explicit — never auto-starts.                                              |
 
 ## Primitives
 
 ### Timed (return `Animation`)
 
-| Primitive                                   | Returns      | Description                                              |
-| ------------------------------------------- | ------------ | -------------------------------------------------------- |
-| [`createAnimation`](#createanimation)       | `Animation`  | Timed tween from A to B with easing and delay |
-| [`createAnimation` (keyframes)](#keyframes) | `Animation`  | Multi-segment interpolation with per-segment easing      |
-| [`createTimeline`](#createtimeline)         | `Timeline`   | Orchestrate multiple animations on a shared timeline     |
+| Primitive                                   | Returns     | Description                                          |
+| ------------------------------------------- | ----------- | ---------------------------------------------------- |
+| [`createAnimation`](#createanimation)       | `Animation` | Timed tween from A to B with easing and delay        |
+| [`createAnimation` (keyframes)](#keyframes) | `Animation` | Multi-segment interpolation with per-segment easing  |
+| [`createTimeline`](#createtimeline)         | `Timeline`  | Orchestrate multiple animations on a shared timeline |
 
 Animations have `play()`/`pause()`/`resume()`/`stop()`/`skipToEnd()`/`kill()` controls, return a `Promise` from `play()`, and emit `onUpdate`/`onEnded`/`onProgress` callbacks.
 
@@ -135,47 +144,48 @@ anim.skipToEnd(); // jumps to end, resolves promise
 
 **Single-tween options:**
 
-| Option       | Type                                         | Default     | Description                                                  |
-| ------------ | -------------------------------------------- | ----------- | ------------------------------------------------------------ |
-| `from`       | `number \| () => number`                     | —           | Start value (static or dynamic)                              |
-| `to`         | `number \| () => number`                     | —           | End value (static or dynamic)                                |
-| `durationMs` | `number`                                     | —           | Duration in milliseconds                                     |
-| `ease`       | `EaseName \| EaseFunction`                   | `"inOutSine"` | Easing function or name                                    |
-| `delayMs`    | `number`                                     | `0`         | Delay before starting                                        |
-| `onStarted`  | `() => void`                                | —           | Called when animation begins (after delay)                   |
-| `onUpdate`   | `(value: number, velocity: number) => void`  | —           | Called every frame with current value and velocity (units/s) |
-| `onEnded`    | `() => void`                                | —           | Called when animation completes                              |
+| Option       | Type                                        | Default       | Description                                                  |
+| ------------ | ------------------------------------------- | ------------- | ------------------------------------------------------------ |
+| `from`       | `number \| () => number`                    | —             | Start value                                                  |
+| `to`         | `number \| () => number`                    | —             | End value                                                    |
+| `durationMs` | `number \| () => number`                    | —             | Duration in milliseconds                                     |
+| `ease`       | `EaseName \| EaseFunction`                  | `"inOutSine"` | Easing function or name                                      |
+| `onStarted`  | `() => void`                                | —             | Called when playback begins                                  |
+| `onUpdate`   | `(value: number, velocity: number) => void` | —             | Called every frame with current value and velocity (units/s) |
+| `onEnded`    | `() => void`                                | —             | Called when animation completes                              |
+
 **Returns:** `Animation`
 
 ### Keyframes
 
-Multi-segment animation with per-keyframe easing. The last keyframe's `at` value determines total duration. Mutually exclusive with `from`/`to`/`durationMs`.
+Multi-segment animation with per-keyframe easing. The first keyframe is the starting point (no gap/ease). Each subsequent keyframe specifies the gap from the previous one and an optional easing. Total duration is the sum of all gaps.
 
 ```ts
 import { createAnimation } from "anim-engine";
 
 const anim = createAnimation({
   keyframes: [
-    { at: 0, value: 0 },
-    { at: 300, value: 50, ease: "outCubic" },
-    { at: 700, value: 80, ease: "inOutQuad" },
-    { at: 1000, value: 100 },
+    { value: 0 },
+    { value: 50, gap: 300, ease: "outCubic" },
+    { value: 80, gap: 400, ease: "inOutQuad" },
+    { value: 100, gap: 300 },
   ],
   onUpdate: (value) => (sprite.x = value),
   onProgress: (progress) => console.log(`${Math.round(progress * 100)}%`),
 });
 ```
 
-Each keyframe's `at` is in milliseconds — the last keyframe's `at` sets the total duration (1000ms in this example). If no `ease` is specified, the previous segment's ease carries forward.
+Each keyframe's `gap` is in milliseconds from the previous keyframe. Total duration is the sum of all gaps (1000ms in this example). If no `ease` is specified on a keyframe, `"inOutSine"` is used as the default.
 
 **Keyframe options:**
 
-| Option       | Type                                        | Description                                               |
-| ------------ | ------------------------------------------- | --------------------------------------------------------- |
-| `keyframes`  | `Keyframe[]`                                | Array of `{ at, value, ease? }` keyframes                 |
-| `onUpdate`   | `(value: number, velocity: number) => void` | Called every frame with current value and velocity        |
-| `onProgress` | `(progress: number) => void`                | Called every frame with 0–1 global progress               |
-| `onEnded`    | `() => void`                               | Called when the keyframe animation completes              |
+| Option       | Type                                        | Description                                        |
+| ------------ | ------------------------------------------- | -------------------------------------------------- |
+| `keyframes`  | `Keyframe[]`                                | Array of `{ value, gap?, ease? }` keyframes        |
+| `onStarted`  | `() => void`                                | Called when playback begins                        |
+| `onUpdate`   | `(value: number, velocity: number) => void` | Called every frame with current value and velocity |
+| `onProgress` | `(progress: number) => void`                | Called every frame with 0–1 global progress        |
+| `onEnded`    | `() => void`                                | Called when the keyframe animation completes       |
 
 **Returns:** `Animation`
 
@@ -218,45 +228,38 @@ for (let i = 0; i < 6; i++) {
 For more complex sequences, use `createTimeline`:
 
 ```ts
-import { createAnimation, createTimeline } from "anim-engine";
-
-const fadeIn = createAnimation({ from: 0, to: 1, durationMs: 300 });
-const fadeOut = createAnimation({ from: 1, to: 0, durationMs: 300 });
+import { createTimeline } from "anim-engine";
 
 const flash = createTimeline([
-  { at: 0, animation: fadeIn },
-  { gap: 0, animation: fadeOut },
+  { at: 0, keyframe: { keyframes: [{ value: 0 }, { value: 1, gap: 300 }] } },
+  { gap: 0, keyframe: { keyframes: [{ value: 1 }, { value: 0, gap: 300 }] } },
 ]);
 await flash.play();
 ```
 
-
 ### createTimeline
 
-Compose multiple animations on a shared timeline with `at` or `gap` positions.
+Compose multiple keyframe animations on a shared timeline with `at` or `gap` positions. Parallelism comes from multiple layers at the same `at`.
 
 ```ts
-import { createAnimation, createTimeline } from "anim-engine";
-
-const fadeIn = createAnimation({
-  from: 0,
-  to: 1,
-  durationMs: 500,
-  onUpdate: (v) => (sprite.alpha = v),
-});
-
-const slideIn = createAnimation({
-  from: -100,
-  to: 0,
-  durationMs: 800,
-  ease: "outBack",
-  onUpdate: (v) => (sprite.x = v),
-});
+import { createTimeline } from "anim-engine";
 
 const timeline = createTimeline(
   [
-    { at: 0, animation: [fadeIn, slideIn] },
-    { gap: 200, animation: slideIn },
+    {
+      at: 0,
+      keyframe: {
+        keyframes: [{ value: 0 }, { value: 1, gap: 500 }],
+        onUpdate: (v) => (sprite.alpha = v),
+      },
+    },
+    {
+      at: 0,
+      keyframe: {
+        keyframes: [{ value: -100 }, { value: 0, gap: 800, ease: "outBack" }],
+        onUpdate: (v) => (sprite.x = v),
+      },
+    },
   ],
   {
     onProgress: (progress) => console.log(`overall: ${progress}`),
@@ -270,8 +273,8 @@ timeline.play();
 
 ```ts
 type TimelineLayer =
-  | { at: number; animation: Animation | Animation[] }
-  | { gap: number; animation: Animation | Animation[] };
+  | { keyframe: KeyframedAnimationOptions; at: DynamicValue }
+  | { keyframe: KeyframedAnimationOptions; gap: number };
 ```
 
 | Parameter            | Type                 | Description                                                    |
@@ -281,7 +284,7 @@ type TimelineLayer =
 | `options.onProgress` | `(progress) => void` | Called every frame with overall 0–1 progress                   |
 | `options.onEnded`    | `() => void`         | Called when timeline finishes                                  |
 
-`gap` is relative to the end of all animations in the previous layer. Pass a single `Animation` or an array for parallel animations within the layer.
+`gap` is relative to the end of the previous layer. Use multiple layers at the same `at` for parallel animations. A simple tween is expressed as a 2-keyframe sequence: `{ value: from }, { value: to, gap: durationMs }`.
 
 ### Continuous primitives
 
@@ -380,8 +383,8 @@ Perceptually uniform Oklab interpolation. Straight RGB lerp produces muddy trans
 ```ts
 import { lerpOklab, hexToRgba } from "anim-engine";
 
-hexToRgba("#ff6b6b");  // → [1, 0.42, 0.42, 1]
-hexToRgba("#f80");      // → [1, 0.533, 0, 1] (shorthand)
+hexToRgba("#ff6b6b"); // → [1, 0.42, 0.42, 1]
+hexToRgba("#f80"); // → [1, 0.533, 0, 1] (shorthand)
 hexToRgba("#ff804080"); // → [1, 0.502, 0.251, 0.502] (with alpha)
 
 const fromColor = hexToRgba("#ff6b6b");
@@ -484,32 +487,77 @@ You can pass the result directly to any `ease` option — it's an `EaseFunction`
 
 ## Dynamic values
 
-All primitives accept `number | (() => number)` for value parameters. Use a function to update the target every frame without recreating the animation:
+The `DynamicValue` type (`number | (() => number)`) lets you provide values that are resolved at runtime. How often they're resolved depends on the primitive:
+
+### Timed animations (per-play)
+
+In `createAnimation` — tweens and keyframes — all dynamic values are resolved **once when `play()` is called** and cached for the duration of that run. The frame-hot update path reads from the cache with zero overhead:
+
+```ts
+const anim = createAnimation({
+  from: () => getLayoutStart(),
+  to: () => getLayoutEnd(),
+  durationMs: () => 500 / speedMultiplier,
+  keyframes: [
+    { at: 0, value: 0 },
+    { at: () => scrollHeight * 0.3, value: 50 },
+    { at: () => scrollHeight, value: 100 },
+  ],
+});
+
+// Values resolved here, cached for duration
+await anim.play();
+
+// On re-play, values are re-resolved
+await anim.play();
+```
+
+This means `from`, `to`, `durationMs`, `keyframe.at`, and `keyframe.value` are all evaluated at play time and remain stable throughout the animation. If you need truly per-frame dynamic values, that's the domain of continuous primitives.
+
+### Continuous primitives (per-frame)
+
+In `createSpring`, `createSmoothDamp`, and `createLerp`, dynamic values are resolved **every frame** — these primitives are designed to chase live targets:
 
 ```ts
 const spring = createSpring({
-  to: () => getMousePosition(), // starts at current mouse position // re-read every frame
+  to: () => getMousePosition(), // re-read every frame
   stiffness: () => sliderValue, // dynamic stiffness
   damping: () => dampingValue,
 });
 ```
 
-The function is called every frame inside the ticker update — no getter/setter objects, no mutation of the returned controls.
+This distinction reflects the two use-cases: timed animations describe a fixed motion path evaluated at start, while continuous primitives describe ongoing behaviour that adapts to changing input.
 
 ## Benchmarks
 
-Performance comparison against GSAP (vitest bench, Apple Silicon M-series, Node 24).
+Performance comparison against GSAP (vitest bench, Apple Silicon M-series, Node 24). All easing functions are matched between libraries.
+
+### vs GSAP internal mutation
+
+GSAP defaults to mutating target properties directly. This is faster than dispatching callbacks but couples GSAP to the mutation pattern. Anim-engine always dispatches via `onUpdate` (renderer-agnostic).
+
+| Benchmark                                     | anim-engine  | GSAP         | Ratio       |
+| --------------------------------------------- | ------------ | ------------ | ----------- |
+| **Single tween** (cubic, 1000 frames)         | 40,814 ops/s | 10,776 ops/s | 3.8× faster |
+| **Single tween** (linear, 1000 frames)        | 28,590 ops/s | 14,499 ops/s | 2.0× faster |
+| **Single tween** (cubic bezier, 1000 frames)  | 21,449 ops/s | 12,637 ops/s | 1.7× faster |
+| **Keyframe** (3 segments, 1000 frames)        | 26,741 ops/s | 3,549 ops/s  | 7.5× faster |
+| **50 concurrent tweens** (500 frames)         | 892 ops/s    | 438 ops/s    | 2.0× faster |
+| **200 concurrent tweens** (500 frames)        | 200 ops/s    | 106 ops/s    | 1.9× faster |
+| **1000 concurrent tweens** (500 frames)       | 38 ops/s     | 22 ops/s     | 1.7× faster |
+| **50 concurrent keyframes** (500 frames)      | 934 ops/s    | 174 ops/s    | 5.4× faster |
+| **50-layer timeline** (staggered, 500 frames) | 710 ops/s    | 404 ops/s    | 1.8× faster |
+| **50 tweens re-play** (2 cycles, 500 frames)  | 558 ops/s    | 128 ops/s    | 4.4× faster |
+
+### vs GSAP onUpdate (fair comparison)
 
-| Benchmark                                    | anim-engine  | GSAP         | Ratio        |
-| -------------------------------------------- | ------------ | ------------ | ------------ |
-| **Single tween** (cubic, 1000 frames)        | 43,265 ops/s | 9,542 ops/s  | 4.53× faster |
-| **Single tween** (linear, 1000 frames)       | 30,461 ops/s | 16,195 ops/s | 1.88× faster |
-| **Single tween** (cubic bezier, 1000 frames) | 21,439 ops/s | 12,869 ops/s | 1.67× faster |
-| **Keyframe** (3 segments, 1000 frames)       | 35,307 ops/s | 3,560 ops/s  | 9.92× faster |
-| **50 concurrent tweens** (500 frames)        | 942 ops/s    | 473 ops/s    | 1.99× faster |
-| **50 concurrent keyframes** (500 frames)     | 918 ops/s    | 171 ops/s    | 5.38× faster |
+gsap also supports `onUpdate` callbacks, which is equivalent to anim-engine's renderer-agnostic model. This is the apples-to-apples comparison.
 
-Easing functions are matched between libraries (cubic = GSAP `power2.out`, cubic bezier = identical control points via GSAP `CustomEase`). Linear strips out easing to show pure framework overhead.
+| Benchmark                              | anim-engine  | GSAP (onUpdate) | Ratio       |
+| -------------------------------------- | ------------ | --------------- | ----------- |
+| **Single tween** (cubic, 1000 frames)  | 40,814 ops/s | 6,618 ops/s     | 6.2× faster |
+| **50 concurrent tweens** (500 frames)  | 892 ops/s    | 273 ops/s       | 3.3× faster |
+| **200 concurrent tweens** (500 frames) | 200 ops/s    | 66 ops/s        | 3.0× faster |
 
 Run locally: `npm run bench`
 
@@ -615,24 +663,25 @@ requestAnimationFrame(gameLoop);
 
 ### Type exports
 
-| Type                 | Description                                                                                                             |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `Animation`          | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setCurrentValue`, `setProgress`, `currentValue`, `velocity`, `progress` (readonly), `status` |
-| `Interpolation`      | `start`, `stop`, `kill`, `setCurrentValue`, `currentValue`, `velocity`, `status`                                             |
-| `Timeline`           | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `progress`, `status`                                            |
-| `EaseName`           | Union of 31 ease name strings                                                                                           |
-| `EaseFunction`       | `(t: number) => number`                                                                                                 |
-| `DynamicValue`       | `number \| (() => number)`                                                                                             |
-| `AnimationStatus`    | `"playing" \| "paused" \| "stopped" \| "dead"` (for `Animation` / `Timeline`)                                           |
-| `InterpolationStatus` | `"active" \| "inactive" \| "dead"` (for `Interpolation`)                                           |
-| `AnimationOptions`   | Single tween or keyframe animation options (discriminated union)                                                         |
-| `Keyframe`           | `{ at, value, ease? }`                                                                                                  |
-| `TimelineLayer`      | `{ at: number; animation: Animation \| Animation[] } \| { gap: number; animation: Animation \| Animation[] }`           |
-| `SpringOptions`      | `to`, `stiffness`, `damping`, `mass`, `precision?`, `onUpdate`, `onEnded`                                                  |
-| `SmoothDampOptions`  | `to`, `smoothTimeMs`, `maxSpeed?`, `precision?`, `onUpdate`, `onEnded`                                                                     |
-| `LerpOptions`        | `to`, `smoothTimeMs`, `precision?`, `onUpdate`, `onEnded`                                                                                        |
-| `RgbaTuple`          | `readonly [number, number, number, number]`                                                                             |
-| `TickerControls`     | `start`, `stop`, `update`, `add`, `remove`                                                                              |
+| Type                        | Description                                                                                                             |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Animation`                 | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `currentValue`, `velocity`, `progress`, `status` |
+| `Interpolation`             | `start`, `stop`, `kill`, `setCurrentValue`, `currentValue`, `velocity`, `status`                                        |
+| `Timeline`                  | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `progress`, `status`                             |
+| `EaseName`                  | Union of 31 ease name strings                                                                                           |
+| `EaseFunction`              | `(t: number) => number`                                                                                                 |
+| `DynamicValue`              | `number \| (() => number)`                                                                                              |
+| `AnimationStatus`           | `"playing" \| "paused" \| "stopped" \| "dead"` (for `Animation` / `Timeline`)                                           |
+| `InterpolationStatus`       | `"active" \| "inactive" \| "dead"` (for `Interpolation`)                                                                |
+| `AnimationOptions`          | Single tween or keyframe animation options (discriminated union)                                                        |
+| `Keyframe`                  | `{ value, gap?, ease? }`                                                                                                |
+| `KeyframedAnimationOptions` | `{ keyframes: Keyframe[], onStarted?, onUpdate?, onProgress?, onEnded? }`                                               |
+| `TimelineLayer`             | `{ keyframe: KeyframedAnimationOptions; at: DynamicValue } \| { keyframe: KeyframedAnimationOptions; gap: number }`     |
+| `SpringOptions`             | `to`, `stiffness`, `damping`, `mass`, `precision?`, `onUpdate`, `onEnded`                                               |
+| `SmoothDampOptions`         | `to`, `smoothTimeMs`, `maxSpeed?`, `precision?`, `onUpdate`, `onEnded`                                                  |
+| `LerpOptions`               | `to`, `smoothTimeMs`, `precision?`, `onUpdate`, `onEnded`                                                               |
+| `RgbaTuple`                 | `readonly [number, number, number, number]`                                                                             |
+| `TickerControls`            | `start`, `stop`, `update`, `add`, `remove`                                                                              |
 
 ## License
 

package/dist/animation/create-animation.d.ts

@@ -2,20 +2,20 @@ import { Animation, DynamicValue, EaseFunction, EaseName } from '../shared/types
 export type SingleTweenOptions = {
     from: DynamicValue;
     to: DynamicValue;
-    durationMs: number;
+    durationMs: DynamicValue;
     ease?: EaseName | EaseFunction;
-    delayMs?: number;
     onStarted?: () => void;
     onUpdate?: (value: number, velocity: number) => void;
     onEnded?: () => void;
 };
 export type Keyframe = {
-    at: number;
     value: DynamicValue;
     ease?: EaseName | EaseFunction;
+    gap?: DynamicValue;
 };
 export type KeyframedAnimationOptions = {
     keyframes: Keyframe[];
+    onStarted?: () => void;
     onUpdate?: (value: number, velocity: number) => void;
     onProgress?: (progress: number) => void;
     onEnded?: () => void;