# 02 — Mascot Animation ("Animation AI")

How a flat, single-pose koala SVG becomes a living, animated Lottie mascot.
This folder holds both the **deliverables** (Lottie JSON, WebP) and the
**method** (source SVGs, rigging scripts, viewer pages). The full reasoning log
is in `../03-learnings-and-reference/mascot-animation-learnings.md` — read it to
understand the decisions.

## The core idea

Designer-supplied poses are flat SVGs where arms/ears/eyes are often **baked
into a single body-outline path**. You cannot just rotate an arm fill — the navy
outline stays behind and you get a "double-arm ghost". The solution is **path
surgery**: parse the outline with `svgpathtools`, find the limb segments, split
them out into their own closed path, then rotate the outline + fills together
around the real shoulder pivot. Each pose was diagnosed (baked-in vs overlay),
rigged, and exported to Lottie.

Seven poses were produced:
1. Hi, I'm Kinko (chin-tap · blink · talk · breath)
2. Looking at map (map sway · eye dart · mouth-O)
3. Notifications (bells ring · blink)
4. Wave (wrist-bend wave)
5. Sleeping (ZZZ float · breath)
6. Search (glass sweep · eye dart)
7. Yes! (star twinkle · mouth pulse)
Plus a `ripple` splash-loader animation.

## Subfolders

### source-poses/
Original designer SVGs (`pose1.svg`…), the **path-surgery-rigged** versions
(`pose1-rigged.svg`, `pose4-wave-rigged.svg`, etc.), and PNG renders (`*_800.png`
used as Lottie embeds). `kinko-logo.svg` included.

### lottie-json/   ← the animation JSON
- `koala-poseN-rigged.json` — **the production deliverables**: small, hand-rigged
  vector Lotties. These are what the gallery pages play.
- `koala-poseN-base.json` — intermediate pre-rig exports.
- `koala-pose1-*.json` (blink / peak / no-shadow / rest / frozen…) — tuning
  experiments, kept for reference.
- `ripple.json` — splash loader.
- `koala-onboarding.json` — a **different kind** of Lottie: it embeds the poses
  as base64 PNGs and crossfades them (raster Lottie, ~429 KB) rather than
  rigging vectors.
- `bear-wave.json` / `koala-wave.json` — early raster-sequence wave Lotties.
- `bear-wave.lottie` — dotLottie zip bundle (manifest + JSON + frames).

### rigging-scripts/   ← how the JSON was generated
Python scripts, one per pose, that read the rigged SVG and emit the Lottie JSON
with the right keyframes/pivots:
`rig_pose4_face.py`, `rig_pose5_sleep.py`, `rig_pose6_search.py`,
`rig_pose7_yes.py`, `rig_ripple.py`. These are the reproducible source of truth.

### raster-frames/
PNG frame sequences captured from animated SVGs (via puppeteer), used to build
the raster Lotties / WebP:
- `wave-bear-frames/` (the original bear "hi")
- `wave-koala-frames/` (the rigged koala wave)

### webp/
Animated WebP deliverables (`bear-wave.webp`, `koala-wave.webp`) — transparent,
small, drop-in for production where Lottie isn't wanted.

### viewers/   ← the WEBPAGES
Serve over HTTP (`python3 -m http.server`) so the pages can fetch local JSON/SVG.

**Galleries that display all mascot poses**
- `koala-lottie-all.html` — clean grid playing all 7 rigged Lottie poses.
- `downloads.html` — same gallery **plus a Download JSON button** per pose.
- `preview.html` — combined viewer (slideshow + Lottie + WebP + raw SVGs).

**The "generate illustrations from JSON/SVG" page (the different one)**
- `exploration.html` — `fetch()`es the raw SVGs, rigs them live in JS, and shows
  2–3 motion *directions* per pose side-by-side. This is the creative-direction
  board, not a pre-baked player.
- `onboarding.html` — the polished 3-scene onboarding slideshow (per-part vector
  rig). `onboarding-v1.html` is the earlier whole-body-bob version.

**Test/debug pages** (kept for reference, not deliverables)
`inspect-poses.html`, `koala-lottie.html` (3-pose), `koala-compare.html`,
`koala-fixtest.html`, `koala-frozen.html`, `koala-shadow-test.html`,
`koala-smil-test.html`, `koala-v2-test.html`, `koala-pose4-only.html`,
`pose4-diff.html`, `pose4-pivot-debug.html`, `ripple-splash.html`,
`wave-koala-rigged.html`, `wave-koala.html`, `wave-test.html`.

## To continue this work
Read `../03-learnings-and-reference/mascot-animation-learnings.md` — it has the
verified path indices per pose, shoulder pivots, the path-surgery algorithm, the
z-stack-safe transform trick (`transform-box: view-box`), and the
visual-verification protocol (render at rest = pixel-identical, then test
rotation = no ghost).