Skip to content

Latest commit

 

History

History
191 lines (152 loc) · 8.84 KB

README.md

File metadata and controls

191 lines (152 loc) · 8.84 KB

DemoFlow

Verified, polished demo videos of the features you ship — from one JSON scenario.

npm execution plane license: MIT docs: wiki

Getting started · Wiki · CLI reference · MCP server · Roadmap

A JSON scenario becomes a verified browser run, then a polished demo video

DemoFlow drives your web app in Chromium through a short scenario — navigate, click, fill, assert — and records it. If an assertion fails, the run fails and the video says so; a demo that shows a broken feature never looks like a working one.

The recording is then rendered into an MP4 with a smooth drawn cursor, click rings, camera zoom on the steps that ask for it, captions, idle time compressed, and the page in a rounded window on a background. Passwords come from environment variables, never touch disk or logs, and are blurred in the video.

Everything runs on your machine. Run it from the command line, from CI, or let an AI agent such as Claude Code ask for a demo over MCP.

Features

Feature What it does
Scenarios A JSON file with up to 200 steps and accessible-role locators, validated by a JSON Schema. Data lists and a repeat step run the same steps once per item.
Running demos demoflow run checks readiness, starts your app if configured, runs the steps and renders the video.
Recording scenarios demoflow record writes the scenario while you click through the app in a browser.
Rendering and effects An FFmpeg compositor adds cursor, rings, zoom, captions, key badges, a window frame and a background.
Secrets and masking valueFrom.env keeps secrets out of files and logs; their fields are blurred in the video.
Run artifacts Every run leaves the video, a timeline and a result.json with per-stage status and exit codes for CI.
MCP server demoflow mcp lets Claude Code generate a demo, poll the task and get the video path back.

Note

demoflow@0.1.0 on npm has run, validate, setup and mcp. record, the press step, starting the app from devCommand, key badges and the window frame are on develop and ship in the next release, with cards, transitions, GIF/WebM export and the vertical 9:16 MP4 (mp4-vertical), as do login, logout and the background runner with online status. Jobs over the Runner connection are not built yet — see Status and Roadmap.

How a demo flows

flowchart LR
  S["scenario.demo.json"] --> RD["readiness<br/>origins · env secrets"]
  RD --> EX["execution<br/>Chromium runs the steps"]
  EX --> VE["verification<br/>assertions"]
  VE --> RC["recording<br/>source.webm + timeline"]
  RC --> RN["rendering<br/>FFmpeg compositor"]
  RN --> MP4["render/ffmpeg.mp4<br/>result.json"]
Loading

Architecture

flowchart TB
  CC["Claude Code"] -->|"MCP · stdio"| CLI
  YOU["You / CI"] --> CLI["demoflow CLI"]
  CLI --> ENG["engine<br/>Playwright"] --> REN["renderer<br/>FFmpeg"]
  CORE["core<br/>zod contracts"] -.-> CLI
  CORE -.-> ENG
  CORE -.-> REN
Loading
  • Recording is separate from rendering — the source stays a faithful capture; every effect is applied afterwards from the timeline (ADR-0004, ADR-0005).
  • Scenarios and config are data, never code — JSON an agent can write and a person can review (ADR-0003).
  • Local first — the browser, your app and your secrets stay on your machine (ADR-0001, ADR-0008).

More in Architecture.

Quick start

Needs Node.js 22+. Create demoflow.config.json in your project:

{ "baseUrl": "http://localhost:3000" }

Write demoflow/first.demo.json:

{
  "schemaVersion": 1,
  "name": "Open the settings",
  "steps": [
    { "action": "navigate", "path": "/" },
    { "action": "click", "target": { "role": "link", "name": "Settings" }, "caption": "Open the settings" },
    { "action": "assertVisible", "target": { "role": "heading", "name": "Settings" } }
  ]
}

With your app running:

npx demoflow run demoflow/first.demo.json

Chromium is downloaded on first use. The summary prints the path of the video. To connect Claude Code instead: claude mcp add demoflow -- npx demoflow mcp.

Repeat steps over data

A scenario can declare data lists and run a group of steps once per item. {{post.text}} is the item's text field and {{index}} its 1-based position; they work in every string of a step inside the repeat:

{
  "schemaVersion": 1,
  "name": "Post three updates",
  "data": {
    "posts": [{ "text": "Hello" }, { "text": "Shipping today" }, { "text": "Thanks!" }]
  },
  "steps": [
    { "action": "navigate", "path": "/feed" },
    {
      "action": "repeat",
      "each": "posts",
      "as": "post",
      "caption": "Three posts",
      "steps": [
        { "action": "click", "target": { "role": "button", "name": "Compose" } },
        { "action": "fill", "target": { "label": "Post" }, "value": "{{post.text}}" },
        { "action": "click", "target": { "role": "button", "name": "Publish" } }
      ]
    }
  ]
}
  • A list holds 1–100 items of strings, numbers and booleans; as defaults to item; a repeat holds 1–50 steps and no repeat of its own.
  • Its caption is shown once, before the first iteration.
  • Every field a step uses must be in every item, and a URL, path or key must be valid once filled in. demoflow validate reports any problem by step path (steps[1].steps[1].value) before anything runs.
  • {{…}} is an error outside a repeat and in valueFrom; write \\{{ in JSON for a literal {{.
  • The timeline and result.json count the expanded steps, and tag each with origin: { repeatIndex, iteration } (0-based). A failure reads step 4 (repeat steps[1], iteration 3).

Pair a machine with your account

demoflow login prints a code, opens the website, and stores a revocable device token once you approve the code there. demoflow logout revokes it. Every other command works without an account. See apps/cli/README.md.

demoflow runner start keeps the paired machine connected in the background, so /app/machines shows it online. See apps/cli/README.md.

Documentation

Where What
Wiki How to use and operate DemoFlow: one page per feature, configuration, CLI and MCP reference, FAQ
docs/adr/ Architecture decisions, one per record, superseded never rewritten
docs/specs/ One specification per issue
docs/product/ Product vision and roadmap
apps/cli/README.md The README shipped in the npm package
deploy/README.md Staging deploy and npm release, for maintainers

Contributing

Bun workspaces and Turborepo; bun install, then bun run check and bun run test. Pull requests target develop. Local setup (Docker, env files) is in Contributing and CLAUDE.md.

License

MIT. The bundled Inter fonts are under the SIL Open Font License 1.1.