nateherkai/hyperframes-student-kit

HyperFrames Video Beats

Use this skill to turn a talking-head video plus transcript into a paced set of motion graphics that support the narration without covering the speaker unnecessarily.

Core Goal

Keep the viewer oriented and engaged. Every beat must answer one of these:

• What should the viewer remember?
• What concept needs visual structure?
• What stat, contrast, or pivot deserves emphasis?
• Where is the pacing getting quiet enough that the viewer may drift?

Do not add graphics just because a gap exists. Add graphics because the narration has a topic, transition, proof point, or mental model that benefits from visual support.

First Pass

1. Read project instructions (AGENTS.md, local skill docs, and project-specific notes).
2. Inspect the root composition, current beat schedule, shared CSS, and transcript.
3. Build a coverage map from the root data-start / data-duration entries or the master SHOW array.
4. Extract transcript chunks for any requested region and any uncovered gaps.
5. Identify topic spans by narration, not by arbitrary timestamps.
6. Decide whether each topic needs a full-screen paper beat, a lower-third glass card, or no new beat.

Use fast local commands. Prefer rg, Select-String, and small Node/PowerShell transcript scripts.

Beat Type Decision

Use Full-Screen Crumpled Paper

Use a paper takeover when the narration reaches a major thesis, list, section marker, quote, or stat that should briefly become the whole frame.

Good uses:

• Hook payoff or "in this video" overview
• Major section transition
• Big stat or study result
• Memorable thesis line
• Short quote or mantra
• Contrast that needs the audience to stop and look

Rules:

• Keep it short, usually 4-12 seconds.
• Use sparse black text.
• Let only true stat numbers or one extremely important word use accent color.
• Do not cover long explanations with paper takeovers.
• Do not make full-screen text playful, huge, or over-bold by default.

Use Glassmorphism Lower Third

Use a glass lower-third when the speaker should remain visible and the graphic should support the current idea.

Good uses:

• Explanation scaffolds
• Topic labels
• Equation-style mental models
• Small lists
• "What this means" translations
• Pacing fills during long talking-head stretches
• Follow-up cards after a shortened full-screen or split-screen beat

Rules:

• Keep lower thirds in the lower third or lower half.
• Avoid covering the face.
• Use concise text: one headline plus optional short subline, or a 2-4 item list.
• Prefer one card per topic span over many tiny flashes.
• Preserve the existing glass-card style unless the user asks for a design change.

Pacing Heuristics

For long-form YouTube talking-head videos:

• Early video: avoid more than 20-30 seconds without a visual beat.
• Main body: avoid more than 30-45 seconds without a beat.
• Dense explanation sections: use lower thirds roughly every topic span, not every sentence.
• Big paper takeovers should be occasional punctuation, not the default.
• If an existing beat was manually shortened because it felt too long, respect that choice and fill after it with a new shorter card.

When scanning a schedule, report true gaps from the visibility schedule, not just the DOM order. If the root timeline uses a SHOW array, that is usually the authoritative visible range.

Timing Method

Time every beat to the transcript topic:

1. Find the first word or phrase where the topic starts.
2. Start the beat 0.2-0.6 seconds before that anchor when possible.
3. Keep the beat visible until the topic ends or naturally hands off.
4. If the next beat begins immediately, clear 0.1-0.5 seconds before it unless the handoff is intentional.
5. Match sub-element entrances to spoken phrases.

Avoid this failure mode:

• Card appears on the right topic but only lasts 5-8 seconds while the speaker keeps discussing the topic for 20-40 seconds.

Prefer:

• One card lives across the whole topic, with a subline or list item building midway through if the narration evolves.

Content Writing

Write for glance comprehension. The viewer should understand the card in under one second.

Use:

• Short noun phrases
• Direct labels
• One mental model per card
• Numbers only when they are meaningful
• Verbs when they clarify the action

Avoid:

• Repeating the whole voiceover
• Long sentences
• Vague hype language
• Too many highlighted words
• Explaining how to use the video inside the graphic

Good patterns:

The bottleneck
Not enough AI inside real workflows.
The problem is adoption, not raw talent.

The bridge
Skills + Workflows = 40 hrs saved

In this video
-> The study
-> The stats
-> The paths you can take
-> What actually matters

Visual Style Rules

Follow the local design system first. For this project family, use:

• Serious professional typography.
• Black primary text on paper beats.
• Accent blue only for major stat numbers or rare power words.
• Glass cards with the existing dark frosted style.
• Lower-third cards that do not cover the speaker's face.

For paper beats:

• Use black for kickers, labels, arrows, sources, quotes, and supporting text.
• Keep font weight restrained.
• Avoid oversized playful type unless the user explicitly asks for it.
• Make the crumpled-paper motion deterministic.

For glass cards:

• Reuse .glass-card dim lower-third or the closest existing class.
• Prefer bottom-center placement.
• Keep cards compact.
• Use equation/list helpers when the idea is structural.

HyperFrames Implementation Rules

Follow project AGENTS.md and HyperFrames lint rules:

• Every mounted timed element needs data-start, data-duration, and data-track-index.
• Visible timed root-mounted elements should have the expected clip/layer class used by the project.
• Sub-compositions should register a paused GSAP timeline on window.__timelines.
• Pin each sub-composition timeline with tl.set({}, {}, SLOT);.
• Keep deterministic logic only.
• Do not animate video element dimensions or media properties in ways that can freeze renders.
• Run npx hyperframes lint after editing HTML.

When adding a beat:

1. Create compositions/beats/NNN-short-name.html.
2. Add the root mount in index.html.
3. Add or update the master visibility schedule if one exists.
4. Make the sub-composition SLOT match the mounted duration.
5. Verify no same-track overlaps unless the project intentionally uses multiple overlay tracks.

Coverage Scan

After edits, scan the master schedule:

• List beats sorted by visible start.
• Print gaps over the target threshold.
• Add or retime beats only where the transcript has a supportable concept.

For this project pattern, use 30 seconds as the strict scan threshold and 45 seconds as the maximum acceptable main-body threshold.

Validation

Before finishing:

1. Run the HyperFrames linter.
2. Fix all errors.
3. Mention warnings separately if they are known and non-blocking.
4. If the user asked for render-ready output, render or smoke-render as appropriate.
5. Give the user exact file paths and timestamps changed.

Practical Defaults

Use these defaults unless project context says otherwise:

• Full-screen paper overview: 8-10 seconds.
• Full-screen paper stat: 5-8 seconds.
• Glass lower-third explanation: 12-30 seconds.
• Long topic glass card: 25-45 seconds with staggered sub-elements.
• Beat start lead-in: 0.2-0.6 seconds.
• Gap scan threshold: 30 seconds.
• Lower-third width: about 68-72vw, max about 1240-1280px.

What To Preserve

Preserve user taste decisions discovered during review:

• If the user says a beat is too long, do not restore it just to satisfy a generic coverage rule.
• If glass card style is approved, reuse it instead of redesigning it.
• If typography is approved, keep it stable and adjust only local sizing/weight.
• If the speaker's face is important, prefer lower-third cards over center-screen cards.