capture

Capture

The orchestrator routed you here. This atom owns the full recording lifecycle: launch a target, execute an interaction script, collect raw outputs.

You should already have a driver atom loaded (tuistory, true-input, agent-browser, or desktop-control) and optionally a target atom (droid-cli). This atom layers the recording discipline on top.

Inputs

The command that invoked you should have provided:

• Target: what to launch and on which branch(es)
• Interaction script: the sequence of actions to perform
• What to capture: recordings (.cast/.mp4), screenshots, text snapshots, byte sequences
• Keystroke logging: whether to emit a keystroke TSV for later overlay

Recording lifecycle

1. Pre-flight

Before recording anything:

• Terminal size is consistent across all sessions (--cols 120 --rows 36)
• Browser viewport size matches the composition layout (see "Browser viewport sizing" below) — mismatched aspects letterbox in the final video
• Branch/worktree paths and env vars are correct
• Recording format matches the driver: .cast for tuistory, .mp4 for true-input, screenshots for agent-browser, window PNGs / recording.mp4 for desktop-control
• If comparing branches, both sessions use identical terminal / viewport dimensions and launch parameters
• For droid-dev captures, --repo-root is mandatory — tctl will refuse to launch without it
• Color env vars are set (see below)

Browser viewport sizing

Panel aspect ratio in the final composition is layout-dependent. At the default 1920×1080 output with factory preset margins, the window-chrome panels that clips render into come out roughly:

Feeding a 16:9 landscape recording into a near-square side-by-side panel triggers objectFit: "contain" letterboxing — you get a thin strip of content with giant black bars above and below. Two ways to avoid it:

1. Match aspects at capture time (preferred) — pick the viewport from the table above based on the committed layout.
2. Opt into cropping at compose time — pass "objectFit": "cover" in showcase props. Crops the edges of the clip instead of letterboxing. Use when the relevant UI is centered and the clip's edges are expendable.

If you're unsure of the layout when capturing, default to 960×1000 — it is workable in both layouts (slight horizontal letterbox in single, no letterbox in side-by-side).

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl
# RUN_ID and RUN_DIR should already be set by the parent (see droid-control ground rule 5)

2. Launch and record

CRITICAL: tuistory's virtual PTY does not advertise color support by default. Node.js apps (Ink/chalk) detect this and suppress ALL color escape codes, producing a monochrome recording. You must pass FORCE_COLOR=3 and COLORTERM=truecolor to force full 24-bit color output. Without these, agg has nothing to theme and the video will look grey/desaturated regardless of the agg theme chosen.

Single branch:

$TCTL launch "droid-dev" -s ${RUN_ID}-demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/demo.cast

Comparison (before/after):

Browser: size the viewport to match the composition layout (see table above).

3. Execute the interaction script

Film for a viewer with no context. You are a director, not an operator.

• Record before setup -- the baseline state is act 1.
• Hold after state changes -- 2-3 seconds so text is readable. Use snapshot --trim as natural verification beats.
• Verify between steps -- wait or snapshot to confirm state before proceeding. Don't blindly fire the next key.
• Verification IS evidence. A snapshot that shows nothing changed after pressing ESC proves the session is frozen. A snapshot that shows an error message proves the command was blocked. Always snapshot after actions where the absence of a response is the point -- the viewer needs to see it too.

For comparison recordings, both branches run identical interactions -- only the behavior differs.

4. Keystroke logging

If the workflow requires keystroke overlay, emit a TSV file during recording. Since every interaction is scripted, the timing data is already known.

Write each keystroke's timestamp (seconds from recording start) and a human-readable label:

Use readable key names (Ctrl+C, not \x03). Save alongside the recording (e.g., /tmp/keys.tsv).

5. Close and verify raw outputs

Before handing off, confirm every expected output file exists and is non-empty:

• Recording files (.cast, .mp4, .webm)
• Screenshot files (.png)
• Keystroke TSV (if committed)
• Text snapshot logs (if needed for the report)

Evidence capture patterns

Outputs

Hand these to the compose stage:

Recovery

If a session gets stuck mid-recording:

For browser: agent-browser close.

Then re-launch and re-record. Partial recordings are not usable.