clawd-emotes

# Clawd pixel-crab emotes Build a cast of tiny animated pixel crabs, each doing something (eating, gaming, celebrating a holiday, playing guitar…). Every emote is **one inline `<svg>` animated entirely with CSS `@keyframes`** — no GIF frames, no external images. Many emotes live together as cards in one HTML "图鉴" (catalog) page. This approach is loved because it's tiny, crisp at any zoom (`image-rendering` stays sharp), trivially themeable, and editable as plain text. The cost is that the crab's body is a fixed pixel grid, so **placement is everything** — most "bugs" are an element drawn at the wrong coordinate or in the wrong group. ## The workflow 1. **Pick the activities.** One emote = one clear action. Decide the prop, the hat (if any), and the one "hero motion" that sells it (a sip, a strum, a blink-and-bob). Keep it readable at 150×150 px. 2. **Copy the scaffold.** Start each page from `assets/card-template.html` — it has the shared `<style>` block, the grid, and one fully-built example card. Each new emote is one `<div class="card">`. 3. **Build the crab, then layer.** Drop in the base anatomy (see `references/anatomy.md`), give it a unique prefix, then add eyes/arms, the prop, the hat, and particles — in that draw order. 4. **Animate the hero motion** plus idle life (blink, bob, shadow). Use the transform-origins from the anatomy reference; a wrong pivot is the #1 cause of parts flying off. 5. **Verify visually — always.** Render with headless Chrome and actually look at every emote (`scripts/check.py`). This is non-negotiable: pixel art lies in the source and only the render tells the truth. Fix floating hats, detached feet, and disconnected props. 6. **Export to GIF only if asked** (`scripts/export_gif.js`). ## The five rules that prevent every common bug These come from real bugs hit while building the existing sets. Internalize them and you avoid almost all rework. 1. **Feet live *inside* the animated body group.** The shadow is separate and stays on the ground; everything that is part of the crab — feet included — goes inside `<g class="XX-body">`. Feet drawn outside the group don't share the body's transform, so the body bobs/tilts away and the feet "detach." This is structural: feet inside the group *cannot* detach. 2. **A hat's brim must sit on the torso top (y≈6), not float above it.** After drawing a hat, compute the y of its lowest edge and confirm it reaches ~6. If there's a gap, the hat floats. Lower the whole hat and set its `transform-origin` near the contact point (e.g. `7.5px 6px`) so any wobble pivots from the head, not from empty space. 3. **A prop held by a moving arm goes *inside that arm's group*** and pivots at the shoulder. If the prop is in a different group than the hand, the hand moves and the prop stays — it looks disconnected. Chopsticks, brushes, mics, watering cans: all nested in the arm `<g>`. 4. **Long props need gentle rotation.** Rotation moves a point by roughly `radius × angle`. A long prop far from its pivot sweeps a huge arc, so a big keyframe angle flings it off-crab. Either keep the swing small (±10–15°) or move the pivot closer to the prop. (The original eating-crab bug: chopsticks far from the shoulder on a −52°→24° swing — they detached visually. Fixed by anchoring them to the hand and softening to −13°→3°.) 5. **Every inline SVG needs a unique class/keyframe prefix.** All the cards share one document, so global CSS names collide. Prefix everything per emote (`bd-` birthday, `cf-` coffee, `gm-` gaming…): `.cf-body`, `@keyframes cf-sip`. Reusing `body`/`blink` across cards makes animations bleed between crabs. ## Draw order (z-order) matters SVG paints in document order. Within the body group, the reliable layering is: ``` shadow (separate, on the ground) └ body group: feet → torso → screen-glow/face-tint → arms → eyes → mouth → hat (on top of head) → particles that belong behind the prop → foreground prop (mug, bowl, laptop, camera…) ← drawn last so it overlays ``` Foreground props (a mug, a laptop, a bowl) are drawn *after* the face so they sit in front of the body — but keep the eyes above the prop's top edge so the crab can still "look." When a prop must cover the face (a camera up to the eye), that's intentional; add a hint of expression elsewhere (a little smile below). ## Reference files — read these when you need them - **`references/anatomy.md`** — the base crab geometry (every coordinate), transform-origins for each part, the standard idle animations, the per-card theming variables, and ready-to-paste snippets. **Read this before building your first crab**; it's the source of truth for placement. - **`references/prop-recipes.md`** — a catalog of props and hats already built (24 emotes: festivals, daily life, hobbies) with the technique each one uses (held prop, rotating tool, floating screen, particles, headwear). Skim it for patterns and to avoid re-deriving solutions. ## Verifying Run `python3 scripts/check.py <file.html>`. It: - validates each SVG is well-formed (catches missing spaces between attributes like `style="..."x="..."`, unescaped `&`/`<`, etc.), - renders the page with the locally cached/headless Chrome, - saves a full screenshot and one crop per card under `/tmp/clawd-check/`. Then **read the crops** and check each crab against the five rules: hat on the head? feet attached? prop connected to the hand? face readable? If a browser extension or live server is flaky, this headless path is the dependable way to see the result — never report an emote "done" without looking at a render. ## Exporting to GIF (only when the user asks) `node scripts/export_gif.js <file.html> <out-dir>` produces one looping GIF per card. It drives Chrome over CDP and steps each CSS animation deterministically via `document.getAnimations()` (pause, set `currentTime` per frame) rather than capturing in real time — this guarantees a clean, seamless loop. Frames are piped through `ffmpeg` palettegen/paletteuse for crisp pixel colors. See the header comment in the script for the per-card loop-period list and tunables (fps, size, deviceScaleFactor). Requirements: Node, `puppeteer-core` (or a Chrome path), and `ffmpeg` on PATH. ### Transparent GIFs `node scripts/export_transparent.js <file.html> <out-dir>` exports each card to a GIF with a **transparent background** (named `clawd-<tag>.gif`). The key steps: strip the cards' CSS backgrounds in-page, screenshot each `<svg>` with `omitBackground:true` so the empty area is truly transparent, then encode with `ffmpeg palettegen=reserve_transparent=1` + `paletteuse=alpha_threshold`. Do NOT color-key the background away — the crab's eyes and shadow are also black and would be deleted; re-rendering from the source keeps them while clearing only the empty background. The loop period per card is auto-detected from its longest CSS animation.