@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-composition/references/time-model.md

@@ -0,0 +1,99 @@
+---
+title: Time Model
+description: "How time propagation works in composition trees: duration inheritance, offset calculation, and element scheduling rules."
+type: explanation
+nav:
+  parent: "Concepts"
+  priority: 11
+  related: ["timegroup-modes"]
+---
+
+# Time Model
+
+Editframe uses a declarative time model. You describe structure — the system computes all timing.
+
+## Single Source of Truth
+
+Only the root timegroup's `currentTime` is writable. All child times are computed from parent state. This guarantees synchronization — it's impossible for timelines to drift.
+
+```javascript
+const root = document.querySelector('ef-timegroup');
+root.currentTime = 5.5; // All children update atomically
+```
+
+## Time Flows Down the Tree
+
+Each timegroup computes its `ownCurrentTimeMs` (local time) from the parent's time based on its mode and position in the tree.
+
+**Root writes `currentTime`** → parent computes child offsets → each child derives its local time → media elements map to source time.
+
+In a sequence, a child at position 5s–8s receives `ownCurrentTimeMs = 0` when the root is at 5s, and `ownCurrentTimeMs = 3000` when the root is at 8s.
+
+## Duration Calculation by Mode
+
+Each mode computes duration differently:
+
+| Mode | Duration rule |
+|------|--------------|
+| `fixed` | Explicit `duration` attribute |
+| `sequence` | Sum of children minus overlaps |
+| `contain` | Maximum child duration |
+| `fit` | Inherited from parent |
+
+Duration bubbles up — a `sequence` inside a `contain` resolves its sum, and the `contain` parent takes the max of that and its other children.
+
+```html
+<ef-timegroup mode="contain">
+  <!-- sequence resolves to 8s (3+5) -->
+  <ef-timegroup mode="sequence">
+    <ef-timegroup mode="fixed" duration="3s">A</ef-timegroup>
+    <ef-timegroup mode="fixed" duration="5s">B</ef-timegroup>
+  </ef-timegroup>
+  <!-- contain takes max(8s, 6s) = 8s -->
+  <ef-timegroup mode="fixed" duration="6s">C</ef-timegroup>
+</ef-timegroup>
+```
+
+## Trimming and the Timeline
+
+When a video is trimmed, its effective duration changes, which propagates up through the tree:
+
+- `sourcein="2s" sourceout="6s"` → effective duration is 4s
+- `trimstart="1s" trimend="2s"` on a 10s source → effective duration is 7s
+
+In a `sequence`, changing a trim value shifts all subsequent items automatically. In `contain`, it may change the overall duration if it was the longest child.
+
+## Overlap Creates Shared Time
+
+In `sequence` mode, `overlap` subtracts time between adjacent items, creating a region where both are active:
+
+```
+Scene A: |---------|
+Scene B:      |---------|
+overlap:      |---|
+```
+
+Total duration: `durationA + durationB - overlap`
+
+During the overlap region, both scenes receive valid `ownCurrentTimeMs` values. Scene A is near its end, Scene B is near its start. This shared time is where transitions happen.
+
+See [transitions.md](references/transitions.md) for using overlap with CSS animations.
+
+## Two Coordinate Systems
+
+Every element has two time perspectives:
+
+- **`currentTimeMs`** — position in the root timeline (global). Same value for all elements at any given moment.
+- **`ownCurrentTimeMs`** — position in the element's local timeline (local). Resets to 0 at the element's start.
+
+Media elements add a third:
+
+- **`currentSourceTimeMs`** — position in the source file, accounting for trims. Survives trim changes.
+
+> **Note:** `ownCurrentTimeMs` is what you use in `addFrameTask` callbacks and CSS animations. It provides element-relative timing that works regardless of where the element sits in the composition.
+
+## See Also
+
+- [timegroup-modes.md](references/timegroup-modes.md) — mode examples
+- [timegroup.md](references/timegroup.md) — attribute reference
+- [sequencing.md](references/sequencing.md) — sequence patterns

package/dist/skills/editframe-composition/references/timegroup-modes.md

@@ -0,0 +1,102 @@
+---
+title: Timegroup Modes
+description: How the four timegroup layout modes — par, seq, excl, and media — control duration, ordering, and child element scheduling.
+type: explanation
+nav:
+  parent: "Concepts"
+  priority: 12
+  related: ["timegroup", "sequencing"]
+track: "layout-mastery"
+track_step: 2
+track_title: "Understanding Timeline Modes"
+prerequisites: ["timegroup"]
+next_steps: ["sequencing"]
+---
+
+# Timegroup Modes
+
+Every `ef-timegroup` has a `mode` that determines how its duration is calculated and how children are arranged in time.
+
+## Fixed
+
+Explicit duration. The base case — you set the length directly.
+
+```html live
+<ef-timegroup mode="fixed" duration="3s" class="w-[720px] h-[300px] bg-slate-600 flex items-center justify-center">
+  <p class="text-white text-4xl">3 Second Scene</p>
+</ef-timegroup>
+```
+
+Use `fixed` when you know the exact duration: title cards, countdowns, static scenes.
+
+## Sequence
+
+Children play one after another. Duration is the sum of all children minus any overlap.
+
+```html live
+<ef-timegroup mode="sequence" class="w-[720px] h-[300px] bg-black">
+  <ef-timegroup mode="fixed" duration="2s" class="bg-red-400 text-red-900 text-3xl flex items-center justify-center">
+    <p>Scene 1 (2s)</p>
+  </ef-timegroup>
+  <ef-timegroup mode="fixed" duration="3s" class="bg-green-400 text-green-900 text-3xl flex items-center justify-center">
+    <p>Scene 2 (3s)</p>
+  </ef-timegroup>
+  <ef-timegroup mode="fixed" duration="1s" class="bg-blue-400 text-blue-900 text-3xl flex items-center justify-center">
+    <p>Scene 3 (1s)</p>
+  </ef-timegroup>
+</ef-timegroup>
+```
+
+Use `sequence` for cut-based editing, multi-scene videos, anything where children play in order. See [sequencing.md](references/sequencing.md).
+
+## Contain
+
+Children play simultaneously. Duration is the longest child.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[300px] bg-black">
+  <ef-timegroup mode="fixed" duration="5s" class="absolute top-0 left-0 w-full h-1/2 bg-red-400 text-red-900 text-2xl flex items-center justify-center">
+    <p>Layer A (5s)</p>
+  </ef-timegroup>
+  <ef-timegroup mode="fixed" duration="8s" class="absolute top-1/2 left-0 w-full h-1/2 bg-green-400 text-green-900 text-2xl flex items-center justify-center">
+    <p>Layer B (8s) — sets total to 8s</p>
+  </ef-timegroup>
+</ef-timegroup>
+```
+
+Use `contain` for layered compositions: video with overlays, picture-in-picture, parallel tracks.
+
+## Fit
+
+Inherits duration from parent. No duration of its own.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[300px] bg-black">
+  <ef-timegroup mode="fixed" duration="4s" class="absolute top-0 left-0 w-full h-1/2 bg-amber-400 text-amber-900 text-2xl flex items-center justify-center">
+    <p>Content (4s)</p>
+  </ef-timegroup>
+  <ef-timegroup mode="fit" class="absolute top-1/2 left-0 w-full h-1/2 bg-blue-900 text-blue-200 text-2xl flex items-center justify-center">
+    <p>Fit background — spans full 4s</p>
+  </ef-timegroup>
+</ef-timegroup>
+```
+
+Use `fit` for backgrounds, watermarks, or any element that should span its parent's full duration.
+
+## Decision Guide
+
+| Scenario | Mode | Why |
+|----------|------|-----|
+| Title card with known length | `fixed` | Explicit control |
+| Multi-scene video | `sequence` | Sequential playback |
+| Video with text overlay | `contain` | Parallel layers |
+| Background music/watermark | `fit` | Span parent duration |
+| Scenes with transitions | `sequence` + `overlap` | Shared time for crossfades |
+
+> **Note:** Modes compose — a `contain` parent with a `sequence` child and a `fit` background is a common pattern for videos with a background track spanning the full timeline.
+
+## See Also
+
+- [timegroup.md](references/timegroup.md) — attribute reference
+- [time-model.md](references/time-model.md) — how time propagates through modes
+- [sequencing.md](references/sequencing.md) — sequence patterns

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

@@ -0,0 +1,457 @@
+---
+title: Timegroup Element
+description: Container element for grouping and sequencing composition elements, controlling layout mode, duration, and playback behavior.
+type: reference
+nav:
+  parent: "Layout & Timing"
+  priority: 10
+  related: ["timegroup-modes", "sequencing"]
+track: "layout-mastery"
+track_step: 1
+track_title: "Understanding Timegroups"
+next_steps: ["timegroup-modes"]
+api:
+  attributes:
+    - name: mode
+      type: string
+      required: true
+      description: Duration calculation mode
+      values: ["fixed", "sequence", "contain", "fit"]
+    - name: duration
+      type: timestring
+      description: Explicit duration (for fixed mode)
+    - name: overlap
+      type: timestring
+      description: Overlap time between sequence items (e.g., "1s")
+    - name: fps
+      type: number
+      default: 30
+      description: Frame rate for rendering
+    - name: auto-init
+      type: boolean
+      default: false
+      description: Auto-seek to frame 0 on load (root only)
+    - name: workbench
+      type: boolean
+      default: false
+      description: Enable timeline/hierarchy UI (root only)
+  methods:
+    - name: renderToVideo()
+      signature: "async renderToVideo(options?: RenderToVideoOptions): Promise<Uint8Array | undefined>"
+      description: Export timegroup to MP4 video using WebCodecs API
+      returns: Promise<Uint8Array | undefined>
+    - name: createRenderClone()
+      signature: "async createRenderClone(): Promise<RenderCloneResult>"
+      description: Create independent off-DOM clone for background rendering without affecting preview
+      returns: Promise<RenderCloneResult>
+    - name: addFrameTask()
+      signature: "addFrameTask(callback: FrameTaskCallback): () => void"
+      description: Register callback executed on each frame during rendering or playback
+      returns: Cleanup function that removes the callback
+    - name: seek()
+      signature: "async seek(timeMs: number): Promise<void>"
+      description: Seek to specific time position and wait for content to be ready
+      returns: Promise<void>
+react:
+  generate: true
+  componentName: Timegroup
+  importPath: "@editframe/react"
+  propMapping:
+    auto-init: autoInit
+  additionalProps:
+    - name: className
+      type: string
+      description: CSS classes for styling
+    - name: ref
+      type: React.Ref
+      description: React ref (useful with hooks)
+  nav:
+    parent: "Core Concepts"
+    priority: 2
+    related: ["timeline-root", "hooks"]
+---
+
+<!-- html-only -->
+# ef-timegroup
+<!-- /html-only -->
+<!-- react-only -->
+# Timegroup
+<!-- /react-only -->
+
+Container for sequencing and grouping elements.
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { Timegroup } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Modes
+
+<!-- html-only -->
+- `fixed` - Uses `duration` attribute
+<!-- /html-only -->
+<!-- react-only -->
+- `fixed` - Uses `duration` prop
+<!-- /react-only -->
+- `sequence` - Sum of children (sequential playback)
+- `contain` - Longest child duration
+- `fit` - Inherit from parent
+
+## Root Timegroup
+
+<!-- html-only -->
+```html live
+<ef-timegroup mode="sequence" workbench class="w-[720px] h-[480px] bg-black">
+  <ef-timegroup mode="fixed" duration="3s" class="absolute w-full h-full flex items-center justify-center">
+    <ef-text duration="3s" class="text-white text-3xl">Scene 1</ef-text>
+  </ef-timegroup>
+  <ef-timegroup mode="fixed" duration="3s" class="absolute w-full h-full flex items-center justify-center">
+    <ef-text duration="3s" class="text-white text-3xl">Scene 2</ef-text>
+  </ef-timegroup>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+import { Timegroup } from "@editframe/react";
+
+export const Video = () => {
+  return (
+    <Timegroup workbench mode="sequence" className="w-[800px] h-[500px] bg-black">
+      {/* scenes here */}
+    </Timegroup>
+  );
+};
+```
+<!-- /react-only -->
+
+## Scene (Fixed Duration)
+
+<!-- html-only -->
+```html
+<ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
+  <ef-video src="clip.mp4" class="size-full object-cover"></ef-video>
+  <ef-text class="absolute top-4 left-4 text-white">Overlay</ef-text>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+<Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
+  <Video src="/assets/clip.mp4" className="size-full object-cover" />
+  <Text className="absolute top-4 left-4 text-white">Overlay</Text>
+</Timegroup>
+```
+<!-- /react-only -->
+
+## Nested Sequence
+
+<!-- html-only -->
+```html
+<ef-timegroup mode="sequence">
+  <ef-timegroup mode="fixed" duration="3s"><!-- Scene 1 --></ef-timegroup>
+  <ef-timegroup mode="fixed" duration="5s"><!-- Scene 2 --></ef-timegroup>
+  <ef-timegroup mode="fixed" duration="4s"><!-- Scene 3 --></ef-timegroup>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+<Timegroup mode="sequence">
+  <Timegroup mode="fixed" duration="3s">
+    {/* Scene 1 */}
+  </Timegroup>
+  <Timegroup mode="fixed" duration="5s">
+    {/* Scene 2 */}
+  </Timegroup>
+  <Timegroup mode="fixed" duration="4s">
+    {/* Scene 3 */}
+  </Timegroup>
+</Timegroup>
+```
+<!-- /react-only -->
+
+<!-- react-only -->
+## Dynamic Content
+
+Map over data to create scenes:
+
+```tsx
+const scenes = [
+  { id: 1, text: "Scene 1", duration: "3s" },
+  { id: 2, text: "Scene 2", duration: "5s" },
+  { id: 3, text: "Scene 3", duration: "4s" },
+];
+
+<Timegroup workbench mode="sequence" className="w-[800px] h-[500px]">
+  {scenes.map((scene) => (
+    <Timegroup
+      key={scene.id}
+      mode="fixed"
+      duration={scene.duration}
+      className="absolute w-full h-full"
+    >
+      <Text className="text-white text-4xl">{scene.text}</Text>
+    </Timegroup>
+  ))}
+</Timegroup>
+```
+<!-- /react-only -->
+
+## Sequence with Overlap
+
+Use `overlap` to create transitions between items:
+
+<!-- html-only -->
+```html
+<ef-timegroup mode="sequence" overlap="1s">
+  <ef-timegroup mode="contain"><!-- Scene 1 --></ef-timegroup>
+  <ef-timegroup mode="contain"><!-- Scene 2 --></ef-timegroup>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+<Timegroup mode="sequence" overlap="1s">
+  <Timegroup mode="contain">{/* Scene 1 */}</Timegroup>
+  <Timegroup mode="contain">{/* Scene 2 */}</Timegroup>
+</Timegroup>
+```
+<!-- /react-only -->
+
+See [transitions.md](references/transitions.md) for crossfade examples.
+
+<!-- react-only -->
+## With useTimingInfo Hook
+
+```tsx
+import { Timegroup } from "@editframe/react";
+import { useTimingInfo } from "@editframe/react";
+
+const AnimatedScene = () => {
+  const { ref, percentComplete, ownCurrentTimeMs } = useTimingInfo();
+
+  return (
+    <Timegroup ref={ref} mode="contain" className="absolute w-full h-full">
+      <div style={{ opacity: percentComplete }}>
+        Fading in... {(ownCurrentTimeMs / 1000).toFixed(2)}s
+      </div>
+    </Timegroup>
+  );
+};
+```
+<!-- /react-only -->
+
+## Methods
+
+### renderToVideo()
+
+Export the timegroup composition to MP4 video using the WebCodecs API. See [render-api.md](references/render-api.md) for complete documentation.
+
+```typescript
+async renderToVideo(options?: RenderToVideoOptions): Promise<Uint8Array | undefined>
+```
+
+**Basic Example:**
+
+```typescript
+const tg = document.querySelector('ef-timegroup');
+
+await tg.renderToVideo({
+  fps: 30,
+  codec: 'avc',
+  filename: 'output.mp4',
+  onProgress: (progress) => {
+    console.log(`${Math.round(progress.progress * 100)}% complete`);
+  }
+});
+```
+
+**RenderToVideoOptions:**
+- `fps` - Frame rate (default: 30)
+- `codec` - Video codec: "avc", "hevc", "vp9", "av1", "vp8" (default: "avc")
+- `bitrate` - Video bitrate in bits/second (default: 5000000)
+- `filename` - Download filename (default: "video.mp4")
+- `scale` - Resolution multiplier (default: 1)
+- `fromMs`, `toMs` - Time range to export
+- `onProgress` - Progress callback receiving `RenderProgress` object
+- `includeAudio` - Include audio tracks (default: true)
+- `signal` - AbortSignal for cancellation
+- `returnBuffer` - Return Uint8Array instead of downloading
+- And more - see [render-api.md](references/render-api.md)
+
+### createRenderClone()
+
+Create an independent off-DOM clone for background rendering without affecting the preview timeline.
+
+```typescript
+async createRenderClone(): Promise<RenderCloneResult>
+```
+
+**Example:**
+
+```typescript
+const tg = document.querySelector('ef-timegroup');
+
+// Create isolated render clone
+const { clone, container, cleanup } = await tg.createRenderClone();
+
+try {
+  // Clone has independent time state
+  await clone.seek(5000);  // Seek clone to 5 seconds
+
+  // Original timeline unaffected
+  console.log('Clone time:', clone.currentTimeMs);
+  console.log('Original time:', tg.currentTimeMs);
+} finally {
+  // Always clean up
+  cleanup();
+}
+```
+
+**RenderCloneResult:**
+```typescript
+interface RenderCloneResult {
+  clone: EFTimegroup;      // Cloned timegroup with independent state
+  container: HTMLElement;  // Off-screen container holding the clone
+  cleanup: () => void;     // Remove clone from DOM and clean up
+}
+```
+
+Clones automatically re-run the `initializer` function if set, enabling JavaScript-driven animations in renders.
+
+### addFrameTask()
+
+Register a callback that executes on each frame during playback or rendering. Returns cleanup function.
+
+```typescript
+addFrameTask(callback: FrameTaskCallback): () => void
+```
+
+**Example:**
+
+```typescript
+const tg = document.querySelector('ef-timegroup');
+
+const cleanup = tg.addFrameTask((info) => {
+  // Update DOM based on current time
+  const progress = info.percentComplete;
+  console.log(`Frame at ${info.ownCurrentTimeMs}ms (${Math.round(progress * 100)}%)`);
+
+  // Modify child elements
+  const textEl = info.element.querySelector('.dynamic-text');
+  if (textEl) {
+    textEl.textContent = `Time: ${(info.ownCurrentTimeMs / 1000).toFixed(2)}s`;
+  }
+});
+
+// Remove callback when done
+cleanup();
+```
+
+**FrameTaskCallback:**
+```typescript
+type FrameTaskCallback = (info: {
+  ownCurrentTimeMs: number;    // This element's local time
+  currentTimeMs: number;       // Root timeline's global time
+  durationMs: number;          // This element's duration
+  percentComplete: number;     // Completion percentage (0.0 to 1.0)
+  element: EFTimegroup;        // The timegroup instance
+}) => void | Promise<void>;
+```
+
+The callback can be sync or async. Multiple callbacks can be registered and execute in parallel.
+
+### seek()
+
+Seek to a specific time position and wait for all visible content to be ready.
+
+```typescript
+async seek(timeMs: number): Promise<void>
+```
+
+**Example:**
+
+```typescript
+const tg = document.querySelector('ef-timegroup');
+
+// Seek to 3 seconds
+await tg.seek(3000);
+
+// Timeline is now at 3s, all visible media loaded
+console.log('Current time:', tg.currentTimeMs);
+```
+
+Time is automatically quantized to frame boundaries based on the `fps` attribute.
+
+## Scripting
+
+<!-- html-only -->
+Add dynamic behavior with JavaScript using the `initializer` property. The initializer function runs on both the original timeline and all render clones.
+
+```html
+<ef-timegroup id="dynamic-scene" mode="fixed" duration="5s">
+  <div class="dynamic-text"></div>
+</ef-timegroup>
+
+<script>
+  const tg = document.querySelector('#dynamic-scene');
+
+  // Initializer runs once per instance (original + clones)
+  tg.initializer = (instance) => {
+    instance.addFrameTask((info) => {
+      const text = instance.querySelector('.dynamic-text');
+      text.textContent = `Time: ${(info.ownCurrentTimeMs / 1000).toFixed(2)}s`;
+    });
+  };
+</script>
+```
+<!-- /html-only -->
+<!-- react-only -->
+Add dynamic behavior with JavaScript. See [scripting.md](references/scripting.md) for details.
+
+```tsx
+import { useRef, useEffect } from "react";
+import { Timegroup } from "@editframe/react";
+
+const DynamicScene = () => {
+  const timegroupRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const tg = timegroupRef.current;
+    if (!tg) return;
+
+    tg.initializer = (instance) => {
+      const cleanup = instance.addFrameTask((info) => {
+        // Update content based on time
+        console.log(`Time: ${info.ownCurrentTimeMs}ms`);
+      });
+
+      return cleanup;
+    };
+  }, []);
+
+  return (
+    <Timegroup ref={timegroupRef} mode="fixed" duration="5s">
+      {/* Content */}
+    </Timegroup>
+  );
+};
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+**TimegroupInitializer:**
+```typescript
+type TimegroupInitializer = (timegroup: EFTimegroup) => void;
+```
+
+**Constraints:**
+- Must be synchronous (no async/await, no Promise return)
+- Must complete quickly (&lt;10ms warning, &lt;100ms error)
+- Should only register callbacks and set up behavior
+- Runs once per instance (prime timeline + each render clone)
+<!-- /html-only -->