Magic Move Slides

---
name: magic-move-slides
description: Build animated slide decks in the user's house style, where points, graph edges, balls, lunes, arcs, charts and KaTeX formulas tween smoothly between slides (Keynote Magic Move style), delivered as one self-contained HTML file plus its Python build source. Use this skill whenever the user asks to visualize or animate a proof, lemma, algorithm, search walk, pruning rule, geometric construction or data structure as slides, asks for "animated slides", "magic move" or "morph" transitions, says "the visualization thingy", "same style as before" or "like the proof slides", or wants to extend, fix or restyle a deck built this way, even if they never mention a skill. Do not use it when the user wants a PowerPoint, Keynote or Google Slides file; use the pptx skill for those.
---

# Magic-move slides

Decks built with this skill are a Python storyboard (`build.py`) that defines elements once
and lists the target state of each slide. `deckkit` turns that into JSON, renders all TeX with
KaTeX, embeds the fonts, and writes a single HTML file played by a small tweening engine.
Elements that keep their id across slides move, grow, recolor and fade smoothly; a camera
can zoom into details. Nothing loads from the network at view time.

Read `references/style.md` before storyboarding (layout grid, color roles, the user's text
rules, proof storyboard patterns, QA checklist). Read `references/api.md` while writing
`build.py` (element types, slide API, timing, camera). `scripts/example_build.py` shows every
pattern in six slides and is the template to copy.

## Workflow

1. **Set up a working directory.** Copy the scripts so the deck can be rebuilt from its zip
   (`/home/claude/deck` in the claude.ai sandbox; a `deck/` folder inside the project when
   working locally):
   ```bash
   mkdir -p deck && cp -r <skill-dir>/scripts/* deck/ && cd deck
   ```
   `render()` fetches KaTeX with `npm pack katex` into `~/.cache/deckkit` the first time
   (npm registry access is needed once). QA screenshots need Playwright with a Chromium
   (`pip install playwright pillow && playwright install chromium`); `shoot.py` falls back to
   an installed Google Chrome. The claude.ai sandbox has browsers preinstalled.

2. **Storyboard before code.** List the slides: one idea and one animation each. For each,
   note what moves (which ids persist from the previous slide), which states are build
   steps (`group=False`), which sequences are auto chains (walks, scans), and whether the
   geometry is real data or a clean schematic. For proofs, follow the arc in
   `references/style.md` §4: rule, mechanism, lemma, theorem on data, failure, bound,
   counting, verdict, closing.

3. **Compute the geometry for real.** Put algorithms in a helper module (`geo.py`) and run
   them: build the actual graph, run the actual search, record the actual scan. When a slide
   must show a behavior (greedy stalls here, succeeds there), search seeds and queries until
   a configuration shows it cleanly, then `assert` that behavior in the build so later edits
   cannot silently break the story. Reuse one point set and one query across slides.

4. **Write `build.py`** from `example_build.py`: `from deckkit import *`, `D = Deck()`, define
   elements with `D.el`, `D.arrow`, `D.lab`, then `with D.slide(...) as s:` blocks, then
   `render(D, out_path, title=...)`. Define every element once and change props per state;
   reusing ids is what produces the magic move.

5. **Build and look.** Run `python3 build.py`, then
   ```bash
   python3 shoot.py deck.html shots --index              # state -> slide map
   python3 shoot.py deck.html shots                      # all states + contact sheets
   python3 shoot.py deck.html shots --mid 12:600         # frames mid-animation
   ```
   View every `shots/sheet_K.png` with the image viewer and fix what the QA checklist in
   `references/style.md` §5 lists. Overflowing formula lines, label collisions and leftover
   elements are the usual defects; they are invisible unless you look. Iterate until clean.

6. **Deliver.** Put the HTML where the user will find it (`/mnt/user-data/outputs/` in the
   claude.ai sandbox; the folder they named when working locally), zip the sources
   (`build.py`, helper modules, `deckkit.py`, `engine.js`, `template.html`, `deck.css`,
   `render_tex.js`) next to it, and share both (with `present_files` in claude.ai). Publish it
   as an artifact link only if the user asks for a link. In the reply, describe what each part of
   the deck animates in a few sentences, name any assumption you made (for example
   which parameter values or which reading of an ambiguous request), and mention the
   controls once: → or Space next, ← back, `.` to pause an animation.

## Extending an existing deck

If the user uploads a source zip from an earlier deck, unzip it and edit that `build.py`
rather than starting over, so style and element ids stay consistent. New slides go where
the story needs them; keep the deck's palette, headline casing and footnote style. If they
only have the HTML, the embedded `window.DECK` JSON shows the structure, but rebuilding
from source is far easier, so ask for the zip when it matters.

## Pitfalls learned the hard way

- An element that goes from hidden to visible appears at its final state; use `s.grow` for
  arrows that should draw and circles that should expand.
- Every state starts from the previous one. When changing topic, `s.hide_all()`; when
  keeping the graph but swapping formulas, hide the old `F_` labels explicitly.
- After a camera zoom, reset it on the next slide with `s.cam(dur=0)`.
- The formula panel is ~560 px wide. Split long lines into two labels; do not shrink below
  18 px.
- Use raw strings for TeX, `$...$` only for math, and `<`/`>` (never `&lt;`) inside math.
- Circles far larger than the drawing area read badly even when clipped; draw arcs.
- `foot()` refuses more than two notes, matching the user's rule.