# GSAP

Controla el tiempo y la intensidad del efecto con una línea de tiempo propia.

Un tween de GSAP es un objeto de animación que cambia propiedades con el tiempo. Usa estas animaciones nativas con cualquier efecto de domfx y una línea de tiempo para ordenarlas. La instancia permite modificar las propiedades numéricas `time` e `intensity`. No necesitas registrar un plugin de domfx ni importar `@domfx/gsap`.

Sigue la [guía de instalación](/docs/es/installation/#add-the-optional-gsap-binding) y añade GSAP a tu aplicación. Este ejemplo usa Fire; sustituye su importación para usar otro efecto.

### Prueba la secuencia

Una línea de tiempo mueve el texto y controla cinco efectos, letra por letra.

domfx

Pasa el cursor para explorarAmplía para explorar Enfoca la vista previa: + y − amplían o reducen, las flechas desplazan y 0 restablece. En pantallas táctiles, arrastra para desplazar.

<!-- Pan first: its arrows unfold leftward, so the zoom buttons never move under the pointer. -->

La reproducción necesita JavaScript y WebGPU. La secuencia y el texto original siguen visibles.

<!-- Open without JavaScript too: the tracks and starting values stay readable. -->

* time (s)

  0.00

* rootColor

  **

* intensity

  0.000.000.000.000.00

Posición en la línea de tiempo (s)0.00

Cambiar la posición pausa la reproducción.

La secuencia

```ts
timeline.fromTo(host, { opacity: 0 }, {
  opacity: 1,
  duration: .4,
  ease: "none",
  immediateRender: false
}, 0);
timeline.fromTo(letters, { y: 70 }, {
  y: 0,
  duration: .8,
  ease: "back.out(2.2)",
  stagger: .06,
  immediateRender: false
}, 0);
timeline.addLabel("ignite", 1);
timeline.to(fires, {
  intensity: 1,
  duration: .7,
  ease: "power3.in",
  stagger: .14
}, "ignite");
timeline.addLabel("surge", 2.4);
timeline.to(fires, {
  rootColor: "#ffffff",
  tipColor: "#ffd27a",
  duration: .7,
  ease: "power1.in"
}, "surge");
timeline.to(fires, {
  rootColor: "#99ddff",
  tipColor: "#0066ff",
  duration: .8,
  ease: "power1.out"
}, "surge+=0.7");
timeline.to(letters, {
  y: -18,
  duration: .3,
  ease: "sine.inOut",
  yoyo: true,
  repeat: 1,
  stagger: .07
}, "surge+=0.3");
timeline.addLabel("burnOut", 4.2);
timeline.to(fires, {
  intensity: .08,
  duration: 1,
  ease: "power2.out",
  stagger: {
    each: .15,
    from: "end"
  }
}, "burnOut");
timeline.to(fires, {
  time: 6,
  duration: 6,
  ease: "none"
}, 0);
```

Esta es la secuencia que ejecuta el reproductor, con su escalonado y sus etiquetas. El ejemplo completo de abajo empieza con algo más pequeño: un objetivo y un efecto.

El reproductor da a cada letra su propio efecto con `attachFire(letter, { host, clock: 'manual', intensity: 0, flameReach: 0.7 })` y después pasa las letras y los efectos a una sola línea de tiempo, de modo que `stagger` se aplica a ambos. Mueve, escala y atenúa el contenedor o la posición de las letras con libertad: el efecto las sigue sin una captura nueva. La rotación y la inclinación desactivan el efecto con `unsupported-placement`, y los cambios de opacidad solo en el objetivo no son compatibles, así que atenúa el contenedor.

El resto de esta guía empieza con algo más pequeño: un objetivo y un efecto.

## Proporciona tus elementos

[Sección titulada «Proporciona tus elementos»](#proporciona-tus-elementos)

Usa el `index.html` de [instalación](/docs/es/installation/#provide-the-target-and-host), incluido el contador de clics. Sustituye todo el contenido de `main.ts` por el siguiente módulo. En un componente, ejecútalo después de montar los elementos.

## Construye tu secuencia

[Sección titulada «Construye tu secuencia»](#construye-tu-secuencia)

Crea el efecto con `clock: ‘manual’` para que GSAP controle su tiempo. El contenedor aparece gradualmente en medio segundo; luego el efecto pasa del tiempo 0 al 4 y de intensidad 0.8 a 0.4 durante cuatro segundos. Anima la opacidad del contenedor para que el objetivo original y el efecto la compartan. Los cambios de opacidad solo en el objetivo no son compatibles.

```ts
import { gsap } from 'gsap';
import { attachFire } from '@domfx/browser';

const host = document.querySelector('#host');
const target = document.querySelector('#target');
const clicks = document.querySelector('#clicks');
if (!(host instanceof HTMLElement) || !target || !clicks) {
  throw new Error('Falta el contenedor, el objetivo o el contador');
}

let count = 0;
const onClick = () => { clicks.textContent = String(++count); };
target.addEventListener('click', onClick);

let disposed = false;
let fire: ReturnType<typeof attachFire> | undefined;
const timeline = gsap.timeline({ paused: true });
let unsubscribe: (() => void) | undefined;

function cleanup() {
  disposed = true;
  window.removeEventListener('pagehide', cleanup);
  target?.removeEventListener('click', onClick);
  unsubscribe?.();
  timeline.revert();
  fire?.dispose();
}

// Antes de llamar a setup, registra también cleanup para que se ejecute al desmontar el componente.
window.addEventListener('pagehide', cleanup, { once: true });

const setup = async () => {
  await document.fonts.ready;
  if (disposed) { return; }

  fire = attachFire(target, {
    host, clock: 'manual', motion: 'respect',
    time: 0, intensity: 0.8, seed: 314,
  });
  unsubscribe = fire.onDispose(() => timeline.revert());
  // El objetivo y el efecto comparten la opacidad del contenedor.
  timeline.from(host, {
    opacity: 0,
    duration: .5,
    immediateRender: false
  });
  timeline.addLabel("ignite", .5);
  timeline.to(fire, {
    time: 4,
    intensity: .4,
    duration: 4,
    ease: "none"
  }, "ignite");

  await fire.ready;
  if (disposed) { return; }
  if (fire.lifecycle !== 'active') {
    console.info(fire.reason);
    return;
  }

  timeline.play();
};

void setup();
```

Ejecuta `pnpm dev` y abre la URL indicada. El botón aparece gradualmente; después, sus llamas cambian durante cuatro segundos. Pulsarlo aumenta el contador. Para producción, ejecuta `pnpm build` y después `pnpm preview`.

## Avanza y reproduce

[Sección titulada «Avanza y reproduce»](#avanza-y-reproduce)

Después de preparar el efecto, usa `timeline.play()`, `pause()`, `seek()` y `reverse()`. En `timeline.seek(2.5)`, el tiempo del efecto es 2 y la intensidad 0.6. Retroceder a 1.5 da tiempo 1 e intensidad 0.7. Los saltos a un punto de la línea de tiempo también actualizan estas propiedades, aunque no ejecuten las funciones de devolución de llamada (callbacks); no hace falta copiar sus valores en `onUpdate`.

Encadena llamadas a `.to()` para animar desde los destinos anteriores. Usa `.from()` o `.fromTo()` para indicar valores iniciales explícitos, teniendo en cuenta su renderizado inmediato predeterminado. Los segmentos `.fromTo()` posteriores suelen necesitar `immediateRender: false`. `ease` define cómo varía la velocidad de la animación. `ease`, `repeat`, `yoyo`, `overwrite` y `timeScale()` siguen las convenciones normales de GSAP.

`gsap.killTweensOf(fire, ‘intensity’)` detiene solo esa propiedad; no libera el efecto ni detiene una animación de tiempo. Usa un controlador por propiedad y mantén los valores dentro de los [rangos de control](/docs/es/api/shared/#control-playback).

## Anima el color

[Sección titulada «Anima el color»](#anima-el-color)

Todos los efectos excepto Burned paper permiten modificar `color`. Inicialízalo con una cadena de color opaca explícita y admitida, y después usa extremos opacos explícitos con `fromTo()`; la paleta original es `undefined`, no un valor entre el que interpolar. Esto cambia la decoración y conserva el objetivo y la opacidad del efecto.

```ts
fire.color = '#ff6600';
const colorTween = gsap.fromTo(
  fire,
  { color: '#ff6600' },
  { color: '#6699ff', duration: 2, ease: 'power1.inOut' },
);
```

Para cambios posteriores, usa `gsap.to(fire, { color: '#ff6600', duration: 2 })`. Al limpiar, llama a `colorTween.kill()` antes de liberar el efecto. Para recuperar la paleta original, detén las animaciones de color y asigna `fire.color = undefined`.

`rootColor` y `tipColor` de Fire se animan igual, sin plugin: asigna primero un color explícito y después usa `fromTo()`. Ninguno se puede definir mientras `color` esté definido.

```ts
fire.rootColor = '#fff5a3';
fire.tipColor = '#ff1701';
const flameTween = gsap.fromTo(
  fire,
  { rootColor: '#fff5a3', tipColor: '#ff1701' },
  { rootColor: '#99ddff', tipColor: '#0066ff', duration: 2 },
);
```

## Gestiona el ciclo de vida

[Sección titulada «Gestiona el ciclo de vida»](#gestiona-el-ciclo-de-vida)

Registra `cleanup()` en el mecanismo de desmontaje de tu framework antes de llamar a `setup()`. Elimina los controladores de eventos, revierte y elimina la línea de tiempo propia y libera el efecto. Funciona incluso si las fuentes o `ready` siguen pendientes. La suscripción de liberación también restaura la opacidad si se elimina el objetivo. Al volver a montar, crea variables, efecto y línea de tiempo nuevos.

Si usas una línea de tiempo ajena, conserva referencias a tus animaciones hijas y elimina solo esas animaciones con `kill()`; su propietario limpia la línea de tiempo y las demás animaciones. Terminar, eliminar o sobrescribir una animación no libera los recursos del objetivo.

### Limpieza del contexto GSAP

[Sección titulada «Limpieza del contexto GSAP»](#limpieza-del-contexto-gsap)

Crea las animaciones dentro de `gsap.context()` y devuelve una función de limpieza explícita. Regístrala de forma síncrona; el contexto no registra automáticamente el trabajo creado después en funciones que esperan promesas.

Si adaptas este ejemplo a un contexto, devuelve `cleanup` desde su función de configuración y llama a `context.revert()` al desmontar.

## Funciones opcionales de ciclo de vida

[Sección titulada «Funciones opcionales de ciclo de vida»](#funciones-opcionales-de-ciclo-de-vida)

`@domfx/gsap` proporciona `bindEffect` y `bindEffectAsync` para enlaces que conservan los valores iniciales de los controles, con responsabilidad explícita de limpieza. La función asíncrona libera con seguridad los resultados que llegan después de cancelar.

Estas funciones capturan los controles iniciales al crearse y animan objetivos proxy privados. Difieren de las llamadas nativas encadenadas a `.to()`, de la eliminación de animaciones por objetivo con `gsap.killTweensOf()` y de la sobrescritura. Consulta la [referencia de enlaces con valores iniciales fijos](/docs/es/api/gsap/#snapshot-bindings) si necesitas ese contrato; para secuencias normales, prefiere animaciones nativas.

## Salida no disponible y reintento

[Sección titulada «Salida no disponible y reintento»](#salida-no-disponible-y-reintento)

El ejemplo principal inicia la reproducción solo cuando el efecto está activo. Si WebGPU no está disponible o se solicita movimiento reducido, conserva el objetivo original. Corrige la condición, espera a `fire.retry()`, consulta su estado y reproduce la línea de tiempo existente. El reintento conserva los controles; no necesita otra animación.

Cada [referencia de efecto](/docs/es/api/effects/) comienza con una vista previa interactiva de los controles compartidos. Consulta la [API de GSAP](/docs/es/api/gsap/) y [solución de problemas](/docs/es/troubleshooting/) para más detalles.
