text-to-lottie

# Authoring Renderable Lottie Files

This app renders Lottie with **Skia's Skottie** module (via `canvaskit-wasm`),
not the JS `lottie-web` runtime. Follow the rules below and
verify the result.

> This skill covers the *mechanics* — the JSON shape Skottie needs. For the
> *craft* (timing, easing, choreography, Disney animation principles), see
> LottieFiles' [motion-design skill](https://github.com/lottiefiles/motion-design-skill).
> Its guidance is in milliseconds; convert to frames with `frames = ms / 1000 * fr`.

## Setting up the project

The deliverable is not just `public/lottie.json`: the viewer should be set up
and the animation should be previewable in the browser. If the player project is
missing, create it; if it exists, install/update dependencies as needed, start
the dev server, and open the local preview URL for verification.

**Always use the official GitHub player project — never hand-roll a custom
viewer.** This skill's JSON rules (slots, the properties panel, the `?frame=`
URL controls, the Skottie wasm wiring) only hold inside that exact project. Do
**not** build your own HTML page, swap in `lottie-web`, or scaffold a bespoke
canvas setup — any of those will silently diverge from how this player renders
and the verification steps below won't apply. If the player project isn't
already on this machine, scaffold a fresh copy of the repo with **degit**:

```bash
npx degit diffusionstudio/lottie my-animation
cd my-animation
npm install   # postinstall copies the CanvasKit wasm into /public
npm run dev
```

Then open the printed local URL. If you already have the project, just
`npm install && npm run dev`.

## Where to write the file (and how it loads)

- Write the animation JSON to **`public/lottie.json`**. That is the only file
  you need to touch to change what the app shows — [`src/App.tsx`](https://github.com/diffusionstudio/lottie/blob/main/src/App.tsx)
  fetches `/lottie.json` at startup.
- With the dev server running (`npm run dev`), a Vite plugin watches that file
  and **full-reloads the page on save**, so your edit appears immediately. No
  other wiring is required.
- If parsing fails, the app shows the error on screen ("CanvasKit could not
  parse the Lottie file.").

## Required top-level shape

Every Lottie document is one JSON object with at least these fields:

```jsonc
{
  "v": "5.7.0",      // bodymovin version string
  "fr": 60,          // frame rate (fps)
  "ip": 0,           // in point (start frame)
  "op": 120,         // out point (end frame) — duration = (op - ip) / fr seconds
  "w": 512,          // composition width  (px)
  "h": 512,          // composition height (px)
  "assets": [],      // images / precomps; [] if none
  "layers": [ /* ... */ ]
}
```

The app letterboxes the `w`×`h` composition to fit the canvas, so pick a square
or sensible aspect ratio. `op` controls the total frame count shown in the UI.

## Layers

`layers` follows After Effects order: the **first** entry in the array is the
**topmost** layer, and later entries render underneath it. Each layer needs at
minimum:

```jsonc
{
  "ty": 4,           // layer type: 4 = shape layer (the common case)
  "nm": "circle",    // name (optional but helpful)
  "ip": 0,           // layer in point
  "op": 120,         // layer out point — must cover the frames you want it visible
  "st": 0,           // start time
  "ks": { /* transform — see below */ },
  "shapes": [ /* ... */ ]   // for shape layers
}
```

Common layer types: `4` shape, `2` image, `1` solid, `0` precomp, `5` text.
Prefer **shape layers (`ty: 4`)** for LLM-authored animations — no external
assets needed.

### The transform block (`ks`)

Every layer has a transform. Each property is either static (`{ "a": 0, "k": value }`)
or animated (`{ "a": 1, "k": [ ...keyframes ] }`).

```jsonc
"ks": {
  "o": { "a": 0, "k": 100 },                 // opacity 0–100
  "r": { "a": 0, "k": 0 },                   // rotation (degrees)
  "p": { "a": 0, "k": [256, 256, 0] },       // position [x, y, z]
  "a": { "a": 0, "k": [0, 0, 0] },           // anchor point [x, y, z]
  "s": { "a": 0, "k": [100, 100, 100] }      // scale (percent, per axis)
}
```

**Anchor matters:** rotation and scale pivot around the anchor `a`, expressed in
the layer's own coordinate space. To rotate a shape around its own center, set
the shape's geometry around the anchor (e.g. center the ellipse on `a`).

## Shapes — the #1 Skottie gotcha

**Skottie requires shape elements to be wrapped in a Group (`ty: "gr"`).** A flat
list of shapes + fills directly in `shapes` renders **blank**. Always nest the
geometry, fill/stroke, and a group transform inside a group's `it` array:

```jsonc
"shapes": [
  {
    "ty": "gr",            // GROUP — required wrapper
    "nm": "ball",
    "it": [
      {
        "ty": "el",        // ellipse
        "p": { "a": 0, "k": [0, 0] },
        "s": { "a": 0, "k": [120, 120] }
      },
      {
        "ty": "fl",        // fill
        "c": { "a": 0, "k": [0.2, 0.6, 1, 1] },   // RGBA, each 0–1
        "o": { "a": 0, "k": 100 }
      },
      {
        "ty": "tr",        // GROUP TRANSFORM — include even if identity
        "p": { "a": 0, "k": [0, 0] },
        "a": { "a": 0, "k": [0, 0] },
        "s": { "a": 0, "k": [100, 100] },
        "r": { "a": 0, "k": 0 },
        "o": { "a": 0, "k": 100 }
      }
    ]
  }
]
```

Shape primitives inside `it`:
- `"el"` ellipse — `p` center, `s` [width, height]
- `"rc"` rectangle — `p` center, `s` [w, h], `r` corner radius
- `"sh"` custom path — `ks.k` is a bezier `{ "c": closed?, "v": verts, "i": inTangents, "o": outTangents }`
- `"st"` stroke — `c` color, `w` width, `o` opacity
- `"fl"` fill — `c` color (RGBA 0–1), `o` opacity
- `"tr"` the group's transform (always include it last)

**Colors are normalized 0–1 RGBA**, not 0–255. `[1, 0, 0, 1]` is opaque red.

## Animating a property (keyframes)

Set `"a": 1` and make `k` an array of keyframe objects. Each keyframe has a
time `t` (frame), a value `s`