# GSAP API

Animate effect properties with GSAP or use optional bindings with fixed starting values.

## Native property tweens

[Section titled “Native property tweens”](#native-property-tweens)

A tween animates property values over time. Use `gsap.to(effect, { time, intensity, duration, ease })` or add the same target to a timeline. Use `clock: ‘manual’` when creating the effect. No domfx plugin registration or `@domfx/gsap` import is needed for these numeric properties.

GSAP writes the effect’s public setters, including during callback-suppressed seeks. Chained `.to()` calls start from the preceding values. `.from()`, `.fromTo()`, `ease` (the rate of change), repeat/yoyo, property overwrite and `gsap.killTweensOf(effect)` use standard GSAP behavior.

Keep values within the [effect control ranges](/docs/api/shared/#control-playback). The instance validates writes at runtime; GSAP’s types do not enforce these ranges. `intensity` clamps per write, so overshooting eases may clip its animation.

Kill your tweens and dispose your effect during teardown. Killing or completing a tween does not dispose its target. Register cleanup immediately, including when setup is still pending. See the [complete GSAP guide](/docs/gsap/) for the lifecycle pattern.

## Optional snapshot bindings

[Section titled “Optional snapshot bindings”](#optional-snapshot-bindings)

Choose a binding when you need fixed starting values or its cleanup helpers. For ordinary sequences, use the native tweens above.

Import `bindEffect` from `@domfx/gsap`. It accepts any undisposed EffectHandle with manual control. Supply the effect instance, a caller-owned GSAP timeline and these options:

| Property                                                                                     | Type            | Default     |
| -------------------------------------------------------------------------------------------- | --------------- | ----------- |
| `time` Absolute destination time in seconds. Must be finite and representable as float32.    | `number`        | Required    |
| `intensity` Finite destination strength. Clamped to 0–1 before interpolation.                | `number`        | Required    |
| `duration` Finite, nonnegative interpolation duration in seconds. Zero is accepted.          | `number`        | Required    |
| `position` GSAP insertion position. Omitting it appends to the timeline.                     | `gsap.Position` | `undefined` |
| `disposeEffect` Give effect cleanup responsibility to the binding, including context revert. | `boolean`       | `false`     |

`bindEffect(effect, timeline, options)` returns an `EffectBinding`. It fixes the starting controls when called and interpolates linearly. Later writes do not change those starting values. `binding.dispose()` removes its tween, keeps the last control values and disposes the effect only with disposeEffect: true. The caller still owns the timeline.

`bindEffectAsync(promise, timeline, options)` accepts a promise of any effect handle and requires `disposeEffect: true`. It returns an `AsyncEffectBinding` with `dispose()` and `ready: Promise<void>`, releasing late results after cancellation. Use `context.revert()` for GSAP context cleanup.

See the [GSAP guide](/docs/gsap/) for a complete sequence and teardown.

These adapters animate private objects rather than the effect instance: `gsap.killTweensOf(effect)` and overwrite between bindings do not affect those tweens. Multiple bindings created together snapshot the same starting controls; use native `.to()` calls for normal chained sequencing.

Killing the caller's timeline alone does not remove a binding's disposal subscription. Dispose the binding too. An asynchronous binding's `ready` waits for binding setup or late-result cleanup, not the effect's own initial setup.

You can bind before effect.ready settles. Invalid options, automatic control and disposed instances throw synchronously; failed validation leaves effect cleanup with you. Disposing an effect detaches its bindings. Use context.revert(), not context.kill(), to run custom context cleanup.
