keyframes 0.1.0__tar.gz

keyframes-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+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
+```

keyframes-0.1.0/README.md

@@ -0,0 +1,98 @@
+# 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
+```

keyframes-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "keyframes"
+version = "0.1.0"
+description = "Agent-written, interactive HTML slide decks with live 3D, physics, math, code and diagrams"
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+    "slides",
+    "presentation",
+    "llm",
+    "agents",
+    "three.js",
+    "mujoco",
+    "katex",
+]
+classifiers = [
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Graphics :: Presentation",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "starlette>=1.7.0",
+    "uvicorn>=0.54.0",
+    "watchfiles>=1.3.0",
+    "websockets>=17.2",
+]
+
+[[project.authors]]
+name = "Pranay Thangeda"
+email = "contact@prny.me"
+
+[project.optional-dependencies]
+export = [
+    "playwright>=1.63.0",
+    "pypdf>=6.20.1",
+]
+
+[project.scripts]
+keyframes = "keyframes.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.17.0",
+]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]

keyframes-0.1.0/pyproject.toml.orig

@@ -0,0 +1,47 @@
+[project]
+name = "keyframes"
+version = "0.1.0"
+description = "Agent-written, interactive HTML slide decks with live 3D, physics, math, code and diagrams"
+readme = "README.md"
+authors = [
+    { name = "Pranay Thangeda", email = "contact@prny.me" }
+]
+requires-python = ">=3.12"
+keywords = ["slides", "presentation", "llm", "agents", "three.js", "mujoco", "katex"]
+classifiers = [
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Graphics :: Presentation",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "starlette>=1.7.0",
+    "uvicorn>=0.54.0",
+    "watchfiles>=1.3.0",
+    "websockets>=17.2",
+]
+
+[project.optional-dependencies]
+export = [
+    "playwright>=1.63.0",
+    "pypdf>=6.20.1",
+]
+
+[project.scripts]
+keyframes = "keyframes.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.17.0",
+]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

keyframes-0.1.0/src/keyframes/__init__.py

@@ -0,0 +1 @@
+

keyframes-0.1.0/src/keyframes/build.py

@@ -0,0 +1,102 @@
+"""Static export. Vendor files are renamed so they work on any static host (no query strings,
+JS/CSS always have an extension) and every reference to a renamed file is rewritten."""
+
+import json
+import posixpath
+import re
+import shutil
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from .deck import STATIC_DIR, Deck, DeckError
+from .render import render_index
+from .vendor import VENDOR_PREFIX, _kind, vendor_import_map
+
+_TOKEN = re.compile(r"""(?<=["'(])[^"'()\s]+(?=["')])""")
+TEXT_SUFFIXES = (".js", ".mjs", ".css", ".html", ".json")
+
+
+def _vendor_entries(cache: Path):
+    for meta_path in cache.rglob("*.meta.json"):
+        meta = json.loads(meta_path.read_text())
+        file = meta_path.with_name(meta_path.name.removesuffix(".meta.json"))
+        parts = urlsplit(meta["url"])
+        key = f"{VENDOR_PREFIX}/{parts.netloc}{parts.path}" + (f"?{parts.query}" if parts.query else "")
+        name = file.relative_to(cache).as_posix()
+        if _kind(meta["type"]) == "js" and not name.endswith((".js", ".mjs")):
+            name += ".js"
+        if _kind(meta["type"]) == "css" and not name.endswith(".css"):
+            name += ".css"
+        yield key, f"{VENDOR_PREFIX}/{name}", file, meta["type"]
+
+
+def rewrite_refs(text: str, self_path: str, renames: dict[str, str]) -> str:
+    base = posixpath.dirname(self_path)
+
+    def sub(m: re.Match) -> str:
+        token = m.group(0)
+        path, sep, query = token.partition("?")
+        if not (path.startswith((".", VENDOR_PREFIX))):
+            return token
+        resolved = posixpath.normpath(posixpath.join(base, path)) + sep + query
+        target = renames.get(resolved)
+        if target is None:
+            return token
+        rel = posixpath.relpath(target, base or ".")
+        return rel if rel.startswith(".") else f"./{rel}"
+
+    return _TOKEN.sub(sub, text)
+
+
+def _copy_tree(src: Path, dst: Path, dst_prefix: str, renames: dict[str, str]):
+    for file in src.rglob("*"):
+        if not file.is_file() or file.name == "index.html" and src == STATIC_DIR:
+            continue
+        rel = file.relative_to(src).as_posix()
+        out = dst / rel
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if file.suffix in TEXT_SUFFIXES:
+            out.write_text(rewrite_refs(file.read_text(), f"{dst_prefix}/{rel}", renames))
+        else:
+            shutil.copy2(file, out)
+
+
+def warm_cache(deck: Deck) -> bool:
+    """Load every slide once in a headless browser so all vendor files get cached."""
+    from .export import render_report
+
+    try:
+        render_report(deck)
+    except DeckError:
+        return False
+    return True
+
+
+def build(deck: Deck, out: Path | None = None) -> Path:
+    out = (out or deck.root / "dist").resolve()
+    if out.exists():
+        shutil.rmtree(out)
+    out.mkdir(parents=True)
+
+    entries = list(_vendor_entries(deck.cache_dir / "vendor"))
+    renames = {key: name for key, name, _, _ in entries if key != name}
+
+    for _, name, file, content_type in entries:
+        target = out / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if _kind(content_type):
+            target.write_text(rewrite_refs(file.read_text(), name, renames))
+        else:
+            shutil.copy2(file, target)
+
+    _copy_tree(STATIC_DIR, out / "_keyframes", "_keyframes", renames)
+    _copy_tree(deck.theme_dir, out / "_theme", "_theme", renames)
+    if (deck.root / "assets").is_dir():
+        _copy_tree(deck.root / "assets", out / "assets", "assets", renames)
+
+    import_map = {
+        name: rewrite_refs(f'"{path}"', "index.html", renames).strip('"')
+        for name, path in vendor_import_map(deck.imports).items()
+    }
+    (out / "index.html").write_text(render_index(deck, "present", import_map))
+    return out

keyframes-0.1.0/src/keyframes/check.py

@@ -0,0 +1,107 @@
+import re
+from collections import Counter
+from html.parser import HTMLParser
+from pathlib import Path
+
+from .deck import STATIC_DIR, Deck
+from .patch import find_block_tags
+
+LOCAL_REF_ATTRS = {"src", "href", "model", "controller", "poster"}
+COMPONENTS = {p.stem for p in (STATIC_DIR / "components").glob("keyframes-*.js")}
+
+
+class _Collector(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.tags: list[tuple[str, dict]] = []
+        self.depth = 0
+        self.roots: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        if self.depth == 0:
+            self.roots.append(tag)
+        self.tags.append((tag, dict(attrs)))
+        if tag not in {"img", "br", "hr", "input", "meta", "link", "source", "wbr"}:
+            self.depth += 1
+
+    def handle_startendtag(self, tag, attrs):
+        if self.depth == 0:
+            self.roots.append(tag)
+        self.tags.append((tag, dict(attrs)))
+
+    def handle_endtag(self, tag):
+        self.depth = max(0, self.depth - 1)
+
+
+def _is_local(ref: str) -> bool:
+    return bool(ref) and not re.match(r"^([a-z]+:|//|#|data:|_vendor/|\$)", ref)
+
+
+def _check_slider(where: str, attrs: dict, ids: set[str]) -> list[str]:
+    target = attrs.get("for")
+    if not target:
+        return [f"{where}: <keyframes-slider> needs a for attribute"]
+    problems = []
+    if target not in ids:
+        problems.append(
+            f'{where}: <keyframes-slider for="{target}"> matches no data-block or id on this slide'
+        )
+    if "timeline" not in attrs and not attrs.get("param"):
+        problems.append(f'{where}: <keyframes-slider for="{target}"> needs param="..." or timeline')
+    return problems
+
+
+def check_slide(deck: Deck, path: Path) -> list[str]:
+    source = path.read_text()
+    problems = []
+    where = f"slides/{path.name}"
+
+    collector = _Collector()
+    collector.feed(source)
+    if collector.roots != ["section"]:
+        problems.append(f"{where}: must contain exactly one root <section>, found {collector.roots}")
+
+    blocks = find_block_tags(source)
+    for block_id, count in Counter(b.id for b in blocks).items():
+        if count > 1:
+            problems.append(f"{where}: duplicate data-block id {block_id!r}")
+    for block in blocks:
+        geometry = {k: block.attrs.get(f"data-{k}") for k in "xywh"}
+        missing = [k for k, v in geometry.items() if v is None]
+        if missing:
+            problems.append(f"{where}#{block.id}: missing data-{', data-'.join(missing)}")
+            continue
+        try:
+            x, y, w, h = (float(geometry[k]) for k in "xywh")
+        except ValueError:
+            problems.append(f"{where}#{block.id}: non-numeric geometry {geometry}")
+            continue
+        if x < 0 or y < 0 or x + w > deck.width or y + h > deck.height:
+            problems.append(f"{where}#{block.id}: extends outside the {deck.width}x{deck.height} canvas")
+
+    ids = {v for _, attrs in collector.tags for k, v in attrs.items() if k in ("id", "data-block") and v}
+    for tag, attrs in collector.tags:
+        if tag == "keyframes-slider":
+            problems += _check_slider(where, attrs, ids)
+        if tag.startswith("keyframes-") and tag not in COMPONENTS:
+            problems.append(f"{where}: unknown component <{tag}> (available: {sorted(COMPONENTS)})")
+        for attr in LOCAL_REF_ATTRS & attrs.keys():
+            ref = (attrs[attr] or "").split("?")[0].split("#")[0]
+            if _is_local(ref) and not (deck.root / ref).exists():
+                problems.append(f'{where}: <{tag} {attr}="{ref}"> file not found')
+    return problems
+
+
+def check_deck(deck: Deck, render: bool = False) -> list[str]:
+    paths = deck.slide_paths()
+    if not paths:
+        return [f"No slides found in {deck.slides_dir}"]
+    problems = [p for path in paths for p in check_slide(deck, path)]
+    if render:
+        from .export import render_report
+
+        for result in render_report(deck):
+            where = f"slides/{result.name}.html"
+            problems += [f"{where}: browser error: {e}" for e in result.errors]
+            problems += [f"{where}#{b}: content overflows its box" for b in result.overflowing]
+    return problems

keyframes-0.1.0/src/keyframes/cli.py

@@ -0,0 +1,149 @@
+import argparse
+import shutil
+import sys
+import threading
+import webbrowser
+from pathlib import Path
+
+from .deck import PACKAGE_DIR, THEMES_DIR, Deck, DeckError
+from .guide import GUIDE_DIR
+
+SCAFFOLD_DIR = PACKAGE_DIR / "scaffold"
+
+
+def cmd_init(args):
+    target = Path(args.path).resolve()
+    if (target / "deck.toml").exists():
+        sys.exit(f"{target} already has a deck.toml")
+    shutil.copytree(SCAFFOLD_DIR, target, dirs_exist_ok=True)
+    shutil.copy(GUIDE_DIR / "core.md", target / "AGENTS.md")
+    deck_toml = target / "deck.toml"
+    deck_toml.write_text(
+        deck_toml.read_text().replace("{{title}}", args.title or target.name).replace("{{theme}}", args.theme)
+    )
+    print(f"Created deck in {target}\nNext: cd {target} && keyframes dev")
+
+
+def serve(args, mode: str):
+    import uvicorn
+
+    from .server import create_app, free_port
+
+    deck = Deck.load(Path(args.path))
+    port = free_port(args.port)
+    url = f"http://127.0.0.1:{port}/"
+    print(f"keyframes {mode} → {url}")
+    if mode == "dev":
+        print("Press E in the browser to toggle the layout editor, S for presenter view.")
+    if not args.no_open:
+        threading.Timer(0.8, lambda: webbrowser.open(url)).start()
+    uvicorn.run(create_app(deck, mode), host="127.0.0.1", port=port, log_level="warning")
+
+
+def cmd_build(args):
+    from .build import build, warm_cache
+
+    deck = Deck.load(Path(args.path))
+    if not warm_cache(deck):
+        print("Warning: install keyframes[export] so build can preload every slide's dependencies.")
+    out = build(deck, Path(args.out) if args.out else None)
+    print(f"Built static deck → {out}")
+    print(f"Serve it with any static server, e.g. `python -m http.server -d {out}`")
+
+
+def cmd_pdf(args):
+    from .export import export_pdf
+
+    deck = Deck.load(Path(args.path))
+    out = export_pdf(deck, Path(args.out) if args.out else deck.root / f"{deck.root.name}.pdf")
+    print(f"Wrote {out}")
+
+
+def cmd_shot(args):
+    from .export import screenshot_slides
+
+    deck = Deck.load(Path(args.path))
+    out_dir = Path(args.out) if args.out else deck.cache_dir / "shots"
+    for path in screenshot_slides(deck, args.slides, out_dir, scale=args.scale):
+        print(path)
+
+
+def cmd_check(args):
+    from .check import check_deck
+
+    problems = check_deck(Deck.load(Path(args.path)), render=args.render)
+    for problem in problems:
+        print(problem)
+    if problems:
+        sys.exit(1)
+    print("No problems found.")
+
+
+def cmd_guide(args):
+    from .guide import full_guide
+
+    print(full_guide(Path(args.path)))
+
+
+def cmd_themes(args):
+    for theme in sorted(p.name for p in THEMES_DIR.iterdir() if p.is_dir()):
+        print(theme)
+
+
+def cmd_eject_theme(args):
+    deck = Deck.load(Path(args.path))
+    target = deck.root / "theme"
+    if target.exists():
+        sys.exit(f"{target} already exists")
+    shutil.copytree(deck.theme_dir, target)
+    config = deck.root / "deck.toml"
+    config.write_text(config.read_text().replace(f'theme = "{deck.theme}"', 'theme = "./theme"'))
+    print(f"Copied theme to {target} and pointed deck.toml at it.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="keyframes", description=__doc__)
+    sub = parser.add_subparsers(required=True)
+
+    def command(name, fn, help, path=True):
+        p = sub.add_parser(name, help=help)
+        if path:
+            p.add_argument("path", nargs="?", default=".", help="deck folder (default: .)")
+        p.set_defaults(fn=fn)
+        return p
+
+    p = command("init", cmd_init, "create a new deck")
+    p.add_argument("--title")
+    p.add_argument("--theme", default="default")
+
+    for name, mode, help in [
+        ("dev", "dev", "live server with layout editor"),
+        ("present", "present", "serve without editor"),
+    ]:
+        p = command(name, lambda a, m=mode: serve(a, m), help)
+        p.add_argument("--port", type=int, default=8765)
+        p.add_argument("--no-open", action="store_true")
+
+    p = command("build", cmd_build, "export a static site")
+    p.add_argument("-o", "--out")
+    p = command("pdf", cmd_pdf, "export a PDF (requires keyframes[export])")
+    p.add_argument("-o", "--out")
+    p = command("shot", cmd_shot, "screenshot slides to PNG (requires keyframes[export])", path=False)
+    p.add_argument("-d", "--deck", dest="path", default=".", help="deck folder (default: .)")
+    p.add_argument("slides", nargs="*", help="slide numbers or names (default: all)")
+    p.add_argument("-o", "--out")
+    p.add_argument("--scale", type=float, default=0.5)
+    p = command("check", cmd_check, "lint slides; --render also loads them in a browser")
+    p.add_argument("--render", action="store_true")
+    command("guide", cmd_guide, "print the full authoring reference for LLMs")
+    command("themes", cmd_themes, "list built-in themes", path=False)
+    command("eject-theme", cmd_eject_theme, "copy the current theme into the deck to customize")
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    try:
+        args.fn(args)
+    except DeckError as e:
+        sys.exit(str(e))