# report-to-video

Turns a cited sweep report into a video: the clips run in chronological order and
let the source speak for itself, with thin chrome carrying the citation and a
timeline of where you are. A video rendering of the reports we already write.

Two scripts and a manifest:

| file | lifetime | what it is |
|---|---|---|
| `build-video.mjs` | stable | manifest → mp4. Fetches clips, snaps cuts to silence, letterboxes them into the chrome, crossfades. |
| `render-cards.mjs` | stable | draws the timeline footer and marker, plus optional card stills. Imported by `build-video.mjs`. |
| `resolve-windows.mjs` | stable | widens clip windows from cue spans to whole sentences. Run once after authoring a manifest. |
| `brand.mjs`, `brand-cards.mjs` | stable | the opt-in brand preset (`render.brand`); see [its section](#the-archilyzer-media-preset-renderbrand). |
| `<report>/video.manifest.json` | per report | the edit decision list. **This is the regeneration source of truth**, not the report. |

```
node umtool/report-to-video/resolve-windows.mjs ~/reports/<slug>/video.manifest.json --write
node umtool/report-to-video/build-video.mjs    ~/reports/<slug>/video.manifest.json
```

Output lands in `<report dir>/out/`: `cards/`, `clips-raw/`, `segments/`, and the
finished `<slug>.mp4`. First worked example: `~/reports/ferret-rescue/`.

## Why there is a manifest at all

**A sweep report does not contain enough information to cut a video from.** Its
citations carry a single start second and nothing else — `momentUrl()`
(`common/lib/momentUrl.ts:106`) takes one `seconds` and floors it, and the MCP
`Snippet` type (`mcp/src/search.ts:41`) has no `end` field. There is no clip
length anywhere in a report.

The end times do exist, they are just never rendered: every cue in
`transcripts/channels/<slug>/data/<id>/transcript.cues.json` is `{start, end, text}`.
So the manifest is built by matching each quote back to its covering cues and
recording the real window. That is also what handles ellipsis-joined citations —
a report quote like `"…" … "…"` is often two separate cue spans presented as one.

The manifest additionally pins the provenance (share link, corpus handle, match
counts, the narrowing queries) so a rebuild months later is reproducible and the
video's own claims about its coverage can be checked.

## Where a clip actually gets cut

Three stages, because a cue span is the wrong answer twice over.

1. **Cue span** — the raw window covering the quote, from `transcript.cues.json`.
2. **Sentence widening** (`resolve-windows.mjs`) — walk outward to the nearest cue
   ending in `.`, `?` or `!`. A cue boundary is where the *caption line wrapped*,
   so cutting there drops the run-up that makes a quote intelligible.

   Two asymmetries matter. The **start** takes a lead-in only if a real sentence
   opening sits within `--max-lead` (8 s); otherwise it takes none, because a
   half-sentence run-up is the irrelevant context you were trying to avoid, not
   context. The **end** is never clamped to a budget — stopping partway through a
   sentence is the exact mid-thought ending this removes — so `--max-tail` (12 s)
   only bounds how far it looks before giving up and using the cue end.

   **Some uploads have no punctuation at all.** Older ASR in this corpus emits
   unpunctuated cue text for whole videos, and sentence detection then has nothing
   to find: widening degrades to the raw cue span at both ends. That is not a
   silent failure you can ignore — it is what produced a clip opening mid-thought
   on "higher than they can afford and because", and what let another clip's tail
   run through its neighbour. For those videos, pick the window by reading the
   cues and set it by hand; the de-overlap and silence passes still apply.

   **`lockStart` / `lockEnd` pin an edge** to exactly what the manifest says, and
   neither widening nor de-overlap will move it. Reach for it when the utterance's
   real trailing pause does not line up with its last cue's end — the snap picks
   the *nearest* silence, and in speech over game audio the nearest one is often a
   gap between syllables rather than the pause at the end of the thought.
3. **Silence snapping** (`build-video.mjs`) — a sentence boundary in the
   *transcript* still isn't a boundary in the *audio*, so clips clip words in
   half. Fetch `fetchPad` seconds wider than needed, run `silencedetect` over the
   result, and move each cut to the nearest silence within `snapWindow`. Starts
   land on a silence's END (just before speech resumes), ends on a silence's START
   (just after speech stops). No silence close enough → keep the exact point; a
   tight cut beats a cut in the wrong place. The build logs `start✓ end✓` per clip
   so you can see which snapped.

   How much of the pause is kept: 0.10 s before speech resumes and 0.18 s after
   it stops by default. `render.snapLead` / `render.snapTail` (seconds) set them,
   and then never more than the pause holds — so with a crossfade, a tail as long
   as the `transition` fades out over the breath instead of the last word, and a
   long lead lets the next clip fade in before its first word. Pair them with a
   `silenceMinDur` that finds real pauses (~0.3 s), not the gaps between words.

   **The silence threshold is relative, and it has to be.** These are game
   streams: the gaps between words are full of game audio and music — quiet, but
   nowhere near silent. A fixed absolute threshold sits below the noise floor and
   finds nothing. On one measured clip: mean volume −21 dB, **0** silences at
   −32 dB, **25** at −26 dB. So each clip is measured with `volumedetect` first
   and the threshold set `silenceRelDb` (default 6) below its own mean. If a rebuild
   suddenly reports mostly `start– end–`, this is the knob.

The trim happens during the burn-in encode, so snapping costs nothing extra.

4. **De-overlap** (`resolve-windows.mjs`) — widening is per-clip and blind to its
   neighbours, so two clips cut from the *same* video can end up overlapping, and
   the overlap plays as the same footage twice. Any earlier clip whose tail runs
   into a later clip's start is trimmed back to that start. This is not a rare
   edge case: it fired on the first report, where a 2024 upload has **no
   punctuation at all** in the relevant stretch, so sentence detection found
   nothing and the tail ran the full budget straight through the next clip.

## Regenerating and changing a video

Everything is cached by content, so iteration is cheap:

- **Reorder, drop or add clips** — edit `timeline`, re-run. Cached clips are not
  refetched, so a re-cut costs an encode, not a download.
- **Change a clip's window** — edit `start`/`end`, re-run. A raw file's window is
  in its name, so the cache is content-addressed; and since a request is satisfied
  by any cached file that **contains** it, a nudge inside the existing pad costs
  nothing at all. Only a window that escapes every cached file downloads again.
- **Preview one entry** — `--only <id>` builds a single segment and stops.
- **Work offline** — `--skip-fetch` fails loudly instead of downloading, so you
  can confirm you are working entirely from cache. `--no-network` is the
  stronger form: every clip's source is found on disk **before** anything is
  rendered, and if even one clip would need a download the build refuses at
  once, listing each such clip as `timeline[<i>] <id>  <channel>/<video>
  <from>–<to>` (the padded span it needs). It governs clip **media** only: cue
  windows and metadata still come from wherever `--cue-source` says, so add
  `--cue-source local` to keep those off the network too.
- **Fetch one clip, wide** — `--fetch-only <id> --pad 20` puts a generous window
  in the cache without building anything. This is what the umtool clip bench runs,
  and containing-window reuse is what makes that fetch double as the build's cache.
- **Force a refetch** — delete `out/clips-raw/`, or pass `--no-reuse` to require an
  exact-window file (the corpus and saved-source tiers below are reuse too, and
  are skipped).
- **Iterate on the rail** — `--rail-only` re-runs only the rail chain over a cached
  `out/<slug>.prerail.mp4`; `--preview <start> <dur>` does the same over a window.
  `--no-rail` builds the cut without one. See
  [The claim rail](#the-claim-rail-renderrail).

Containing-window reuse was retrofitted, and the waste it removes is measurable:
`ferret-rescue/out/clips-raw` holds **31 files for 10 clips** because every window
edit before this downloaded the same material again — one source is there four
times over overlapping windows. The tightest containing file wins, not the widest,
because silence detection decodes the whole file and a 40 s file costs more than
the 24 s one that would also have done.

After changing any window, re-run `resolve-windows.mjs --write` before building.
It is a **fixed point**: running it on an already-resolved manifest reports
`0 window(s) changed` and rewrites nothing. That property is load-bearing and was
not free — the manifest stores times rounded to 2 dp, so a value read back can sit
a hair below the cue end it came from, which lands the end lookup on the previous
cue and runs the search on to the *next* sentence. Left alone, every re-run grew
the same clip. Hence `EPS` in the end lookup and the 0.05 s deadband on applying a
change.

### Where a clip's source comes from

Before a clip is fetched, `sources.mjs` looks for its source on disk, in this
order, and the first place holding the clip's **padded** span (its extent plus
`fetchPad`, to the same 0.02 s tolerance) wins:

1. **`raw-cache`** — this build's `out/clips-raw/<video>_<from>-<to>.mp4`: the
   exact-window file first, else the tightest containing one, as above.
2. **`corpus-window`** — the editor's window cache,
   `channels/<slug>/data/<id>/clips/<from>-<to>.mp4` (`.mkv`/`.webm` from older
   fetches; the `.json` sidecar and in-flight `.part.mp4` are ignored), tightest
   first. This is where umtool's bench and the MCP's `fetch_clip` put windows.
3. **`saved-video`** — the whole recording: the saved-video store's container
   through `data/<id>/saved-video.json`, else a `data/<id>/source-media.<ext>`
   not yet moved there. It counts as the window `[0, duration]`, the duration
   (and picture height) read by one `ffprobe` — run only when tiers 1 and 2
   missed.

4. **`audio`** — the recording's sound alone, `data/<id>/audio.<ext>` (`mp3`,
   then `m4a`, then `opus`, then any other: `aac`, `ogg`, `wav`, `flac`, an
   audio `webm` or `mp4`), the window `[0, duration]`. Only when allowed, by one
   rule (`sources.mjs` `audioUse`), which also names the use:
   - **`audio-only`, before the network**, when the clip has no picture to
     fetch: the entry says `audioOnly: true`, the manifest says
     `render.preferLocalAudio: true`, the record's `platform` is a feed
     (`podcast`, `feed`, `rss`), or the record has no page (`webpageUrl`) to
     fetch from;
   - **`audio-fallback`, only when asked**: a clip that SHOULD have a picture,
     in a build that may not fetch one (`--no-network` or `--skip-fetch`),
     with `--audio-fallback` given.

   Being last, it never beats a picture already on disk. Without the rule a cut
   would quietly lose its pictures to it: many transcribed videos keep an
   `audio.mp3`. **`--no-network` still proves every picture is on disk**: a clip
   that should have one and has only its sound is listed as needing a fetch,
   with a note that its sound is there (`--audio-fallback` would play it). An
   audio-only clip is satisfied — listed up front as playing from audio only,
   not as a miss — and with `--audio-fallback` the fallbacks are listed
   separately, and their `fetch` event's `source` is `"audio-fallback"`, not
   `"audio"`. `planLocalSources` returns the three as `{missing, audio,
   audioFallback}`; it reads a clip's record only when its sound is all that is
   on disk.

Only a miss in all of them fetches. The channels tree is the one the clip bench
reads for the project: `provenance.channelsDir`, else a `.shadow-channels/`
beside the manifest, else `CHANNELS_DIR` / the checkout's `transcripts/channels`.
A file reached through a link into `media/` (perhaps on another drive) is
followed; a dangling one — a drive not mounted — is "not here", and the next
candidate or tier answers. The build logs one line per clip naming the kind it
used (`--progress ndjson`: the `fetch` event's `source`, which is `"network"`
for a download, plus `local` and `window` for a hit).

A corpus window or a whole source is wider than the fetch would have been, so
silence detection measures just the padded span of it — the same seconds a
fetch would have produced — rather than decoding a fifteen-minute window or a
three-hour container. A raw-cache window is measured whole, as before, so no
cached cut moves. umtool's bench lists tiers 2 and 3 through the same module
(`clipWindowDirs`), with a container's span from its cue doc rather than an
ffprobe, so what the bench calls fetched is what the build cuts from. (Not the
audio tier: the bench would call every video that kept its sound fetched.)

**A source with no picture plays under a poster.** Whatever a clip is cut from
— the audio tier, a `src` that is an mp3 (below), a window with no video
stream — the build `ffprobe`s it, and when it holds no video (an mp3's cover
art does not count) the segment's picture is a poster: the clip's own card —
channel, title and date, resolved as the header resolves them — rendered by
`renderCard` at exactly the picture box's size, with the sound's waveform
moving along its foot in the accent colour (`render.audioPoster.waveform`,
default `true`; `false` keeps the still). It replaces `[0:v]` and nothing
else, so the letterbox, the header, the footer and the deck's framing all
apply, and the encode is the same: size, fps, pixel format, SAR and audio
layout match every other segment's, and the concat cannot tell it from one.

## Driven from umtool

The three CLIs are the source of truth and stay usable on their own; umtool drives
them rather than reimplementing them, so the UI and the terminal can never disagree
about a window, a format string or the Rumble retry. Three additions exist for that:

- **`--progress ndjson`** — one JSON object per line instead of prose:
  `start`, `card`, `clip`, `fetch`, `snap`, `segment`, `entry-failed`, `concat`,
  `chapters`, `note`, `done`, `error`. The event set is exactly what was already
  being printed; making it a format switch is what stops a wording change from
  breaking the driver.
- **`--continue-on-error`** — record a failed entry and carry on. A dead source at
  clip 14 of 19 otherwise throws away thirteen fetches already paid for. The run
  still **refuses to concatenate** and exits non-zero: a finished file that quietly
  lost a citation is worse than no file.
- **`buildVideo({manifestPath, opts, out, only, fetchOnly})`** is exported, and
  `widen()` from `resolve-windows.mjs` already was. umtool imports `widen()` so the
  bench's "extend to sentence end" is the CLI's own function, and **spawns** the
  build — a 40-minute chain of yt-dlp and ffmpeg inside a request handler has no
  cancellation story.

`check-availability.mjs` is the fourth CLI and belongs at the *front* of a build:

```
node umtool/report-to-video/check-availability.mjs <manifest.json>
```

It runs `yt-dlp --simulate` once per distinct `(channel, video)` — no bytes
downloaded — classifies each failure (`deleted`, `private`, `restricted`,
`members-only`, `geo-blocked`, `no-cues`, `maybe_missing`), and writes
`out/availability.json` with a timestamp. This is the one fact about a manifest
that goes stale in *both* directions: a source can die after the manifest is
written, and a source annotated "gone" can come back. `no-cues` is called out
separately because it is a different bug — usually the Rumble two-ids trap, where
the manifest names the MCP video id while the cue file lives under the URL slug.

## Manifest shape

`timeline` is an ordered list; entries are `card`, `clip` or `image` (plus
`scroll`, `chart`, `ledger` and `teaser` — the vocabulary is open).

A manifest and a report site's `report.json` convert into each other:
`archilyzer reports to-manifest <report.json> --out video.manifest.json` writes a
starter cut of a report (a title card, a chapter card per section, each claim's
still and clips carrying its `claim`, its posts), and `archilyzer reports convert
manifest video.manifest.json --out report.json` makes a report of a manifest — see
REPORT.md, "Making a report from what exists". An image's `quote` is what the
converters carry as the still's words; nothing in a build reads it. The sentence
widening `resolve-windows.mjs` does is `common/lib/cueWiden.mjs`, which the
converters share.

```jsonc
{ "type": "card", "id": "ch3", "style": "chapter", "seconds": 4.0,
  "kicker": "March – November 2025", "heading": "Then: the county",
  "sub": "Six months for the first approval" }

{ "type": "clip", "id": "c04", "video": "uyz1_FIqIEk",
  "start": 32989.56, "end": 32994.19,   // cue-accurate, from transcript.cues.json
  "cite": 32989,                        // the second shown in the attribution line
  "quote": "The pre-application screening was approved by the county, dude." }
```

Three per-clip fields exist for compilations that span sources or need a hand-cut
window:

- **`channel`** — the archived channel this clip's cue file lives under, overriding
  `provenance.channelSlug`. A compilation about one person routinely spans several
  mirror channels (`HasanAbiVODs` / `…VODs3` / `…VODsbackup`), and cue files are
  keyed by channel, so a single manifest-wide slug cannot find them all.
- **`lock`** — exempt this clip from `resolve-windows`. Sentence-widening exists to
  stop clips ending mid-thought, but that is exactly wrong when the author has
  deliberately cut a quote short: a single cue often holds a whole paragraph, so
  trimming to "I hate this country so much sometimes" and dropping the rest of the
  sentence is an editorial decision that widening would silently undo. `lock` also
  handles the reverse case — a clip whose lead-in would drag in seconds of some
  *other* audio (a news package playing before the speaker starts).
- **`muteFrom`** — SOURCE seconds, like `start`/`end`/`cutEnd`, within the clip's
  `start`–`end`: the clip's sound goes silent from that second to the end of the
  clip while the picture plays on. A 40 ms fade ends exactly at `muteFrom`, so
  nothing of a sound that starts there gets through and nothing clicks; from it on
  the sound is digital silence, and a hold on that clip stays silent. It is made
  where the cut is joined (see [The cut's edits](#the-cuts-edits-mutefrom-and-renderendfade)),
  so changing it rebuilds no segment: `--chrome-only` applies it under the deck.
  Only the played window is in the segment, so a mark past `cutEnd` (inside the
  extent, so it validates) mutes nothing; the build says it will not be heard.

### A clip with its own media: `src` and `cues`

A clip may name a FILE instead of a corpus recording — a podcast episode, a
recording no channel holds — with no stub channel built for it:

```jsonc
{ "type": "clip", "id": "p01",
  "src": "media/episode-12.mp3",     // relative to the MANIFEST; video or audio-only
  "cues": "media/episode-12.json",   // optional: its cues, relative to the manifest
  "start": 61.2, "end": 74.9,        // optional: default the whole file
  "title": "Episode 12", "channelTitle": "The Feed", "date": "2026-01-02",
  "citeUrl": "https://…" }           // optional: the ONLY thing that draws a QR
```

- **The window is the file**, `[0, its ffprobe duration]`; `start`/`end` cut
  inside it and default to its two ends. Nothing is looked up or fetched, and
  `--fetch-only` on one is a no-op. The cut still snaps to silence.
- **`cues`** is read in either shape — the corpus's `transcript.cues.json`
  (`cues: [{start, end, text}]`, with `title`, `channel`, `uploadDate`,
  `platform`) or the transcript `scripts/parakeet-stitch.mjs` writes
  (`chunk_data: [{start_time, end_time, text}]`, `duration_seconds`) — through
  one normaliser (`local-media.mjs` `normaliseCueDoc`), and feeds
  `resolve-windows.mjs`'s widening and `--cut-to-quote` as a record's cues do.
  Without `cues`, or without `start`/`end`, resolve-windows leaves the clip as
  it is. The header, the chapter and the deck read the cue file's `title`,
  `channel` and `uploadDate` (the file's name is the title when it has none);
  the entry's own `title`, `channelTitle` and `date` win as on any clip.
- **No QR is derived**: the file has no page on the archive. `citeUrl` draws
  one. (The legacy rail draws a code on every tile, so there a `src` clip
  without `citeUrl` gets a card's — the sweep's link.)
- **Paths may not climb out of the manifest's directory**, and an absolute one
  is refused unless the manifest sets `render.allowAbsoluteSrc: true` — media
  too big to keep beside the manifest is a decision written down. A `src` beside
  a `video`, a `cues` without a `src`, a file that is not there, a cue file in
  neither shape, or an `end` past the file's end refuses the build before
  anything runs, naming each entry (`timeline[<i>] <id>: …`).

`render.endFade` (seconds, default 0 = off, at most 10) fades the cut's LAST
segment — whatever it is — picture to `palette.bg` and sound to silence over its
final `endFade` seconds (all of it, when the segment is shorter), reaching both
on the last frame. It is for a cut that
ends on a clip; once a finale entry follows the last clip, the ordinary
crossfade into it does the job and `endFade` fades the finale instead.

### `render.chrome` — the on-screen deck's settings, and per-entry `onscreen`

Opt-in (`render.chrome.engine: "hyperframes"`, `layout: "deck"`) — see
[The on-screen deck](#renderchrome--the-on-screen-deck) below for what it draws
and how a build renders it. Every key is optional; `resolveDeck()` fills
whatever a manifest omits, one level deep:

```jsonc
"render": {
  "chrome": {
    "engine": "hyperframes", "layout": "deck",
    "deck": {
      "height": 190,                 // px, whole number, 120–400
      "footageScale": 0.82,          // 0.5–1; the footage must still fit above the deck
      "background": "panel",         // "panel" (lifted) | "flush"
      "pip": { "spacing": "even", "size": 6, "activeSize": 12 },  // spacing "even" | "time"; activeSize ≥ size
      "title": { "size": 54, "maxChars": 48 },     // size 24–96; maxChars 10–120 (the editor's counter, not a refusal)
      "subtitle": { "parts": "auto", "dateFormat": "long" },      // parts "auto" | a distinct list of channel/title/date/clock; dateFormat "long" | "iso"
      "qr": { "show": true, "size": 150,           // size 80–380, and at most height − 20
              "links": "site" },                   // | "original": a clip's QR opens its record's own page (below)
      "overCards": "hide",            // "hide" | "show"
      "motion": { "out": 0.3, "in": 0.45, "pip": 0.7 },  // seconds; out/in 0–2, pip 0–3
      "posts": { "show": true, "layout": "popup",                      // | "feed": a column beside the footage for the whole cut (below)
                 "seconds": 4, "hold": 2.5,                            // the manifest's `posts` (below); seconds 0.5–10; hold 0–10 (0: none; the feed never holds)
                 "shift": { "scale": 0.86, "seconds": 0.6 },          // the footage makes room: scale 0.5–1, seconds 0–3; or false
                 "position": "top-right",                              // | "top-left"
                 "width": 600, "qrSize": 120, "maxLines": 7, "inset": 24,  // width 320–900 px; qrSize 80–200 and ≤ width/2; maxLines 2–14; inset 0–80
                 "links": "archive" }                                  // | "original": where a post's QR goes (below)
    },
    "factcheck": {                                                     // the fact-check stamps and tally (below); every key optional
      "verdicts": { "PARTLY": { "label": "Partly true", "color": "#e3b23c" } },  // per verdict: label ≤ 24 characters, a #rgb/#rrggbb colour
      "stamp": { "seconds": 3, "position": "top-left" },               // seconds 1–10; top-left | top-right | bottom-left | bottom-right | center
      "tally": { "show": true, "position": "right" }                   // position "right" (beside the QR) | "left" (before the title)
    }
  }
}
```

`validateChrome()` (`deck.mjs`) is the ONE validator — umtool's writer refuses
with it and the build refuses with it before a single fetch, so a manifest
umtool accepted is one the build accepts. It refuses an **unknown** key rather
than ignoring it (`footageScle` silently meaning the default is the bug this
catches), and refuses `render.chrome` beside `render.rail` or the legacy
`render.chromeEngine` — the deck replaces both, it does not layer onto them.

Any `clip`, `image` or `card` entry may carry `onscreen`:

```jsonc
{ "type": "clip", "id": "c04", …,
  "onscreen": { "title": "County approves pre-application",
                "subtitle": "…optional override…" } }
```

Nested — `onscreen.title`, not `title` — because `entry.title` already means
the *stream's* title in the header and the chapters. One line each, ≤ 200
characters, trimmed; an empty value deletes the key, the way the attribution
fields do. Without it the deck's title is empty (a card falls back to
`heading`) and the subtitle is auto-built: a clip's channel · title · date (the
channel only when the cut spans more than one), an image's `title · date`, a
card's `sub`. A line too long for its column gives way in its middle parts
(the title ends in "…"): its first part and its last (the date) always show
whole. The QR follows a clip's corner-QR rule unchanged (`citeUrl`, else
the site link at the clip's start); an image draws one only with an explicit
`citeUrl`; a card never does.

`qr.links: "original"` points a clip's QR at its source instead of the archive:
the record's own `webpageUrl` — a YouTube page at the clip's start (`&t=<s>`,
or `?t=<s>` on a youtu.be link), a Rumble page as it is (it has no time
parameter a QR can carry), an X post's link as it is. A clip's `citeUrl` still
wins, and a clip whose record names no page keeps the site link.

### `posts` — written statements on the deck

A cut that wears the deck can carry a post — a Bluesky or X statement — as a
card over the footage, near the end of the clip it belongs with
(`plans/deck-posts.md` has the rulings). A post is not a segment: it has no
footage, so it rides on a clip.

```jsonc
"posts": [
  { "id": "bs-3msydljwjis2a", "platform": "bluesky",        // "bluesky" | "x" | "web" (a page's words)
    "author": "Pirate Software", "handle": "piratesoftware.live",
    "date": "2026-08-13T19:05:26.424Z",                    // ISO date or date-time
    "text": "We just signed off on 51 page document …",    // newlines kept; ≤ 3000 characters
    "url": "https://bsky.app/profile/piratesoftware.live/post/3msydljwjis2a",  // the post itself
    "attachTo": null,                                       // a clip id, to override the date rule
    "hide": false,
    "siteChannel": "piratesoftware-bsky",                   // optional: the archive channel that keeps it
    "siteUrl": null,                                        // optional: an http(s) page the QR links instead
    "postId": null,                                         // optional: its id, when `url` does not carry one
    "shot": "shots/post-1.png",                             // optional: a screenshot drawn instead of the text card
    "variant": "full",                                      // optional: in that cut only, as an entry's `variant`
    "accent": "#c98fd6",                                    // optional: the card's rail, rim and flag colour
    "logo": "brand/source.png",                             // optional: a logo in the card's top corner, above the QR
    "flag": "No source in the article" } ]                  // optional: a short label (≤ 60) above the words or picture
```

- **Which clip.** The one whose recording most closely PRECEDES the post: the
  latest day on or before the post's (a clip's day is its own `date`, else its
  record's upload date — the build reads the real one), ties to the later clip in
  the cut; a post older than every clip goes on the first. `attachTo` overrides;
  `hide: true` leaves a post out; `variant` keeps it to one cut. A variant that
  drops the named clip falls back to the date rule.
- **When.** A clip's posts, oldest first, stack: post j of k appears at
  A − seconds·(k − j), where A is the start of the outgoing transition (the next
  segment's start under a crossfade, 0.3 s before a hard cut, 0.3 s before the end
  of the cut). Each has `seconds` (4 by default) alone before the next stacks on,
  and the last has the clip's final `seconds`; a clip too short for that shares
  what it has after its incoming dissolve. They all leave together over the
  transition.

  `at: "start"` brings them up with the clip instead: in the manifest's order
  (not by date), sharing the whole clip after its incoming dissolve — post j of
  k at from + j·(A − from)/k. A card beside the words it goes with needs no
  hold; set `hold: 0`.
- **The hold.** A clip that carries posts is held on its last frame, in silence,
  for `hold` seconds (2.5) before its outgoing transition, so the last post can
  be read. The hold is part of the clip's length in the CUT: every start after
  it, the total, the chapters and the posts' own timing are measured with it
  (the schedule's `segments[i].hold`).
- **The move.** With `shift` on (the default), the footage eases over
  `shift.seconds` (0.6) from its box to `shift.scale` of it (0.86), its far edge
  `inset` from the frame's edge away from the column and centred above the deck,
  as the clip's first post appears; it stays there to the end of the clip, hold
  included, and the next clip comes in at the normal box through the transition
  (the schedule's `moves`). At 1920×1080: 1574×886 at (173, 2) → 1354×762 at
  (24, 64).
- **What.** The post's date (as the deck writes dates; a date-time is drawn as
  its day), `@handle · Bluesky` (or X), the words — paragraphs kept, clamped to
  `maxLines` with an ellipsis — and a QR of the post's page on the archive
  (below), or of its own `url`. A post with a `shot` draws the screenshot in
  place of the words, always as wide as the card's text (so it reads), in a
  viewport no taller than a full card of words, or than `shotMaxHeight` px when
  that is set; a taller screenshot holds on its top for 1.2 s once the card has
  landed, pans to its bottom, and holds there 1.2 s before the card leaves.
- **Marks.** A post's own `accent`, `logo` and `flag` set one kind of card apart
  from another at a glance — a source document's sentence beside a platform post,
  say: the rail and rim in the accent, the logo above the QR in the top corner,
  the flag as a label in the accent above the words or picture. Popup cards only;
  the feed draws its cards as before.
- **Where.** A column `inset` from the top of the footage box and from the
  FRAME's edge on the `position` side (inside the footage box when `shift` is
  `false`), `width` wide. Cards stack top-down; when the next would overflow the
  column, the oldest slide up and out.
- **How they read.** Each card slides in from past the frame's edge on the
  column's side and its accent rim flares as it lands, then settles to a quiet
  glow; an accent rail runs down its leading edge and the platform is a pill
  beside the handle. The QR is fully opaque once the card is in.
- **A screenshot.** `shot` — a `.png`, `.jpg`, `.jpeg` or `.webp`, relative to
  the manifest and inside its folder (no leading `/`, no `..`) — is drawn in
  place of the date, handle and words, as wide as they would be and no taller
  than a full card of them; the QR cell stays. The popup and the feed both
  draw it, the page waits for the picture before it measures the stack, and a
  shot that cannot be read refuses that region's compose. `text` is still
  required: it is the post's words wherever they are listed.

#### Where a post's QR links

By default (`posts.links: "archive"`) a post's QR opens the post's page on the
archive the manifest names (`provenance.siteOrigin`) —
`<origin>/?v=<channel>%2F<id>&vm=post`, the site's post view, which shows the
post and links on to the original — so the QR keeps working if the post or the
platform goes away. `deck.mjs` `postQrUrl` makes the link: the post's
`siteUrl` when it has one; else the archive page, when there is a `siteOrigin`,
an archive channel and the post's id; else the post's own `url`, as before.
`"original"` always links the post's own `url`.

- **The archive channel.** A post channel is a channel of its own on the
  archive (`piratesoftware-bsky`, not the video channel `piratesoftware`), and
  a manifest rarely says which. The build finds it (`post-links.mjs`), just
  before it writes the schedule: `/corpus.json`'s channels with a posts
  manifest, each manifest's `slugToPage` asked for the post's id — a Bluesky
  rkey (`/post/<rkey>`) or an X status id (`/status/<id>`), or `postId` —
  channels whose slug or name carries the post's handle first. Through the cue
  walk's cache (memory and disk, `REPORT_CACHE_DIR`); a post missing from a
  cached copy is looked for once more in a fresh one. Hidden posts, and a cut
  without the deck, are not looked up.
- **In memory only.** The found channel is set on the run's copy of the post
  and written to `schedule.json` as the post's `qrUrl` (beside its own `url`),
  so a `--chrome-only` re-render draws the link the build found; the manifest
  is never rewritten. A post that pins `siteChannel` (or `siteUrl`) is not looked
  up — pin one to make a cut that never asks the network.
- **Never a failure.** Each post gets a note: `<id>: archive link via <slug>`,
  `<id>: not in the archive at <origin> -- QR links the original`, or the
  archive did not answer and the QR links the original. Each request may take
  15 s, and a URL that failed is not asked again in that build — whichever
  pass or post asks next — so an archive that does not answer costs at most one
  timeout per URL it has (its `corpus.json` and each posts manifest), not one
  per post.
- **umtool's preview** links its posts through the same resolver and the same
  disk cache, so the On-screen preview draws the build's QRs. A request waits
  at most 10 s for all its posts together (8 s a request); a post not found by
  then links the original for that request, while its lookup finishes in the
  background for the next. A URL that failed is not asked again for ten
  minutes, and a miss is re-read fresh at most that often; a post a draft
  un-hides is linked too. The deck form's `qr links` field is `posts.links`.
- **The chrome cache** follows: a QR is an asset of the page, so a post whose
  link changes is a new key and a re-render.

`validatePosts()` (`deck.mjs`) is the one validator, unknown keys refused; a
deck build refuses a bad `posts` before a single fetch. Posts are drawn only
under the deck: without `render.chrome` they are data for the report, and
nothing in a build reads them.

### `claim` and `render.chrome.factcheck` — fact-check stamps and the tally

A cut that wears the deck can be a fact-check: any `clip`, `image` or card
entry may say which claim it is evidence for, and the claim's verdict.

```jsonc
{ "type": "clip", "id": "c07", …,
  "claim": { "id": "k3", "verdict": "CONTRADICTED" } }   // CORROBORATED | PARTLY | CONTRADICTED | NOT_FOUND | UNTESTABLE
```

`claim` is its own key: an entry's `verdict` is the clip review's
(`confirmed` / `incorrect`) and is untouched. The id is letters, digits and
`_ . : -` (≤ 64); a claim id carries ONE verdict across the timeline, a teaser
carries none, and `validateClaims()` (`factcheck.mjs`) refuses either before a
build fetches — umtool's writer refuses with the same function.

- **The stamp.** Each claim is stamped once, on the LAST segment that carries
  it (its evidence may run over several clips): the verdict's label, in its
  colour, slams in over the footage `stamp.seconds` (3) before that segment's
  outgoing transition — or as its incoming dissolve ends, on a shorter one —
  flashes as it lands, and leaves with the transition, as a popup post does.
  It sits in a 560×200 box (at 1920 wide, scaled with the frame) `28` px in
  from the footage box's `stamp.position` corner (`top-left` by default, the
  corner the popup posts do not use), the feed's footage box in a feed cut.
- **The tally.** A cell per verdict the cut stamps, in the deck beside the QR's
  cell (`tally.position: "left"`: before the title), each a count over its
  label. A count steps up — the old number rolls out, the new one in, the cell
  flashes — at the moment its stamp lands; a cell is dim until its first. It
  is part of the deck's panel, so it slides away over a card with it, and the
  title's column gives it its room only in a cut that stamps something.
- **The schedule.** A stamped segment carries `claim`, and `schedule.json`
  gains `factcheck: { stamps: [{ claim, verdict, segment, at, landed, out }] }`
  (`stampSchedule`) — only when a claim is stamped, so a cut without one
  writes the schedule it always did.
- **The render.** `chrome-stamp.mjs` is the stamps' page (pure, like the
  deck's), `compose-chrome.mjs --region stamp` composes and renders it for the
  whole cut (`chrome/stamp/`, `chrome/stamp-frames/`, cached by its key, a
  window `stamp-from<s>`), and the build lays it last, over the posts, exactly
  as it lays the deck's. `verify-build.mjs` checks its frame count.

`render.chrome.factcheck` sets the verdicts' labels and colours (one at a time:
a verdict named without a colour keeps the default's), the stamp's seconds and
corner, and whether and where the tally is drawn; `validateChrome()` refuses an
unknown key there as everywhere in the block.

### `thread` and `render.chrome.threads` — the thread rail

A cut whose clips make a few lines of argument can draw them as a rail of cards
down the frame's left side. Each clip names its thread; the list names the
threads in the rail's order, each with an optional outcome.

```jsonc
"render": { "chrome": { …, "threads": { "list": [
  { "id": "bet", "label": "The bet: her career",                 // ≤ 32 characters, one line
    "outcome": { "verdict": "CONTRADICTED", "label": "Walked back" } },  // label optional (≤ 24): else the verdict's
  { "id": "aside", "label": "An aside" } ] } } }                 // no outcome: never stamped
{ "type": "clip", "id": "c07", …, "thread": "bet" }
```

- **The layout.** With the rail on, the footage box moves to the frame's right
  edge (24 px in) and the rail takes the left, as tall as the footage: a card
  per thread (1–8), each its number, a dot per clip and its label.
- **The motion.** The card of the thread on screen is lit and a string draws
  from it to the picture; a clip's dot fills as the clip comes in; when the
  thread's last clip ends (1.8 s before it hands over), its outcome is stamped
  on its card in the verdict's colour. Before its thread plays a card is dim,
  after it rests quieter, so by the last clip the rail is the whole argument.
  The rail steps aside while a popup post has moved the footage over it.
- **Checks.** `validateThreads()` (via `validateChrome()`) refuses a bad list
  and the feed layout beside it; `validateThreadEntries()` refuses an entry
  naming an unlisted thread, a teaser in a thread and a listed thread with no
  clip. `schedule.json` gains `threads: { threads, runs, asides }` only when
  the rail is on. `chrome-threads.mjs` is the page; `compose-chrome.mjs
  --region threads` renders it; the build lays it last, like the stamps.

### `render.chrome.flips` — THEN and NOW, back to back

A cut built of pairs: a line from THEN and the opposite line from NOW. A panel
down the frame's left (the rail's region: a cut has the rail or the panel)
holds one pair while it plays.

```jsonc
"render": { "transition": 0.12, "chrome": { …, "deck": { "footageScale": 0.78 }, "flips": { "pairs": [
  { "id": "vax", "topic": "Vaccines",                            // ≤ 32 characters
    "then": { "entry": "c01", "when": "2019", "words": "…" },    // when ≤ 18, words ≤ 110: verbatim
    "now":  { "entry": "c02", "when": "2025", "words": "…" } } ] } } }
```

- **The motion.** The pair rises in with its THEN clip: its place (`03 / 11`),
  the topic, the THEN card (tag, when, words) lit. As the NOW clip starts its
  card slams in under it with a flash, the THEN card dims, and when both
  `when`s carry a year the years between roll up on an odometer
  ("+7 years later"). The pair lifts away as its NOW clip ends.
- **Checks.** `validateFlips()` (via `validateChrome()`) refuses a bad pair
  and the rail beside it; `validateFlipEntries()` refuses a side naming no
  timeline entry, a teaser, a THEN after its NOW and an entry in two pairs.
  `schedule.json` gains `flips: { pairs, asides }`. `chrome-flips.mjs` is the
  page; `compose-chrome.mjs --region flips` renders it.
- **Punch.** The panel is built for short clips — the line and nothing else —
  and near-hard cuts (`transition` 0.12); a smaller `footageScale` gives it room.

### The `image` entry type

A still: the receipts a clip cannot say out loud — a post, a thread, a DM, a
poster — shown for `seconds` and then gone.

```jsonc
{ "type": "image", "id": "i01a",
  "src": "nathan-pictures/IMG_7095.jpeg",  // relative to the MANIFEST's directory
  "seconds": 6,                            // default 4
  "redact": [[630, 925, 180, 145]],        // optional: filled solid, before the crop
  "crop": [0, 0, 1260, 1020],              // optional [x, y, w, h] in SOURCE pixels
  "scroll": { "holdStart": 2, "holdEnd": 3 },  // optional: crawl a tall capture
  // …or, INSTEAD of `src`, two to four captures side by side:
  "panels": [{ "src": "a.png" }, { "src": "b.jpg", "redact": [[630, 925, 180, 145]] }],
  "gap": 48,                               // px between panels; default 40
  "title": "Bx (@bx_on_x) on X, Sept 2026 — 1/4",
  "date": "2026-08-19",                    // optional; appended like a clip's
  "citeUrl": "https://…",                  // optional; the ONLY thing that draws a QR
  "quote": "…",                            // optional: the words the still shows (not drawn)
  "note": "…" }
```

It is **framed like a clip and encoded like a card**: the picture area is the
frame less the header, less the footer, less the rail column, so dropping a still
between two clips does not move the letterbox; the stream is a still plus silent
stereo at the same fps and encode args, so concat and xfade cannot tell the three
kinds apart. The header is the same tick and the same drawtext, reading
`${title} · ${date}` — **no clock**, because there is no moment inside a
screenshot to cite. Each still is one chapter, like every other entry.

- **No QR is ever derived.** A clip's code comes from the archive that serves it;
  a screenshot has no such archive, and a code resolving to the wrong place is
  worse than none. An explicit `citeUrl` draws one, in a clip's position.
- **`crop` and `redact` are in the ORIGINAL file's pixels**, and redaction runs
  first, so both sets of numbers come straight off the file the author measured.
- **Redaction fills; it does not blur.** A screenshot can carry a live QR code, a
  phone number or an address that must not ship in the video — and a QR survives
  mild blur, so a pixelated code still scans. `destinys-child`'s `i00b` is a
  recruitment poster with two working codes: `zbarimg` reads both off the source
  file and nothing off the rendered frame.
- **Out of bounds is an error, not a clamp.** ffmpeg would quietly shrink either
  box to fit, and a redaction that silently became a smaller redaction is the
  failure the field exists to prevent.
- **`scroll` crawls a capture too tall to fit** — a whole tweet thread. The
  picture is scaled to the picture area's **width** (which makes phone-capture
  text large), capped at the area's width and at 2× (a smaller picture is centred
  at 2× rather than blown up into artefacts), and then the frame walks from the
  top edge to the bottom: hold `holdStart`, travel over
  `seconds - holdStart - holdEnd`, hold `holdEnd`. `true` takes the defaults
  (1.5 / 2.0). A capture that fits after all is simply held still, and
  `seconds <= holdStart + holdEnd` is refused — that is not a slow crawl, it is
  two holds with a jump cut between them.
  **It has to be `crop`'s `y`**: crop's `w`/`h` are config-time but its `x`/`y`
  are per-frame in `t`, which is the same asymmetry the fill-bar note below is
  about — `drawbox` has no time variable at all. Measured on `destinys-child`'s
  `t01` (1096×3214 → 1920×5630, 34 s, holds 2/3): frames at 0.5 s and 2.0 s are
  the same picture (RMSE 0.13 %), 2→8→16.5→29 s each move a third of the frame,
  and 31 s and 33.9 s are the same again (0.49 %) — holds at both ends, linear
  travel between.
- **`panels` puts two to four captures side by side**, instead of `src` (both is
  an error, and so is `panels` with `scroll` — they are different answers to "it
  does not fit"). Each panel carries its own `redact` and `crop`, applied in its
  own source pixels, and is then scaled to the picture area's **height**:
  matching heights is what makes two differently-sized phone captures read as one
  exhibit. A row too wide for the frame shrinks by **one factor for every panel**
  — a per-panel fit would keep the row fitting and quietly restate the relative
  sizes of the exhibits — and the gaps keep their width while the pictures give
  way, because the space between two exhibits means "these are two things".
  Measured on `destinys-child`'s `p05`: a 327×675 expulsion post and an 853×1280
  poster become `496x1024 + 682x1024 with 48px gaps = 1226px of 1920`, centred,
  with the poster's two recruitment codes filled black (`zbarimg` reads nothing
  off the frame).
- **`--fetch-only` on a still is a no-op that says so**, not an error: a bench
  walking the timeline should not have to know which kinds have a window.

The footer's rows are reserved but left empty under a still. The marker's
position is a function of `section`, which a still does not have, and a timeline
strip whose marker vanishes for six seconds reads as a bug.

Clips also carry `section` and (auto-set) `sectionEnter`. Card styles — `title`,
`timeline`, `status`, `bullets`, `sources` — still work, but the ferret-rescue cut
uses none of them. `render` holds resolution, fps, fonts, palette and the knobs
(`fetchPad`, `snapWindow`, `silenceRelDb`, `transition`, `xfadeBatch`, `slideSeconds`,
`headerHeight`, `footerHeight`, and the optional `rail`); `provenance` holds the
sweep's scope and counts. Two further entry `type`s, `scroll` and `chart`, close a
cut off a top-level `ledger[]` — see [The claim rail](#the-claim-rail-renderrail).

**None of the header, footer, marker or corner QR described above is drawn
under `render.chrome`'s deck layout.** The deck replaces all of it with one
persistent panel — see [The on-screen deck](#renderchrome--the-on-screen-deck).

### Article stills: `shoot-page.mjs`

An article a report cites is a receipt like a post, and `shoot-page.mjs` makes
its still: it opens a page **saved to disk**, finds the quoted sentence in its
text, paints it like a highlighter and screenshots the paragraph that holds it,
at `deviceScaleFactor` 2. The PNG is then an `image` entry's `src`.

```sh
# one
node umtool/report-to-video/shoot-page.mjs \
  --page saved/article.html --quote "the sentence as the report quotes it" --out stills/a01.png
# many: <dir>/<id>.png per item, and <dir>/results.json
node umtool/report-to-video/shoot-page.mjs --batch stills.json --out stills/
```

```jsonc
// stills.json — `page` is relative to this file
[{ "id": "a01", "page": "saved/article.html", "quote": "…",
   "context": "…",     // optional: a longer stretch around the quote, to pick one occurrence
   "crop": "mark" }]   // optional: this item's --crop
```

- **The page is loaded offline.** Every request is refused except a `file://`
  under the page's own directory — the `<name>_files/` folder that "save page,
  complete" writes — so a shot never touches the network and never reads a file
  the page was not saved with. Each result lists what was `blocked`; a page that
  saved its fonts by URL renders in fallback fonts, and that list says why.
- **Page scripts are off** (`--js` turns them on). A saved page is already
  rendered; its scripts, with nothing to talk to, are likelier to hide the
  article behind an overlay than to finish drawing it.
- **The quote is matched as text, loosely only where copying is loose:** curly and
  straight quotes and apostrophes are one character, NBSP and every other space
  are a space, a run of whitespace is one, an ellipsis is three dots, and soft
  hyphens and zero-width characters are not there at all. Case and every other
  character are exact. A match runs across element boundaries — a link, an
  `<em>`, a `<br>` — and the end of one block and the start of the next read as a
  space, never as nothing. Hidden (`display: none`) text is not searched.
- **A quote found more than once** shoots the first and says so on stderr, with
  `occurrences` in its result. Give `context` to pick another.
- **The shot is the nearest block that holds the whole match**, plus `--padding`
  (24 CSS px), with everything outside that block hidden for the shot so the
  padding shows the page's ground and not the bottom of the paragraph above
  (`--no-isolate` leaves it). A block taller than `--max-height` (1200) is trimmed
  to that height around the quote, and says `trimmed`. The highlight
  (`--color`, `#ffe14d`) never reflows the text: one `<mark>` per text node it
  covers, padded vertically only.
- **`--crop mark` shoots the quote's lines, not the block** (`--crop block` is
  the default; an item's `crop` overrides either). On a forum-style page the
  whole post is ONE block of `<br>`-separated paragraphs, so the block crop is a
  slab of embeds around a two-line quote. The mark crop is the quote's own lines
  plus `--context-lines` (1) whole lines above and below, stepped in the
  computed `line-height` of the text the quote sits in from the lines the
  highlight is on, so a context line is never cut mid-glyph; it spans the
  block's content box, never leaves it, and adds `--padding`. That padding would
  show the next line's glyphs cut, so above and below the lines it is painted
  in the block's own background. `--max-height` does not apply.
- **A miss is never skipped.** It is in `results.json` with its `reason`
  (`quote not found`, `context not found`, `quote not found inside its context`,
  `page not found`, or the load error), it is summarised on stderr, and the run
  exits 1 after shooting every other item.

Each result carries `crop` (the CSS-pixel rectangle, in document coordinates),
`cropMode` (`block` or `mark`), `pixels` (the PNG's size), `matched` (the page's own text of the match, curly
quotes and all), `block` (a CSS selector for the block shot) and `blocked`. The
matcher is pure and is what `shoot-page.test.mjs` tests; the one test that
launches Chromium runs only with `SHOOT_PAGE_BROWSER=1`.

### The `teaser` entry type

A season teaser's "coming soon" card: a full-frame graphic, its words the
manifest's, popping in one line at a time over a dark cinematic ground, with a
trailer hit under each pop. Put it after the last clip; the ordinary crossfade
joins them, and `render.endFade` — which fades the cut's last segment — now
falls on the teaser.

```jsonc
{ "type": "teaser", "id": "fin", "seconds": 7,
  "lines": ["Pirate Software",
            { "text": "The Largest Ferret Rescue in the United States",
              "break": "in the United States" },
            "February 2027"],
  "tail": "?",          // optional: hangs off the LAST line, fades in on its own
  "tailWait": 2,        // optional: seconds from the last hit to the tail (default: the beat's)
  "beat": 0.7,          // optional, default 0.7: seconds from one pop to the next
  "hits": true,         // optional, default true: false makes the card silent
  "dip": { "fade": 1.2, "black": 0.6 } }  // optional: go to black before it (below)
```

- **`lines`** — 1 to 8 in at most 5 rows (below), each one line of at most 80 characters: a string, or
  `{ text, break, replace?, role?, hold?, together?, lead? }`, where `break` is the END of `text` drawn as a smaller,
  wide-tracked second tier under the rest that pops 3/7 of a beat after it
  (0.3 s at the default `beat`).
  The words are data: they are drawn uppercase, and kept as written everywhere
  else. **Roles follow position:** with three or more lines the first is a
  small wide-tracked overline between two accent rules, the last a mid-size
  kicker (a date), and everything between a big heavy title; two lines are an
  overline and a title; one is a title.
- **Rows that say several things in turn: `replace`.** A line written
  `{ "text": …, "replace": true }` takes the ROW of the line before it: it
  slams in where that one was, and the one it replaces rises 64 px, shrinks
  to 0.9×, blurs and fades over 0.3 s from its pop (`TEASER_MOTION.out*`),
  gone before the new line's impact. So one row can step through a sequence
  — his estimates, each pushing out the last — and a last line with
  `replace` can resolve it (`"2027"` pushing out the last estimate). The
  frame holds at most **5 rows** (`TEASER_LIMITS.rows`) of at most **8 lines**;
  roles follow the ROW's position as they followed the line's, and a
  replacing line takes the role of the line it replaces. The lines of a row
  are stacked in one grid cell (`.slot`), so the row is as tall as its
  tallest line and the layout never moves as they change. The first line
  cannot replace.
- **A line's own size: `role`.** `"overline"`, `"title"` or `"kicker"` on a
  line overrides the role its row's position gives it — its type, its fit
  and its hit. A row of estimates at `"kicker"` keeps the title above them
  the biggest words on the card; `"2027"` at `"title"` makes the answer
  outweigh them. A kicker-sized row above a title gets 44 px of air.
- **`hold`** — 0 to 4 seconds on a line: held after its pop (after its
  second tier's) before the next line pops, so a line about to be pushed out
  — or the last before the kicker — can be read. On the last line it holds
  the tail back as well.
- **`together`** — `true` on a line with a `break`: its second tier pops
  WITH it, on the line's one hit, instead of 3/7 of a beat later on a
  lighter hit of its own. For a row that steps through quote-and-date pairs,
  so each step is one hit, not two.
- **`lead`** — a few words drawn ABOVE a line as a small wide-tracked tier,
  the way a `break` is drawn below it: a label for the line ("Breaking
  Ground" over "2027"). It drops in with its line's pop, on that line's hit,
  and fits as a second tier does (at most 66 characters).
- A teaser that uses none of these composes the page it always did,
  byte for byte (`chrome-teaser.test.mjs` pins it), so no existing cut
  re-renders.
- **What fits the frame** (`TEASER_LIMITS.fit`): a row wider than 80 % of the
  frame shrinks to its role's floor and no further, so each row is also held to
  what fits at that floor — a **title** at most **34** characters, a
  **kicker** 56, an **overline** 64, a `break`'s second tier 66; the tail and
  the space before it count TWICE on the row that carries it, because that row
  is centred by its own words and the tail hangs off its right (so a tail can
  never be pushed past the frame's edge by a wide line). An 80-character title
  spilled past both edges of the frame. A longer title fits by setting its end
  as a `break`. The counts were measured in the face on ordinary words in
  capitals (a title holds 36–37 there); a row of only wide capitals (M, W) can
  still spill.
- **`beat`** — 0.4 to 2.5 seconds, default 0.7 (`TEASER_MOTION.gap`): the
  time from one line's pop to the next, and so from one hit to the next. The
  pops land 0.55 s in (after the incoming dissolve) and a beat apart, counted
  from the line before or from its second tier. Two waits scale with the beat
  in the default's proportion, so a slower beat is the same rhythm slowed: a
  second tier pops 3/7 of a beat after its line (0.3 s at 0.7) and the tail
  starts 8/7 of a beat after the last pop (0.8 s). What is not the beat stays
  put: the first landing, each slam (0.2 s to its hit, 0.5 s to settle), the
  tail's 1.7 s fade and the swell under it, and the last 1.2 s, a still hold
  for the end fade. A teaser without `beat`, or with 0.7, is the page it
  always was — the same render key and the same frames.
- **`seconds`** — optional, 3 to 20. **Nothing is squeezed to fit**: a
  `seconds` shorter than the beats need (the last pop, the tail's fade and the
  1.2 s hold) is refused with the length they need. Left out, the card is
  exactly that long, rounded up to a tenth of a second and at least 3 s; a
  card that would need more than 20 s is refused (a shorter beat, or fewer
  lines). The ferret card needs 5.95 s at 0.7, 6.7 at 0.9, 7.2 at 1.05 and
  8.1 at 1.3 — its `"seconds": 7` (a little over a second more still at the
  end) holds beats up to about 0.99.
- **`tail`** — at most 8 characters, in the accent, set a little apart from
  the last line (0.32 em). **The last line is centred by its own words**: the
  tail hangs off its right in a zero-width box on its baseline, so "2027"
  sits on the frame's centre and the "?" beside it, not the two centred
  as one unit. (Before, the year sat left of centre by half the tail.)
- **`tailWait`** — optional, 0.3 to 6 seconds, and only with a tail: the time
  from the last hit — the last line's impact, or its second tier's pop when it
  has a `break` — to the tail's entrance. Left out, it is what the beat gives
  (8/7 of a beat from the last pop, less the 0.2 s slam when the last line has
  no `break`: 0.6 s at 0.7, 1.0 s at 1.05), so a teaser without it keeps its
  timing. The swell under the tail and
  the card's length follow it; the tail's 1.7 s fade and the 1.2 s end room do
  not change. Without a dip, a teaser at beat 1.05 with `tailWait: 2` hits its
  last line at 3.3 s, starts the tail at 5.3 s and needs 8.2 s (7.2 without
  it); the ferret finale also has a dip, so in its own clock the year hits at
  4.0 s, the tail starts at 6.0 s and the card needs 7.8 s — its `seconds:
  9.8` holds the finished line 2 s more before the end fade.
- **The chapter** is the lines joined with " — ", the tail after the last
  (an authored `chapter` still wins). The deck slides away over a teaser
  whatever `overCards` says — it is full frame, never framed into the footage
  box — and it has no pip and no QR.

**How it is drawn.** `chrome-teaser.mjs` builds the page (pure; the cue list
is `teaserCues`, every cue a `fromTo` with its from stated, as the deck's are),
compose-chrome renders it as region `teaser` (`chrome/teaser-<id>/`, frames in
`chrome/teaser-<id>-frames/`, cached by the page's content key — changed words
are a new render), and the build encodes the frames into `segments/<id>.mp4`
at the parameters every segment shares. The display face is the vendored
Archivo (`fonts/Archivo[wdth,wght].ttf`, weight 600–900 and width 112–125 %),
copied in as the private family `TeaserDisplay`. The ground is `palette.bg`
lifted toward the accent at the centre and falling toward black at the edges,
a vignette, seeded film grain, a soft light leak drifting across, letterbox
bars that close in over the dissolve, and a slow push-in over the whole card.
Each line slams in from 1.42× (the overline from 1.25×), blurred, undershoots
to 0.968× as it lands — a flash of the accent behind it and a streak of light
through it — and settles to rest. Rendered on the ferret cut: 210 frames in
about 90 s.

**The sound.** Synthesised in ffmpeg, no samples (`teaserAudioGraph`): under
each pop a trailer hit — a sub sine dropping from ~92 to ~40 Hz with its octave
for body on an exponential decay, a band-passed noise burst for the punch, a
low noise tail and a short low-passed echo. The title's hit is the biggest,
the overline's and the date's a little smaller, the second tier's lighter and
shorter; under the tail a low swell rises and settles as it fades in. The times
are `teaserTimes` (`deck.mjs`), the SAME the composition's cues are built from,
and each hit starts on the sample of its pop. The sum is limited at −6 dBFS
(`alimiter`, no auto-level, latency compensated) and levelled against the ferret
cut: the cut measures −17.7 LUFS integrated, the teaser's segment −19.7. `hits: false` is
digital silence, as a card's is.

**When it is rebuilt.** The segment is re-encoded only when its key — the
frames' render key, the whole sound graph and the encode's parameters (`crf`,
`preset`, `audioBitrate`, `audioRate`, `audioChannels`) — differs from the one
recorded beside it (`<id>.teaser.json`). Any build that reaches a teaser
rebuilds it when its words, motion, sound or encoding changed: a full build, `--only <id>`, and
**`--chrome-only`**, which builds teaser segments (they are chrome — graphics
made from the manifest, nothing fetched) while still rebuilding no clip.
`verify-build` checks each teaser's frame count and that its segment was
encoded from the frames on disk.

#### `dip` — to black before the teaser, and up out of it

```jsonc
"dip": { "fade": 1.2, "black": 0.6 }   // fade 0.3–4 s, black 0–3 s; both required
```

The cut goes to black before the teaser and the teaser comes up out of it, like
a trailer. Only a teaser takes a `dip` (anywhere else it is refused, and so is a
dip on the first entry, which has nothing before it to fade).

1. **The fade — the whole frame.** Over the previous segment's last `fade`
   seconds, ending on its last frame (where the dissolve into the teaser ends),
   everything on screen eases to black: the footage, the deck, the feed column,
   popup posts, a rail. Its sound fades to silence over the same frames. The
   picture is ffmpeg's `fade` out to black laid on the FINISHED picture, after
   every overlay (`dipWindows`, `dipVideoFilter` in `build-video.mjs`), and
   only inside the dip's window: every other frame passes untouched. A fade to
   BLACK stays in the stream's yuv420p (luma 16, chroma 128) — only a coloured
   fade goes through RGB, which is why the end fade is a `geq` — and it is
   about 25× faster than the same blend in `geq` at 1080p (a preview window
   that starts inside the fade uses the `geq` form). The sound is the end
   fade's `afade` on that segment's join. Both are made where the cut is joined, so `--chrome-only` changes a
   dip without re-encoding a clip.
   The crossfade into the teaser does not dissolve: over the overlap the
   outgoing segment plays untouched (`xfade=transition=custom:expr='A'`, and
   `acrossfade` with `nofade` on both sides) and the teaser takes over at its
   end, under the black. A dissolve there blended the footage with the
   teaser's black lead and darkened it faster than the deck and the feed,
   which only the dip fades — the panels were left lit over a darker picture.
2. **The black.** The blend stays fully black from that last frame for
   `black` seconds more — whole frames at the cut's fps: a `black` that falls
   between frames is taken to the nearest one (0.45 at 30 fps is 14 frames,
   0.4667 s; `dipOf`), and one that is already whole frames (0.6 at 30 fps) is
   used as given, so the joined cut's black, the teaser's frame count and the
   page's rise all end on the same frame. Under it, the teaser's own first `transition + black`
   seconds — its **lead** (`teaserLead`) — are black and silent but for the
   riser, so the teaser takes over in black and nothing is held: the teaser
   segment is simply longer by the lead (`teaserSeconds(entry, D)`), and the
   schedule, the chapters and the pips count it as they count any segment's
   length (the crossfade's overlap included, as everywhere). The deck and the feed are gone in an instant on the
   faded segment's last frame (`dipHideAt`), under the black, instead of
   sliding away over the dissolve.
3. **The rise.** The card opens with the letterbox already closed and dark; a
   black veil over the ground and the light leak (under the words) starts
   lifting as the black ends, slowly, to 45 % by the first line's impact
   0.35 s later, then blooms away over 0.3 s (`DIP_RISE`), so the first hit is
   the moment the light comes on. The first line's slam starts 0.15 s after
   the black, not 0.55 s (there is no dissolve to land after), and every later
   time follows it. Under the black, a **riser** (`DIP_RISER`, synthesised like
   the hits): a sub climbing 30 → 55 Hz and a band-passed noise swell, rising
   for up to a second into the first hit and released 40 ms after it, about
   6 dB under the hit.

With a dip, `seconds` is the CARD's — from where the light comes up — and the
segment is the lead plus it; left out, the card is what its beats need from
there (0.4 s less than without a dip). The ferret finale at `beat: 1.05`: the
card 6.8 s, the segment 7.7 s at `{0.9, 0.4}`, 7.9 s at `{1.2, 0.6}`, 8.3 s at
`{1.6, 1}`. With `{1.2, 0.6}` after c20 (the cut's 0.5 s dissolve): c20 fades
over its last 1.2 s to black on its last frame, black holds 0.6 s more, the
veil starts lifting 1.1 s into the teaser and its first impact is 1.45 s in.

The lead counts the cut's transition AS BUILT: a `--no-xfade` build composes a
teaser whose lead is the black alone (`buildTeaserSegment` and compose-chrome
take the build's transition; compose-chrome's CLI uses the manifest's). The
teaser's record beside its segment (`<id>.teaser.json`) names that transition,
and `verify-build.mjs` counts the teaser's frames at it (an older record
without it: the schedule's, else 0 under `--no-xfade`, which umtool's driver
passes on whenever the build had it, else the manifest's). A
teaser without `dip` composes the page, the sound and the segment key it
always did, and a cut without one writes every graph it did.

**umtool** shows a teaser as a card row named by its lines (the report page,
the On-screen table, the timeline strip). Editing its lines there is not
built: it needs a writer (`updateTeaser(dir, id, {lines, tail, seconds, beat, hits},
{token})` through `withManifestLock` and `validateTeaser`), a route, a small
form (one field per line with a break picker), and a preview — a still of the
composition at a chosen second through compose-chrome's `--still`, which the
deck's true-still route already does for its region.

## Chrome, not cards

**The ferret-rescue cut has no cards at all** — no title, no chapter breaks, no
closing slate. It is a cited timeline and nothing else: the clips run in
chronological order and the source material carries the argument. Cards remain
supported for reports that want them, but the default posture is that anything
drawn is an interruption which has to earn its place.

Nothing is drawn *over* the picture either. The video is **letterboxed between**
thin chrome rather than overlaid by it:

- **Header (`headerHeight`, 56 px).** The citation only — channel · cleaned
  title · upload date · timestamp (`OmniBased · Chillin' · 2022-08-31 @
  1:58:08`). No quote: the clip is already saying it, and burning in a
  transcription of speech you can hear is noise. A clip's own `title` and `date`
  (`YYYY-MM-DD`) replace the record's cleaned title and upload date — for a
  VOD-mirror channel that is how the header shows the *stream's* date.
  **The channel heads the line** because a compilation routinely spans a
  streamer's own channel and two VOD mirrors, and nothing else on screen says
  which one is playing; it resolves `channelTitle` (per-clip override) → the cue
  record's `channel` → `provenance.channel` for the sweep's own channel → the
  raw slug, which is ugly on purpose.
- **Footer (`footerHeight`, 100 px).** The timeline: one node per milestone, each
  with a label and a month/year stamp beneath it. Drawn once by
  `renderFooterAssets()`.
- **The marker slides.** On the first clip of each section (`sectionEnter`, set
  automatically), the fill bar and the amber marker animate from the previous node
  to the current one over `slideSeconds`. Everywhere else they hold position. The
  motion is ffmpeg expressions on `crop`/`overlay`, so it costs nothing beyond the
  encode that was happening anyway.

  > **This used to be half true.** Until 2026-08-19 only the marker moved. The
  > fill bar was a `drawbox` whose width was `if(lt(t,0.9),…)` — but **`drawbox`
  > has no time variable**: its `t` is the box *thickness*, and with `t=fill`
  > that is effectively `INT_MAX`, so the comparison was always false and the
  > width expression collapsed to its end value. (`drawbox=w='t*10':h=8:t=2` and
  > `drawbox=w=20:h=8:t=2` produce an identical YAVG.)
  >
  > It was worse than "always full", because **`drawbox` reads `w=0` as *the
  > input width***. Section 0's fill is 0 px, so every clip in the first section
  > drew the bar across the **whole frame** — the progress track read 100 %
  > complete on the opening clip of every cut that has a footer. Measured on
  > `quartering-flagging-takedowns/n02`: 1708 accent px on the track row before,
  > 0 after (the correct value), with the amber marker parked on node 0.
  >
  > It is now a `_bar.png` strip of `2·trackLen × 3` — accent on the left half,
  > transparent on the right — translated under a fixed-width `crop`, which
  > *does* evaluate `x` per frame. Verified on `ferret-rescue/c07`: 608 → 698 →
  > 798 → 912 px across t = 0.0 … 0.9 s, then parked.

Clips carry `section` (index into `timelineNodes`); nodes supply `label` and
`date`. Ordering clips chronologically is the author's job — the manifest plays in
the order it is written.

A consequence worth knowing: 16:9 source into the reduced height leaves narrow
pillarbox bars. That is the price of never covering the picture, and it is why the
chrome is kept as thin as it is.

**Both bands are optional, and turning them off is a real setting, not a hack.**
`footerHeight: 0` (or an empty `timelineNodes`) drops the timeline; `headerHeight: 0`
drops the citation line. With both at zero the clips fill the whole frame and
nothing is drawn at all — the filtergraph loses the overlays rather than compositing
invisible ones, and `renderFooterAssets` returns early instead of drawing PNGs
nobody uses. Two reasons this comes up:

- A timeline footer only means something if the clips *are* a progression through
  time. A cut ordered by argument rather than by date should not draw one.
- The header prints the **upload date of the archived copy**, which for a VOD-mirror
  channel is often years after the stream (a Nov 2019 stream re-uploaded in Apr 2023
  reads `… November 6, 2019 … · 2023-04-06`). The title usually carries the true
  date, so nothing is false, but on a cut spanning many re-uploads it reads badly.

The `hasan-hate-america` cut runs with both off. Restoring them is a two-value edit.

Note: commas inside an ffmpeg filter expression have to survive filtergraph
parsing — wrapping the expression in single quotes is what protects them.

- **Segments crossfade** (`transition`, default 0.5 s). This forces a full
  re-encode of the timeline via `xfade`/`acrossfade` — the concat demuxer can only
  stream-copy hard cuts. Pass `--no-xfade` for a fast hard-cut build while
  iterating; the last pass can add the transitions back.
- **A long cut is crossfaded in batches.** One ffmpeg that opens every segment at
  once grows with the segment count: a 223-segment 1080p cut reached 8 GB and was
  killed, where 46 segments were fine. Past 24 segments (`render.xfadeBatch`, or
  `REPORT_VIDEO_XFADE_BATCH` in the environment, which wins: memory is the
  machine's; `0` never batches) the build crossfades each run of consecutive
  segments, at most that many, into `out/<variant>/xfade-batches/batch-<key>.mov`
  (the cut's own video encode, PCM sound), then crossfades the batch files
  together with the same transition, laying the deck, the rail and the dips over
  them in that last pass. A batch starts where its first segment does in one
  pass, so every dissolve, the schedule, the chapters and the dips land on the
  same frames; the cost is one more video encode generation on a batched cut. A
  batch's key is its whole ffmpeg command and each input's size and modified
  time (and its segments' holds and moves are in the command), so `--chrome-only`,
  `--rail-only` and a rebuild that changed a few segments redo only the batches
  those changes touch, then the last pass, and files of a stale key are
  removed when the next batched build starts. Past 24² segments the batches grow
  instead, so the last pass stays 24 inputs wide.

## Two cuts from one manifest (`--variant`)

A sweep finds more claims than a cut can show footage for. There are two
defensible answers to that and they make different videos, so the manifest
describes both and one filter picks between them.

| variant | output | ledger | what the viewer sees |
|---|---|---|---|
| `sourced` (default) | `out/<slug>.mp4` | claims with a clip | every row on screen has footage behind it |
| `full` | `out/<slug>-full.mp4` | every claim | the unclipped ones are stacked onto `ledger` cards |

`selectVariant(manifest, variant)` runs **immediately after the manifest is read**
and is the whole mechanism. Three rules, in this order:

1. a timeline entry tagged `"variant": "full"` survives only in that variant;
2. a claim survives only if the entry its `entryId` names survived — which is what
   makes `sourced` a sourced-only ledger, because in `full` every claim is pinned,
   to a clip or to a `ledger` card;
3. `card.variants[<name>]` field overrides are merged in and the key dropped.

Nothing downstream learns about variants. `ledgerTotals`, the rail, the chart
band, `scheduleClaims`, the chapters and the closing cards already take the
ledger and the timeline as inputs.

**Rule 3 exists because copy can be false in one cut.** A title card saying "48
dated claims" is a lie in a cut that shows nineteen, and the closing sources card
says two claims stayed ambiguous — both of which happen to be unclipped, so in
`sourced` there are none.

### Output layout

```
out/
  clips-raw/          SHARED — the only expensive thing in a build
  availability.json   SHARED — a fact about the manifest, not about a cut
  <slug>.mp4          sourced
  <slug>-full.mp4     full
  sourced/{cards,segments,qr,chrome,xfade-batches,schedule.json}
  full/{cards,segments,qr,chrome,xfade-batches,schedule.json}
```

`xfade-batches/` exists only for a cut long enough to be crossfaded in batches
(see "Segments crossfade" above).

`clips-raw` is shared deliberately: `sourced`'s clips are a subset of `full`'s, so
no clip is ever fetched twice. `sourced` writes `out/<slug>.mp4` because that is
the path umtool's build probe already looks for.

`compose-chrome.mjs` and `verify-build.mjs` both take `--variant` for the same
reason: the band plots the ledger the cut carries, and verifying the whole
manifest against one variant's file would report a missing chapter for every
entry the other cut has.

### The `ledger` entry type

`full`'s answer to the claims no clip covers. One card per **run of consecutive
unclipped claims**, so 29 claims cost 13 cards and about 66 seconds.

```jsonc
{ "type": "ledger", "id": "L10", "variant": "full", "seconds": 4.8,
  "kicker": "November 2024",
  "heading": "Ten and eight, named separately, in one breath",
  "sub": "…",                          // optional
  "claims": ["c12", "m14"] }           // ledger ids, in ledger order
```

Each row draws `date · scope pill · why it is not footage · the quote · his
figure`, plus a right-hand **arithmetic column**: `media / coffee / publica` as
they stand, the implied total, the layer this claim just moved lit, and its delta.
The arithmetic is **read from `ledgerTotals`, never recomputed** — one walk, or
the card and the band disagree about the same sum.

Rows **reveal in sequence** behind an opaque `pal.bg` rectangle walking down the
card: the rail curtain's device, exact because the card ground is flat.
`seconds` is derived (`2.2 + 1.3·rows`) rather than authored, because the rail
pins to the same clock — see below.

**"Why it is not footage" comes from a probe, not from a hand-written kicker.**
`check-availability.mjs` now probes every **ledger** source as well as every clip
source, so a row says `source deleted`, `source unreachable` or `not clipped`
because `yt-dlp --simulate` said so on a recorded date. Several unclipped claims
are cut from videos this cut clips elsewhere, i.e. demonstrably live; saying "the
upload is gone" about one of those is the kind of error that discredits the whole
compilation.

**Pins gain a within-segment offset.** A claim on a `ledger` card is pinned to its
own row's reveal (`ledgerRevealAt(r)`), not to the segment's mid-dissolve.
Otherwise four rail rows land on one frame, and the pin-order guard's strict
monotonicity breaks for no reason. In `full` this pins the rail almost exactly:
every claim has a segment, so `scheduleClaims` interpolates almost nothing.

**`status` is retired.** It existed to quote a claim whose source had gone; a
`ledger` card does the same thing better, alongside the arithmetic the claim moves
and with the reason coming from the probe.

## The claim rail (`render.rail`)

A cut whose whole point is *which company a number was about* has a problem: the
dates and the figures are **spoken**, and shown only in the header's citation
line. A viewer can hear "nearly ten" three times without ever seeing that the
three refer to three different payrolls.

`render.rail` adds a persistent **vertical ledger down the right edge**. It
appends one row per claim as the video runs, keeps a live per-company tally
beside it, and lists **every claim the sweep found** — not just the ones with a
clip behind them. Claims with no clip are dimmed (muted ink, hollow dot) and pass
with no audio; they are what stops the rail from implying the cut is the corpus.

It is **entirely opt-in**. With no `render.rail` key the filtergraph is the one
that was there before, and output is byte-for-byte unchanged.

```jsonc
"render": {
  "rail": {
    "width": 420,           // picture shrinks to width - 420
    "rowHeight": 46,        // one claim row; window height is a whole multiple
    "tallyRowHeight": 44,
    "tallyTop": 96,         // y of the tally block inside the rail column
    "pad": 22,
    "slide": 0.55,          // seconds per row-change ease
    "rule": "#2A322F",
    "tracks": [             // one per company; ORDER is the rail/legend order
      { "key": "media", "label": "The Quartering · media", "color": "#22AB83" }
    ]
  }
}
```

and a top-level `ledger[]`, in **playback order** — each track's claims contiguous
and date-sorted within the track:

```jsonc
{ "id": "m02", "date": "2022-09-17", "company": "media",
  "value": 4,                 // null for a qualitative claim; the tally ignores those
  "display": "4",             // the badge
  "label": "counts them out: one, two, three, four",
  "quote": "…", "src": "…",
  "hedged": false,            // a hedge word, not a figure -> hollow dot on the chart
  "plotted": true,            // appears in the step chart
  "entryId": "a01" }          // pins the row to that timeline entry's segment
```

Pinned entries carry a `claim` back-reference so the link reads both ways.

### How it is put together

Everything that moves is **one tall strip walked by a fixed-size `crop`**, not a
per-state still, because swapping stills can only cut and a crop can ease. Five
strips, all bounded `-loop 1 -framerate <fps> -t <total+2>`:

| strip | size | what it is |
|---|---|---|
| `_rail_chrome.png` | `RW × RHGT` | opaque panel, title, rules, **and the tally swatches and labels**. Runs the whole video — no `enable=` gates |
| `_rail_log.png` | `RW × N·rowHeight` | every claim, stacked, no padding |
| `_rail_curtain.png` | `RW × LOGH` | opaque `pal.bg` |
| `_rail_hl.png` | `RW × rowHeight` | the amber current-row marker |
| `_rail_tally.png` | `ΣlaneW × rows·cellH` | one COLUMN per lane — four rolling cells and the roster line |
| `_rail_qr.png` | `TILEW × segments·TILEH` | one provenance tile per segment |

### The tally rolls one number at a time

It used to be a column of four-row slabs walked by one `crop`: when the coffee
company's number changed, all four rows moved, and "The Quartering" slid up the
screen for a reason that had nothing to do with it. Text that has not changed
must not move.

So the **swatch and the company label went into the static chrome**, and each
track got its own **rolling cell** — number, delta triangle, `as of <date>` and a
population chip, right-aligned in a ~170 px column. All the lanes live side by
side in **one** PNG, so it is still one input: five `crop`s at different `x`, five
overlays.

**The direction of a roll is decided by the strip's LAYOUT, not by the ramp.**

| | rows | the crop | what you see |
|---|---|---|---|
| rise | `[old, new]` | walks **down** | content moves **up** |
| fall | `[new, old]` | walks **up** | content moves **down** |

Between transitions a one-frame `gte()` step repositions to the next pair's
starting row. That step is invisible **because both endpoint rows hold identical
content** — which is why every pair repeats the value it starts from instead of
sharing a row with its neighbour, and why the delta chip rides on both rows and
therefore stays on screen until the next change.

```
y_j(t) = r_j0 + Σ_k [ (a_k − b_{k−1})·gte(t,t_k) + (b_k − a_k)·ease(t_k) ]
```

Every term is cumulative and saturating — the rail's hard rule.

A repeated identical figure still rolls, upward: he said it again on a new date,
and the `as of` line underneath is what changed.

### The roster line

A fifth lane under the tally, `2 editors · 1 designer`, in `pal.muted`. It moves
**only when the rendered line changes**, which in this corpus means it stands
still through October and December 2023 while the total above it goes from three
to four. That is the finding, drawn rather than asserted.

It comes from an optional `roles` field on a ledger claim, and `rosterAt()` /
`rosterLine()` in `ledger-totals.mjs` are the one implementation, because a
chapter card states the same thing in words.

```jsonc
"roles": [{ "role": "video editor", "count": 2, "verbatim": "two video editors" }]
```

`verbatim` is his words; `role` and `count` are our reading. `roles` is **not** one
of the six adjudication fields — most claims are a number and nothing else, and
gating the inbox on a field a handful of entries can carry would leave it
permanently red.

### The QR moved into the rail's foot

It used to float over the bottom-right of the **picture**, which is the one part
of the frame this cut promises never to draw on. It is now a bordered tile parked
at the foot of the rail column — `pal.accent` rule, `SCAN → JERALYZER` above the
code, what it opens below it — and one more strip: one tile per segment,
crop-walked with **instantaneous `gte()` steps** at segment mid-dissolves. A code
that eased into place would spend the ease unscannable.

The tile overlays **after the curtain**, which is what stops the parked curtain
painting over it.

> **A card cannot carry the report's share link.** That link carries all 23
> channel filters and is ~1.4 k characters: a version-40 symbol, 177 modules in a
> 132 px tile, about 0.7 px per module. Cards get `provenance.qrLink` — the same
> query without the channel list, ~200 chars, 63 modules, verified scannable at
> this size — and fall back to `provenance.siteOrigin`. Manifests with **no**
> rail keep the old per-clip overlay in `buildClipSegment`, byte for byte.

> **`railGeometry` used to derive its height from `render.footerHeight`.** With
> the chart band on, the band reserves 200 px and `footerHeight` says 100, so the
> rail column ran a hundred pixels — about two rows of its log window — past the
> line every other renderer letterboxes to. It reads `reservedFooterHeight(render)`
> now, the same fix the closing cards needed for the same reason.

**The curtain is why one strip is enough.** With the window parked at the top
while the list is still filling, rows `i+1 … K-1` would show claims the video has
not made yet. The curtain is an opaque rectangle riding just below the last
revealed row; once the list is full it parks exactly one window-height down,
which is the bottom of the rail column — permanently outside the window. It is
`pal.bg` precisely so that parking there is invisible against the footer band.
Curtain and log **must share the same eased `P`**, or the curtain lags the rows
mid-slide and unrevealed claims flash into view.

**Ramps are cumulative and saturating, never gated.** A piecewise sum of
`gte(t,sᵢ)·lt(t,sᵢ₊₁)·…` terms flashes to `y=0` for one frame at any boundary
gap, because every gate evaluates false at once and the sum collapses. Terms that
rise to their delta and stay cannot do that.

**Scheduling.** Playback is ONE chronology across every company, and the ledger is
sorted the same way, so a claim's position in the rail *is* its position in time.
A claim with a clip behind it is pinned to that clip's segment; a claim on a
`ledger` card is pinned to its own row's reveal; the rest are spread evenly
between their neighbouring pins. A pin that runs backwards is refused — the
ledger and the timeline disagreeing about the order of events is a manifest bug,
and the whole cut rests on the two agreeing.

Segment-level pins land at **`starts[i] + D/2`** — mid-dissolve, where the picture
is already crossfading and a ±3-frame error is invisible.

The chain attaches **after the last `xfade` node**, inside the concat pass. `t`
there is absolute and continuous from 0, and nothing downstream of the last xfade
is dissolved — so it already has post-pass semantics without a second encode,
which would re-quantize crf-20 output at exactly the content that hurts most
(antialiased text on flat colour).

### `--rail-only` and `--preview`

`--rail-only` re-runs just the rail over a cached `out/<slug>.prerail.mp4`,
building that file from the existing segments the first time. Seconds instead of
the full concat. The hard-cut base is a separate file
(`<slug>.prerail-hardcut.mp4`), because the two timelines are different lengths
and a cached base from the wrong mode is a stale-cache trap the length assertion
would otherwise have to explain.

**It is mandatory for `--no-xfade`**, not an optimisation: `concatHardCut` is
`-c copy` and a stream-copy mux cannot host a filtergraph at all. That path
concats to `.prerail.mp4`, asserts its length against `segmentOffsets().total`,
and then applies the rail.

`--preview <start> <dur>` renders a window. `-ss` restarts `t` near zero, which
would put every absolute-time ramp in the wrong place — so the preview path
inserts `setpts=PTS+<start>/TB` before the rail chain and rebases afterwards.
Getting that wrong makes a working rail look broken.

## The end sequence: `scroll` and `chart`

Two timeline entry `type`s that exist to close a cut, both driven off the same
`ledger[]`:

- **`scroll`** — the whole ledger as one tall PNG, walked by an animated `crop`.
  **One chronological line, a column per company**: it used to group by company,
  which re-told the cut's own order backwards and hid the only thing worth seeing
  there — that the four payrolls were being described in the same weeks. Company
  is read from COLUMN POSITION, so colour is the secondary encoding.
  `hold` (default 2 s) buys a still moment at both ends;
  `clip()` in the expression provides it for free, and crop's own clamping
  degrades an off-by-a-few content height into a static last frame, not an error.
- **`chart`** — the four-series step chart over the `plotted` claims, authored as
  SVG and rasterized with `rsvg-convert` (deterministic about output size in a
  way ImageMagick's RSVG delegate is not). Fonts inside the SVG resolve through
  **fontconfig, not `render.fontRegular`** — use the family name the Pango cards
  use.

The chart's wipe **cannot** be `crop=w='<ramp>'`: crop's `w` is config-time and
`t` is undefined there. It is a curtain instead — an opaque `pal.bg` rectangle
slid rightwards off the plot, which is exact because the card ground is flat.

**Colour is not the only encoding on that chart, and that is a requirement.** No
four-colour categorical palette clears the data-viz all-pairs CVD gate (three
slots is the documented ceiling), so every series also carries a distinct dash
pattern and a direct end-of-line label with a leader elbow. The four hues are the
published artifact's, re-validated against this video's darker ground (`#0F1312`)
on the *adjacent* pairlist — the pairlist for line charts — where all five checks
pass (worst adjacent CVD ΔE 10.2 against a ≥8 target; normal-vision ΔE 17.4
against a ≥15 floor).

**`hideRail: true`** on a closing card slides the whole rail column off to the
right over that card's dissolve — one offset expression shared by every rail
overlay, so the column moves as one object — and lets the card render at the full
`width` instead of `contentWidth`. Not an `enable=` pop: a column that vanishes
between two frames reads as a dropped frame. The slide is cumulative and
saturating like every other ramp, so the rail does not come back; every card
after the first `hideRail` one should carry the flag too, or it lays out inside a
content width whose rail is no longer there.

Both kinds go through the same `fps=,setsar=1` and the same `encodeArgs` as every
other segment. They have to: `xfade` rejects a mismatched link with *"First input
link parameters do not match"*, and that surfaces at concat time, after every
fetch has been paid for.

## The ledger is adjudicated, and both totals depend on it

`ledger[].company` used to be an **undocumented interpretation**, and four
different hazards were riding on it:

| hazard | example | why it mattered |
|---|---|---|
| **scope ambiguity** | *"I have 10 employees, my coffee company employees… my editors"* | all-companies or coffee-only, depending on where the comma falls |
| **derived, not stated** | *"10 at coffee brand coffee, I've got eight staff for the live stream"* recorded as **18** | he never says 18 |
| **population drift** | 5 *"full-time salaried"*, 10 *"employees"*, 10 *"all basically contractors"* | different denominators, one series |
| **synthetic values** | 10.5 for *"about 10 people, 11 people"* | a midpoint we invented and attributed to him |

So every ledger entry now carries six adjudicated fields — `scope`,
`scopeBasis`, `scopeConfidence`, `population`, `valueKind`, `flags` — settled
against **±90 s of surrounding context, never the quote alone**. A first-person
quote is routinely the host reading someone else's words or being sarcastic, and
neither is visible inside the quote. One claim in this corpus is a guest's
payroll rather than his, and it reads identically until you listen either side.

`scopeConfidence: "unresolved"` is a legitimate outcome and **feeds neither
total**.

**The rule that follows:** the *stated* series may contain only **a figure he
utters as a single number for a named scope**. Sums and midpoints are ours, and
live in the *implied* series, which says so on screen.

`ledger-totals.mjs` is the one implementation of that arithmetic — the umtool
inbox, the chart band and the closing card all import it, so none of them can
disagree. It **refuses to run on an unadjudicated ledger**, because both totals
lie if you act on one. **Six** named predicates compute incoherence rather than
asserting it (`contradicts_component`, `same_day_conflict`, `self_negating`,
`population_mismatch`, `not_his_number`, `status_flip`). Deliberately **not** a
predicate: a large rise or fall between claims. Fluctuation is the subject, not a
defect.

`status_flip` is the sixth: the same people described as staff and then as
contractors, or the reverse. Three details in it are load-bearing.

- **`employees` and `people` are in NEITHER camp.** They are what he says when he
  is not making a claim about status at all, and reading them as one side or the
  other manufactures a reversal out of a change of vocabulary.
- **An `all` claim is comparable with any company; two companies are not
  comparable with each other.** Without that asymmetry the corpus's clearest
  reversal is invisible: December 2024's ten are the *channel's*, May 2025's ten
  or eleven are *everything's*.
- **Only against the most recent comparable claim that carries a camp.** Fire on
  every earlier pair and one 2022 "all 1099 and not full-time" flags each of the
  next seven claims in turn — seven findings where there is one. Bounded this
  way it fires at the TRANSITIONS, which is what a flip-flop is.

It is not gated on the claim having a figure. *"That's why all my workers are
contract workers"* names no number and is the single clearest status claim here.

Work the adjudication in umtool, at `/browse/<project>/claim/<id>`. Sign-off is
"the inbox is empty": `claim-unadjudicated` is **blocking**.

## `render.chromeEngine: "hyperframes"` — the chart band

Opt-in, and absent it the ffmpeg chrome path is byte-for-byte unchanged.

The chart band **replaces** the footer node track, which only moved at section
handovers — precisely the fault it exists to fix. It takes the footer's ground
and 100 px more, and the picture loses that height (1500×924 → 1500×824).

`compose-chrome.mjs` emits a HyperFrames project per region and renders it to a
**lossless RGBA PNG sequence**; `build-video.mjs` overlays the frames. Three
things about that are load-bearing:

- **Footage never enters Chrome.** HyperFrames pre-extracts source video to JPEG
  q95, which is unacceptable when the picture *is* the cited evidence. Only
  chrome is composed there — about 37 % of full-frame pixels rather than 100 %.
- **The PNG regions overlay BEFORE the rail chain, not after.** The rail chain
  ends in `format=yuv420p`, and overlaying an alpha sequence onto yuv420p is the
  same alpha-subsampling trap the rail already documents, one layer later.
- **The playhead is driven by `out/schedule.json`**, which the build writes.
  Recomputing claim times here would be a second implementation of
  `segmentOffsets()` and would drift the first time `transition` changed. Same
  rule as `widen()`: imported, never reimplemented.

One clip-path sweeps the whole plot rather than a `stroke-dashoffset` per series.
The obvious build animates each path's dash offset, and it looks right for the
strokes and wrong for everything else: the gap band between the two totals is a
filled polygon with no stroke to offset, so it appears whole the moment it fades
in and the chart is showing an answer the playhead has not reached.

**The flag colour is not the palette's amber.** `#E8A33F` sits at ΔE 12.4 from
the coffee series' `#D2732F` at *normal* vision — below the 15 floor — so a flag
badge beside a coffee mark was hard to tell from the coffee mark. `#E0E24A`
replaces it and adds **no new worst pair**: the worst CVD pair
(`#C55F9C↔#22AB83`, ΔE 5.4 deutan) and the worst normal-vision pair
(`#C55F9C↔#D2732F`, ΔE 16.3) are identical with and without it. The implied
total's `#EDF0EC` fails the categorical lightness and chroma checks *by design* —
it is an aggregate, not a categorical peer, so it is encoded by weight and
consumes no palette slot.

## `render.chrome` — the on-screen deck

Opt-in (`render.chrome = { engine: "hyperframes", layout: "deck", deck: {...} }`,
every key in [Manifest shape](#renderchrome--the-on-screen-decks-settings-and-per-entry-onscreen));
absent, nothing here runs and the ffmpeg chrome path — header, footer, corner
QR — is byte-for-byte unchanged. It **replaces** that chrome rather than
joining it: a deck manifest draws none of the citation header, the footer's
node track or the per-clip corner QR, because the deck carries all three
itself, and it refuses a `render.rail` or the legacy `render.chromeEngine`
beside it.

A persistent bottom panel, rendered as ONE HyperFrames composition over the
WHOLE concat — a pip timeline (one subtle, unlabelled pip per segment the deck
is shown over), a big authored title per clip, an automatic source-and-date
subtitle, and the clip's QR — while the footage is scaled into a box above it
(`footageScale`, default 0.82: 1574×886 at (173, 2) for a 1920×1080 frame with
the default 190 px deck). At every clip boundary the pip travels and the
title, subtitle and QR hand over to the next clip's, centred on the cut's own
mid-dissolve; a card plays under the deck when `overCards: "show"`, or the
deck slides away for its duration when it is `"hide"` (the default) — no text
handover happens across a hidden segment, because there is nothing on screen
to animate.

The code's host (`JASOLYZER.PAGES.DEV`, muted, tracked 0.1 em) runs up the QR's
left side and is exactly as long as the code is tall (`deckLayout(render).qr.size`,
150 px by default), whatever the host: the page measures the string's ink in the
loaded face once at load, scales its size to fit, and indents the first
letter's side bearing away, so the ink starts on the code's bottom edge and
ends on its top.

`out/<variant>/schedule.json` (`deckSchedule()`) is the one source of *when*:
the build writes it from PROBED segment durations and real source metadata;
`estimateSchedule()` produces the same shape (`estimated: true`) from the
manifest alone, for a preview that runs before anything has been built.
`deckChoreography()` turns a schedule into the handover times the
composition, the preview and a reviewer all read — there is no second
implementation of the arithmetic to drift.

### Rendering it

`compose-chrome.mjs --region deck` is `--region chart`'s sibling: the same
CLI, the same render cache, the same vendored GSAP, a different composition
(`chrome-deck.mjs` instead of the chart band's SVG). `--region feed`, `stamp`,
`posts` and `teaser` are the deck's other regions (below).

```
node umtool/report-to-video/compose-chrome.mjs <manifest.json> [--region chart|deck|feed|stamp|posts|teaser] [--variant sourced|full]
                                                [--from <s>] [--duration <s>] [--out <dir>] [--preview]
                                                [--still <s> --png <path>]
                                                [--render] [--workers 4] [--quality high] [--format png-sequence] [--fps 30]
```

- **`--preview`** composes into `chrome/deck-preview/` and never renders —
  umtool's live settings preview, which must never disturb a build's own
  project directory or its frame cache.
- **`--still <s> --png <path>`** is the review still: a headless Chromium
  screenshot of `index.html?still=<s>`, the SAME seek the renderer performs for
  every frame — about 2 s instead of a render.
- **`--render`** writes `chrome/deck-frames/frame_%06d.png` plus a `.key` file
  holding `chromeCacheKey({html, assets, fps, frames, version})`. A render is
  SKIPPED when the key on disk matches and the frame count on disk equals
  `frameCount(total, fps)`: a full ~6-minute deck is ~10,800 frames, about
  7–8 minutes with the default 4 workers and ~400 MB of PNGs, and an
  unchanged re-run is about 1 s. The renderer is pinned (`HYPERFRAMES_PKG`,
  default `hyperframes@0.8.24`; `HYPERFRAMES_BIN` overrides it for a stub, an
  e2e fixture's), and the version is part of the key — a new renderer is new
  frames.
- **`--from <s>` / `--duration <s>`** window a compose to less than the whole
  cut, used by `--chrome-preview` below. A windowed project and its frames get
  their own names, `deck-from<s>[-frames]`, so a window never overwrites the
  full-cut sequence.

`build-video.mjs` drives all of it as one command — schedule, compose, render
(cached), overlay — with three flags beyond the ones already
[listed](#driven-from-umtool):

- **`--chrome-only`** — re-lay the deck over the segments already on disk:
  re-probe, rewrite the schedule, recompose (re-render only if the key
  changed), re-concat with the overlay, re-mux the chapters. **No segment is
  rebuilt and nothing is fetched.** The driver labels this "re-render
  on-screen".
- **`--no-chrome`** — the deck's framing with no overlay: a fast picture check
  of the letterboxing, with nothing composed or rendered. Holds and footage
  moves are part of the CUT, not the chrome, so `--no-chrome` still applies
  them (the footage moves aside for cards it does not draw), and its length is
  the schedule's.
- **`--chrome-preview <at> <dur>`** — renders only that window of the deck and
  writes `out/<variant>/<slug>.preview.mp4` of it, from a cached concat when
  there is one, else built straight from the segments the window touches.

`assertChrome(render.chrome, render)` runs at the top of every build whenever
`render.chrome` is set at all — not only when the deck is on — so a block that
is present but malformed (a bad `engine` or `layout`, as well as a bad `deck`)
is refused before a single fetch, the same guarantee a deck build gets.

**`transition: 0` (hard cuts) now works through the deck.** A hard-cut concat
to `<slug>.prerail-hardcut.mp4`, then ONE overlay re-encode (`applyChrome`,
ported from the diet fork) lays the panel on afterwards, because the concat
demuxer's stream copy cannot host a filtergraph. The legacy chart band still
refuses a hard-cut transition outright.

### Posts on the deck

When the schedule carries `posts` (`deckSchedule` adds the key only when there
are some, so a cut without them writes the schedule it always did), the build
renders one short sequence per clip that carries posts — a WINDOW
(`postWindows`), from that clip's first card appearing to the end of its
leave — and lays each over the cut at its own second, after the deck's own
region. `chrome-posts.mjs` is the page (pure, like `chrome-deck.mjs`).

```
node umtool/report-to-video/compose-chrome.mjs <manifest.json> --region posts --segment <clip id>
                                                [--still <cut s> --png <path>] [--render] [--preview]
```

- **The window** is snapped outward to the frame grid (`snapWindow`): frame 1
  lands exactly on cut frame `f0`, and the sequence is `frameCount(to − from,
  fps)` of the snapped window, never past the cut's end.
- **Files:** project `chrome/posts-<segment>/`, frames
  `chrome/posts-<segment>-frames/` with their own `.key` (html, assets, fps,
  frames, renderer version — the deck's cache, per window); `--preview`
  composes `chrome/posts-preview-<segment>/` and never renders.
- **The page** is region-local (`postsGeometry`, 600×838 at (1296, 26) by
  default; at (1123, 26) with `shift: false`), transparent outside the cards. `?still=<t>` and the preview's
  `deck:seek` take CUT seconds; a preview page answers with
  `{type: "posts:ready", segment, from, to, ids}`.
- **The stack is planned in the page.** Whether the next card overflows the
  column depends on how its words wrap in the deck's face, so the page
  measures the cards once the fonts are in and hands the heights to
  `postsCues` — the module's own function, carried in by its source text, so
  the tests run the exact plan the page runs. The timeline is built and
  registered in that callback; the renderer awaits `document.fonts.ready`
  before its first seek.
- **The overlay:** each window is an input with `-itsoffset <from>` (negative
  in a `--chrome-preview` that starts after the window does), the deck's
  `-reinit_filter 0` + `format=rgba`, and
  `overlay=…:format=yuv444:eof_action=pass` — **not** `shortest=1`, which would
  end the whole cut where the window ends. Outside its window every frame is
  the deck-only frame, bit for bit, and the length is unchanged (a unit test
  runs ffmpeg to say so). The crossfade concat, the hard-cut `applyChrome`
  pass, `--chrome-only` and `--chrome-preview` (only the windows it touches)
  all lay them; `--no-chrome` lays neither.
- **`verify-build`** also checks each window's `chrome/posts-<segment>-frames`
  holds that window's frame count, and that each held clip's freeze is in the
  file: two frames inside the still part of the hold -- after the hold starts
  and the move lands, before the outgoing dissolve (or the end fade) -- are the
  same, outside the deck and the column, within re-encoding noise. A hold with
  under three frames of still picture there (0.5 s under a 0.5 s crossfade) is
  reported as not checked.

### The posts feed (`posts.layout: "feed"`)

The other way to draw the posts: a column for the WHOLE cut beside the
footage, instead of cards over the end of each clip. The deck stays full
width at the bottom; the column stands on it from the frame's top, so the two
read as one L-shaped surface around the picture. Nothing pauses and nothing
moves: no hold, no footage move, and the cut is as long as its segments.

- **Geometry** (`feedGeometry`): the column is `posts.width` (600) wide, flush
  with the `position` side's edge and the frame's top, down to the deck's top
  edge — 600×890 at (1320, 0) at 1920×1080. The footage keeps the frame's
  aspect and is as large as fits beside it with `posts.inset` (24) clear on
  every side, centred: 1272×716 at (24, 87), 66 % of the frame's width against
  the deck alone's 82 %. A feed whose footage would be under half the frame's
  width is refused (`postsFitErrors`).
- **Framing.** Every footage segment of a feed cut — clips, stills, cards with
  `overCards: "show"` — is framed into that box when it is built
  (`deckFraming(render, { feed: true })`), for the whole cut. A cut is a feed
  (`feedOn`) when the deck is on, `posts.show`, `layout: "feed"`, and at least
  one post is drawn on a clip of the cut's whole timeline (an `--only` rebuild
  frames as the full build would). Each framed segment's `<id>.cut.json`
  records `framing: { layout, box }`; a still's and a card's record holds only
  that.
- **Switching the layout reframes every segment**, so it takes a normal build
  (with `--skip-fetch` it re-cuts from the cached windows). `--chrome-only` and
  `--chrome-preview` read the records first and refuse segments framed for the
  other layout, naming each one (`framingProblems`); a segment with no
  framing record was built for the deck's box.
- **When** (`postSchedule`): a post has one time, `in` — its clip's start
  plus the transition (start + D): after the incoming dissolve, and D in on
  the first clip too, which has none; a clip's next posts follow
  `seconds` apart, or closer on a clip too short for that, so the last is in at
  least that long before the clip leaves. Once in, a post stays. The schedule
  says `layout: "feed"` and carries each post's `in` — only when there are
  posts to draw, so a popup schedule and one without posts are byte-identical
  to what they were. `postWindows` is empty for a feed.
- **The column** (`chrome-feed.mjs`, one composition for the whole cut,
  region-local at the column, transparent outside its panel): a one-row header
  (the platform and `@handle`, or "Posts" over several authors -- no running
  count and no caption, which a viewer reads off the column itself), over its
  ground and nothing else until the first post (no empty plate). Each
  post TICKS IN at the top, newest first: the cards already in slide down by
  its height over `push` while it enters from the column's outer edge, its
  accent rim flares and settles to a lit rail, which goes out when the next
  one arrives. A card pushed past the column's bottom fades out as it goes —
  the oldest scroll out. Over a segment the deck hides for (a full-frame card,
  the teaser) the column slides out of the frame's side with the deck and
  back after (`deckChoreography`'s visibility). Cards are the popup's design
  sized for the column: 24 px words on 33 px lines, `maxLines`, the post's
  date (the handle and platform too when there is more than one author), a
  `qrSize` QR in its own cell. The plan (`feedCues`) runs in the page on the
  measured card heights, embedded by `embedFn`, like the popup's.
- **Files:** `compose-chrome.mjs <manifest> --region feed` — project
  `chrome/feed/`, frames `chrome/feed-frames/` and their `.key`, a window
  `chrome/feed-from<s>[-frames]`, the preview `chrome/feed-preview/` (never
  rendered); cached exactly as the deck's. The build renders it after the
  deck, checks it is as many frames as the deck's, and lays it the deck's way
  (`-reinit_filter 0`, `format=rgba`, `shortest=1`) in the crossfade concat,
  the hard-cut `applyChrome` pass and `--chrome-preview`.
- **`verify-build`** checks `chrome/feed-frames` holds the whole cut's frames
  and that the schedule holds and moves nothing.

### The hold and the move, where the cut is joined

`segmentJoins(schedule)` turns the schedule's holds and `moves` into one join
per carrying clip; the segment FILES are never touched, so `--chrome-only`
changes a hold or a move without rebuilding a clip, and a cut without posts has
no joins and runs the graphs it always did.

- **The hold** is `tpad=stop_mode=clone:stop_duration=<hold>` on the input's
  picture and `apad=pad_dur=<hold>` (silence) on its sound, before the
  xfade/acrossfade. A hold is a whole number of frames (`postHolds` rounds it:
  2.5 s at 25 fps is 2.52 s), because `tpad` clones whole frames and `apad`
  pads exact seconds.
- **The move** is one `perspective` filter on that input, AFTER the hold
  (`sense=destination`, `eval=frame`): the input frame's corners are placed so
  the footage box goes from `from` to `to`, eased by smoothstep over
  `[segmentAt, segmentAt + seconds]` in the segment's own clock, hold included,
  then held there. A first post that appears inside the hold therefore still
  moves the footage, the frozen frame with it. Perspective resamples at
  1/256 px, so the box glides with no whole-pixel stepping, where `scale` +
  `overlay` and `zoompan` round to whole pixels. Before the move the map is the
  identity, which perspective copies bit for bit. `fillborders` pins the
  frame's outer 2 px to `palette.bg` first, because perspective fills what the
  shrink uncovers from the input's edge.
- **Hard cuts** with a hold or a move concatenate through the concat FILTER
  (`hardCutFilterArgs`, one encode) rather than the demuxer's stream copy; the
  prerail's `.segments` record then names each join, so a changed hold is never
  served from a stale concat. Without joins the stream copy is unchanged.
- **Every length is the schedule's** under the deck: the xfade offsets, the
  chapters, a `--chrome-preview` window and `--chapters-only` all add the holds
  to the probed lengths (`cutOffsets`), the same sum `deckSchedule` makes.

### The cut's edits: `muteFrom` and `render.endFade`

Both are made on one input's chain before the join, beside the hold and the
move (`cutJoins` merges them into the deck's joins; `withCutEdits` is the pure
merge), so neither touches a segment file, and a cut that sets neither gets no
join for them: its graph, record and schedule are what they are without the two
keys. (Every crossfaded graph did change once, separately, when each input's
sound was pinned to its picture's length — `umtool/docs/quirks.md`.) They work
with or without the deck, on crossfades and hard cuts.

- **`muteFrom` is mapped through the segment's cut record.** The build snaps a
  clip's cut to the nearest silence, so its segment starts up to `snapWindow`
  seconds from the manifest's `start` (or `cutStart − leadIn`). Every clip build
  writes `segments/<id>.cut.json` — `{ video, start, end }`, the source seconds
  it was really cut from — and `muteFrom − start` is the mute point in the
  segment's clock (`muteSegmentSeconds`, in `deck.mjs`). A segment with no record
  (built before records existed, or copied without it), or one whose record is
  not as long as the segment, is measured from the unsnapped start instead, and
  the build says so in a note. The sound chain is
  `afade=t=out:st=<at − 0.04>:d=0.04` (then the hold's `apad`, if any); a mute at
  or before the segment's start is `volume=0`.
- **The end fade's picture is a `geq` blend toward bg's Y′CbCr**, enabled from
  the fade's first frame: frame `lastFrame − n` is the last untouched one and
  `lastFrame` (the hold's clones counted) is bg. Not `fade=…:color=`, which works
  in RGB only (`umtool/docs/quirks.md`). The sound is `afade` out to silence at the
  last frame's time, over the same `n` frames. A fade longer than the segment is
  the segment (`endFadeFrames` clamps `n` to `lastFrame`), so a 3 s finale under
  `endFade: 5` still ends on bg and in silence together.
- **The hard-cut record names a mute and a fade** (`"mute"`, `"fade"` on a
  `# join` line, only when there is one), so a cached prerail made without them,
  or with other values, is never reused. A teaser's `dip` is recorded the same
  way (`"dip"`, on the segment before it).
- **A teaser's `dip`** is a third edit made here: its sound on the segment
  before the teaser, its picture after every overlay (the teaser section above).

### Two ffmpeg traps that are the deck's alone

- **Mixed RGB/RGBA frames restart the whole filtergraph.** HyperFrames writes
  a frame with nothing transparent in it as opaque RGB and every other frame
  as RGBA; ffmpeg's default response to the decoded stream switching kind
  mid-sequence is to REINITIALISE the filtergraph, which drops whatever was
  buffered and ends the output early — measured, a 3.5 s xfade+overlay came
  out at 2.0 s. The deck's input alone gets `-reinit_filter 0` plus
  `format=rgba` straight after it; the chart band's chain and inputs are
  untouched.
- **A relative `--out` broke every hard-cut concat.** The concat demuxer
  resolves a list entry against the LIST FILE's own directory, not the cwd, so
  a relative output root named every segment twice over and the first input
  failed to open. `concatHardCut` now writes every list entry as an absolute
  path — unchanged for a build that already worked, and not only the deck's.

Both are in [quirks.md](../docs/quirks.md)'s running list.

### Fonts

Copied into the composition's `assets/` as private families `DeckSans` /
`DeckSansBold` (from `render.fontRegular` / `render.fontBold`), with
`sans-serif` as the only fallback — the same trap the chart band's `'Band'`
dodges (a bare `local()` resolves on a desktop browser and silently fails in
the render browser, shifting every metric). The deck is **strict** where the
band is lenient, though: a face that cannot be copied is a build error, not a
quiet fallback, because the deck has no other text on screen to notice a
substitution happened.

### `verify-build.mjs`'s deck checks, and their limit

Confirms `schedule.json` is a *measured* (not estimated) deck schedule, that
`chrome/deck-frames` (and `chrome/feed-frames` / `chrome/stamp-frames` when the
schedule has a feed or stamps) holds exactly `frameCount(schedule.total, fps)` frames,
and that the finished file's video stream is that many frames long — laid
with `shortest=1`, so a short sequence shortens the cut silently rather than
erroring. It **cannot tell whether the overlay was actually laid onto the
concat**: a `--no-chrome` final passes as long as old frames happen to be on
disk from an earlier render. `--chrome-only` and `--rail-only` both write over
the final file while it is still encoding, the way they always have, so a
check that races one of them is checking a half-written file.

### Driven from umtool

Writers (`updateClip`'s `onscreen`, `updateOnscreen`, `updateChrome`), routes
(`/api/report/{chrome,onscreen,chrome/preview,chrome/files,still,video}`) and
the UI (the "On-screen" section, never "deck" — that name is already the song
kind's) are [report-video.md](../docs/report-video.md#the-on-screen-deck-renderchrome)'s
to describe; this file stays the pipeline's own contract.

## The Archilyzer Media preset (`render.brand`)

The channel's own videos wear its brand; a report cut for anybody else does not.
So the brand is **one opt-in key**, and a manifest without it renders exactly as
it did — the before/after card diff in `plans/brand-and-themes.md` ("Slice S4, as
shipped") is the proof, and `brand.test.mjs` pins the unbranded header and
`selectVariant`'s unbranded result.

```jsonc
"render": {
  "brand": "archilyzer-media",
  "endCard": { "seconds": 20, "url": "archilyzer.pages.dev" },  // optional; false = none
  ...
},
"thumbnail": { "headline": "The county said yes", "clip": "c04", "at": 32990.5 }  // optional
```

`umtool new <slug> --brand archilyzer-media`, or the brand choice in umtool's
"new project" form, writes the key for you.

What the preset **owns**, whatever the manifest says:

- `render.palette` — the slate of the parent mark lit in Signal
  (`#151b20` / `#e7edf1` / `#8496a2` / `#5fa8a0`, amber `#e3b15c`);
- the faces — Archivo at wdth 118 for display, IBM Plex Sans for body (the
  rail, `ledger`, `scroll` and `chart` SVG text included), IBM Plex Mono for the
  header and meta lines; `render.fontRegular` becomes the vendored Plex Mono
  Regular and `render.fontBold` the vendored Plex Mono Bold (compose-chrome's
  HyperFrames band sets its bold in it).

What it **adds**:

| | what | where |
|---|---|---|
| title card | `style: "title"` becomes the lockup top-left, the title in Archivo 720, the found line, a mono meta line (`meta` or `foot`; `sub` sits above the found line) | `brand-cards.mjs` |
| clip header | the mark leads the `Channel · title · date @ time` line in place of the accent tick; the channel is drawn in the foreground colour | `headerFilters` in `build-video.mjs` |
| end card | appended by `selectVariant` (id `end`, `hideRail`), 20 s by default: the lockup and the site on the left, the **right half bare** for YouTube's end-screen videos | `brand.mjs`, `brand-cards.mjs` |
| thumbnail | 1280 × 720: a still from a cached clip window (or `thumbnail.still`), the headline in Archivo 800, the mark top-left, the duration-badge corner clear. Made after a full build when `thumbnail` is set, or alone with `--thumbnail` | `out/<slug>.thumbnail.png` |

The other card styles (`chapter`, `bullets`, `sources`, `timeline`) keep their
layouts and take the preset's faces and palette. So do the rail, `ledger`,
`scroll` and `chart`: their SVG text is set in IBM Plex Sans, and rsvg-convert
finds it through the same `FONTCONFIG_FILE`, measured by its own advances
(below, "Why a table, not an average").

**The drawings are not drawn here.** The mark and the lockup (its letters as
outlines, so no font is needed to draw it) are `common/lib/brandMedia.ts`'s,
exported by `common/bin/brand-media.ts --video-kit` into
`brands/archilyzer-media.json`, because these scripts run under plain `node`.
A common test fails when that file is stale; re-run the CLI, never edit it.

**Fonts are vendored, not installed.** `fonts/` holds Archivo[wdth,wght], IBM Plex
Sans[wdth,wght] and IBM Plex Mono Regular and Bold — unmodified from google/fonts
(`ofl/archivo` at `95f4904f`, `ofl/ibmplexsans` / `ofl/ibmplexmono` at
`0b58fb37`), about 1.5 MB — with `OFL.txt` (Plex carries a Reserved Font Name, so
it may not be shipped modified, subset included) and a `fonts.conf`. The preset
sets `FONTCONFIG_FILE` to that conf on **its own** `magick` and `rsvg-convert`
children only, so Pango sees the variable faces (`Archivo @wght=720,wdth=118`);
drawtext takes the mono face as a `fontfile=` path, which is why it is a static.
If a renderer ignores `FONTCONFIG_FILE`, `sh fonts/install-user-fonts.sh` puts
the faces in `~/.local/share/fonts` with no sudo.

Two measurements the code depends on:

- **ImageMagick's pango coder lays out at 96 dpi** (7.1.2 here), so a Pango `size` of N pt
  draws N × 4/3 px, and a `-size W` wrap width is honoured in px only at that
  default density (`-density 72` makes 1 pt = 1 px but wraps at ¾ of W, and
  `-define pango:width` is ignored). `brand-cards.mjs` sizes in px through `pt()`.
- **ImageMagick stamps the wall clock into every PNG** (`tEXt date:create`,
  `date:modify`, `date:timestamp`) and ignores `SOURCE_DATE_EPOCH`, so two runs
  of the same code never produce the same PNG bytes. A byte-identity check has to
  drop those three chunks and compare the rest — IHDR and IDAT included.

### Why a table, not an average

The rail, `ledger`, `scroll` and `chart` assets are **fitted, not flowed**: a
label that would overrun its column is cut short with an ellipsis by `fit()`
(and a ledger quote wrapped by `wrapPx()`) before it is drawn, because an
overflowing row runs under the value column beside it rather than wrapping. So
a face carries the metric it is fitted by (`svg-faces.mjs`), and swapping the
face without it would overrun.

- **Fira Sans** (no brand) keeps its average: 0.50 em a character, a character
  count, exactly as it always cut. Measured over the strings `fit()` actually
  truncates in the real manifests, Fira averages 0.457 em (p95 of a string's own
  average 0.492), so 0.50 is the hair of margin it was chosen with. It cannot
  move — an unbranded render is byte-identical by rule — and it is the system's
  font, so a table of its advances could not be pinned anyway.
- **IBM Plex Sans** (the preset) is measured per character:
  `face-metrics.mjs` holds the vendored variable font's advance for all 891
  characters it maps, at the two weights these assets draw (400 and 700, wdth
  100). `fit()` keeps the longest prefix whose width — ellipsis, weight and
  letter-spacing included — is inside the budget; `wrapPx()` wraps by width and
  fits every line; the ledger's scope pill hugs its label.

An average cannot promise a column. Measured the same way, Plex Sans averages
0.456 em regular (Fira's own number) but 0.479 bold and 0.59–0.61 in capitals;
and pushing the manifests' longest real text through each call site, even
Fira's 0.50 lets the scroll's bold, letter-spaced column head overrun (152 px
rendered in 140). The table does not: over the same runs, every Plex one
renders inside its budget (widest 98.9 %).

Two limits, both measured and both sub-visible in the real manifests:

- **Kerning is ignored, and the plain sum is not the conservative side in
  general.** Plex Sans has positive kern pairs (412 at regular, 348 at bold, up
  to +55 units: a closing quote after `r`, `y` or `f`, `TT`, `AA`; bold `(j`
  +70), so text made of them renders wider than the table says — `T` × 60 at
  13 px is 464 px of ink against a sum of 446.2. Over the manifests' 144 real
  strings, and the same in capitals, the worst net kerning is **+0.50 px**, so a
  fitted run can end half a pixel past its budget at most. If that ever
  matters, `gen-face-metrics.py` would emit the positive pairs and
  `textWidth()` add them (the branded path only).
- **A character the face does not map** (emoji, CJK, drawn by fontconfig's
  fallback) counts `FALLBACK_EM`, 1.3 em. That covers emoji (~1.23 em), flags,
  CJK (at most 1 em) and the common scripts, but not every fallback glyph: a few
  wide symbols exceed it (`⟹` 1.42 em, `﷽` 1.93, `Ⅷ` 1.31), so a label made
  mostly of them would overrun by about 9 %. No real label has one.

`face-metrics.mjs` is generated: `python3 fonts/gen-face-metrics.py` (fontTools)
rewrites it from the vendored font, and a test fails when it is stale.

## Things that cost time to find out

**yt-dlp picks VP9 at `height<=720`, and that is a trap.** `--download-sections`
combined with `--force-keyframes-at-cuts` re-encodes, so a VP9 pick means
libvpx-vp9 — 27 seconds to cut a 5-second clip. It also writes a `.webm` and
appends that extension to whatever `-o` you gave, so the file never lands where
you asked and the run fails looking for it. Pin H.264/AAC in mp4 and the same cut
takes ~12 seconds. `build-video.mjs` does this and keeps a rename fallback for
the case where a fallback format still forces another container.

**`--force-keyframes-at-cuts` is not optional here.** Without it the cut snaps to
the nearest preceding keyframe and can start seconds early. That is fine for a
human scrubbing a VOD; it is not fine when the clip *is* the citation.
`PlayerProvider.tsx:478` builds the copyable clip command without this flag —
correct for its purpose, wrong for ours.

**`--ignore-config` is mandatory.** The operator's own yt-dlp config redirects
output to `~/Podcasts` and attaches thumbnail/metadata post-processors. Every
managed yt-dlp call in this repo passes `--ignore-config` for the same reason.

**yt-dlp exit 101 is success**, not failure — it means a clean early stop. The
repo encodes this at `common/ytdlp/downloadOneManaged.ts:355`; a new caller has to
replicate it.

**Local media will not help you.** Only 5 of 1,804 PirateSoftware video dirs hold
any media at all, and none are ones a report is likely to cite. Clips are a
network fetch. `metadata.info.json` and `transcript.cues.json` *are* present for
every video, so titles, dates, durations, webpage URLs and cue timings all come
from disk with no probe.

**Upstream availability is load-bearing.** A clip can only be fetched while the
source is still up. Check `platform state` via `get_video_metadata` before
committing to a clip — a `deleted`/`maybe_missing` source needs a quote card
instead of footage. The archive outlives its sources, so a video built from an
old report will be *less* complete than the report unless this is handled
deliberately.

**ImageMagick's `-size` leaks into the Pango group.** `-size 1920x1080 xc:BG`
followed by `( ... pango:@file )` renders the text into a full-frame box, which
pins it to the top and wraps at the frame edge instead of the text column. Reset
`-size` inside the parens.

**ffmpeg `drawtext` does not wrap and hates punctuation.** Both are solved the
same way: wrap to a column count in JS, write to a file, and use
`textfile=`. Nothing then needs escaping. Stream titles also need emoji and
`!command` suffixes stripped or they render as tofu in the attribution line.

**Segments are encoded to identical parameters on purpose** so the final
concatenation is a stream copy via the concat demuxer. Mismatched streams are the
usual reason a naive concat produces a broken or audio-desynced file.

## Not done yet

- **Narration is silent by design.** Cards carry the connective text; the only
  audio is the clips'. A TTS layer would attach per card (`seconds` already gives
  it a duration to fill) — deliberately deferred rather than designed out.
- **Snapping is silence-based, not word-based.** It finds gaps in the audio, which
  is usually the same thing as a word boundary but is not guaranteed to be —
  a speaker who does not pause gets the unsnapped cut. Forced alignment against
  the transcript would be exact; `silencedetect` is a tenth of the work and
  handles the cases that were actually audible.
- **`chromeRegions()` returns one entry, never two.** The chart band and the
  deck are each a single HyperFrames region, and a manifest gets at most one of
  them (`render.chrome` and the legacy `render.chromeEngine` refuse each
  other). The deck excludes a rail outright (`validateChrome` refuses
  `render.chrome` beside `render.rail`) and replaces the header and the
  footer's node track with its own panel; for every manifest that is NOT a
  deck, the rail and the header are still drawn by the ffmpeg chain, and
  porting them into a region of their own is the rest of that job — the rail needs the ghost/hop convention (a row with no clip fades
  in dimmed under a dashed rule and the amber highlight *hops over* it to the
  next cited row) which the strip builders cannot express. Until then
  `railFilterChain` and `renderFooterAssets` stay; they must not be retired on
  the strength of either region alone.
- **`timelineNodes` / `section` / `sectionEnter` are still live.** They lose their
  only consumer when the ffmpeg footer goes, not when the band arrives — so they
  retire with `renderFooterAssets`, in that same commit.
- **Manifests are written by hand** from verified cue data. Deriving a first-draft
  manifest automatically from a report's citations is the obvious next step; the
  report parse is straightforward (`> "quote"` followed by
  `— [title @ h:mm:ss](…?v=slug%2Fid&t=sec)`), the cue-matching is the real work.