@warpgogol/forge 0.13.0 → 0.15.0

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

@@ -0,0 +1,66 @@
+---
+name: ef-composition-review
+description: Review an Editframe React composition for time model correctness, accessibility, and best practices
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-composition-review
+
+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 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 `.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 `.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 `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 `Timegroup` — nested Timegroups should not loop.
+
+### 3. Accessibility review
+
+- 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` 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` 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
+
+Review aspects not covered by automated invariants:
+
+- Scene composition quality — are scenes well-structured with clear transitions?
+- Narrative pacing — does the timing flow naturally?
+- Visual hierarchy — are text elements readable and well-positioned?
+- Asset reuse — are assets reused efficiently across scenes?
+
+Do not duplicate checks that `forge doctor` already performs.
+
+### 7. Report
+
+Summarize findings organized by category (time model, accessibility, assets, invariants, best practices). For each finding, include the file path, line number (if applicable), severity (error / warning / info), and a specific recommendation.

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

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

@@ -0,0 +1,77 @@
+---
+name: ef-onboard
+description: Onboard a new Editframe video project — check prerequisites, discover requirements, scaffold, and start preview. Use when the operator asks to create a new video project.
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "create a new editframe project"
+  - "start a new video project"
+  - "build a video with editframe"
+  - "create a video composition"
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-onboard
+
+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.
+
+Guide the operator through creating a new Editframe video project within a Forge-managed workspace. The skill covers prerequisites check, discovery, scaffold, domain knowledge reading, and build + preview.
+
+## Process
+
+### 1. Prerequisites check
+
+- **Node.js 18+**: Run `node --version`. If missing or below 18, direct the operator to `https://nodejs.org/en/download/` or install via the system package manager.
+- **FFmpeg**: Run `ffmpeg -version`. If missing, direct the operator to `https://ffmpeg.org/download.html` or install via the system package manager (`apt install ffmpeg`, `brew install ffmpeg`).
+- If either prerequisite is missing and cannot be installed automatically, stop and ask the operator to install it manually.
+
+### 2. Discovery
+
+Ask the operator:
+
+1. **Project type**:
+   - Single video (product demo, social media video, personal project)
+   - Video template (reusable with different assets — birthday card, wedding announcement)
+   - Video editing tool (custom editor built with Editframe as the engine)
+   - Video workflow automation (script that generates videos from triggers)
+   - Something else (ask them to describe it)
+
+2. **Existing assets**:
+   - Video clips, images, or audio files (file paths or URLs)
+   - Website URLs to use as content source — if provided, download and cache all relevant assets locally before building
+   - No existing assets — start from scratch
+
+3. **Node.js/React libraries**: Ask if the operator has any libraries in mind (e.g. AnimeJS for animations, Tailwind for styling).
+
+Prioritize getting all answers before starting to build. This minimizes wait time for the operator.
+
+### 3. Scaffold
+
+Run `forge create --profile editframe` to scaffold the project with Forge governance (invariants, AGENTS.md templates, forge skills). The `editframe` profile scaffolds a React + TypeScript + Vite project with `@editframe/react` pre-configured.
+
+If `forge create` fails (missing profile, network error, permission issue), report the error to the operator and stop. Do not proceed to subsequent steps without a scaffolded project.
+
+### 4. Read domain knowledge
+
+Before building, the agent MUST read the vendored Editframe domain skills. These are bundled with `@warpgogol/forge` and available in `.agents/skills/`:
+
+- **ef-composition** — time model, media elements, rendering pipeline
+- **ef-dev-server** — Vite plugin setup, local asset serving
+- **ef-editor-gui** — editor toolkit for visual composition editing
+- **ef-webhooks** — webhook notifications for render completion
+- **ef-brand-video-generator** — brand video generation templates
+- **ef-motion-design** — motion design patterns, transitions, kinetic typography
+
+The agent should also read **ef-composition-review** and **ef-render-verify** for quality assurance workflows.
+
+### 5. Build and preview
+
+1. Build the initial composition based on the operator's answers from Step 2. Use the discovery answers (project type, assets, libraries) to determine composition structure, asset placement, and optional dependencies.
+2. Run `forge dev` to start the preview server (delegates to `editframe preview` per the `editframe` profile's `devServer.command`).
+3. Report the localhost URL to the operator.
+4. Run `forge doctor` to check all profile invariants on the initial composition. For the `editframe` profile, this covers VIDEO-01 through VIDEO-09.
+5. Report any invariant violations and suggest fixes.