keyframes 0.1.0__py3-none-any.whl

keyframes/guide/components/keyframes-excalidraw.md

@@ -0,0 +1,148 @@
+# `<keyframes-excalidraw>`: Excalidraw diagrams
+
+Renders a `.excalidraw` file as crisp, hand-drawn SVG (via `exportToSvg` from `@excalidraw/excalidraw` 0.18), scaled to fit its block. Supports click-through build steps. Files drawn at excalidraw.com work as-is, and so do files an LLM writes by hand (see the schema below).
+
+## Usage
+
+```html
+<div data-block="diagram" data-x="96" data-y="200" data-w="1728" data-h="820">
+  <keyframes-excalidraw src="assets/keyframes-excalidraw/diagram.excalidraw"></keyframes-excalidraw>
+</div>
+```
+
+The element fills its block (`display: block; width: 100%; height: 100%`). The drawing keeps its aspect ratio and is centered.
+
+## Attributes
+
+| Attribute    | Default   | Meaning |
+|--------------|-----------|---------|
+| `src`        | required  | Path to the `.excalidraw` JSON, relative to the deck root. Fetched fresh on every load, so editing the file live-reloads the slide. |
+| `fit`        | `contain` | `contain` shows the whole drawing. `cover` fills the block and crops the overflow. |
+| `background` | off       | Off means transparent, so the slide shows through. Bare `background` uses the file's `appState.viewBackgroundColor`. `background="#f1f3f5"` uses that color. |
+| `dark`       | off       | Excalidraw's dark-mode export, which inverts colors. Use it on dark slides. |
+| `padding`    | `16`      | Padding around the drawing, in scene units. |
+
+Attributes are read once, at init.
+
+## Build steps
+
+An element shows up at step N if either of these is true:
+
+- **`"customData": { "step": N }`** is set on the element. This is the easiest option when writing JSON.
+- **It sits inside a frame named `step-N`.** This is the easiest option when drawing at excalidraw.com: draw a frame (F), name it `step-1`, and put elements in it.
+
+Elements with no step appear at step 0. A bound label inherits its container's step, so you only need to tag the shape. The component adds hidden `<span data-step="N">` markers to itself, so the slide's step count includes the diagram's steps. Diagram steps combine with other `data-step` elements on the slide. In print/PDF, every step is shown.
+
+## Gotchas
+
+- Each step is its own SVG layer, stacked on the others. Later steps always draw above earlier ones, whatever their z-order in the file.
+- The full drawing's bounds are reserved from step 0, so the layout doesn't jump. If the diagram looks off-center at step 0, that's why.
+- Frame chrome (outline and name) is never rendered. If you want a visible panel, use a rectangle.
+- Deep-linking to a step inside a diagram (`#/6/2`) lands on step 0. The step markers only exist once the file has loaded, which is after the runtime clamps the step.
+- Fonts are embedded in the SVG as subsets, and the font files go through the vendor cache. To make every font available offline, run `keyframes build`, which loads each slide once.
+- Text in a container that is too tall for it will overflow (Excalidraw would grow the box). Make boxes big enough.
+
+## Authoring a `.excalidraw` file by hand
+
+The file is plain JSON. On load the component fills in every missing field (seed, version, stroke defaults, and so on), measures text, wraps and centers labels, and positions arrow labels. So you only need to write the fields below.
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "elements": [ ... ],
+  "appState": { "viewBackgroundColor": "#ffffff" },
+  "files": {}
+}
+```
+
+Coordinates are scene units: x grows to the right and y grows downward. Only the relative layout matters, because the drawing is scaled to fit the block. A canvas around 1600×600 suits a full-width slide block.
+
+### Shapes: `rectangle`, `ellipse`, `diamond`
+
+```json
+{ "id": "sim", "type": "rectangle", "x": 0, "y": 220, "width": 380, "height": 180,
+  "backgroundColor": "#a5d8ff", "fillStyle": "solid", "roundness": { "type": 3 },
+  "boundElements": [{ "type": "text", "id": "sim-label" }] }
+```
+
+Optional fields:
+
+- `strokeColor` (default `#1e1e1e`) and `strokeWidth` (1, 2 or 4)
+- `strokeStyle`: `solid`, `dashed` or `dotted`
+- `fillStyle`: `solid`, `hachure` or `cross-hatch`
+- `roughness`: 0 is clean, 1 is sketchy, 2 is very sketchy
+- `opacity`: 0–100
+- `roundness`: `{ "type": 3 }` gives rounded rectangles; use `null` for sharp corners
+- `customData.step`
+
+### Labels inside a shape (bound text)
+
+Add a `text` element whose `containerId` is the shape's id. Also list the text in the shape's `boundElements`.
+
+```json
+{ "id": "sim-label", "type": "text", "x": 0, "y": 0,
+  "text": "Simulation\nMuJoCo × 4096 envs", "fontSize": 32, "fontFamily": 5,
+  "textAlign": "center", "verticalAlign": "middle", "containerId": "sim" }
+```
+
+- **Position:** `x`/`y` are recomputed from the container, so `0, 0` is fine.
+- **Size:** leave `width`/`height` out; they are measured.
+- **Line breaks:** use `\n`. Long lines wrap to the container's width.
+- **Alignment:** always set `"textAlign": "center", "verticalAlign": "middle"`. The defaults are left/top.
+
+### Free text
+
+```json
+{ "id": "note", "type": "text", "x": 0, "y": 460, "text": "4096 parallel envs", "fontSize": 24, "fontFamily": 5 }
+```
+
+`x`/`y` is the top-left corner.
+
+`fontFamily` values:
+
+| Value | Font |
+|-------|------|
+| 5 | Excalifont (hand-drawn, default) |
+| 1 | Virgil (older hand-drawn) |
+| 6 | Nunito (clean sans) |
+| 8 | Comic Shanns (mono) |
+| 3 | Cascadia (code) |
+
+### Arrows and lines
+
+```json
+{ "id": "obs", "type": "arrow", "x": 386, "y": 270, "points": [[0, 0], [248, 0]],
+  "endArrowhead": "arrow",
+  "startBinding": { "elementId": "sim", "focus": 0, "gap": 6 },
+  "endBinding": { "elementId": "policy", "focus": 0, "gap": 6 },
+  "boundElements": [{ "type": "text", "id": "obs-label" }] }
+```
+
+- **Points:** `x`/`y` is the start point, and `points` are offsets from it. The first point is always `[0, 0]`.
+- **Paths:** add more points for an L- or U-shaped path, e.g. `[[0,0],[0,150],[-1280,150],[-1280,0]]`.
+- **Arrowheads:** `startArrowhead`/`endArrowhead` take `null`, `arrow`, `triangle`, `dot` or `bar`.
+- **Lines:** use `"type": "line"` for a line with no heads.
+- **Bindings:** `startBinding`/`endBinding` are optional. They only matter if someone later edits the file at excalidraw.com, and then each target shape should also list the arrow in its `boundElements` (`{ "type": "arrow", "id": "obs" }`). The renderer does not snap arrows to shapes, so make the endpoints touch the shape edges yourself: leave a gap of about 6.
+- **Labels:** give an arrow a label with a `text` element whose `containerId` is the arrow's id (`x`/`y` `0, 0`, center/middle). It is drawn at the middle of the path, with a gap cut in the line.
+
+### Layout tips
+
+- Put shapes on a grid, e.g. 380×180 boxes with 260 gaps.
+- Compute arrow endpoints from box edges: a box's right edge at mid-height is (`x + width`, `y + height/2`).
+- Use Excalidraw's palette for fills:
+
+  | Color | Hex |
+  |-------|-----|
+  | blue | `#a5d8ff` |
+  | yellow | `#ffec99` |
+  | green | `#b2f2bb` |
+  | violet | `#eebefa` |
+  | red | `#ffc9c9` |
+  | gray | `#e9ecef` |
+
+  Keep strokes `#1e1e1e`.
+- Use fontSize 28–36 for box labels and 20–24 for arrow labels, so they stay readable once the drawing is scaled down to the block.
+- Give every element a unique, readable `id`.
+
+The example `examples/showcase/assets/keyframes-excalidraw/diagram.excalidraw` (slide `06-excalidraw.html`) is a complete hand-written file with 3 build steps.

keyframes/guide/components/keyframes-mujoco.md

@@ -0,0 +1,76 @@
+# `<keyframes-mujoco>`: live MuJoCo physics
+
+Runs a MuJoCo model in the browser using the official DeepMind WASM bindings (`@mujoco/mujoco`), stepped in real time and rendered with three.js: orbit camera, soft shadows, a checker ground. An optional controller module sets `data.ctrl` every physics step and can react to slide build steps.
+
+## Usage
+
+```html
+<div class="card" data-block="sim" data-x="784" data-y="200" data-w="1040" data-h="800" style="padding: 0; overflow: hidden">
+  <keyframes-mujoco model="assets/arm/scene.xml" controller="assets/arm/ctrl.js"
+             camera="1.9,-1.6,1.35" target="0.1,0,0.35" snapshot-time="6.6"></keyframes-mujoco>
+</div>
+```
+
+The element fills its block (`display: block; width: 100%; height: 100%`). Put it in a block with no padding, plus `overflow: hidden` if the corners are rounded. The canvas background is transparent, so the block's background shows through and an infinite ground plane fades into it.
+
+Interaction: drag to orbit, scroll to zoom, right-drag to pan, **Ctrl+drag (Cmd on macOS) on a body to pull it** with a spring, **double-click to reset**.
+
+## Attributes
+
+| Attribute       | Default            | Meaning |
+|-----------------|--------------------|---------|
+| `model`         | required           | MJCF file, relative to the deck. |
+| `assets`        | none               | Comma-separated extra files (meshes, textures, `<include>`d XML), **relative to the model file**. Each is written into MuJoCo's virtual file system under that same relative path, so write it exactly as the MJCF resolves it, including `meshdir`. For example, `meshdir="meshes"` with `file="arm.stl"` needs `assets="meshes/arm.stl"`. |
+| `controller`    | none               | ES module that drives the sim (see below), relative to the deck. |
+| `camera`        | auto from model    | Camera position `x,y,z` in **MuJoCo world coordinates (Z is up)**. |
+| `target`        | model center       | Orbit target `x,y,z`, also Z-up. |
+| `speed`         | `1`                | Sim seconds per wall-clock second. Read every frame, so you can change it live. Ignored while a timeline is bound. |
+| `paused`        | off                | When present, rendering continues but physics doesn't step. Can be toggled live. Ignored while a timeline is bound. |
+| `snapshot-time` | `2`                | For PDF export, the sim runs to this sim time (in seconds) before the frame is frozen. Pick a moment that shows something good. A bound timeline's `snapshot`/`value` takes precedence. |
+
+## Model support
+
+- Rendered geom types: `plane`, `sphere`, `capsule`, `ellipsoid`, `cylinder`, `box`, `mesh` (OBJ/STL/MSH, using MuJoCo's own processed vertices and normals). `hfield` and `sdf` are not drawn. Sites, tendons, and lights from the MJCF are not drawn either; the component uses its own lighting.
+- Color comes from geom `rgba`, or from the material's `rgba` when the geom keeps the default color. Textures are ignored. Every plane gets a checker in its own color, with the checker size taken from the plane's third `size` value. A plane with `size="0 0 …"` is infinite and fades out at the edges.
+- Geoms in `group` 3 or higher, and geoms with alpha 0, are hidden. This matches MuJoCo's convention for collision-only geoms.
+- If the model has a `<keyframe>`, reset (on load and on double-click) goes to key 0. Otherwise it goes to `qpos0`.
+- To show a moving target marker, use a `mocap="true"` body with a non-colliding geom (`contype="0" conaffinity="0"`) and set `data.mocap_pos` from the controller.
+
+## Controller module
+
+```js
+export default function setup({ mujoco, model, data, container, params }) {
+  return {
+    step(t) { data.ctrl[0] = (params.gain ?? 1) * Math.sin(t); },  // before every mj_step; t = data.time
+    onStep(n) {},                             // slide build step changed (also called once at load)
+    onParam(name, value) {},                  // a bound <keyframes-slider param> changed (also called at load for set values)
+    reset() {},                               // after mj_resetData / keyframe, before mj_forward
+    dispose() {},                             // the component is being destroyed
+  };
+}
+```
+
+All fields are optional, and `setup` may be `async`. `mujoco` is the loaded WASM module (for `mj_name2id`, `mjtObj`, and so on), `model` and `data` are the live `MjModel` and `MjData`, `container` is the `<keyframes-mujoco>` element, and `params` holds the live values of bound `<keyframes-slider param="…">` elements (read it inside `step`). In print/PDF mode, `onStep` gets the slide's last build step.
+
+Useful `data` arrays: `ctrl`, `qpos`, `qvel`, `qfrc_bias` (gravity + Coriolis, which is handy for gravity compensation), `xpos`/`xmat` (body poses), `geom_xpos`, `mocap_pos`/`mocap_quat`, `xfrc_applied`. Use `mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_GEOM.value, "hand")` to look things up by name.
+
+From outside, the element exposes `el.mujoco`, `el.mjModel`, `el.mjData`, `el.reset()`, and `el.seek(t)` once it has loaded.
+
+## Timeline
+
+A bound `<keyframes-slider for="sim" timeline duration="12" loop>` takes over the clock. Play advances the sim in real time. Seeking forward steps the physics up to the new time. Seeking backward resets to the keyframe (calling the controller's `reset()`) and re-simulates up to that time, so with a deterministic controller the result is exactly the state the sim had at that moment. The PDF frame is the timeline's `snapshot` (or `value`).
+
+- Seeking costs one `mj_step` per timestep of sim time from the keyframe (6,000 steps to seek to 12 s at `timestep="0.002"`). That is instant for small models but noticeable for heavy ones, so keep `duration` short for big scenes.
+- Ctrl+drag pushes apply while time is advancing, but they are not recorded. Seeking backward drops them. Double-click reset re-simulates to the current timeline position without pushes.
+- The controller must depend only on `data` and `t` (plus params and build step) for seeks to be exact. Keep state in `setup` closures and clear it in `reset()`.
+
+## Gotchas
+
+- **Get the arrays again on every access** (`data.ctrl`, `data.qpos`, and so on). Each one is a live view into WASM memory, and a view you keep around goes stale if that memory grows. Don't cache them in `setup`.
+- Don't `.delete()` `model` or `data` in the controller; the component owns them. Do `.delete()` any MuJoCo objects you create yourself (`new mujoco.MjvPerturb()`, buffers, and so on), for example in `dispose()`.
+- `step(t)` runs at physics rate (e.g. 500 Hz for `timestep="0.002"`), so keep it cheap. If the browser can't keep up, the sim runs slower than real time rather than taking huge steps.
+- The bindings take the model from the virtual file system only. Any file the XML references must be listed in `assets`, or loading fails with a MuJoCo error in the red error box.
+- Model `stat.extent` sets the default camera distance, and an infinite plane makes the extent large. Set `camera` and `target` explicitly for a well-framed shot.
+- The sim keeps its state when you leave the slide and come back, unless it was disposed (more than 2 slides away). Then it reloads from the keyframe.
+- The browser caches controller modules as ES modules. After editing `ctrl.js`, reload the page: hot slide reload re-runs `setup` but doesn't re-import the module.
+- Every instance holds one WebGL context. Keep it to a few per deck.

keyframes/guide/components/keyframes-slider.md

@@ -0,0 +1,65 @@
+# `<keyframes-slider>`: live parameters and timelines
+
+A slider bound to another component on the same slide, so the presenter can drag a parameter or scrub time during the talk. Two modes:
+
+- **param**: drives one named value in the target's `params` (`<keyframes-three>` scene modules, `<keyframes-mujoco>` controllers).
+- **timeline**: a play/pause button plus a scrubber that owns the target's clock. Dragging seeks; play advances in real time.
+
+## Usage
+
+The slider is its own block, so the user can move and resize it in the editor like any other block. Put `data-block` and geometry directly on it.
+
+```html
+<div class="card" data-block="scene" data-x="784" data-y="200" data-w="1040" data-h="680" style="padding: 0; overflow: hidden">
+  <keyframes-three src="assets/wave/scene.js"></keyframes-three>
+</div>
+<keyframes-slider data-block="speed" data-x="96" data-y="800" data-w="640" data-h="72"
+              for="scene" param="speed" min="0" max="2" step="0.01" value="1" label="Speed"></keyframes-slider>
+<keyframes-slider data-block="time" data-x="784" data-y="912" data-w="1040" data-h="72"
+              for="scene" timeline duration="10" loop snapshot="4"></keyframes-slider>
+```
+
+A height of 64–80 px fits one row at the default size. The slider draws no background, so it sits directly on the slide; wrap it in a `card` block if you want a panel.
+
+## Attributes
+
+| Attribute  | Mode     | Default             | Meaning |
+|------------|----------|---------------------|---------|
+| `for`      | both     | required            | `data-block` id (or element `id`) on the same slide. The slider binds to that element if it is a component, otherwise to the first component inside it. |
+| `param`    | param    | required            | Key in the target's `params`. |
+| `min`, `max` | param  | `0`, `1`            | Range. |
+| `step`     | both     | range / 100 (param), duration / 1000 (timeline) | Granularity of drag and arrow keys. Also sets the decimals shown for params. |
+| `value`    | both     | midpoint (param), `0` (timeline) | Starting value. |
+| `label`    | both     | none                | Text shown left of the track. |
+| `unit`     | both     | none (param), ` s` (timeline) | Suffix after the value readout, e.g. `unit="×"`. Include a leading space if you want one. |
+| `timeline` | timeline | off                 | Timeline mode. |
+| `duration` | timeline | `10`                | Length in seconds. |
+| `loop`     | timeline | off                 | Wrap to 0 at the end. Without it, playback stops at `duration`; play again restarts from 0. |
+| `paused`   | timeline | off                 | Start paused instead of playing on slide entry. |
+| `snapshot` | both     | `value`             | Value used for PDF/print instead of `value`. |
+| `steps`    | both     | none                | Comma-separated values per build step, e.g. `steps="0.5, 1, 2"`: step *n* sets the slider to item *n* (the last item repeats). For a timeline this seeks. |
+
+From outside, `el.value` is the current value.
+
+## Behaviour
+
+- Values reach the target before it initializes, so a scene sees the slider's `value` from its first frame. They also survive the target being destroyed and re-created.
+- Timeline position survives leaving and re-entering the slide. Playback pauses while the slide is off-screen.
+- **Keyboard**: a focused slider owns the keys. Arrows and PageUp/PageDown adjust it and don't change slides. Space toggles play on a timeline. **Esc** hands keys back to slide navigation, and so does clicking anywhere else on the slide. Clickers send arrow/PageDown keys, so press Esc (or click the slide) after dragging.
+- **Editor (E)**: click selects and drags the block. Double-click enters interaction mode, where the slider can be dragged.
+- **PDF/print**: the slider renders as a static control showing `snapshot` (or `value`). The target freezes at that value. A timeline target freezes at that time (see the component docs). If `steps` is set, print uses the last item, because print shows the final build step.
+- Styling uses the theme variables `--accent` (fill, thumb, play button), `--border` (track), `--ink`/`--fg` (label), `--muted` (readout), `--font-sans`, and `--font-mono`. Set `--keyframes-slider-size` (default `28px`) on the block to scale everything.
+
+## Which components support it
+
+| Target | `param` | `timeline` |
+|--------|---------|------------|
+| `<keyframes-three>` | `ctx.params` + `ctx.onParam` | `t` passed to `onFrame` follows the scrubber |
+| `<keyframes-mujoco>` | controller `params` + `onParam` | seek by re-simulating from the keyframe |
+| `<keyframes-code>`, `<keyframes-excalidraw>` | stored in `el.params`, unused | not supported (error box) |
+
+## Gotchas
+
+- `check` reports a `for` that matches nothing on the slide, or a slider with neither `param` nor `timeline`.
+- With a timeline bound, write frame code as a function of `t` (e.g. `y = sin(k*x - w*t)`) so that seeking backwards is exact. Code that accumulates `dt` (`rotation += dt`) still runs, but it ignores the scrubber.
+- One timeline per target. Any number of param sliders can share a target.

keyframes/guide/components/keyframes-three.md

@@ -0,0 +1,81 @@
+# `<keyframes-three>`: three.js scenes
+
+Embeds a live three.js scene. The component owns the renderer, scene, camera, orbit controls, resizing, pixel ratio, the render loop, and GPU cleanup. You write a small ES module that fills in the scene.
+
+## Usage
+
+```html
+<div class="card" data-block="scene" data-x="784" data-y="200" data-w="1040" data-h="800" style="padding: 0; overflow: hidden">
+  <keyframes-three src="assets/my-scene/scene.js" camera="4,3,5" target="0,1,0" fov="40"></keyframes-three>
+</div>
+```
+
+The element fills its block (it is `display: block; width: 100%; height: 100%`). Put it in a block with no padding. If the block has rounded corners, add `overflow: hidden` so they clip the canvas.
+
+## Attributes
+
+| Attribute    | Default       | Meaning |
+|--------------|---------------|---------|
+| `src`        | required      | Scene module path, relative to the deck root (e.g. `assets/x/scene.js`). |
+| `controls`   | `orbit`       | `orbit` gives OrbitControls with damping (drag to orbit, scroll to zoom, right-drag to pan). `none` turns them off. |
+| `background` | `transparent` | `transparent` lets the slide or card show through. Any CSS color (`#0f1b3d`) sets `scene.background`. |
+| `camera`     | `4,3,6`       | Camera position `x,y,z`. |
+| `target`     | `0,0,0`       | Point the camera looks at, which is also the orbit pivot. |
+| `fov`        | `45`          | Vertical field of view in degrees. |
+
+Attributes are read once, at init.
+
+## Scene module contract
+
+```js
+export default async function setup(ctx) {
+  const { THREE, scene, camera, renderer, controls, container, onFrame, onStep, onResize, params, onParam, addons } = ctx;
+  const { RoomEnvironment } = await addons("environments/RoomEnvironment.js");
+
+  const cube = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial({ color: 0x2f6fed }));
+  scene.add(cube, new THREE.HemisphereLight(0xffffff, 0x888888, 2));
+
+  let step = 0;
+  onStep((n) => (step = n));
+  onFrame((t, dt) => (cube.rotation.y += dt * (step >= 1 ? 2 : 0.3) * (params.speed ?? 1)));
+  onParam("color", (v) => cube.material.color.setHSL(v, 0.7, 0.5));
+
+  return () => {};
+}
+```
+
+| `ctx` field | Description |
+|-------------|-------------|
+| `THREE` | The `three` module from the import map. |
+| `scene`, `camera`, `renderer` | `THREE.Scene`, `THREE.PerspectiveCamera`, and `THREE.WebGLRenderer` (antialias, alpha). Change them however you like: tone mapping, shadows, `camera.near`/`far`. |
+| `controls` | The `OrbitControls` instance, or `null` when `controls="none"`. Example: `controls.maxPolarAngle = Math.PI * 0.47`. |
+| `container` | The `<keyframes-three>` element. |
+| `onFrame(cb(t, dt))` | Runs every frame while the slide is current. `t` counts seconds of play time (it does not advance while paused). `dt` is capped at 0.1 s. When a `<keyframes-slider timeline>` is bound, `t` is the scrubber position instead: it jumps when the presenter seeks and holds still while paused. `dt` stays the wall-clock frame time, so easing still settles. |
+| `onStep(cb(n))` | Called with the slide's build step. It fires once after `setup` with the current step, then on every change. Use it to drive behaviour from `data-step` elements on the slide. |
+| `onResize(cb(w, h))` | Called with the canvas size in unscaled slide px. It fires once after `setup`, then on every resize. The camera aspect is already updated. |
+| `params` | Live values from bound `<keyframes-slider param="…">` elements, keyed by `param`. Read it in `onFrame` (`params.speed ?? 1`). Values set before `setup` runs are already present. |
+| `onParam(name, cb(value))` | Called when that param changes, and once after `setup` if it already has a value. Use it for one-off rebuilds; for per-frame use, just read `params`. |
+| `addons(path)` | `import("three/addons/" + path)`, e.g. `addons("loaders/GLTFLoader.js")`. |
+
+`setup` may return a cleanup function. Use it for anything the component can't see, such as timers, workers, or listeners on `window`. You don't need to dispose meshes, materials, textures, `scene.environment` or `scene.background`: on destroy the component traverses the scene and disposes them, then calls `renderer.dispose()` and `forceContextLoss()`.
+
+Your module can also `import * as THREE from "three"` directly, since the import map applies to it. Using `ctx.THREE` is equivalent.
+
+## Lifecycle
+
+- **init**: runs the first time the slide is shown. It creates the renderer, imports `src` with a `?v=<timestamp>` cache-buster so live reload always gets fresh code, then awaits `setup`. If anything throws, the GPU context is freed and an error box appears in the block.
+- **play/pause**: the render loop runs only while the slide is current. Off-slide, a step change or resize renders a single frame.
+- **destroy**: runs when the slide is more than 2 slides away or is live-replaced. It calls your cleanup and frees the WebGL context. Coming back re-runs `setup` from scratch, with `t` reset to 0.
+- **snapshot (PDF/print)**: the loop stops, frame callbacks are simulated at 60 Hz until `t >= 2` s, and one frame is rendered and frozen into an `<img>`. In print the step is the slide's max step, so the PDF shows the final, settled build state. Bound sliders apply their `snapshot` (or `value`) first. With a timeline, `t` is pinned at that position and 2 s of frames run at fixed `t` so that easing settles.
+
+## Gotchas
+
+- Keep all motion in `onFrame`. Don't call `requestAnimationFrame` yourself, because it keeps running when the slide is off-screen.
+- Base animation on `t`/`dt`, not wall-clock time. Exponential easing like `x += (goal - x) * (1 - Math.exp(-dt * k))` gives smooth step transitions and settles correctly in snapshots.
+- Only the `src` module is cache-busted. Helper modules it imports relatively are cached for the page's lifetime, but editing any asset triggers a full reload in dev anyway.
+- Pixel ratio is `devicePixelRatio * deck scale`, capped at 3, and is updated on deck rescale. Sizes in your code should be in world units, not pixels.
+- Each `<keyframes-three>` holds one WebGL context, and browsers cap them at about 16. Several scenes per slide is fine. The runtime disposes far-away slides.
+- With `background="transparent"`, receive shadows on a `THREE.ShadowMaterial` ground plane so only the shadow shows.
+- Heavy setup, like sampling thousands of points or loading GLTF, belongs in `setup`, which is async. Show the result immediately rather than waiting for the first step.
+- Addons must exist under `three@<version>/examples/jsm/`. Check the three version in `DEFAULT_IMPORTS` (`src/keyframes/vendor.py`).
+- In the editor (E), pointer events are disabled on block contents, so orbiting doesn't interfere with dragging blocks.

keyframes/guide/core.md

@@ -0,0 +1,113 @@
+# Keyframes deck: authoring guide
+
+This folder is a [keyframes](https://pypi.org/project/keyframes/) deck. Slides are HTML
+files you edit directly. The user lays out blocks by hand in a live browser editor, so
+**respect existing geometry** unless asked to change layout.
+
+Run `uv run keyframes guide` for the full, version-matched reference: components, the
+active theme's style guide, and its layout templates.
+
+## Workflow
+
+1. The user runs `uv run keyframes dev`: Chrome opens, every save hot-reloads the slide.
+2. Read `references/` for source material the user wants the talk built from.
+3. Write or edit `slides/NN-name.html`. Slides are ordered by filename; use two-digit
+   prefixes and insert with suffixes (`03b-ablation.html`) instead of renaming files.
+4. Verify your work: `uv run keyframes check --render` (structure, missing files, browser
+   errors, text overflowing its box) and `uv run keyframes shot 3 4` (PNG screenshots in
+   `.keyframes/shots/`). Before finishing, look at every shot: one claim per slide, text
+   density, alignment of edges and captions. Fix and re-shoot.
+
+## Writing slides
+
+- Titles are claims written as one sentence ("Sim-trained grasps transfer to the real arm"),
+  not topics ("Results"). Keep them to one line where the layout allows.
+- One main visual per slide, with at most two supporting bullets.
+- Captions say what is happening and where it comes from (real / sim / scripted), with
+  numbers and units: "Real robot, 1× speed · 12/15 grasps succeed".
+- Citations go in a short `cite` footer: `Author et al. Venue Year · Author et al. Venue Year`.
+- Speaker notes are what to say: what to point at, caveats, the so-what. Not a transcript of
+  the slide.
+
+## Slide format
+
+Each file holds exactly one `<section>` drawn on a fixed **1920×1080 canvas**. Every
+top-level element is a *block* with a unique id and absolute geometry in canvas pixels:
+
+```html
+<section data-layout="split">
+  <h2 class="title" data-block="title" data-x="88" data-y="72" data-w="800" data-h="170">The policy transfers to the real arm</h2>
+  <div class="body" data-block="points" data-x="88" data-y="270" data-w="800" data-h="650">
+    Trained only in simulation:
+    <ul class="small">
+      <li>87% success over 40 real trials</li>
+      <li>No fine-tuning on hardware</li>
+    </ul>
+    <p class="lead" data-step="1">Takeaway, revealed on the first click</p>
+  </div>
+  <div class="media" data-block="sim" data-x="1010" data-y="92" data-w="860" data-h="896">
+    <keyframes-mujoco model="assets/arm.xml"></keyframes-mujoco>
+  </div>
+  <aside class="notes">Speaker notes (presenter view: press S).</aside>
+</section>
+```
+
+Rules:
+
+- `data-block` ids are unique per slide and stable. The editor and the user refer to blocks
+  by id (`slides/04-results.html#sim`), so never rename ids casually.
+- `data-x`, `data-y`, `data-w`, `data-h` are integers. Optional `data-z` sets stacking.
+  Keep blocks inside the canvas. Text does not auto-shrink: size the box for its content,
+  or `check --render` reports overflow.
+- When the user has moved/resized blocks, keep their numbers. Change geometry only when the
+  request is about layout.
+- Don't nest blocks. Put structure *inside* a block with normal HTML/CSS (flex, grid).
+- Copy starting layouts from the theme's templates (see `keyframes guide`), then adapt.
+- Use the theme's classes (`headline`, `title`, `subtitle`, `body`, `lead`, `subhead`, `small`,
+  `caption`, `cite`, `media`, `card`, … — see the theme style guide) and CSS variables
+  (`var(--accent)`) instead of hard-coded styling.
+  Small inline `style` tweaks are fine; repeated patterns belong in `assets/deck.css`
+  (loaded via `head` in `deck.toml`).
+- Put every file a slide uses under `assets/` (images, videos, models, scene modules).
+  Reference them with relative paths: `assets/robot.mp4`.
+
+## Builds (click-through reveals)
+
+- `data-step="N"`: element appears at step N (steps start at 0 = slide entry).
+- `data-step-out="M"`: element disappears at step M (combine for replace-in-place).
+- Components receive the step too (e.g. a 3D scene can change camera per step).
+- Use builds to reveal the takeaway or question last. Don't step through ordinary bullets.
+
+## Math
+
+KaTeX renders automatically: `$inline$`, `$$display$$`, `\(...\)`, `\[...\]`,
+`\begin{align}...\end{align}`. Escape literal dollar signs as `\$`, or add class `no-math`
+to a container to skip it.
+
+## Media
+
+- Video: `<video src="assets/clip.mp4" autoplay muted loop playsinline class="fill"></video>`
+  restarts every time the slide is entered and pauses when it's left.
+- Images: `<img src="assets/fig.png" class="fill">` inside a `media` block.
+- `fill` crops to the block; `fill contain` (on an img or video) letterboxes instead. Use
+  `contain` for plots, figures and clips whose edges matter.
+- Arbitrary HTML/CSS/JS is allowed. Prefer components (below) for anything heavy so
+  it starts/stops with the slide and works in PDF export.
+
+## ES modules
+
+Bare imports `three`, `three/addons/...`, `katex`, `@mujoco/mujoco` and anything listed under
+`[imports]` in `deck.toml` resolve through a local caching proxy: decks keep working offline
+after the first load. Add libraries in `deck.toml` instead of `<script src="https://...">`.
+
+## Commands
+
+| command | purpose |
+| --- | --- |
+| `keyframes dev` | live server + layout editor (press E in the browser) |
+| `keyframes present` | serve without the editor |
+| `keyframes check [--render]` | lint slides; `--render` adds browser errors and overflow |
+| `keyframes shot [N ...]` | screenshot slides to `.keyframes/shots/` |
+| `keyframes pdf` | export PDF (all build steps visible) |
+| `keyframes build` | self-contained static site in `dist/` |
+| `keyframes guide` | this guide + components + theme reference |

keyframes/patch.py

@@ -0,0 +1,77 @@
+"""Surgical edits to slide source: only the touched attributes of the touched tags change."""
+
+import re
+from dataclasses import dataclass
+from html.parser import HTMLParser
+
+GEOMETRY_KEYS = ("x", "y", "w", "h", "z")
+
+
+@dataclass
+class BlockTag:
+    id: str
+    start: int
+    end: int
+    text: str
+    attrs: dict[str, str | None]
+
+
+class _BlockFinder(HTMLParser):
+    def __init__(self, source: str):
+        super().__init__(convert_charrefs=False)
+        self.line_offsets = [0]
+        for line in source.split("\n"):
+            self.line_offsets.append(self.line_offsets[-1] + len(line) + 1)
+        self.blocks: list[BlockTag] = []
+
+    def handle_starttag(self, tag, attrs):
+        attr_map = dict(attrs)
+        block_id = attr_map.get("data-block")
+        if block_id is None:
+            return
+        line, col = self.getpos()
+        start = self.line_offsets[line - 1] + col
+        text = self.get_starttag_text()
+        self.blocks.append(BlockTag(block_id, start, start + len(text), text, attr_map))
+
+    handle_startendtag = handle_starttag
+
+
+def find_block_tags(source: str) -> list[BlockTag]:
+    finder = _BlockFinder(source)
+    finder.feed(source)
+    finder.close()
+    return finder.blocks
+
+
+def set_attrs(tag_text: str, values: dict[str, str | None]) -> str:
+    for name, value in values.items():
+        pattern = re.compile(rf"""(\s){re.escape(name)}(\s*=\s*("[^"]*"|'[^']*'|[^\s"'>]+))?(?=[\s/>])""")
+        if value is None:
+            tag_text = pattern.sub("", tag_text, count=1)
+        elif pattern.search(tag_text):
+            replacement = f'{name}="{value}"'
+            tag_text = pattern.sub(lambda m, r=replacement: m.group(1) + r, tag_text, count=1)
+        else:
+            close = re.search(r"\s*/?>$", tag_text)
+            tag_text = f'{tag_text[: close.start()]} {name}="{value}"{tag_text[close.start() :]}'
+    return tag_text
+
+
+def geometry_attrs(geometry: dict[str, float | None]) -> dict[str, str | None]:
+    unknown = set(geometry) - set(GEOMETRY_KEYS)
+    if unknown:
+        raise ValueError(f"Unknown geometry keys: {sorted(unknown)}")
+    return {f"data-{key}": None if value is None else str(round(value)) for key, value in geometry.items()}
+
+
+def patch_blocks(source: str, updates: dict[str, dict[str, str | None]]) -> str:
+    """Apply attribute updates keyed by block id. Raises KeyError for unknown ids."""
+    tags = {tag.id: tag for tag in find_block_tags(source)}
+    missing = set(updates) - set(tags)
+    if missing:
+        raise KeyError(f"Blocks not found: {sorted(missing)}")
+    for tag in sorted((tags[i] for i in updates), key=lambda t: t.start, reverse=True):
+        new_text = set_attrs(tag.text, updates[tag.id])
+        source = source[: tag.start] + new_text + source[tag.end :]
+    return source

keyframes/render.py

@@ -0,0 +1,32 @@
+import html
+import json
+
+from .deck import STATIC_DIR, Deck
+from .vendor import vendor_import_map
+
+DEV_SCRIPTS = """<link rel="stylesheet" href="_keyframes/editor/editor.css">
+<script type="module" src="_keyframes/editor/editor.js"></script>"""
+
+
+def render_slide(name: str, source: str) -> str:
+    return f'<article class="keyframes-slide" data-slide="{html.escape(name)}">\n{source}\n</article>'
+
+
+def render_slides(deck: Deck) -> str:
+    return "\n".join(render_slide(p.stem, p.read_text()) for p in deck.slide_paths())
+
+
+def render_index(deck: Deck, mode: str, import_map: dict[str, str] | None = None) -> str:
+    template = (STATIC_DIR / "index.html").read_text()
+    config = {"mode": mode, "width": deck.width, "height": deck.height, "title": deck.title}
+    replacements = {
+        "{{title}}": html.escape(deck.title),
+        "{{importmap}}": json.dumps({"imports": import_map or vendor_import_map(deck.imports)}, indent=2),
+        "{{config}}": json.dumps(config),
+        "{{head}}": "\n".join(deck.extra_head),
+        "{{dev}}": DEV_SCRIPTS if mode == "dev" else "",
+        "{{slides}}": render_slides(deck),
+    }
+    for key, value in replacements.items():
+        template = template.replace(key, value)
+    return template

keyframes/scaffold/.gitignore

@@ -0,0 +1,3 @@
+.keyframes/
+dist/
+*.pdf

keyframes/scaffold/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

keyframes/scaffold/assets/deck.css

@@ -0,0 +1 @@
+/* Deck-specific styles go here. */

keyframes/scaffold/assets/figure.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 600"><rect width="860" height="600" fill="#f1f3f4"/><text x="430" y="310" font-family="sans-serif" font-size="28" fill="#9aa0a6" text-anchor="middle">assets/figure.svg</text></svg>

keyframes/scaffold/deck.toml

@@ -0,0 +1,10 @@
+title = "{{title}}"
+theme = "{{theme}}"
+size = [1920, 1080]
+
+# Extra tags injected into <head>:
+head = ['<link rel="stylesheet" href="assets/deck.css">']
+
+# Extra ES module imports available to slides and assets (proxied and cached for offline use):
+# [imports]
+# "d3" = "https://cdn.jsdelivr.net/npm/d3@7/+esm"

keyframes/scaffold/slides/01-title.html

@@ -0,0 +1,4 @@
+<section data-layout="title">
+  <h1 class="headline" data-block="title" data-x="220" data-y="193" data-w="735" data-h="220">Talk Title on Two Lines</h1>
+  <p class="byline" data-block="byline" data-x="220" data-y="465" data-w="735" data-h="130">Speaker Name<br>Venue · Date</p>
+</section>