Plain-Sight Explainer Video

Plain-Sight Explainer (Gateway Workflow)

Build against the HyperFrames composition contract (clips, data-* timing, and the #root schema). Install the upstream HyperFrames skills with npx skills add heygen-com/hyperframes, or scaffold with npx hyperframes init, and read the generated project documentation first.

Make a 60–90s explainer about something the viewer sees daily but has never looked at. The film manufactures recognition first, then pays it off with a causal history. Grammar measured from Vox's Cooper Black film; motion from the same frame-by-frame calibration process.

This is a Vox-inspired design vocabulary, not an affiliation or endorsement. Do not use Vox logos or imply that Vox produced the result.

Trust boundary and requirements

• Require Node.js 22 or newer for the bundled seam scripts. When they start a preview server, npx may download the exact HyperFrames version pinned in scripts/seam-gate.mjs from the npm registry.
• Read only the files and URLs the user supplies. Source mode may fetch public citations and public-domain or openly licensed assets from declared sources. Never send private documents, credentials, or private URLs to another service.
• Ask before using any TTS or transcription API. State the provider, data sent, required credential, and possible cost before the call.
• Write project source, downloaded assets, audio, contact sheets, and renders only inside the user's chosen project directory. Do not publish or upload the result automatically.
• The seam verifier starts a local preview server and an isolated Chrome profile. Its --url and --comp-url inputs accept localhost only. A preview may still load remote assets declared by the user's composition.

Reference map

Read only the references needed for the current stage:

• Topic selection: plain-sight-topics.md
• Script and captions: plain-sight-script.md
• Layout and assets: vox-collage-layout.md
• Text and highlights: vox-text-overlays.md
• Collage motion: vox-collage-motion.md
• Motion law and seam gate: motion-continuity.md
• Transition catalog and code: velocity-matched-transitions.md and velocity-matched-transitions-gsap.md
• Multi-stage element motion: animation-overlap.md
• Render-safe seam mechanics: render-safe-seams.md
• Seam ledger and script usage: seam-gate.md

Pipeline (run in order; each gate blocks the next)

1. Entry router — two modes, one gate. Read plain-sight-topics.md.

   • Topic mode (the user names a subject, or asks for ideas): the four-part filter governs IDEATION and tie-breaking only. If a user-chosen topic fails it, name which part fails and what the film loses, offer passing alternatives — then build the film they asked for if they confirm. The filter never refuses a chosen subject.
   • Source mode (the user supplies material — documents: a memo, strategy doc, report, paper, deck, transcript, PDF, or a folder of them; or links: an article, docs page, repo, announcement): the filter does not apply at all. After confirming the allowed network scope, read every supplied file, fetch every supplied URL, and follow at most one public citation hop when needed for a claim. When a citation is dead or truncated (common in exported PDFs), do not guess the source — verify the claim independently on the open web before it becomes a receipt, or cut it. Then run the storyline mine. Person+date and PD-archive requirements are waived; the mechanism beat is not. The audience is the source's INTENDED audience, not "any viewer" — the FAMILIAR beat calibrates to what they see daily. The VO never mentions the source — see plain-sight-script.md.

   The storyline mine (source mode). The source is ore, not an outline — never film it section by section. Extract five things:

   • The on-ramp — the recognition the intended audience already has, in the source's own world (a habit, a number they see weekly, a thing on their screen right now).
   • The tension — the sharpest claim in the source that contradicts what that audience assumes.
   • The turn — the DIG's landing point: a person+date when the source has one, otherwise the decision, number, or moment the story pivots on.
   • The mechanism — the one claim the viewer can verify on screen unaided. If the source only asserts, BUILD the demonstration (two-panel compare, dots redistributed two ways, before/after at equal scale).
   • The receipts — real artifacts from the source plus the open web (charts, screenshots, filings, on-screen attributed quotes). Real-assets rule still holds.

   Map those onto the structural spine; beats the source can't fill honestly get cut, not faked. Multiple sources — or ONE source carrying several candidate storylines — mine each, then pick ONE spine: a film gets one storyline; everything else demotes to receipts. Deliver the beat map for approval before drafting script.

2. Script — read plain-sight-script.md. Draft VO + beat map. GATE: every line passes the deletion test; opener/closer rules hold. If ghost-writing for a specific person, their voice skill outranks this one.

3. Design pass — read vox-collage-layout.md. Build a contact sheet (one frame per beat, 960×540 tiles, HTML → headless-Chrome screenshot) from REAL assets. Deliver the sheet BEFORE building any comp. Iterate here — it is 10x cheaper than comp notes.

   LOOK GATE — check before delivering the sheet. Use this collage grammar without implying Vox affiliation. Verify, don't assume:

   • Palette is the measured set — ink #1a1a1a, yellow #FFE619, process blue #66CFFF, specimen blue #58BCEC, greys #F2F2F2 / #8d9399, ground #fbfaf8. Treat bright blues as fills and accents. Use #3E87A8 or darker for small text on white, and pass the renderer's contrast checks.
   • Headlines are Archivo Black.
   • Every frame is a named recipe from the layout reference (evidence stack, zoom-isolation, two-panel compare, specimen grid, lower-third, newsprint layering, circle reveal). Label each frame with its recipe on the sheet.
   • The yellow circle appears as the recurring visual carrier.

   The trap: when the source document belongs to a company with its own design system — or the project folder already holds a brand capture, frame.md, or an earlier build in that brand — the pull is to inherit those tokens. Do not. brand-faithful is a DIFFERENT workflow for product-launch films. A brand skin here is an explicit user decision, never a default. Ask; don't substitute.

4. VO — record or TTS. The TTS input file is a PRONUNCIATION script: numbers written out ("eighteen thirty-nine"), names spelled as spoken. Transcribe the result for word timestamps — audio is the clock; every cut, pop, and highlight keys to a word time. A replacement VO = a full retime. Captions transcribe the PERFORMED read verbatim, not the script doc. TTS playbook: npx hyperframes tts first; if its bundled speech stack fails (old Python, espeakng-loader abort), install espeak-ng and call the Kokoro model directly with the CLI's cached model files. Use a TTS API only after the user approves its provider, data sharing, credentials, and cost. Then transcribe whatever produced the audio; the timestamps are the clock regardless of the engine.

5. Build — one HyperFrames comp, one clip group per beat, quiet caption rail (suppress cues wherever promoted on-screen text carries the words). Read vox-text-overlays.md and vox-collage-motion.md before writing timelines.

6. QC gates (all numeric, all mandatory)

   • lint/check: 0 errors.
   • Dead-time sweep: MAD every consecutive frame pair of the RENDER; any still run >3s is a planning bug — add a staged reveal, not wobble.
   • Seam measurement: for any zoom-isolation cut, render the last pre-swap and first post-swap frames, detect the carrier in both, verify centers within ~30px and sizes within ~10%. Fix by measuring, not eyeballing.
   • Event-density: per beat, largest gap between authored timeline events ≤3.0s (the motion reference explains why the MAD sweep cannot see creep-only holds).
   • Composition integrity: audit the final keyframe sheet against the layout reference's hard rules, item by item, logged.
   • Keyframe sheet: screenshot one frame per beat; look at it.