@warpgogol/forge 0.14.0 → 0.16.0

package/skills/fo/ef-brand-video-generator/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ef-brand-video-generator
+description: "Generate brand video compositions from templates — logo animation, intro/outro, brand colors, typography. Use when the operator asks to generate a brand video."
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "generate a brand video"
+  - "create a logo animation"
+  - "brand intro video"
+  - "brand outro video"
+source: domain-knowledge
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Brand Video Generator
+
+Generate brand video compositions from reusable templates. Brand videos typically include logo animations, intro/outro sequences, brand color overlays, and typography that matches brand guidelines.
+
+## Template structure
+
+A brand video composition uses `@editframe/react` components with brand-specific assets:
+
+```tsx
+import { TimelineRoot, Timegroup, Video, Image, Text } from "@editframe/react";
+
+export default function BrandIntro() {
+  return (
+    <TimelineRoot>
+      <Timegroup duration="3s" mode="sequence">
+        <Image src="assets/logo.svg" duration="1s" fit="contain" />
+        <Text
+          text="Your Brand"
+          x="50%"
+          y="50%"
+          fontSize="64px"
+          color="#FF6B00"
+          duration="1s"
+        />
+        <Video src="assets/brand-bg.mp4" fit="cover" duration="1s" />
+      </Timegroup>
+    </TimelineRoot>
+  );
+}
+```
+
+## Brand asset checklist
+
+- **Logo** — SVG or PNG with transparent background
+- **Brand colors** — primary, secondary, accent as CSS color values
+- **Typography** — brand font family, weights, sizes
+- **Background video** — optional branded background clip
+- **Audio** — optional brand jingle or voiceover
+
+## Common brand video patterns
+
+### Logo animation
+
+Animate the logo in with a `Timegroup` using `mode="sequence"`:
+
+```tsx
+<Timegroup duration="2s" mode="sequence">
+  <Image src="assets/logo.svg" duration="0.5s" fit="contain" />
+  <Text text="Your Brand" fontSize="48px" color="#FF6B00" duration="1.5s" />
+</Timegroup>
+```
+
+### Intro/outro pair
+
+Create separate compositions for intro and outro, then combine them in a parent `Timegroup`:
+
+```tsx
+<TimelineRoot>
+  <Timegroup duration="15s" mode="sequence">
+    <BrandIntro />
+    <MainContent />
+    <BrandOutro />
+  </Timegroup>
+</TimelineRoot>
+```
+
+### Brand color overlay
+
+Use a semi-transparent `Image` or `Text` overlay with brand colors:
+
+```tsx
+<Image src="assets/brand-overlay.png" duration="10s" fit="cover" />
+```
+
+## Rendering
+
+Run `ref(forge.yaml bindings.commands.build)` to render the brand video. Use `ref(forge.yaml bindings.commands.validate)` to check the composition before rendering.
+
+## Customization
+
+Each brand video template accepts parameters for logo, colors, text, and timing. Adjust the `duration`, `mode`, and asset paths to match the brand guidelines.

package/skills/fo/ef-composition/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ef-composition
+description: "Guide creating a video composition with Editframe React components — time model, media elements, rendering. Use when the operator asks to create or build a video composition."
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "create a video composition"
+  - "build a video with editframe"
+  - "create a composition"
+  - "add a scene to my video"
+source: https://editframe.com/skills/composition.md
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Video Composition
+
+Build video scenes with React components from `@editframe/react`, for example `<Timegroup>` and `<Video>`. Both HTML web component syntax (`<ef-timegroup>`) and React syntax (`<Timegroup>`) share the same composition model and rendering pipeline.
+
+Web component attributes use kebab-case (`file-id`, `api-host`). React props use camelCase (`fileId`, `apiHost`). Four attributes break this pattern: `sourcein`, `sourceout`, `trimstart`, `trimend` — same lowercase string in both forms.
+
+## Quick Start
+
+```tsx
+import { TimelineRoot, Timegroup, Video, Text, Audio, Captions } from "@editframe/react";
+
+export default function Composition() {
+  return (
+    <TimelineRoot>
+      <Timegroup duration="10s">
+        <Video src="assets/background.mp4" fit="contain" duration="10s" />
+        <Text text="Hello, Editframe!" x="50%" y="50%" fontSize="48px" color="white" duration="5s" />
+        <Audio src="assets/narration.mp3" />
+        <Captions src="assets/captions.vtt" />
+      </Timegroup>
+    </TimelineRoot>
+  );
+}
+```
+
+Run `ref(forge.yaml bindings.commands.devServer)` to preview. Run `ref(forge.yaml bindings.commands.build)` to render.
+
+## Duration units
+
+- `5s` — seconds
+- `500ms` — milliseconds
+- `2.5s` — fractional seconds
+
+## Core concepts
+
+### Time model
+
+A composition is a tree of `Timegroup` elements. The root `Timegroup` defines the composition's total duration. Child elements inherit timing context from their parent.
+
+### Timegroups and sequencing
+
+- **`mode="sequence"`** — children play one after another
+- **`mode="fixed"`** — children play at absolute offsets
+- **`mode="contain"`** (default) — children fit within parent duration
+- **`mode="fit"`** — children scale to fit
+
+### Transitions
+
+Use `ef-transition` or the `transition` prop to declare CSS-like transitions between scenes.
+
+### Scripting
+
+Compositions support inline scripting via `ef-script` or the `script` prop for dynamic behavior during rendering.
+
+## Media elements
+
+- **`Video`** (`ef-video`) — video source with `fit` mode (`contain`, `cover`, `fill`)
+- **`Audio`** (`ef-audio`) — audio source with FFT analysis (`fftSize`, `fftGain`, `fftDecay`)
+- **`Image`** (`ef-image`) — image source
+- **`Text`** (`ef-text`) — text overlay with positioning. Splits text into `ef-text-segment` children (`split="word"`, `split="char"`, `split="line"`). Set `stagger` to delay each segment's start. Segments render in light DOM with `data-active` attribute and `--ef-index`, `--ef-word-index`, `--ef-stagger-offset`, `--ef-seed` custom properties.
+- **`Captions`** (`ef-captions`) — synchronized captions with word-level highlighting. Accepts caption data via `captionsSrc` (URL to JSON), `captionsScript` (inline script id), or `captionsData` (JS property). JSON uses `segments` or `word_segments` shape with `start`/`end` times.
+- **`Waveform`** (`ef-waveform`) — visualizes an `ef-audio` or `ef-video` `target`. Modes: `bars`, `line`, `curve`, `bricks`, `pixel`, `wave`, `spikes`, `roundBars`.
+- **`Surface`** (`ef-surface`) — mirrors another element's pixels onto its own canvas. Set `target` to a canvas or any `HTMLElement` to reuse a video's decoded frames without re-decoding.
+- **`PanZoom`** (`ef-pan-zoom`) — pan and zoom control for video/image elements.
+- **`MotionBlur`** (`ef-motionblur`) — motion blur effect.
+- **`Configuration`** (`ef-configuration`) — opt-in element for API authentication. Add when deploying against the Editframe API: `apiHost` and `signingUrl` for signed-URL auth on cross-origin media, `imageProxy` for cross-origin image proxying. Skip for compositions using only local files.
+
+## Rendering
+
+**Browser export.** Call `renderTimegroupToVideo(timegroup, options)` from `@editframe/elements` to encode a live `ef-timegroup` to a video file. Uses WebCodecs. Key options: `width`/`height`/`fps`, `from`/`to` (export range in seconds), `videoCodec`/`audioCodec`/`videoBitrate`/`audioBitrate`, `target` (mediabunny output target), `signal` (AbortSignal), `onProgress`.
+
+For in-app export from an interactive preview, use `ef-workbench`'s `exportVideo()` method (see the `ef-editor-gui` skill). For CLI/cloud rendering (`editframe render`), the `window.EF_RENDER` path handles offscreen cloning automatically.
+
+**Custom render data.** A CLI or Playwright host can inject arbitrary JSON into `window.EF_RENDER_DATA` before running the composition. Read it with `getRenderData<T>()` (module-level function) or `useRenderData<T>()` (React hook). Use this to parameterize a render without templating the composition.
+
+Run `ref(forge.yaml bindings.commands.build)` to produce the final video output. Use `ref(forge.yaml bindings.commands.validate)` to check composition structure before rendering.
+
+## React
+
+Import components from `@editframe/react`. React props use camelCase. The composition is a standard React component that returns JSX.
+
+### React Three Fiber
+
+Wrap a `<Timegroup>` child in `<CompositionCanvas>` from `@editframe/react/r3f` to get an R3F `<Canvas>` synced to composition time. Read the clock with `useCompositionTime()` which returns `{ time, duration }` in seconds.
+
+```tsx
+<Timegroup mode="fixed" duration="14s">
+  <CompositionCanvas shadows>
+    <MyScene />
+  </CompositionCanvas>
+</Timegroup>
+```
+
+For 3D in a Web Worker, use `OffscreenCompositionCanvas` with `@react-three/offscreen`.
+
+### Server-side rendering
+
+`@editframe/react/server` and `@editframe/elements/server` export composition components and types only — no custom-element registration, no DOM, canvas, or WebCodecs code. Import safely in Next.js or Remix server code. These server entry points do not include GUI components or hooks — render those on the client with `dynamic(() => import("@editframe/react"), { ssr: false })`.
+
+### Package entry points
+
+| Import | Environment | Contains |
+| --- | --- | --- |
+| `@editframe/elements` | Browser | All custom elements, canvas/WebCodecs rendering |
+| `@editframe/elements/server` | Browser, Node, SSR | Types only, plus `getRenderInfo()` (browser-only at runtime) |
+| `@editframe/elements/gui` | Browser | Editor GUI custom elements (timeline, scrubber, handles) |
+| `@editframe/elements/styles.css` | Browser | Base + theme styles |
+| `@editframe/react` | Browser | React composition + GUI components, hooks |
+| `@editframe/react/server` | Browser, Node, SSR | Composition components only, no hooks/GUI |
+| `@editframe/react/r3f` | Browser | `CompositionCanvas`, `OffscreenCompositionCanvas`, `useCompositionTime` |
+
+## Element reference
+
+| Element | React component | Key props |
+| --- | --- | --- |
+| `ef-timegroup` | `Timegroup` | `duration`, `mode`, `fps`, `offset`, `loop` |
+| `ef-video` | `Video` | `src`, `fit`, `duration`, `fileId`, `sourcein`, `sourceout`, `trimstart`, `trimend` |
+| `ef-audio` | `Audio` | `src`, `duration`, `volume`, `mute`, `loop`, `fftSize`, `fftGain` |
+| `ef-text` | `Text` | `text`, `x`, `y`, `fontSize`, `color`, `textAlign`, `duration`, `split`, `stagger` |
+| `ef-captions` | `Captions` | `captionsSrc`, `captionsScript`, `target`, `wordStyle`, `duration` |
+| `ef-image` | `Image` | `src`, `fit`, `duration`, `fileId` |
+| `ef-waveform` | `Waveform` | `target`, `mode`, `color` |
+| `ef-surface` | `Surface` | `target` |
+| `ef-pan-zoom` | `PanZoom` | `target`, `pan`, `zoom` |
+| `ef-configuration` | `Configuration` | `apiHost`, `signingUrl`, `imageProxy` |
+| `ef-transition` | `Transition` | `type`, `duration` |
+| `ef-script` | `Script` | `src`, `inline` |

package/skills/fo/ef-composition-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ef-composition-review
-description: Review an Editframe HTML composition for time model correctness, accessibility, and best practices
+description: Review an Editframe React composition for time model correctness, accessibility, and best practices
 invocation: user
 category: fo
 concerns: read-only
@@ -14,41 +14,41 @@ languagePolicy: ref(PREFERENCES.md)
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
-A read-only review of an Editframe HTML composition file. The skill checks time model correctness, accessibility, asset references, automated invariants, and manual best practices. It does **not** modify any file — it produces a structured report and stops.
+A read-only review of an Editframe React composition file. The skill checks time model correctness, accessibility, asset references, automated invariants, and manual best practices. It does **not** modify any file — it produces a structured report and stops.
 
 ## Scope
 
-This skill reviews `.html` composition files that use Editframe custom elements (`ef-timegroup`, `ef-video`, `ef-audio`, `ef-text`, `ef-captions`). It is designed for projects using the `editframe-html` stack profile.
+This skill reviews `.tsx` composition files that use `@editframe/react` components (`TimelineRoot`, `Timegroup`, `Video`, `Audio`, `Text`, `Captions`). It is designed for projects using the `editframe` stack profile.
 
 ## Process
 
 ### 1. Empty state check
 
-Scan the `compositions/` directory for `.html` files. If no compositions are found, report "No compositions found — nothing to review" and stop. Do not report false positives on an empty project.
+Scan the `compositions/` directory for `.tsx` files. If no compositions are found, report "No compositions found — nothing to review" and stop. Do not report false positives on an empty project.
 
 ### 2. Time model review
 
 For each composition file:
 
-- Check that the root `ef-timegroup` declares a `duration` attribute or uses `mode="contain"` / `mode="fit"`.
+- Check that the root `Timegroup` declares a `duration` prop or uses `mode="contain"` / `mode="fit"`.
 - Check that all `duration` and `offset` values are valid CSS time strings (e.g. `5s`, `300ms`, `2.5s`).
 - Check that `mode` values are one of: `sequence`, `fixed`, `contain`, `fit`.
 - Check that `fps` is a positive integer (e.g. `30`, `60`).
-- Check that `loop` is only present on the root `ef-timegroup` — nested timegroups should not loop.
+- Check that `loop` is only present on the root `Timegroup` — nested Timegroups should not loop.
 
 ### 3. Accessibility review
 
-- Check that all `ef-audio` elements with speech content have corresponding `ef-captions` elements.
-- Check that `ef-text` elements have sufficient contrast between foreground and background colors (if declared via inline styles or CSS classes).
+- Check that all `Audio` components with speech content have corresponding `Captions` components.
+- Check that `Text` components have sufficient contrast between foreground and background colors (if declared via inline styles or CSS classes).
 
 ### 4. Asset reference review
 
-- Check that all `src` attributes in `ef-video`, `ef-audio`, and `ef-image` elements point to files that exist in the `assets/` directory.
+- Check that all `src` props in `Video`, `Audio`, and `Image` components point to files that exist in the `assets/` directory.
 - Check that asset filenames use kebab-case (lowercase letters, digits, hyphens only).
 
 ### 5. Invariant check
 
-Run `forge doctor` to check all profile invariants automatically. For the `editframe-html` profile, this covers VIDEO-01 through VIDEO-09 (filename conventions, scene fit modes, captions, and time model invariants). Review the output and include any violations in the report.
+Run `forge doctor` to check all profile invariants automatically. For the `editframe` profile, this covers VIDEO-01 through VIDEO-09 (filename conventions, scene fit modes, captions, and time model invariants). Review the output and include any violations in the report.
 
 ### 6. Manual best practices
 

package/skills/fo/ef-dev-server/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: ef-dev-server
+description: "Set up and manage the Editframe dev server for live preview and local asset serving. Use when the operator asks to set up or configure the Editframe dev server."
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "set up editframe dev server"
+  - "configure editframe preview"
+  - "local asset serving"
+  - "dev server not working"
+source: https://editframe.com/skills/dev-server.md
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Dev Server
+
+The Editframe dev server provides JIT video transcoding, local image and caption serving, and a local files API that mirrors the production files API. It integrates with Vite, Next.js, or any framework-agnostic setup.
+
+## Vite setup
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePluginEditframe } from "@editframe/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    vitePluginEditframe({
+      root: "./src",
+      cacheRoot: "./cache",
+    }),
+  ],
+});
+```
+
+The plugin mounts onto Vite's own dev server. Compositions make same-origin requests. No separate port and no CORS setup are necessary.
+
+## Next.js setup
+
+```javascript
+// next.config.mjs
+import { withEditframe } from "@editframe/nextjs-plugin";
+
+export default withEditframe(
+  { root: "./src", cacheRoot: "./cache" },
+  {
+    // your existing Next.js config
+  },
+);
+```
+
+`withEditframe` starts a sidecar HTTP server next to `next dev`, on port 3099 by default. Override the port with a `port` option. It also adds `rewrites()` rules that proxy Editframe's requests to that sidecar, so compositions still make same-origin requests. Run `next dev` as usual. No other setup is necessary.
+
+The sidecar does not start in production. Deploy against real media (cloud renders, uploaded files) instead.
+
+## Framework-agnostic setup
+
+For a toolchain with no Vite or Next.js integration, call `@editframe/dev-server` directly:
+
+```typescript
+import { createEditframeDevServer, createProdEfHandlers } from "@editframe/dev-server";
+import {
+  generateTrack,
+  generateScrubTrack,
+  generateTrackFragmentIndex,
+  cacheImage,
+  findOrCreateCaptions,
+  md5FilePath,
+} from "@editframe/assets";
+import { Client, createURLToken } from "@editframe/api";
+
+const server = createEditframeDevServer(
+  { root: "./src", cacheRoot: "./cache" },
+  { generateTrack, generateScrubTrack, generateTrackFragmentIndex, cacheImage, findOrCreateCaptions, md5FilePath },
+  createProdEfHandlers({
+    createURLToken,
+    getClient: () => new Client(process.env.EF_TOKEN),
+  }),
+);
+
+server.listen(3001, () => console.log("Editframe dev server running on http://localhost:3001"));
+```
+
+## What it enables
+
+- **JIT video transcoding** — reference a local video file directly (`<Video src="clip.mp4" />`). The dev server transcodes it into streamable segments on first request, then serves cached segments.
+- **Local image and caption serving** — `<Image>` and caption generation work against local files.
+- **A local files API** that mirrors the shape of the production files API.
+- **URL signing** — `ef-configuration`'s default `signing-url` forwards to the real Editframe cloud API. Set `EF_TOKEN` before starting the dev server. Set `EF_HOST` to point at a non-default API host.
+
+## Framework-agnostic middleware integration
+
+If your toolchain already exposes a Connect-compatible middleware stack (Express, Connect, or a custom Vite integration), call `createEditframeRouter(...)` with the same three arguments instead. Mount the result with `.use()`. `createEditframeDevServer` wraps that same router in its own standalone `http.Server`, for toolchains with no middleware stack of their own.
+
+## Visual regression testing (Vite only)
+
+The Vite plugin supports visual regression testing. Configure snapshot directories and thresholds in the plugin options.
+
+## Debug logging
+
+Set `DEBUG=editframe:*` to enable verbose logging from the dev server and plugin.

package/skills/fo/ef-editor-gui/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: ef-editor-gui
+description: "Configure the Editframe editor GUI for visual composition editing — timeline, scrubber, canvas, preview controls. Use when the operator asks to set up or use the Editframe editor."
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "open editframe editor"
+  - "set up editor gui"
+  - "add timeline controls"
+  - "visual editing"
+source: https://editframe.com/skills/editor-gui.md
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Editor Toolkit
+
+The Editframe editor toolkit provides visual composition editing controls: timeline, scrubber, canvas, preview, playback, and transformation.
+
+## Quick start
+
+```html
+<ef-timegroup id="my-video">
+  <ef-video src="/video.mp4"></ef-video>
+</ef-timegroup>
+
+<ef-controls target="my-video">
+  <ef-toggle-play></ef-toggle-play>
+  <ef-scrubber></ef-scrubber>
+  <ef-time-display></ef-time-display>
+</ef-controls>
+```
+
+## Core concepts: target and bridge
+
+Each playback control (`ef-play`, `ef-pause`, `ef-toggle-play`, `ef-toggle-loop`, `ef-volume`, `ef-mute`, `ef-scrubber`, `ef-time-display`) resolves the composition it drives in this order:
+
+1. Its own `target="id-or-selector"` attribute, if set.
+2. Walks up through ancestor `ef-controls`, `ef-preview`, and `ef-configuration` elements. An ancestor with its own `target` resolves there. A bare `ef-configuration` ancestor resolves to itself.
+3. As a last resort, resolves to the nearest enclosing temporal root.
+
+`ef-controls` is a pure proxy — it renders nothing itself but gives descendant controls a shared `target`.
+
+## Preview and canvas
+
+- **`ef-preview`** — renders a live preview of the composition
+- **`ef-canvas`** — interactive canvas with selection state
+
+## Playback and display controls
+
+- **`ef-play`** / **`ef-pause`** / **`ef-toggle-play`** — playback controls
+- **`ef-toggle-loop`** — toggle loop mode
+- **`ef-volume`** / **`ef-mute`** — audio controls
+- **`ef-time-display`** — current time / total time display
+- **`ef-scrubber`** — seekable timeline scrubber
+- **`ef-fullscreen`** — fullscreen toggle
+- **`ef-pip`** — picture-in-picture toggle
+
+## Timeline
+
+- **`ef-timeline`** — timeline container with rows
+- **`ef-timeline-row`** — a single track row
+- **`ef-timeline-ruler`** — time ruler with markers
+- **`ef-composition-thumbnail-strip`** — thumbnail overview of the composition
+
+## Transform and manipulation
+
+- **`ef-transform-handles`** — drag, resize, rotate handles for elements
+- **`ef-trim-handles`** — trim start/end of video clips
+- **`ef-fit-scale`** — fit or scale the canvas to the viewport
+
+## Overlay system
+
+- **`ef-overlay-layer`** — overlay container
+- **`ef-overlay-item`** — individual overlay panel
+
+## Editor shells
+
+- **`ef-workbench`** — full editor layout with panels
+- **`ef-tree`** / **`ef-tree-item`** — hierarchy tree of composition elements
+- **`ef-hierarchy`** / **`ef-hierarchy-item`** — alternative hierarchy view with selection bridge
+
+## Element reference
+
+| Element                          | Purpose                                          |
+| -------------------------------- | ------------------------------------------------ |
+| `ef-canvas`                      | Interactive composition canvas                   |
+| `ef-canvas-selection-box`        | Selection rectangle overlay on canvas            |
+| `ef-composition-thumbnail-strip` | Thumbnail overview of the composition            |
+| `ef-controls`                    | Proxy container for shared target                |
+| `ef-dial`                        | Rotary dial control for parameters               |
+| `ef-fit-scale`                   | Fit or scale canvas to viewport                  |
+| `ef-fullscreen`                  | Fullscreen toggle                                |
+| `ef-hierarchy`                   | Alternative hierarchy view with selection bridge |
+| `ef-hierarchy-item`              | Item in hierarchy view                           |
+| `ef-mute`                        | Mute toggle                                      |
+| `ef-overlay-item`                | Individual overlay panel                         |
+| `ef-overlay-layer`               | Overlay container                                |
+| `ef-pause`                       | Pause button                                     |
+| `ef-pip`                         | Picture-in-picture toggle                        |
+| `ef-play`                        | Play button                                      |
+| `ef-preview`                     | Live composition preview                         |
+| `ef-resolution`                  | Resolution selector                              |
+| `ef-scrubber`                    | Seekable timeline scrubber                       |
+| `ef-thumbnail-strip`             | Thumbnail strip for timeline                     |
+| `ef-time-display`                | Time display                                     |
+| `ef-timeline`                    | Timeline container                               |
+| `ef-timeline-row`                | Single track row in timeline                     |
+| `ef-timeline-ruler`              | Time ruler with markers                          |
+| `ef-toggle-loop`                 | Toggle loop mode                                 |
+| `ef-toggle-play`                 | Play/pause toggle                                |
+| `ef-transform-handles`           | Drag, resize, rotate handles for elements        |
+| `ef-tree`                        | Composition hierarchy tree                       |
+| `ef-tree-item`                   | Item in hierarchy tree                           |
+| `ef-trim-handles`                | Trim start/end of video clips                    |
+| `ef-volume`                      | Volume control                                   |
+| `ef-waveform-strip`              | Audio waveform strip for timeline                |
+| `ef-workbench`                   | Full editor layout with panels                   |
+
+### `ef-workbench`
+
+Composes a hierarchy panel, a canvas and selection view, a timeline, and transport controls into one panel layout (DOM preview mode only).
+
+**Attributes:** `rendering` (boolean, collapses to bare stage during native render), `resolution` (string, e.g. `"1920x1080"`).
+
+**Methods:** `exportVideo(options?)` — renders the composition to an MP4 through an offscreen clone. Dispatches `export-start`, `export-progress`, `export-complete`, `export-error` events. Options: `width`, `height`, `fps`, `from`, `to`, `videoCodec`, `audioCodec`, `videoBitrate`, `audioBitrate`, `audioSampleRate`.

package/skills/fo/ef-motion-design/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ef-motion-design
+description: "Apply motion design patterns to Editframe compositions — transitions, animations, easing, kinetic typography. Use when the operator asks to add motion design or animation patterns."
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "add motion design"
+  - "animate text"
+  - "kinetic typography"
+  - "transition between scenes"
+source: domain-knowledge
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Motion Design
+
+Motion design patterns for Editframe compositions: transitions, animations, easing, and kinetic typography. These patterns enhance video compositions with professional motion graphics.
+
+## Transitions
+
+Use `ef-transition` or the `transition` prop to declare CSS-like transitions between scenes:
+
+```tsx
+<Timegroup mode="sequence">
+  <Video src="assets/scene1.mp4" duration="5s" transition="fade" />
+  <Video src="assets/scene2.mp4" duration="5s" transition="slide-left" />
+</Timegroup>
+```
+
+### Transition types
+
+- **`fade`** — cross-fade between elements
+- **`slide-left`** / **`slide-right`** — slide in from left/right
+- **`slide-up`** / **`slide-down`** — slide in from top/bottom
+- **`zoom-in`** / **`zoom-out`** — scale transition
+- **`wipe`** — directional wipe
+
+## Kinetic typography
+
+Animate text with `ef-text` or the `Text` component using timing and positioning:
+
+```tsx
+<Timegroup mode="sequence">
+  <Text text="First" x="50%" y="50%" fontSize="72px" duration="1s" />
+  <Text text="Second" x="50%" y="50%" fontSize="72px" duration="1s" />
+  <Text text="Third" x="50%" y="50%" fontSize="72px" duration="1s" />
+</Timegroup>
+```
+
+### Text animation patterns
+
+- **Sequential reveal** — words appear one after another in a `mode="sequence"` Timegroup
+- **Position animation** — animate `x`/`y` props across time
+- **Scale animation** — animate `fontSize` across time
+- **Color transitions** — animate `color` across time
+
+## Easing
+
+Editframe supports CSS easing functions for transitions and animations:
+
+- `ease` (default)
+- `ease-in`
+- `ease-out`
+- `ease-in-out`
+- `linear`
+- `cubic-bezier(x1, y1, x2, y2)` — custom bezier curve
+
+## Pan and zoom
+
+Use `ef-pan-zoom` or the `PanZoom` component for Ken Burns-style effects:
+
+```tsx
+<PanZoom
+  src="assets/photo.jpg"
+  duration="5s"
+  startX="0%"
+  startY="0%"
+  endX="100%"
+  endY="100%"
+  startScale="1"
+  endScale="1.5"
+/>
+```
+
+## Motion blur
+
+Apply motion blur to moving elements with `ef-motionblur` or the `MotionBlur` component:
+
+```tsx
+<MotionBlur intensity="0.5">
+  <Video src="assets/fast-pan.mp4" duration="3s" />
+</MotionBlur>
+```
+
+## CSS variables for time-based animation
+
+Editframe compositions support CSS custom properties for time-based values, enabling complex animation sequences without JavaScript:
+
+```css
+:root {
+  --scene-duration: 5s;
+  --transition-duration: 0.5s;
+}
+```
+
+## Best practices
+
+- Keep transitions consistent within a composition — use 1-2 transition types
+- Match transition duration to content pacing (fast cuts for energy, slow for drama)
+- Use kinetic typography sparingly — it draws attention
+- Preview with `ref(forge.yaml bindings.commands.devServer)` before rendering
+- Run `ref(forge.yaml bindings.commands.validate)` to check composition structure