Code Vocabulary

PR videos run on two kinds of moving picture: code (the lines that changed) and behavior (what the change does at runtime). This file is the vocabulary for both — the code-* blocks for code beats, and the mechanism beat (an invented animated diagram, or a flowchart / data-chart) for behavior beats. A video that is all code reads flat; alternate the two (story-design plans the rhythm; see “Showing behavior” below).

For code beats the registry ships purpose-built code animation blocks that render a diff, a typed-on snippet, a morph, a highlight, a scroll, or a 3D/particle/dissolve reveal — far better than hand-built motion. Reach for one of these first for any code beat; fall back to hand-authored composition only when none fits.

• Step 4 (visual design): for each diff / before_after / code beat, name the block in the frame's scene (e.g. “the request() retry block, ~6 lines, code-diff“). One judgment call: which block.
• Step 5 (frame worker): install the named block and fill it with the real diff/snippet (below). The block is the frame’s centerpiece, composited onto code-editorial’s navy Code Surface.

Install + use

Every block installs the same way (confirmed packages/cli/src/commands/add.ts):

It is a self-contained sub-composition (inlined engine; a paused GSAP timeline the engine seeks per frame). Mount it in the frame as a sub-composition clip:

Customize by editing two globals in the installed HTML’s inline <script>:

• window.__TOKENS — the code content, baked as Shiki tokens: { <seq>: { lang, theme, bg, fg, states: [ { code, tokens:[ {key, content, color, fontStyle} ] } ] } }. Replace code/tokens with the PR’s real snippet(s). fontStyle is a bitmask (&1 italic, &2 bold). The blocks bake theme: "github-dark" independently of the code-snippet-* themes below.
• window.__BLOCK — selects the effect + timing: 2D { id, effect, seq, line?, duration }; WebGL { id, effect, seq, duration, seed }.

The timeline registers synchronously at window.__timelines[id]. All blocks are 1920×1080 and deterministic / seek-safe (no CSS transitions, no rAF, seeded randomness — never Math.random / Date.now).

The animation blocks

Gotchas (call out so the worker doesn’t trip):

• Fit the cadence to the frame’s data-duration. Each block carries its own internal timing — code-typing types at a fixed per-character speed, so a snippet that’s long relative to a short frame overruns: the code never finishes typing within data-duration, and the chrome beats around it (an underline, a +N/−M count-up) never play. Check char-count × per-char cadence (plus the block’s settle) against data-duration, and tune the timing so the full block lands inside the frame. This is the one code-motion knob you MUST set to the frame — you’re fitting the timing, not redesigning the effect (the typewriter / diff / morph stays the block’s).
• code-diff and code-morph need ≥2 baked states; every other animation block uses a single state.
• Line indexing differs: code-highlight is 0-based (line: 1 = the 2nd line); code-scroll is 1-based. Don’t off-by-one.
• No caption-safe band. These are full-bleed 1920×1080 code surfaces with no reserved caption area. When captions are enabled, the frame must keep the code panel clear of the bottom caption keep-out band (composite the block in the top ~83%, or scale/inset it) — the worker owns that, not the block.

The code-snippet-* theme family (standalone, not palettes)

These are NOT palettes you attach to the animation blocks — each is its own ready-made ~11–12s composition rendering a full developer UI with baked typing and its own timeline. Use one when you want ambient realistic context (a real IDE or terminal on screen), not a focused diff. Install the specific one: npx hyperframes add code-snippet-<name>.

• VS Code workbench (12): full VS Code window (activity bar, file-tree, tabs, editor with per-char typing, integrated terminal running pytest, status bar) in each theme. dark-plus, light-plus, dark-modern, light-modern, dark-2026, light-2026, monokai, solarized-light, visual-studio-dark, visual-studio-light, high-contrast, high-contrast-light. (Each pulls a background.jpeg into assets/.)
• Apple Terminal (12): macOS Terminal.app window typing a shell command per profile. apple-terminal- + basic, clear-dark, clear-light, grass, homebrew, man-page, novel, ocean, pro, red-sands, silver-aerogel, solid-colors.

The theme is baked into each block (not chosen at runtime); to use a given look, install that block and edit its codeLines. For code-editorial’s editorial register, prefer the focused animation blocks on the navy Code Surface; reach for a code-snippet-* UI only when “show it in a real editor/terminal” is the point.

Showing behavior — the mechanism beat (not a code-* block)

A code-* block shows the code. It does not show what the code does. The single biggest cause of a flat PR video is a body that is all code surfaces — so for any change with a visible runtime behavior, plan a mechanism beat that animates the behavior (story-design owns the rhythm; this is the vocabulary).

A mechanism beat is not a registry code-* block. It is one of:

• an invented animated diagram — SVG / HTML / GSAP the frame worker builds from code-editorial’s atoms (hairline-ink nodes / edges / lanes on cream, one coral marker on the active element), the build playing out the behavior across the shot; or
• a flowchart / flowchart-vertical registry block — a process / pipeline / state flow; or
• a data-chart registry block — a perf / metric comparison (two bars or timelines racing).

flowchart, flowchart-vertical, and data-chart install exactly like a code block (npx hyperframes add <name>) and mount as a sub-composition — so when a mechanism frame names one in its scene, Step 5 pre-installs it alongside the code-* blocks. An invented SVG/GSAP diagram needs no install (the worker hand-builds it).

What to animate, by what the change touches (the menu story-design plans from):

Unlike a code-* block (which owns its own animation), the diagram’s motion is yours — sequence ≥3 effects into entrance (draw the nodes / lanes) → development (run the flow) → settle (the resolved state + one coral emphasis). Never let it enter then freeze.

PR beat → block cheat-sheet