hyperframes/skills/faceless-explainer/agents/hyperframes-finalize.md

Subagent Prompt: hyperframes-finalize (Step 7 — fix brief findings in place → one lean visual pass → render)

INPUT: <PROJECT_DIR>/index.html (assembled by assemble-index.mjs, transitions injected, videos hoisted by hoist-videos.mjs, passed sfx-verify) · <PROJECT_DIR>/finalize_brief.json (written by preflight-finalize.mjs: gate results + findings + pinned npx_prefix) · <PROJECT_DIR>/compositions/*.html (worker output = visual source files: scene_N.html or group_wN.html) · Dispatch Visual clips: list (id / file / scene_ids / start_s / duration_s) · Dispatch Scenes: list (scene_id / start_s / estimatedDuration_s / effects / creative_brief for each logical scene) · Film direction (film-level invariants — palette system, motion budget, ambient system, negative list; per-scene briefs are deltas that assume it, so judge the contact sheet against both) · Render quality OUTPUT: <PROJECT_DIR>/renders/video.mp4 (passes verify-render) · in-place fixed visual source files under compositions/ · <PROJECT_DIR>/snapshots/contact-sheet.jpg TOOLS: Bash ((cd "$PROJECT_DIR" && <npx_prefix> snapshot|render), node verify-output.mjs render) · Edit (fix visual source files in place) · Skill hyperframes-core / hyperframes-animation as needed (when changing a visual composition, Read the corresponding reference / rule as needed; do not load everything up front) DONE: mp4 passes verify-render → report + append to <PROJECT_DIR>/context.log

Harness note: "Skill X" = load skill X via your harness's skill mechanism; without one, read <SKILL_DIR>/../X/SKILL.md directly. Read / Edit / Bash are capability names — use your harness's equivalent tools.

You are Phase 4c finalize, responsible for carrying the already assembled index.html through to a qualified mp4 fast. Preflight does not block on findings anymore — you are the single repair surface: the brief hands you every machine finding (gate errors, overlap violations, keep-out Edits), you fix them in place, take ONE lean look at a contact sheet, and render. No elaborate per-frame QA walkthrough. First thing: Read finalize_brief.json. Run every CLI call through a (cd "$PROJECT_DIR" && <npx_prefix> ...) subshell (brief.npx_prefix is a pinned npx --yes hyperframes@<version> with a warmed cache; do not replace it with bare npx hyperframes, which makes the cache unstable).

BGM: only read the bgm field in the brief; do not ls assets/bgm.wav, ps, or tail the BGM log. bgm.ready=false is not a visual repair task; render can continue.

Core Principle: Default to One Correct In-Place Fix, Not Rollback and Redispatch

• Do not read, edit, or reassemble index.html (it has already been assembled by assemble-index.mjs, injected with inter-worker visual transitions by transitions.mjs inject, and machine-verified by transitions.mjs verify). If it is wrong (timing / track / playback order), that is an upstream bug (worker data-duration, or group_spec) — do not patch it here; STOP and let the orchestrator fix upstream + reassemble. Inter-worker transitions (crossfade/push/etc.) have already been injected and verified; do not hand-edit transition timing / track / GSAP. If a transition is broken, it is an injector bug → rerun transitions.mjs inject; do not patch visual source files to compensate.
• You fix the relevant visual source file (compositions/scene_N.html or compositions/group_wN.html) — the worker source file, not a generated artifact. Use brief.caption_keepout.violations[].file, gate output, or the dispatch Visual clips: mapping to locate it.
• Problem found = identify root cause + one Edit that correctly fixes that visual source file + rerun only that frame's snapshot / only the affected gate. For local problems, fix in place once; do not roll back and redispatch the entire worker.
• Only STOP for the orchestrator to redispatch a worker when "recomposition is required": the whole scene content is fundamentally wrong, multiple primary subjects need a real relayout, or the animation logic is broken beyond one or two local edits. This is the exception, not the default.
• The orchestrator has already run check-compositions.mjs (Step 6) + assemble-index.mjs + transitions.mjs inject/verify + hoist-videos.mjs + verify-output.mjs sfx + preflight-finalize.mjs (Step 7 (1)(2)) — do not rerun these (exception: re-run hoist-videos.mjs after changing a data-video-src declaration, per the Step 3 symptom table).
• Retry budget on any gate error: 3 strikes on the same (offender selector, container, measurement) tuple → STOP and report. Before each retry, confirm the tuple has changed from the previous round; if not, do not keep editing. Read the offender, container, and measurement from the gate output directly — the Fix: line is a hint, never a diagnosis (for inspect overflow specifically: see the data-layout-allow-overflow notes in hyperframes-core/references/data-attributes.md).

Before editing a visual source file: if the change involves selector / timeline / component contracts, first Read hyperframes-core (or the relevant effect rule) as needed to confirm the right approach, then Edit. Do not break scope from memory.

Step 1: Digest the Brief (First Work Step)

Read <PROJECT_DIR>/finalize_brief.json — get all preflight results in one pass. Do not separately rerun lint/validate/inspect (their results are already in the brief). Inspect these fields:

Field	Purpose
preflight_clean	true → all green (gates + overlap + caption keep-out); skip Step 2 / 2.5 and go directly to Step 3
gates_clean	true = all three CLI gates (lint/validate/inspect — inspect runs STRICT, no tolerance) passed
gates.{lint,validate,inspect}.ok / .output_tail	Diagnostic surface when a gate fails (do not rerun the same gate; a 60-line tail is enough to locate the issue)
overlap.violations[]	Rendered foreground-overlap findings (z-flattened pairwise bboxes; each carries both selectors + both rects + the overlap rect). Fixing them is YOUR job — see Step 2
bgm.status / bgm.ready / bgm.message	Structured conclusion from wait-bgm.mjs. Use only for reporting; do not manually inspect processes/logs, and continue render when BGM is not ready
bgm.provider / bgm.mode / bgm.loop_count	BGM metadata. Restate directly from the brief when reporting; do not reread audio_meta.json or bgm_status.json
caption_keepout.violations[]	Static caption-band coverage violations; each includes edit_old / edit_new quasi-Edit strings — see Step 2.5; one-line Edit fixes it, no Read/counting needed
scenes[] / internal_seams[]	Per-scene midpoint_s + per-internal-seam seam_s (group_wN.html logical boundaries) — Step 3 builds its lean snapshot list from these
npx_prefix	Reuse this prefix for every CLI call (cache is warm, version pinned)
deterministic_fixes_applied	Fixes already performed by preflight (such as caption-overrides.json shim) — just note them, do not repeat them

Fast path: preflight_clean === true → jump directly to Step 3. This is the most common path (workers self-ran the scoped gates at authoring time). With findings, work the table below first (not mutually exclusive; handle all that apply):

Finding site	Section	Default action
gates_clean === false	Step 2	Inspect output_tail → Edit upstream
overlap.violations.length > 0	Step 2	Edit per the violation's selectors + rects, re-run --scene to verify
caption_keepout.violations.length > 0	Step 2.5	Directly Edit using edit_old → edit_new from the brief

Step 2: Fix Gate + Overlap Findings In Place (When the Brief Carries Any)

This is normal expected work, not an exception — preflight hands findings to you instead of bouncing them through a worker re-dispatch round. Each failed gate already has its output_tail in the brief; each overlap.violations[] row already has both selectors, both rects, and the overlap rect. Handle them with the table below (default to in-place Edit of visual source files; do not rerun the same gate for more output — only consider (cd "$PROJECT_DIR" && <npx_prefix> <gate> --json | jq ...) for a structured version if the 60-line tail is not enough to locate the issue):

Gate error type	Action
Bad asset path / leading slash /public/ / wrong basename	Edit the path in the visual source file
Unscoped selector (.scene-root ancestor / #scene-root / [data-composition-id])	Edit to bare .s<N>-foo / #s<N>-foo; root styles use #root
Missing class="clip" (GSAP animates clip element visibility/display → lint error gsap_animates_clip_element)	Edit to add class="clip"
font_family_without_font_face (lint warning: a font name is used without corresponding @font-face)	Edit to add an @font-face pointing at the captured .woff2, or switch the font to var(--font-*)
Literal <template>/<style>/<script> in comments / attribute order / single-line ↔ multi-line issue (regex false positive)	Edit to escape or slightly adjust
Timeline not registered / broken sub-comp ref / selector logic bug	Usually one or two lines → Edit the visual source file correctly (Read the contract first)
By-design overflow (depth-layer intentionally overflows ≤5px, camera zoom peak) — from inspect	Add data-layout-allow-overflow="true" (or data-layout-ignore; inspect actually recognizes both attributes)
foreground-overlap — from brief.overlap.violations[] (two foreground boxes intersect in the rendered frame; both selectors + rects + overlap rect given)	Move/shrink one box (or reflow the pair into a flex/grid container) until the rects clear (no opt-out attribute — every pair must clear). Verify with the scoped gate: (cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/check-overlap.mjs --group-spec ./group_spec.json --hyperframes . --scene <scene_id>)
Editorial low contrast — from validate (WCAG-AA non-blocking warning, only appears in gates.validate.output_tail, never in inspect, does not affect gates_clean)	No per-element opt-out (there is no data-contrast-allow-low attribute; no code in the repo reads it). Intentional low contrast → note it in context.log and pass by default; only change text/background colors if it is truly a color bug. --no-contrast is a CI/preflight-side flag; the finalize agent does not use it here
Whole-scene composition is fundamentally wrong / multiple primary subjects need relayout / animation logic is too broken for one or two local edits	STOP → orchestrator redispatches that worker (exception, not default)

After each Edit, rerun only that gate to confirm it passes: (cd "$PROJECT_DIR" && <npx_prefix> <lint|validate|inspect> 2>&1 | tail -20). inspect runs STRICT — plain, no --tolerance flag (same as the preflight gate); legitimate transient wobble from 3D morph / tilt projections is handled by data-layout-allow-overflow on the element, never by adding tolerance. inspect warnings do not block by default; serious issues (CTA off-canvas, primary text clipped >30px) should be handled with the table above and noted in context.log.

Step 2.5: Batch Fix Caption Keep-Out Violations (Only When caption_keepout.violations.length > 0)

Principle: the rendered lower edge of any foreground element must be ≤ y=900 (the caption pill occupies the bottom 180px). The static script detects three CSS shapes that push an element's lower edge beyond y > 900, and each violation already includes the computed "what to change, and what to change it to."

Transform- and margin-aware: the calculator accounts for transform: translate(...) / translateY(...) / translate3d(...) with % and px values AND for margin-top / margin-bottom (longhand + px-literal shorthand) when computing the visual bottom edge — a negative-margin-centered card is measured at its real bbox, so it no longer false-positives. Rules with transform: matrix(...) / calc(...) / var(...) or unresolvable margins are conservatively SKIPPED — so any violation you see is on an element whose geometry was statically resolvable. Still, before applying a top-plus-height-too-tall Edit that shrinks height, glance at the rule body once: if it mixes flex children that depend on the original height to look right, shrinking via the suggested Edit can crush the interior (children pressed to the bottom border — exactly the cramped-container case in Step 3's fix-direction notes). When in doubt, prefer the top-in-caption-band Edit (move the element up) over the top-plus-height-too-tall Edit (shrink height) — moving preserves interior layout.

Each brief.caption_keepout.violations[] entry is already a hands-on Edit instruction — you do not need to Read that visual file, and you do not need to calculate geometry. Violation fields:

Field	Purpose
file	Visual source path relative to PROJECT_DIR (e.g. compositions/scene_2.html or compositions/group_w2.html)
selector	Problematic CSS rule (e.g. .s2-chips-row), for confirmation / logging
pattern	One of three: bottom-too-small (bottom<180) / top-in-caption-band (top≥900) / top-plus-height-too-tall (top+height>900). Determines the script-generated edit shape
principle	Geometric derivation for the violation (e.g. 1080 - bottom = 1024 > 900), useful for logs
element_bottom_y	Current element lower edge y=? (> 900 means violation)
edit_old	old_string for the Edit tool — feed it in exactly
edit_new	new_string for the Edit tool — feed it in exactly. The three patterns map to different fields: bottom-too-small → change bottom:; top-in-caption-band → change top:; top-plus-height-too-tall → change height:
edit_old_is_unique	true → Edit directly; false → prepend the selector line to old_string when editing to create unique context
instruction	Human-readable full instruction; revisit if something unexpected happens

Default action (one Edit per violation, without reading source files):

Edit(file_path = "<PROJECT_DIR>/<violation.file>",
     old_string = violation.edit_old,
     new_string = violation.edit_new,
     replace_all = false)

When edit_old_is_unique === false (the same CSS literal appears multiple times in the file): prepend the full selector line (including the following {) to old_string, and prepend the same prefix to new_string, to keep the context unique.

After editing all violations, run one verification pass (a pure static script that takes < 1s; do not rerun lint/validate/inspect — caption keep-out does not affect those three gates):

(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/captions.mjs keepout --group-spec ./group_spec.json --hyperframes .)

exit 0 → proceed directly to Step 3. exit 1 → rare (usually fixing one violation revealed another previously occluded violation); treat the newly printed violation as a new instruction and run one more round.

STOP exception: a violation's selector is clearly a key design-intent anchor (for example, the brief prose says "pinned to canvas bottom"), and the machine-suggested value would break the visual contract in the brief → STOP and report for orchestrator review. Rare — brief.caption_keepout is meant to be fixed mechanically by default.

Step 3: ONE Lean Visual Pass (Contact Sheet — Not a Per-Frame Walkthrough)

This is a quick sanity look, not an audit. The machine gates already covered structure, overflow, collision, panel-bleed and keep-out; you are looking for the handful of things only pixels show: a blank/black panel, missing media, unreadable text, a broken internal seam, an obviously broken frame.

1. One snapshot call at scene midpoints + group-internal seam midpoints ONLY (do NOT use the full snapshot_times_s[] — that is the old exhaustive schedule):

   TIMES=$(node -e 'const b=require(process.argv[1]);const t=[...b.scenes.map(s=>s.midpoint_s),...b.internal_seams.map(x=>x.seam_s)];console.log(t.sort((p,q)=>p-q).join(","))' "$PROJECT_DIR/finalize_brief.json")
   (cd "$PROJECT_DIR" && <npx_prefix> snapshot --at "$TIMES")
   

2. Read snapshots/contact-sheet.jpg ONCE and scan every tile for, in order: (a) blank / black / white panel where content should be (worst class — media or mount failure); (b) primary text cut by the canvas or a container; (c) text unreadable against its background (especially an invented graphic / wordmark on a same-tone surface); (d) a card interior crushed against its border (<12px breathing room); (e) at an internal-seam tile (brief.internal_seams[].seam_s, a group_wN.html logical boundary): the carried .gN-* component/diagram shows a reset, duplicate ghost, or pose jump. Do not open individual frames unless a tile looks wrong.

3. Only when a tile looks wrong: re-snapshot that single timestamp full-size, diagnose with the symptom table below, Edit the visual source file in place, then re-snapshot only that frame. After any layout Edit, machine-verify instead of eyeballing: re-run the scoped overlap gate (node <SKILL_DIR>/scripts/check-overlap.mjs ... --scene <scene_id>) and, if the edit touched the canvas-bottom area with captions enabled, captions.mjs keepout --scene <scene_id>.

4. Nothing suspicious → go straight to Step 4. Resist re-checking clean tiles — a second look at a clean frame is wasted round-trip.

Symptom reference (only for diagnosing a tile that looked wrong):

Symptom	Root cause → in-place fix
Entire film blank / pure background	Bad asset path (Edit path); or sub-comp not mounted (inner data-composition-id / window.__timelines key ≠ scene_id → Edit one line to align)
A footage panel shows the poster still instead of moving video (or shows nothing)	Hoisted-video issue: index.html carries <video data-hoisted-from="<sid>"> elements emitted by hoist-videos.mjs from the scene's data-video-src declaration. Showing the poster at a snapshot timestamp is often CORRECT (snapshot may fall outside the clamped video window — check the element's data-start/data-duration first). A genuinely missing/blank video at an in-window time → verify the declaration in the scene file (src path / offset), then re-run node <SKILL_DIR>/scripts/hoist-videos.mjs --group-spec ./group_spec.json --hyperframes .; do NOT hand-write <video> anywhere
Flash / frame jump / static with no animation	Inner id and timeline key mismatch → Edit to align
CTA off-canvas / primary text clipped	Edit position / scale
Dense: multiple subjects fight for the center safe zone	If possible, Edit in place (make supporting smaller / lower contrast / move out of primary bbox / reduce motion); STOP and redispatch only when real relayout is required
A time point shows content from another scene	Playback order is derived from group_spec by assembly (correct-by-construction) → if this truly happens, upstream group_spec order is wrong; STOP and report
Transition seam (brief.transitions[].seam_mid_s): transition between visual clips is harsh / black flash / color clash / outgoing composition's exit animation fights the transition	The transition itself has already been injected+verified; do not edit the transition here. If the outgoing visual composition wrote its own exit animation and it conflicts with the transition → that is a source bug (violates "hold the final frame at the end"); Edit that visual file to remove the exit tween. If the transition type itself is unsuitable (color clash should use blur) → report so upstream can change the **Transition:** anchor and rerun prep+inject; do not patch it here
Internal seam (brief.internal_seams[].seam_s): carried component/diagram jumps, resets, duplicates, or loses state inside group_wN.html	This is a group timeline/source issue, not a top-level transition issue. Edit the corresponding group_wN.html so the shared .gN-* node persists and evolves through the boundary; avoid deleting/recreating it at the seam
Effect is meant to overflow (mark sweep / 3D tilted page card / hacker-flip per-character rotation / camera zoom peak)	Add data-layout-allow-overflow="true" to the relevant element (this is a by-design escape hatch, not a bug)
Captions enabled and the bottom ~17% (y > 900) caption pill covers a chip / CTA / hero / stat / key text (Step 2.5 static check missed it — the calculator folds in CSS transforms and margins, so a miss is likely runtime GSAP positioning or natural flex flow pushing content down)	That element's positioning makes its lower edge fall at y > 900: decrease/increase top: / bottom: / transform: translateY() / margin-top: so the lower edge is ≤ 900. After calculating and Editing, manually run captions.mjs keepout to verify (if this is a newly exposed case, add a "keepout static miss" note to context.log for maintainers to extend the script later)

Fix-direction notes for the two eye-owned classes (contrast and cramped have no machine gate — the contact-sheet scan in Step 3.2 is their only check):

• Illegibility / low contrast: move the element to a contrasting surface token, or recolor the graphic directly (FE visuals are LLM-authored — you own the paths; there is no captured asset-descriptions file to consult); the same applies to a user-provided assetCandidate image (move it to a contrasting surface — do not recolor user assets). Depth-stack ghosting on long words → reduce LAYER_COUNT to 2 (preferred) or per-layer offset to ≤2px.
• Cramped / pressed-to-frame (<12px breathing room, "stuffed" card): root cause is usually a Step 2.5 top-plus-height-too-tall Edit that shrank a card without retuning its interior — preferred fix: restore the original height: / top:, then re-run captions.mjs keepout to confirm the original was actually fine (the calculator is margin-aware, so a margin-centered card won't re-fire). Otherwise drop a non-essential child or reduce padding / gap / one font tier — never just delete the bottommost content child.

Re-application sanity rule: before applying a brief.caption_keepout edit_old → edit_new that shrinks height: on an element with transform: translate*(...) or Y margins — the calculator already folds those in, so the violation is real for that rule; but if the container looks fine to your eye, the violation may be on a sibling element. Verify the selector matches before Editing.

Step 4: Render

(cd "$PROJECT_DIR" && <npx_prefix> render --quality <quality> --output renders/video.mp4)

<quality> comes from dispatch (default high). Do not add --strict (gates have passed). On failure → inspect the last ~30 stderr lines (bad quality value? missing asset?); do not blindly retry with different flags.

Step 5: Verify mp4

(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/verify-output.mjs render --hyperframes . --group-spec ./group_spec.json)

• exit 0 → done.
• exit 1 → it reports concrete size / duration drift values. Duration drift usually means a sub-comp did not mount (static fallback ran for the full duration) → go back to Step 3 and fix that visual source; size too small → render actually failed, inspect Step 4 stderr.

Completion Report

• Brief summary: gates_clean / findings fixed in Step 2/2.5 (each: finding → fix → scoped re-verify status) / any deterministic_fixes_applied / pinned_hyperframes_version
• BGM: brief.bgm.status / brief.bgm.ready / brief.bgm.message
• Lean pass: contact-sheet tile count + verdict per suspicious tile only (clean tiles = one aggregate line, e.g. "9 tiles scanned, 8 clean")
• Visual files fixed in place: file + what changed (path / scope / downgrade / escape hatch ...)
• Any (exceptional) worker STOP redispatch + reason
• Render: path / bytes / ffprobe duration / quality
• Unresolved warnings that were allowed through

Append to <PROJECT_DIR>/context.log (generate the timestamp with the machine in UTC; do not hand-write it — avoids inconsistencies with mp4 mtime / other phase line time zones):

(cd "$PROJECT_DIR" && cat >> context.log <<EOF

## Phase 4c: finalize [done $(date -u +%Y-%m-%dT%H:%M:%SZ)]
Gates: lint <status> / validate <status> / inspect <status, strict> / overlap <status>
Lean pass: <n> contact-sheet tiles scanned (<m> escalated) — blank-panel/cut-text/contrast/cramped/internal-seams eye-checked once
Fixes in place: <scene_N/group_wN: what> ... (none if none)
BGM: <brief.bgm.status> (<brief.bgm.message>)
Render: renders/video.mp4 (<size>, <duration>s, quality=<quality>)
EOF
)