@vibeframe/cli 0.104.3 → 0.105.2

package/dist/commands/_shared/edit/fade.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module _shared/edit/fade
+ * @description `executeFade` — FFmpeg fade/afade filters for video and/or
+ * audio fade-in / fade-out. Split out of `ai-edit.ts` in v0.69 (Plan G
+ * Phase 3).
+ */
+export interface FadeOptions {
+    /** Path to the input video file */
+    videoPath: string;
+    /** Path for the output video with fade effects */
+    outputPath: string;
+    /** Fade-in duration in seconds (default: 1) */
+    fadeIn?: number;
+    /** Fade-out duration in seconds (default: 1) */
+    fadeOut?: number;
+    /** Apply fade to audio only (video copied) */
+    audioOnly?: boolean;
+    /** Apply fade to video only (audio copied) */
+    videoOnly?: boolean;
+}
+export interface FadeResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the output video */
+    outputPath?: string;
+    /** Total duration of the source video in seconds */
+    totalDuration?: number;
+    /** Whether fade-in was applied */
+    fadeInApplied?: boolean;
+    /** Whether fade-out was applied */
+    fadeOutApplied?: boolean;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Apply fade-in and/or fade-out effects to video and/or audio using FFmpeg.
+ */
+export declare function executeFade(options: FadeOptions): Promise<FadeResult>;

package/dist/commands/_shared/edit/jump-cut.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @module _shared/edit/jump-cut
+ * @description `executeJumpCut` — remove filler words from video using
+ * Whisper word-level timestamps + FFmpeg stream-copy concat. Also exports
+ * `transcribeWithWords` and `detectFillerRanges` (used by other modules
+ * via `ai-edit.ts` re-export). Split out of `ai-edit.ts` in v0.69 (Plan G
+ * Phase 3).
+ */
+/** A detected filler word with its time range. */
+export interface FillerWord {
+    /** The filler word or merged phrase */
+    word: string;
+    /** Start time in seconds */
+    start: number;
+    /** End time in seconds */
+    end: number;
+}
+/** Options for {@link executeJumpCut}. */
+export interface JumpCutOptions {
+    /** Path to the input video file */
+    videoPath: string;
+    /** Path for the output video (filler words removed) */
+    outputPath: string;
+    /** Custom filler words to detect (default: {@link DEFAULT_FILLER_WORDS}) */
+    fillers?: string[];
+    /** Padding in seconds around filler cuts (default: 0.05) */
+    padding?: number;
+    /** Language code for Whisper transcription */
+    language?: string;
+    /** If true, only analyze without producing output video */
+    analyzeOnly?: boolean;
+    /** Override OpenAI API key */
+    apiKey?: string;
+}
+/** Result from {@link executeJumpCut}. */
+export interface JumpCutResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the output video (undefined in analyze-only mode) */
+    outputPath?: string;
+    /** Total duration of the source video in seconds */
+    totalDuration?: number;
+    /** Number of filler word occurrences detected */
+    fillerCount?: number;
+    /** Total duration of filler words in seconds */
+    fillerDuration?: number;
+    /** Detected filler word ranges */
+    fillers?: FillerWord[];
+    /** Error message on failure */
+    error?: string;
+}
+/** Default set of filler words detected by jump-cut. */
+export declare const DEFAULT_FILLER_WORDS: string[];
+/**
+ * Transcribe audio with word-level timestamps using Whisper API directly.
+ * Uses timestamp_granularities[]=word for filler detection.
+ */
+export declare function transcribeWithWords(audioPath: string, apiKey: string, language?: string): Promise<{
+    words: {
+        word: string;
+        start: number;
+        end: number;
+    }[];
+    text: string;
+}>;
+/**
+ * Detect filler word ranges and merge adjacent ones within padding distance.
+ */
+export declare function detectFillerRanges(words: {
+    word: string;
+    start: number;
+    end: number;
+}[], fillers: string[], padding: number): FillerWord[];
+/**
+ * Remove filler words from a video using Whisper word-level timestamps + FFmpeg concat.
+ *
+ * Pipeline: extract audio -> Whisper transcription (word-level) -> detect fillers ->
+ * invert to keep-segments -> FFmpeg stream-copy concat.
+ */
+export declare function executeJumpCut(options: JumpCutOptions): Promise<JumpCutResult>;

package/dist/commands/_shared/edit/noise-reduce.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module _shared/edit/noise-reduce
+ * @description `executeNoiseReduce` — FFmpeg afftdn filter with optional
+ * highpass/lowpass for stronger settings. Split out of `ai-edit.ts` in
+ * v0.69 (Plan G Phase 3).
+ */
+export interface NoiseReduceOptions {
+    /** Path to the input audio or video file */
+    inputPath: string;
+    /** Path for the noise-reduced output file */
+    outputPath: string;
+    /** Reduction strength preset (default: "medium") */
+    strength?: "low" | "medium" | "high";
+    /** Custom noise floor in dB (overrides strength preset) */
+    noiseFloor?: number;
+}
+export interface NoiseReduceResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the noise-reduced output file */
+    outputPath?: string;
+    /** Duration of the input file in seconds */
+    inputDuration?: number;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Reduce audio noise in a video or audio file using FFmpeg afftdn filter.
+ *
+ * Supports three strength presets (low/medium/high) with optional highpass/lowpass
+ * for the "high" setting. Video streams are copied without re-encoding.
+ */
+export declare function executeNoiseReduce(options: NoiseReduceOptions): Promise<NoiseReduceResult>;

package/dist/commands/_shared/edit/silence-cut.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module _shared/edit/silence-cut
+ * @description `executeSilenceCut` — detect silent segments via FFmpeg
+ * `silencedetect` (default) or Gemini multimodal analysis, then trim and
+ * concatenate the non-silent segments. Split out of `ai-edit.ts` in v0.69
+ * (Plan G Phase 3).
+ */
+/** A detected silent segment within a media file. */
+export interface SilencePeriod {
+    /** Start time in seconds */
+    start: number;
+    /** End time in seconds */
+    end: number;
+    /** Duration of the silent period in seconds */
+    duration: number;
+}
+/** Options for {@link executeSilenceCut}. */
+export interface SilenceCutOptions {
+    /** Path to the input video file */
+    videoPath: string;
+    /** Path for the output video (silent segments removed) */
+    outputPath: string;
+    /** FFmpeg noise threshold in dB (default: -30) */
+    noiseThreshold?: number;
+    /** Minimum silence duration in seconds to detect (default: 0.5) */
+    minDuration?: number;
+    /** Padding in seconds kept around cuts (default: 0.1) */
+    padding?: number;
+    /** If true, only analyze without producing output video */
+    analyzeOnly?: boolean;
+    /** Use Gemini multimodal analysis instead of FFmpeg silencedetect */
+    useGemini?: boolean;
+    /** Gemini model shorthand: "flash", "flash-2.5", "pro" */
+    model?: string;
+    /** Use low-resolution mode for Gemini (longer videos) */
+    lowRes?: boolean;
+    /** Override API key (Google for Gemini mode) */
+    apiKey?: string;
+}
+/** Result from {@link executeSilenceCut}. */
+export interface SilenceCutResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the output video (undefined in analyze-only mode) */
+    outputPath?: string;
+    /** Total duration of the source video in seconds */
+    totalDuration?: number;
+    /** Detected silent periods */
+    silentPeriods?: SilencePeriod[];
+    /** Total silent duration removed in seconds */
+    silentDuration?: number;
+    /** Detection method used */
+    method?: "ffmpeg" | "gemini";
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Remove silent segments from a video using FFmpeg or Gemini detection.
+ *
+ * Detects silence via FFmpeg silencedetect (default) or Gemini multimodal
+ * analysis, then trims and concatenates the non-silent segments.
+ */
+export declare function executeSilenceCut(options: SilenceCutOptions): Promise<SilenceCutResult>;

package/dist/commands/_shared/edit/text-overlay.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module _shared/edit/text-overlay
+ * @description `applyTextOverlays` + `executeTextOverlay` — burn text onto
+ * video using FFmpeg drawtext filter. Falls back to Remotion when libfreetype
+ * is missing. Auto-detects system fonts (macOS/Linux/Windows). Split out of
+ * `ai-edit.ts` in v0.69 (Plan G Phase 3).
+ */
+/** Visual style preset for text overlays. */
+export type TextOverlayStyle = "lower-third" | "center-bold" | "subtitle" | "minimal";
+/** Options for {@link applyTextOverlays} and {@link executeTextOverlay}. */
+export interface TextOverlayOptions {
+    /** Path to the input video file */
+    videoPath: string;
+    /** Array of text lines to overlay */
+    texts: string[];
+    /** Path for the output video */
+    outputPath: string;
+    /** Text overlay style preset (default: "lower-third") */
+    style?: TextOverlayStyle;
+    /** Font size override (auto-calculated from video height if omitted) */
+    fontSize?: number;
+    /** Font color name (default: "white") */
+    fontColor?: string;
+    /** Fade in/out duration for text in seconds (default: 0.3) */
+    fadeDuration?: number;
+    /** Start time for text display in seconds (default: 0) */
+    startTime?: number;
+    /** End time for text display in seconds (default: video duration) */
+    endTime?: number;
+}
+/** Result from {@link applyTextOverlays} and {@link executeTextOverlay}. */
+export interface TextOverlayResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Absolute path to the output video */
+    outputPath?: string;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Apply text overlays to a video using FFmpeg drawtext filter.
+ *
+ * Supports multiple text lines with configurable style, position, font,
+ * and fade-in/out. Auto-detects system fonts across macOS, Linux, and Windows.
+ */
+export declare function applyTextOverlays(options: TextOverlayOptions): Promise<TextOverlayResult>;
+/**
+ * Execute text overlay for CLI/Agent usage. Delegates to {@link applyTextOverlays}.
+ */
+export declare function executeTextOverlay(options: TextOverlayOptions): Promise<TextOverlayResult>;

package/dist/commands/_shared/edit/translate-srt.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module _shared/edit/translate-srt
+ * @description `executeTranslateSrt` — translate SRT subtitle files via
+ * Claude or OpenAI in 30-segment batches. Preserves timestamps; only
+ * text content is translated. Split out of `ai-edit.ts` in v0.69 (Plan G
+ * Phase 3).
+ */
+export interface TranslateSrtOptions {
+    /** Path to the source SRT subtitle file */
+    srtPath: string;
+    /** Path for the translated SRT output */
+    outputPath: string;
+    /** Target language name (e.g. "Korean", "Spanish") */
+    targetLanguage: string;
+    /** LLM provider for translation (default: "claude") */
+    provider?: "claude" | "openai";
+    /** Source language hint (auto-detected if omitted) */
+    sourceLanguage?: string;
+    /** Override API key for the chosen provider */
+    apiKey?: string;
+}
+export interface TranslateSrtResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the translated SRT file */
+    outputPath?: string;
+    /** Number of subtitle segments translated */
+    segmentCount?: number;
+    /** Detected or specified source language */
+    sourceLanguage?: string;
+    /** Target language used for translation */
+    targetLanguage?: string;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Translate an SRT subtitle file to a target language using Claude or OpenAI.
+ * Segments are batched (~30 at a time) for efficient API usage.
+ */
+export declare function executeTranslateSrt(options: TranslateSrtOptions): Promise<TranslateSrtResult>;

package/dist/commands/_shared/edit/video-review.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module _shared/edit/video-review
+ * @description Type definitions for AI video review feedback (Gemini-
+ * powered quality analysis with auto-fix suggestions). Used by
+ * `commands/ai-review.ts`. Split out of `ai-edit.ts` in v0.69 (Plan G
+ * Phase 3).
+ */
+/** A single auto-fix proposal with optional FFmpeg filter. */
+export interface AutoFix {
+    /** Category of the fix */
+    type: "color_grade" | "text_overlay_adjust" | "speed_adjust" | "crop";
+    /** Human-readable description of the issue */
+    description: string;
+    /** FFmpeg filter string to apply the fix (if applicable) */
+    ffmpegFilter?: string;
+}
+/** Scored review for a single quality category. */
+export interface VideoReviewCategory {
+    /** Quality score from 1-10 */
+    score: number;
+    /** List of identified issues */
+    issues: string[];
+    /** Whether the issues can be auto-fixed */
+    fixable: boolean;
+    /** Suggested FFmpeg filter for fixing (color category) */
+    suggestedFilter?: string;
+    /** Improvement suggestions (text readability category) */
+    suggestions?: string[];
+}
+/** Beat-level issue returned by project-aware render review. */
+export interface VideoReviewBeatIssue {
+    beatId?: string;
+    scene?: string;
+    timeRange?: {
+        start: number;
+        end: number;
+        duration?: number;
+    };
+    severity?: "error" | "warning" | "info";
+    category?: "pacing" | "color" | "textReadability" | "audioVisualSync" | "composition";
+    message: string;
+    suggestedFix?: string;
+}
+/** Complete AI video review feedback from Gemini analysis. */
+export interface VideoReviewFeedback {
+    /** Overall quality score from 1-10 */
+    overallScore: number;
+    /** Per-category quality assessments */
+    categories: {
+        pacing: VideoReviewCategory;
+        color: VideoReviewCategory;
+        textReadability: VideoReviewCategory;
+        audioVisualSync: VideoReviewCategory;
+        composition: VideoReviewCategory;
+    };
+    /** List of auto-fixable issues with FFmpeg filter suggestions */
+    autoFixable: AutoFix[];
+    /** General improvement recommendations */
+    recommendations: string[];
+    /** Optional beat-level findings for project-aware review loops. */
+    beatIssues?: VideoReviewBeatIssue[];
+}

package/dist/commands/_shared/execute-fill-gaps.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @module _shared/execute-fill-gaps
+ * @description `executeFillGaps` — fill timeline gaps with AI-generated
+ * video (Kling image-to-video). Extracted from the 562-line `.action()`
+ * body in `commands/ai-fill-gaps.ts` in v0.69 Phase 4 finishing piece.
+ *
+ * The CLI handler in ai-fill-gaps.ts now just wires onProgress to an
+ * ora spinner and prints humanLines on completion. The manifest entry
+ * (`edit_fill_gaps`) calls this same function without onProgress and
+ * returns humanLines as the result body — same logic, dual surface.
+ */
+export interface ExecuteFillGapsOptions {
+    /** Timeline file or directory (resolved relative to cwd). */
+    projectPath: string;
+    /** Output project path. Defaults to overwriting the input. */
+    output?: string;
+    /** Directory for generated videos. Defaults to <projectDir>/footage. */
+    dir?: string;
+    /** Custom prompt for video generation. */
+    prompt?: string;
+    /** If true, only report gaps without generating. */
+    dryRun?: boolean;
+    /** Kling generation mode (std or pro). */
+    mode?: "std" | "pro";
+    /** Aspect ratio. */
+    ratio?: "16:9" | "9:16" | "1:1";
+    /** Override Kling API key. */
+    apiKey?: string;
+    /** Override ImgBB API key (used to host frames for Kling input). */
+    imgbbApiKey?: string;
+    /** Optional progress callback for streaming status updates. */
+    onProgress?: (message: string) => void;
+}
+export interface FillGapsGapReport {
+    start: number;
+    end: number;
+    duration: number;
+    /** How much of the gap can be filled by extending the previous clip. */
+    canExtendBefore: number;
+    /** How much can be filled by extending the next clip. */
+    canExtendAfter: number;
+    /** Remaining duration that needs AI generation. */
+    remainingGap: number;
+}
+export interface ExecuteFillGapsResult {
+    success: boolean;
+    /** Error message on failure. */
+    error?: string;
+    /** Human-readable status lines (CLI prints; manifest joins). */
+    humanLines: string[];
+    /** Per-gap analysis (always populated when success=true). */
+    gaps?: FillGapsGapReport[];
+    /** Gaps that need AI generation (subset of `gaps`). */
+    gapsNeedingAI?: FillGapsGapReport[];
+    /** Number of gaps actually filled (0 in dry-run / no-gaps cases). */
+    generatedCount?: number;
+    /** Final project path (input path or `options.output`). */
+    outputPath?: string;
+    /** True when no gaps were detected. */
+    noGaps?: boolean;
+    /** True when all gaps can be filled by extending adjacent clips. */
+    allExtendable?: boolean;
+    /** True when dry-run mode reported gaps without generating. */
+    dryRun?: boolean;
+}
+export declare function detectVideoGaps(videoClips: Array<{
+    startTime: number;
+    duration: number;
+}>, totalDuration: number): Array<{
+    start: number;
+    end: number;
+}>;
+export declare function analyzeGapFillability(gaps: Array<{
+    start: number;
+    end: number;
+}>, videoClips: Array<{
+    startTime: number;
+    duration: number;
+    sourceId: string;
+    sourceStartOffset: number;
+    sourceEndOffset: number;
+}>, sources: Array<{
+    id: string;
+    url: string;
+    type: string;
+    duration: number;
+}>): Array<{
+    gap: {
+        start: number;
+        end: number;
+    };
+    canExtendBefore: number;
+    canExtendAfter: number;
+    remainingGap: number;
+    gapStart: number;
+}>;
+export declare function executeFillGaps(options: ExecuteFillGapsOptions): Promise<ExecuteFillGapsResult>;

package/dist/commands/_shared/hf-skill-bundle/bundle-content.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module _shared/hf-skill-bundle/bundle-content
+ *
+ * Vendored Hyperframes skill content as TS template-literal constants.
+ * AUTO-GENERATED — regenerate via `scripts/refresh-hf-bundle.sh`. Do not
+ * hand-edit; modify the sibling .md files (audit reference) and re-run
+ * the script.
+ *
+ * Source: github.com/heygen-com/hyperframes (Apache 2.0). See `./NOTICE`
+ * for license + provenance, and `/CREDITS.md` for the relationship.
+ */
+export declare const SKILL_MD = "---\nname: hyperframes\ndescription: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.\n---\n\n# HyperFrames\n\nHTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.\n\n## Approach\n\nBefore writing HTML, think at a high level:\n\n1. **What** \u2014 what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.\n2. **Structure** \u2014 how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).\n3. **Timing** \u2014 which clips drive the duration, where do transitions land, what's the pacing.\n4. **Layout** \u2014 build the end-state first. See \"Layout Before Animation\" below.\n5. **Animate** \u2014 then add motion using the rules below.\n\nFor small edits (fix a color, adjust timing, add one element), skip straight to the rules.\n\n### Visual Identity Gate\n\n<HARD-GATE>\nBefore writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.\n\nCheck in this order:\n\n1. **DESIGN.md exists in the project?** \u2192 Read it. Use its exact colors, fonts, motion rules, and \"What NOT to Do\" constraints.\n2. **visual-style.md exists?** \u2192 Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets \u2014 different files.)\n3. **User named a style** (e.g., \"Swiss Pulse\", \"dark and techy\", \"luxury brand\")? \u2192 Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).\n4. **None of the above?** \u2192 Ask 3 questions before writing any HTML:\n   - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)\n   - Light or dark canvas?\n   - Any specific brand colors, fonts, or visual references?\n     Then generate a minimal DESIGN.md from the answers.\n\nEvery composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` \u2014 you skipped this step.\n</HARD-GATE>\n\nFor motion defaults, sizing, entrance patterns, and easing \u2014 follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.\n\n## Layout Before Animation\n\nPosition every element where it should be at its **most visible moment** \u2014 the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.\n\n**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion.\n\n### The process\n\n1. **Identify the hero frame** for each scene \u2014 the moment when the most elements are simultaneously visible. This is the layout you build.\n2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward \u2014 NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.\n3. **Add entrances with `gsap.from()`** \u2014 animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there.\n4. **Add exits with `gsap.to()`** \u2014 animate TO offscreen/invisible FROM the CSS position.\n\n### Example\n\n```css\n/* scene-content fills the scene, padding positions content */\n.scene-content {\n  display: flex;\n  flex-direction: column;\n  justify-content: center;\n  width: 100%;\n  height: 100%;\n  padding: 120px 160px;\n  gap: 24px;\n  box-sizing: border-box;\n}\n.title {\n  font-size: 120px;\n}\n.subtitle {\n  font-size: 42px;\n}\n/* Container fills any scene size (1920x1080, 1080x1920, etc).\n   Padding positions content. Flex + gap handles spacing. */\n```\n\n**WRONG \u2014 hardcoded dimensions and absolute positioning:**\n\n```css\n.scene-content {\n  position: absolute;\n  top: 200px;\n  left: 160px;\n  width: 1920px;\n  height: 1080px;\n  display: flex; /* ... */\n}\n```\n\n```js\n// Step 3: Animate INTO those positions\ntl.from(\".title\", { y: 60, opacity: 0, duration: 0.6, ease: \"power3.out\" }, 0);\ntl.from(\".subtitle\", { y: 40, opacity: 0, duration: 0.5, ease: \"power3.out\" }, 0.2);\ntl.from(\".logo\", { scale: 0.8, opacity: 0, duration: 0.4, ease: \"power2.out\" }, 0.3);\n\n// Step 4: Animate OUT from those positions\ntl.to(\".title\", { y: -40, opacity: 0, duration: 0.4, ease: \"power2.in\" }, 3);\ntl.to(\".subtitle\", { y: -30, opacity: 0, duration: 0.3, ease: \"power2.in\" }, 3.1);\ntl.to(\".logo\", { scale: 0.9, opacity: 0, duration: 0.3, ease: \"power2.in\" }, 3.2);\n```\n\n### When elements share space across time\n\nIf element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist \u2014 but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.\n\n### What counts as intentional overlap\n\nLayered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap \u2014 two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.\n\n## Data Attributes\n\n### All Clips\n\n| Attribute          | Required                          | Values                                                 |\n| ------------------ | --------------------------------- | ------------------------------------------------------ |\n| `id`               | Yes                               | Unique identifier                                      |\n| `data-start`       | Yes                               | Seconds or clip ID reference (`\"el-1\"`, `\"intro + 2\"`) |\n| `data-duration`    | Required for img/div/compositions | Seconds. Video/audio defaults to media duration.       |\n| `data-track-index` | Yes                               | Integer. Same-track clips cannot overlap.              |\n| `data-media-start` | No                                | Trim offset into source (seconds)                      |\n| `data-volume`      | No                                | 0-1 (default 1)                                        |\n\n`data-track-index` does **not** affect visual layering \u2014 use CSS `z-index`.\n\n### Composition Clips\n\n| Attribute                    | Required | Values                                       |\n| ---------------------------- | -------- | -------------------------------------------- |\n| `data-composition-id`        | Yes      | Unique composition ID                        |\n| `data-start`                 | Yes      | Start time (root composition: use `\"0\"`)     |\n| `data-duration`              | Yes      | Takes precedence over GSAP timeline duration |\n| `data-width` / `data-height` | Yes      | Pixel dimensions (1920x1080 or 1080x1920)    |\n| `data-composition-src`       | No       | Path to external HTML file                   |\n\n## Composition Structure\n\nSub-compositions loaded via `data-composition-src` use a `<template>` wrapper. **Standalone compositions (the main index.html) do NOT use `<template>`** \u2014 they put the `data-composition-id` div directly in `<body>`. Using `<template>` on a standalone file hides all content from the browser and breaks rendering.\n\nSub-composition structure:\n\n```html\n<template id=\"my-comp-template\">\n  <div data-composition-id=\"my-comp\" data-width=\"1920\" data-height=\"1080\">\n    <!-- content -->\n    <style>\n      [data-composition-id=\"my-comp\"] {\n        /* scoped styles */\n      }\n    </style>\n    <script src=\"https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js\"></script>\n    <script>\n      window.__timelines = window.__timelines || {};\n      const tl = gsap.timeline({ paused: true });\n      // tweens...\n      window.__timelines[\"my-comp\"] = tl;\n    </script>\n  </div>\n</template>\n```\n\nLoad in root: `<div id=\"el-1\" data-composition-id=\"my-comp\" data-composition-src=\"compositions/my-comp.html\" data-start=\"0\" data-duration=\"10\" data-track-index=\"1\"></div>`\n\n## Video and Audio\n\nVideo must be `muted playsinline`. Audio is always a separate `<audio>` element:\n\n```html\n<video\n  id=\"el-v\"\n  data-start=\"0\"\n  data-duration=\"30\"\n  data-track-index=\"0\"\n  src=\"video.mp4\"\n  muted\n  playsinline\n></video>\n<audio\n  id=\"el-a\"\n  data-start=\"0\"\n  data-duration=\"30\"\n  data-track-index=\"2\"\n  src=\"video.mp4\"\n  data-volume=\"1\"\n></audio>\n```\n\n## Timeline Contract\n\n- All timelines start `{ paused: true }` \u2014 the player controls playback\n- Register every timeline: `window.__timelines[\"<composition-id>\"] = tl`\n- Framework auto-nests sub-timelines \u2014 do NOT manually add them\n- Duration comes from `data-duration`, not from GSAP timeline length\n- Never create empty tweens to set duration\n\n## Rules (Non-Negotiable)\n\n**Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).\n\n**GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`.\n\n**Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously.\n\n**No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`.\n\n**Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately \u2014 no need to wait for font loading.\n\n**Never do:**\n\n1. Forget `window.__timelines` registration\n2. Use video for audio \u2014 always muted video + separate `<audio>`\n3. Nest video inside a timed div \u2014 use a non-timed wrapper\n4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`)\n5. Animate video element dimensions \u2014 animate a wrapper div\n6. Call play/pause/seek on media \u2014 framework owns playback\n7. Create a top-level container without `data-composition-id`\n8. Use `repeat: -1` on any timeline or tween \u2014 always finite repeats\n9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`)\n10. Use `gsap.set()` on clip elements from later scenes \u2014 they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead.\n11. Use `<br>` in content text \u2014 forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `<br>` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., \"THE\\nIMMORTAL\\nGAME\" at 130px).\n\n## Scene Transitions (Non-Negotiable)\n\nEvery multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.\n\n1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions.\n2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.\n3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other \"out\" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.\n4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed.\n\n**WRONG \u2014 exit animation before transition:**\n\n```js\n// BANNED \u2014 this empties the scene before the transition can use it\ntl.to(\"#s1-title\", { opacity: 0, y: -40, duration: 0.4 }, 6.5);\ntl.to(\"#s1-subtitle\", { opacity: 0, duration: 0.3 }, 6.7);\n// transition fires on empty frame\n```\n\n**RIGHT \u2014 entrance only, transition handles exit:**\n\n```js\n// Scene 1 entrance animations\ntl.from(\"#s1-title\", { y: 50, opacity: 0, duration: 0.7, ease: \"power3.out\" }, 0.3);\ntl.from(\"#s1-subtitle\", { y: 30, opacity: 0, duration: 0.5, ease: \"power2.out\" }, 0.6);\n// NO exit tweens \u2014 transition at 7.2s handles the scene change\n// Scene 2 entrance animations\ntl.from(\"#s2-heading\", { x: -40, opacity: 0, duration: 0.6, ease: \"expo.out\" }, 8.0);\n```\n\n## Animation Guardrails\n\n- Offset first animation 0.1-0.3s (not t=0)\n- Vary eases across entrance tweens \u2014 use at least 3 different eases per scene\n- Don't repeat an entrance pattern within a scene\n- Avoid full-screen linear gradients on dark backgrounds (H.264 banding \u2014 use radial or solid + localized glow)\n- 60px+ headlines, 20px+ body, 16px+ data labels for rendered video\n- `font-variant-numeric: tabular-nums` on number columns\n\nWhen no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults.\n\n## Typography and Assets\n\n- **Fonts:** Just write the `font-family` you want in CSS \u2014 the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.\n- Add `crossorigin=\"anonymous\"` to external media\n- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`\n- All files live at the project root alongside `index.html`; sub-compositions use `../`\n\n## Editing Existing Compositions\n\n- Read the full composition first \u2014 match existing fonts, colors, animation patterns\n- Only change what was requested\n- Preserve timing of unrelated clips\n\n## Output Checklist\n\n- [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass\n- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked\n- [ ] Contrast warnings addressed (see Quality Checks below)\n- [ ] Layout issues addressed (see Quality Checks below)\n- [ ] Animation choreography verified (see Quality Checks below)\n\n## Quality Checks\n\n### Visual Inspect\n\n`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`:\n\n```bash\nnpx hyperframes inspect\nnpx hyperframes inspect --json\n```\n\nFailures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy.\n\nUse `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.\n\n`hyperframes layout` is the compatibility alias for the same check.\n\n### Contrast\n\n`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:\n\n```\n\u26A0 WCAG AA contrast warnings (3):\n  \u00B7 .subtitle \"secondary text\" \u2014 2.67:1 (need 4.5:1, t=5.3s)\n```\n\nIf warnings appear:\n\n- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)\n- On light backgrounds: darken it\n- Stay within the palette family \u2014 don't invent a new color, adjust the existing one\n- Re-run `hyperframes validate` until clean\n\nUse `--no-contrast` to skip if iterating rapidly and you'll check later.\n\n### Animation Map\n\nAfter authoring animations, run the animation map to verify choreography:\n\n```bash\nnode skills/hyperframes/scripts/animation-map.mjs <composition-dir> \\\n  --out <composition-dir>/.hyperframes/anim-map\n```\n\nOutputs a single `animation-map.json` with:\n\n- **Per-tween summaries**: `\"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)\"`\n- **ASCII timeline**: Gantt chart of all tweens across the composition duration\n- **Stagger detection**: reports actual intervals (`\"3 elements stagger at 120ms\"`)\n- **Dead zones**: periods over 1s with no animation \u2014 intentional hold or missing entrance?\n- **Element lifecycles**: first/last animation time, final visibility\n- **Scene snapshots**: visible element state at 5 key timestamps\n- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)\n\nRead the JSON. Scan summaries for anything unexpected. Check every flag \u2014 fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.\n\nSkip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.\n\n---\n\n## References (loaded on demand)\n\n- **[references/captions.md](references/captions.md)** \u2014 Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.\n- **[references/tts.md](references/tts.md)** \u2014 Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.\n- **[references/audio-reactive.md](references/audio-reactive.md)** \u2014 Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.\n- **[references/css-patterns.md](references/css-patterns.md)** \u2014 CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.\n- **[references/typography.md](references/typography.md)** \u2014 Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** \u2014 every composition has text.\n- **[references/motion-principles.md](references/motion-principles.md)** \u2014 Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.\n- **[visual-styles.md](visual-styles.md)** \u2014 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.\n- **[house-style.md](house-style.md)** \u2014 Default motion, sizing, and color palettes when no style is specified.\n- **[patterns.md](patterns.md)** \u2014 PiP, title cards, slide show patterns.\n- **[data-in-motion.md](data-in-motion.md)** \u2014 Data, stats, and infographic patterns.\n- **[references/transcript-guide.md](references/transcript-guide.md)** \u2014 Transcription commands, whisper models, external APIs, troubleshooting.\n- **[references/dynamic-techniques.md](references/dynamic-techniques.md)** \u2014 Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).\n\n- **[references/transitions.md](references/transitions.md)** \u2014 Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. **Always read for multi-scene compositions** \u2014 scenes without transitions feel like jump cuts.\n  - [transitions/catalog.md](references/transitions/catalog.md) \u2014 Hard rules, scene template, and routing to per-type implementation code.\n  - Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) \u2014 read package source, not skill files.\n\nGSAP patterns and effects are in the `/gsap` skill.\n";
+export declare const HOUSE_STYLE_MD = "# House Style\n\nCreative direction for compositions when no `visual-style.md` is provided. These are starting points \u2014 override anything that doesn't serve the content.\n\n## Before Writing HTML\n\n1. **Interpret the prompt.** Generate real content. A recipe lists real ingredients. A HUD has real readouts.\n2. **Pick a palette.** Light or dark? Declare bg, fg, accent before writing code.\n3. **Pick typefaces.** Run the font discovery script in [references/typography.md](references/typography.md) \u2014 or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.\n\n## Lazy Defaults to Question\n\nThese patterns are AI design tells \u2014 the first thing every LLM reaches for. If you're about to use one, pause and ask: is this a deliberate choice for THIS content, or am I defaulting?\n\n- Gradient text (`background-clip: text` + gradient)\n- Left-edge accent stripes on cards/callouts\n- Cyan-on-dark / purple-to-blue gradients / neon accents\n- Pure `#000` or `#fff` (tint toward your accent hue instead)\n- Identical card grids (same-size cards repeated)\n- Everything centered with equal weight (lead the eye somewhere)\n- Banned fonts (see [references/typography.md](references/typography.md) for full list)\n\nIf the content genuinely calls for one of these \u2014 centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match \u2014 use it. The goal is intentionality, not avoidance.\n\n## Color\n\n- Match light/dark to content: food, wellness, kids \u2192 light. Tech, cinema, finance \u2192 dark.\n- One accent hue. Same background across all scenes.\n- Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).\n- **Contrast:** enforced by `hyperframes validate` (WCAG AA). Text must be readable with decoratives removed.\n- Declare palette up front. Don't invent colors per-element.\n\n## Background Layer\n\nEvery scene needs visual depth \u2014 persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.\n\nIdeas (mix and match, 2-5 per scene):\n\n- Radial glows (accent-tinted, low opacity, breathing scale)\n- Ghost text (theme words at 3-8% opacity, very large, slow drift)\n- Accent lines (hairline rules, subtle pulse)\n- Grain/noise overlay, geometric shapes, grid patterns\n- Thematic decoratives (orbit rings for space, vinyl grooves for music, grid lines for data)\n\nAll decoratives should have slow ambient GSAP animation \u2014 breathing, drift, pulse. Static decoratives feel dead.\n\n## Motion\n\nSee [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3\u20130.6s, vary eases, combine transforms on entrances, overlap entries.\n\n## Typography\n\nSee [references/typography.md](references/typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.\n\n## Palettes\n\nDeclare one background, one foreground, one accent before writing HTML.\n\n| Category          | Use for                                       | File                                                       |\n| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |\n| Bold / Energetic  | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md)   |\n| Warm / Editorial  | Storytelling, documentaries, case studies     | [palettes/warm-editorial.md](palettes/warm-editorial.md)   |\n| Dark / Premium    | Tech, finance, luxury, cinematic              | [palettes/dark-premium.md](palettes/dark-premium.md)       |\n| Clean / Corporate | Explainers, tutorials, presentations          | [palettes/clean-corporate.md](palettes/clean-corporate.md) |\n| Nature / Earth    | Sustainability, outdoor, organic              | [palettes/nature-earth.md](palettes/nature-earth.md)       |\n| Neon / Electric   | Gaming, tech, nightlife                       | [palettes/neon-electric.md](palettes/neon-electric.md)     |\n| Pastel / Soft     | Fashion, beauty, lifestyle, wellness          | [palettes/pastel-soft.md](palettes/pastel-soft.md)         |\n| Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](palettes/jewel-rich.md)           |\n| Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](palettes/monochrome.md)           |\n\nOr derive from OKLCH \u2014 pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.\n";
+export declare const MOTION_PRINCIPLES_MD = "# Motion Principles\n\n## Guardrails\n\nYou know these rules but you violate them. Stop.\n\n- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights \u2014 no more than 2 independent tweens with the same ease in a scene.\n- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3\u00D7 slower than the fastest. Vary duration deliberately.\n- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.\n- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.\n- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.\n- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.\n\n## What You Don't Do Without Being Told\n\n### Easing is emotion, not technique\n\nThe transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.\n\n**Direction rules \u2014 these are not optional:**\n\n- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.\n- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.\n- `.inOut` for elements moving between positions.\n\nYou get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.\n\n### Speed communicates weight\n\n- Fast (0.15-0.3s) \u2014 energy, urgency, confidence\n- Medium (0.3-0.5s) \u2014 professional, most content\n- Slow (0.5-0.8s) \u2014 gravity, luxury, contemplation\n- Very slow (0.8-2.0s) \u2014 cinematic, emotional, atmospheric\n\n### Scene structure: build / breathe / resolve\n\nEvery scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.\n\n- **Build (0-30%)** \u2014 elements enter, staggered. Don't dump everything at once.\n- **Breathe (30-70%)** \u2014 content visible, alive with ONE ambient motion.\n- **Resolve (70-100%)** \u2014 exit or decisive end. Exits are faster than entrances.\n\n### Transitions are meaning\n\n- **Crossfade** = \"this continues\"\n- **Hard cut** = \"wake up\" / disruption\n- **Slow dissolve** = \"drift with me\"\n\nYou crossfade everything. Use hard cuts for disruption and register shifts.\n\n### Choreography is hierarchy\n\nThe element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion \u2014 overlap entries. Total stagger sequence under 500ms regardless of item count.\n\n### Asymmetry\n\nEntrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.\n\n## Visual Composition\n\nYou build for the web. Video frames are not pages.\n\n- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.\n- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.\n- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).\n- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as \"nothing loaded.\"\n- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.\n- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.\n- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).\n";
+export declare const TYPOGRAPHY_MD = "# Typography\n\nThe compiler embeds supported fonts \u2014 just write `font-family` in CSS.\n\n## Banned\n\nTraining-data defaults that every LLM reaches for. These produce monoculture across compositions.\n\nInter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata, Syne\n\n**Syne in particular** is the most overused \"distinctive\" display font. It is an instant AI design tell.\n\n## Guardrails\n\nYou know these rules but you violate them. Stop.\n\n- **Don't pair two sans-serifs.** You do this constantly \u2014 one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.\n- **One expressive font per scene.** You pick two interesting fonts trying to make it \"better.\" One performs, one recedes.\n- **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.\n- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.\n\n## What You Don't Do Without Being Told\n\n- **Tension should mean something.** Don't pattern-match pairings. Ask WHY these two fonts disagree. The pairing should embody the content's contradiction \u2014 mechanical vs human, public vs private, institutional vs personal. If you can't articulate the tension, it's arbitrary.\n- **Register switching.** Assign different fonts to different communicative modes \u2014 one voice for statements, another for data, another for attribution. Not hierarchy on a page. Voices in a conversation.\n- **Tension can live inside a single font.** A font that looks familiar but is secretly strange creates tension with the viewer's expectations, not with another font.\n- **One variable changed = dramatic contrast.** Same letterforms, monospaced vs proportional. Same family at different optical sizes. Changing only rhythm while everything else stays constant.\n- **Double personality works.** Two expressive fonts can coexist if they share an attitude (both irreverent, both precise) even when their forms are completely different.\n- **Time is hierarchy.** The first element to appear is the most important. In video, sequence replaces position.\n- **Motion is typography.** How a word enters carries as much meaning as the font. A 0.1s slam vs a 2s fade \u2014 same font, completely different message.\n- **Fixed reading time.** 3 seconds on screen = must be readable in 2. Fewer words, larger type.\n- **Tracking tighter than web.** -0.03em to -0.05em on display sizes. Video encoding compresses letter detail.\n\n## Finding Fonts\n\nDon't default to what you know. If the content is luxury, a grotesque sans might create more tension than the expected Didone serif. Decide the register first, then search.\n\nSave this script to `/tmp/fontquery.py` and run with `curl -s 'https://fonts.google.com/metadata/fonts' > /tmp/gfonts.json && python3 /tmp/fontquery.py /tmp/gfonts.json`:\n\n```python\nimport json, sys, random\nfrom collections import OrderedDict\n\nrandom.seed()  # true random each run\n\nwith open(sys.argv[1]) as f:\n    data = json.load(f)\nfonts = data.get(\"familyMetadataList\", [])\n\nban = {\"Inter\",\"Roboto\",\"Open Sans\",\"Noto Sans\",\"Lato\",\"Poppins\",\"Source Sans 3\",\n       \"PT Sans\",\"Nunito\",\"Outfit\",\"Sora\",\"Playfair Display\",\"Cormorant Garamond\",\n       \"Bodoni Moda\",\"EB Garamond\",\"Cinzel\",\"Prata\",\"Arimo\",\"Source Sans Pro\",\"Syne\"}\nskip_pfx = (\"Roboto\",\"Noto \",\"Google Sans\",\"Bpmf\",\"Playwrite\",\"Anek\",\"BIZ \",\n            \"Nanum\",\"Shippori\",\"Sawarabi\",\"Zen \",\"Kaisei\",\"Kiwi \",\"Yuji \",\"Radio \")\n\ndef ok(f):\n    if f[\"family\"] in ban: return False\n    if any(f[\"family\"].startswith(b) for b in skip_pfx): return False\n    if \"latin\" not in (f.get(\"subsets\") or []): return False\n    return True\n\nseen = set()\nR = OrderedDict()\n\n# Trending Sans \u2014 recent (2022+), popular (<300)\nR[\"Trending Sans\"] = []\nfor f in fonts:\n    if not ok(f) or f[\"family\"] in seen: continue\n    if f.get(\"category\") in (\"Sans Serif\",\"Display\") and f.get(\"dateAdded\",\"\") >= \"2022-01-01\" and f.get(\"popularity\",9999) < 300:\n        R[\"Trending Sans\"].append(f); seen.add(f[\"family\"])\n\n# Trending Serif \u2014 recent (2018+), popular (<600)\nR[\"Trending Serif\"] = []\nfor f in fonts:\n    if not ok(f) or f[\"family\"] in seen: continue\n    if f.get(\"category\") == \"Serif\" and f.get(\"dateAdded\",\"\") >= \"2018-01-01\" and f.get(\"popularity\",9999) < 600:\n        R[\"Trending Serif\"].append(f); seen.add(f[\"family\"])\n\n# Monospace \u2014 recent (2018+), popular (<600)\nR[\"Monospace\"] = []\nfor f in fonts:\n    if not ok(f) or f[\"family\"] in seen: continue\n    if f.get(\"category\") == \"Monospace\" and f.get(\"dateAdded\",\"\") >= \"2018-01-01\" and f.get(\"popularity\",9999) < 600:\n        R[\"Monospace\"].append(f); seen.add(f[\"family\"])\n\n# Impact & Condensed \u2014 heavy display fonts with 800+ weight\nR[\"Impact & Condensed\"] = []\nfor f in fonts:\n    if not ok(f) or f[\"family\"] in seen: continue\n    has_heavy = any(k in list(f.get(\"fonts\",{}).keys()) for k in (\"800\",\"900\"))\n    is_display = f.get(\"category\") in (\"Sans Serif\",\"Display\")\n    if has_heavy and is_display and f.get(\"popularity\",9999) < 400:\n        R[\"Impact & Condensed\"].append(f); seen.add(f[\"family\"])\n\n# Script & Handwriting \u2014 popular (<300)\nR[\"Script & Handwriting\"] = []\nfor f in fonts:\n    if not ok(f) or f[\"family\"] in seen: continue\n    if f.get(\"category\") == \"Handwriting\" and f.get(\"popularity\",9999) < 300:\n        R[\"Script & Handwriting\"].append(f); seen.add(f[\"family\"])\n\n\n# Randomize the top 5 in each category so the LLM doesn't always pick the same first result\nfor cat in R:\n    R[cat].sort(key=lambda x: x.get(\"popularity\",9999))\n    top5 = R[cat][:5]\n    rest = R[cat][5:]\n    random.shuffle(top5)\n    R[cat] = top5 + rest\nlimits = {\"Trending Sans\":15,\"Trending Serif\":12,\"Monospace\":8,\n          \"Impact & Condensed\":12,\"Script & Handwriting\":10}\nfor cat in R:\n    items = R[cat][:limits.get(cat,10)]\n    if not items: continue\n    print(f\"--- {cat} ({len(items)}) ---\")\n    for ff in items:\n        var = \"VAR\" if ff.get(\"axes\") else \"   \"\n        print(f'  {ff.get(\"popularity\"):4d} | {var} | {ff[\"family\"]}')\n    print()\n```\n\nFive categories: trending sans, trending serif, monospace, impact/condensed, script/handwriting. All dynamically filtered from Google Fonts metadata \u2014 no hardcoded font names. Cross classification boundaries when pairing.\n\n## Selection Thinking\n\nDon't pick fonts by category reflex (editorial \u2192 serif, tech \u2192 mono, modern \u2192 geometric sans). That's pattern matching, not design.\n\n1. **Name the register.** What voice is the content speaking in? Institutional authority? Personal confession? Technical precision? Casual irreverence? The register narrows the field more than the category.\n2. **Think physically.** Imagine the font as a physical object the brand could ship \u2014 a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label inside a coat, a children's book printed on cheap newsprint, a tax form. Whichever physical object fits the register is pointing at the right _kind_ of typeface.\n3. **Reject your first instinct.** The first font that feels right is usually your training-data default for that register. If you picked it last time too, find something else.\n4. **Cross-check the assumption.** An editorial brief does NOT need a serif. A technical brief does NOT need a sans. A children's product does NOT need a rounded display font. The most distinctive choice often contradicts the category expectation.\n\n## Similar-Font Pairing\n\nNever pair two fonts that are similar but not identical \u2014 two geometric sans-serifs, two transitional serifs, two humanist sans. They create visual friction without clear hierarchy. The viewer senses something is \"off\" but can't articulate it. Either use one font at two weights, or pair fonts that contrast on multiple axes: serif + sans, condensed + wide, geometric + humanist.\n\n## Dark Backgrounds\n\nLight text on dark backgrounds creates two optical illusions you need to compensate for:\n\n- **Increased apparent weight.** Light-on-dark reads heavier than dark-on-light at the same `font-weight`. Use 350 instead of 400 for body text. Headlines are less affected because size compensates.\n- **Tighter apparent spacing.** Light halos around letterforms reduce perceived gaps. Increase `line-height` by 0.05-0.1 beyond your light-background value. For display sizes, add 0.01em `letter-spacing` to counteract.\n\n## OpenType Features for Data\n\nMost fonts ship with OpenType features that are off by default. Turn them on for data compositions:\n\n```css\n/* Tabular numbers \u2014 digits align vertically in columns */\n.stat-value,\n.timer,\n.data-column {\n  font-variant-numeric: tabular-nums;\n}\n\n/* Diagonal fractions \u2014 renders 1/2 as \u00BD */\n.recipe-amount,\n.ratio {\n  font-variant-numeric: diagonal-fractions;\n}\n\n/* Small caps for abbreviations \u2014 less visual shouting */\n.abbreviation,\n.unit {\n  font-variant-caps: all-small-caps;\n}\n\n/* Disable ligatures in code \u2014 fi, fl, ffi should stay separate */\ncode,\n.code {\n  font-variant-ligatures: none;\n}\n```\n\n`tabular-nums` is essential any time numbers are stacked vertically \u2014 stat callouts, timers, scoreboards, data tables. Without it, digits have proportional widths and columns don't align.\n";
+export declare const TRANSITIONS_MD = "# Scene Transitions\n\nA transition tells the viewer how two scenes relate. A crossfade says \"this continues.\" A push slide says \"next point.\" A blur crossfade says \"drift with me.\" Choose transitions that match what the content is doing emotionally, not just technically.\n\n## Animation Rules for Multi-Scene Compositions\n\nThese are non-negotiable for every multi-scene composition:\n\n1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.\n2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` \u2014 opacity, position, scale, etc. No scene should pop fully-formed onto screen.\n3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts \u2014 the transition handles the visual handoff.\n4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.\n\n## Energy \u2192 Primary Transition\n\n| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |\n| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |\n| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |\n| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |\n| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |\n\nPick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.\n\n## Mood \u2192 Transition Type\n\nThink about what the transition _communicates_, not just what it looks like.\n\n| Mood                     | Transitions                                                                                                                          | Why it works                                                                                |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |\n| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn \u00B7 **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |\n| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve \u00B7 **Shader:** gravitational lens                                                   | Content transforms mechanically \u2014 compressed, shrunk, sliced, gridded.                      |\n| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter \u00B7 **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |\n| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration \u00B7 **Shader:** glitch, chromatic split                                  | Grid dissolve is the core \"data\" transition. Shader glitch adds posterization + scan lines. |\n| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple \u00B7 **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |\n| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe \u00B7 **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |\n| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black \u00B7 **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |\n| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black \u00B7 **Shader:** cross-warp morph, thermal distortion                                    | Restraint. Cross-warp morph flows both scenes into each other organically.                  |\n| **Retro / analog**       | Film burn, light leak, VHS, clock wipe \u00B7 **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |\n\n## Narrative Position\n\n| Position                   | Use                                                                        | Why                                                   |\n| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |\n| **Opening**                | Your most distinctive transition. Match the mood. 0.4-0.6s                 | Sets the visual language for the entire piece.        |\n| **Between related points** | Your primary transition. Consistent. 0.3s                                  | Don't distract \u2014 the content is continuing.           |\n| **Topic change**           | Something different from your primary. Staggered blocks, shutter, squeeze. | Signals \"new section\" \u2014 the viewer's brain resets.    |\n| **Climax / hero reveal**   | Your boldest accent. Fastest or most dramatic.                             | This is the payoff \u2014 spend your best transition here. |\n| **Wind-down**              | Return to gentle. Blur crossfade, crossfade. 0.5-0.7s                      | Let the viewer exhale after the climax.               |\n| **Outro**                  | Slowest, simplest. Crossfade, color dip to black. 0.6-1.0s                 | Closure. Don't introduce new energy at the end.       |\n\n## Blur Intensity by Energy\n\n| Energy     | Blur    | Duration | Hold at peak |\n| ---------- | ------- | -------- | ------------ |\n| **Calm**   | 20-30px | 0.8-1.2s | 0.3-0.5s     |\n| **Medium** | 8-15px  | 0.4-0.6s | 0.1-0.2s     |\n| **High**   | 3-6px   | 0.2-0.3s | 0s           |\n\n## Presets\n\n| Preset     | Duration | Easing            |\n| ---------- | -------- | ----------------- |\n| `snappy`   | 0.2s     | `power4.inOut`    |\n| `smooth`   | 0.4s     | `power2.inOut`    |\n| `gentle`   | 0.6s     | `sine.inOut`      |\n| `dramatic` | 0.5s     | `power3.in` \u2192 out |\n| `instant`  | 0.15s    | `expo.inOut`      |\n| `luxe`     | 0.7s     | `power1.inOut`    |\n\n## Implementation\n\nRead [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.\n\n| Category    | CSS                                                            | Shader (WebGL)                                                            |\n| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |\n| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |\n| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |\n| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |\n| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | \u2014                                                                         |\n| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |\n| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |\n| Pattern     | Grid dissolve, morph circle                                    | \u2014                                                                         |\n\n## Transitions That Don't Work in CSS\n\nAvoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.\n\n## CSS vs Shader\n\nCSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas \u2014 they can warp, dissolve, and morph in ways CSS cannot.\n\n**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package \u2014 import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.\n\nWhen a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.\n\n## Shader-Compatible CSS Rules\n\nShader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:\n\n1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.\n2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.\n3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.\n4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.\n5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.\n6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.\n\nThese rules only apply to shader transition compositions. CSS-only compositions have no restrictions.\n\n## Visual Pattern Warning\n\nAvoid transitions that create visible repeating geometric patterns \u2014 grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.\n";