@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-motion-design/references/4-process.md

@@ -0,0 +1,418 @@
+---
+title: Process
+description: "Four-phase animation iteration process: establish motion intent, rough timing, refine easing, and polish with detail."
+type: explanation
+order: 4
+---
+
+# Systematic Iteration
+
+## Core Concept
+
+**Broad Strokes → Easing → Secondary → Polish**
+
+Don't perfect details before structure is right. Iterate in phases, each building on the previous.
+
+## The Four Phases
+
+```
+Phase 1: Broad Strokes    (40% of time)
+    ↓
+Phase 2: Easing           (20% of time)
+    ↓
+Phase 3: Secondary Motion (25% of time)
+    ↓
+Phase 4: Polish           (15% of time)
+```
+
+---
+
+## Phase 1: Broad Strokes (40%)
+
+**Goal: Get the sequence and rhythm right**
+
+### Do
+- Basic opacity and position only
+- Round timing (200, 300, 500ms)
+- Simple stagger (50, 100, 200ms)
+- Linear easing (ignore curves for now)
+- Test attention flow
+
+### Don't
+- Custom easing curves
+- Squash & stretch
+- Color transitions
+- Particle effects
+- Precise timing
+
+### Success Criteria
+- ✅ Sequence makes sense
+- ✅ Attention flows correctly
+- ✅ Nothing overlaps wrong
+- ✅ Overall rhythm feels approximately right
+
+### Example
+```
+// Phase 1: Basic structure only
+Title card entrance:
+  0ms:   opacity: 0, translateY: 40px
+  300ms: opacity: 1, translateY: 0
+  easing: linear  // ← ignore easing for now
+
+At 30fps: 9 frames
+Simple stagger for multiple elements: +100ms each
+```
+
+**If broad strokes feel wrong, stop.** Don't proceed to Phase 2. Fix the sequence first.
+
+---
+
+## Phase 2: Easing (20%)
+
+**Goal: Make motion feel natural**
+
+### Do
+- Replace linear with appropriate easing
+- Fine-tune timing (±50ms adjustments)
+- Test at 0.5× and 2× speed
+- Round to nearest 10ms when settled
+
+### Easing Selection
+- **Entrance:** ease-out (decelerating to rest)
+- **Exit:** ease-in (accelerating away)
+- **Within-screen:** ease-in-out (smooth start and stop)
+- **Never:** linear (except spinners/mechanical)
+
+### Success Criteria
+- ✅ Motion feels natural, not robotic
+- ✅ No jarring speed changes
+- ✅ Comfortable to watch repeatedly
+- ✅ Material choice is evident
+
+### Example
+```
+// Phase 2: Add proper easing
+Title card entrance:
+  0ms:   opacity: 0, translateY: 40px
+  330ms: opacity: 1, translateY: 0  // ← adjusted from 300ms
+  easing: ease-out  // ← cubic-bezier(0, 0, 0.2, 1)
+
+At 30fps: 10 frames (frame-aligned)
+Stagger refined: +80ms each (was +100ms)
+```
+
+---
+
+## Phase 3: Secondary Motion (25%)
+
+**Goal: Add life and personality**
+
+### Do
+- Squash & stretch (material-appropriate)
+- Anticipation & follow-through
+- Scale overshoots (102-105%)
+- Background dimming during focus
+- Subtle rotation during motion
+
+### Material-Based Deformation
+
+**Playful (rubber) - for fun brands:**
+```
+Logo bounce entrance:
+  0ms:   scale: 0.8
+  245ms: scale: 1.08  (70% through animation)
+  350ms: scale: 1
+
+At 30fps: ~10 frames
+Material: Rubber (energetic overshoot)
+```
+
+**Professional (glass) - for corporate:**
+```
+Title card entrance:
+  0ms:   translateY: 40px, scale: 1
+  210ms: translateY: 0, scale: 1.02  (70% through)
+  300ms: translateY: 0, scale: 1
+
+At 30fps: 9 frames
+Material: Glass (subtle overshoot)
+```
+
+### Success Criteria
+- ✅ Motion has personality
+- ✅ Elements feel like they have weight
+- ✅ Natural physics evident
+- ✅ Not overdone (still serves message)
+
+---
+
+## Phase 4: Polish (15%)
+
+**Goal: Handle edge cases and optimize**
+
+### Do
+- Micro-adjustments (±10ms)
+- Edge case testing (long text, missing images)
+- Performance optimization (will-change)
+- Accessibility (prefers-reduced-motion)
+- Cross-browser testing
+
+### Edge Cases to Test
+- Very long text (does it read in time?)
+- Very short text (does timing still work?)
+- Different aspect ratios (16:9, 9:16, 1:1)
+- Different resolutions (SD, HD, 4K)
+- Export format compatibility (H.264, ProRes, WebM)
+- Audio sync (if applicable)
+- Color space (sRGB, Rec.709, Rec.2020)
+
+### Performance
+- Pre-render heavy effects (particles, blur, 3D)
+- Use appropriate motion blur (180° shutter for natural look)
+- Optimize layer count in compositions
+- Ensure smooth playback at target framerate (24/30/60fps)
+- Check export file size vs quality tradeoff
+- Test on target viewing platform (mobile, TV, cinema)
+
+### Accessibility
+
+For video content intended for diverse audiences:
+
+```
+Standard version:
+- Full motion with bounces, particles, effects
+- Fast-paced stagger patterns
+
+Accessible version (when required):
+- Simpler animations (cuts or dissolves)
+- Longer durations (easier to follow)
+- Reduced flash/strobe effects
+- Lower contrast for motion elements
+- Maintain core message clarity
+```
+
+**Accessibility guidelines:**
+- No flashing faster than 3Hz (seizure risk)
+- Sufficient contrast for legibility
+- Longer read times for critical text
+- Alternative static versions available
+- Captions/subtitles always available
+
+### Success Criteria
+- ✅ Works across all target browsers
+- ✅ Performs at 60fps
+- ✅ Handles edge cases gracefully
+- ✅ Accessible (reduced motion support)
+- ✅ Mobile and desktop optimized
+
+---
+
+## Knowing When to Stop
+
+### Animation is Done When
+1. ✅ Serves the message clearly
+2. ✅ Guides attention intentionally
+3. ✅ Feels natural and polished
+4. ✅ Performs smoothly (60fps)
+5. ✅ Survives 10+ repeated views
+6. ✅ Works on target devices
+7. ✅ Handles edge cases
+8. ✅ Passes accessibility checks
+
+### Animation is Not Done If
+- ❌ Tweaking timing by 5ms increments (over-polishing)
+- ❌ Adding motion for motion's sake
+- ❌ Can't explain why specific values chosen
+- ❌ Haven't tested on real devices
+- ❌ Feedback says it's distracting
+
+### The 10-View Test
+
+Watch the animation 10 times in a row:
+- **Views 1-3:** Notice everything
+- **Views 4-6:** Start to see flaws
+- **Views 7-10:** Boring vs still pleasant?
+
+**If annoying by view 7, simplify or remove.**
+
+---
+
+## Common Iteration Mistakes
+
+### Mistake 1: Polishing Too Early
+
+```javascript
+// Bad: Perfect easing before sequence is right
+element.animate([...], {
+  duration: 347,  // overly precise
+  easing: 'cubic-bezier(0.43, 0.01, 0.22, 0.99)'  // custom curve
+});
+```
+
+**Sequence is still wrong!** Broad strokes first, always.
+
+### Mistake 2: Not Testing Edge Cases
+
+Only testing:
+- Fast computer ✗
+- Fast internet ✗
+- Perfect data ✗
+- Ideal device ✗
+
+**Test worst cases:**
+- Slow device
+- Slow network
+- Missing images
+- Very long text
+- Rapid interaction
+
+### Mistake 3: Ignoring Feedback Patterns
+
+Multiple people say "too fast" → it's too fast.
+
+Don't defend your choice. Listen to patterns.
+
+### Mistake 4: Over-Engineering
+
+```
+// Too complex for a simple title entrance
+Title card with:
+- 3D rotation on 3 axes
+- Color shift through 5 hues
+- Particle system
+- Light bloom effect
+- Depth of field animation
+All in 600ms
+
+Viewer gets: overwhelming blur, misses the title text
+```
+
+**Simpler is better.** Only add properties that serve the message. Title should be readable above all.
+
+---
+
+## Add vs Remove Decision
+
+### Remove If
+- ❌ Distracts from message
+- ❌ Slows user progress
+- ❌ Boring on 3rd+ view
+- ❌ Performance issues
+- ❌ Breaks on some devices
+- ❌ Violates "one focus at a time"
+
+### Add If
+- ✅ Guides attention better
+- ✅ Communicates state clearly
+- ✅ Adds personality without distraction
+- ✅ Makes interaction feel responsive
+- ✅ Shows relationships between elements
+
+**Default: Subtract when in doubt.**
+
+---
+
+## Testing at Different Speeds
+
+Good animation works at multiple speeds:
+
+```javascript
+// Test at various playback rates
+const speeds = [0.5, 1, 1.5, 2];
+
+speeds.forEach(speed => {
+  element.animate([...keyframes], {
+    duration: baseDuration / speed,
+    easing: easing
+  });
+});
+```
+
+**Quality test:**
+- **0.5×:** Still feels intentional?
+- **1×:** Perfect?
+- **2×:** Doesn't break logic?
+
+If it breaks at any speed, timing relationships are wrong.
+
+---
+
+## Getting Feedback at Right Stage
+
+### After Phase 1 (Broad Strokes):
+**Ask:** "Does the sequence make sense?"
+
+Don't ask about easing or polish yet. Just sequence.
+
+### After Phase 2 (Easing):
+**Ask:** "Does the motion feel natural?"
+
+Now curves matter. But don't ask about details yet.
+
+### After Phase 3 (Secondary):
+**Ask:** "Does it have personality?"
+
+Deformation and weight should be evident.
+
+### After Phase 4 (Polish):
+**Ask:** "Are there any issues or edge cases?"
+
+Now details matter.
+
+**Don't ask for polish feedback when sequence is wrong!**
+
+---
+
+## Workflow Checklist
+
+```
+□ Phase 1: Broad Strokes (40%)
+  □ Basic motion working
+  □ Sequence is right
+  □ Linear easing OK
+  □ Round timing values
+  
+□ Phase 2: Easing (20%)
+  □ Natural movement
+  □ Correct curves applied
+  □ Fine-tuned timing (±50ms)
+  □ Material choice evident
+  
+□ Phase 3: Secondary Motion (25%)
+  □ Squash & stretch added
+  □ Anticipation on actions
+  □ Follow-through on heavy elements
+  □ Supporting animations
+  
+□ Phase 4: Polish (15%)
+  □ Edge cases tested
+  □ Performance optimized
+  □ Accessibility implemented
+  □ Cross-browser verified
+  □ 10-view test passed
+  
+□ Done
+  □ Serves message clearly
+  □ Guides attention
+  □ Performs at 60fps
+  □ Works on all targets
+```
+
+---
+
+## Time Investment Guide
+
+For a typical UI animation project:
+
+**Total time: 8 hours**
+- Broad strokes: 3.2 hours (40%)
+- Easing: 1.6 hours (20%)
+- Secondary: 2 hours (25%)
+- Polish: 1.2 hours (15%)
+
+**If you find yourself:**
+- Spending 50% on polish → too early, go back to broad strokes
+- Spending 10% on broad strokes → rushing, will require rework
+- Skipping phases → recipe for weak foundation
+
+Respect the phase distribution. It's optimized for quality with minimum rework.

package/dist/skills/editframe-vite-plugin/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: editframe-vite-plugin
+description: Vite integration for Editframe development with local video transcoding, asset serving, file API endpoints, and visual regression testing.
+status: draft
+license: PROPRIETARY
+metadata:
+  package: "@editframe/vite-plugin"
+  version: "0.37.3-beta"
+  type: vite-plugin
+references:
+  - getting-started.md
+---
+
+# Vite Plugin
+
+## When do you need this?
+
+You need the Vite plugin when your composition references **local video files**. Without it, the browser can't play raw video files — they must be transcoded to streamable ISOBMFF format first.
+
+**Already included** in all project templates (`npm create @editframe`). You only need to install it manually when adding Editframe to an existing Vite project.
+
+| Scenario | Need this? |
+|----------|-----------|
+| Compositions with local `.mp4`/`.mov` files | Yes — JIT transcoding |
+| Compositions with remote URLs only | No |
+| Adding Editframe to existing Vite project | Yes — install manually |
+| Visual regression tests with Vitest | Yes — use vitest entry point |
+
+## The Dev Loop with This Plugin
+
+```
+npm run dev
+  ↓
+Vite starts + plugin registers middleware
+  ↓
+Composition loads video src="/src/assets/clip.mp4"
+  ↓
+Plugin transcodes on first request → cached in cacheRoot/
+  ↓
+Subsequent loads → served from cache (fast)
+```
+
+The `@editframe/vite-plugin` adds local development capabilities to your Vite project. It handles on-demand video transcoding, local asset serving, and visual regression testing so you can develop Editframe compositions without cloud API dependencies.
+
+## Installation
+
+```bash
+npm install @editframe/vite-plugin
+```
+
+## Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePluginEditframe } from "@editframe/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    vitePluginEditframe({
+      root: "./src",       // Base directory for resolving file paths
+      cacheRoot: "./cache", // Directory for cached transcoded assets
+    }),
+  ],
+});
+```
+
+## Reference
+
+- [references/getting-started.md](references/getting-started.md) — Installation and configuration options
+- [references/jit-transcoding.md](references/jit-transcoding.md) — How on-demand video transcoding works
+- [references/local-assets.md](references/local-assets.md) — Local image and caption serving
+- [references/file-api.md](references/file-api.md) — File API endpoints
+- [references/visual-testing.md](references/visual-testing.md) — Visual regression testing with Vitest
+```

package/dist/skills/editframe-vite-plugin/references/file-api.md

@@ -0,0 +1,111 @@
+---
+title: Local File API
+description: Local development endpoints for file upload and ISOBMFF video processing, mirroring the Editframe cloud files API.
+type: reference
+nav:
+  parent: "Features"
+  priority: 40
+api:
+  endpoints:
+    - path: /api/v1/files/local/index
+      method: GET
+      description: Returns the track fragment index for a local file
+    - path: /api/v1/files/local/md5
+      method: GET
+      description: Returns the MD5 hash of a local file
+    - path: /api/v1/files/local/track
+      method: GET
+      description: Returns a transcoded track for a local file
+    - path: /api/v1/isobmff_files/local/index
+      method: GET
+      description: Returns the track fragment index for a local ISOBMFF file
+    - path: /api/v1/isobmff_files/local/md5
+      method: GET
+      description: Returns the MD5 hash of a local ISOBMFF file
+    - path: /api/v1/isobmff_files/local/track
+      method: GET
+      description: Returns a transcoded track for a local ISOBMFF file
+---
+
+# Local File API
+
+The plugin provides local equivalents of the production file and ISOBMFF file APIs. These endpoints handle fragment index generation, MD5 hashing, and track extraction for local media files so that the elements runtime can process local assets without a cloud backend.
+
+## Endpoints
+
+The `/api/v1/files/local/*` and `/api/v1/isobmff_files/local/*` routes are interchangeable -- both accept the same parameters and produce the same results.
+
+### Fragment Index
+
+Returns track metadata (codec, duration, timescale, segment byte offsets) for all tracks in a media file:
+
+```
+GET /api/v1/files/local/index?src=assets/clip.mp4
+GET /api/v1/isobmff_files/local/index?src=assets/clip.mp4
+```
+
+The response is the cached fragment index JSON produced by `generateTrackFragmentIndex`. Each track entry includes:
+
+- `type` -- `"video"` or `"audio"`
+- `codec` -- e.g. `"avc1.640029"` or `"mp4a.40.2"`
+- `duration` and `timescale` -- total duration in track timescale units
+- `initSegment` -- byte offset and size of the initialization segment
+- `segments` -- array of `{ offset, size, duration }` for each media segment
+
+### MD5 Hash
+
+Returns the MD5 hash of a local file, used for cache invalidation and asset identity:
+
+```
+GET /api/v1/files/local/md5?src=assets/clip.mp4
+```
+
+Response:
+
+```json
+{ "md5": "a1b2c3d4e5f6..." }
+```
+
+### Track Extraction
+
+Extracts and serves a specific track from a media file:
+
+```
+GET /api/v1/files/local/track?src=assets/clip.mp4&trackId=1
+GET /api/v1/files/local/track?src=assets/clip.mp4&trackId=1&segmentId=0
+GET /api/v1/files/local/track?src=assets/clip.mp4&trackId=-1
+```
+
+Parameters:
+
+- `src` (required) -- path to the source file, resolved relative to `root`
+- `trackId` (required) -- track to extract. `1` for video, `2` for audio, `-1` for the low-resolution scrub track
+- `segmentId` (optional) -- specific segment within the track
+
+Track ID `-1` is a special case that calls `generateScrubTrack` instead of `generateTrack`, producing a 320px-wide low-bitrate version for timeline scrubbing.
+
+## Legacy Endpoints
+
+These routes predate the REST API and are still supported:
+
+| Legacy Route | Equivalent |
+|---|---|
+| `HEAD /@ef-asset/{path}` | `/api/v1/files/local/md5?src={path}` |
+| `/@ef-track-fragment-index/{path}` | `/api/v1/files/local/index?src={path}` |
+| `/@ef-track/{path}?trackId=N` | `/api/v1/files/local/track?src={path}&trackId=N` |
+| `/@ef-scrub-track/{path}` | `/api/v1/files/local/track?src={path}&trackId=-1` |
+
+The `@ef-asset` HEAD request returns the MD5 in the `ETag` header and stores an in-memory MD5-to-filepath mapping for subsequent requests.
+
+## Error Handling
+
+- Missing `src` returns `400` with `{ error: "src parameter is required" }`
+- Missing `trackId` on the track endpoint returns `400`
+- File not found (`ENOENT`) returns `404`
+- Other errors return `500` with the error message
+
+## Debug Logging
+
+```bash
+DEBUG=ef:vite-plugin:isobmff npm run dev
+```

package/dist/skills/editframe-vite-plugin/references/getting-started.md

@@ -0,0 +1,96 @@
+---
+title: Getting Started
+description: Install and configure the Editframe Vite plugin to enable local asset serving, JIT transcoding, and visual testing.
+type: reference
+nav:
+  parent: vite-plugin
+  priority: 1
+api:
+  functions:
+    - name: vitePluginEditframe
+      signature: vitePluginEditframe(options)
+      description: Creates the Editframe Vite plugin instance
+      returns: Plugin
+---
+
+# Getting Started
+
+The Editframe Vite plugin integrates video transcoding, asset management, and visual testing into your Vite development workflow.
+
+## Installation
+
+```bash
+npm install @editframe/vite-plugin
+```
+
+## Configuration
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { vitePluginEditframe } from "@editframe/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    vitePluginEditframe({
+      root: "./src",
+      cacheRoot: "./cache",
+    }),
+  ],
+});
+```
+
+## Configuration Options
+
+### root
+
+The base directory for resolving relative file paths. When the plugin receives a request for a local file, it resolves the path relative to this directory.
+
+```typescript
+vitePluginEditframe({
+  root: "./src",
+  cacheRoot: "./cache",
+})
+```
+
+### cacheRoot
+
+Directory where transcoded video assets are cached. On first request for a video, the plugin transcodes it and stores the result here for fast subsequent loads.
+
+```typescript
+vitePluginEditframe({
+  root: "./src",
+  cacheRoot: "./cache",
+})
+```
+
+## Vitest Configuration
+
+For visual testing with Vitest browser mode, use the vitest-specific entry point:
+
+```typescript
+// vitest.config.ts
+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",
+      },
+    },
+  };
+});
+```