---
name: foreground-ledger
description: Build a short presenter composition with photographic cue cards arriving in a face-safe foreground row.
version: 1.0.0
---

# Foreground Ledger

Use this parameterized renderer to introduce two to four visual cues while a continuous human presenter remains visible. A short arrival for each whole card leads to an evenly spaced reading hold. Output is editable HTML/CSS, local photography, a GSAP timeline, and a HyperFrames project at 1920 × 1080, 30 fps, 7.6 seconds.

## Prepare the brief

Provide a JSON object with `heading` (up to 38 characters), `summary` (up to 78), `palette` (`linen`, `fjord`, `plum`, or `chalk`), `take` (local video), and `cues` (two to four objects, each with `label` up to 20 characters and `photo` as a local JPG, PNG or WebP). Paths resolve from the JSON file. There are no bundled demo photographs or presenter takes.

Choose a continuous take lasting at least 7.6 seconds, with the face above the card band. Cards occupy the lower 330 pixels, so low hand gestures can be occluded intentionally. Inspect actual frames; a sufficiently long video alone does not prove a safe crop. Use footage and photographs you have permission to use. Avoid endorsement claims or suggesting that stock speech matches the captions. This is a visual cue sequence, not synthesized narration or lip synchronization.

## Install and generate

Requires Node.js 22 or newer, npm, FFmpeg and ffprobe on PATH, and a browser supported by HyperFrames.

```sh
npm ci --ignore-scripts
node compose.mjs /absolute/brief.json /absolute/new-project
npx --no-install hyperframes inspect /absolute/new-project --json
npx --no-install hyperframes render /absolute/new-project --output /absolute/film.mp4 --fps 30 --quality high --strict --workers 1 --no-browser-gpu --experimental-fast-capture=false
```

Use a fresh project folder each time. Dependencies are pinned in package-lock.json. Fonts are copied from the installed upstream font packages and loaded locally. Manrope supports Latin text; Noto Sans SC supplies Chinese glyphs. The GSAP license is included; font notices accompany the generated assets. HyperFrames 0.8.30 has known moderate transitive dependency advisories; installation with scripts disabled does not resolve those advisories. Use local trusted projects and do not expose its preview server publicly.

## Review and edit

Read `build.json` for entries and timing. The paused timeline is registered under `window.__timelines['foreground-ledger']`; `seekLedger(seconds)` seeks graphics. The renderer controls media independently; interactive testing must seek the video to the same timestamp. Inspect start, each arrival, settled row and final native frame. Check forward and backward seek routes, text bounds, fonts, uninterrupted face motion, image crops, and ordinary-speed encoded playback. Capture actual playback frame counts; do not infer smoothness from successful encoding.

The renderer does not produce audio and mutes presenter media. Add separately authorized narration or music in an editor if needed, record that editable audio timeline and verify the actual mixed output. Do not label a silent composition as narrated.

Theme, wording and photographs are input-controlled. New timing or layout behavior requires editing the generator; this is not automatic free-form film direction. Validate a changed package from its new ZIP in a fresh directory. Keep rendered examples separate from the generic distribution.