@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-vite-plugin/references/jit-transcoding.md

@@ -0,0 +1,91 @@
+---
+title: JIT Transcoding
+description: On-demand video transcoding during local development for instant browser-compatible playback of any input video format.
+type: reference
+nav:
+  parent: "Features"
+  priority: 20
+api:
+  endpoints:
+    - path: /api/v1/transcode/manifest.json
+      method: GET
+      description: Returns a JIT manifest describing available renditions and segments
+    - path: /api/v1/transcode/{rendition}/init.mp4
+      method: GET
+      description: Returns the initialization segment for a rendition
+    - path: /api/v1/transcode/{rendition}/{segmentId}.mp4
+      method: GET
+      description: Returns a media segment as a standalone playable file
+    - path: /api/v1/transcode/{rendition}/{segmentId}.m4s
+      method: GET
+      description: Returns a media segment fragment for streaming
+---
+
+# JIT Transcoding
+
+The Vite plugin transcodes video files on-demand during development. When a composition references a local video, the plugin splits it into streamable ISOBMFF segments and serves them through a local transcode API that mirrors the production endpoint structure.
+
+## How It Works
+
+When a video is first requested, the plugin:
+
+1. Generates a **fragment index** describing every track (video, audio, scrub) with byte offsets and durations
+2. Creates separated track files cached in the `cacheRoot` directory
+3. Serves individual segments by streaming the correct byte ranges from cached track files
+
+Subsequent requests for the same video skip transcoding entirely and serve directly from cache.
+
+## Manifest Endpoint
+
+The manifest describes available renditions and their segments:
+
+```
+GET /api/v1/transcode/manifest.json?url=http://localhost:5173/src/assets/clip.mp4
+```
+
+The response includes video renditions (`high`, `scrub`), audio renditions, per-segment duration arrays, codec strings, and endpoint templates for fetching init and media segments.
+
+## Segment Serving
+
+Init segments and media segments are served by extracting byte ranges from the cached track file:
+
+```
+GET /api/v1/transcode/high/init.mp4?url=...    # Initialization segment
+GET /api/v1/transcode/high/1.m4s?url=...        # Fragment (moof+mdat only)
+GET /api/v1/transcode/high/1.mp4?url=...        # Standalone playable (init+moof+mdat)
+```
+
+The `.m4s` extension returns raw fragments for streaming playback. The `.mp4` extension prepends the init segment so the file is independently playable, which is useful for testing.
+
+## Renditions
+
+The plugin creates three rendition types from each video:
+
+- **high** -- Full resolution video track (track ID 1)
+- **scrub** -- Low-resolution 320px-wide video for timeline scrubbing (track ID -1)
+- **audio** -- Audio track extracted separately (track ID 2, or track ID 1 for audio-only files)
+
+## Cache Management
+
+Transcoded assets are stored under `{cacheRoot}/.cache/`. To clear the cache programmatically:
+
+```
+DELETE /@ef-clear-cache/
+```
+
+The cache clear uses retry logic with backoff to handle race conditions during concurrent test runs. ENOENT errors are treated as success (cache already cleared), and ENOTEMPTY errors trigger retries.
+
+## Remote URL Support
+
+The `url` parameter can reference either local or remote files. The plugin resolves the URL by checking the hostname:
+
+- **Local URLs** (localhost, 127.0.0.1, *.localhost) are resolved to file paths relative to `root`
+- **Remote URLs** are passed directly to ffprobe, which supports HTTP/HTTPS natively
+
+## Debug Logging
+
+Enable debug output for the transcode middleware:
+
+```bash
+DEBUG=ef:vite-plugin:jit npm run dev
+```

package/dist/skills/editframe-vite-plugin/references/local-assets.md

@@ -0,0 +1,75 @@
+---
+title: Local Assets API
+description: Local development endpoints for asset management, image thumbnail caching, and automatic caption file generation.
+type: reference
+nav:
+  parent: "Features"
+  priority: 30
+api:
+  endpoints:
+    - path: /api/v1/assets/image
+      method: GET
+      description: Caches and serves a local or remote image file
+    - path: /api/v1/assets/captions
+      method: GET
+      description: Generates or retrieves cached captions for an audio/video file
+---
+
+# Local Assets API
+
+The plugin serves local images and captions through endpoints that mirror the production asset API. This allows compositions to use the same asset-fetching logic in both development and production without conditional paths.
+
+## Image Caching
+
+The image endpoint caches and serves image files with proper MIME types and ETags:
+
+```
+GET /api/v1/assets/image?src=assets/background.png
+```
+
+The `src` parameter accepts both local paths (resolved relative to the plugin `root` directory) and remote `http`/`https` URLs. Remote images are fetched server-side and returned as same-origin responses, preventing canvas CORS taint when compositions serialize to image. Local files are processed through `cacheImage(cacheRoot, absolutePath)` and served with an MD5-based ETag.
+
+## Caption Generation
+
+The captions endpoint generates or retrieves cached transcription data for audio and video files:
+
+```
+GET /api/v1/assets/captions?src=assets/interview.mp4
+```
+
+This calls `findOrCreateCaptions(cacheRoot, absolutePath)` which either returns existing cached captions or generates new ones using the assets package transcription pipeline. The result is served as JSON with cache headers.
+
+## Path Resolution
+
+All `src` parameters follow the same resolution logic:
+
+1. If `src` starts with `http://` or `https://`, it is fetched server-side and proxied to the browser as same-origin
+2. Otherwise, `src` is joined with the plugin `root` option
+3. Any `dist/` prefix in the resolved path is replaced with `src/` to support source-mapped development
+
+```typescript
+// Example: root = "./dev-projects/src"
+// src = "assets/photo.jpg"
+// Resolved: ./dev-projects/src/assets/photo.jpg
+```
+
+## Response Format
+
+All asset responses are streamed from the cache with:
+
+- **Content-Type** determined by file extension via the `mime` package
+- **ETag** set to the MD5 hash of the cached file
+- **Cache-Control** set to `max-age=3600`
+- **Range request** support for partial content (HTTP 206)
+
+## Error Handling
+
+- Missing `src` parameter returns `400` with `{ error: "src parameter is required" }`
+- File not found returns `404` with plain text body
+- Other errors return `500` with `{ error: "..." }` JSON
+
+## Debug Logging
+
+```bash
+DEBUG=ef:vite-plugin:assets npm run dev
+```

package/dist/skills/editframe-vite-plugin/references/visual-testing.md

@@ -0,0 +1,136 @@
+---
+title: Visual Testing
+description: Automated visual regression testing for Editframe compositions, comparing rendered frames against stored baseline images.
+type: reference
+nav:
+  parent: "Features"
+  priority: 50
+api:
+  endpoints:
+    - path: "/@ef-write-snapshot"
+      method: POST
+      description: Writes a snapshot image (baseline or actual) to disk
+    - path: "/@ef-compare-snapshot"
+      method: POST
+      description: Compares a screenshot against a stored baseline using odiff
+    - path: "/@ef-compare-two-images"
+      method: POST
+      description: Compares two arbitrary images using odiff
+---
+
+# Visual Testing
+
+The Vitest entry point (`@editframe/vite-plugin/src/index.vitest.js`) adds server-side image comparison endpoints powered by [odiff-bin](https://github.com/nicolo-ribaudo/odiff-bin). Tests running in the browser capture screenshots and POST them to the Vite server, which performs pixel-level comparison on the server where native binaries are available.
+
+## Setup
+
+Use the Vitest-specific import in your `vitest.config.ts`:
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig(async () => {
+  const { vitePluginEditframe } = await import(
+    "@editframe/vite-plugin/src/index.vitest.js"
+  );
+
+  return {
+    plugins: [
+      vitePluginEditframe({
+        root: "./test-assets",
+        cacheRoot: "./test-assets",
+      }),
+    ],
+    test: {
+      browser: {
+        enabled: true,
+        provider: "playwright",
+      },
+    },
+  };
+});
+```
+
+## Snapshot Comparison
+
+The `/@ef-compare-snapshot` endpoint compares a screenshot against a stored baseline:
+
+```typescript
+const response = await fetch("/@ef-compare-snapshot", {
+  method: "POST",
+  body: JSON.stringify({
+    testName: "my-component",
+    snapshotName: "default-state",
+    dataUrl: canvas.toDataURL("image/png"),
+    threshold: 0.1,
+    antialiasing: true,
+    acceptableDiffPercentage: 1.0,
+  }),
+});
+const result = await response.json();
+// { match: true, diffCount: 0, diffPercentage: 0 }
+```
+
+### First Run Behavior
+
+When no baseline exists, the actual image is automatically saved as the baseline and the comparison returns `{ match: true, baselineCreated: true }`. Subsequent runs compare against this stored baseline.
+
+### Comparison Parameters
+
+- **threshold** (default `0.1`) -- Color distance threshold passed to odiff. Lower values are stricter.
+- **antialiasing** (default `true`) -- When true, odiff ignores antialiasing differences between images.
+- **acceptableDiffPercentage** (default `1.0`) -- Maximum percentage of differing pixels before the comparison is considered a failure.
+
+## Two-Image Comparison
+
+The `/@ef-compare-two-images` endpoint compares any two images without baseline management:
+
+```typescript
+const response = await fetch("/@ef-compare-two-images", {
+  method: "POST",
+  body: JSON.stringify({
+    testName: "animation-test",
+    comparisonName: "frame-1-vs-frame-2",
+    dataUrl1: frame1Canvas.toDataURL("image/png"),
+    dataUrl2: frame2Canvas.toDataURL("image/png"),
+    threshold: 0.1,
+    acceptableDiffPercentage: 5.0,
+  }),
+});
+```
+
+Both images are written to the snapshot directory and compared with odiff. This is useful for verifying that two frames of an animation are visually distinct or within tolerance.
+
+## Snapshot Storage
+
+Snapshots are stored under `{root}/test/__snapshots__/{testName}/`:
+
+```
+test/__snapshots__/my-component/
+  default-state.baseline.png   # Reference image
+  default-state.actual.png     # Latest capture
+  default-state.diff.png       # Pixel diff (generated on mismatch)
+```
+
+The `/@ef-write-snapshot` endpoint can write a baseline or actual image directly:
+
+```typescript
+await fetch("/@ef-write-snapshot", {
+  method: "POST",
+  body: JSON.stringify({
+    testName: "my-component",
+    snapshotName: "default-state",
+    dataUrl: canvas.toDataURL("image/png"),
+    isBaseline: true,
+  }),
+});
+```
+
+## Diff Output
+
+When images differ beyond the acceptable threshold, odiff generates a diff image highlighting changed pixels. The response includes:
+
+- **match** -- `false` when the diff exceeds the threshold
+- **diffCount** -- Total number of differing pixels
+- **diffPercentage** -- Percentage of the image area that differs
+- **error** -- Set to `"Images have different dimensions"` when a layout diff is detected

package/dist/skills/editframe-webhooks/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: editframe-webhooks
+title: Webhooks
+description: Webhook notifications for render completion and file processing events. Configure endpoints, verify HMAC signatures, and handle real-time status payloads.
+order: 35
+license: MIT
+metadata:
+  author: editframe
+  version: "2.0"
+---
+
+# Webhooks
+
+Receive real-time HTTP notifications when renders complete, files finish processing, or other asynchronous events occur in your Editframe account.
+
+## Setup
+
+Webhooks are configured on an API key, not separately. The webhook URL and events you want to receive are set at API key creation time.
+
+**Step 1**: Create an API key with webhook configuration via the Editframe dashboard (editframe.com → API Keys → Create), or via your application's API key management endpoint. The dashboard returns a webhook secret — store it securely.
+
+**Step 2**: Handle webhook requests:
+
+```typescript
+// 3. Handle webhook requests
+app.post("/webhooks/editframe", async (req, res) => {
+  const signature = req.headers["x-webhook-signature"];
+  const payload = JSON.stringify(req.body);
+  const webhookSecret = process.env.EDITFRAME_WEBHOOK_SECRET;
+
+  // Verify signature — always verify before processing
+  const expectedSignature = crypto
+    .createHmac("sha256", webhookSecret)
+    .update(payload)
+    .digest("hex");
+
+  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+    return res.status(401).send("Invalid signature");
+  }
+
+  // Respond quickly, process asynchronously
+  res.status(200).send("OK");
+
+  const { topic, data } = req.body;
+  if (topic === "render.completed") {
+    console.log(`Render ${data.id} completed. Download: ${data.download_url}`);
+  }
+});
+```
+
+**Critical:** Hash the raw request body string (`JSON.stringify(req.body)`), not the parsed object. Use `timingSafeEqual` to prevent timing attacks.
+
+## Event Topics
+
+Webhooks are triggered for specific event topics:
+
+### Render Events
+- `render.created` — Render job created
+- `render.pending` — Render queued for processing
+- `render.rendering` — Render is actively processing
+- `render.completed` — Render successfully finished
+- `render.failed` — Render encountered an error
+
+### File Events
+- `file.created` — File record created
+- `file.uploading` — File is being uploaded
+- `file.processing` — File is being processed (video only)
+- `file.ready` — File is ready for use
+- `file.failed` — File processing failed
+
+### Legacy Events
+- `unprocessed_file.created` — Unprocessed file created (deprecated)
+
+## Configuration
+
+Configure webhooks when creating or updating an API key:
+
+**Webhook URL**: The HTTPS endpoint where Editframe will send POST requests
+**Webhook Events**: Array of event topics you want to receive
+**Webhook Secret**: Auto-generated HMAC secret for signature verification
+
+See [references/getting-started.md](references/getting-started.md) for detailed setup instructions.
+
+## Security
+
+All webhook requests include an `X-Webhook-Signature` header containing an HMAC-SHA256 signature. Always verify this signature before processing webhook payloads.
+
+See [references/security.md](references/security.md) for signature verification implementation.
+
+## Delivery Guarantees
+
+- Webhooks are delivered via HTTP POST with JSON payload
+- Automatic retry with exponential backoff (3 attempts)
+- 30-second timeout per attempt
+- Events marked as failed after retry exhaustion
+- Delivery history tracked for debugging
+
+## Testing
+
+Test your webhook endpoint before going live:
+
+```bash
+# Use the Editframe dashboard to send test webhooks
+# Or trigger test events via the API
+```
+
+See [references/testing.md](references/testing.md) for testing strategies including local development with ngrok.
+
+## Troubleshooting
+
+Common issues and solutions:
+
+- **Signature verification fails**: Ensure you're hashing the raw request body, not parsed JSON
+- **Timeout errors**: Respond with 200 OK quickly, process events asynchronously
+- **Missed webhooks**: Check delivery logs in the Editframe dashboard
+- **Duplicate events**: Implement idempotency using event IDs
+
+See [references/troubleshooting.md](references/troubleshooting.md) for detailed debugging guidance.
+
+## Reference Documentation
+
+- [references/getting-started.md](references/getting-started.md) — Set up your first webhook
+- [references/events.md](references/events.md) — Event types and payload structures
+- [references/security.md](references/security.md) — HMAC signature verification
+- [references/testing.md](references/testing.md) — Test webhooks locally and in production
+- [references/troubleshooting.md](references/troubleshooting.md) — Debug common issues