@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-composition/references/getting-started.md

@@ -0,0 +1,259 @@
+---
+title: Getting Started
+description: Build your first HTML video composition with Editframe Elements — install the package, place elements, and render to MP4.
+type: tutorial
+nav:
+  parent: "Quick Start"
+  priority: 1
+track: "getting-started"
+track_step: 1
+track_title: "Your First Composition"
+next_steps: ["video"]
+react:
+  generate: true
+  componentName: "Getting Started"
+  importPath: "@editframe/react"
+  nav:
+    parent: "Quick Start"
+    priority: 0
+---
+
+# Getting Started
+
+<!-- html-only -->
+Build your first video composition with Editframe Elements.
+
+> **Note:** Need a project? Run `npm create @editframe -- html -d my-project -y` — see the `editframe-create` skill.
+<!-- /html-only -->
+<!-- react-only -->
+Build your first video composition with React.
+
+> **Note:** Need a project? Run `npm create @editframe -- react -d my-project -y` — see the `editframe-create` skill.
+<!-- /react-only -->
+
+## Composition Structure
+
+<!-- html-only -->
+Every composition starts with an `ef-timegroup` root:
+
+```html
+<ef-timegroup mode="sequence" class="w-[1920px] h-[1080px] bg-black">
+  <!-- scenes go here -->
+</ef-timegroup>
+```
+
+The `mode` controls how child elements are timed.
+
+### Step 1: Start with Motion
+
+The first thing a viewer sees should move. Add an animated title — every word slides up in sequence using `split="word"` and `--ef-word-index`:
+
+```html live
+<ef-timegroup mode="fixed" duration="3s" class="w-[720px] h-[400px] bg-black flex items-center justify-center">
+  <ef-text
+    split="word"
+    class="text-white text-5xl font-bold"
+    style="animation: 0.6s slide-up both; animation-delay: calc(var(--ef-word-index) * 100ms)"
+  >Hello Editframe</ef-text>
+</ef-timegroup>
+<style>
+  @keyframes slide-up {
+    from { transform: translateY(30px); opacity: 0; }
+    to   { transform: translateY(0);    opacity: 1; }
+  }
+</style>
+```
+
+`split="word"` breaks the text into individual word elements. Each gets a `--ef-word-index` CSS variable so you can stagger delays. The animation runs relative to the scene timeline — it's fully scrubbable.
+
+### Step 2: Add a Video Background
+
+Place the title inside a `contain` timegroup with a video beneath it. The timegroup holds both layers simultaneously:
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[400px] bg-black">
+  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="absolute inset-0 size-full object-cover"></ef-video>
+  <div class="absolute inset-0 bg-black/50"></div>
+  <ef-text
+    split="word"
+    class="absolute top-8 left-8 text-white text-4xl font-bold"
+    style="animation: 0.6s slide-up both; animation-delay: calc(var(--ef-word-index) * 100ms)"
+  >Hello Editframe</ef-text>
+</ef-timegroup>
+<style>
+  @keyframes slide-up {
+    from { transform: translateY(30px); opacity: 0; }
+    to   { transform: translateY(0);    opacity: 1; }
+  }
+</style>
+```
+
+### Step 3: Chain Scenes with a Transition
+
+Use `mode="sequence"` with `overlap` to crossfade between scenes. Each scene fades out while the next fades in:
+
+```html live
+<ef-timegroup mode="sequence" overlap="1s" class="w-[720px] h-[400px] bg-black">
+  <ef-timegroup mode="contain" class="absolute w-full h-full" style="animation: 1s fade-out var(--ef-transition-out-start) both">
+    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="0s" sourceout="4s" class="absolute inset-0 size-full object-cover"></ef-video>
+    <ef-text
+      split="word"
+      class="absolute top-8 left-8 text-white text-4xl font-bold"
+      style="animation: 0.6s slide-up both; animation-delay: calc(var(--ef-word-index) * 100ms)"
+    >Scene One</ef-text>
+  </ef-timegroup>
+  <ef-timegroup mode="contain" class="absolute w-full h-full" style="animation: 1s fade-in both">
+    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="5s" sourceout="9s" class="absolute inset-0 size-full object-cover"></ef-video>
+    <ef-text
+      split="word"
+      class="absolute top-8 left-8 text-white text-4xl font-bold"
+      style="animation: 0.6s slide-up 0.3s both; animation-delay: calc(0.3s + var(--ef-word-index) * 100ms)"
+    >Scene Two</ef-text>
+  </ef-timegroup>
+</ef-timegroup>
+<style>
+  @keyframes slide-up {
+    from { transform: translateY(30px); opacity: 0; }
+    to   { transform: translateY(0);    opacity: 1; }
+  }
+  @keyframes fade-in  { from { opacity: 0; } to { opacity: 1; } }
+  @keyframes fade-out { from { opacity: 1; } to { opacity: 0; } }
+</style>
+```
+
+`--ef-transition-out-start` is a CSS variable Editframe sets automatically — it's the point in time when the overlap begins, so the fade-out starts exactly at the transition point.
+
+<!-- /html-only -->
+<!-- react-only -->
+## Motion-First Composition
+
+The first thing a viewer sees should move. This example animates a title word-by-word using `split="word"` and `--ef-word-index`:
+
+```tsx
+import { Timegroup, Text } from "@editframe/react";
+
+export const Video = () => {
+  return (
+    <Timegroup mode="fixed" duration="3s" className="w-[1920px] h-[1080px] bg-black flex items-center justify-center">
+      <Text
+        split="word"
+        className="text-white text-7xl font-bold"
+        style={{
+          animation: "0.6s slide-up both",
+          animationDelay: "calc(var(--ef-word-index) * 100ms)"
+        }}
+      >
+        Hello Editframe
+      </Text>
+    </Timegroup>
+  );
+};
+```
+
+```css
+@keyframes slide-up {
+  from { transform: translateY(30px); opacity: 0; }
+  to   { transform: translateY(0);    opacity: 1; }
+}
+```
+
+Wrap it with `TimelineRoot` in `src/main.tsx`:
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { TimelineRoot } from "@editframe/react";
+import { Video } from "./Video";
+import "@editframe/elements/styles.css";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Root element not found");
+
+ReactDOM.createRoot(root).render(
+  <TimelineRoot id="root" component={Video} />
+);
+```
+
+**Important**: `TimelineRoot` is required for rendering. See [timeline-root.md](references/timeline-root.md).
+
+## Add a Video Background
+
+```tsx
+import { Timegroup, Video, Text } from "@editframe/react";
+
+export const MyVideo = () => (
+  <Timegroup mode="contain" className="w-[1920px] h-[1080px] bg-black">
+    <Video src="/assets/background.mp4" className="absolute inset-0 size-full object-cover" />
+    <div className="absolute inset-0 bg-black/50" />
+    <Text
+      split="word"
+      className="absolute top-16 left-16 text-white text-6xl font-bold"
+      style={{
+        animation: "0.6s slide-up both",
+        animationDelay: "calc(var(--ef-word-index) * 100ms)"
+      }}
+    >
+      Opening Title
+    </Text>
+  </Timegroup>
+);
+```
+
+## Chain Scenes with a Transition
+
+```tsx
+import { Timegroup, Video, Text, Audio } from "@editframe/react";
+
+export const VideoComposition = () => (
+  <Timegroup mode="sequence" overlap="1s" className="w-[1920px] h-[1080px]">
+    <Timegroup
+      mode="contain"
+      className="absolute w-full h-full"
+      style={{ animation: "1s fade-out var(--ef-transition-out-start) both" }}
+    >
+      <Video src="/assets/intro.mp4" className="size-full object-cover" />
+      <Text
+        split="word"
+        className="absolute top-16 left-16 text-white text-5xl font-bold"
+        style={{ animation: "0.6s slide-up both", animationDelay: "calc(var(--ef-word-index) * 100ms)" }}
+      >
+        Scene One
+      </Text>
+    </Timegroup>
+    <Timegroup
+      mode="contain"
+      className="absolute w-full h-full"
+      style={{ animation: "1s fade-in both" }}
+    >
+      <Video src="/assets/main.mp4" className="size-full object-cover" />
+      <Audio src="/assets/music.mp3" volume={0.3} />
+    </Timegroup>
+  </Timegroup>
+);
+```
+
+```css
+@keyframes fade-in  { from { opacity: 0; } to { opacity: 1; } }
+@keyframes fade-out { from { opacity: 1; } to { opacity: 0; } }
+```
+<!-- /react-only -->
+
+## Assets
+
+Place media files in `src/assets/` and reference with `/assets/filename`:
+
+<!-- html-only -->
+```html
+<ef-video src="/assets/video.mp4"></ef-video>
+<ef-audio src="/assets/music.mp3"></ef-audio>
+<ef-image src="/assets/logo.png"></ef-image>
+```
+<!-- /html-only -->
+
+## Render to Video
+
+```bash
+npx editframe render -o output.mp4
+```
+
+See the `editframe-cli` skill for full render options.

package/dist/skills/editframe-composition/references/hooks.md

@@ -0,0 +1,234 @@
+---
+title: Hooks
+description: React hooks for reading current playback time, pan/zoom transform, and media loading state from within composition components.
+type: reference
+nav:
+  parent: "React"
+  priority: 11
+  related: ["timeline-root", "timegroup"]
+---
+
+# Hooks
+
+React hooks for accessing timing information and transforms.
+
+## useTimingInfo
+
+Access timing information for the current element.
+
+**Important**: This hook requires `TimelineRoot` to work correctly in render clones. See [timeline-root.md](references/timeline-root.md).
+
+### Import
+
+```tsx
+import { useTimingInfo } from "@editframe/react";
+```
+
+### Returns
+
+```tsx
+{
+  ref: RefObject<HTMLElement>;           // Attach to your component
+  ownCurrentTimeMs: number;              // Current time within this element
+  durationMs: number;                    // Total duration of element
+  percentComplete: number;               // Progress (0-1)
+  isActive: boolean;                     // Is currently playing
+  startTimeMs: number;                   // Start time in parent
+  endTimeMs: number;                     // End time in parent
+}
+```
+
+### Basic Usage
+
+```tsx
+import { Timegroup, useTimingInfo } from "@editframe/react";
+
+const AnimatedScene = () => {
+  const { ref, percentComplete, ownCurrentTimeMs } = useTimingInfo();
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="5s" className="absolute w-full h-full">
+      <div style={{ opacity: percentComplete }}>
+        Fading in... {(ownCurrentTimeMs / 1000).toFixed(2)}s
+      </div>
+    </Timegroup>
+  );
+};
+```
+
+### Fade In/Out
+
+```tsx
+const FadeInOut = ({ children }: { children: React.ReactNode }) => {
+  const { ref, percentComplete } = useTimingInfo();
+  
+  // Fade in first half, fade out second half
+  const opacity = percentComplete < 0.5 
+    ? percentComplete * 2 
+    : (1 - percentComplete) * 2;
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="5s" className="absolute w-full h-full">
+      <div style={{ opacity }}>
+        {children}
+      </div>
+    </Timegroup>
+  );
+};
+```
+
+### Scale Animation
+
+```tsx
+const ScaleIn = ({ children }: { children: React.ReactNode }) => {
+  const { ref, percentComplete } = useTimingInfo();
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="3s" className="absolute w-full h-full flex items-center justify-center">
+      <div style={{ transform: `scale(${percentComplete})` }}>
+        {children}
+      </div>
+    </Timegroup>
+  );
+};
+```
+
+### Progress Bar
+
+```tsx
+const SceneWithProgress = () => {
+  const { ref, percentComplete, ownCurrentTimeMs, durationMs } = useTimingInfo();
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="10s" className="absolute w-full h-full bg-black flex flex-col items-center justify-center">
+      <h1 className="text-white text-4xl mb-4">Scene Content</h1>
+      
+      <div className="w-96 bg-gray-700 h-2 rounded">
+        <div 
+          className="bg-blue-500 h-full rounded transition-all"
+          style={{ width: `${percentComplete * 100}%` }}
+        />
+      </div>
+      
+      <p className="text-white mt-2">
+        {(ownCurrentTimeMs / 1000).toFixed(1)}s / {(durationMs / 1000).toFixed(1)}s
+      </p>
+    </Timegroup>
+  );
+};
+```
+
+### Conditional Rendering
+
+```tsx
+const TimedReveal = () => {
+  const { ref, ownCurrentTimeMs } = useTimingInfo();
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="10s" className="absolute w-full h-full">
+      {ownCurrentTimeMs > 2000 && (
+        <Text duration="8s" className="text-white text-4xl">
+          Appears after 2 seconds
+        </Text>
+      )}
+      
+      {ownCurrentTimeMs > 5000 && (
+        <Image src="/assets/logo.png" className="absolute top-8 right-8 w-32" />
+      )}
+    </Timegroup>
+  );
+};
+```
+
+### Complex Animation
+
+```tsx
+const ComplexAnimation = ({ children }: { children: React.ReactNode }) => {
+  const { ref, percentComplete } = useTimingInfo();
+  
+  // Different animations per stage
+  let transform = '';
+  let opacity = 1;
+  
+  if (percentComplete < 0.25) {
+    // Slide in from left
+    const progress = percentComplete * 4;
+    transform = `translateX(${-100 + progress * 100}%)`;
+  } else if (percentComplete < 0.75) {
+    // Stay centered
+    transform = 'translateX(0)';
+  } else {
+    // Slide out to right
+    const progress = (percentComplete - 0.75) * 4;
+    transform = `translateX(${progress * 100}%)`;
+    opacity = 1 - progress;
+  }
+  
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="8s" className="absolute w-full h-full flex items-center justify-center">
+      <div style={{ transform, opacity }}>
+        {children}
+      </div>
+    </Timegroup>
+  );
+};
+```
+
+## usePanZoomTransform
+
+Access pan/zoom transform values for synchronized UI elements.
+
+### Import
+
+```tsx
+import { usePanZoomTransform } from "@editframe/react";
+```
+
+### Returns
+
+```tsx
+{
+  x: number;      // Pan X offset
+  y: number;      // Pan Y offset
+  scale: number;  // Zoom scale
+}
+```
+
+### Basic Usage
+
+```tsx
+import { PanZoom, usePanZoomTransform } from "@editframe/react";
+
+const SyncedOverlay = () => {
+  const { x, y, scale } = usePanZoomTransform();
+  
+  return (
+    <div 
+      className="absolute top-0 left-0 pointer-events-none"
+      style={{
+        transform: `translate(${x}px, ${y}px) scale(${scale})`,
+      }}
+    >
+      <div className="text-white text-2xl">
+        Follows pan/zoom
+      </div>
+    </div>
+  );
+};
+```
+
+### Display Transform Info
+
+```tsx
+const TransformInfo = () => {
+  const { x, y, scale } = usePanZoomTransform();
+  
+  return (
+    <div className="absolute top-4 right-4 bg-black/80 text-white p-2 rounded text-sm font-mono">
+      <div>X: {x.toFixed(0)}px</div>
+      <div>Y: {y.toFixed(0)}px</div>
+      <div>Scale: {scale.toFixed(2)}x</div>
+    </div>
+  );
+};
+```