# Writing scenes The HTML scene authoring contract, with small examples that link a style and render in any of them. The HTML scene contract, with examples that render in `swiss` and `terminal` alike. Agents follow the same contract through the plugin's `rapid-scene` skill, whose reference files (`plugin/skills/rapid-scene/*.md`) document every library call. The [libraries](/docs/shots), a style's [components](/docs/style-json#the-components-folder), and the join's [transitions](/docs/transitions) are starting points. Use one as it is, tune it, copy it into the scene and change it, or write your own when the moment needs something else; only the contract below is fixed. ## The smallest scene ```html

hello.

``` The scene names no colour, face, or type size. `` brings them from the style it renders in, and the kit classes `field` and `display` use them. Save it as `hello.html` and render it in each style: ```sh rapid render hello.html --style swiss --out out/swiss/hello.mp4 rapid render hello.html --style terminal --out out/terminal/hello.mp4 ``` `swiss` sets the word in a bold grotesque on off-white paper; `terminal`, in lowercase monospace on a near-black screen. Each command prints one JSON line naming what it wrote: the MP4, with `hello.boxes.json` and `hello.cues.json` beside it. No daemon needed. One frame, or a strip of them, without a full render: ```sh rapid still hello.html --style swiss --t 0.5 --out out/hello-0.5.png rapid sheet hello.html --style swiss --times 0.2,0.5,1.9 --out out/hello-sheet.png ``` A scene that links `rapid:style` needs `--style`; without one, the render stops with `the scene links rapid:style; render it with a style`. `--style` takes a built-in style by name (`swiss`, `terminal`), an installed or pinned one, or a folder. ## The contract 1. **One file, one scene.** A whole document with a `` and a ``. In a video, its file is `scenes/.html` and its id is the storyboard scene's. 2. **The meta block** is a ``, rapid's [shot library](/docs/shots) `rapid:lib/shots@1`, and `camera`, `motion`, `fields`, `shapes`, `charts`, and `pictures`, each `@1` ([the other libraries](/docs/shots#the-other-libraries)). Another version, or an unknown name, is refused. 5. **Nothing from the network.** An absolute address in the HTML or CSS outside the scene's folder is refused; anything a script builds at run time is blocked. Put images, fonts, and clips beside the scene and use relative addresses. A style's own files are `rapid:style/`. 6. **Motion is a function of time.** Compute from `t`, in `rapid.frame`, GSAP timelines, or CSS and Web Animations made at load. Never from what the previous frame did. 7. **Elements that matter carry `data-el` and `data-role`** so the checks can see them. 8. **Cues** mark what the sound plays and where the reviewer looks. 9. **The key frame** is `meta.key`, in seconds: the hero, complete. In a video it is built and judged first, and the motion is built around it. 10. **The poster is the last frame.** End on a frame worth a thumbnail. ## The style in the page When a scene renders in a style, its `rapid:style` link becomes the style's tokens as custom properties on `:root`, adapted to the format, followed by the style's own `style.css`: | Custom property | Holds | |---|---| | `--rapid-color-` | each palette colour, by the name the style gives it (`field`, `ink`, `accent`, `paper`, `cool`, …) | | `--rapid-font-` | each face as a `font-family` list: the face, its substitutes, then a generic family | | `--rapid-weight-`, `--rapid-style-` | each face's weight and style | | `--rapid-size-` | each type size, scaled by the format's `type_k` | | `--rapid-leading-min`, `--rapid-leading-max` | the range of line heights | | `--rapid-margin-x`, `--rapid-margin-y` | the margins for the format | | `--rapid-grid-columns`, `--rapid-grid-gutter`, `--rapid-grid-col`, `--rapid-grid-baseline` | the style's grid for the format, when it has one; `--rapid-grid-col` is one column's width | | `--rapid-video-` | each step of the style's `video.steps` type scale, scaled by `type_k` | | `--rapid-ease-` | each easing as a CSS timing function | `rapid:style/` anywhere in the page is one of the style's files, inlined: `

`. Scripts read the same values as `window.rapidStyle`: `tokens`, `motion`, `format` (the format's name), and `adaptation` (what the style changes for that format). ## The runtime The runtime sets `window.rapid` before your scripts run: | | | |---|---| | `rapid.t` | the current time, in seconds | | `rapid.meta` | the meta block, parsed, with its defaults | | `rapid.frame(fn)` | `fn(t)` runs on every frame, in the order you registered them | | `rapid.at(t0, t1, t?)` | progress from 0 to 1 across `[t0, t1]`, clamped; `t` defaults to now | | `rapid.ease` | `linear`, `outCubic`, `inOutCubic`, `outExpo`, `outBack`, `outElastic`, each taking 0–1 | | `rapid.random()` | seeded from the scene's id; inside a frame callback, reseeded from the frame's time | | `rapid.cue(kind, { key, color, gain, params })` | records a cue at the current time | `Date`, `performance.now`, `requestAnimationFrame`, the timers, `Math.random`, and `crypto.getRandomValues` are all virtual too. Only the motion listed under [determinism](/docs/scenes#determinism) is safe in any seek order, and a render seeks out of order across chunks. ## Video clips A video clip in the project's `assets/` (`.mp4`, `.webm`, `.mov`) plays in a plain `