@agent-foundry/replay-server 1.0.0 → 1.0.2

package/.cursor/dev.mdc

@@ -0,0 +1,941 @@
+---
+alwaysApply: true
+---
+
+# Replay Server - Development Rules
+
+## TypeScript Guidelines
+
+### Configuration
+
+- **Strict Mode**: Enabled in `tsconfig.json`
+  - `strict: true`
+  - `noImplicitAny: true`
+  - `strictNullChecks: true`
+- **ES Modules**: `"type": "module"` in `package.json`
+- **Target**: ES2022
+- **Module Resolution**: `bundler` (for ESM)
+
+### Type Safety
+
+- **Always use types**: Avoid `any`, use `unknown` when type is truly unknown
+- **Explicit return types**: For public methods, specify return types
+- **Type inference**: Use inference for local variables when type is obvious
+
+```typescript
+// Good: Explicit return type for public method
+async render(manifest: ReplayManifestV1, config: RenderConfig): Promise<RenderResult> {
+  // ...
+}
+
+// Good: Type inference for local variable
+const jobId = uuidv4(); // Inferred as string
+
+// Bad: Using any
+function process(data: any) { }
+
+// Good: Proper typing
+function process(data: ReplayManifestV1) { }
+```
+
+### Interfaces vs Types
+
+- **Interfaces**: For object shapes that might be extended
+- **Types**: For unions, intersections, computed types
+
+```typescript
+// Good: Interface for extensible object
+interface RenderConfig {
+  gameUrl: string;
+  outputPath: string;
+  width?: number;
+}
+
+// Good: Type for union
+type JobStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+// Good: Type for computed
+type RenderProgressStage = RenderProgress['stage'];
+```
+
+### Null Safety
+
+- **Optional properties**: Use `?` for optional properties
+- **Null checks**: Always check for null/undefined before use
+- **Non-null assertion**: Avoid `!` operator, use proper checks
+
+```typescript
+// Good: Optional chaining
+if (job?.progress) {
+  console.log(job.progress.current);
+}
+
+// Good: Null check
+if (!this.page) {
+  throw new Error('Browser not initialized');
+}
+
+// Bad: Non-null assertion
+this.page!.screenshot();
+```
+
+### Enums
+
+- **Avoid enums**: Use union types instead
+- **String literals**: Prefer `'pending' | 'processing'` over `enum JobStatus`
+
+---
+
+## Express Patterns
+
+### Route Handlers
+
+- **Async functions**: Always use async/await
+- **Error handling**: Wrap in try/catch, return consistent error format
+- **Request validation**: Check required fields early
+- **Logging**: Use console.log with prefixes for debugging
+
+```typescript
+// Good: Async handler with error handling
+app.post('/render', async (req, res) => {
+  console.log('[POST /render] Request received');
+  try {
+    const { manifest, config } = req.body;
+    
+    // Validate early
+    if (!manifest && !req.body.manifestUrl) {
+      return res.status(400).json({ error: 'Either manifest or manifestUrl is required' });
+    }
+    
+    // Process request
+    const jobId = uuidv4();
+    // ...
+    
+    res.json({ jobId, status: 'pending' });
+  } catch (error) {
+    console.error('[POST /render] Error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+```
+
+### Error Responses
+
+- **Consistent format**: Always return JSON with `error` field
+- **Status codes**: Use appropriate HTTP status codes
+  - `400` - Bad request (validation errors)
+  - `404` - Not found
+  - `500` - Internal server error
+
+```typescript
+// Good: Consistent error format
+res.status(400).json({ error: 'Invalid manifest schema' });
+
+// Good: Descriptive error messages
+res.status(404).json({ error: 'Job not found' });
+```
+
+### Middleware
+
+- **CORS**: Enable for all routes
+- **JSON parsing**: Set limit for large manifests (10mb)
+- **Static files**: Serve bundles after API routes
+
+```typescript
+app.use(cors());
+app.use(express.json({ limit: '10mb' }));
+
+// API routes first
+app.get('/bundles', ...);
+app.post('/render', ...);
+
+// Static files after API routes
+app.use('/bundles', express.static(BUNDLES_DIR));
+```
+
+### Logging
+
+- **Prefix logs**: Use `[ENDPOINT]` or `[COMPONENT]` prefix
+- **Structured logging**: Include relevant context
+- **Error logging**: Log full error details
+
+```typescript
+// Good: Prefixed logging
+console.log('[POST /render] Request received');
+console.log('[POST /render] Render job started, jobId:', jobId);
+console.error('[POST /render] Error starting render job:', error);
+```
+
+---
+
+## Puppeteer Patterns
+
+### Browser Initialization
+
+- **Reuse instance**: Create browser once, reuse for multiple renders
+- **Close properly**: Always close browser in finally block
+- **Configuration**: Use optimized flags for containerized environments
+
+```typescript
+// Good: Browser initialization with proper cleanup
+private browser: Browser | null = null;
+
+async render(...) {
+  try {
+    await this.initBrowser(config);
+    // ... rendering logic
+  } finally {
+    await this.closeBrowser();
+  }
+}
+
+private async closeBrowser(): Promise<void> {
+  if (this.browser) {
+    await this.browser.close();
+    this.browser = null;
+    this.page = null;
+  }
+}
+```
+
+### Browser Configuration
+
+- **Container-friendly**: Use `--single-process`, `--no-zygote`
+- **Memory optimization**: `--disable-dev-shm-usage` for small /dev/shm
+- **Security**: `--no-sandbox`, `--disable-setuid-sandbox` in containers
+- **Performance**: Disable GPU, extensions, background networking
+
+```typescript
+// Good: Optimized browser args
+this.browser = await puppeteer.launch({
+  executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || '/usr/bin/chromium',
+  headless: true,
+  args: [
+    '--no-sandbox',
+    '--disable-setuid-sandbox',
+    '--disable-dev-shm-usage',
+    '--no-zygote',
+    '--single-process',
+    '--disable-gpu',
+    // ... more flags
+  ],
+});
+```
+
+### Page Navigation
+
+- **Wait strategy**: Use `networkidle0` for full page load
+- **Timeout**: Set reasonable timeout (30s for game load)
+- **Error tracking**: Track page errors and failed requests
+
+```typescript
+// Good: Navigation with proper wait strategy
+await this.page.goto(url.toString(), {
+  waitUntil: 'networkidle0',
+  timeout: 30000,
+});
+
+// Good: Error tracking
+this.page.on('pageerror', (error) => {
+  this.pageErrors.push(error.message);
+  console.error('📼 Page error:', error.message);
+});
+
+this.page.on('requestfailed', (request) => {
+  const failure = request.failure();
+  this.failedRequests.push({
+    url: request.url(),
+    errorText: failure?.errorText,
+  });
+});
+```
+
+### Waiting for Game Ready
+
+- **React initialization**: Wait for app container and loading spinner
+- **Replay ready**: Wait for `data-replay-ready` attribute
+- **Retry logic**: Implement retry with timeout
+
+```typescript
+// Good: Wait for React initialization
+await this.page.waitForFunction(() => {
+  const app = document.querySelector('ion-app');
+  const loading = document.querySelector('ion-spinner');
+  return app !== null && loading === null;
+}, { timeout: 15000 });
+
+// Good: Wait for replay ready with retry
+const maxRetries = 3;
+let retryCount = 0;
+while (retryCount < maxRetries) {
+  try {
+    await this.page.waitForSelector('[data-replay-ready="true"]', {
+      timeout: 5000,
+    });
+    break;
+  } catch {
+    retryCount++;
+    await new Promise(resolve => setTimeout(resolve, 500));
+  }
+}
+```
+
+### Screenshot Capture
+
+- **JPEG format**: Use JPEG for smaller file size
+- **Quality**: 85% quality for good balance
+- **Binary encoding**: Use `encoding: 'binary'` for Buffer
+
+```typescript
+// Good: JPEG screenshot
+const screenshotBuffer = await this.page.screenshot({
+  type: 'jpeg',
+  quality: 85,
+  encoding: 'binary',
+}) as Buffer;
+```
+
+---
+
+## FFmpeg Integration
+
+### Streaming Mode
+
+- **Stdin input**: Use `-f image2pipe -vcodec mjpeg -i -`
+- **No temp files**: Stream frames directly to FFmpeg
+- **Backpressure**: Handle stdin drain events
+
+```typescript
+// Good: Streaming FFmpeg setup
+const ffmpeg = spawn('ffmpeg', [
+  '-y',
+  '-f', 'image2pipe',
+  '-vcodec', 'mjpeg',
+  '-r', String(config.fps),
+  '-i', '-',
+  '-c:v', 'libx264',
+  '-preset', 'fast',
+  '-crf', '28',
+  '-pix_fmt', 'yuv420p',
+  '-r', String(config.fps),
+  '-movflags', '+faststart',
+  config.outputPath,
+]);
+
+// Good: Handle stdin drain
+const writeSuccess = ffmpeg.stdin.write(screenshotBuffer);
+if (!writeSuccess) {
+  await new Promise<void>((resolve) => {
+    if (ffmpeg.stdin) {
+      ffmpeg.stdin.once('drain', resolve);
+    } else {
+      resolve();
+    }
+  });
+}
+```
+
+### Encoder Selection
+
+- **Default**: libx264 (CPU encoding, works everywhere)
+- **Optional**: h264_nvenc (GPU encoding, requires NVIDIA GPU)
+- **Configuration**: Use `useHardwareAcceleration` flag
+
+```typescript
+// Good: Encoder selection
+const encoder = config.useHardwareAcceleration ? 'h264_nvenc' : 'libx264';
+
+// Good: NVENC-specific parameters
+if (encoder === 'h264_nvenc') {
+  args.splice(args.length - 1, 0, '-rc', 'vbr', '-cq', '28');
+}
+```
+
+### Process Management
+
+- **Error handling**: Track stderr, handle process errors
+- **Timeout**: Set timeout to prevent hanging (5 minutes)
+- **Cleanup**: Close stdin, kill process on error
+- **Promise-based**: Use promise with event handlers
+
+```typescript
+// Good: Process management with timeout
+const encodingPromise = new Promise<void>((resolve, reject) => {
+  const timeout = setTimeout(() => {
+    if (!ffmpegClosed) {
+      ffmpegClosed = true;
+      reject(new Error('FFmpeg encoding timeout'));
+      if (ffmpeg && !ffmpeg.killed) {
+        ffmpeg.kill('SIGKILL');
+      }
+    }
+  }, 5 * 60 * 1000); // 5 minutes
+
+  ffmpeg.on('close', (code) => {
+    clearTimeout(timeout);
+    if (code === 0) {
+      resolve();
+    } else {
+      reject(new Error(`FFmpeg exited with code ${code}`));
+    }
+  });
+
+  ffmpeg.on('error', (err) => {
+    clearTimeout(timeout);
+    reject(new Error(`Failed to start FFmpeg: ${err.message}`));
+  });
+});
+
+// Good: Cleanup on error
+try {
+  // ... capture frames
+} catch (error) {
+  if (ffmpeg.stdin && !ffmpeg.stdin.destroyed) {
+    ffmpeg.stdin.destroy();
+  }
+  if (ffmpeg && !ffmpeg.killed) {
+    ffmpeg.kill('SIGKILL');
+  }
+  throw error;
+}
+```
+
+---
+
+## File Organization
+
+### Server Structure
+
+```
+src/server/
+└── index.ts          # Express app, all routes, job management
+```
+
+**Pattern**: Single file for server (small enough to maintain). If it grows, split by route prefix:
+- `routes/render.ts` - Render endpoints
+- `routes/jobs.ts` - Job management
+- `routes/bundles.ts` - Bundle serving
+
+### Renderer Structure
+
+```
+src/renderer/
+├── index.ts              # Exports
+└── PuppeteerRenderer.ts  # Main renderer class
+```
+
+**Pattern**: Single class with private methods:
+- `render()` - Public entry point
+- `initBrowser()` - Browser initialization
+- `loadGame()` - Game loading and manifest injection
+- `captureAndEncodeFrames()` - Frame capture loop
+- `launchFFmpeg()` - FFmpeg process setup
+- `closeBrowser()` - Cleanup
+
+### CLI Structure
+
+```
+src/cli/
+└── render.ts  # CLI entry point, argument parsing, renderer invocation
+```
+
+**Pattern**: Single file with:
+- `parseArgs()` - Command-line argument parsing
+- `loadManifest()` - Manifest loading (file or URL)
+- `formatProgress()` - Progress bar formatting
+- `main()` - Entry point
+
+---
+
+## Naming Conventions
+
+### Classes
+
+- **PascalCase**: `PuppeteerRenderer`, `RenderConfig`
+- **Static classes**: Use static methods (no instances needed)
+
+```typescript
+// Good: PascalCase class
+export class PuppeteerRenderer {
+  private browser: Browser | null = null;
+  
+  async render(...) { }
+}
+```
+
+### Functions
+
+- **camelCase**: `render`, `initBrowser`, `loadGame`
+- **Verb-based**: `getJob`, `createJob`, `startRender`
+- **Descriptive**: `captureAndEncodeFrames` not `capture`
+
+```typescript
+// Good: Verb-based, descriptive
+async function processJob(job: RenderJob, manifest: ReplayManifestV1) { }
+async function resolveGameUrl(manifest: ReplayManifestV1, configGameUrl?: string) { }
+```
+
+### Variables
+
+- **camelCase**: `jobId`, `outputPath`, `frameIndex`
+- **Constants**: `UPPER_SNAKE_CASE`: `DEFAULT_CONFIG`, `MAX_RETRIES`
+
+```typescript
+// Good: camelCase variables
+const jobId = uuidv4();
+const outputPath = path.join(OUTPUT_DIR, `${jobId}.mp4`);
+
+// Good: UPPER_SNAKE_CASE constants
+const DEFAULT_CONFIG = {
+  width: 720,
+  height: 1280,
+  fps: 16,
+};
+```
+
+### Interfaces/Types
+
+- **PascalCase**: `RenderConfig`, `RenderProgress`, `RenderResult`
+- **No "I" prefix**: Use `RenderConfig` not `IRenderConfig`
+- **Descriptive names**: `RenderProgress` not `Progress`
+
+```typescript
+// Good: PascalCase, descriptive
+interface RenderConfig {
+  gameUrl: string;
+  outputPath: string;
+}
+
+type JobStatus = 'pending' | 'processing' | 'completed' | 'failed';
+```
+
+---
+
+## Error Handling
+
+### Explicit Errors
+
+- **Throw with context**: Include relevant information in error message
+- **Error types**: Use Error class, not strings
+- **Propagate errors**: Let errors bubble up with context
+
+```typescript
+// Good: Descriptive error
+if (!manifest.bundleId && !configGameUrl) {
+  throw new Error('Bundle not found and no gameUrl provided');
+}
+
+// Good: Error with context
+if (code === 0) {
+  resolve();
+} else {
+  reject(new Error(`FFmpeg exited with code ${code}. Stderr: ${ffmpegStderr}`));
+}
+
+// Bad: Generic error
+throw new Error('Error');
+```
+
+### Progress Reporting
+
+- **Callback pattern**: Use optional callback for progress updates
+- **Structured progress**: Include stage, current, total, message
+- **Update frequency**: Don't update on every frame (use modulo)
+
+```typescript
+// Good: Progress callback pattern
+interface RenderConfig {
+  onProgress?: (progress: RenderProgress) => void;
+}
+
+private reportProgress(
+  callback: ((progress: RenderProgress) => void) | undefined,
+  stage: RenderProgress['stage'],
+  current: number,
+  total: number,
+  message: string
+): void {
+  if (callback) {
+    callback({ stage, current, total, message });
+  }
+}
+
+// Good: Update frequency
+if (frameIndex % config.fps === 0) {
+  this.reportProgress(onProgress, 'capture', frameIndex, totalFrames, message);
+}
+```
+
+### Job Status Tracking
+
+- **State machine**: Track pending → processing → completed/failed
+- **Error storage**: Store error message in job object
+- **Timestamps**: Track createdAt and completedAt
+
+```typescript
+// Good: Job status tracking
+interface RenderJob {
+  id: string;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  progress: RenderProgress | null;
+  outputPath: string | null;
+  error: string | null;
+  createdAt: Date;
+  completedAt: Date | null;
+}
+
+// Good: Status updates
+job.status = 'processing';
+try {
+  // ... render
+  job.status = 'completed';
+  job.outputPath = result.outputPath;
+} catch (error) {
+  job.status = 'failed';
+  job.error = error instanceof Error ? error.message : String(error);
+} finally {
+  job.completedAt = new Date();
+}
+```
+
+---
+
+## Dependencies
+
+### Core Dependencies
+
+- **express**: HTTP server framework
+- **puppeteer**: Headless browser automation
+- **fluent-ffmpeg**: FFmpeg wrapper (note: actual FFmpeg binary required)
+- **cors**: CORS middleware
+- **uuid**: Job ID generation
+
+### Type Dependencies
+
+Always include `@types/*` packages for TypeScript support:
+- `@types/express`
+- `@types/fluent-ffmpeg`
+- `@types/cors`
+- `@types/uuid`
+- `@types/node`
+
+### Shared Package
+
+- **@agent-foundry/replay**: Replay manifest type definitions
+  - Import types: `import type { ReplayManifestV1 } from '@agent-foundry/replay'`
+  - Used for manifest validation and type safety
+
+### Package Management
+
+- **Always use pnpm**: This is a pnpm monorepo workspace
+- **Run from root**: Use `pnpm --filter replay-server` from monorepo root
+- **CLI tools**: Use `pnpm exec <command>` for local CLI tools
+
+---
+
+## Code Organization
+
+### Import Order
+
+1. Node.js built-ins
+2. Third-party libraries
+3. Shared packages
+4. Local imports
+5. Type imports (use `import type`)
+
+```typescript
+// Good: Organized imports
+import * as fs from 'fs';
+import * as path from 'path';
+import express, { type Express } from 'express';
+import cors from 'cors';
+import { v4 as uuidv4 } from 'uuid';
+import { PuppeteerRenderer, RenderProgress } from '../renderer/PuppeteerRenderer.js';
+import type { ReplayManifestV1 } from '@agent-foundry/replay';
+```
+
+### Export Strategy
+
+- **Named exports**: For classes, functions, types
+- **Default exports**: Avoid (not needed for this project)
+- **Barrel exports**: Use `index.ts` for clean imports
+
+```typescript
+// src/renderer/index.ts
+export * from './PuppeteerRenderer.js';
+
+// Usage
+import { PuppeteerRenderer } from '../renderer';
+```
+
+### File Headers
+
+- **Purpose**: Add file header comment explaining purpose
+- **Key exports**: List main exports in header
+
+```typescript
+/**
+ * Puppeteer-based Video Renderer
+ * 
+ * This renderer:
+ * 1. Launches a headless browser
+ * 2. Opens the game at a special replay URL
+ * 3. Injects the replay manifest
+ * 4. Captures screenshots as JPEG buffers and streams directly to FFmpeg via stdin
+ * 5. Encodes video using libx264 (CPU) by default, or h264_nvenc if explicitly enabled
+ */
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Game URL Resolution
+
+```typescript
+function resolveGameUrl(manifest: ReplayManifestV1, configGameUrl?: string): string {
+  // 1. Explicit gameUrl in config takes precedence
+  if (configGameUrl) {
+    return configGameUrl;
+  }
+  
+  // 2. Use bundleId from manifest to serve from local bundles
+  if (manifest.bundleId) {
+    const bundlePath = path.join(BUNDLES_DIR, manifest.bundleId);
+    if (!fs.existsSync(bundlePath)) {
+      throw new Error(`Bundle not found: ${manifest.bundleId}`);
+    }
+    return `http://localhost:${PORT}/bundles/${manifest.bundleId}/`;
+  }
+  
+  // 3. Fall back to default GAME_URL
+  return GAME_URL;
+}
+```
+
+### Pattern: Manifest Injection
+
+```typescript
+await this.page.evaluate((manifestJson: string) => {
+  // Store manifest in window for the game to read
+  (window as unknown as { __REPLAY_MANIFEST__: unknown }).__REPLAY_MANIFEST__ = JSON.parse(manifestJson);
+
+  // Dispatch event to notify the game
+  window.dispatchEvent(new CustomEvent('replay-manifest-loaded', {
+    detail: JSON.parse(manifestJson)
+  }));
+}, JSON.stringify(manifest));
+```
+
+### Pattern: Frame Capture Loop
+
+```typescript
+for (let ageIndex = 0; ageIndex < totalAges; ageIndex++) {
+  // Advance to next age
+  await this.page.evaluate(() => {
+    window.dispatchEvent(new CustomEvent('replay-next-age'));
+  });
+  
+  // Wait for animation
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  // Capture frames for this age
+  for (let f = 0; f < framesPerAge; f++) {
+    const screenshotBuffer = await this.page.screenshot({
+      type: 'jpeg',
+      quality: 85,
+      encoding: 'binary',
+    }) as Buffer;
+    
+    // Write to FFmpeg stdin
+    if (ffmpeg.stdin && !ffmpeg.stdin.destroyed) {
+      ffmpeg.stdin.write(screenshotBuffer);
+    }
+    
+    // Small delay between frames
+    await new Promise(resolve => setTimeout(resolve, 1000 / config.fps / 2));
+  }
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Direct Browser Access Without Cleanup
+
+```typescript
+// BAD: Browser not closed
+async function render() {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  // ... render
+  // Browser never closed!
+}
+
+// GOOD: Always close in finally
+async function render() {
+  let browser: Browser | null = null;
+  try {
+    browser = await puppeteer.launch();
+    // ... render
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+}
+```
+
+### ❌ Mutating Job State Directly
+
+```typescript
+// BAD: Direct mutation
+job.status = 'completed';
+job.outputPath = outputPath;
+
+// GOOD: Update through setter or immutable update
+jobs.set(jobId, {
+  ...job,
+  status: 'completed',
+  outputPath: outputPath,
+});
+```
+
+### ❌ Ignoring FFmpeg Errors
+
+```typescript
+// BAD: No error handling
+const ffmpeg = spawn('ffmpeg', args);
+ffmpeg.on('close', () => {
+  // Assume success
+});
+
+// GOOD: Track errors and exit codes
+let ffmpegStderr = '';
+ffmpeg.stderr?.on('data', (data: Buffer) => {
+  ffmpegStderr += data.toString();
+});
+
+ffmpeg.on('close', (code) => {
+  if (code !== 0) {
+    throw new Error(`FFmpeg exited with code ${code}. Stderr: ${ffmpegStderr}`);
+  }
+});
+```
+
+### ❌ Using Any Type
+
+```typescript
+// BAD: Using any
+function process(data: any) { }
+
+// GOOD: Proper typing
+function process(data: ReplayManifestV1) { }
+```
+
+---
+
+## Code Review Checklist
+
+- [ ] Follows TypeScript strict mode (no `any`)
+- [ ] Proper error handling (try/catch, error messages)
+- [ ] Browser cleanup in finally block
+- [ ] FFmpeg process properly managed (timeout, cleanup)
+- [ ] Logging with prefixes for debugging
+- [ ] Consistent error response format
+- [ ] Request validation early in handlers
+- [ ] Follows naming conventions
+- [ ] Proper file organization
+- [ ] Comments for complex logic
+- [ ] No unused imports/variables
+
+---
+
+## Performance Considerations
+
+### Browser Optimization
+
+- **Single process**: Use `--single-process` in containers
+- **Disable unnecessary features**: GPU, extensions, background networking
+- **Memory**: Increase shared memory (`--shm-size=2g` in Docker)
+
+### FFmpeg Optimization
+
+- **Streaming**: Use stdin instead of temp files
+- **Encoder preset**: Use `fast` preset for balance
+- **CRF**: Use 28 for good quality/size balance
+- **Hardware acceleration**: Use h264_nvenc when available (NVIDIA GPU)
+
+### Frame Capture
+
+- **Update frequency**: Don't report progress on every frame
+- **Frame delay**: Small delay between frames for stability
+- **JPEG quality**: 85% for good balance
+
+---
+
+## Testing Guidelines
+
+### Unit Tests
+
+- **Renderer methods**: Test browser initialization, game loading (with mocks)
+- **URL resolution**: Test game URL resolution logic
+- **Error handling**: Test error scenarios
+
+### Integration Tests
+
+- **End-to-end rendering**: Test full render flow with sample manifest
+- **API endpoints**: Test HTTP endpoints with test client
+- **Bundle serving**: Test bundle hosting and game loading
+
+### Test Structure
+
+```typescript
+describe('PuppeteerRenderer', () => {
+  describe('render', () => {
+    it('should render video successfully', async () => {
+      // Test logic
+    });
+    
+    it('should handle browser errors', async () => {
+      // Test error handling
+    });
+  });
+});
+```
+
+---
+
+## Documentation
+
+### Code Comments
+
+- **JSDoc**: Use JSDoc for public APIs
+- **Complex logic**: Comment complex algorithms
+- **Why, not what**: Comment why, not what (code should be self-documenting)
+
+```typescript
+/**
+ * Resolve game URL from manifest bundleId or config
+ * Priority: config.gameUrl > manifest.bundleId > GAME_URL env
+ * 
+ * @param manifest - Replay manifest
+ * @param configGameUrl - Optional explicit game URL
+ * @returns Resolved game URL
+ * @throws Error if bundle not found
+ */
+function resolveGameUrl(manifest: ReplayManifestV1, configGameUrl?: string): string {
+  // Implementation
+}
+```
+
+---
+
+## Resources
+
+- **TypeScript Handbook**: https://www.typescriptlang.org/docs/
+- **Express Guide**: https://expressjs.com/en/guide/routing.html
+- **Puppeteer API**: https://pptr.dev/
+- **FFmpeg Documentation**: https://ffmpeg.org/documentation.html
+- **Node.js Streams**: https://nodejs.org/api/stream.html