@editframe/create 0.44.0 → 0.45.1

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

@@ -0,0 +1,73 @@
+---
+title: Composition Model
+description: Mental model for how timegroup trees, temporal scheduling, and element rendering work together in an Editframe composition.
+type: explanation
+nav:
+  parent: "Concepts"
+  priority: 10
+  related: ["timegroup", "timegroup-modes", "time-model"]
+---
+
+## Timegroup tree structure
+
+A composition is a tree of nested timegroups. The root timegroup acts as the top-level container, and every media element, text block, or nested timegroup sits as a child within it. This tree structure determines both the visual layering order and the temporal relationships between elements.
+
+Timegroups can nest arbitrarily deep. A root timegroup might contain a video element, a text element, and a child timegroup that itself contains an image sequence. Each level of nesting creates a new timing scope: the parent controls when the child subtree starts and how long it runs, while the child manages the relative timing of its own children.
+
+## Temporal scheduling
+
+Time flows from the root of the tree down to the leaves. The root timegroup drives the master clock. When the root advances to a given time, each child receives a time value relative to its own start point. This relative time is called `ownCurrentTimeMs`.
+
+An element does not know or care about the absolute position in the overall composition. It only knows its own local time. A video element at `ownCurrentTimeMs: 2000` is 2 seconds into its own playback, regardless of where it sits in the global timeline. This local-time model makes it straightforward to rearrange, nest, or reuse subtrees without recalculating offsets.
+
+Each element also has a `startMs` and `durationMs` that define when it becomes active within its parent's timeline. Outside that window, the element is inactive and produces no output.
+
+## Timegroup modes
+
+A timegroup's mode determines how it calculates its own duration from its children:
+
+- **sequence** -- Children play one after another. The timegroup's duration is the sum of all child durations. Each child's start time is the cumulative duration of all preceding siblings. This is the natural choice for slide decks, sequential scenes, or any content that plays in order.
+
+- **fixed** -- The timegroup has an explicit duration set directly. Children are positioned within that fixed window. Content that extends beyond the boundary is clipped; content shorter than the boundary leaves dead time.
+
+- **contain** -- The timegroup shrink-wraps to fit its longest child. All children start at time zero by default, and the timegroup's duration equals the maximum child duration. This is useful for layered compositions where multiple elements play simultaneously.
+
+## Media elements
+
+Video, audio, and image elements represent source media within the tree. Video and audio have intrinsic durations derived from their source files. An image has no intrinsic duration, so it displays for whatever duration its parent assigns.
+
+Media elements decode their source material frame by frame during rendering. A video element at `ownCurrentTimeMs: 1500` seeks to the 1.5-second mark of its source file and produces the corresponding frame. Audio elements produce sample data for the current time window.
+
+## Text and captions
+
+Text elements render styled HTML content within the composition. They participate in the same timing model as media elements: they have a start time and duration, and they produce visual output when active.
+
+Captions are a specialized form of text that synchronize individual words or phrases to specific time ranges. Each caption segment maps to a span of time, enabling word-level highlighting and timed appearance.
+
+Both text and captions support animations through CSS transitions and frame tasks. A frame task is a function that runs on every frame, receiving the current time and allowing dynamic style changes such as fade-ins, position shifts, or color transitions.
+
+## Surface
+
+A surface element mirrors the rendered output of another element. Rather than producing its own content, it references a target element by ID and displays whatever that element currently renders.
+
+This enables picture-in-picture layouts, reflection effects, and multi-view compositions without duplicating source media. The surface updates automatically as the target element's output changes over time.
+
+## Context system
+
+Elements communicate through a DOM-based context system. When a timegroup mounts, it provides a context that downstream elements and controls can consume. Playback controls such as play, pause, and scrubber components connect to a timegroup by reading from this context.
+
+Controls can also target a specific timegroup using the `target` attribute with an element reference or selector. This allows a single interface to contain controls for multiple independent timegroups, each bound explicitly rather than through context inheritance.
+
+The context system follows the DOM hierarchy. A control nested inside a timegroup automatically connects to the nearest ancestor timegroup unless an explicit target overrides that behavior.
+
+## Rendering pipeline
+
+During rendering, the tree is evaluated frame by frame at a fixed frame rate. At each frame:
+
+1. The root timegroup advances to the next time position.
+2. Time propagates down the tree. Each element receives its local `ownCurrentTimeMs`.
+3. Active elements resolve their visual state: media elements decode a frame, text elements compute their styled output, surfaces sample their target.
+4. The results composite into a single canvas in tree order, with later siblings drawing on top of earlier ones.
+5. The final canvas pixel data is captured as one frame of the output video.
+
+This process repeats for every frame in the composition's total duration. Audio is mixed in a parallel pass, combining all active audio sources according to the same timing model. The final output is a video file that faithfully reproduces the composition tree's state at every point in time.

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

@@ -0,0 +1,403 @@
+---
+title: Configuration Element
+description: Configuration wrapper for selecting media engine (ffmpeg or native) and setting API credentials for Editframe compositions.
+type: reference
+nav:
+  parent: "Advanced"
+  priority: 10
+api:
+  attributes:
+    - name: api-host
+      type: string
+      description: Override API host for asset resolution
+    - name: signing-url
+      type: string
+      default: "/@ef-sign-url"
+      description: URL endpoint for signed URL generation
+    - name: media-engine
+      type: string
+      default: "cloud"
+      description: Media engine selection
+      values: ["cloud", "local", "jit"]
+react:
+  generate: true
+  componentName: Configuration
+  importPath: "@editframe/react"
+  propMapping:
+    api-host: apiHost
+    signing-url: signingURL
+    media-engine: mediaEngine
+  additionalProps:
+    - name: children
+      type: React.ReactNode
+      description: Application content (typically TimelineRoot)
+  nav:
+    parent: "Core Concepts"
+    priority: 0
+    related: ["timeline-root"]
+---
+
+<!-- html-only -->
+# ef-configuration
+<!-- /html-only -->
+<!-- react-only -->
+# Configuration
+<!-- /react-only -->
+
+Configuration wrapper for media engine selection and API settings.
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { Configuration } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Basic Usage
+
+Wrap your composition to configure media handling:
+
+<!-- html-only -->
+```html
+<ef-configuration media-engine="cloud">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black">
+    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+// Video.tsx
+import { Timegroup } from "@editframe/react";
+
+export const Video = () => {
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+      {/* Your composition */}
+    </Timegroup>
+  );
+};
+
+// main.tsx
+import ReactDOM from "react-dom/client";
+import { Configuration, TimelineRoot } from "@editframe/react";
+import { Video } from "./Video";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <Configuration apiHost="https://api.example.com" mediaEngine="local">
+    <TimelineRoot id="root" component={Video} />
+  </Configuration>
+);
+```
+<!-- /react-only -->
+
+## Media Engine Options
+
+<!-- html-only -->
+The `media-engine` attribute controls how media files are loaded and processed.
+<!-- /html-only -->
+<!-- react-only -->
+Controls how media files are loaded and processed. Three options are available:
+<!-- /react-only -->
+
+### Cloud Mode (Default)
+
+Automatically selects the appropriate engine based on URL:
+- Remote URLs (`http://`, `https://`) use JIT transcoding
+- Local paths use asset engine
+
+<!-- html-only -->
+```html live
+<ef-configuration media-engine="cloud">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black">
+    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+**Use when:** Building production applications with mixed local and remote assets.
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+<Configuration mediaEngine="cloud">
+  <Timegroup mode="sequence">
+    <Video src="https://cdn.example.com/video.mp4" /> {/* JIT transcoding */}
+    <Video src="/assets/local.mp4" /> {/* Local assets */}
+  </Timegroup>
+</Configuration>
+```
+<!-- /react-only -->
+
+### Local Mode
+
+Forces all sources through the local asset engine using `@ef-*` URLs:
+
+<!-- html-only -->
+```html
+<ef-configuration media-engine="local">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+**Use when:**
+- Development with local files only
+- Testing without network access
+- Working with bundled assets
+<!-- /html-only -->
+<!-- react-only -->
+- All sources use local asset endpoints
+- No transcoding applied
+- Best for local development with Vite plugin
+
+```tsx
+<Configuration mediaEngine="local">
+  <Timegroup mode="sequence">
+    <Video src="/assets/video.mp4" /> {/* → /@ef-assets/... */}
+  </Timegroup>
+</Configuration>
+```
+<!-- /react-only -->
+
+### JIT Mode
+
+Forces all sources through JIT transcoding using `/api/v1/transcode/*` URLs:
+
+<!-- html-only -->
+```html
+<ef-configuration media-engine="jit">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="https://example.com/video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+**Use when:**
+- On-demand transcoding needed
+- Working with incompatible video formats
+- Development with Editframe Vite plugin
+<!-- /html-only -->
+<!-- react-only -->
+- All sources are transcoded on-demand
+- Useful for testing transcoding behavior
+- May have slower initial load
+
+```tsx
+<Configuration mediaEngine="jit">
+  <Timegroup mode="sequence">
+    <Video src="/assets/video.mp4" /> {/* → /api/v1/transcode/... */}
+  </Timegroup>
+</Configuration>
+```
+<!-- /react-only -->
+
+## API Host Override
+
+When no `ef-configuration` ancestor is present, all source-based elements (`ef-video`, `ef-audio`, `ef-image`, `ef-captions`) fall back to `window.location.origin` as the API host. This means elements work without any configuration wrapper — API requests go to the same origin as the page, which is handled by the Vite plugin in development and by telecine in production.
+
+Use `ef-configuration` with `api-host` when you need to override that default:
+
+<!-- html-only -->
+Override the API host for asset resolution in production:
+
+```html
+<ef-configuration api-host="https://api.editframe.com">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+**Use when:**
+- Deploying to custom domains
+- Using proxy servers
+- Testing against staging environments
+<!-- /html-only -->
+<!-- react-only -->
+Set the API endpoint for transcription and rendering:
+
+```tsx
+<Configuration apiHost="https://api.editframe.com">
+  <Timegroup mode="sequence">
+    {/* Composition */}
+  </Timegroup>
+</Configuration>
+```
+<!-- /react-only -->
+
+## Signing URL
+
+Configure the endpoint for generating signed URLs:
+
+<!-- html-only -->
+```html
+<ef-configuration signing-url="/api/sign-url">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+**Use when:**
+- Custom authentication flows
+- Non-standard URL signing
+- Backend integration requirements
+<!-- /html-only -->
+<!-- react-only -->
+Defaults to `/@ef-sign-url`:
+
+```tsx
+<Configuration
+  apiHost="https://api.example.com"
+  signingURL="/custom-signing-endpoint"
+>
+  <Timegroup mode="sequence">
+    {/* Composition */}
+  </Timegroup>
+</Configuration>
+```
+
+The signing URL is used to:
+- Generate signed URLs for secure media access
+- Authenticate transcoding requests
+- Control access to media files
+
+In development, the Vite plugin provides this endpoint automatically.
+<!-- /react-only -->
+
+## Development vs Production
+
+<!-- html-only -->
+### Local Development Setup
+
+Use `local` mode with Vite plugin for fast iteration:
+
+```html
+<ef-configuration media-engine="local" signing-url="/@ef-sign-url">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="./assets/video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+### Production Setup
+
+Use `cloud` mode with custom API host:
+
+```html
+<ef-configuration media-engine="cloud" api-host="https://api.yourdomain.com">
+  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
+    <ef-video src="https://cdn.yourdomain.com/video.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+const apiHost = import.meta.env.VITE_API_HOST || "http://localhost:3000";
+const mediaEngine = import.meta.env.PROD ? "cloud" : "local";
+
+export const Video = () => {
+  return (
+    <Configuration apiHost={apiHost} mediaEngine={mediaEngine}>
+      <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+        {/* Your composition */}
+      </Timegroup>
+    </Configuration>
+  );
+};
+```
+<!-- /react-only -->
+
+## Context Provision
+
+<!-- html-only -->
+`ef-configuration` provides settings via Lit context to all descendant elements. This means you only need one configuration wrapper at the root level:
+
+```html
+<ef-configuration media-engine="cloud">
+  <ef-timegroup mode="sequence" class="w-[720px] h-[480px]">
+    <!-- All children inherit configuration -->
+    <ef-video src="clip1.mp4" class="size-full"></ef-video>
+    <ef-video src="clip2.mp4" class="size-full"></ef-video>
+    <ef-video src="clip3.mp4" class="size-full"></ef-video>
+  </ef-timegroup>
+</ef-configuration>
+```
+<!-- /html-only -->
+<!-- react-only -->
+If you don't need API features (transcription) or want default settings, you can omit Configuration:
+
+```tsx
+export const Video = () => {
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+      {/* Your composition */}
+    </Timegroup>
+  );
+};
+```
+<!-- /react-only -->
+
+## Multiple Configurations
+
+<!-- html-only -->
+Nest configurations to override settings for specific subtrees:
+
+```html
+<ef-configuration media-engine="cloud">
+  <ef-timegroup mode="sequence" class="w-[720px] h-[480px]">
+    <!-- Remote video uses cloud mode -->
+    <ef-video src="https://cdn.example.com/intro.mp4" class="size-full"></ef-video>
+
+    <!-- Local videos use local mode -->
+    <ef-configuration media-engine="local">
+      <ef-video src="./local-clip.mp4" class="size-full"></ef-video>
+    </ef-configuration>
+  </ef-timegroup>
+</ef-configuration>
+```
+
+> **Note:** Inner configurations override outer settings only for their descendants. Settings merge — unspecified attributes inherit from parent configuration.
+<!-- /html-only -->
+<!-- react-only -->
+## Typical Setup
+
+```tsx
+// VideoComposition.tsx
+import { Timegroup, Video, Audio } from "@editframe/react";
+
+export const VideoComposition = () => {
+  return (
+    <Timegroup
+
+      mode="sequence"
+      className="w-[1920px] h-[1080px] bg-black"
+    >
+      <Timegroup mode="fixed" duration="10s" className="absolute w-full h-full">
+        <Video src="/assets/intro.mp4" className="size-full object-cover" />
+        <Audio src="/assets/music.mp3" volume={0.3} />
+      </Timegroup>
+    </Timegroup>
+  );
+};
+
+// main.tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { Configuration, TimelineRoot } from "@editframe/react";
+import { VideoComposition } from "./VideoComposition";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <Configuration
+    apiHost={import.meta.env.VITE_EDITFRAME_API}
+    mediaEngine="local"
+  >
+    <TimelineRoot id="root" component={VideoComposition} />
+  </Configuration>
+);
+```
+<!-- /react-only -->

package/dist/skills/editframe-composition/references/css-parts.md

@@ -0,0 +1,105 @@
+---
+title: CSS Parts Reference
+description: "Catalog of CSS ::part() selectors for styling internal shadow DOM elements of Editframe web components from external stylesheets."
+type: reference
+nav:
+  parent: "Advanced"
+  priority: 60
+  related: ["css-variables", "editor-toolkit"]
+---
+
+# CSS Parts Reference
+
+Editframe elements use Shadow DOM to encapsulate internal markup. Each component exposes named parts via the `part` attribute, letting you style internals with `::part()` CSS selectors without breaking encapsulation.
+
+## ef-scrubber
+
+| Part | Description |
+|------|-------------|
+| `scrubber` | Outer track container |
+| `progress` | Filled portion indicating current position |
+| `handle` | Draggable circular knob |
+| `playhead` | Vertical line at the current time position |
+
+```css
+ef-scrubber::part(scrubber) { background: #1a1a2e; border-radius: 4px; }
+ef-scrubber::part(progress) { background: #e94560; }
+ef-scrubber::part(handle)   { background: #e94560; width: 14px; height: 14px; }
+```
+
+## ef-time-display
+
+| Part | Description |
+|------|-------------|
+| `time` | Span containing the formatted `current / duration` text |
+
+```css
+ef-time-display::part(time) { font-family: monospace; color: #aaa; }
+```
+
+## ef-workbench
+
+| Part | Description |
+|------|-------------|
+| `toolbar` | Top toolbar row with mode indicators and controls |
+| `canvas` | Central preview area where the composition is rendered |
+
+## ef-timeline
+
+| Part | Description |
+|------|-------------|
+| `header` | Controls row above the tracks (playback, time display, zoom) |
+| `tracks` | Scrollable viewport containing all track rows |
+| `ruler` | Time ruler bar along the top of the tracks area |
+| `playhead` | Vertical playhead line spanning all tracks |
+
+## ef-timeline-row
+
+| Part | Description |
+|------|-------------|
+| `label` | Row label area (element name, icon, detail text) |
+| `track` | Row track area displaying the clip bar |
+
+## ef-hierarchy
+
+| Part | Description |
+|------|-------------|
+| `list` | Outer container wrapping the hierarchy tree |
+| `header` | Optional header above the tree items |
+
+## ef-hierarchy-item
+
+| Part | Description |
+|------|-------------|
+| `row` | Item row container (receives `data-focused` and `data-selected` attributes) |
+| `icon` | Element-type icon span |
+| `label` | Element name text span |
+
+## Combined Example
+
+Style an entire editor theme by targeting parts across multiple elements:
+
+```css
+/* Dark coral theme */
+ef-workbench::part(toolbar)  { background: #1a1a2e; }
+ef-workbench::part(canvas)   { background: #0f0f1a; }
+
+ef-scrubber::part(scrubber)  { background: #16213e; height: 6px; }
+ef-scrubber::part(progress)  { background: #e94560; }
+ef-scrubber::part(handle)    { background: #e94560; }
+
+ef-timeline::part(header)    { background: #16213e; }
+ef-timeline::part(ruler)     { background: #0f3460; }
+ef-timeline::part(playhead)  { background: #e94560; }
+
+ef-time-display::part(time)  { color: #e94560; font-variant-numeric: tabular-nums; }
+
+ef-hierarchy-item::part(row):hover { background: rgba(255, 255, 255, 0.05); }
+ef-hierarchy-item::part(label)     { font-size: 0.75rem; }
+```
+
+## Notes
+
+- `::part()` selectors cannot be chained -- `::part(a)::part(b)` is invalid. Style each part independently.
+- Parts work inside media queries, container queries, and `:host()` selectors.
+- For nested shadow roots, use `exportparts` on the host to forward inner parts to outer consumers.