@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-composition/references/render-api.md

@@ -0,0 +1,484 @@
+---
+title: Render API
+description: Export compositions to video in the browser or via CLI with full control over resolution, bitrate, and encoding options.
+type: reference
+nav:
+  parent: "Rendering"
+  priority: 11
+api:
+  methods:
+    - name: renderToVideo()
+      signature: renderToVideo(options?)
+      description: Export timegroup to MP4 video with WebCodecs
+      returns: Promise<Uint8Array | undefined>
+    - name: createRenderClone()
+      signature: createRenderClone()
+      description: Create off-DOM clone for rendering without affecting preview
+      returns: Promise<RenderCloneResult>
+    - name: getRenderData()
+      signature: getRenderData<T>()
+      description: Access custom data passed from CLI at render time
+      returns: T | undefined
+---
+
+# Render API
+
+Export compositions to MP4 video using browser-based WebCodecs or server-side rendering via CLI.
+
+## Browser Export with renderToVideo()
+
+Export videos directly in the browser using the WebCodecs API. Best for client-side applications and interactive exports.
+
+### Basic Usage
+
+```html live
+<ef-timegroup mode="fixed" duration="3s" class="w-[720px] h-[480px] bg-gradient-to-br from-blue-500 to-purple-600 flex items-center justify-center">
+  <ef-text duration="3s" class="text-white text-6xl font-bold">Hello Video!</ef-text>
+</ef-timegroup>
+
+<button id="exportBtn" class="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700">
+  Export Video
+</button>
+
+<div id="progress" class="mt-4 hidden">
+  <div class="text-sm text-gray-300 mb-2">
+    <span id="progressText">Rendering...</span>
+  </div>
+  <div class="w-full bg-gray-700 rounded-full h-2">
+    <div id="progressBar" class="bg-blue-600 h-2 rounded-full transition-all" style="width: 0%"></div>
+  </div>
+  <canvas id="preview" class="mt-4 border border-gray-600" style="width: 360px; height: 240px;"></canvas>
+</div>
+
+<script type="module">
+  const timegroup = document.querySelector('ef-timegroup');
+  const exportBtn = document.getElementById('exportBtn');
+  const progressDiv = document.getElementById('progress');
+  const progressBar = document.getElementById('progressBar');
+  const progressText = document.getElementById('progressText');
+  const previewCanvas = document.getElementById('preview');
+
+  exportBtn.addEventListener('click', async () => {
+    exportBtn.disabled = true;
+    progressDiv.classList.remove('hidden');
+
+    try {
+      await timegroup.renderToVideo({
+        fps: 30,
+        codec: 'avc',
+        filename: 'my-video.mp4',
+        onProgress: (progress) => {
+          const percent = Math.round(progress.progress * 100);
+          progressBar.style.width = `${percent}%`;
+          progressText.textContent = `Rendering frame ${progress.currentFrame}/${progress.totalFrames} (${percent}%)`;
+
+          // Show live preview of current frame
+          if (progress.framePreviewCanvas) {
+            const ctx = previewCanvas.getContext('2d');
+            previewCanvas.width = progress.framePreviewCanvas.width;
+            previewCanvas.height = progress.framePreviewCanvas.height;
+            ctx.drawImage(progress.framePreviewCanvas, 0, 0);
+          }
+        }
+      });
+
+      progressText.textContent = 'Export complete! Video downloaded.';
+      exportBtn.disabled = false;
+    } catch (error) {
+      progressText.textContent = `Export failed: ${error.message}`;
+      exportBtn.disabled = false;
+    }
+  });
+</script>
+```
+
+### RenderToVideoOptions
+
+All options for `renderToVideo()`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fps` | `number` | `30` | Frame rate (frames per second) |
+| `codec` | `string` | `"avc"` | Video codec: `"avc"`, `"hevc"`, `"vp9"`, `"av1"`, `"vp8"` |
+| `bitrate` | `number` | `5_000_000` | Video bitrate in bits per second |
+| `filename` | `string` | `"video.mp4"` | Download filename |
+| `scale` | `number` | `1` | Rendering scale multiplier (2 = 2x resolution) |
+| `keyFrameInterval` | `number` | `150` | Frames between keyframes |
+| `fromMs` | `number` | `0` | Start time in milliseconds |
+| `toMs` | `number` | `duration` | End time in milliseconds |
+| `onProgress` | `function` | - | Progress callback (see below) |
+| `streaming` | `boolean` | `false` | Stream output using File System Access API |
+| `signal` | `AbortSignal` | - | AbortSignal to cancel render |
+| `includeAudio` | `boolean` | `true` | Include audio tracks in output |
+| `audioBitrate` | `number` | `128_000` | Audio bitrate in bits per second |
+| `contentReadyMode` | `string` | `"immediate"` | `"immediate"` or `"blocking"` for video readiness |
+| `blockingTimeoutMs` | `number` | `5000` | Timeout for blocking video loads |
+| `returnBuffer` | `boolean` | `false` | Return Uint8Array instead of downloading |
+| `preferredAudioCodecs` | `array` | `["opus", "aac"]` | Preferred audio codecs in order |
+| `benchmarkMode` | `boolean` | `false` | Skip encoding for performance testing |
+| `customWritableStream` | `WritableStream` | - | Custom output stream for programmatic control |
+| `progressPreviewInterval` | `number` | `10` | Frames between preview updates |
+| `canvasMode` | `string` | `"foreignObject"` | `"native"` or `"foreignObject"` rendering |
+
+### Progress Callback
+
+The `onProgress` callback receives a `RenderProgress` object with detailed information:
+
+```typescript
+interface RenderProgress {
+  progress: number;              // 0.0 to 1.0
+  currentFrame: number;          // Current frame index
+  totalFrames: number;           // Total frames to render
+  renderedMs: number;            // Milliseconds rendered so far
+  totalDurationMs: number;       // Total video duration
+  elapsedMs: number;             // Real time elapsed
+  estimatedRemainingMs: number;  // Estimated time remaining
+  speedMultiplier: number;       // Render speed (2.0 = 2x real-time)
+  framePreviewCanvas?: HTMLCanvasElement; // Preview of current frame
+}
+```
+
+### Codec Support Matrix
+
+Browser support varies by codec. Check availability before rendering:
+
+| Codec | Chrome | Safari | Firefox | Notes |
+|-------|--------|--------|---------|-------|
+| `avc` (H.264) | ✅ | ✅ | ✅ | Best compatibility, widely supported |
+| `hevc` (H.265) | ⚠️ | ✅ | ❌ | macOS/iOS only, better compression |
+| `vp9` | ✅ | ❌ | ✅ | Open codec, good compression |
+| `av1` | ✅ | ⚠️ | ✅ | Modern, best compression, slower encoding |
+| `vp8` | ✅ | ❌ | ✅ | Legacy WebM codec |
+
+**Recommendation:** Use `avc` for maximum compatibility or `av1` for best quality/size.
+
+### Audio Inclusion
+
+Audio from `ef-video` and `ef-audio` elements is automatically mixed and included:
+
+```typescript
+await timegroup.renderToVideo({
+  includeAudio: true,           // Include audio tracks
+  audioBitrate: 192_000,        // Higher quality audio (192 kbps)
+  preferredAudioCodecs: ['opus', 'aac'] // Codec preference order
+});
+```
+
+Audio codecs available: `opus` (best quality), `aac` (most compatible), `mp3` (legacy).
+
+### Streaming Output
+
+Stream large videos to disk without loading entire file into memory:
+
+```typescript
+await timegroup.renderToVideo({
+  streaming: true,              // Uses File System Access API
+  filename: 'large-video.mp4'   // User picks save location
+});
+```
+
+Requires browser support for File System Access API (Chrome 86+, Edge 86+).
+
+### Aborting Renders
+
+Cancel long-running exports with AbortController:
+
+```typescript
+const controller = new AbortController();
+
+// Start render
+const renderPromise = timegroup.renderToVideo({
+  signal: controller.signal,
+  onProgress: (progress) => {
+    console.log(`${Math.round(progress.progress * 100)}%`);
+  }
+});
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await renderPromise;
+} catch (error) {
+  if (error.name === 'RenderCancelledError') {
+    console.log('Render was cancelled');
+  }
+}
+```
+
+### Partial Exports
+
+Export specific time ranges without modifying the composition:
+
+```typescript
+// Export only seconds 5-15
+await timegroup.renderToVideo({
+  fromMs: 5000,
+  toMs: 15000,
+  filename: 'clip.mp4'
+});
+```
+
+### High-Resolution Export
+
+Render at higher resolutions using the `scale` option:
+
+```typescript
+// Render at 2x resolution (1440x960 from 720x480 composition)
+await timegroup.renderToVideo({
+  scale: 2,
+  bitrate: 10_000_000  // Increase bitrate for higher resolution
+});
+```
+
+### Programmatic Buffer Access
+
+Get video data as Uint8Array instead of downloading:
+
+```typescript
+const videoBuffer = await timegroup.renderToVideo({
+  returnBuffer: true,
+  filename: 'video.mp4'
+});
+
+// Upload to server
+const formData = new FormData();
+formData.append('video', new Blob([videoBuffer], { type: 'video/mp4' }));
+await fetch('/api/upload', { method: 'POST', body: formData });
+```
+
+## Off-DOM Rendering with createRenderClone()
+
+Create an independent clone of a timegroup for off-screen rendering. This enables rendering without affecting the user's preview position and allows concurrent renders.
+
+### Why Use Render Clones?
+
+- **Non-disruptive:** Render in background without affecting preview playback
+- **Concurrent:** Run multiple renders simultaneously with different clones
+- **Isolated state:** Each clone has independent time position and state
+- **JavaScript re-execution:** Initializer functions run on each clone
+
+### Basic Usage
+
+```typescript
+// Create a render clone
+const { clone, container, cleanup } = await timegroup.createRenderClone();
+
+try {
+  // Clone is fully functional and independent
+  await clone.seekForRender(5000);  // Seek to 5 seconds
+
+  // Render single frame to canvas
+  const canvas = await renderToImageNative(clone, 1920, 1080);
+
+  // Use canvas data...
+  const dataUrl = canvas.toDataURL('image/png');
+
+} finally {
+  // Always clean up when done
+  cleanup();
+}
+```
+
+### Automatic Clone Management
+
+`renderToVideo()` automatically manages clones internally. You typically don't need to use `createRenderClone()` directly unless you're building custom rendering logic.
+
+```typescript
+// This internally creates and manages a render clone
+await timegroup.renderToVideo({ fps: 30 });
+```
+
+### Clone Factory Pattern
+
+For compositions with JavaScript behavior, provide an initializer function that runs on both the prime timeline and all clones:
+
+```typescript
+<ef-timegroup id="myComp" mode="sequence"></ef-timegroup>
+
+<script type="module">
+  const timegroup = document.getElementById('myComp');
+
+  // This function runs on the original AND on all render clones
+  timegroup.initializer = (tg) => {
+    // Set up reactive state, register callbacks, etc.
+    tg.addEventListener('frame-task', (e) => {
+      // Update canvas, modify DOM, etc.
+      console.log('Frame:', e.detail.currentTimeMs);
+    });
+  };
+</script>
+```
+
+The initializer:
+- **Must be synchronous** (no async/await, no Promise return)
+- **Must complete quickly** (&lt;10ms warning, &lt;100ms error)
+- Runs once per instance (original + each clone)
+- Enables JavaScript-driven animations in renders
+
+## CLI Rendering
+
+For server-side rendering, use the Editframe CLI. See the `editframe-cli` skill for full documentation.
+
+### Quick Render
+
+```bash
+npx editframe render -o output.mp4
+```
+
+### Custom Render Data
+
+Pass dynamic data into compositions at render time:
+
+```bash
+npx editframe render --data '{"userName":"John","theme":"dark"}' -o video.mp4
+```
+
+Read the data in your composition with `getRenderData()`:
+
+```typescript
+import { getRenderData } from "@editframe/elements";
+
+interface MyRenderData {
+  userName: string;
+  theme: "light" | "dark";
+}
+
+const data = getRenderData<MyRenderData>();
+if (data) {
+  console.log(data.userName);  // "John"
+  console.log(data.theme);     // "dark"
+}
+```
+
+### When to Use CLI vs Browser
+
+**Use CLI rendering when:**
+- Running on a server or CI/CD pipeline
+- Need consistent encoding across platforms
+- Processing videos in batch
+- Require specific encoder settings not available in browsers
+
+**Use browser rendering when:**
+- Building interactive client-side applications
+- Want instant preview and export without server
+- Need real-time progress feedback
+- Exporting user-generated content
+
+## Advanced: Custom Writable Streams
+
+For fine-grained control over output, provide a custom WritableStream:
+
+```typescript
+class VideoUploadStream extends WritableStream<Uint8Array> {
+  constructor() {
+    super({
+      async write(chunk) {
+        // Stream chunks directly to server
+        await fetch('/api/upload/chunk', {
+          method: 'POST',
+          body: chunk
+        });
+      },
+      async close() {
+        // Finalize upload
+        await fetch('/api/upload/complete', { method: 'POST' });
+      }
+    });
+  }
+}
+
+await timegroup.renderToVideo({
+  customWritableStream: new VideoUploadStream(),
+  returnBuffer: false
+});
+```
+
+## Performance Tips
+
+1. **Use appropriate codecs:** `avc` encodes fastest, `av1` encodes slowest but smallest
+2. **Reduce resolution:** Lower resolution renders much faster
+3. **Limit audio bitrate:** High audio bitrates don't improve quality much
+4. **Use contentReadyMode: "immediate":** Skip waiting for videos to fully load
+5. **Disable progress previews:** Set high `progressPreviewInterval` or omit callback
+6. **Test codec support:** Not all codecs are hardware-accelerated on all devices
+
+## Browser Requirements
+
+- **WebCodecs API** (Chrome 94+, Edge 94+, Safari 16.4+)
+- **File System Access API** for streaming (Chrome 86+, Edge 86+)
+- Requires HTTPS or localhost (secure context)
+
+Check support:
+
+```typescript
+const hasWebCodecs = 'VideoEncoder' in window && 'VideoDecoder' in window;
+const hasFileSystemAccess = 'showSaveFilePicker' in window;
+```
+
+## Error Handling
+
+```typescript
+try {
+  await timegroup.renderToVideo({ fps: 60, codec: 'av1' });
+} catch (error) {
+  if (error.name === 'RenderCancelledError') {
+    console.log('User cancelled export');
+  } else if (error.name === 'NoSupportedAudioCodecError') {
+    console.log('No compatible audio codec available');
+    // Retry without audio
+    await timegroup.renderToVideo({ includeAudio: false });
+  } else {
+    console.error('Render failed:', error);
+  }
+}
+```
+
+## Examples
+
+### Export with Custom Settings
+
+```typescript
+await timegroup.renderToVideo({
+  fps: 60,                       // Smooth 60fps
+  codec: 'avc',                  // H.264 for compatibility
+  bitrate: 8_000_000,            // 8 Mbps
+  scale: 1.5,                    // 1.5x resolution
+  includeAudio: true,
+  audioBitrate: 256_000,         // High quality audio
+  filename: 'high-quality.mp4'
+});
+```
+
+### Progress Bar with Time Estimates
+
+```typescript
+await timegroup.renderToVideo({
+  onProgress: ({ progress, elapsedMs, estimatedRemainingMs, speedMultiplier }) => {
+    const percent = Math.round(progress * 100);
+    const elapsed = Math.round(elapsedMs / 1000);
+    const remaining = Math.round(estimatedRemainingMs / 1000);
+
+    console.log(
+      `${percent}% complete | ` +
+      `Elapsed: ${elapsed}s | ` +
+      `Remaining: ${remaining}s | ` +
+      `Speed: ${speedMultiplier.toFixed(1)}x`
+    );
+  }
+});
+```
+
+### Export Multiple Clips
+
+```typescript
+const clips = [
+  { fromMs: 0, toMs: 5000, filename: 'intro.mp4' },
+  { fromMs: 5000, toMs: 15000, filename: 'main.mp4' },
+  { fromMs: 15000, toMs: 20000, filename: 'outro.mp4' },
+];
+
+for (const clip of clips) {
+  await timegroup.renderToVideo(clip);
+}
+```

package/dist/skills/editframe-composition/references/render-strategies.md

@@ -0,0 +1,119 @@
+---
+title: Render Strategies
+description: Three approaches to rendering Editframe compositions — CLI, browser-side, and cloud — with tradeoffs and when to use each.
+type: explanation
+nav:
+  parent: "Concepts"
+  priority: 13
+  related: ["render-api", "render-to-video"]
+---
+
+# Render Strategies
+
+Editframe compositions can be rendered through three paths. Each targets a different environment and set of constraints. The composition itself is identical across all three — only the rendering infrastructure differs.
+
+## CLI Render (Playwright)
+
+The CLI spawns a local Vite dev server and a Playwright browser instance. The browser loads the composition, and frames are captured server-side using Playwright's screenshot API.
+
+```bash
+npx editframe render -o output.mp4
+```
+
+The CLI handles encoding, audio muxing, and output assembly. Dynamic data can be injected at render time:
+
+```bash
+npx editframe render --data '{"title":"Q4 Report","theme":"dark"}' -o output.mp4
+```
+
+Access the data inside the composition with `getRenderData()`:
+
+```html
+<script type="module">
+  import { getRenderData } from "@editframe/elements";
+
+  const data = getRenderData();
+  if (data) {
+    document.querySelector('ef-text').textContent = data.title;
+  }
+</script>
+```
+
+The CLI path is suited for local development, automation scripts, and CI/CD pipelines where no browser UI is needed.
+
+## Browser Render (WebCodecs)
+
+The browser path uses the WebCodecs API for video encoding and FFmpeg.wasm for muxing. The entire render runs client-side — no server is required.
+
+```html
+<script type="module">
+  const timegroup = document.querySelector('ef-timegroup');
+
+  await timegroup.renderToVideo({
+    fps: 30,
+    codec: 'avc',
+    filename: 'export.mp4',
+    onProgress: (progress) => {
+      console.log(`${Math.round(progress.progress * 100)}%`);
+    }
+  });
+</script>
+```
+
+Browser support: Chrome 94+, Edge 94+, Safari 16.4+. Check availability at runtime:
+
+```html
+<script type="module">
+  const supported = 'VideoEncoder' in window && 'VideoDecoder' in window;
+</script>
+```
+
+The browser path is suited for user-facing export features, interactive applications, and cases where you want to avoid running a backend.
+
+## Cloud Render (API)
+
+The cloud path uploads the composition bundle to a server, which processes it with Playwright in a controlled environment. The server handles encoding, asset resolution, and output delivery.
+
+```bash
+# POST composition bundle to render API
+curl -X POST https://api.editframe.com/v1/renders \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "bundle=@composition.tgz"
+```
+
+Results are delivered via webhook or polling. The cloud path is suited for production workflows, scalable rendering, and environments where no browser is available.
+
+## Comparison
+
+| Aspect | CLI (Playwright) | Browser (WebCodecs) | Cloud (API) |
+|--------|-------------------|---------------------|-------------|
+| Runs in | Local machine | User's browser | Remote server |
+| Encoding | Server-side FFmpeg | WebCodecs + FFmpeg.wasm | Server-side FFmpeg |
+| Audio muxing | Automatic | Automatic | Automatic |
+| Dynamic data | `--data` flag | JavaScript state | Request payload |
+| Progress feedback | Terminal output | `onProgress` callback | Webhook / polling |
+| Browser required | Playwright (headless) | User's browser | None (server-side) |
+| Codec control | Full FFmpeg options | Browser-supported codecs | Full FFmpeg options |
+| Concurrent renders | Limited by local CPU | One per tab | Scales with infrastructure |
+
+## Architecture Differences
+
+All three paths share the same composition format. The divergence is in how frames are captured and encoded.
+
+**CLI and cloud** both use Playwright to load the composition in a headless browser. Playwright captures each frame as a screenshot, and an FFmpeg process encodes the image sequence into the output container. Audio is decoded and muxed separately.
+
+**Browser render** creates an off-DOM clone of the composition, seeks it frame-by-frame, and rasterizes each frame to a canvas. The canvas frames are fed to a `VideoEncoder` instance (WebCodecs API), and the encoded chunks are muxed with FFmpeg.wasm into the final MP4.
+
+## Performance Characteristics
+
+**CLI render** speed depends on the local machine. Frame capture through Playwright adds per-frame overhead, but encoding benefits from native FFmpeg and hardware acceleration where available.
+
+**Browser render** speed depends on the user's device and browser. WebCodecs can leverage hardware encoding (GPU-accelerated H.264/H.265 on supported hardware), but the JavaScript overhead of canvas rasterization is the typical bottleneck.
+
+**Cloud render** offloads all computation to the server. Latency comes from uploading the bundle and waiting for the job to complete, but the render itself benefits from dedicated infrastructure.
+
+## See Also
+
+- [render-api.md](references/render-api.md) — full `renderToVideo()` options reference
+- [render-to-video.md](references/render-to-video.md) — step-by-step browser export tutorial
+- [server-rendering.md](references/server-rendering.md) — SSR-safe imports for server environments