Terminal Overlays for Narrated Screencasts
Put the code and plan text on screen, timed to the voiceover.
Gantry can film narrated screencasts of its own runs: a voice track walks through what happened while the recorded terminal plays underneath. Until this job, that narration could talk about a snippet of code or a line of the plan, but there was no way to put the actual text on screen where a viewer could read it. This job added overlays.
A narrated script can now carry hidden directives that name a piece of code, a plan excerpt, or a literal caption, each attached to the paragraph of narration it belongs with. A compile step turns those directives into a timed sidecar file, and a player renders each one as a small floating terminal panel over the recording — appearing when the narration reaches it and clearing before the next arrives. An optional background dim-and-blur keeps the panel the focus of the frame.
Build
The work split along a data contract: a compile half that turns script directives into a timed JSON sidecar, and a runtime half that plays that sidecar as floating panels. The sidecar is why the compiler could be finished and tested before any player existed.
The two milestones are drawn at the sidecar file. The first compiles: parse the script's overlay directives against one shared grammar, resolve each code overlay's text from the committed run artifact at compile time, and emit a deterministic JSON timeline whose entries carry text rather than repository paths. The second consumes: a player that reads that timeline, waits against the replay clock, and shows one panel at a time. Because the compiler writes finished text into the file, the player never needs the script, the repository, or git history — which is what let the whole compiler, down to byte-for-byte output and the clamping that keeps panels from overlapping, be built and tested with no player in existence.
Inside each milestone the order follows the same dependency. On the compile side the shared directive grammar lands first, so validation and compilation cannot fork it, then materialization, then the timing math, then the command that wires them together. On the runtime side the base player comes first, then the silent-recorder integration, then the compositor polish, then the narrated map workflow that produces and consumes a sidecar per episode.
The run stayed green across both milestones and every sprint: no gate sent a piece back, and nothing was re-planned. The riskiest boundary — whether a compositor could blur the background under the recorder's headless display at all — had been retired before this build by a separate smoke-test spike, and the sprint brief points the builder straight at its findings. That is why the compositor sprint was scoped to use a proven invocation and degrade to crisp, un-composited panels on failure, rather than to discover whether the effect was possible in the first place.
Feature
Narrated Gantry screencasts can now display the code and plan text they describe as legible on-screen panels synced to the narration, rendered by a compile-then-play pipeline that still stands at HEAD with its compositor config since rewritten.
Before this work a narrated episode could describe a change in the voiceover but had nothing to show for it: the viewer heard about a function or a plan step and saw only the terminal. The answer is a pipeline in two stages. The `compile-overlays` command reads a narrated script and its sync profile and writes a JSON timeline; an overlay player launches each entry as a borderless ghostty terminal over the captured run, formatted through a syntax highlighter, showing a single panel at any moment; and a picom compositor dims and blurs the rest of the frame behind it. The narrated map render calls the compiler after building the sync profile and hands the resulting sidecar to the recorder.
At today's HEAD that pipeline is intact. The command is still wired into the verb table, the overlay and player engine modules are present and carry most of the lines the job introduced, the shared directive grammar still lives in the script module, and the recorder wrappers still accept an overlays sidecar.
Two things have moved since. The standalone integration test files the run added for the compiler and the overlay recorder are no longer present — the test tree was reorganized into a consolidated harness — though the engine modules keep their own inline tests. And the compositor configuration was rewritten outright. The spike's GLX backend with a dual-kawase blur, proven on real hardware, composited the entire display to black under the recorder's software OpenGL, so every overlay episode filmed that way came out as a black frame. The committed config now selects the xrender backend with a kernel blur, which renders correctly with no GPU present. The capability the job set out to build survives; the one part that leaned on hardware the recorder does not have is the part that had to change.