# 0031 — C++ animation curves (timeline + bezier_editor + tween_curves)

## APP Metadata

| Campo | Valor |
|-------|-------|
| **ID** | 0031 |
| **Estado** | pendiente |
| **Prioridad** | media |
| **Tipo** | feature — C++ core (cpp/functions/core) |

## Dependencias

`tokens_cpp_core`. Independiente de los demas issues.

**Desbloquea:** animar uniforms en `shaders_lab` con keyframes; easing reusable en transiciones de UI; control fino sobre animaciones procedurales.

---

## Objetivo

Tres primitivos:

1. **`tween_curves_cpp_core`** — set de funciones de easing puras (Penner): linear, ease_in/out_quad/cubic/expo, elastic, bounce. Header-only.
2. **`bezier_editor_cpp_core`** — editor visual de una curva cubica Bezier (4 puntos de control), evaluacion `f(t)` para t∈[0,1]. Estado puro + render en ImGui canvas.
3. **`timeline_cpp_core`** — widget tipo DAW: tracks horizontales con keyframes draggable, scrub, play/pause, evaluacion `track_value_at(time)` con interp lineal o curve por keyframe.

Demo en `primitives_gallery` con un slider animado por timeline + curva bezier para ease.

## Contexto

`shaders_lab` tiene sliders manuales para uniforms. No hay forma de:
- Animar un uniform con curva temporal.
- Disenar transiciones suaves reusables.

Las funciones de easing son utiles tambien fuera de animacion (interpolacion de colores, rampas).

## Arquitectura

```
cpp/functions/core/
├── tween_curves.h               # NEW (header-only ok)
├── tween_curves.cpp             # NEW (si hace falta .cpp)
├── tween_curves.md              # NEW
├── bezier_editor.h              # NEW
├── bezier_editor.cpp            # NEW
├── bezier_editor.md             # NEW
├── timeline.h                   # NEW
├── timeline.cpp                 # NEW
└── timeline.md                  # NEW
cpp/apps/primitives_gallery/
├── demos_animation.cpp          # NEW
├── demos.h                      # MOD
├── main.cpp                     # MOD
└── CMakeLists.txt               # MOD
```

### API propuesta

```cpp
namespace fn {

// --- tween_curves (puro, header-only ok) ---
namespace tween {
    inline float linear(float t)       { return t; }
    inline float in_quad(float t)      { return t*t; }
    inline float out_quad(float t)     { return 1 - (1-t)*(1-t); }
    inline float in_out_cubic(float t) { /* Penner */ }
    inline float in_expo(float t);
    inline float out_expo(float t);
    inline float in_elastic(float t);
    inline float out_elastic(float t);
    inline float out_bounce(float t);
    // ... ~15 easing funcs

    enum class Ease { Linear, InQuad, OutQuad, InOutQuad, InCubic, OutCubic, /*...*/ };
    float apply(Ease e, float t);
}

// --- bezier_editor (puro estado) ---
struct BezierCurve { ImVec2 p0{0,0}, p1{0.25f,0.0f}, p2{0.75f,1.0f}, p3{1,1}; };
float bezier_eval(const BezierCurve&, float t);  // y at x=t
bool  bezier_editor(const char* id, BezierCurve&, ImVec2 size = {200, 200});  // returns true if changed

// --- timeline ---
struct Keyframe { float time; float value; tween::Ease ease = tween::Ease::Linear; };
struct Track { std::string name; std::vector<Keyframe> keys; };
struct TimelineState {
    std::vector<Track> tracks;
    float current_time = 0.0f;
    float duration     = 5.0f;
    bool  playing      = false;
};
float track_value_at(const Track&, float t);  // interp puro
void  timeline_update(TimelineState&, float dt);  // avanza si playing
bool  timeline_widget(const char* id, TimelineState&, ImVec2 size = {-1, 200});  // returns true if changed
}
```

## Tareas

### Fase 1 — tween_curves

- 1.1 Implementar las funciones Penner (referencia: easings.net). Header-only inline para que el compilador inline en hot paths.
- 1.2 `tween::apply(Ease, t)` con switch.
- 1.3 Tests: cada curva en t=0 y t=1 da 0 y 1 respectivamente (excepto elastic/bounce).
- 1.4 `.md`.

### Fase 2 — bezier_editor

- 2.1 `bezier_eval`: De Casteljau o forma polinomial. Implementacion puramente algebraica.
- 2.2 `bezier_editor`: canvas ImGui con 4 puntos draggable (p0/p3 fijos en {0,0}/{1,1} para easing). Dibuja la curva con `AddBezierCubic`.
- 2.3 Tests para `bezier_eval`.
- 2.4 `.md`.

### Fase 3 — timeline

- 3.1 `track_value_at`: encuentra el segmento (k_i, k_{i+1}), normaliza t, aplica `tween::apply(ease)`.
- 3.2 `timeline_update`: si `playing`, avanza `current_time += dt`; loop al llegar a duration.
- 3.3 `timeline_widget`: barra con tracks horizontales, keyframes como diamantes draggable, scrub time con click en barra superior, botones play/pause. Estilo basado en `tokens`.
- 3.4 Tests para `track_value_at` (linear).
- 3.5 `.md`.

### Fase 4 — Gallery demo

- 4.1 `demos_animation.cpp`:
  - `demo_tween()`: dropdown de Ease + curva animandose contra el tiempo.
  - `demo_bezier_editor()`: editor + plot de la curva resultante.
  - `demo_timeline()`: timeline con 2 tracks ("hue", "amp") + slider que muestra `track_value_at(now)` para cada uno.
- 4.2 Registrar en gallery (3 entradas).

### Fase 5 — Tests + docs

- 5.1 Tests de easing y track_value_at.
- 5.2 `./fn index` + `./fn show` de los 3.

## Ejemplo de uso

```cpp
fn::TimelineState tl{};
tl.tracks.push_back({"hue", {{0, 0}, {2, 1}, {4, 0}}});
tl.duration = 4.0f;
tl.playing  = true;

fn::run_app("anim", [&](float dt){
    fn::timeline_update(tl, dt);
    float h = fn::track_value_at(tl.tracks[0], tl.current_time);
    ImGui::Text("hue = %.3f", h);
    fn::timeline_widget("##tl", tl);
});
```

## Decisiones de diseño

- **Tween header-only**: codigo pequeño, alto uso → inline.
- **Bezier solo para easing (p0=0, p3=1)** en MVP. Generalizable si hace falta.
- **Timeline simple, no jerarquico**: tracks planos. Si hace falta layering en el futuro, otro issue.

## Riesgos

- **UX del bezier_editor**: precision de drag con mouse en canvas pequeño. Documentar tamaño minimo recomendado (180+).
- **Timeline drag race**: keyframe drag debe respetar orden temporal. Reordenar al soltar.
