termstage 0.1.0__tar.gz

termstage-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for trusted publisher (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

termstage-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+uv.lock
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Output SVGs (examples)
+*.svg
+!examples/*.svg
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/

termstage-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

termstage-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versions follow [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] — 2026-02-25
+
+### Added
+- Initial release
+- YAML-driven terminal demo SVG generation — no recording required
+- `termstage` CLI with `render` command
+- Support for typing, pause, output, and clear actions
+- Typer-based CLI with `--output` flag
+- PyPI packaging via hatchling + uv

termstage-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: termstage
+Version: 0.1.0
+Summary: Fake terminal demos. YAML in, SVG out. No recording.
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# termstage
+
+Fake terminal demos. Write a YAML file describing the session, run `termstage render`, get an SVG. No recording, no live shell, no asciinema.
+
+Good for README headers and docs where you want to show what a CLI looks like without screenshotting your actual terminal.
+
+---
+
+## Install
+
+```bash
+pip install termstage
+# or
+uv add termstage
+```
+
+## Quick Start
+
+**1. Write a demo YAML:**
+
+```yaml
+# demo.yaml
+title: "notes — a simple CLI notes app"
+theme: dark
+prompt: "$ "
+width: 700
+
+steps:
+  - cmd: "notes --version"
+    output: "notes 1.0.0"
+  - cmd: "notes add 'Fix the login bug before Friday'"
+    output: "Added note #1"
+  - cmd: "notes list"
+    output: |
+      #1  Fix the login bug before Friday
+  - comment: "# Search works too"
+  - cmd: "notes search 'login'"
+    output: "#1  Fix the login bug before Friday"
+```
+
+**2. Render:**
+
+```bash
+termstage render demo.yaml            # → demo.svg
+termstage render demo.yaml -o out.svg
+termstage render demo.yaml --animated # CSS typewriter animation
+```
+
+**3. Preview:**
+
+```bash
+termstage preview demo.yaml
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `termstage render <file.yaml>` | Render static SVG |
+| `termstage render <file.yaml> -o out.svg` | Custom output path |
+| `termstage render <file.yaml> --animated` | Animated CSS typewriter SVG |
+| `termstage init` | Create a starter `demo.yaml` in current directory |
+| `termstage themes` | List available themes |
+| `termstage preview <file.yaml>` | Render and open in browser |
+
+---
+
+## YAML Format
+
+```yaml
+title: "my cli demo"        # Window title bar text
+theme: dark                 # dark | light | dracula | nord
+prompt: "$ "                # Prompt string
+width: 700                  # SVG width in pixels (default: 700)
+
+steps:
+  - cmd: "notes --version"
+    output: "notes 1.0.0"
+
+  - cmd: "notes add 'Fix the login bug before Friday'"
+    output: "Added note #1"
+
+  - cmd: "notes --help"
+    output: |
+      Usage: notes [OPTIONS] COMMAND
+        add     Add a new note
+        list    List all notes
+        search  Search notes by keyword
+        done    Mark a note as done
+
+  - comment: "# Search works too"
+
+  - cmd: "notes search 'login'"
+    output: "#1  Fix the login bug before Friday"
+```
+
+Two step types: `cmd` (prompt + command + optional output) and `comment` (no prompt, styled like a code comment).
+
+---
+
+## Themes
+
+| Theme | Background | Based on |
+|-------|------------|----------|
+| `dark` | `#1e1e1e` | VS Code Dark+ (default) |
+| `light` | `#ffffff` | Clean light terminal |
+| `dracula` | `#282a36` | Dracula |
+| `nord` | `#2e3440` | Nord |
+
+```bash
+termstage themes
+```
+
+---
+
+## Animated SVG
+
+`--animated` generates a pure CSS animated SVG: commands type out character by character, output fades in after each one, cursor blinks. No JavaScript — works in GitHub READMEs and anywhere SVG is supported.
+
+```bash
+termstage render demo.yaml --animated -o demo-animated.svg
+```
+
+---
+
+## Window
+
+SVGs render with a macOS-style title bar (traffic light dots, centered title, rounded corners). Font stack: JetBrains Mono, Fira Code, Cascadia Code, monospace.
+
+---
+
+## Examples
+
+```bash
+termstage init
+termstage render demo.yaml -o demo.svg
+termstage render demo.yaml --animated -o demo-animated.svg
+```
+
+---
+
+## License
+
+MIT

termstage-0.1.0/README.md

@@ -0,0 +1,146 @@
+# termstage
+
+Fake terminal demos. Write a YAML file describing the session, run `termstage render`, get an SVG. No recording, no live shell, no asciinema.
+
+Good for README headers and docs where you want to show what a CLI looks like without screenshotting your actual terminal.
+
+---
+
+## Install
+
+```bash
+pip install termstage
+# or
+uv add termstage
+```
+
+## Quick Start
+
+**1. Write a demo YAML:**
+
+```yaml
+# demo.yaml
+title: "notes — a simple CLI notes app"
+theme: dark
+prompt: "$ "
+width: 700
+
+steps:
+  - cmd: "notes --version"
+    output: "notes 1.0.0"
+  - cmd: "notes add 'Fix the login bug before Friday'"
+    output: "Added note #1"
+  - cmd: "notes list"
+    output: |
+      #1  Fix the login bug before Friday
+  - comment: "# Search works too"
+  - cmd: "notes search 'login'"
+    output: "#1  Fix the login bug before Friday"
+```
+
+**2. Render:**
+
+```bash
+termstage render demo.yaml            # → demo.svg
+termstage render demo.yaml -o out.svg
+termstage render demo.yaml --animated # CSS typewriter animation
+```
+
+**3. Preview:**
+
+```bash
+termstage preview demo.yaml
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `termstage render <file.yaml>` | Render static SVG |
+| `termstage render <file.yaml> -o out.svg` | Custom output path |
+| `termstage render <file.yaml> --animated` | Animated CSS typewriter SVG |
+| `termstage init` | Create a starter `demo.yaml` in current directory |
+| `termstage themes` | List available themes |
+| `termstage preview <file.yaml>` | Render and open in browser |
+
+---
+
+## YAML Format
+
+```yaml
+title: "my cli demo"        # Window title bar text
+theme: dark                 # dark | light | dracula | nord
+prompt: "$ "                # Prompt string
+width: 700                  # SVG width in pixels (default: 700)
+
+steps:
+  - cmd: "notes --version"
+    output: "notes 1.0.0"
+
+  - cmd: "notes add 'Fix the login bug before Friday'"
+    output: "Added note #1"
+
+  - cmd: "notes --help"
+    output: |
+      Usage: notes [OPTIONS] COMMAND
+        add     Add a new note
+        list    List all notes
+        search  Search notes by keyword
+        done    Mark a note as done
+
+  - comment: "# Search works too"
+
+  - cmd: "notes search 'login'"
+    output: "#1  Fix the login bug before Friday"
+```
+
+Two step types: `cmd` (prompt + command + optional output) and `comment` (no prompt, styled like a code comment).
+
+---
+
+## Themes
+
+| Theme | Background | Based on |
+|-------|------------|----------|
+| `dark` | `#1e1e1e` | VS Code Dark+ (default) |
+| `light` | `#ffffff` | Clean light terminal |
+| `dracula` | `#282a36` | Dracula |
+| `nord` | `#2e3440` | Nord |
+
+```bash
+termstage themes
+```
+
+---
+
+## Animated SVG
+
+`--animated` generates a pure CSS animated SVG: commands type out character by character, output fades in after each one, cursor blinks. No JavaScript — works in GitHub READMEs and anywhere SVG is supported.
+
+```bash
+termstage render demo.yaml --animated -o demo-animated.svg
+```
+
+---
+
+## Window
+
+SVGs render with a macOS-style title bar (traffic light dots, centered title, rounded corners). Font stack: JetBrains Mono, Fira Code, Cascadia Code, monospace.
+
+---
+
+## Examples
+
+```bash
+termstage init
+termstage render demo.yaml -o demo.svg
+termstage render demo.yaml --animated -o demo-animated.svg
+```
+
+---
+
+## License
+
+MIT

termstage-0.1.0/examples/demo.yaml

@@ -0,0 +1,27 @@
+title: "notes — a simple CLI notes app"
+theme: dark
+prompt: "$ "
+width: 700
+
+steps:
+  - cmd: "notes --version"
+    output: "notes 1.0.0"
+
+  - cmd: "notes add 'Fix the login bug before Friday'"
+    output: "Added note #1"
+
+  - cmd: "notes add 'Review pull request from @alice'"
+    output: "Added note #2"
+
+  - cmd: "notes list"
+    output: |
+      #1  Fix the login bug before Friday
+      #2  Review pull request from @alice
+
+  - comment: "# Search works too"
+
+  - cmd: "notes search 'login'"
+    output: "#1  Fix the login bug before Friday"
+
+  - cmd: "notes done 1"
+    output: "Marked #1 as done"

termstage-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "termstage"
+version = "0.1.0"
+description = "Fake terminal demos. YAML in, SVG out. No recording."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.9",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+termstage = "termstage.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/termstage"]

termstage-0.1.0/src/termstage/__init__.py

@@ -0,0 +1,3 @@
+"""termstage — Generate polished terminal demo SVGs from YAML."""
+
+__version__ = "0.1.0"

termstage-0.1.0/src/termstage/animator.py

@@ -0,0 +1,257 @@
+"""CSS keyframe-based animated SVG generation for termstage."""
+
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from .themes import (
+    COMMENT_COLOR,
+    FONT_FAMILY,
+    FONT_SIZE,
+    LINE_HEIGHT,
+    OUTPUT_COLOR,
+    PADDING,
+    THEMES,
+    TITLE_BAR_HEIGHT,
+)
+
+# Characters per second for typing animation
+CHARS_PER_SEC = 30
+# Seconds for output fade-in
+FADE_DURATION = 0.4
+# Seconds pause after each step before next starts
+STEP_PAUSE = 0.3
+
+
+def _escape(text: str) -> str:
+    return html.escape(text, quote=True)
+
+
+def _count_lines(steps: list[dict]) -> int:
+    total = 0
+    for i, step in enumerate(steps):
+        if "comment" in step:
+            total += 1
+        elif "cmd" in step:
+            total += 1
+            output = step.get("output", "")
+            if output:
+                total += len(output.rstrip("\n").split("\n"))
+        if i < len(steps) - 1:
+            total += 1
+    return total
+
+
+def _render_title_bar(width: int, title: str, theme: dict) -> str:
+    dots_y = TITLE_BAR_HEIGHT // 2
+    dots_html = ""
+    if theme.get("dots", True):
+        dot_colors = ["#ff5f57", "#febc2e", "#28c840"]
+        dot_x_start = 16
+        dot_spacing = 20
+        for i, color in enumerate(dot_colors):
+            cx = dot_x_start + i * dot_spacing
+            dots_html += f'<circle cx="{cx}" cy="{dots_y}" r="6" fill="{color}" />\n    '
+
+    title_x = width // 2
+    title_svg = (
+        f'<text x="{title_x}" y="{dots_y + 5}" '
+        f'font-family={FONT_FAMILY!r} font-size="13" '
+        f'fill="{theme["text"]}" opacity="0.7" '
+        f'text-anchor="middle" dominant-baseline="middle">'
+        f"{_escape(title)}</text>"
+    )
+
+    return f"""    <!-- Title bar -->
+    <rect x="0" y="0" width="{width}" height="{TITLE_BAR_HEIGHT}"
+          rx="8" ry="8" fill="{theme['title_bar']}" />
+    <rect x="0" y="{TITLE_BAR_HEIGHT - 8}" width="{width}" height="8"
+          fill="{theme['title_bar']}" />
+    {dots_html}{title_svg}"""
+
+
+def _make_keyframes(anim_id: str, n_chars: int, start_s: float, duration_s: float) -> str:
+    """Generate @keyframes for a typewriter clip-path width expansion."""
+    # We use a clipPath trick: text is clipped by a rect whose width grows.
+    # Each character is ~ch wide; we animate max-width via clip-path.
+    # Actually we'll use the 'steps()' timing function with clip-path width.
+    # The animation: from width=0 to width=full_width over duration_s
+    # with steps(n_chars, end) for discrete character reveals.
+    steps_fn = f"steps({max(n_chars, 1)}, end)"
+    delay_s = start_s
+
+    return (
+        f"  @keyframes type-{anim_id} {{\n"
+        f"    from {{ clip-path: inset(0 100% 0 0); }}\n"
+        f"    to   {{ clip-path: inset(0 0% 0 0); }}\n"
+        f"  }}\n"
+        f"  .type-{anim_id} {{\n"
+        f"    clip-path: inset(0 100% 0 0);\n"
+        f"    animation: type-{anim_id} {duration_s:.3f}s {steps_fn} {delay_s:.3f}s forwards;\n"
+        f"  }}\n"
+    )
+
+
+def _make_fade_keyframes(anim_id: str, start_s: float) -> str:
+    return (
+        f"  @keyframes fade-{anim_id} {{\n"
+        f"    from {{ opacity: 0; }}\n"
+        f"    to   {{ opacity: 1; }}\n"
+        f"  }}\n"
+        f"  .fade-{anim_id} {{\n"
+        f"    opacity: 0;\n"
+        f"    animation: fade-{anim_id} {FADE_DURATION:.2f}s ease {start_s:.3f}s forwards;\n"
+        f"  }}\n"
+    )
+
+
+def _make_cursor_keyframes(anim_id: str, start_s: float, end_s: float) -> str:
+    """Cursor blinks during typing, then disappears."""
+    return (
+        f"  @keyframes blink-{anim_id} {{\n"
+        f"    0%, 49% {{ opacity: 1; }}\n"
+        f"    50%, 100% {{ opacity: 0; }}\n"
+        f"  }}\n"
+        f"  .cursor-{anim_id} {{\n"
+        f"    opacity: 0;\n"
+        f"    animation:\n"
+        f"      blink-{anim_id} 0.6s step-end {start_s:.3f}s {int((end_s - start_s) / 0.6) + 1},\n"
+        f"      fade-{anim_id}-out 0.01s linear {end_s:.3f}s forwards;\n"
+        f"  }}\n"
+        f"  @keyframes fade-{anim_id}-out {{\n"
+        f"    to {{ opacity: 0; }}\n"
+        f"  }}\n"
+    )
+
+
+def render_animated_svg(config: dict[str, Any]) -> str:
+    """
+    Render an animated SVG terminal window from config dict.
+    Uses CSS @keyframes for typewriter + fade-in effects. No JS.
+    """
+    title = config.get("title", "termstage demo")
+    theme_name = config.get("theme", "dark")
+    prompt = config.get("prompt", "$ ")
+    width = int(config.get("width", 700))
+    steps = config.get("steps", [])
+
+    theme = THEMES.get(theme_name, THEMES["dark"])
+
+    n_lines = _count_lines(steps)
+    body_height = PADDING + n_lines * LINE_HEIGHT + PADDING
+    total_height = TITLE_BAR_HEIGHT + body_height
+
+    keyframes_parts: list[str] = []
+    elements: list[str] = []
+
+    y = TITLE_BAR_HEIGHT + PADDING + LINE_HEIGHT
+    time_cursor = 0.5  # slight initial pause
+
+    anim_counter = 0
+
+    for i, step in enumerate(steps):
+        if "comment" in step:
+            comment_text = step["comment"]
+            aid = f"c{anim_counter}"
+            anim_counter += 1
+            n_chars = len(comment_text)
+            duration = n_chars / CHARS_PER_SEC
+
+            keyframes_parts.append(_make_keyframes(aid, n_chars, time_cursor, duration))
+            time_cursor += duration
+
+            elements.append(
+                f'    <text x="{PADDING}" y="{y}" '
+                f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                f'fill="{COMMENT_COLOR}" xml:space="preserve" class="type-{aid}">'
+                f"{_escape(comment_text)}</text>"
+            )
+            y += LINE_HEIGHT
+            time_cursor += STEP_PAUSE
+
+        elif "cmd" in step:
+            cmd = step["cmd"]
+            output = step.get("output", "")
+
+            full_line = prompt + cmd
+            aid = f"cmd{anim_counter}"
+            anim_counter += 1
+            n_chars = len(full_line)
+            duration = n_chars / CHARS_PER_SEC
+
+            # Cursor appears at start of typing, disappears at end
+            cursor_end = time_cursor + duration
+            keyframes_parts.append(_make_keyframes(aid, n_chars, time_cursor, duration))
+            keyframes_parts.append(
+                _make_cursor_keyframes(aid, time_cursor, cursor_end)
+            )
+
+            # Cursor x position: after the text. Approximate at font-size * 0.6 per char
+            char_width = FONT_SIZE * 0.61
+            cursor_x = PADDING + n_chars * char_width
+
+            elements.append(
+                f'    <text x="{PADDING}" y="{y}" '
+                f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                f'xml:space="preserve" class="type-{aid}">'
+                f'<tspan fill="{theme["prompt"]}">{_escape(prompt)}</tspan>'
+                f'<tspan fill="{theme["text"]}">{_escape(cmd)}</tspan>'
+                f"</text>"
+            )
+            # Cursor rect (blinking block)
+            elements.append(
+                f'    <rect x="{cursor_x:.1f}" y="{y - FONT_SIZE}" '
+                f'width="{char_width:.1f}" height="{FONT_SIZE + 2}" '
+                f'fill="{theme["text"]}" opacity="0.7" class="cursor-{aid}" />'
+            )
+
+            time_cursor = cursor_end
+            y += LINE_HEIGHT
+
+            if output:
+                output_lines = output.rstrip("\n").split("\n")
+                # Fade in all output lines together
+                oid = f"out{anim_counter}"
+                anim_counter += 1
+                keyframes_parts.append(_make_fade_keyframes(oid, time_cursor))
+                time_cursor += FADE_DURATION
+
+                for line in output_lines:
+                    elements.append(
+                        f'    <text x="{PADDING}" y="{y}" '
+                        f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                        f'fill="{OUTPUT_COLOR}" xml:space="preserve" class="fade-{oid}">'
+                        f"{_escape(line)}</text>"
+                    )
+                    y += LINE_HEIGHT
+
+        # blank gap between steps
+        if i < len(steps) - 1:
+            y += LINE_HEIGHT
+            time_cursor += STEP_PAUSE
+
+    title_bar_svg = _render_title_bar(width, title, theme)
+    keyframes_css = "\n".join(keyframes_parts)
+    elements_joined = "\n".join(elements)
+
+    svg = f"""<svg xmlns="http://www.w3.org/2000/svg"
+     width="{width}" height="{total_height}"
+     viewBox="0 0 {width} {total_height}">
+  <style>
+{keyframes_css}
+  </style>
+  <!-- Window frame -->
+  <rect x="0" y="0" width="{width}" height="{total_height}"
+        rx="8" ry="8" fill="{theme['bg']}" />
+{title_bar_svg}
+  <!-- Terminal body -->
+  <clipPath id="body-clip">
+    <rect x="0" y="{TITLE_BAR_HEIGHT}" width="{width}" height="{body_height}" />
+  </clipPath>
+  <g clip-path="url(#body-clip)">
+{elements_joined}
+  </g>
+</svg>
+"""
+    return svg

termstage-0.1.0/src/termstage/cli.py

@@ -0,0 +1,160 @@
+"""termstage CLI — typer app."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+import yaml
+
+from .animator import render_animated_svg
+from .renderer import render_svg
+from .themes import THEMES
+
+app = typer.Typer(
+    name="termstage",
+    help="Generate polished terminal demo SVGs from YAML — no recording required.",
+    add_completion=False,
+)
+
+
+def _load_yaml(path: Path) -> dict:
+    try:
+        with path.open() as f:
+            return yaml.safe_load(f)
+    except FileNotFoundError:
+        typer.echo(f"Error: file not found: {path}", err=True)
+        raise typer.Exit(1)
+    except yaml.YAMLError as e:
+        typer.echo(f"Error: invalid YAML: {e}", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def render(
+    input_file: Annotated[Path, typer.Argument(help="Input YAML file")],
+    output: Annotated[
+        Optional[Path],
+        typer.Option("-o", "--output", help="Output SVG file (default: <input>.svg)"),
+    ] = None,
+    animated: Annotated[
+        bool, typer.Option("--animated", help="Generate animated CSS typewriter SVG")
+    ] = False,
+):
+    """Render a terminal demo SVG from a YAML file."""
+    config = _load_yaml(input_file)
+
+    if animated:
+        svg_content = render_animated_svg(config)
+    else:
+        svg_content = render_svg(config)
+
+    if output is None:
+        output = input_file.with_suffix(".svg")
+
+    output.write_text(svg_content, encoding="utf-8")
+    typer.echo(f"✅ Rendered {'animated ' if animated else ''}SVG → {output}")
+
+
+@app.command()
+def init(
+    output: Annotated[
+        Path,
+        typer.Argument(help="Output YAML file (default: demo.yaml)"),
+    ] = Path("demo.yaml"),
+):
+    """Scaffold a demo.yaml in the current directory."""
+    if output.exists():
+        overwrite = typer.confirm(f"{output} already exists. Overwrite?")
+        if not overwrite:
+            raise typer.Exit(0)
+
+    content = """\
+title: "My CLI Demo"
+theme: dark          # dark | light | dracula | nord
+prompt: "$ "
+width: 700
+
+steps:
+  - comment: "# Welcome to termstage — terminal demos without recording"
+
+  - cmd: "mytool encode 37.7749 -122.4194"
+    output: "8928308280fffff"
+
+  - cmd: "mytool --help"
+    output: |
+      Usage: mytool [OPTIONS] COMMAND
+
+        encode    Encode lat/lng to H3 cell ID
+        decode    Decode H3 cell ID to lat/lng
+
+      Options:
+        --help    Show this message and exit.
+
+  - comment: "# Supports batch mode too"
+
+  - cmd: "mytool encode --batch coords.csv"
+    output: "Processed 1000 rows → output.jsonl"
+"""
+    output.write_text(content, encoding="utf-8")
+    typer.echo(f"✅ Created {output}")
+    typer.echo("Run: termstage render demo.yaml")
+
+
+@app.command()
+def themes():
+    """List available themes."""
+    typer.echo("Available themes:\n")
+    for name, config in THEMES.items():
+        bg = config["bg"]
+        prompt = config["prompt"]
+        typer.echo(f"  {name:<10}  bg={bg}  prompt={prompt}")
+    typer.echo(
+        "\nUsage: set `theme: <name>` in your YAML file, or pass --theme on the CLI."
+    )
+
+
+@app.command()
+def preview(
+    input_file: Annotated[Path, typer.Argument(help="Input YAML file")],
+    animated: Annotated[
+        bool, typer.Option("--animated", help="Generate animated CSS typewriter SVG")
+    ] = False,
+):
+    """Render the SVG and open it in the default browser."""
+    import tempfile
+
+    config = _load_yaml(input_file)
+
+    if animated:
+        svg_content = render_animated_svg(config)
+    else:
+        svg_content = render_svg(config)
+
+    # Write to a temp file and open it
+    suffix = ".svg"
+    with tempfile.NamedTemporaryFile(
+        delete=False, suffix=suffix, mode="w", encoding="utf-8"
+    ) as f:
+        f.write(svg_content)
+        tmp_path = f.name
+
+    typer.echo(f"Opening preview: {tmp_path}")
+
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(["open", tmp_path], check=True)
+        elif sys.platform == "win32":
+            subprocess.run(["start", tmp_path], shell=True, check=True)
+        else:
+            subprocess.run(["xdg-open", tmp_path], check=True)
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        typer.echo(f"Could not open browser: {e}", err=True)
+        typer.echo(f"SVG saved at: {tmp_path}")
+
+
+if __name__ == "__main__":
+    app()

termstage-0.1.0/src/termstage/renderer.py

@@ -0,0 +1,159 @@
+"""Pure Python SVG generation for termstage (static rendering)."""
+
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from .themes import (
+    COMMENT_COLOR,
+    FONT_FAMILY,
+    FONT_SIZE,
+    LINE_HEIGHT,
+    OUTPUT_COLOR,
+    PADDING,
+    THEMES,
+    TITLE_BAR_HEIGHT,
+)
+
+
+def _escape(text: str) -> str:
+    """HTML-escape text for safe SVG embedding."""
+    return html.escape(text, quote=True)
+
+
+def _count_lines(steps: list[dict]) -> int:
+    """Count total rendered lines across all steps."""
+    total = 0
+    for i, step in enumerate(steps):
+        if "comment" in step:
+            total += 1
+        elif "cmd" in step:
+            total += 1  # prompt + cmd line
+            output = step.get("output", "")
+            if output:
+                total += len(output.rstrip("\n").split("\n"))
+        # blank line gap between steps (not after last)
+        if i < len(steps) - 1:
+            total += 1
+    return total
+
+
+def _render_title_bar(width: int, title: str, theme: dict) -> str:
+    """Render the macOS-style title bar."""
+    bar_y = 0
+    dots_y = TITLE_BAR_HEIGHT // 2
+
+    dots_html = ""
+    if theme.get("dots", True):
+        dot_colors = ["#ff5f57", "#febc2e", "#28c840"]
+        dot_x_start = 16
+        dot_spacing = 20
+        for i, color in enumerate(dot_colors):
+            cx = dot_x_start + i * dot_spacing
+            dots_html += (
+                f'<circle cx="{cx}" cy="{dots_y}" r="6" fill="{color}" />\n    '
+            )
+
+    title_x = width // 2
+    title_svg = (
+        f'<text x="{title_x}" y="{dots_y + 5}" '
+        f'font-family={FONT_FAMILY!r} font-size="13" '
+        f'fill="{theme["text"]}" opacity="0.7" '
+        f'text-anchor="middle" dominant-baseline="middle">'
+        f"{_escape(title)}</text>"
+    )
+
+    return f"""    <!-- Title bar -->
+    <rect x="0" y="{bar_y}" width="{width}" height="{TITLE_BAR_HEIGHT}"
+          rx="8" ry="8" fill="{theme['title_bar']}" />
+    <!-- Fake bottom corners for title bar -->
+    <rect x="0" y="{TITLE_BAR_HEIGHT - 8}" width="{width}" height="8"
+          fill="{theme['title_bar']}" />
+    {dots_html}{title_svg}"""
+
+
+def render_svg(config: dict[str, Any]) -> str:
+    """
+    Render a static SVG terminal window from config dict.
+
+    config keys:
+      title, theme, prompt, width, steps
+    """
+    title = config.get("title", "termstage demo")
+    theme_name = config.get("theme", "dark")
+    prompt = config.get("prompt", "$ ")
+    width = int(config.get("width", 700))
+    steps = config.get("steps", [])
+
+    theme = THEMES.get(theme_name, THEMES["dark"])
+
+    # Calculate height
+    n_lines = _count_lines(steps)
+    body_height = PADDING + n_lines * LINE_HEIGHT + PADDING
+    total_height = TITLE_BAR_HEIGHT + body_height
+
+    lines_svg = []
+    y = TITLE_BAR_HEIGHT + PADDING + LINE_HEIGHT  # baseline y of first line
+
+    for i, step in enumerate(steps):
+        if "comment" in step:
+            comment_text = step["comment"]
+            lines_svg.append(
+                f'    <text x="{PADDING}" y="{y}" '
+                f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                f'fill="{COMMENT_COLOR}" xml:space="preserve">'
+                f"{_escape(comment_text)}</text>"
+            )
+            y += LINE_HEIGHT
+
+        elif "cmd" in step:
+            cmd = step["cmd"]
+            output = step.get("output", "")
+
+            # Render prompt + command on same line using tspan
+            lines_svg.append(
+                f'    <text x="{PADDING}" y="{y}" '
+                f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                f'xml:space="preserve">'
+                f'<tspan fill="{theme["prompt"]}">{_escape(prompt)}</tspan>'
+                f'<tspan fill="{theme["text"]}">{_escape(cmd)}</tspan>'
+                f"</text>"
+            )
+            y += LINE_HEIGHT
+
+            if output:
+                for line in output.rstrip("\n").split("\n"):
+                    lines_svg.append(
+                        f'    <text x="{PADDING}" y="{y}" '
+                        f'font-family={FONT_FAMILY!r} font-size="{FONT_SIZE}" '
+                        f'fill="{OUTPUT_COLOR}" xml:space="preserve">'
+                        f"{_escape(line)}</text>"
+                    )
+                    y += LINE_HEIGHT
+
+        # blank gap between steps
+        if i < len(steps) - 1:
+            y += LINE_HEIGHT
+
+    title_bar_svg = _render_title_bar(width, title, theme)
+    lines_joined = "\n".join(lines_svg)
+
+    svg = f"""<svg xmlns="http://www.w3.org/2000/svg"
+     width="{width}" height="{total_height}"
+     viewBox="0 0 {width} {total_height}">
+  <!-- Window frame -->
+  <rect x="0" y="0" width="{width}" height="{total_height}"
+        rx="8" ry="8" fill="{theme['bg']}" />
+{title_bar_svg}
+  <!-- Terminal body -->
+  <clipPath id="body-clip">
+    <rect x="0" y="{TITLE_BAR_HEIGHT}" width="{width}" height="{body_height}"
+          rx="0" ry="0" />
+  </clipPath>
+  <g clip-path="url(#body-clip)">
+{lines_joined}
+  </g>
+</svg>
+"""
+    return svg

termstage-0.1.0/src/termstage/themes.py

@@ -0,0 +1,40 @@
+"""Terminal color themes for termstage."""
+
+THEMES: dict[str, dict] = {
+    "dark": {
+        "bg": "#1e1e1e",
+        "title_bar": "#323233",
+        "text": "#d4d4d4",
+        "prompt": "#4ec9b0",
+        "dots": True,
+    },
+    "light": {
+        "bg": "#ffffff",
+        "title_bar": "#e0e0e0",
+        "text": "#333333",
+        "prompt": "#007acc",
+        "dots": True,
+    },
+    "dracula": {
+        "bg": "#282a36",
+        "title_bar": "#44475a",
+        "text": "#f8f8f2",
+        "prompt": "#50fa7b",
+        "dots": True,
+    },
+    "nord": {
+        "bg": "#2e3440",
+        "title_bar": "#3b4252",
+        "text": "#eceff4",
+        "prompt": "#88c0d0",
+        "dots": True,
+    },
+}
+
+COMMENT_COLOR = "#6a9955"
+OUTPUT_COLOR = "#aaaaaa"
+FONT_FAMILY = "'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace"
+FONT_SIZE = 14
+LINE_HEIGHT = 22
+TITLE_BAR_HEIGHT = 38
+PADDING = 20