@mineo71/showtime 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.0 — 2026-10-13
+
+- `showtime frames` also renders a contact sheet (`frames/sheet.png`) of every step.
+- `showtime lint`: long captions, pauses that should be waits, zoom/spotlight that cannot apply,
+  and, with a take, captions too brief to read and overall length.
+- `--json` on every command.
+- `hooks.before` / `hooks.after`: shell commands or HTTP calls around every `check` and `record`,
+  so state can be reset between rehearsal and take.
+- `app.mock` (canned responses for matching requests), `app.clock` (the page clock starts at a fixed date),
+  `app.dialogs` (accept or dismiss native dialogs; accepted by default).
+- Safe re-takes: a failed `record` leaves the previous take untouched (`take.tmp` keeps the failure).
+- Settling ignores event streams; relative `goto` URLs resolve against `app.url`.
+- Captions never overlap, and move to the top when the action is at the bottom of the screen.
+- `meta.outro` closing card and `meta.logo` on the intro and outro cards.
+- `showtime.config.json` brand file with default `style` and `meta` for every script below it.
+- Takes recorded with 0.2 stay valid.
+
 ## 0.2.1 — 2026-10-13
 
 - Releases are automated: `npm version patch|minor|major` dates the changelog, tags and pushes;

package/README.md

@@ -26,7 +26,7 @@ No timeline editor. No re-take when a caption changes.
 <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>
+  <sub>Made by <a href="examples/fennel/demo.json">a 39-line script</a>, a <a href="examples/fennel/showtime.config.json">brand file</a> and one command, with no manual editing. <a href="docs/media/demo.mp4">▶ Full-quality MP4</a></sub>
 </div>
 
 ---
@@ -121,7 +121,19 @@ again.
     <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>
+      <sub>Title card with your logo, a browser frame with your URL, a gradient backdrop, rounded corners and a shadow. Each of them is a <code>style</code> or <code>meta</code> field.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td valign="top">
+      <img src="docs/media/outro.jpg" alt="Outro card with logo, title and URL" /><br />
+      <b>📣 Ends on your call to action</b><br />
+      <sub>An outro card with your logo, a headline and the URL to visit. Put it in a brand file once and every demo ends the same way.</sub>
+    </td>
+    <td valign="top">
+      <img src="docs/media/sheet.jpg" alt="Contact sheet of every step" /><br />
+      <b>🧪 Reviews its own work</b><br />
+      <sub><code>showtime frames</code> renders a contact sheet of every step, and <code>showtime lint</code> flags captions that are too long or too brief to read. The agent fixes them before you look.</sub>
     </td>
   </tr>
 </table>
@@ -132,8 +144,16 @@ And under the hood:
   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.
+- 🧹 **Clean state for every take.** `hooks` run a reset command or call an endpoint before and
+  after each rehearsal and take, so a flow that creates data works twice in a row.
+- 🎭 **Deterministic pages.** `app.mock` answers flaky or slow APIs with canned JSON, `app.clock`
+  pins the date, and `app.dialogs` answers `confirm()` the way the demo needs.
+- 🎨 **One brand file.** `showtime.config.json` holds your colours, logo and outro; every script
+  below it inherits them.
+- 🛟 **Safe re-takes.** A take that fails halfway leaves the last good one untouched.
+- 🤖 **JSON everywhere.** Every command takes `--json`, so agents read results instead of parsing
+  prose. Captions also move to the top on their own when the action happens at the bottom of the
+  screen.
 - 📐 **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.
@@ -169,7 +189,8 @@ The agent takes it from there:
 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.
+5. **Reviews** the contact sheet from `showtime frames` and the warnings from `showtime lint`,
+   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
@@ -224,8 +245,9 @@ into and waited on, and everything cinematic is computed afterwards.
 }
 ```
 
-`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.
+`meta.title` adds an intro card, `meta.outro` a closing card and `meta.logo` puts your logo on
+both. `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>
@@ -291,6 +313,52 @@ Targets are Playwright selectors: `role=button[name='Save']`, `text=Save`, `#id`
 | `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=`) |
+| `mock`              | `[]`       | `[{ url, method?, status?, json? \| body?, headers?, delayMs? }]`: answer matching requests (`url` is a glob like `**/api/stats*`; the first match wins) |
+| `clock`             | none       | start the page clock at this ISO date-time; it then runs normally |
+| `dialogs`           | `accept`   | answer `alert`/`confirm`/`prompt` with `accept` or `dismiss` |
+
+</details>
+
+<details>
+<summary><b>Cards</b> (<code>meta</code>)</summary>
+
+| field      | |
+|------------|-|
+| `title`, `subtitle` | intro card |
+| `logo`     | SVG, PNG, JPEG or WebP (≤ 2 MB), relative to the file that names it; shown on the intro and outro |
+| `outro`    | `{ title, subtitle?, url? }`: closing card after the video |
+
+</details>
+
+<details>
+<summary><b>Hooks</b> (<code>hooks</code>)</summary>
+
+```json
+"hooks": {
+  "before": [{ "run": "npm run db:reset" }],
+  "after": [{ "request": { "url": "http://localhost:3000/api/test/reset", "method": "POST" } }]
+}
+```
+
+`before` hooks run at the start of every `check` and `record` (so `make` resets between the
+rehearsal and the take); `after` hooks run when they end, even after a failure, and a failing
+`after` hook is a warning that never costs you the take. `run` is a shell
+command in the script's folder (120 s timeout); `request` is an HTTP call that must answer 2xx.
+
+</details>
+
+<details>
+<summary><b>Brand file</b> (<code>showtime.config.json</code>)</summary>
+
+Put it next to your scripts or in any folder above them; the nearest one applies. Its `style` and
+`meta` are defaults, and a script's own fields win key by key.
+
+```json
+{
+  "style": { "background": "linear-gradient(135deg, #0f172a, #312e81)", "accent": "#6366f1", "address": "app.acme.com" },
+  "meta": { "logo": "brand/logo.svg", "outro": { "title": "Try Acme free", "url": "acme.com" } }
+}
+```
 
 </details>
 
@@ -303,10 +371,12 @@ Targets are Playwright selectors: `role=button[name='Save']`, `text=Save`, `#id`
 | `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 frames <script>` | QA stills (intro, one per step, outro) and a contact sheet of them |
+| `showtime lint <script>` | warnings about captions, pauses and length; timing checks need a take |
 | `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
+Every command takes `--json` and then prints exactly one JSON document. 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
@@ -317,7 +387,9 @@ The video lands next to the script (`demo/pitch.json` → `demo/pitch.mp4`). Wor
   `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`.
+  for anything personal, and `hooks` to reset the data between `check` and `record`.
+- **Pin the world.** Mock slow or random APIs with `app.mock` and pin the date with `app.clock`,
+  so every take looks the same.
 
 ## FAQ
 

package/docs/script.schema.json

@@ -18,6 +18,31 @@
         },
         "subtitle": {
           "type": "string"
+        },
+        "logo": {
+          "description": "SVG/PNG/JPEG/WebP shown on the intro and outro cards",
+          "type": "string",
+          "minLength": 1
+        },
+        "outro": {
+          "description": "Closing card after the video",
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "minLength": 1
+            },
+            "subtitle": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "title"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -83,6 +108,71 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "mock": {
+          "default": [],
+          "description": "Answer matching network requests with canned responses; the first match wins",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Playwright URL glob of the requests to answer, e.g. **/api/reports*"
+              },
+              "method": {
+                "description": "Only answer this HTTP method; others go to the network",
+                "type": "string",
+                "minLength": 1
+              },
+              "status": {
+                "default": 200,
+                "type": "integer",
+                "minimum": 100,
+                "maximum": 599
+              },
+              "json": {
+                "description": "Response body, sent as application/json"
+              },
+              "body": {
+                "description": "Raw response body",
+                "type": "string"
+              },
+              "headers": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "delayMs": {
+                "description": "Wait this long before answering",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 30000
+              }
+            },
+            "required": [
+              "url"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "clock": {
+          "description": "Start the page clock at this ISO date-time; it then runs normally",
+          "type": "string"
+        },
+        "dialogs": {
+          "default": "accept",
+          "description": "How to answer alert/confirm/prompt dialogs",
+          "type": "string",
+          "enum": [
+            "accept",
+            "dismiss"
+          ]
         }
       },
       "required": [
@@ -90,6 +180,133 @@
       ],
       "additionalProperties": false
     },
+    "hooks": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "before": {
+          "default": [],
+          "description": "Run before every check and record, e.g. to reset demo data",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "run": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Shell command, run in the script folder"
+                  }
+                },
+                "required": [
+                  "run"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "request": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "method": {
+                        "default": "POST",
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "json": {},
+                      "headers": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "url"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "request"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "after": {
+          "default": [],
+          "description": "Run after every check and record, even when it failed",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "run": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Shell command, run in the script folder"
+                  }
+                },
+                "required": [
+                  "run"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "request": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "method": {
+                        "default": "POST",
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "json": {},
+                      "headers": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "url"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "request"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "setup": {
       "default": [],
       "type": "array",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mineo71/showtime",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Product demos, directed by AI: Claude writes a JSON script, showTime records your web app and renders a polished MP4",
   "keywords": [
     "demo",

package/skill/SKILL.md

@@ -33,14 +33,19 @@ showtime setup    # downloads the browsers it records with
 4. **Rehearse:** `showtime check demo/pitch.json`. On failure read the error, the ARIA snapshot it
    prints and `.showtime/<name>/check/failure.png`; fix the selector or add a `wait`, repeat until
    green.
-5. **Record:** `showtime record demo/pitch.json` (runs in real time).
-6. **Render:** `showtime render demo/pitch.json` → `demo/pitch.mp4`.
-7. **QA:** `showtime frames demo/pitch.json`, then Read the PNGs it lists. Check that zoom lands on
-   the right control, captions are legible and do not hide the action, and pacing feels right.
-8. **Iterate:** edits to `show`, `style` or `meta` only need `render`. Edits to actions (`do`,
+5. **Lint:** `showtime lint demo/pitch.json` and fix every warning (long captions, pauses that
+   should be waits, zoom or spotlight on steps without a target).
+6. **Record:** `showtime record demo/pitch.json` (runs in real time).
+7. **Render:** `showtime render demo/pitch.json` → `demo/pitch.mp4`.
+8. **QA:** `showtime frames demo/pitch.json`, then Read the contact sheet it prints first
+   (`sheet.png`: every step in one image); open single stills only to look closer. Check that zoom
+   lands on the right control, captions are legible, and pacing feels right. Run `showtime lint`
+   again: with a take it also flags captions on screen too briefly to read.
+9. **Iterate:** edits to `show`, `style` or `meta` only need `render`. Edits to actions (`do`,
    targets, text, `hold`, `app`) need `record` again — `render` refuses a stale take.
 
-`showtime make <script>` runs check → record → render in one go.
+`showtime make <script>` runs check → record → render in one go. Every command takes `--json`
+and then prints exactly one JSON document on stdout.
 
 ## Long-running commands
 
@@ -48,14 +53,22 @@ showtime setup    # downloads the browsers it records with
 Remotion. They routinely take several minutes. In Claude Code run them with `timeout: 600000`, or
 with `run_in_background: true` and wait for the completion notification. In Codex and other
 agents, give the command a timeout of at least 10 minutes.
-Never let a `record` be killed halfway: it replaces the previous take.
+A `record` that fails or is stopped halfway leaves the previous take in place.
 
 ## Side effects
 
 `check` performs every action for real (it is a full run, just fast), and `record` repeats them.
 Flows that create data ("New project", sign-up, checkout) can collide on the second run
-("name already exists"). Use a resettable demo account or seed data, make names unique, or undo
-the change in `setup`; after a green `check`, reset the data before `record`.
+("name already exists"). Add `hooks` that reset the data: `before` hooks run at the start of every
+`check` and `record`, `after` hooks when they end.
+
+```
+"hooks": { "before": [{ "run": "npm run db:reset" }] }
+```
+
+A hook is `{ "run": "<shell command, run in the script folder>" }` or
+`{ "request": { "url": "…", "method": "POST", "json": {…} } }`. If the project has no reset command,
+ask the user for one rather than guessing.
 
 ## Example
 
@@ -97,7 +110,14 @@ the change in `setup`; after a green `check`, reset the data before `record`.
   (address-bar text), `padding`, `radius`, `shadow`, `font`, `accent`, `autoZoom`, `autoSpeed`, `maxZoom`.
 - **`app`:** `url`, `viewport`, `deviceScaleFactor`, `storageState` (Playwright storage-state JSON,
   path relative to the script), `colorScheme`, `locale`, `timezoneId`, `mask` (CSS selectors to blur —
-  plain CSS only, not `text=` / `role=`).
+  plain CSS only, not `text=` / `role=`), `mock` (`[{ url: "**/api/x*", json | body, status?,
+  method?, delayMs? }]`), `clock` (ISO date-time the page clock starts at; first matching mock wins), `dialogs` (`accept` | `dismiss`).
+  Relative `goto` URLs resolve against `app.url`.
+- **`meta`:** `title`, `subtitle` (intro card), `logo` (SVG/PNG/JPEG/WebP), `outro`
+  (`{ title, subtitle?, url? }`, closing card).
+- **`hooks`:** `before` / `after` lists of `{ run }` or `{ request }`.
+- **Brand file:** `showtime.config.json` in the script's folder or above holds default `style` and
+  `meta` (logo, outro) for every script; the script's own fields win.
 - Output lands next to the script; working files in `.showtime/<script-name>/`.
 
 ## Direction tips
@@ -109,4 +129,8 @@ the change in `setup`; after a green `check`, reset the data before `record`.
 - Never `pause` to wait for loading — use `wait {for}`; auto-speed compresses the loader.
 - Use `setup` for cookie banners and onboarding, `app.storageState` to start logged in, `app.mask`
   to blur personal data.
+- Mock APIs that are slow, random or need real accounts (`app.mock`), and pin the date
+  (`app.clock`) so every take shows the same numbers and timestamps.
+- End pitch demos with `meta.outro`: the product name and the URL to visit. Put brand colours, logo
+  and outro in `showtime.config.json` when a project has several demos.
 - Keep the default 1440×900 viewport at `deviceScaleFactor` 2 for crisp 16:9 zooms.

package/src/cli/format.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import type { Issue } from '../lint';
 import type { CheckReport } from '../runner/check';
 
 const ARIA_LINES = 80;
@@ -17,3 +18,12 @@ export function formatCheck(report: CheckReport): string {
     ...aria.map((line) => `    ${line}`),
   ].join('\n');
 }
+
+export function formatLint(issues: Issue[], timing: boolean): string {
+  const lines = issues.map((i) => `${i.level === 'warn' ? '⚠' : 'ℹ'} ${i.where}  ${i.message}  [${i.rule}]`);
+  const warns = issues.filter((i) => i.level === 'warn').length;
+  const notes = issues.length - warns;
+  lines.push(issues.length ? `${warns} warning${warns === 1 ? '' : 's'}, ${notes} note${notes === 1 ? '' : 's'}` : '✓ no issues');
+  if (!timing) lines.push('(record a take to also check timing)');
+  return lines.join('\n');
+}