Repository navigation
Glossary
Archi edited this page Oct 18, 2026
·
1 revision
The words this wiki, the specs and the code use, with the page that explains each in full.
The terms below are grouped by where they appear: the files you write, the run DemoFlow performs, the video it renders, and the parts of the project.
flowchart LR
SC["scenario"] --> RUN["run"] --> RD["run directory"]
RD --> TL["timeline"] --> RP["render plan"] --> VID["video"]
RD --> RES["result.json"]
| Term | Meaning | More |
|---|---|---|
| scenario | A JSON file demoflow/**/*.demo.json describing one demo: a name, a viewport and up to 200 steps. |
Scenarios |
| step | One action in a scenario: navigate, waitFor, click, fill, select, hover, press, scroll, assertVisible, assertText, screenshot, marker or wait. |
Scenarios |
| locator | How a step finds an element: by role and name, label, testId, text, placeholder, or css (accepted with a warning). |
Scenarios |
| marker | A step that marks a moment without acting: kind: 'scene' starts a scene, kind: 'caption' shows a caption. |
Scenarios |
| caption | Short text on a step or a caption marker, shown as a lower-third in the video. | Rendering and Effects |
| project config |
demoflow.config.json at the project root: baseUrl, allowedOrigins, devCommand, artifactsDir, render. |
Project Configuration |
valueFrom.env |
A fill value read from an environment variable at run time, so the secret is never in the scenario. |
Secrets and Masking |
| Term | Meaning | More |
|---|---|---|
| run | One execution of a scenario, identified by a run id YYYYMMDD-HHmmss-xxxxxx (UTC). |
Running Demos |
| stage | One phase of a run: readiness, execution, verification, recording, rendering, storage. Each is pending, running, passed, failed or skipped. |
How a Demo Flows |
| readiness | Checks before the browser starts: allowed origins, a base URL for relative paths, every secret env var set. | How a Demo Flows |
| verification | The assertion steps; skipped when the scenario has none. |
Scenarios |
| origin guard | Stops a run that navigates to an origin not in allowedOrigins. |
Security and Access |
| home | The directory holding run directories; resolved from --out, DEMOFLOW_HOME, artifactsDir or the OS data directory. |
Run Artifacts |
| run directory |
<home>/runs/<runId>/: source.webm, timeline.json, scenario.json, result.json, screenshots/, render/ffmpeg.mp4. |
Run Artifacts |
result.json |
The run's outcome: status, stages, renders, warnings. | Run Artifacts |
| timeline |
timeline.json: what each step did and when, in ms from the video's first frame and CSS pixels. |
Run Artifacts |
| sync mark | A magenta frame the engine paints at clock zero so the renderer can line the video up with the timeline. | Rendering and Effects |
| task | One MCP generate_demo request; queued, running, completed, failed, cancelled or timed_out. |
MCP Server |
| Term | Meaning | More |
|---|---|---|
| source video |
source.webm, the plain recording at the viewport size (1×). |
Rendering and Effects |
| render plan | The JSON the renderer builds from the timeline and executes with FFmpeg. | Rendering and Effects |
| compositor | The FFmpeg-only renderer that draws every effect. | Rendering and Effects |
| idle compression | A frozen stretch at least idle.thresholdMs long plays in idle.compressToMs. |
Rendering and Effects |
| frame / background | The page drawn in a rounded, shadowed window on a gradient or colour. | Rendering and Effects |
| mask | A blurred box over a secret field, kept in place through scrolls. | Secrets and Masking |
| key badge | A small label such as Control + a shown during a press step. |
Rendering and Effects |
| failure card | The "FAILED" watermark and 3 s end card on a failed run's video. | Rendering and Effects |
| visual baselines | Committed reference images the renderer tests compare against. | Contributing |
| Term | Meaning | More |
|---|---|---|
| execution plane | Core, engine, renderer and CLI: everything that runs on your machine, on Node. | Architecture |
| control plane | The website and API (scaffolding; Phase 5). | Architecture |
| Runner | A planned local agent paired with the website. Not built. | Status and Roadmap |
| fixture app |
apps/fixture, the test app real runs use in CI. |
Contributing |
| ADR | An architecture decision record in docs/adr/; superseded, never rewritten. |
Architecture |
| spec | One issue's specification in docs/specs/<issue>-<slug>.md. |
Contributing |
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference