# Effect instance

Read effect state, update the captured image and release resources.

An effect instance (`EffectHandle`) is returned immediately by every effect function. Keep it to control animation, check setup results and release resources. [Time and intensity](/docs/api/shared/#control-playback) are its writable controls. Every typed handle except Burned paper extends `ColorEffectHandle`: its `color` property returns normalized `rgb(…)`, or `undefined` for the effect’s original colors. Frost also exposes `mistOpacity`, Burned paper exposes `emberGlow`, and Fire exposes its resolved creation-only `emberDensity` plus writable `rootColor` and `tipColor`, which return normalized `rgb(…)` or `undefined` when unset. The pair is exclusive with `color`: writing one while the other is set throws `invalid-fire-parameter` and keeps the prior value, so assign `undefined` first.

## Read-only state

[Section titled “Read-only state”](#read-only-state)

These properties are read-only. A paused effect can still have up-to-date, visible output. Check lifecycle, capture status and pause separately.

| Property                                                                                                                                                   | Type                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `ready` Resolves after initial setup or cleanup of cancelled setup. Environmental unavailability does not reject it. Check lifecycle and reason afterward. | `Promise<void>`                                          |
| `lifecycle` Current effect state. Check it after setup or retry.                                                                                           | `'active' \| 'suspended' \| 'unavailable' \| 'disposed'` |
| `raster` Capture status: fresh is up to date; refreshing means capture is in progress; stale is out of date.                                               | `'fresh' \| 'refreshing' \| 'stale'`                     |
| `reason` Reason code for unavailable output or temporary suspension. Use this for program logic.                                                           | `EffectReason \| undefined`                              |
| `reasonDetail` Diagnostic message. Wording can change; do not use it for program logic.                                                                    | `string \| undefined`                                    |
| `clock` Animation control selected at creation.                                                                                                            | `'manual' \| 'auto'`                                     |
| `seed` Seed selected at creation.                                                                                                                          | `number`                                                 |
| `paused` Whether domfx automatic animation is paused. Always true with external control or a still effect, including when GSAP is changing time.           | `boolean`                                                |

Readiness does not guarantee visible output or completed GPU execution. Inspect `lifecycle` and `reason`; keep the original content usable when decoration is unavailable.

## Methods

[Section titled “Methods”](#methods)

| Method                                                                                                                                                                                                                                | Returns         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `pause()` Pause automatic animation while retaining the attachment and pending control writes.                                                                                                                                        | `void`          |
| `resume()` Resume automatic animation without catching up time spent paused or hidden. Does not advance externally controlled time or a still effect.                                                                                 | `void`          |
| `refresh()` Hide out-of-date output and capture again. Resolves when this or a newer requested capture is accepted; it does not wait for screen presentation. It rejects on failure, invalidation, disposal or an unavailable handle. | `Promise<void>` |
| `retry()` Start setup again, retaining controls and bindings. Concurrent calls share one attempt. Rejects if already disposed; otherwise inspect state after it settles.                                                              | `Promise<void>` |
| `dispose()` Release resources and detach bindings. Safe to call repeatedly or before setup finishes. Remounting requires a new instance.                                                                                              | `void`          |
| `onDispose(callback)` Register a `() => void` callback that runs once, immediately if already disposed. Returns an unsubscribe function.                                                                                              | `() => void`    |

Refresh and control writes cannot recover an unavailable handle. Correct the condition before calling `retry()`. Call `dispose()` on component unmount and handle rejected refresh/retry promises within the component's lifetime.

## Understand the reported state

[Section titled “Understand the reported state”](#understand-the-reported-state)

`lifecycle` reports whether the effect can render. `raster` reports whether its captured image is up to date. `paused` reports only whether domfx’s automatic animation is paused. These values describe different things.

A GSAP-controlled effect has `paused: true` while its time changes. An effect can have `paused: false` while temporarily unable to render. A still effect can be active, up to date and visible.

Await `ready` for the initial setup attempt, `refresh()` for an updated capture, or `retry()` for a new setup attempt after correcting a problem. Retry keeps the original `ready` promise. None of these promises signals animation completion or completed GPU execution/screen presentation; inspect state for availability.
