protoreel 0.1.0__tar.gz

protoreel-0.1.0/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "includeCoAuthoredBy": false
+}

protoreel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+          uv run python -m playwright install --with-deps chromium
+      - name: Lint
+        run: |
+          uv run ruff check src tests
+          uv run ruff format --check src tests
+      - name: Test
+        run: uv run pytest -q

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

@@ -0,0 +1,31 @@
+name: Release
+
+# Push a tag like v0.2.0 to build Protoreel and publish it to PyPI.
+# One-time setup: on pypi.org, add this repository as a "trusted publisher"
+# (workflow: release.yml, environment: pypi). No API token is needed.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # lets PyPI verify this workflow instead of using a password
+      contents: write   # lets the job create the GitHub release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check the tag matches the package version
+        run: |
+          version=$(grep -oP '__version__ = "\K[^"]+' src/protoreel/__init__.py)
+          test "v$version" = "${GITHUB_REF_NAME}" || { echo "Tag ${GITHUB_REF_NAME} does not match version $version"; exit 1; }
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --title "${GITHUB_REF_NAME}" --notes-file CHANGELOG.md

protoreel-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+renders/
+takes/
+.DS_Store

protoreel-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 — 2026-10-13
+
+First open-source release, grown out of a personal "Recorder Studio" script.
+
+- MCP server with `list_workspace`, `record_video`, `render_take`, `preview_frame`, `open_studio` and `check_setup`
+- Studio web app for hand-captured takes; takes are now saved to `takes/` so they can be re-rendered later
+- Scripts gain `click`, `hover`, `type` and `scroll` actions, CSS-selector points, and late element lookup
+- Bundled ffmpeg fallback and automatic Chromium install
+- Six social formats from 1080 to 4K, optional backdrop and caption, prototype sound

protoreel-0.1.0/CLAUDE.md

@@ -0,0 +1,32 @@
+# Protoreel — notes for Claude Code
+
+Protoreel films HTML prototypes into social videos. It is a Python package with a CLI, an MCP
+server and a small web Studio. Read `docs/architecture.md` for the map of modules.
+
+## Strict rule: authorship
+
+Never add Claude, Claude Code or Cowork as an author or co-author of anything in this project.
+No `Co-Authored-By` trailers, no "Generated with Claude Code" lines in commits, pull requests,
+releases or files. Commits are authored by the repository owner only.
+
+## Commands
+
+```bash
+uv venv && source .venv/bin/activate && uv pip install -e ".[dev]"   # set up
+python -m playwright install chromium                               # once per machine
+pytest -q                                                            # ~30 s, real renders
+ruff check src tests && ruff format src tests                        # lint + format
+protoreel studio --folder ~/Playwright                               # run the Studio
+protoreel record examples/like-button.html examples/like-button.json # scripted render
+```
+
+## Conventions
+
+- Keep it readable for a junior developer: one job per module, plain names, short docstrings,
+  comments that explain *why*.
+- Never print to stdout from code the MCP server runs: stdout carries the MCP protocol.
+  Progress goes to stderr (CLI) or `ctx.report_progress` (MCP).
+- Errors a user can fix raise `ValueError` / `FileNotFoundError` with a helpful message;
+  `mcp_server.user_errors` passes those messages through to the AI client.
+- The MCP SDK is v2 (`mcp.server.mcpserver.MCPServer`), not v1's `FastMCP`.
+- Version lives in `src/protoreel/__init__.py`; update `CHANGELOG.md` with it.

protoreel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for helping! Protoreel aims to stay small and readable, so a new contributor can
+understand any file in one sitting.
+
+## Set up
+
+```bash
+git clone https://github.com/iamkingsleey/protoreel && cd protoreel
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+python -m playwright install chromium
+pytest
+```
+
+## House rules
+
+- **Name things for what they mean** to someone making videos (`take`, `frame`, `format`), not how they're implemented.
+- **One job per module.** If a file starts doing two things, split it. [docs/architecture.md](docs/architecture.md) is the map; update it when the map changes.
+- **Explain why, not what,** in comments. Short docstrings on every public function.
+- **Readable errors.** Anything a user can fix should say what went wrong and what to do.
+- `ruff check` and `ruff format` before you push; CI runs both, plus the tests.
+
+## Making a release
+
+1. Bump `__version__` in `src/protoreel/__init__.py` and add a section to `CHANGELOG.md`.
+2. Commit, then tag: `git tag v0.2.0 && git push --tags`.
+3. The *Release* workflow builds the package and publishes it to PyPI.

protoreel-0.1.0/HANDOFF.md

@@ -0,0 +1,21 @@
+# Handing Protoreel to Claude Code
+
+Open Terminal and run:
+
+```bash
+cd ~/Playwright/protoreel
+claude
+```
+
+Then paste this prompt:
+
+> Read CLAUDE.md and docs/architecture.md, and follow its authorship rule strictly: never add
+> yourself as a co-author or add "Generated with Claude" lines anywhere. Then ship Protoreel for me by running
+> `scripts/ship.sh ~/Playwright`. If a step fails, fix the cause and re-run the script
+> (it is safe to re-run). If GitHub login is needed, ask me to run `gh auth login`.
+> When it finishes, walk me through the PyPI "pending publisher" step it prints, then push
+> the v0.1.0 tag and watch the Release workflow until it succeeds. Finally, confirm the
+> MCP server works by listing the protoreel tools.
+
+That's it. After this, you never need `Recorder.command` again: ask Claude to
+"open the Protoreel studio", or to record a prototype for you.

protoreel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kingsley Mkpandiok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

protoreel-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: protoreel
+Version: 0.1.0
+Summary: Turn HTML prototypes into frame-perfect social videos — from a Studio app or any MCP client.
+Project-URL: Homepage, https://github.com/iamkingsleey/protoreel
+Project-URL: Issues, https://github.com/iamkingsleey/protoreel/issues
+Author: Kingsley Mkpandiok
+License-Expression: MIT
+License-File: LICENSE
+Keywords: animation,design,mcp,playwright,prototype,screen-recording,video
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: playwright>=1.45
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Protoreel
+
+**Turn HTML prototypes into frame-perfect social videos — by hand in a small Studio app, or by asking your AI assistant.**
+
+Protoreel opens your prototype in a headless browser, plays an interaction (clicks, drags, typing, scrolling) with a smooth on-screen cursor, and films it one frame at a time into an MP4. Because the page's clock only moves when Protoreel says so, videos never stutter or drop frames, whatever machine you run them on. If your prototype makes sound, the sound comes along too.
+
+- **Six social formats** — 4:5 feed, 9:16 reels, 1:1, 16:9, and two Dribbble sizes — up to 4K
+- **An MCP server** — Claude, Cursor, VS Code and other MCP clients can record videos for you
+- **A Studio app** — perform the interaction yourself, then render it in any format
+- **Sound** — prototypes can hand Protoreel their audio, mixed under the video
+- **No setup beyond one command** — Chromium and ffmpeg are fetched for you
+
+---
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) (one line to install). Then:
+
+```bash
+uvx protoreel setup --folder ~/Prototypes
+```
+
+That downloads Chromium (once), creates the folder, and prints the config for your AI client. Put your `.html` prototypes in that folder.
+
+### Use it from Claude, Cursor or VS Code (MCP)
+
+**Claude Desktop / Cowork** — open *Settings → Developer → Edit Config* and add:
+
+```json
+{
+  "mcpServers": {
+    "protoreel": {
+      "command": "uvx",
+      "args": ["protoreel", "mcp", "--folder", "/Users/you/Prototypes"]
+    }
+  }
+}
+```
+
+If Claude says it can't start the server, replace `"uvx"` with the full path that `which uvx` prints (desktop apps don't always see your shell's PATH). `protoreel setup` prints the snippet with the full path filled in.
+
+**Claude Code**
+
+```bash
+claude mcp add protoreel -- uvx protoreel mcp --folder ~/Prototypes
+```
+
+**Cursor** (`.cursor/mcp.json`) uses the same block as Claude Desktop. **VS Code** (`.vscode/mcp.json`) uses the key `"servers"` instead of `"mcpServers"`.
+
+Restart the app, then just ask:
+
+> *"Record checkout.html as a 9:16 video: tap the Add to bag button, wait a second, then open the bag."*
+
+> *"Open the Protoreel studio for like-button.html so I can record it myself."*
+
+> *"Re-render my last take as a 4:5 and a 16:9."*
+
+### Use the Studio yourself
+
+```bash
+uvx protoreel studio --folder ~/Prototypes
+```
+
+Pick a prototype, choose a format, press **Capture**, perform the interaction with your mouse, press **Esc**, then **Render**. Every take is saved to `takes/`, so you (or your AI assistant) can render it again later in another format.
+
+### Use the command line
+
+```bash
+uvx protoreel record like-button.html examples/like-button.json --format 9x16 --zoom 2.4
+uvx protoreel render-take like-button_20261013-101500.json --format 16x9 --res 4k
+```
+
+---
+
+## The MCP tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_workspace` | Lists prototypes, recent takes and recent videos |
+| `record_video` | Films a prototype following a script (below) |
+| `render_take` | Films a take captured in the Studio, in any format |
+| `preview_frame` | Returns one frame as an image, to check framing and zoom |
+| `open_studio` | Opens the Studio in your browser |
+| `check_setup` | Checks Chromium and ffmpeg (and can install Chromium) |
+
+## Scripts
+
+A script is a list of actions, played in order. Elements are found with CSS selectors *at the moment each action starts*, so menus that open mid-video work naturally.
+
+```json
+{
+  "start": ["80%", "85%"],
+  "actions": [
+    {"wait": 400},
+    {"click": "#add-to-bag", "dur": 800},
+    {"wait": 900},
+    {"type": "Lekki Phase 1", "delay": 60},
+    {"key": "Enter"},
+    {"drag": {"by": [0, -220]}, "dur": 900},
+    {"scroll": {"to": "#reviews"}, "dur": 1000},
+    {"wait": 1200}
+  ]
+}
+```
+
+| Action | Meaning |
+| --- | --- |
+| `{"wait": 500}` | hold still for 500 ms |
+| `{"move": POINT, "dur": 600}` / `{"hover": POINT}` | glide the pointer to a point |
+| `{"click": POINT, "dur": 500}` | glide there, then press and release (`{"click": true}` clicks in place) |
+| `{"drag": {"to": POINT} or {"by": [dx, dy]}, "dur": 900}` | press, move, release |
+| `{"down": true}` / `{"up": true}` | press or release in place |
+| `{"key": "Enter"}` | press a key ([names](https://playwright.dev/docs/api/class-keyboard#keyboard-press)) |
+| `{"type": "Hello", "delay": 70}` | type text, one character every 70 ms |
+| `{"scroll": {"by": [0, 400]} or {"to": POINT}, "dur": 800}` | scroll smoothly |
+
+A **POINT** is `[x, y]` in CSS pixels, `["50%", "60%"]` of the frame, `"#selector"`, or `{"el": "#selector", "x": 0.5, "y": 0.5}` for a spot inside an element. Any action can take `"ease"`: `smooth` (default, like a hand), `linear`, `in`, `out` or `inout`.
+
+## Formats and zoom
+
+| Format | Size at 1080 | Typical use |
+| --- | --- | --- |
+| `4x5` | 1080 × 1350 | Instagram / LinkedIn feed |
+| `9x16` | 1080 × 1920 | Reels, TikTok, Shorts |
+| `1x1` | 1080 × 1080 | Square |
+| `16x9` | 1920 × 1080 | Landscape, YouTube, X |
+| `4x3` | 1600 × 1200 | Dribbble |
+| `3x2` | 1800 × 1200 | Dribbble wide |
+
+**Zoom** (0.6–3.6, default 2) is how large the prototype appears: the page is laid out at *format ÷ zoom* CSS pixels and rendered sharply at that scale. **Resolution** (`1080`, `2k`, `3k`, `4k`) adds pixels without changing the framing.
+
+## Sound
+
+Headless browsers can't record their own audio, so prototypes that make sound opt in with one function:
+
+```js
+// Return a base64 WAV of the sounds that played between startMs and startMs + durationMs
+// (on the page's clock, i.e. performance.now()). A Promise of the string is fine too.
+window.__recorderAudio = function (startMs, durationMs) { /* ... */ };
+```
+
+The usual pattern is to log each sound as it plays and replay the log into an `OfflineAudioContext`. [`examples/like-button.html`](examples/like-button.html) shows the whole thing in about 15 lines. Pages without the function produce silent videos.
+
+## Folder layout
+
+```
+~/Prototypes/          your .html prototypes (full pages or bare fragments)
+~/Prototypes/renders/  finished videos
+~/Prototypes/takes/    takes captured in the Studio
+```
+
+Set the folder with `--folder`, or the `PROTOREEL_HOME` environment variable (default `~/Protoreel`).
+
+## Troubleshooting
+
+- **"Chromium is not installed"** — run `uvx protoreel setup`. Behind a strict network? Point `PROTOREEL_CHROMIUM` at an existing Chrome/Chromium.
+- **The Studio port is busy** — another Studio is probably running; `protoreel studio --port 8800` picks another.
+- **The video is silent** — the page doesn't define `window.__recorderAudio`; see *Sound*.
+- **Clicks miss** — use a selector rather than coordinates, and check with `preview_frame`.
+
+## Contributing
+
+Protoreel is small on purpose and written to be easy to read. Start with [docs/architecture.md](docs/architecture.md), then see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT © Kingsley Mkpandiok

protoreel-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Protoreel
+
+**Turn HTML prototypes into frame-perfect social videos — by hand in a small Studio app, or by asking your AI assistant.**
+
+Protoreel opens your prototype in a headless browser, plays an interaction (clicks, drags, typing, scrolling) with a smooth on-screen cursor, and films it one frame at a time into an MP4. Because the page's clock only moves when Protoreel says so, videos never stutter or drop frames, whatever machine you run them on. If your prototype makes sound, the sound comes along too.
+
+- **Six social formats** — 4:5 feed, 9:16 reels, 1:1, 16:9, and two Dribbble sizes — up to 4K
+- **An MCP server** — Claude, Cursor, VS Code and other MCP clients can record videos for you
+- **A Studio app** — perform the interaction yourself, then render it in any format
+- **Sound** — prototypes can hand Protoreel their audio, mixed under the video
+- **No setup beyond one command** — Chromium and ffmpeg are fetched for you
+
+---
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) (one line to install). Then:
+
+```bash
+uvx protoreel setup --folder ~/Prototypes
+```
+
+That downloads Chromium (once), creates the folder, and prints the config for your AI client. Put your `.html` prototypes in that folder.
+
+### Use it from Claude, Cursor or VS Code (MCP)
+
+**Claude Desktop / Cowork** — open *Settings → Developer → Edit Config* and add:
+
+```json
+{
+  "mcpServers": {
+    "protoreel": {
+      "command": "uvx",
+      "args": ["protoreel", "mcp", "--folder", "/Users/you/Prototypes"]
+    }
+  }
+}
+```
+
+If Claude says it can't start the server, replace `"uvx"` with the full path that `which uvx` prints (desktop apps don't always see your shell's PATH). `protoreel setup` prints the snippet with the full path filled in.
+
+**Claude Code**
+
+```bash
+claude mcp add protoreel -- uvx protoreel mcp --folder ~/Prototypes
+```
+
+**Cursor** (`.cursor/mcp.json`) uses the same block as Claude Desktop. **VS Code** (`.vscode/mcp.json`) uses the key `"servers"` instead of `"mcpServers"`.
+
+Restart the app, then just ask:
+
+> *"Record checkout.html as a 9:16 video: tap the Add to bag button, wait a second, then open the bag."*
+
+> *"Open the Protoreel studio for like-button.html so I can record it myself."*
+
+> *"Re-render my last take as a 4:5 and a 16:9."*
+
+### Use the Studio yourself
+
+```bash
+uvx protoreel studio --folder ~/Prototypes
+```
+
+Pick a prototype, choose a format, press **Capture**, perform the interaction with your mouse, press **Esc**, then **Render**. Every take is saved to `takes/`, so you (or your AI assistant) can render it again later in another format.
+
+### Use the command line
+
+```bash
+uvx protoreel record like-button.html examples/like-button.json --format 9x16 --zoom 2.4
+uvx protoreel render-take like-button_20261013-101500.json --format 16x9 --res 4k
+```
+
+---
+
+## The MCP tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_workspace` | Lists prototypes, recent takes and recent videos |
+| `record_video` | Films a prototype following a script (below) |
+| `render_take` | Films a take captured in the Studio, in any format |
+| `preview_frame` | Returns one frame as an image, to check framing and zoom |
+| `open_studio` | Opens the Studio in your browser |
+| `check_setup` | Checks Chromium and ffmpeg (and can install Chromium) |
+
+## Scripts
+
+A script is a list of actions, played in order. Elements are found with CSS selectors *at the moment each action starts*, so menus that open mid-video work naturally.
+
+```json
+{
+  "start": ["80%", "85%"],
+  "actions": [
+    {"wait": 400},
+    {"click": "#add-to-bag", "dur": 800},
+    {"wait": 900},
+    {"type": "Lekki Phase 1", "delay": 60},
+    {"key": "Enter"},
+    {"drag": {"by": [0, -220]}, "dur": 900},
+    {"scroll": {"to": "#reviews"}, "dur": 1000},
+    {"wait": 1200}
+  ]
+}
+```
+
+| Action | Meaning |
+| --- | --- |
+| `{"wait": 500}` | hold still for 500 ms |
+| `{"move": POINT, "dur": 600}` / `{"hover": POINT}` | glide the pointer to a point |
+| `{"click": POINT, "dur": 500}` | glide there, then press and release (`{"click": true}` clicks in place) |
+| `{"drag": {"to": POINT} or {"by": [dx, dy]}, "dur": 900}` | press, move, release |
+| `{"down": true}` / `{"up": true}` | press or release in place |
+| `{"key": "Enter"}` | press a key ([names](https://playwright.dev/docs/api/class-keyboard#keyboard-press)) |
+| `{"type": "Hello", "delay": 70}` | type text, one character every 70 ms |
+| `{"scroll": {"by": [0, 400]} or {"to": POINT}, "dur": 800}` | scroll smoothly |
+
+A **POINT** is `[x, y]` in CSS pixels, `["50%", "60%"]` of the frame, `"#selector"`, or `{"el": "#selector", "x": 0.5, "y": 0.5}` for a spot inside an element. Any action can take `"ease"`: `smooth` (default, like a hand), `linear`, `in`, `out` or `inout`.
+
+## Formats and zoom
+
+| Format | Size at 1080 | Typical use |
+| --- | --- | --- |
+| `4x5` | 1080 × 1350 | Instagram / LinkedIn feed |
+| `9x16` | 1080 × 1920 | Reels, TikTok, Shorts |
+| `1x1` | 1080 × 1080 | Square |
+| `16x9` | 1920 × 1080 | Landscape, YouTube, X |
+| `4x3` | 1600 × 1200 | Dribbble |
+| `3x2` | 1800 × 1200 | Dribbble wide |
+
+**Zoom** (0.6–3.6, default 2) is how large the prototype appears: the page is laid out at *format ÷ zoom* CSS pixels and rendered sharply at that scale. **Resolution** (`1080`, `2k`, `3k`, `4k`) adds pixels without changing the framing.
+
+## Sound
+
+Headless browsers can't record their own audio, so prototypes that make sound opt in with one function:
+
+```js
+// Return a base64 WAV of the sounds that played between startMs and startMs + durationMs
+// (on the page's clock, i.e. performance.now()). A Promise of the string is fine too.
+window.__recorderAudio = function (startMs, durationMs) { /* ... */ };
+```
+
+The usual pattern is to log each sound as it plays and replay the log into an `OfflineAudioContext`. [`examples/like-button.html`](examples/like-button.html) shows the whole thing in about 15 lines. Pages without the function produce silent videos.
+
+## Folder layout
+
+```
+~/Prototypes/          your .html prototypes (full pages or bare fragments)
+~/Prototypes/renders/  finished videos
+~/Prototypes/takes/    takes captured in the Studio
+```
+
+Set the folder with `--folder`, or the `PROTOREEL_HOME` environment variable (default `~/Protoreel`).
+
+## Troubleshooting
+
+- **"Chromium is not installed"** — run `uvx protoreel setup`. Behind a strict network? Point `PROTOREEL_CHROMIUM` at an existing Chrome/Chromium.
+- **The Studio port is busy** — another Studio is probably running; `protoreel studio --port 8800` picks another.
+- **The video is silent** — the page doesn't define `window.__recorderAudio`; see *Sound*.
+- **Clicks miss** — use a selector rather than coordinates, and check with `preview_frame`.
+
+## Contributing
+
+Protoreel is small on purpose and written to be easy to read. Start with [docs/architecture.md](docs/architecture.md), then see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT © Kingsley Mkpandiok

protoreel-0.1.0/docs/architecture.md

@@ -0,0 +1,63 @@
+# How Protoreel is built
+
+Protoreel is about 1,800 lines of Python (half of it comments and docstrings) plus three small JavaScript files and the Studio page. Each module does one job.
+
+```
+src/protoreel/
+├── cli.py            command line: studio, record, render-take, mcp, setup
+├── mcp_server.py     the MCP server and its six tools
+├── renderer.py       opens a page, plays an interaction, films it frame by frame
+├── timeline.py       scripts and takes → one input state per frame
+├── takes.py          takes captured in the Studio: load, save, smooth, re-centre
+├── settings.py       formats, resolutions and defaults
+├── workspace.py      the folder of prototypes, renders and takes; a tiny file server
+├── encoder.py        ffmpeg: PNG frames in, MP4 out, plus the soundtrack
+├── audio.py          asks the page for its sound (window.__recorderAudio)
+├── browser.py        launches Chromium, installing it on first use
+├── page_scripts/     JavaScript injected into the prototype
+│   ├── clock.js        freezes time so we can step it
+│   ├── cursor.js       the on-screen pointer
+│   └── background.js   optional backdrop colour
+└── studio/
+    ├── server.py       the Studio's web server and JSON API
+    └── static/index.html  the Studio app (plain HTML/CSS/JS)
+```
+
+## The one idea that makes it work: a frozen clock
+
+Normally a browser animates in real time, so a slow machine (or a slow screenshot) drops frames.
+`page_scripts/clock.js` replaces `requestAnimationFrame`, `setTimeout`, `setInterval`,
+`performance.now`, `Date.now` and every CSS/Web Animation with versions driven by a number we
+control. The renderer then repeats, for every frame:
+
+1. apply this frame's input (move the mouse, press, type, scroll) — `renderer.Player.step`
+2. advance the page's clock by exactly 1/60 s — `window.__advance(ms)`
+3. take a screenshot and pipe it to ffmpeg — `encoder.VideoEncoder`
+
+So a 5-second video at 60 fps is exactly 300 screenshots, each showing precisely the right moment.
+
+## From an interaction to frames
+
+`timeline.py` turns both kinds of interaction into the same stream of `FrameInput` objects:
+
+- **Takes** (`take_frames`) replay captured events at their recorded times.
+- **Scripts** (`script_frames`) expand each action into frames. Element positions are looked up
+  *when the action starts*, so earlier actions can open menus or move things around.
+
+The renderer doesn't know or care which kind it is playing.
+
+## Where things run
+
+| You run | What happens |
+| --- | --- |
+| `protoreel studio` | `studio.server.Studio` serves the app at http://127.0.0.1:8765 |
+| `protoreel mcp` | `mcp_server.build_server` serves tools over stdio; `open_studio` starts the Studio in a background thread |
+| `protoreel record` | `renderer.render` directly |
+
+Every render serves the prototype's folder from a throwaway local web server
+(`workspace.PrototypeServer`), so pages load over `http://` and behave like they do in a real browser.
+
+## Tests
+
+`pytest` runs everything, including real renders, a real Studio and a real MCP session over
+stdio (about 30 seconds). Unit tests for the timeline and takes need no browser.

protoreel-0.1.0/examples/README.md

@@ -0,0 +1,8 @@
+# Examples
+
+`like-button.html` is a tiny prototype with an animation, a counter and sound (see how it
+implements `window.__recorderAudio`). `like-button.json` is a script that likes it.
+
+```bash
+uvx protoreel record examples/like-button.html examples/like-button.json --format 1x1 --zoom 2.5
+```