Metadata-Version: 2.3
Name: keyframes
Version: 0.1.0
Summary: Agent-written, interactive HTML slide decks with live 3D, physics, math, code and diagrams
Keywords: slides,presentation,llm,agents,three.js,mujoco,katex
Author: Pranay Thangeda
Author-email: Pranay Thangeda <contact@prny.me>
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Requires-Dist: httpx>=0.28.1
Requires-Dist: starlette>=1.7.0
Requires-Dist: uvicorn>=0.54.0
Requires-Dist: watchfiles>=1.3.0
Requires-Dist: websockets>=17.2
Requires-Dist: playwright>=1.63.0 ; extra == 'export'
Requires-Dist: pypdf>=6.20.1 ; extra == 'export'
Requires-Python: >=3.12
Provides-Extra: export
Description-Content-Type: text/markdown

# keyframes

HTML slide decks that LLMs write and you arrange by hand.

- **Slides are plain HTML files** on a fixed 1920×1080 canvas. Claude Code, Codex & co.
  write them from your references; a generated `AGENTS.md` teaches them the format.
- **Live editor in Chrome**: press `E` to drag, resize, snap and nudge blocks. Changes are
  written straight back into the slide source (only the touched attributes change), so
  your layout and the LLM's edits never fight.
- **Rich embeds** as web components: three.js scenes, MuJoCo WASM physics, editable/runnable
  code (JS + Python via Pyodide), Excalidraw figures, KaTeX math, video.
- **Present anywhere**: presenter view with notes and timer, offline-safe dependency cache,
  PDF export, static site export.

## Quick start

```bash
uv init my-talk && cd my-talk
uv add keyframes            # or: uv add 'keyframes[export]' for pdf/shot/check --render
uv run keyframes init .
uv run keyframes dev        # opens Chrome; edit slides/*.html or ask your LLM to
```

Then ask your agent something like *"Using the papers in references/, draft a 12-slide talk
on X. Put the MuJoCo demo from assets/ on slide 5."* and rearrange the result with `E`.

For exports install the browser once: `uv run playwright install chromium` (or have Chrome).

## In the browser

| key | action |
| --- | --- |
| → / Space, ← | next / previous (build steps included) |
| E | toggle the layout editor |
| S | presenter view (notes, next slide, timer) |
| F | fullscreen · B blackout |

Editor: drag to move (Shift locks axis, Alt disables snapping), handles resize (Shift keeps
aspect), arrows nudge (Shift ×10), `[`/`]` z-order, double-click to interact with a live
embed, `C` copies a block reference like `slides/04-results.html#sim` for your next prompt,
⌘Z / ⌘⇧Z undo/redo, `?` for help.

Edit mode also opens a resizable side panel (toggle with `` ` ``):

- **Source**: the current slide's HTML. Selecting a block jumps to its tag; edits save and
  hot-reload as you type; drags and LLM edits flow back in.
- **Claude / Codex / Shell**: real terminals running in the deck folder (whichever CLIs are
  installed). Sessions survive page reloads. `+ ref` (or `R`) types the selected blocks'
  reference into the prompt, e.g. `@slides/04-problem.html (block "figure")`.

The dev server only accepts editor/terminal requests from its own page, but it does give that
page a shell: keep it bound to 127.0.0.1 (the default).

## Commands

```
keyframes init [path]        new deck from the scaffold
keyframes dev                live server + editor
keyframes present            serve without the editor
keyframes check [--render]   lint; --render adds browser errors and text overflow
keyframes shot [N ...]       PNG screenshots → .keyframes/shots/
keyframes pdf                PDF export (one page per slide, all builds shown)
keyframes build              static site → dist/
keyframes guide              full authoring reference (for LLMs)
keyframes themes             list built-in themes
keyframes eject-theme        copy the theme into the deck to customize it
```

## Deck layout

```
my-talk/
  deck.toml        title, theme, canvas size, extra <head> tags, extra ES module imports
  AGENTS.md        authoring rules for LLMs (CLAUDE.md imports it)
  slides/          01-title.html, 02-motivation.html, ...  (ordered by filename)
  assets/          images, video, MJCF models, three.js scene modules, .excalidraw files
  references/      papers/notes for the LLM to draw from (never exported)
  .keyframes/    dependency cache + screenshots (gitignored)
```

## Themes

- `default`: a clone of Google Slides' "simple-light" template (Google Sans + Roboto Light,
  orbit artwork on title/section slides, split layouts with a grey media panel).
- `minimal`: plain Inter/JetBrains Mono theme.

A theme is a folder with `theme.css` (CSS variables + text/container classes),
`STYLE_GUIDE.md` (rules the LLM follows) and `layouts/*.html` (starting-point slides).
Use `theme = "./theme"` in `deck.toml` for a deck-local theme.

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check src tests && uv run ruff format src tests
cd examples/showcase && uv run keyframes dev   # every component in one deck
```
