demobites 1.0.9 → 1.4.0

package/README.md

@@ -1,15 +1,166 @@
-# demobites
+# DemoBites Agentic Recorder
 
-An alias of [`demobite`](https://www.npmjs.com/package/demobite), the DemoBites agentic recorder. Same launcher, same subcommands, one more spelling.
+**Ask your coding agent to record your product. Edit the result. Download the MP4.**
+
+Your agent drives a real browser on your machine and records the flow you describe. Connect a free DemoBites account to turn the take into an editable video, with text-to-speech, zooms, captions, and MP4 export included.
+
+**Sign in to your app locally. You do not hand DemoBites your app password or upload your recording browser profile.**
+
+```bash
+npx demobite@latest
+```
+
+**Free Studio · Text-to-speech included · Unlimited exports · No watermark · No credit card**
+
+[Website](https://agentic-recorder.com/) · [npm](https://www.npmjs.com/package/demobite) · [Report an issue](https://github.com/demobites/agentic-recorder/issues)
+
+## See the workflow
+
+https://github.com/user-attachments/assets/18293b85-82e2-475f-8d94-543f1f9bbc1d
+
+An illustrated walkthrough of the flow, with waiting time compressed.
+
+## Start with your own agent
+
+You need a coding agent that can read skill instructions, run terminal commands, and control a local browser. A browser-only chat session cannot run this local workflow.
+
+Before installing:
+
+- **Node.js 18 or newer** and npm.
+- **Google Chrome**, recommended. The recorder also supports Playwright's Chromium.
+- A **free DemoBites account** for the Studio workflow below.
+
+Run these commands from your project directory:
 
 ```bash
-npx demobites            # setup: checks Node, Chrome, ffmpeg; installs the recorder skill; wires the MCP
-npx demobites login      # connect this project to a DemoBites workspace (approve a code in your browser)
-npx demobites mcp        # register the DemoBites management MCP with your agent
-npx demobites logout     # revoke the key on the server and remove it locally
-npx demobites retake <biteId>   # re-film an existing bite against today's app
+# Install the skill and check your setup.
+npx demobite@latest
+
+# Connect this project to your DemoBites workspace.
+npx demobite login
 ```
 
-Then ask your coding agent (Claude Code, Cursor, Codex): "Record a demo of how search works on our app and upload it to DemoBites."
+The installer installs Playwright, ffmpeg and ffprobe beside the skill if they are not already there. It uses your own ffmpeg when a compatible build is on your PATH. It checks for Chrome and downloads Chromium on the first take if Chrome is missing.
+
+To connect, open the link printed in your terminal and approve the connection in your browser. If you are signed out of DemoBites, sign in there first. You do not paste a password into the terminal.
+
+Then ask your agent:
+
+> Record a demo of inviting a teammate in my app at http://localhost:3000. Open Team settings, invite alex@example.com as an Admin, and show the confirmation. Show me the storyboard before recording.
+
+Use your own app URL and a demo account. The agent performs real actions in your app, including sending an invitation if that is part of the approved flow.
+
+### Which agent?
+
+The installer currently places the skill at `~/.claude/skills/agentic-recorder/`, the Claude Code skill directory.
+
+For Cursor or Codex, make the [recorder instructions](skill/SKILL.md) available to your agent and ensure it can run the installed scripts. The launcher currently does not install into separate Cursor or Codex skill directories. Connecting an MCP client alone does not install the recorder skill.
+
+## From prompt to finished video
+
+1. **Describe the flow.** Give your agent the app URL and what you want to demonstrate.
+2. **Approve the storyboard.** Review the steps and estimated length before filming. If your app needs a login, sign in yourself in the recorder's local browser window.
+3. **Let it record.** The agent checks the flow and films it. Recording normally runs in the background.
+4. **Review the raw take.** Open the review link printed in the terminal. Check the footage, then approve it to create a Bite, an editable video project.
+5. **Tweak and download.** In the Studio, change a sentence, generate its voice, adjust the zooms or timing, and export your MP4.
+
+The storyboard's narration is a starting point. DemoBites rewrites and fits it to the footage; you can edit the final wording in the Studio.
+
+## What connecting to DemoBites adds
+
+The recorder supplies footage, action timings, cursor movements, and camera targets. The Studio uses that information to create a video you can keep editing.
+
+| Included in the free Studio | What you can do |
+| --- | --- |
+| Script and text-to-speech | Edit the words and generate narration without recording your own voice. |
+| Camera and cursor editing | Adjust automatic zooms, cursor appearance, and timing. |
+| Video finishing | Trim the take, edit captions, and add your background, branding, intro, and outro. |
+| MP4 export | Download Full HD video with narration and no DemoBites watermark. |
+
+**The free Studio holds up to 8 Bites at a time, with unlimited exports. Invite three people who sign up and the Studio becomes unlimited, still free.** It has no trial clock and requires no credit card. You bring your own coding agent; its subscription or model usage is separate. An ElevenLabs key is optional, not required for the Studio's included text-to-speech.
+
+You can use the exported video in your docs, website, release notes, or wherever you need it. Paid publishing and management features are optional. See [current plan details](https://www.demobites.com/pricing).
+
+## One prompt, one result
+
+> Record a demo of Funnels: where customers drop off, which channels work. Show the sidebar and graphs.
+
+
+
+https://github.com/user-attachments/assets/02eb7d3e-fe74-4c0d-b532-e16bfc3fa614
+
+
+ 
+ Recorded by the agent, then edited and narrated in the free Studio. This prompt assumes the agent already knows the app URL and can access the Funnels page.
+
+## Your app login stays local
+
+**You do not need to hand DemoBites your app password to record a signed-in flow.** Sign in yourself in the recorder's browser on your machine.
+
+The recorder uses a separate, persistent Chrome profile at `.recorder/profile/`. Your app session is saved there for later takes. It does not automatically inherit the sessions in your everyday Chrome profile.
+
+| Data | Where it goes |
+| --- | --- |
+| Your app's browser session | Stays in the local recording profile; the standard local workflow does not upload that profile to DemoBites. |
+| DemoBites recorder key | Saved in `.recorder/config.json` and used to authenticate recorder requests to DemoBites. This is separate from your app login. |
+| Footage and recording metadata | Uploaded to DemoBites for review and processing, including the storyboard, narration intent, cursor events, and camera targets. |
+
+Recording happens locally. Studio processing and editing use DemoBites online. Anything visible or typed into the recorded flow can appear in the footage or recording metadata, so use suitable demo data. Your coding agent's own data handling still follows its provider and your settings.
+
+Keep `.recorder/` and take directories out of version control. To disconnect the recorder, run `npx demobite logout`.
+
+## Local output without a DemoBites account
+
+The repository also contains a [standalone recorder skill](recorder/SKILL.md) and local finishing scripts. These produce a local MP4; optional voiceover uses your own ElevenLabs key.
+
+This is an advanced, manual workflow. The default `npx demobite@latest` command installs the Studio-connected skill, not the standalone skill. The standalone finishing reference contains legacy instructions; use the standalone skill as the entry point rather than treating it as a second ending of the installed Studio skill.
+
+## A few boundaries
+
+- The agentic recorder films **browser workflows**. It does not record native desktop apps or phone screens.
+- The Studio-connected skill is designed for short demos, usually **30–45 seconds**, with a **90-second maximum per Bite**. Split longer stories into separate videos.
+- Some sites block automated browsers. The workflow may need a human sign-in or verification step, and some sites may refuse recording.
+- Filming does not publish anything. You review the take before creating the Bite; public publishing is a separate action.
+
+## Optional: Retake and management
+
+When your UI changes, **Retake** can refilm an existing Bite from its saved recipe. It is a paid capability; see [plan details](https://www.demobites.com/pricing).
+
+```bash
+npx demobite retake <biteId> --note "Export moved to the header"
+```
+
+**In your app's repository.** Run the skill from the project that is your app and the agent reads the routes, the navigation, the control labels and the data handlers before it plans, then verifies everything on the live page. Without the code it works from the live app alone and asks when it cannot find a screen.
+
+**Workspace rules.** A workspace admin can write standing rules for the recorder in plain words in the DemoBites settings tab Agentic Recorder Rules, one per line: what to mask, which pages never to open, which words to use. The agent reads them at the start of every take and applies them under its own filming laws; `npx demobite rules` prints them. Every take records the rules version it was filmed under.
+
+**Batches of briefs.** When a pull request in DemoBites produces approved briefs, your agent claims them, films one take per brief after you approve each storyboard, and delivers each take. A delivered take becomes a Bite in DemoBites by itself; there is no second review click for these takes. Nothing is published or shared.
+
+The package also includes a DemoBites management MCP for releases and centers:
+
+```bash
+npx demobite mcp
+```
+
+The default installer also attempts to register that MCP with Claude Code when the current project is already connected. Management access depends on your account and key permissions. You do not need paid management to record, edit, or export a free Bite.
+
+[Management documentation](https://www.demobites.com/docs/bites/manage-from-your-agent)
+
+## Repository
+
+| Directory | Purpose |
+| --- | --- |
+| `launcher/` | CLI setup, connection commands, and MCP registration. |
+| `skill/` | Studio-connected recorder instructions, login, upload, and Retake. |
+| `scripts/` | Shared browser recording, trimming, and timing calibration. |
+| `recorder/` | Standalone skill and local video finishing tools. |
+
+The same package is published under three names, `demobite`, `agentic-recorder` and `demobites`, always at the same version; `npx agentic-recorder@latest` and `npx demobites@latest` do exactly what `npx demobite@latest` does. Run it again to update the installed skill. For publishing instructions, see [RELEASING.md](RELEASING.md).
+
+Found something confusing or have an example to share? [Open an issue](https://github.com/demobites/agentic-recorder/issues). Include your operating system, agent, and recorder version. Remove keys, cookies, and private app data from logs or recordings before attaching them.
+
+## License
+
+The code in this repository is [MIT licensed](LICENSE). The hosted DemoBites Studio is a separate service; its source is not included here.
 
-Docs and source: https://github.com/demobites/agentic-recorder · https://agenticrecorder.com
+Built and maintained by [DemoBites](https://www.demobites.com/).

package/launcher/index.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// demobite — connect DemoBites to your agent, one command away.
+//
+//   npx demobite@latest            full setup: checks, recorder skill, MCP
+//   npx demobite@latest login      connect this machine to DemoBites
+//   npx demobite@latest mcp        register the DemoBites management MCP
+//   npx demobite@latest logout     disconnect (revokes the key server-side)
+//
+// One front door (founder 2026-08-31): the user never chooses between the
+// recorder skill and the management MCP — bare `npx demobite` sets up both.
+// The MCP is universal (every agent gets it); the skill is the bonus layer
+// for code agents, and stays the advocated recording lane because the agent
+// knows the customer's code. `agentic-recorder` remains a docs alias of bare.
+//
+// This launcher is deliberately boring: it verifies the environment, installs
+// the recorder skill into your agent's skills directory, wires the MCP, and
+// hands off. The recorder itself is driven by your coding agent (Claude
+// Code): once set up, you just ask it — "record a demo of our search flow".
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync, spawnSync } from "node:child_process";
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+const arg = process.argv[2] ?? "";
+
+const ok = (m) => console.log(`  ✓ ${m}`);
+const warn = (m) => console.log(`  ! ${m}`);
+
+console.log(`\ndemobite v${pkg.version} — the DemoBites agentic recorder\n`);
+
+// ── 1. Environment checks ──────────────────────────────────────────────────
+const nodeMajor = Number(process.versions.node.split(".")[0]);
+if (nodeMajor >= 18) ok(`Node ${process.versions.node}`);
+else { warn(`Node ${process.versions.node} — 18+ required`); process.exit(1); }
+
+const hasBin = (bin) => {
+  try { execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "ignore" }); return true; }
+  catch { return false; }
+};
+const chromePaths = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "C:/Program Files/Google/Chrome/Application/chrome.exe",
+  "/usr/bin/google-chrome",
+];
+const haveChrome = chromePaths.some((p) => fs.existsSync(p)) || hasBin("google-chrome") || hasBin("google-chrome-stable");
+if (haveChrome) ok("Google Chrome (films with the real browser)");
+else console.log("  · Google Chrome not found — installing Playwright's Chromium for the recorder");
+if (hasBin("claude")) ok("Claude Code (drives the recorder; MCP registers automatically)");
+else warn("Claude Code not found — using Cursor or Codex? They drive the recorder too; MCP setup prints below");
+
+// ── 2. Install / update the skill ──────────────────────────────────────────
+const skillsDir = path.join(os.homedir(), ".claude", "skills");
+const dest = path.join(skillsDir, "agentic-recorder");
+fs.mkdirSync(dest, { recursive: true });
+fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+const copy = (from, to) => fs.copyFileSync(path.join(pkgRoot, from), path.join(dest, to));
+copy("skill/SKILL.md", "SKILL.md");
+for (const f of fs.readdirSync(path.join(pkgRoot, "skill/scripts"))) copy(`skill/scripts/${f}`, `scripts/${f}`);
+for (const f of fs.readdirSync(path.join(pkgRoot, "scripts"))) copy(`scripts/${f}`, `scripts/${f}`);
+ok(`Skill installed → ${dest}`);
+
+// Playwright and the media tools live with the skill so takes can film and
+// finish on any machine. ffmpeg and ffprobe are packaged per platform
+// (@ffmpeg-installer, @ffprobe-installer); a compatible system build is preferred when present
+// (scripts/media-tools.mjs decides). One line installs everything.
+const needed = ["playwright", "@ffmpeg-installer/ffmpeg", "@ffprobe-installer/ffprobe"].filter(
+  (m) => !fs.existsSync(path.join(dest, "node_modules", m)),
+);
+if (needed.length) {
+  console.log(`\n  Installing ${needed.join(", ")} (one-time)…`);
+  const r = spawnSync("npm", ["install", "--prefix", dest, "--silent", "--no-audit", "--no-fund", ...needed], { stdio: "inherit" });
+  if (r.status === 0) ok("Playwright ready");
+  else warn(`Install failed — run: npm install --prefix ~/.claude/skills/agentic-recorder ${needed.join(" ")}`);
+}
+// No Chrome on this machine: fetch Playwright's Chromium once so the first
+// take has a browser. Linux needs the shared libraries too (--with-deps).
+if (!haveChrome) {
+  const pw = path.join(dest, "node_modules", "playwright", "cli.js");
+  const marker = path.join(dest, ".chromium-ready");
+  if (!fs.existsSync(marker) && fs.existsSync(pw)) {
+    console.log("  Installing Chromium (one-time)…");
+    const args = [pw, "install", "chromium", ...(process.platform === "linux" ? ["--with-deps"] : [])];
+    const r = spawnSync("node", args, { stdio: "inherit", cwd: dest });
+    if (r.status === 0) { fs.writeFileSync(marker, new Date().toISOString()); ok("Chromium ready"); }
+    else warn(`Chromium install failed — run: node ${pw} install chromium${process.platform === "linux" ? " --with-deps" : ""}`);
+  } else if (fs.existsSync(marker)) ok("Chromium ready");
+}
+{
+  // Verify both tools actually run (compatibility, not presence).
+  const r = spawnSync("node", [path.join(dest, "scripts", "media-tools.mjs")], { encoding: "utf8" });
+  const rows = (r.stdout || "").trim().split("\n").filter(Boolean).map((l) => l.split("\t"));
+  for (const [tool, source, info] of rows) {
+    if (source === "missing") warn(`${tool}: no working build (${info})`);
+    else ok(`${tool} ready (${source === "packaged" ? "packaged with the recorder" : source === "system" ? "your system build" : "from .recorder/config.json"})`);
+  }
+  if (r.status !== 0) warn("Recording will fail until ffmpeg and ffprobe both work. Re-run this command, or install them on your system.");
+}
+
+// ── 3. Subcommands ─────────────────────────────────────────────────────────
+if (arg === "login" || arg === "logout") {
+  const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs"), ...(arg === "logout" ? ["--logout"] : [])], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+  process.exit(r.status ?? 0);
+}
+
+// ── 3b. Management MCP ─────────────────────────────────────────────────────
+// The key lives in <cwd>/.recorder/config.json (login.mjs writes it there),
+// so MCP registration is per-project too — `claude mcp add` default (local)
+// scope matches that exactly and keeps the key out of committable files.
+const readCfg = () => {
+  try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), ".recorder", "config.json"), "utf8")); }
+  catch { return null; }
+};
+const registerMcp = (cfg, { quiet = false } = {}) => {
+  const url = `${cfg.base ?? "https://app.demobites.com"}/api/mcp`;
+  const header = `Authorization: Bearer ${cfg.api_key}`;
+  if (hasBin("claude")) {
+    const r = spawnSync("claude", ["mcp", "add", "--transport", "http", "demobites", url, "--header", header], {
+      stdio: quiet ? "ignore" : "inherit",
+      cwd: process.cwd(),
+    });
+    if (r.status === 0) { ok(`DemoBites MCP registered with Claude Code (${url})`); return true; }
+  }
+  if (!quiet) {
+    console.log(`
+Add the DemoBites MCP to your agent manually — Streamable HTTP:
+
+    URL:     ${url}
+    Header:  ${header}
+
+Claude Code:  claude mcp add --transport http demobites ${url} --header "${header}"
+Cursor:       add the URL + header under Settings → MCP
+Other MCP clients: any Streamable HTTP client works with the same URL + header.
+`);
+  }
+  return false;
+};
+
+if (arg === "retake") {
+  const biteId = process.argv[3];
+  if (!biteId || !/^\d+$/.test(biteId)) { warn('Usage: npx demobite retake <biteId> [--note "what changed"]'); process.exit(2); }
+  let cfg = readCfg();
+  if (!cfg?.api_key) {
+    console.log("\n  Not connected yet — linking this machine to DemoBites first…\n");
+    const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs")], { stdio: "inherit", cwd: process.cwd() });
+    if (r.status !== 0) process.exit(r.status ?? 1);
+    cfg = readCfg();
+  }
+  if (!cfg?.api_key) { warn("Login did not complete — run: npx demobite login"); process.exit(1); }
+  const r = spawnSync("node", [path.join(dest, "scripts", "retake.mjs"), ...process.argv.slice(3)], { stdio: "inherit", cwd: process.cwd() });
+  process.exit(r.status ?? 1);
+}
+
+// Batch of briefs (2026-09-13): `npx demobite briefs list <batchId>` etc. and
+// `npx demobite status <takeDir|stagingId>` hand straight to the skill scripts.
+// WORKSPACE RULES (1.4): `npx demobite rules` prints the workspace's standing rules.
+if (arg === "briefs" || arg === "status" || arg === "rules") {
+  let cfg = readCfg();
+  if (!cfg?.api_key) {
+    console.log("\n  Not connected yet — linking this machine to DemoBites first…\n");
+    const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs")], { stdio: "inherit", cwd: process.cwd() });
+    if (r.status !== 0) process.exit(r.status ?? 1);
+    cfg = readCfg();
+  }
+  if (!cfg?.api_key) { warn("Login did not complete — run: npx demobite login"); process.exit(1); }
+  const r = spawnSync("node", [path.join(dest, "scripts", `${arg}.mjs`), ...process.argv.slice(3)], { stdio: "inherit", cwd: process.cwd() });
+  process.exit(r.status ?? 1);
+}
+
+if (arg === "mcp") {
+  let cfg = readCfg();
+  if (!cfg?.api_key) {
+    console.log("\n  Not connected yet — linking this machine to DemoBites first…\n");
+    const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs")], { stdio: "inherit", cwd: process.cwd() });
+    if (r.status !== 0) process.exit(r.status ?? 1);
+    cfg = readCfg();
+  }
+  if (!cfg?.api_key) { warn("Login did not complete — run: npx demobite login"); process.exit(1); }
+  registerMcp(cfg);
+  console.log(`
+Your agent can now manage DemoBites — try asking it:
+
+    "Create a release with my latest bites and add Spanish"
+
+Publishing always shows you a preview to approve first.
+`);
+  process.exit(0);
+}
+
+// ── 4. Handoff ─────────────────────────────────────────────────────────────
+// Bare invocation (and the `agentic-recorder` docs alias): if this project is
+// already linked, quietly wire the MCP too — one command, both magics.
+const cfg = readCfg();
+if (cfg?.api_key) registerMcp(cfg, { quiet: true });
+console.log(`
+Ready. Everything is agent-driven — open your coding agent (Claude Code,
+Cursor, Codex) in your project and ask:
+
+    "Record a demo of <your flow> and upload it to DemoBites"
+    "Create a release with my latest bites and add Spanish"
+
+It signs in via your browser on first use (or run: npx demobite login).
+Manage-by-agent needs the MCP: npx demobite mcp (once, after login).
+Only the recorder, no DemoBites? See the open recorder in this package's repo.
+`);

package/package.json

@@ -1,14 +1,42 @@
 {
   "name": "demobites",
-  "version": "1.0.9",
-  "description": "DemoBites agentic recorder (plural spelling). Same command as npx demobite.",
-  "type": "module",
-  "bin": { "demobites": "index.mjs" },
-  "files": ["index.mjs", "README.md", "LICENSE"],
-  "dependencies": { "demobite": "^1.0.9" },
-  "engines": { "node": ">=18" },
-  "keywords": ["demobites", "agentic recorder", "demo video", "playwright", "claude code", "cursor", "codex", "mcp"],
-  "repository": { "type": "git", "url": "git+https://github.com/demobites/agentic-recorder.git", "directory": "aliases/demobites" },
+  "version": "1.4.0",
+  "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
+  "bin": {
+    "demobites": "launcher/index.mjs"
+  },
+  "files": [
+    "launcher",
+    "skill",
+    "recorder",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "demo",
+    "screen-recording",
+    "playwright",
+    "claude-code",
+    "skill",
+    "demobites",
+    "agentic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/demobites/agentic-recorder.git"
+  },
   "homepage": "https://github.com/demobites/agentic-recorder#readme",
-  "license": "MIT"
+  "bugs": {
+    "url": "https://github.com/demobites/agentic-recorder/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "release": "node scripts/release.mjs",
+    "prepublishOnly": "node scripts/check-release.mjs"
+  }
 }

package/recorder/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: open-recorder
+description: Film a polished product demo by driving a real browser from a storyboard, delivering a finished styled demo.mp4 — no account required. The open sibling of the DemoBites agentic recorder.
+---
+
+# The Open Recorder
+
+The same filming engine as the DemoBites agentic recorder — storyboard-driven
+Playwright capture in a real Chrome, hover-anchor clock calibration, human-pace
+cursor motion — ending at a finished, styled `demo.mp4` on your disk.
+
+Phases (shared engine lives in `../scripts/`):
+
+1. **Storyboard** — write the shot list as JSON (see the schema in
+   `../skill/SKILL.md`, identical here), show it to the human, get approval.
+2. **Dry run** — resolve every selector headless before filming.
+3. **The take** — `node ../scripts/record.mjs <takeDir> <storyboard.json>`
+4. **Trim + calibrate** — `node ../scripts/trim.mjs <takeDir>` then
+   `node ../scripts/calibrate.mjs <takeDir>`
+5. **Deliver** — the standalone finishing tools in `scripts/`:
+   `frame.mjs` (rounded corners + shadow), `post.sh` (backdrop + trim to
+   `demo.mp4`), optional `tts.mjs`/`mux.mjs` voiceover with your own
+   ElevenLabs key, optional SRT captions.
+
+The full standalone-ending reference, preserved verbatim from the original
+skill, is in `STANDALONE-ENDING.md`.
+
+Want narration written for you, cinematic zooms, a rendered cursor, an
+editable timeline, hosting and analytics? That is the DemoBites ending — the
+sibling skill in `../skill/`, one login away: `npx demobite login`.

package/recorder/STANDALONE-ENDING.md

@@ -0,0 +1,34 @@
+# PARKED: the standalone ending (future community skill)
+
+This skill is the COMMERCIAL DemoBites recorder — it does not offer a
+standalone MP4. The content below is preserved verbatim for the planned
+open-source community skill and is NOT part of this skill's flow.
+Do not ask the human which ending they want; there is one ending.
+
+### Ending A: STANDALONE
+
+Deliver a finished, styled demo.mp4.
+
+```bash
+node scripts/frame.mjs <takeDir>            # look overlays: shadow + alpha mask (radius 28)
+scripts/post.sh <takeDir> <backdropHexNo#>  # raw.webm -> demo.mp4, backdrop + corners + shadow + trim
+```
+
+Look laws inside: TRUE alpha mask rounded corners (alphamerge, radius 28, never painted on), shadow strength derived from backdrop luminance, `shortest=1` so the still overlays never extend the cut.
+
+Optional voiceover, only with the customer's OWN ElevenLabs key (env `ELEVENLABS_API_KEY` or `.recorder/elevenlabs.key`, never ask the human to paste it into chat):
+
+```bash
+node scripts/tts.mjs <takeDir>              # narration lines -> measured mp3 segments
+node scripts/mux.mjs <takeDir>              # demo.mp4 -> demo-voiced.mp4, anchored to real step timings
+```
+
+Optional captions:
+
+```bash
+node scripts/manifest.mjs <takeDir> --srt   # writes captions.srt from the narration timeline
+ffmpeg -i <takeDir>/demo-voiced.mp4 -vf "subtitles=<takeDir>/captions.srt" -c:a copy <takeDir>/demo-captioned.mp4
+```
+
+Deliverables: `demo.mp4` (or `demo-voiced.mp4` / `demo-captioned.mp4`) plus `manifest.json`.
+

package/recorder/scripts/frame.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Standalone ending only — generate the look overlays for post.sh:
+// a shadow ring PNG and a TRUE rounded-alpha mask PNG.
+//
+// LAW (true alpha corners): rounded corners must be a real alpha mask fed to
+// ffmpeg alphamerge — never painted-on corner squares. Radius 28.
+// LAW (shadow from luminance): shadow strength derives from the backdrop's
+// luminance — light backdrops get a soft ink shadow, dark backdrops a deep one.
+//
+// Usage: node frame.mjs <takeDir> [backdropHex]
+// Backdrop resolution order: CLI arg, .recorder/config.json look.backdrop, #0f1420.
+import { chromium } from "playwright";
+import fs from "node:fs";
+import path from "node:path";
+
+const [, , outDir, argBackdrop] = process.argv;
+if (!outDir) {
+  console.error("Usage: node frame.mjs <takeDir> [backdropHex]");
+  process.exit(2);
+}
+let backdrop = argBackdrop;
+if (!backdrop) {
+  try {
+    backdrop = JSON.parse(fs.readFileSync(path.resolve(".recorder", "config.json"), "utf8")).look?.backdrop;
+  } catch {}
+}
+backdrop = backdrop || "#0f1420";
+if (!/^#?[0-9a-fA-F]{6}$/.test(backdrop)) {
+  console.error(`Backdrop must be a 6 digit hex color, got "${backdrop}"`);
+  process.exit(2);
+}
+if (!backdrop.startsWith("#")) backdrop = "#" + backdrop;
+fs.mkdirSync(path.resolve(outDir), { recursive: true });
+
+const hx = backdrop.slice(1);
+const light =
+  parseInt(hx.slice(0, 2), 16) * 0.299 +
+  parseInt(hx.slice(2, 4), 16) * 0.587 +
+  parseInt(hx.slice(4, 6), 16) * 0.114 > 128;
+const W = 1920, H = 1080, VW = 1728, VH = 972, R = 28;
+const X = (W - VW) / 2, Y = (H - VH) / 2;
+
+const b = await chromium.launch();
+const p = await b.newPage();
+await p.setViewportSize({ width: W, height: H });
+// Shadow ring: transparent page, rounded rect with only its box-shadow visible.
+const shadow = light
+  ? "0 14px 60px rgba(20,22,28,.16), 0 3px 14px rgba(20,22,28,.08)"
+  : "0 18px 80px rgba(0,0,0,.5), 0 4px 20px rgba(0,0,0,.3)";
+await p.setContent(`<body style="margin:0;background:transparent"><div style="position:absolute;left:${X}px;top:${Y}px;width:${VW}px;height:${VH}px;border-radius:${R}px;background:transparent;box-shadow:${shadow}"></div></body>`);
+await p.screenshot({ path: path.join(outDir, "shadow.png"), omitBackground: true });
+// Alpha mask: black canvas, white rounded rect — post.sh alphamerges this
+// grayscale source onto the scaled video.
+await p.setViewportSize({ width: VW, height: VH });
+await p.setContent(`<body style="margin:0;background:#000"><div style="position:absolute;inset:0;border-radius:${R}px;background:#fff"></div></body>`);
+await p.screenshot({ path: path.join(outDir, "mask.png") });
+await b.close();
+console.log("overlays ready (radius", R + "px,", light ? "light" : "dark", "shadow,", "backdrop", backdrop + ")");

package/recorder/scripts/mux.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Standalone ending only — mux the measured TTS segments onto the composited
+// cut (demo.mp4), anchored to the manifest's REAL step timings. The script is
+// the metronome: each line starts when its step starts, minus the trim.
+//
+// Founder-proven anchor tweaks (kept, commented):
+//   * the OPENING line gets a +0.3s beat after the hold starts, so the voice
+//     never fires on the very first frame
+//   * a line attached to a SCROLL step starts 1.5s early — it describes the
+//     page that just revealed, so it lands as the page settles, before the
+//     scroll moves
+//
+// Usage: node mux.mjs <takeDir>
+// Reads <takeDir>/demo.mp4 + <takeDir>/manifest.json + <takeDir>/tts/tts.json.
+// Writes <takeDir>/demo-voiced.mp4.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const dir = process.argv[2];
+if (!dir) {
+  console.error("Usage: node mux.mjs <takeDir>");
+  process.exit(2);
+}
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE, requireMediaTools } from "../../scripts/media-tools.mjs";
+requireMediaTools(["ffmpeg","ffprobe"]);
+
+const demoPath = path.join(dir, "demo.mp4");
+const manPath = path.join(dir, "manifest.json");
+const ttsPath = path.join(dir, "tts", "tts.json");
+if (!fs.existsSync(demoPath)) { console.error(`${demoPath} not found. Run frame.mjs + post.sh first.`); process.exit(1); }
+if (!fs.existsSync(manPath)) { console.error(`${manPath} not found. Run record.mjs first.`); process.exit(1); }
+if (!fs.existsSync(ttsPath)) { console.error(`${ttsPath} not found. Run tts.mjs first.`); process.exit(1); }
+
+const man = JSON.parse(fs.readFileSync(manPath, "utf8"));
+const tts = JSON.parse(fs.readFileSync(ttsPath, "utf8"));
+const r0 = man.record_from ?? 0;
+
+// Anchor each narrated step to its real start time, normalized to the cut.
+const narrated = (man.steps ?? []).filter((s) => s.narration?.text);
+const anchors = new Map();
+let first = true;
+for (const s of narrated) {
+  let at = (s.t_start ?? 0) - r0;
+  if (first) { at += 0.3; first = false; } // opening line, small beat after the hold starts
+  if (s.action === "scroll") at -= 1.5;    // page reveal line starts as the page settles, before the scroll
+  anchors.set(s.n, Math.max(0.05, Math.round(at * 100) / 100));
+}
+console.log("narration anchors (s):", JSON.stringify(Object.fromEntries(anchors)));
+
+const inputArgs = [];
+for (const seg of tts) inputArgs.push("-i", path.join(dir, "tts", seg.file));
+const delays = tts
+  .map((seg, i) => {
+    const ms = Math.round((anchors.get(seg.n) ?? 0) * 1000);
+    return `[${i + 1}:a]adelay=${ms}|${ms}[a${i}]`;
+  })
+  .join(";");
+const mix = tts.map((_, i) => `[a${i}]`).join("") + `amix=inputs=${tts.length}:normalize=0[aout]`;
+
+const outPath = path.join(dir, "demo-voiced.mp4");
+execFileSync(FFMPEG(), [
+  "-y", "-loglevel", "error",
+  "-i", demoPath,
+  ...inputArgs,
+  "-filter_complex", `${delays};${mix}`,
+  "-map", "0:v", "-map", "[aout]",
+  "-c:v", "copy", "-c:a", "aac", "-b:a", "160k",
+  outPath,
+], { stdio: "inherit" });
+const dur = execFileSync(FFPROBE(), [
+  "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", outPath,
+]).toString().trim();
+console.log(`demo-voiced.mp4 ready, ${parseFloat(dur).toFixed(2)}s`);