Add Remotion-based video generation for Goldfish intro

[lukacf]

Summary

This PR introduces a complete video production system for Goldfish using Remotion, a React-based video framework. The implementation includes a reusable, tool-agnostic terminal simulator component that can generate realistic TUI demos for any command-line tool, along with a full 60-second intro video composition showcasing Goldfish's capabilities.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

What's Included

Core Terminal Simulator (src/terminal/)

A production-ready terminal component with:

• Theme system: Swap visual identity (colors, fonts, prompts) without changing component code
• Script engine: Declarative event-based playback (typing, spinners, output, pauses)
• Playback hook: Frame-accurate state computation for smooth animations
• Chrome: macOS-style window with traffic lights and title bar

Supports simulating any TUI tool (Claude Code, Codex CLI, Cursor, Aider, etc.) by providing theme + script combinations.

Video Composition (src/GoldfishIntro.tsx)

A 60-second intro video with five scenes:

1. Title (5s): Goldfish branding with spring animation
2. Problem (9s): Pain points of traditional ML workflows
3. Terminal Demo (36s): Claude Code + Goldfish MCP integration showcase
4. Benefits (7s): Key value propositions with staggered animations
5. Closing (3s): Call-to-action

Configuration & Scripts

• config/video.ts: Global video settings (FPS, dimensions, scene durations)
• config/scripts.ts: Terminal demo scripts with helper functions for readability
• remotion.config.ts: Remotion CLI configuration

Reusable Components

• AnimatedText: Fade-in + slide-up text animations
• SceneFade: Scene-level fade-in/fade-out wrapper
• Scene components: Fully composable and customizable

How to Use

cd video
npm install

# Interactive preview
npm run studio

# Render to MP4
npm run render
# Output: out/goldfish-intro.mp4

Creating Variants

The architecture is designed for easy customization:

1. Change terminal content: Edit src/config/scripts.ts
2. Swap themes: Use codexCliTheme or create a new theme in src/terminal/themes.ts
3. Create new compositions: Duplicate GoldfishIntro.tsx, modify scenes, register in Root.tsx
4. Adjust timing: Edit SCENE_DURATIONS in src/config/video.ts

See README.md for detailed examples.

Architecture Highlights

• Separation of concerns: Themes control appearance, scripts control content
• Frame-accurate playback: All animations use Remotion's frame-based timing
• Type-safe: Full TypeScript support with comprehensive interfaces
• Extensible: Easy to add new script event types, themes, or scenes
• Production-ready: Includes proper error handling, performance optimization, and documentation

Testing

The video can be previewed in real-time using Remotion Studio (npm run studio), which provides:

• Interactive timeline scrubbing
• Frame-by-frame inspection
• Live editing of composition props
• Instant preview of changes

Rendered output has been validated for:

• Smooth animations and transitions
• Correct timing and synchronization
• Visual fidelity and color accuracy
• Terminal simulation realism

Related Issues

This enables video marketing content for Goldfish and provides a foundation for creating multiple video variants (short-form, tool-specific, etc.) without duplicating code.

https://claude.ai/code/session_012VucUymxvzNCLkzoonqCdr

[claude]

Code Review: Remotion Video Production System

Executive Summary

This PR introduces a well-architected video production system for Goldfish marketing content. The code demonstrates strong TypeScript/React practices with a reusable, extensible terminal simulator. Overall assessment: APPROVE with minor recommendations.

---

Strengths ✅

1. Architecture & Design

• Excellent separation of concerns: Theme system allows swapping visual identity without touching component logic
• Clean abstractions: useTerminalPlayback hook is pure, testable, and frame-accurate
• Type-first approach: All interfaces defined in types.ts before implementation
• Composable scenes: Easy to create variants or new compositions

2. TypeScript Quality

• Strict mode enabled ("strict": true)
• Discriminated unions for ScriptEvent types
• Proper React.FC typing throughout
• Good use of as const for configuration objects

3. Performance

• Efficient memoization: Timeline pre-computed once, state recomputed only on frame changes
• O(n) complexity: Where n = number of script events (typically 20-30), acceptable for video generation
• Frame-based rendering optimized for Remotion's needs

---

Issues & Recommendations

🔴 HIGH Priority

1. Missing Exhaustiveness Checks in Switch Statements

Location: src/terminal/useTerminalPlayback.ts lines 26-27, 84-158

Problem: If a new ScriptEvent type is added, TypeScript won't catch missing cases.

Current Code:

default:
  return 0;  // Silent failure

Recommended Fix:

default:
  const _exhaustive: never = event;
  return _exhaustive;  // TypeScript error if case missing

This pattern ensures compile-time safety when extending the event system.

---

🟡 MEDIUM Priority

2. React Keys Using Array Indices (Anti-pattern)

Location: src/terminal/TerminalContent.tsx lines 31-32, 81-82

Problem:

{state.lines.map((line, i) => (
  <LineRenderer key={i} line={line} theme={theme} />
))}

Using array indices as keys can cause issues when:

• Terminal clears (lines.length = 0)
• Rapid frame-to-frame changes occur
• Cursor blink state persists across different lines

Impact: Visual inconsistencies, cursor rendering artifacts.

Recommended Fix:

// Generate stable keys from line content
const lineKey = `${i}-${line.spans.map(s => s.text).join('')}`;
{state.lines.map((line, i) => (
  <LineRenderer key={lineKey} line={line} theme={theme} />
))}

3. Missing Accessibility Attributes

Location: All terminal components

Recommendation: Add minimal a11y support:

<div role="presentation" aria-label="Terminal animation demo">
  {/* terminal content */}
</div>

While not critical for marketing videos, this improves semantic HTML.

---

🟢 LOW Priority (Optional)

4. Binary File in Repository

Observation: video/out/goldfish-intro.mp4 (4.9MB) is committed.

Consideration:

• Binary files increase repo size over time (not tracked by Git LFS)
• out/ directory is typically build output
• However, this may be intentional for quick previews

Options:

1. Add video/out/ to root .gitignore if regeneration is easy
2. Keep it if the file serves as a reference/preview
3. Use GitHub Releases for distributing final renders

Current verdict: Not blocking, but worth discussing with team.

5. Scene Duration Validation

Location: src/config/video.ts

Current:

export const SCENE_DURATIONS = {
  title: 5,
  problem: 9,
  terminalDemo: 36,
  benefits: 7,
  closing: 3,
} as const;
// Manual verification: 5+9+36+7+3 = 60 ✓

Optional Enhancement: Add compile-time assertion:

type TotalDuration = typeof SCENE_DURATIONS[keyof typeof SCENE_DURATIONS];
// Validate sum at build time (requires additional type-level math)

Minor improvement for catching configuration errors early.

---

Security Assessment ✅

Verdict: No security concerns (appropriate for video generation code)

• ✅ No user input processing
• ✅ No dangerouslySetInnerHTML or dynamic script evaluation
• ✅ Color strings from hardcoded themes (no injection vectors)
• ✅ No file system access (browser-based Remotion)
• ✅ Dependencies up-to-date (Remotion 4.0.242, React 18.3.1)

---

Test Coverage

Observation: This PR contains no automated tests.

Context: Video generation code is typically tested through:

1. Visual preview (Remotion Studio) ✅ Mentioned in PR description
2. Rendered output validation ✅ PR author confirmed
3. Manual QA (timing, animations, transitions) ✅ Completed

Recommendation: While unit tests for useTerminalPlayback logic would be beneficial, visual testing via Remotion Studio is the industry standard for video projects. Not blocking.

---

Goldfish Integration

Alignment with Codebase Standards

✅ Follows CLAUDE.md guidance:

• Self-contained in video/ directory (doesn't touch core Goldfish code)
• Separate package.json and tsconfig.json (no dependency pollution)
• Clear README with usage instructions
• TypeScript strict mode aligns with Goldfish's type safety requirements

✅ No conflicts:

• Doesn't modify Python code, database schema, or MCP server
• Independent build system (npm run render vs. make for Goldfish)
• Separate .gitignore for Node.js artifacts

Considerations

This PR adds a separate project within the Goldfish monorepo. It's essentially a standalone Remotion app for marketing purposes. This is acceptable if:

1. The team wants video production tooling in the same repo as the product
2. Maintainers are comfortable with dual ecosystems (Python + TypeScript)
3. CI/CD can handle optional Node.js builds (or skip video builds in CI)

No technical objections, just an architectural observation.

---

Final Verdict

Recommendation: ✅ APPROVE (with minor fixes recommended)

Summary Table

Category	Status	Critical?
Type Safety	🟡 Good (needs exhaustiveness checks)	No
React Best Practices	🟡 Good (array keys fixable)	No
Architecture	🟢 Excellent	N/A
Performance	🟢 Good	N/A
Security	🟢 No concerns	N/A
Test Coverage	🟡 Visual testing only	No
Goldfish Integration	🟢 Clean separation	N/A

Action Items (Optional)

1. Before merge: Fix exhaustiveness checks (5-minute change, prevents future bugs)
2. Before merge: Replace array index keys (10-minute change, improves stability)
3. Post-merge: Add accessibility attributes (nice-to-have)
4. Post-merge: Decide on binary file strategy (out/ directory)

---

Positive Notes 🎉

• Excellent documentation: README.md is thorough and well-organized
• Production-ready: Code is clean, commented, and maintainable
• Extensible design: Theme system makes it trivial to create variants (Codex CLI, Cursor, etc.)
• Clear intent: PR description accurately describes implementation and goals

This is high-quality work. The recommendations above are for robustness, not correctness. Great job! 🚀