Skip to content

Glossary

Archi edited this page Oct 18, 2026 · 1 revision

Glossary

The words this wiki, the specs and the code use, with the page that explains each in full.

Overview

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"]
Loading

Files you write

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

The run

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

The video

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

The project

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

See also

Clone this wiki locally