text-to-lottie

# Authoring Renderable Lottie Files

This app renders Lottie with **Skia's Skottie** module, follow the rules below and verify the result.

## Setting up the project

The deliverable is not just a `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. The dev server defaults to **`http://localhost:3030`**. If you already have the project, just `npm install && npm run dev`.

## Required folder structure in `/public`

The player is a multi-scene editor: every scene lives in its own folder under
`public/projects/`, and the app routes to one by path. **You must follow this
layout exactly** — anything off-layout is ignored.

```
public/
├── canvaskit.wasm                 # Skia wasm (copied in by postinstall — don't touch)
└── projects/
    └── <project-slug>/            # e.g. main-project
        └── <scene-N>/             # e.g. scene-1, scene-2, … (see ordering below)
            ├── lottie.json        # REQUIRED — the Bodymovin animation
            ├── controls.json      # OPTIONAL — properties-panel metadata (see slots)
            └── <image files>      # OPTIONAL — .png/.jpg/.jpeg/.webp/.gif/.svg assets
```

Rules the scanner enforces:

- **Slugs are URL segments.** `<project-slug>` and `<scene-N>` must be
  folder-safe lowercase-ish names; they become the path `/<project>/<scene>`.
  The sidebar label is derived by title-casing the slug (`main-project` →
  "Main Project", `scene-1` → "Scene 1").
- **Scene ordering is the trailing `-N`.** A scene's sort order is the number at
  the end of its slug (`scene-1`, `scene-2`, …, regex `/-(\d+)$/`). Name new
  scenes `scene-<N>` so they order correctly; a slug with no trailing number
  sorts last.
- **`lottie.json` is mandatory.** A scene folder without one is silently dropped
  from the tree (and a project with zero valid scenes disappears entirely).
- **Images are referenced by bare filename.** Put an image in the scene folder
  and reference it in the Lottie's `assets[].p` by filename only
  (e.g. `"p": "background.png"`); the loader resolves it from the same folder.

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

- Write your animation to **`public/projects/<project>/<scene-N>/lottie.json`**.
  If you're creating a brand-new animation and no target scene is specified,
  create a project folder (e.g. `public/projects/my-animation/scene-1/`) and
  write `lottie.json` there, then open `/my-animation/scene-1`.
- The app routes on **`/:project/:scene`** ([`src/router.tsx`](https://github.com/diffusionstudio/lottie/blob/main/src/router.tsx));
  `/` redirects to the first project's first scene. The canvas provider
  ([`src/context/canvas.tsx`](https://github.com/diffusionstudio/lottie/blob/main/src/context/canvas.tsx)) fetches that
  scene's `lottie.json` (plus its images) and renders it.
- With the dev server running, the scenes plugin **watches the folder tree**.
  Adding, removing, or renaming a project/scene folder live-updates the sidebar
  over Vite's HMR socket (no reload). Editing the *contents* of an existing
  `lottie.json` does **not** auto-reload the active scene — reload the page (or
  re-navigate) to pick up hand-edited JSON.

## Example

```json lottie.json
{
  "v": "5.7.0",
  "fr": 60,
  "ip": 0,
  "op": 90,
  "w": 512,
  "h": 512,
  "nm": "Bouncing ball",
  "assets": [],
  "slots": {
    "ballColor": { "p": { "a": 0, "k": [0.231, 0.6, 1, 1] } },
    "ballOpacity": { "p": { "a": 0, "k": 100 } },
    "ballSize": { "p": { "a": 0, "k": [120, 120] } }
  },
  "layers": [
    {
      "ty": 4,
      "nm": "ball",
      "ip": 0,
      "op": 90,
      "st": 0,
      "ks": {
        "o": { "sid": "ballOpacity" },
        "r": { "a": 0, "k": 0 },
        "a": { "a": 0, "k": [0, 0, 0] },
        "s": { "a": 0, "k": [100, 100, 100] },
        "p": {
          "a": 1,
          "k": [
            { "t": 0, "s": [256, 140, 0], "i": { "x": [0.5], "y": [1] }, "o": { "x": [0.7], "y": [0] } },
            { "t": 45, "s": [256, 380, 0], "i": { "x": [0.3], "y": [1] }, "o": { "x": [0.5], "y": [0] } },
            { "t": 90, "s": [256, 140, 0] }
          ]
        }
      },
      "shapes": [
        {
          "ty": "gr",
          "nm": "ball-group",
          "it": [
            { "ty": "el", "p": { "a": 0, "k": [0, 0] }, "s": { "sid": "ballSize" } },
            { "ty": "fl", "c": { "sid": "ballColor" }, "o": { "a": 0, "k": 100 } },
            { "ty": "tr", "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 } }
          ]
        }
      ]
    },
    {
      "ty": 4,
      "nm": "background",
      "ip": 0,
      "op": 90,
      "st": 0,
      "ks": {
        "o": { "a": 0, "k": 100 },
        "r": { "a": 0, "k": 0 },
        "a": { "a": 0, "k": [0, 0, 0] },
        "s": { "a": 0, "k": [100, 100, 100] },
        "p": { "a": 0, "k": [256, 256, 0] }
      },
      "shapes": [
        {
          "ty": "gr",
          "nm": "background-group",
          "it": [
            { "ty": "rc", "p": { "a": 0, "k": [0, 0] }, "s": { "a": 0, "