keyframes 0.1.0__py3-none-any.whl

keyframes/__init__.py

@@ -0,0 +1 @@
+

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/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/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))

keyframes/deck.py

@@ -0,0 +1,67 @@
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PACKAGE_DIR = Path(__file__).parent
+STATIC_DIR = PACKAGE_DIR / "static"
+THEMES_DIR = PACKAGE_DIR / "themes"
+
+
+class DeckError(Exception):
+    pass
+
+
+@dataclass
+class Deck:
+    root: Path
+    title: str
+    theme: str
+    width: int = 1920
+    height: int = 1080
+    extra_head: list[str] = field(default_factory=list)
+    imports: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, root: Path) -> "Deck":
+        root = root.resolve()
+        config_path = root / "deck.toml"
+        if not config_path.exists():
+            raise DeckError(f"No deck.toml in {root}. Run `keyframes init` first.")
+        config = tomllib.loads(config_path.read_text())
+        width, height = config.get("size", [1920, 1080])
+        return cls(
+            root=root,
+            title=config.get("title", root.name),
+            theme=config.get("theme", "default"),
+            width=width,
+            height=height,
+            extra_head=config.get("head", []),
+            imports=config.get("imports", {}),
+        )
+
+    @property
+    def slides_dir(self) -> Path:
+        return self.root / "slides"
+
+    @property
+    def cache_dir(self) -> Path:
+        return self.root / ".keyframes"
+
+    @property
+    def theme_dir(self) -> Path:
+        local = (self.root / self.theme).resolve()
+        if local.is_dir():
+            return local
+        builtin = THEMES_DIR / self.theme
+        if builtin.is_dir():
+            return builtin
+        raise DeckError(f"Theme {self.theme!r} not found locally or in built-in themes.")
+
+    def slide_paths(self) -> list[Path]:
+        return sorted(self.slides_dir.glob("*.html"))
+
+    def slide_path(self, name: str) -> Path:
+        path = (self.slides_dir / f"{name}.html").resolve()
+        if path.parent != self.slides_dir.resolve() or not path.exists():
+            raise DeckError(f"Unknown slide {name!r}")
+        return path

keyframes/export.py

@@ -0,0 +1,106 @@
+import contextlib
+import io
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .deck import Deck, DeckError
+from .server import background_server
+
+READY_TIMEOUT_MS = 90_000
+
+OVERFLOW_SCRIPT = """() => [...document.querySelectorAll('.keyframes-slide [data-block]')]
+  .filter(el => el.scrollHeight > el.clientHeight + 2 || el.scrollWidth > el.clientWidth + 2)
+  .filter(el => getComputedStyle(el).overflow === 'visible')
+  .map(el => el.dataset.block)"""
+
+
+@dataclass
+class SlideRender:
+    number: int
+    name: str
+    errors: list[str] = field(default_factory=list)
+    overflowing: list[str] = field(default_factory=list)
+
+
+@contextlib.contextmanager
+def browser():
+    try:
+        from playwright.sync_api import Error, sync_playwright
+    except ImportError as e:
+        raise DeckError("Exports need the extra: uv add 'keyframes[export]'") from e
+    with sync_playwright() as p:
+        try:
+            instance = p.chromium.launch(channel="chrome")
+        except Error:
+            try:
+                instance = p.chromium.launch()
+            except Error as e:
+                raise DeckError("No browser found. Run: uv run playwright install chromium") from e
+        yield instance
+        instance.close()
+
+
+def resolve_slides(deck: Deck, selectors: list[str] | None) -> list[tuple[int, str]]:
+    names = [p.stem for p in deck.slide_paths()]
+    if not selectors:
+        return list(enumerate(names, start=1))
+    picked = []
+    for selector in selectors:
+        if selector.isdigit() and 1 <= int(selector) <= len(names):
+            picked.append((int(selector), names[int(selector) - 1]))
+        elif selector in names:
+            picked.append((names.index(selector) + 1, selector))
+        else:
+            raise DeckError(f"No slide {selector!r}")
+    return picked
+
+
+def _render_slides(deck: Deck, slides, scale: float, on_page):
+    results = []
+    with background_server(deck) as url, browser() as chrome:
+        page = chrome.new_page(
+            viewport={"width": deck.width, "height": deck.height}, device_scale_factor=scale
+        )
+        page.on("console", lambda m: m.type == "error" and results[-1].errors.append(m.text))
+        page.on("pageerror", lambda e: results[-1].errors.append(str(e)))
+        for number, name in slides:
+            result = SlideRender(number, name)
+            results.append(result)
+            page.goto(f"{url}?print={number}")
+            page.wait_for_selector("html[data-ready='1']", timeout=READY_TIMEOUT_MS)
+            result.overflowing = page.evaluate(OVERFLOW_SCRIPT)
+            on_page(page, result)
+    return results
+
+
+def screenshot_slides(deck: Deck, selectors, out_dir: Path, scale: float = 0.5) -> list[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths = []
+
+    def shoot(page, result: SlideRender):
+        path = out_dir / f"{result.name}.png"
+        page.screenshot(path=path)
+        paths.append(path)
+
+    _render_slides(deck, resolve_slides(deck, selectors), scale, shoot)
+    return paths
+
+
+def render_report(deck: Deck) -> list[SlideRender]:
+    return _render_slides(deck, resolve_slides(deck, None), 0.25, lambda page, result: None)
+
+
+def export_pdf(deck: Deck, out: Path) -> Path:
+    from pypdf import PdfReader, PdfWriter
+
+    writer = PdfWriter()
+
+    def print_page(page, result: SlideRender):
+        pdf = page.pdf(width=f"{deck.width}px", height=f"{deck.height}px", print_background=True)
+        for pdf_page in PdfReader(io.BytesIO(pdf)).pages[:1]:
+            writer.add_page(pdf_page)
+
+    _render_slides(deck, resolve_slides(deck, None), 1, print_page)
+    with out.open("wb") as f:
+        writer.write(f)
+    return out

keyframes/guide/__init__.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from ..deck import THEMES_DIR, Deck, DeckError
+
+GUIDE_DIR = Path(__file__).parent
+
+
+def _theme_dir(deck_path: Path) -> Path:
+    try:
+        return Deck.load(deck_path).theme_dir
+    except DeckError:
+        return THEMES_DIR / "default"
+
+
+def full_guide(deck_path: Path) -> str:
+    theme = _theme_dir(deck_path)
+    parts = [(GUIDE_DIR / "core.md").read_text(), "# Components\n"]
+    parts += [p.read_text() for p in sorted((GUIDE_DIR / "components").glob("*.md"))]
+    if (theme / "STYLE_GUIDE.md").exists():
+        parts.append((theme / "STYLE_GUIDE.md").read_text())
+    layouts = sorted((theme / "layouts").glob("*.html"))
+    if layouts:
+        parts.append("## Layout templates\n")
+        parts += [f"### {p.stem}\n\n```html\n{p.read_text().strip()}\n```\n" for p in layouts]
+    return "\n\n".join(parts)

keyframes/guide/components/keyframes-code.md

@@ -0,0 +1,60 @@
+# `<keyframes-code>`: editable, runnable code
+
+A syntax-highlighted code block (CodeMirror 6) the presenter can edit live. With `run`, it gets a Run button and an output pane: JavaScript runs in a sandboxed iframe, Python runs in the browser via Pyodide.
+
+## Usage
+
+Always put the source inside `<script type="text/plain">`. The HTML parser leaves it untouched, so `<`, `>`, `&`, and `<tag>`-like text need no escaping. Indent it however you like: common indentation and leading/trailing blank lines are stripped.
+
+```html
+<div data-block="demo" data-x="96" data-y="200" data-w="1060" data-h="800">
+  <keyframes-code lang="python" run line-numbers highlight="|4-5|8-10">
+    <script type="text/plain">
+      import numpy as np
+
+      x = np.linspace(0, 1, 5)
+      if x.max() < 2:
+          print(x ** 2)
+    </script>
+  </keyframes-code>
+</div>
+```
+
+The element fills its block and draws its own card (surface background, border, rounded corners), so put it in a plain block with no `card` class or padding.
+
+## Attributes
+
+| Attribute      | Default | Meaning |
+|----------------|---------|---------|
+| `lang`         | `text`  | `python`, `javascript`/`js`, `typescript`/`ts`, `jsx`, `tsx`, `cpp`/`c`, `rust`, `json`, `css`, `html`. Anything else is shown as plain, unhighlighted text. |
+| `run`          | off     | Adds the Run button, Shift+Enter / Cmd+Enter, and the output pane. Only for `python` and `javascript`/`js`; other languages show an error. |
+| `readonly`     | off     | Not editable. |
+| `line-numbers` | off     | Show the line-number gutter. |
+| `font-size`    | `26`    | Code size in px (`22`) or any CSS length. The bar and output scale with it. |
+| `highlight`    | none    | Line ranges per build step, separated by `\|`. See below. |
+| `packages`     | none    | Extra Pyodide packages to load before running, e.g. `packages="numpy scipy"`. Usually unneeded: packages imported by the code are detected and loaded automatically. |
+
+The output pane takes 30% of the height. Change it with a CSS variable: `<keyframes-code style="--keyframes-code-output: 40%">`.
+
+## Build steps with `highlight`
+
+`highlight="1-3|5|7-9,12"` gives one segment per build step: step 0 highlights lines 1-3, step 1 line 5, step 2 lines 7-9 and 12. Lines outside the segment are dimmed. An empty segment means no highlight, so `highlight="|4-5|8-10"` starts with the whole snippet visible. The component creates the extra build steps itself; you do not need `data-step` elements. If the slide has other `data-step` elements they share the same step counter (step `n` reveals both `data-step="n"` and highlight segment `n`). Steps past the last segment keep the last one. Line numbers refer to the original source, not to lines the presenter adds while editing.
+
+## Running code
+
+- **Python**: Pyodide is downloaded the first time any block on any slide is run (a few seconds; the output shows "Loading Python…"), then shared by all blocks. Each run gets a fresh namespace. `print` and stderr go to the output pane; if the last line is an expression, its value is printed too (like a REPL). Tracebacks are trimmed to your code. Packages from the Pyodide distribution (numpy, scipy, pandas, ...) are available; arbitrary pip packages and network or file access are not.
+- **JavaScript**: the code body runs as an async function, so top-level `await` works. `console.log/info/debug` go to the output, `console.warn/error` and uncaught errors show in red. Objects are printed as JSON. It runs in a sandboxed iframe: no access to the deck, the DOM, or `import`. Each run starts a clean sandbox.
+- Neither runtime has a timeout. An infinite loop freezes the tab.
+
+## Presenting
+
+- Click into the code to edit. While the editor has focus, arrow keys and Space edit the code instead of changing slides. Press Esc to leave the editor and get slide navigation back.
+- Edits survive navigating away and back. Reloading the page resets them to the slide source.
+- Print and PDF show the code statically with no highlight dimming. The output pane is hidden unless something was run.
+
+## Gotchas
+
+- The only thing you cannot write inside `<script type="text/plain">` is the literal `</script>`. Write `<\/script>`; the component turns it back into `</script>`.
+- Without the `<script>` wrapper, the element's text content is used. That works for code with no `<` or `&`, but the HTML parser will eat anything that looks like a tag. Don't rely on it.
+- Size the block for the code. 26px code is about 40px per line, so 15 lines need around 650px of editor height, plus about 30% more for the output pane when `run` is set. Long lines scroll horizontally rather than wrap. For longer snippets, lower `font-size` to 20-22.
+- `$` inside code is safe: math rendering skips `keyframes-code`.