@mineo71/showtime 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0 — 2026-10-13
+
+- Published to npm as `@mineo71/showtime`.
+- `showtime setup`: downloads the Chromium build Playwright drives and Remotion's headless
+  shell, and links the skill into Claude Code (`~/.claude/skills`) and Codex (`~/.agents/skills`).
+- The skill works with Codex: agent-neutral instructions, a setup step.
+- Browser window chrome around the take (`style.chrome`, `style.address`); the window eases in
+  after the intro card.
+- `examples/fennel`: a showcase app and script; `npm run example`, `npm run media`.
+- `docs/script.schema.json` for editor autocomplete (`"$schema"` in your script).
+
+## 0.1.0 — 2026-10-13
+
+First release: `showtime check | record | render | frames | make`, the Claude Code skill,
+auto-zoom, synthetic cursor, click ripples, spotlights, captions, auto speed-up of idle time,
+intro card, privacy masks, stale-take detection.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleh Rylskyj
+
+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.

package/README.md

@@ -1,3 +1,366 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="docs/media/logo.svg" width="96" alt="showTime logo" />
+
+# showTime
+
+**Product demos, directed by AI.**
+
+Your AI agent (Claude Code or Codex) writes a short JSON script. showTime clicks through your web app, films it and edits it
+the way a motion designer would (auto-zoom, a smooth cursor, click ripples, spotlights, captions,
+sped-up loading) and hands you a polished 1080p MP4.<br />
+No timeline editor. No re-take when a caption changes.
+
+[![tests](https://img.shields.io/github/actions/workflow/status/mineo71/showTime/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/mineo71/showTime/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@mineo71/showtime?style=flat-square&color=6366f1)](https://www.npmjs.com/package/@mineo71/showtime)
+[![license](https://img.shields.io/badge/license-MIT-c026d3?style=flat-square)](LICENSE)
+![node](https://img.shields.io/badge/node-%E2%89%A5%2020-6366f1?style=flat-square)
+![built with](https://img.shields.io/badge/Playwright%20%2B%20Remotion-0f172a?style=flat-square)
+![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-d97757?style=flat-square)
+![Codex](https://img.shields.io/badge/Codex-skill-10a37f?style=flat-square)
+
+**[Install](#install)** · [Try it](#try-it) · [Use with Claude Code or Codex](#use-it-with-claude-code-or-codex) · [Script reference](#script-reference) · [CLI](#cli)
+
+</div>
+
+<div align="center">
+  <a href="docs/media/demo.mp4"><img src="docs/media/hero.webp" width="860" alt="A demo of a fictional invoicing app, filmed and edited by showTime: the camera zooms on a chart, a cursor fills in a new invoice, a spotlight lands on the total, and the sent invoice appears in the table" /></a>
+  <br />
+  <sub>Made by <a href="examples/fennel/demo.json">one 44-line script</a> and one command, with no manual editing. <a href="docs/media/demo.mp4">▶ Full-quality MP4</a></sub>
+</div>
+
+---
+
+## Install
+
+Needs **Node ≥ 20** and **ffmpeg** (`brew install ffmpeg` / `sudo apt install ffmpeg`).
+
+```bash
+npm install -g @mineo71/showtime
+showtime setup      # downloads Chromium + the renderer, links the skill into Claude Code and Codex
+showtime --help     # check that it works
+```
+
+Then ask your agent for a demo, or [film the bundled example](#try-it).
+
+**Or let your agent install it.** Paste this into Claude Code or Codex:
+
+> Install showTime: run `npm install -g @mineo71/showtime`, then `showtime setup`, and check
+> that `showtime --help` works.
+
+<sub>**Update:** `npm install -g @mineo71/showtime@latest`. **Switched Node versions with nvm?** Install it again under the new version. **From source:** clone the repo, then `npm install && npm link && showtime setup` (see [CONTRIBUTING](CONTRIBUTING.md)).</sub>
+
+## Why
+
+Every pitch, launch post and README needs a product demo. Recording one is the easy part. The
+editing eats the afternoon: zooming in on the button that matters, smoothing a jittery mouse,
+cutting the spinner, adding captions, and doing it all again when the UI changes next week.
+
+An AI can already write the shot list. **showTime gives it hands and an editing suite.** Claude
+explores your app, writes the script, rehearses it, records it and reviews the stills. You watch
+the result and ask for changes in plain words.
+
+## From script to screen
+
+A step in the script says *what happens* and *what the viewer should notice*:
+
+```json
+{ "do": "hover", "target": ".bar[data-m='Oct']", "show": { "caption": "Your studio at a glance" } }
+```
+
+showTime records the app untouched, then builds everything else from what happened during the take:
+
+<table>
+  <tr>
+    <th width="50%">What the browser recorded</th>
+    <th width="50%">What showTime rendered</th>
+  </tr>
+  <tr>
+    <td><img src="docs/media/before.jpg" alt="Raw recording: the full dashboard, no cursor, no framing" /></td>
+    <td><img src="docs/media/after.jpg" alt="Rendered: browser window on a gradient, zoomed on the chart, cursor on the bar, caption below" /></td>
+  </tr>
+</table>
+
+The window, the camera move, the cursor and the caption are all added **after** the recording.
+Change a caption, the colours or the pacing and re-render in seconds, without touching the app
+again.
+
+## Features
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="docs/media/zoom.jpg" alt="Auto-zoom on a chart bar" /><br />
+      <b>🔍 Auto-zoom that follows the action</b><br />
+      <sub>The camera eases in on every click and keystroke. Zoom depth comes from the target's size, and nearby moments are joined by a pan instead of a bounce.</sub>
+    </td>
+    <td width="50%" valign="top">
+      <img src="docs/media/typing.jpg" alt="Typing into an autocomplete field" /><br />
+      <b>⌨️ Human typing, smooth cursor</b><br />
+      <sub>A synthetic cursor glides along eased paths, turns into an I-beam over text fields and types at a natural (seeded, repeatable) pace.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td valign="top">
+      <img src="docs/media/spotlight.jpg" alt="Spotlight on the invoice total" /><br />
+      <b>🔦 Spotlights and captions</b><br />
+      <sub>Dim everything except the number that matters. One-line captions carry the story and fade in sync with the action.</sub>
+    </td>
+    <td valign="top">
+      <img src="docs/media/speed.jpg" alt="Clicking Send with a click ripple" /><br />
+      <b>⏩ Loading, compressed</b><br />
+      <sub>Spinners and network waits are detected and sped up 2–8×, so the demo never stalls. Click ripples show every press.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td valign="top">
+      <img src="docs/media/tracked.jpg" alt="Invoice table with blurred billing emails and a spotlit new row" /><br />
+      <b>🙈 Privacy masks</b><br />
+      <sub>Blur emails, names or card numbers with plain CSS selectors. The blur is applied inside the browser, so no frame ever holds the real data.</sub>
+    </td>
+    <td valign="top">
+      <img src="docs/media/intro.jpg" alt="Intro card with title and subtitle" /><br />
+      <b>🎬 Intro card and window chrome</b><br />
+      <sub>Title card, a browser frame with your URL, a gradient backdrop, rounded corners and a shadow. Each of them is a <code>style</code> field.</sub>
+    </td>
+  </tr>
+</table>
+
+And under the hood:
+
+- ✅ **Rehearsal mode.** `showtime check` runs the script at full speed and screenshots every step.
+  When a step fails it prints an ARIA snapshot of the page, so Claude can fix its own selectors.
+- 🔁 **Stale-take detection.** The take stores a hash of the actions. Edit a caption and `render`
+  reuses the take. Edit a click and `render` tells you to `record` again.
+- 🧪 **Self-review.** `showtime frames` renders a still per step so the agent can *look* at its
+  work before you do.
+- 📐 **Typed scripts.** Point `"$schema"` at [`docs/script.schema.json`](docs/script.schema.json)
+  for autocomplete and validation in your editor.
+- 🖥️ **Crisp at 1080p.** The app is captured at 2× device scale, so zoomed shots stay sharp.
+
+## Try it
+
+After [installing](#install), film the example app from the video above. The example lives in
+the repo:
+
+```bash
+git clone https://github.com/mineo71/showTime.git && cd showTime
+npm run example                              # terminal 1: serves examples/ on http://127.0.0.1:4800
+showtime make examples/fennel/demo.json      # terminal 2: → examples/fennel/demo.mp4
+```
+
+`make` rehearses the script, records it in real time (about 25 s for this one) and renders it.
+Expect a minute or two end to end.
+
+## Use it with Claude Code or Codex
+
+`showtime setup` links the skill into `~/.claude/skills` for Claude Code and `~/.agents/skills`
+for Codex (`--agent claude` or `--agent codex` picks one). Then ask for a demo the way you would
+ask a person:
+
+> Make a 30-second demo of the checkout flow on localhost:3000 for our investor deck.
+> Blur customer emails.
+
+The agent takes it from there:
+
+1. **Explores** the app (with the Playwright MCP if it has one) and picks the 2–4 moments that
+   sell it.
+2. **Writes** `demo/checkout.json`.
+3. **Rehearses** with `showtime check` until every step passes, fixing selectors from the ARIA
+   snapshot.
+4. **Records and renders** with `showtime record` and `showtime render`.
+5. **Reviews** the stills from `showtime frames`, tightens captions and pacing, and re-renders.
+
+The skill ([`skill/SKILL.md`](skill/SKILL.md)) is a plain-Markdown
+[Agent Skill](https://agentskills.io). Any agent that can run shell commands can follow it, and so
+can a human with a text editor.
+
+## How it works
+
+```mermaid
+flowchart LR
+  S["demo.json<br/>script"] --> C["check<br/>fast rehearsal"]
+  C -- green --> R["record<br/>Playwright + CDP"]
+  R --> V["raw.mp4<br/>clean video, no cursor"]
+  R --> E["events.json<br/>targets · clicks · idle"]
+  S --> T["timeline.json<br/>camera · cursor · captions · speed"]
+  E --> T
+  T --> M["Remotion"]
+  V --> M
+  M --> O["demo.mp4"]
+```
+
+The core idea is to **separate capture from direction**. `record` drives a real Chromium through
+the script and writes two things: a clean video with no cursor, and an event log of where every
+target was, when each click landed and when the page sat idle. A pure function,
+`buildTimeline(script, events)`, turns that log into speed segments, camera keyframes, cursor
+paths, captions and spotlights. Remotion renders the result frame by frame.
+
+So presentation is cheap to change and recording stays honest: the app really is clicked, typed
+into and waited on, and everything cinematic is computed afterwards.
+
+## Script reference
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/mineo71/showTime/main/docs/script.schema.json",
+  "version": 1,
+  "meta": { "title": "Acme", "subtitle": "Reports in two clicks" },
+  "app": { "url": "http://localhost:3000/", "mask": [".email"] },
+  "setup": [{ "do": "click", "target": "text=Accept cookies" }],
+  "style": { "accent": "#6366f1" },
+  "scenes": [
+    {
+      "id": "report",
+      "steps": [
+        { "do": "click", "target": "role=button[name='New report']", "show": { "caption": "A report in one click" } },
+        { "do": "type", "target": "#name", "text": "Q3 revenue" },
+        { "do": "click", "target": "text=Create" },
+        { "do": "wait", "for": "text=Report ready" },
+        { "do": "hover", "target": ".total", "show": { "spotlight": true, "hold": 1500 } }
+      ]
+    }
+  ]
+}
+```
+
+`meta.title` adds an intro card. `setup` steps run before the camera starts (cookie banners,
+onboarding). Scenes group steps for readability and for naming the stills.
+
+<details>
+<summary><b>Actions</b> (<code>do</code>)</summary>
+
+| action   | fields                          | notes |
+|----------|---------------------------------|-------|
+| `goto`   | `url`                           | navigate and wait for `load` |
+| `click`  | `target`                        | cursor travels there, ripple on press |
+| `type`   | `target, text, pace?, clear?`   | `pace`: `human` (default), `fast` or ms per character |
+| `press`  | `key`                           | `Enter`, `Escape`, `Meta+K`, … |
+| `hover`  | `target`                        | |
+| `select` | `target, value`                 | picks a `<select>` option by value |
+| `scroll` | `target` *or* `by`              | smooth-scroll an element into view, or by pixels |
+| `wait`   | `for` *or* `ms`                 | prefer `for` (a selector): the wait is sped up automatically |
+| `pause`  | `ms`                            | a deliberate beat, always at 1× |
+
+Targets are Playwright selectors: `role=button[name='Save']`, `text=Save`, `#id`,
+`[data-testid=x]`, CSS, and `>>` chains.
+
+</details>
+
+<details>
+<summary><b>Per-step presentation</b> (<code>show</code>)</summary>
+
+| field       | value          | effect |
+|-------------|----------------|--------|
+| `caption`   | string         | caption while the step plays |
+| `zoom`      | 1–4 or `false` | override the auto-zoom depth, or skip zooming |
+| `spotlight` | boolean        | dim everything except the target |
+| `hold`      | ms             | extra real time after the step (changes the take) |
+| `speed`     | 0.25–16        | playback speed for this step |
+
+</details>
+
+<details>
+<summary><b>Look</b> (<code>style</code>)</summary>
+
+| field        | default            | |
+|--------------|--------------------|-|
+| `background` | indigo gradient    | any CSS background |
+| `chrome`     | `browser`          | browser window frame, or `none` |
+| `address`    | the app URL        | address-bar text |
+| `accent`     | `#6366f1`          | ripples, spotlight ring, intro rule |
+| `padding`    | `0.06`             | backdrop around the window, as a fraction of the frame |
+| `radius`     | `14`               | window corner radius, px |
+| `shadow`     | `true`             | window drop shadow |
+| `font`       | Inter / system UI  | captions and intro card |
+| `autoZoom`   | `true`             | zoom on clicks, typing, hovers and selects |
+| `autoSpeed`  | `true`             | speed up idle stretches longer than 0.8 s |
+| `maxZoom`    | `1.8`              | cap for auto-zoom |
+
+</details>
+
+<details>
+<summary><b>App</b> (<code>app</code>)</summary>
+
+| field               | default    | |
+|---------------------|------------|-|
+| `url`               | (required) | where the take starts |
+| `viewport`          | 1440 × 900 | CSS pixels |
+| `deviceScaleFactor` | `2`        | capture resolution multiplier |
+| `storageState`      | none       | Playwright storage-state file (relative to the script) to start logged in |
+| `colorScheme`       | none       | `light` or `dark`; also picks the browser-bar theme |
+| `locale`, `timezoneId` | none    | passed to the browser context |
+| `mask`              | `[]`       | CSS selectors to blur (plain CSS, not `text=`) |
+
+</details>
+
+## CLI
+
+| command | what it does |
+|---|---|
+| `showtime setup [--agent claude\|codex\|all] [--no-browsers]` | download the browsers, link the skill |
+| `showtime make <script> [-o out.mp4]` | check → record → render |
+| `showtime check <script> [--json] [--headed]` | rehearse; a screenshot per step; the first failure with an ARIA snapshot |
+| `showtime record <script> [--headed] [--keep-frames]` | record a take into `.showtime/<name>/take` |
+| `showtime render <script> [-o out.mp4]` | render from the last take, without re-recording |
+| `showtime frames <script>` | QA stills: the intro plus one per step |
+| `showtime schema` | print the script's JSON Schema |
+
+The video lands next to the script (`demo/pitch.json` → `demo/pitch.mp4`). Working files live in
+`.showtime/<name>/`, which is worth adding to your `.gitignore`.
+
+## Tips for a great demo
+
+- **One idea per caption, six words at most.** Caption the benefit ("Paid in two clicks"), not
+  the click ("Click Pay").
+- **Let payoffs breathe.** After the screen that matters, add `hold` (800–2000 ms) and a
+  `spotlight` on the one number that sells it.
+- **Never `pause` for loading.** Use `wait` with a selector and auto-speed compresses the spinner.
+- **Start clean.** Use `setup` for cookie banners, `app.storageState` to skip the login, `app.mask`
+  for anything personal, and seed data you can reset between `check` and `record`.
+
+## FAQ
+
+**Which apps does it work with?** Any web app Chromium can open: a localhost dev server, staging
+or production. Logged-in flows work through `app.storageState`.
+
+**Does showTime call an AI model?** No. showTime is deterministic and needs no API keys. The AI
+part (writing, fixing and reviewing the script) happens in your agent, guided by the skill.
+
+**Why not just screen-record?** You can, once. A screen recording can't be re-edited when the copy
+changes, the cursor is wherever your hand was, and the spinner plays at full length. With
+showTime, edits are a re-render and a UI change is one command.
+
+**Does it run on Linux or Windows?** It is developed on macOS. Linux should work since it only
+needs Playwright and ffmpeg. Windows is untested.
+
+## Roadmap
+
+- 🎙️ Narration: text-to-speech per scene, with steps stretched to fit the audio, and burnt-in subtitles.
+- 📱 Vertical 9:16 and square 1:1 cuts with a follow-cam, from the same take.
+- 🎞️ Deterministic frame-by-frame capture in virtual time, for a perfect 60 fps.
+- 🧩 An MCP server for Claude Desktop, and a desktop studio for timeline tweaks.
+- 📲 Mobile (iOS Simulator) and desktop-app drivers that produce the same `events.json`.
+
+## Development
+
+```bash
+npm test             # unit tests (seconds)
+npm run test:int     # Playwright + ffmpeg + Remotion, end to end (minutes)
+npm run typecheck
+npm run media        # rebuild the README media from examples/fennel (see CONTRIBUTING)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the architecture and how to work on it. The design
+document is in [`docs/superpowers/specs`](docs/superpowers/specs/2026-10-13-showtime-design.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Oleh Rylskyj.
+
+showTime renders with [Remotion](https://www.remotion.dev), which has its own
+[license](https://www.remotion.dev/license): it is free for individuals, non-profits and companies
+of up to 3 people, and larger companies need a Remotion company license. The renderer only reads
+`timeline.json`, so it can be swapped out.
+
+<sub>Fennel, the app in the example, is fictional. It was built for this README and its data is made up.</sub>

package/bin/showtime.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from 'tsx/esm/api';
+
+register();
+await import('../src/cli/main.ts');