Glossary

Each word on this page has one meaning in the docs, the CLI and the skills. A word with a dotted underline on another docs page links to its entry here. Hold the pointer on the word to see the first sentence.

The page and time

Page

A page is one HTML file, films/<name>/page.html, that describes a whole film. You write it in HTML, CSS, Web Animations, SVG, canvas or three.js, so you learn no private format. Read The page.

Film

A film is the mp4 file that the renderer makes from one page. One page gives one film for each aspect and each set of params, and the CLI names each file so that they do not overwrite each other. Read Introduction.

Page contract

The page contract is the set of rules that a page obeys so that the renderer, the checks and the judge can read it. A page that breaks the contract can render, but the tools then measure the wrong thing. Read The page.

Duration

The duration is the film length in seconds, set by <meta name="duration" content="12.4">. The value auto uses the end of the last animation plus a hold, and vawe dev --lock-length writes the found number into the page. Read The page.

World

A world is the one element that holds one beat of the film, marked with data-world="<id>". The checks, the judge, strip --cuts and the storyboard find the beats through these elements, so each beat needs its own world element. Read Worlds.

Beat

A beat is one part of the story with one idea, such as the hook, a feature or the end. The brief lists the beats as Shots, and the page gives each beat one worldA world is the one element that holds one beat of the film, marked with data-world="<id>".. Read Worlds.

Seek

To seek is to set the page to a time t in seconds and paint the frame for that time. The renderer never plays the page, so every frame must come from t alone and not from a clock. Read Time and seek.

Virtual clock

The virtual clock is the code in core/engine/page-clock.js that controls Date, requestAnimationFrame, timers and Math.random during a render. It makes these follow the seek time, so code that reads the clock still gives the same frames. Read Determinism.

Determinism

Determinism means that the same page gives the same frames on every render, in any order. It lets the renderer capture slices in parallel and render again only the seconds that you changed. Read Determinism.

Seeded random

A seeded random number comes from a generator that starts from a fixed seed, such as rng(seed) in core/motion/springs.js. An unseeded random value changes on each render and breaks determinismDeterminism means that the same page gives the same frames on every render, in any order.. Read Time and seek.

Aspect

The aspect is the width-to-height ratio of a film, such as 16:9, 9:16 or 1:1. The page lays out with --vw and --vh and never crops, so one page can render in each aspect with --aspect W:H. Read Aspect ratios.

Message

The message is the one thing that a viewer must remember, set by <meta name="message">. The storyboard and the fresh judge read this sentence, so write it before you write the page. Read The page.

Spectacle

The spectacle is the second of the one big moment in a film, set by <meta name="spectacle" content="6.2">. You put quiet before it, and the board plans the film around it. Read The page.

Literal

A literal is a tunable number that you write in the page: a [[f, v]] table row, a keyframe stop or a :root custom property. The studio finds literals and edits them in place; it cannot edit a number that the page computes when it runs. Read The page.

Param

A param is a page option that you pass with --param key=value, and the page reads it with new URLSearchParams(location.search). One page can then render several looks or rows of data, and each param becomes part of the output name. Read CLI.

Page API

The page API is the window.vawe object that the renderer sets before your scripts run: aspect, width, height, fps, duration, onFrame and more. Use it to read the render settings instead of guessing them. Read The page.

Waiver

A waiver is a declared break of a check rule, with a measured reason, in the page’s <script id="authoring"> block. The checks accept the break only when the reason names the place and a measured value, so a waiver records a decision and not an excuse. Read Waivers.

Making a film

Loop

The loop is the ten stages that make a film: brief, references, design kit, states, board, draft, motion pass, critique, fix and final. Each verb prints a next: line that names the next stage, so you can follow the loop without a map. Read Use with an agent.

Stage

A stage is one step of the loopThe loop is the ten stages that make a film: brief, references, design kit, states, board, draft, motion pass, critique, fix and final., with one command and one result. Do the stages in order: the board comes before the draft, and the critique comes before the final. Read Use with an agent.

Brief

The brief is films/<name>/brief.md, the file of facts and plans for one film. vawe new writes it, asks for the details that the request leaves open, and every later stage reads it. Read Write the brief.

Template

A template is a file in prompts/ for one type of film, with when to use it, the brief to fill in, a question bank and known mistakes. vawe new --from prompts/<template>.md starts a brief from it, so you begin from what worked before. Read Write the brief.

Reference

A reference is an existing film that you study or recreate. References live outside the repo in ~/.vawe/refs, and vawe refs add stores and measures a new one. Read Study references.

Recreation

A recreation is a film that rebuilds one reference, started with vawe new <name> --ref <mp4>. It gets a SPEC.md of measured values, and vawe critique --ref compares your draft with the reference until it passes. Read Match a reference film.

Design kit

The design kit is films/<name>/DESIGN.md and the kit/ folder: the palette, the type, the ground and the parts of one film. Every key frame uses the kit, so the frames look like one film. Read Design system and kit.

Key frame

A key frame is one still of a world in its settled state. vawe frames <page> writes one for each world, so you can see the layout before you animate anything. Read Key frames and the board.

Board

The board is the “Board” section of the brief: a plan for time, with the rhythm of the cuts, the spectacle second, one named move for each cut and the sound. A board finds timing problems before a draft costs render time. Read Key frames and the board.

Storyboard

A storyboard is an HTML page with one card for each world, made by vawe storyboard. It shows the moves, eases, handoffs, sound and rhythm of the page on one screen. Read Key frames and the board.

Animatic

An animatic is a silent mp4 that holds the key frame of each world for its planned time, with hard cuts, made by vawe animatic. It tests the timing of a film in a few seconds, before any motion exists. Read Key frames and the board.

Draft

A draft is a fast render at half size and 30 fps, with sound, made by vawe dev. You make many drafts and one final; a --from/--to window renders only those seconds, without sound. Read Draft.

Cut

A cut is the change from one world to the next. Most of the motion advice is about cuts, because a cut is where the eye can get lost. Read Motion pass.

Handoff

A handoff is the thing that carries the eye across a cut, such as a match cut, a shared axis or a colour flood. vawe names twelve handoff families, and the board names what carries the eye at each cut. Read Motion pass.

Motion pass

The motion pass is the stage where you look at every cut of the draft with vawe strip --cuts and write one row for each cut in the brief. It finds the flat moves and dead holds that a single frame cannot show. Read Motion pass.

Critique

A critique is a review of a draft by a session that did not write the page, run with vawe critique <page>. It starts from REJECT and lists each finding with a second, a frame and a fix. Read Critique and fix.

Fresh session

A fresh session is an agent session that did not write the page, in a separate terminal or agent. A new VAWE_AGENT name in the same session does not make one. The critique and the judge must run in one, because an author misses the faults in their own film. Read Critique and fix.

Judge

The judge is a scored review of a film against a rubric, prepared by vawe judge. vawe judge --fresh scores it in a separate headless session; it advises and never blocks, and an author never records a PASS for their own page. Read Critique and fix.

Owner

The owner is the person who asked for the film and signs it off. Only the owner runs vawe approve; an agent never runs it. Read Approve and ship.

Approve

To approve is to record that the owner accepts the full draft, with vawe approve <page>. vawe ship refuses to start without this approval, so no final reaches anyone without a person’s yes. Read Approve and ship.

Final

A final is the full-quality render: 60 fps, motion blur and the mixed audio, followed by a final check. It costs much more time than a draft, so you make it once, after the approval. Read Approve and ship.

Ship

To ship is to make the final with vawe ship <page>, which runs in the background. It refuses until a fresh review and the owner’s approval exist, and vawe ship --status --wait reports the result. Read Approve and ship.

Motion, look and sound

Move

A move is a named, copyable piece of motion, such as mask-rise or whip-pan, with its CSS and Web Animations code, notes, a sound line and a clip. Moves come in seven groups, from “Reveal a title” to “Grounds”, and live in prompts/moves/. Read Motion.

Recipe

A recipe is a chain of moves for one short film, with a table of beats, sound cues and transitions. prompts/moves/RECIPES.md has fifteen recipes, from a 5 s brand sting to a 22 s product demo. Read Recipes.

Ease

An ease is the curve that sets how a value changes speed during a move. vawe names ten eases, such as land for an arrival and launch for an exit, and the renderer sets each one as a CSS variable --ease-<name>. Read Motion.

Spring

A spring is a motion curve that a stiffness and a damping value set, computed by the functions in core/motion/springs.js. A spring gives a natural arrival and can overshoot, and it stays a pure function of the time. Read Motion.

Overshoot

An overshoot is an arrival that goes past its target and comes back. In 17 measured reference films, about 30% of arrivals overshoot, and the overshoot-share check compares your draft with that share. Read Motion.

Lens

The lens is the camera in core/surfaces/lens.js that films a flat page like a real object, with depth of field, bloom, grain and more. It makes these effects in image space, so they look real and never come from CSS fakes. Read Motion.

Look

A look is a named set of lens settings, such as film-halation or crt, passed as lens(source, { look }). vawe frames <page> --looks shows the page under every look, so you can compare them before you choose. Read Motion.

Motion blur

Motion blur is the streak of a fast move, made in the final by blending up to 32 subframes for each frame. The renderer measures how far each frame moves and uses more subframes only where the motion is fast. Read Motion.

Ground

The ground is the background layer of a world. A ground must never be flat or still, because a dead background makes a held frame look frozen. Read Backgrounds and images.

Cue

A cue is one sound at one second, written as an <audio> tag with data-at. The house rule is small cues on actions, and a recorded effect comes before a synth voice. Read Audio.

Voice

A voice is one of the built-in synth sounds, such as pluck or whoosh, chosen with data-synth="<voice>". vawe sound lists the voices with their default gain and length. Read Audio.

Bed

A bed is a music track that plays under the whole film, marked by the loop attribute on an <audio> tag. A bed must come from a file that the user gives, and the mixer refuses synth beds such as bed, pad and drone. Read Audio.

Duck

To duck is to lower the music while a voice speaks. An <audio> tag with data-role="vo" ducks the bed by 18 dB, so the words stay clear. Read Audio.

Tools and checks

Verb

A verb is one command of the vawe CLI, such as new, dev or ship, run as bin/vawe <verb>. bin/vawe --help lists the common verbs, --help --all lists every verb, and bin/vawe <verb> --help explains one. Read CLI.

Next line

The next line is the next: line that each verb prints, which names the command to run after it. Follow it, and you do the stages in the right order. Read CLI.

Skill

A skill is a SKILL.md file of instructions that an agent loads for one task, such as vawe-page for writing a page. Install the vawe skills with npx skills add vawe-hq/skills, or use them in place inside a vawe checkout. Read Use with Claude Code, Codex or Cursor.

Doctor

The doctor is the verb vawe doctor, which checks Node, git, ffmpeg, ffprobe, Chrome and the fonts. It prints the install line for each missing tool, so a failed setup tells you what to do. Read Install and doctor.

Studio

The studio is a live preview that you open with vawe studio <page>, with a scrubber that uses the render clock and seek. It edits the literalsA literal is a tunable number that you write in the page: a [[f, v]] table row, a keyframe stop or a :root custom property. of the page in place, so you tune a number and see the result at once. Read CLI.

Strip

A strip is a row of frames through one moment or across every cut, made by vawe strip. It shows motion in one image, so you can read a move without a video player. Read CLI.

Sheet

A sheet is a grid of frames from a page, a draft or a reference, made by vawe sheet. It shows a whole film on one screen, and --ref puts the reference beside your film. Read CLI.

Check

A check is an automatic measurement of a page or a film that reports a problem and a fix. Most checks advise and never stop a render, because the author can know a reason that the check cannot see. Read Checks.

Gate

A gate is a named check that you run with vawe check <name>, such as anim-traps or page-check. vawe check with no name lists every gate. Read Checks.

Refuse

To refuse is to stop a verb with an error instead of an advice line. vawe refuses only for a page that cannot repeat its frames, a banned item, a waiver without a valid reason, or a final without a fresh review and the owner’s approval. Read Checks.

Taste rule

A taste rule is one written rule of film craft in taste/rules/<id>.md, such as “exits shorter than entrances”. taste/build/DIGEST.md is the short list of taste pitfalls, so read it before you write a page. Read Checks.

Render key

The render key is a short hash of the page folder, core/ and the render settings, including each param. Two renders with the same key give the same pixels, so the renderer can reuse the frames of the first one. Read Determinism.

Kept frames

The kept frames are the captured frames that a render stores in a folder named after its render key. A failed final resumes from them, and a second render of an unchanged page reuses them instead of capturing again. Read Determinism.

Run log

The run log is out/<film>.runs.jsonl, one JSON line for each command with its stage, time and result. vawe runs <film> reads it, so you can see where a film spent its time. Read Use with an agent.

From the blogHTML to video format: the page contract · Seed Math.random and freeze Date.now in JavaScript