@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-editor-gui/references/workbench.md

@@ -0,0 +1,453 @@
+---
+title: Workbench Element
+description: Full-featured video editor layout combining preview, timeline, hierarchy panel, and export controls in one component.
+type: reference
+nav:
+  parent: "Editor Shells"
+  priority: 10
+api:
+  attributes:
+    - name: rendering
+      type: boolean
+      default: false
+      description: Enable render-only mode (no UI)
+  properties:
+    - name: rendering
+      type: boolean
+      default: false
+      description: Enable render-only mode (no UI)
+  methods:
+    - name: setPreviewPresentationMode()
+      signature: setPreviewPresentationMode(mode)
+      description: Set preview rendering mode ("dom" or "canvas")
+      returns: void
+    - name: getPreviewPresentationMode()
+      signature: getPreviewPresentationMode()
+      description: Get current preview rendering mode
+      returns: PreviewPresentationMode
+    - name: startExport()
+      signature: startExport(options)
+      description: Start video export with progress tracking
+      returns: Promise<void>
+    - name: cancelExport()
+      signature: cancelExport()
+      description: Cancel the current export
+      returns: void
+react:
+  generate: true
+  componentName: Workbench
+  importPath: "@editframe/react"
+  additionalProps:
+    - name: className
+      type: string
+      description: CSS classes for styling
+  nav:
+    parent: "Tools"
+    priority: 42
+    related: ["preview", "controls"]
+---
+
+<!-- html-only -->
+# ef-workbench
+<!-- /html-only -->
+<!-- react-only -->
+# Workbench
+<!-- /react-only -->
+
+<!-- html-only -->
+Complete video editor interface with preview, timeline, hierarchy panel, and export controls.
+<!-- /html-only -->
+<!-- react-only -->
+Full timeline editor UI with hierarchy and timeline views.
+<!-- /react-only -->
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { Workbench } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Basic Usage
+
+<!-- html-only -->
+Wrap a composition to add a full editing interface:
+
+```html live
+<ef-workbench class="w-full h-screen">
+  <ef-pan-zoom slot="canvas">
+    <ef-fit-scale>
+      <ef-timegroup mode="sequence" class="w-[720px] h-[480px] bg-black">
+        <ef-timegroup mode="fixed" duration="3s" class="flex items-center justify-center">
+          <ef-text duration="3s" class="text-white text-4xl">First Scene</ef-text>
+        </ef-timegroup>
+        <ef-timegroup mode="fixed" duration="3s" class="flex items-center justify-center">
+          <ef-text duration="3s" class="text-white text-4xl">Second Scene</ef-text>
+        </ef-timegroup>
+      </ef-timegroup>
+    </ef-fit-scale>
+  </ef-pan-zoom>
+
+  <ef-hierarchy slot="hierarchy"></ef-hierarchy>
+
+  <div slot="timeline" class="h-full flex flex-col">
+    <ef-controls class="flex items-center gap-2 p-2 border-b border-gray-700">
+      <ef-toggle-play>
+        <button slot="play" class="px-3 py-1 bg-blue-600 text-white rounded">Play</button>
+        <button slot="pause" class="px-3 py-1 bg-gray-600 text-white rounded">Pause</button>
+      </ef-toggle-play>
+      <ef-time-display class="text-sm text-gray-300"></ef-time-display>
+    </ef-controls>
+    <ef-filmstrip class="flex-1"></ef-filmstrip>
+  </div>
+</ef-workbench>
+```
+<!-- /html-only -->
+<!-- react-only -->
+The `workbench` prop on the root `Timegroup` automatically enables the workbench UI:
+
+```tsx
+import { Timegroup, Video, Text } from "@editframe/react";
+
+export const Video = () => {
+  return (
+    <Timegroup
+      workbench  // Enables workbench UI
+      mode="sequence"
+      className="w-[1920px] h-[1080px] bg-black"
+    >
+      <Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
+        <Video src="/assets/intro.mp4" className="size-full" />
+        <Text duration="5s" className="text-white text-4xl">Title</Text>
+      </Timegroup>
+    </Timegroup>
+  );
+};
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+## Workbench Layout
+
+The workbench provides a three-panel layout:
+
+- **Canvas** (center) - Preview with pan/zoom controls
+- **Hierarchy** (left sidebar) - Layer panel showing composition structure
+- **Timeline** (bottom) - Playback controls and timeline visualization
+
+## Slots
+
+### canvas
+
+Main preview area. Should contain a timegroup wrapped in `ef-pan-zoom` and `ef-fit-scale`:
+
+```html
+<ef-pan-zoom slot="canvas">
+  <ef-fit-scale>
+    <ef-timegroup mode="contain" class="w-[1920px] h-[1080px]">
+      <!-- composition content -->
+    </ef-timegroup>
+  </ef-fit-scale>
+</ef-pan-zoom>
+```
+
+### hierarchy
+
+Left sidebar for layer management:
+
+```html
+<ef-hierarchy slot="hierarchy"></ef-hierarchy>
+```
+
+### timeline
+
+Bottom panel for playback controls and timeline:
+
+```html
+<div slot="timeline" class="flex flex-col">
+  <ef-controls class="border-b">
+    <!-- playback controls -->
+  </ef-controls>
+  <ef-filmstrip class="flex-1"></ef-filmstrip>
+</div>
+```
+<!-- /html-only -->
+
+<!-- react-only -->
+## Standalone Workbench Component
+
+Use `Workbench` component for custom layouts:
+
+```tsx
+import { Preview, Controls, Workbench } from "@editframe/react";
+
+export const Editor = () => {
+  return (
+    <div className="h-screen flex flex-col">
+      {/* Top: Preview */}
+      <div className="flex-1 flex items-center justify-center p-4 bg-gray-900">
+        <Preview className="max-w-[1280px] w-full aspect-video bg-black" />
+      </div>
+
+      {/* Middle: Controls */}
+      <div className="px-4 py-2 bg-gray-800">
+        <Controls />
+      </div>
+
+      {/* Bottom: Timeline */}
+      <div className="h-80 border-t border-gray-700">
+        <Workbench className="w-full h-full" />
+      </div>
+    </div>
+  );
+};
+```
+
+## Features
+
+The workbench provides:
+
+- **Timeline view** - Visual timeline with all elements
+- **Hierarchy view** - Tree structure of your composition
+- **Playhead scrubbing** - Click timeline to seek
+- **Element selection** - Click elements to select
+- **Duration visualization** - See timing of all elements
+<!-- /react-only -->
+
+## Preview Modes
+
+<!-- html-only -->
+Workbench supports two preview rendering modes:
+
+- **DOM mode** (default) - Shows the real timegroup DOM directly
+- **Canvas mode** - Renders to canvas each frame for consistent output
+
+Toggle modes via the toolbar settings button.
+<!-- /html-only -->
+<!-- react-only -->
+The workbench supports different preview rendering modes:
+
+```tsx
+import { setPreviewPresentationMode, getPreviewPresentationMode } from "@editframe/react";
+
+// Set DOM mode (default) - shows original DOM content
+setPreviewPresentationMode("dom");
+
+// Set Canvas mode - renders to canvas using active rendering path
+setPreviewPresentationMode("canvas");
+
+// Get current mode
+const mode = getPreviewPresentationMode(); // "dom" | "canvas"
+```
+
+### DOM Mode
+
+Shows the original DOM content directly. This is the default and recommended for most use cases:
+
+```tsx
+import { setPreviewPresentationMode } from "@editframe/react";
+
+setPreviewPresentationMode("dom");
+```
+
+### Canvas Mode
+
+Renders to canvas using the active rendering path. Useful for testing how content will appear in the final render:
+
+```tsx
+import { setPreviewPresentationMode } from "@editframe/react";
+
+setPreviewPresentationMode("canvas");
+```
+<!-- /react-only -->
+
+## Render Mode
+
+<!-- html-only -->
+When `rendering="true"`, workbench hides the UI and shows only the canvas. Used for server-side rendering:
+
+```html
+<ef-workbench rendering>
+  <ef-timegroup slot="canvas" mode="contain">
+    <!-- composition -->
+  </ef-timegroup>
+</ef-workbench>
+```
+<!-- /html-only -->
+<!-- react-only -->
+The `rendering` property indicates when the composition is in render mode (used by CLI/export flows):
+
+```tsx
+import { Timegroup } from "@editframe/react";
+
+<Timegroup
+  workbench
+  rendering={isExporting}  // Set to true during export
+  mode="sequence"
+  className="w-[1920px] h-[1080px]"
+>
+  {/* Composition */}
+</Timegroup>
+```
+
+When `rendering={true}`:
+- The workbench UI is hidden
+- The composition is optimized for export
+- Frame generation is enabled
+- Used by CLI tools and server-side rendering
+<!-- /react-only -->
+
+<!-- html-only -->
+## Export
+
+Click the Export button in the toolbar to render the composition to video. Configure export settings in the popup:
+
+- **Scale** - Resolution multiplier (25%, 50%, 75%, 100%)
+- **Audio** - Include audio tracks
+- **Range** - Export full duration or custom in/out range
+
+Export uses browser WebCodecs API for local rendering. Progress updates show:
+- Current frame / total frames
+- Elapsed time / total duration
+- Render speed multiplier
+- Estimated time remaining
+- Live preview thumbnail
+
+## Theme
+
+Workbench respects system theme by default. Toggle between light, dark, and system modes via the toolbar button.
+
+## Performance Stats
+
+Enable the performance overlay via toolbar settings to see:
+- **FPS** - Actual frame rate
+- **Render** - Average render time per frame (canvas mode)
+- **Headroom** - Time budget remaining (canvas mode)
+- **Resolution** - Current render resolution
+- **Scale** - Resolution scale percentage (canvas mode)
+- **CPU** - Compute pressure state
+- **State** - Motion state (playing, scrubbing, or at rest)
+
+Auto resolution mode dynamically adjusts render resolution during playback to maintain smooth performance.
+
+## Fit to Content
+
+Click the fit-to-content button in the toolbar to reset zoom and center the composition.
+<!-- /html-only -->
+
+<!-- react-only -->
+## Full Editor Layout
+
+```tsx
+import {
+  Configuration,
+  Preview,
+  Controls,
+  Workbench,
+  Timegroup,
+  Video,
+  Audio,
+  Text
+} from "@editframe/react";
+
+export const FullEditor = () => {
+  return (
+    <Configuration mediaEngine="local">
+      <div className="h-screen flex flex-col bg-gray-950">
+        {/* Header */}
+        <header className="h-14 bg-gray-900 border-b border-gray-800 flex items-center px-4">
+          <h1 className="text-white text-xl font-bold">Video Editor</h1>
+        </header>
+
+        {/* Main content */}
+        <div className="flex-1 flex flex-col">
+          {/* Preview area */}
+          <div className="flex-1 flex items-center justify-center p-8 bg-gray-900">
+            <Preview className="max-w-[1280px] w-full aspect-video bg-black rounded-lg shadow-2xl" />
+          </div>
+
+          {/* Controls */}
+          <div className="bg-gray-800 border-y border-gray-700">
+            <div className="max-w-4xl mx-auto px-4 py-3">
+              <Controls />
+            </div>
+          </div>
+
+          {/* Timeline */}
+          <div className="h-80 bg-gray-900 border-t border-gray-800">
+            <Workbench className="w-full h-full" />
+          </div>
+        </div>
+
+        {/* Hidden composition */}
+        <div className="hidden">
+          <Timegroup workbench mode="sequence" className="w-[1920px] h-[1080px]">
+            <Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
+              <Video src="/assets/video.mp4" className="size-full object-cover" />
+              <Text duration="5s" className="absolute top-8 text-white text-4xl">
+                Title
+              </Text>
+              <Audio src="/assets/music.mp3" volume={0.3} />
+            </Timegroup>
+          </Timegroup>
+        </div>
+      </div>
+    </Configuration>
+  );
+};
+```
+
+## Resizable Timeline
+
+```tsx
+import { useState } from "react";
+
+export const ResizableEditor = () => {
+  const [timelineHeight, setTimelineHeight] = useState(320);
+
+  return (
+    <div className="h-screen flex flex-col">
+      <div className="flex-1">
+        <Preview className="w-full h-full" />
+      </div>
+
+      <div style={{ height: `${timelineHeight}px` }} className="border-t">
+        <Workbench className="w-full h-full" />
+      </div>
+    </div>
+  );
+};
+```
+
+## Side-by-Side Layout
+
+```tsx
+export const SideBySideEditor = () => {
+  return (
+    <div className="h-screen grid grid-cols-2">
+      {/* Left: Preview & Controls */}
+      <div className="flex flex-col">
+        <Preview className="flex-1 bg-black" />
+        <Controls className="bg-gray-800 p-4" />
+      </div>
+
+      {/* Right: Timeline */}
+      <div className="border-l border-gray-700">
+        <Workbench className="w-full h-full" />
+      </div>
+    </div>
+  );
+};
+```
+
+## Notes
+
+- The `workbench` prop on root `Timegroup` enables automatic UI
+- Use `Workbench` component for custom layouts
+- Timeline shows all elements and their timing
+- Hierarchy shows nested structure
+- Interactive scrubbing and element selection
+- Preview modes are persisted to localStorage
+- `rendering` state is typically controlled by export/CLI workflows
+<!-- /react-only -->

package/dist/skills/editframe-motion-design/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: editframe-motion-design
+title: Motion Design
+description: Professional motion graphics for video content — animations, transitions, title sequences, and time-based visual design for video production.
+order: 40
+license: MIT
+status: draft
+metadata:
+  author: editframe
+  version: "2.0"
+---
+
+# Motion Design
+
+**For Video Content Creation**
+
+Motion serves communication, not decoration. Every animation must guide attention and express intent.
+
+## The 4 Core Concepts
+
+All motion design derives from these four ideas:
+
+### [1. Intent → Strategy](references/1-intent.md)
+Message + Emotion → Motion characteristics
+
+What should the viewer feel? This determines material selection and personality.
+
+### [2. Physics Model](references/2-physics-model.md)
+Material + Weight + Force → Timing + Deformation + Easing
+
+Material properties determine how objects move. Contains reference tables for durations, deformation, bounce, and easing curves.
+
+### [3. Attention Flow](references/3-attention.md)
+One focus at a time. Sequence everything.
+
+Plan viewer focus flow. Contains stagger patterns, timing, and sequencing strategies.
+
+### [4. Systematic Iteration](references/4-process.md)
+Broad strokes → Easing → Secondary → Polish
+
+Don't perfect details before structure is right. Process for iterating from concept to polish.
+
+## Decision Framework
+
+```
+START: What's the message?
+  ↓
+INTENT: What should viewer feel?
+  → Determines material personality
+  ↓
+PHYSICS MODEL: What material expresses that?
+  → Material determines timing/deformation/bounce
+  → Weight scales duration
+  → Force determines easing
+  ↓
+ATTENTION: What's the viewing sequence?
+  → Determines stagger patterns
+  → Ensures one focus at a time
+  ↓
+PROCESS: Iterate systematically
+  → Broad strokes → Easing → Secondary → Polish
+```
+
+## Core Rules
+
+1. **One focus at a time** - Never animate unrelated elements simultaneously
+2. **Intent first** - Every animation serves the message
+3. **Material consistency** - All elements of same material move similarly
+4. **Exits faster than entrances** - 30-40% shorter duration
+5. **Respect physics** - Unless intentionally stylized
+
+## Video-Specific Considerations
+
+- Work in **frames**, not just milliseconds (24fps, 30fps, 60fps)
+- Consider **composition duration** and pacing for full sequence
+- Think about **viewer distance** (mobile vs TV vs cinema)
+- Plan for **audio sync** when applicable
+- Account for **export format** constraints
+
+## Editframe Implementation
+
+Motion principles map to specific Editframe mechanisms. Always check [0-editframe.md](references/0-editframe.md) first — it translates every concept to actual syntax.
+
+| Motion concept | Editframe mechanism |
+|---------------|---------------------|
+| Easing / physics | CSS `animation-timing-function` + `@keyframes` |
+| Stagger | `ef-text split="word"` + `--ef-word-index` CSS var |
+| Progress-driven | `--ef-progress` CSS var (0–1, updates every frame) |
+| Per-frame procedural | `addFrameTask((ownCurrentTimeMs, durationMs) => {})` on timegroup |
+| Exit timing | `--ef-transition-out-start` CSS var |
+| Scene overlap | `overlap="1s"` on parent `ef-timegroup[mode="sequence"]` |
+
+**`addFrameTask` rules:** callback must be a pure function of `ownCurrentTimeMs` — no `Date.now()`, no `Math.random()`. Renders must be deterministic.
+
+## Quick Reference
+
+For detailed tables and patterns, see:
+- **Editframe implementation**: [0-editframe.md](references/0-editframe.md)
+- **Material properties & durations**: [2-physics-model.md](references/2-physics-model.md)
+- **Stagger delays & patterns**: [3-attention.md](references/3-attention.md)
+- **Iteration workflow**: [4-process.md](references/4-process.md)