# Visual-First Final Render Repair

Session lesson from AutoShorts/TrueTraceShorts Final Pilot Render V1 rejection.

## Failure pattern

A technically generated final can still be rejected when it looks like a preview board with an AI background pasted behind it.

Rejected symptoms:

- Preview/animatic overlays reused in a final video.
- Wan/AI video used only as a short blurry background loop.
- Large cards, thick frames, debug bars, simulated document blocks, and permanent text boxes dominate the image.
- Final output feels like a technical demo instead of harmonious short-form content.
- A ComfyUI/Wan extraction process exits nonzero but the recovered MP4 is treated as success.

Hard rule: a run with exit code != 0 is not final-success unless explicitly marked recovered and then validated by a robust output parser + ffprobe.

## Correct architecture

Separate Preview and Final renderers.

Preview may use:

- boxes, frames, technical labels
- PREVIEW / NOT FINAL markers
- debug-style layout
- dense structure overlays
- deterministic animatic cards

Final must avoid:

- large text frames / document cards / UI walls
- thick debug bars or progress bars
- permanent framed screens
- long simulated document text
- stretching a 3–5s AI background loop across a 35–40s video

Final should be visual-first:

- full-bleed Wan/AI visuals carry the main image
- overlays are supporting layers only
- captions are calm, mobile-safe, and visually integrated
- at most one small label/stamp per scene, except a deliberate final takeaway
- scene transitions and visual metaphors should work even with captions muted

## FinalOverlayPolicy baseline

For final renders enforce a policy similar to:

- captions allowed, but keep within lower third
- one short label/stamp per scene maximum
- final takeaway allowed
- block preview frames, debug bars, long document text
- block large textbox/UI-card overlays > ~35% of screen
- block overlay overload with reason `overlay_overload`

## Visual-first shot plan pattern

For an AI-summary / decision-evidence short, use scene-level Wan clips rather than split-screen text cards:

1. Hook / failure: full-bleed meeting/data room; note fragments move toward a polished but hollow AI summary. Tiny `USELESS` stamp only if needed.
2. Bad output: smooth AI surface with subtle missing slots for owner/risk/decision. Minimal labels only.
3. Mechanism: note particles pulled into a compression funnel; decision target remains outside/unlit. One small label/pointer.
4. Fix: decision target lights up; notes organize into calm lanes for blockers, owners, risks, next steps. Labels must be tiny and renderer-owned.
5. Takeaway: blurred generic summary transforms into a clear decision path.

Prefer Strategy A for the next full final: one Wan clip per scene matching scene duration (e.g. 5s, 7s, 9s, 9s, 8s), then deterministic renderer adds captions/labels.

## Visual proof before second final

After a rejected final architecture, do not jump into another full 38s final. First create a 6–10s visual proof for one key scene (often the mechanism scene):

- 9:16
- no preview frames/cards/debug bars
- Wan is primary visual layer
- minimal overlay: caption + at most one small label/pointer
- static phrase captions with active-word highlight
- Telegram MP4 for human review

Only proceed to a second full final after explicit approval of the visual direction.

## Caption integration

Keep the corrected caption system:

- static 3–7 word phrase segment
- words stay fixed during the phrase
- only current spoken word highlights/pulses left-to-right
- segment changes only at phrase/sentence boundary

But for final visual-first renders:

- no hard debug caption box
- avoid thick background bars
- use shadow/outline/subtle glow
- keep captions mobile-safe but integrated

## ComfyUI/Wan output parsing guardrail

ComfyUI `SaveVideo` history can contain metadata lists such as:

```json
"animated": [true]
```

Do not treat every list item in `outputs` as a file object. Robust parser rules:

- ignore bool/null metadata items
- require dict items for file outputs
- require string `filename`, `subfolder`, and `type`
- validate downloaded file exists
- ffprobe duration and FPS
- block final success if exit code != 0 unless explicitly recovered
- block or hard-warn when Wan raw clip is far shorter than target final duration

Regression tests to keep:

- `false`/`true` history item ignored or blocked cleanly
- missing filename blocks
- nonzero exit blocks final_success
- too-short Wan clip blocks full final or hard-warns

## Approval states

Add an intermediate state after a rejected final:

```text
APPROVED_FOR_VISUAL_PROOF <candidate_id> <version> <script_hash>
```

Allows:

- one short Wan/visual proof
- no full final
- no posting
- no platform API
- no render series

Do not convert `APPROVED_FOR_VISUAL_PROOF` into `APPROVED_FOR_FINAL_RENDER` implicitly.