@warpgogol/forge 1.1.0 → 1.2.2

package/profiles/obsidian-vault.yaml

@@ -1,103 +0,0 @@
-schema: forge/stack-profile@1
-id: obsidian-vault
-displayName: Obsidian Knowledge Base
-detect:
-  anyOf:
-    - .obsidian/app.json
-    - vault/**/*.md
-domain: knowledge-base
-register: creative
-terminology:
-  artifact: note
-  artifactPlural: notes
-  module: folder
-  source: markdown file
-  output: export
-  verify: link-check
-  operator: author
-scriptDir: scripts
-artifacts:
-  - id: note
-    extensions:
-      - .md
-    validate:
-      command: note.link.validate
-  - id: canvas
-    extensions:
-      - .canvas
-  - id: attachment
-    extensions:
-      - .png
-      - .jpg
-      - .jpeg
-      - .webp
-      - .svg
-      - .pdf
-      - .mp4
-      - .webm
-workspaceTypes:
-  - id: vault
-    detect:
-      glob: "**/*.md"
-      contains: "---"
-invariants:
-  - id: NOTE-01
-    rule: All [[wikilinks]] must resolve to an existing note file
-    severity: error
-    check:
-      kind: link-resolution
-      glob: "vault/**/*.md"
-  - id: NOTE-02
-    rule: Every note must have a title in frontmatter (title or first H1)
-    severity: warning
-    check:
-      kind: frontmatter-required
-      glob: "vault/**/*.md"
-      fields: [title]
-  - id: NOTE-03
-    rule: No executable code files in vault/ (scripts go to scripts/ per ADR-0043)
-    severity: error
-    check:
-      kind: path-exclusion
-      glob: "vault/**/*.{ts,mjs,js,py,sh}"
-  - id: NOTE-04
-    rule: Note filenames must use kebab-case (lowercase letters, digits, hyphens)
-    severity: warning
-    check:
-      kind: filename-pattern
-      glob: "vault/**/*.md"
-      pattern: "^[a-z0-9]+(-[a-z0-9]+)*\\.md$"
-workspace:
-  dirs:
-    - vault
-    - scripts
-    - .forge
-  files:
-    - path: .gitignore
-      content: |
-        node_modules
-        .obsidian/workspace
-        .obsidian/workspace.json
-        .cache
-        operator-profile.md
-    - path: forge.yaml
-      content: |
-        schema: forge/config@1
-        project:
-          name: __PROJECT_NAME__
-          stack:
-            - obsidian-vault
-          packageManager: pnpm
-        paths:
-          rfcsDir: docs/rfcs
-          adrsDir: docs/adrs
-    - path: package.json
-      content: |
-        {
-          "name": "__PROJECT_NAME__",
-          "version": "0.1.0",
-          "private": true,
-          "type": "module"
-        }
-install:
-  - pnpm add -D @warpgogol/forge

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

@@ -1,92 +0,0 @@
----
-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 { Timegroup, Video, Image, Text } from "@editframe/react";
-
-export default function BrandIntro() {
-  return (
-    <Timegroup duration="3s" mode="sequence">
-      <Image src="assets/logo.svg" duration="1s" fit="contain" />
-      <Text duration="1s" style={{ color: "#FF6B00", fontSize: "64px" }}>
-        Your Brand
-      </Text>
-      <Video src="assets/brand-bg.mp4" fit="cover" duration="1s" />
-    </Timegroup>
-  );
-}
-```
-
-## 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 duration="1.5s" style={{ color: "#FF6B00", fontSize: "48px" }}>Your Brand</Text>
-</Timegroup>
-```
-
-### Intro/outro pair
-
-Create separate compositions for intro and outro, then combine them in a parent `Timegroup`:
-
-```tsx
-<Timegroup duration="15s" mode="sequence">
-  <BrandIntro />
-  <MainContent />
-  <BrandOutro />
-</Timegroup>
-```
-
-### 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

@@ -1,156 +0,0 @@
----
-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 { Configuration, Timegroup, Video, Text, Audio, Captions, Workbench } from "@editframe/react";
-
-export default function Composition() {
-  return (
-    <Workbench resolution="1920x1080">
-      <Configuration>
-        <Timegroup
-          id="root"
-          duration="10s"
-          mode="contain"
-          style={{ width: "1920px", height: "1080px", background: "#000", display: "flex", alignItems: "center", justifyContent: "center" }}
-        >
-          <Video src="assets/background.mp4" fit="contain" duration="10s" />
-          <Text duration="5s" style={{ color: "white", fontSize: "48px", textAlign: "center" }}>
-            Hello, Editframe!
-          </Text>
-          <Audio src="assets/narration.mp3" />
-          <Captions src="assets/captions.vtt" />
-        </Timegroup>
-      </Configuration>
-    </Workbench>
-  );
-}
-```
-
-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. Inside a `Workbench`, use `Timegroup` directly as the root temporal element — do NOT wrap it in `TimelineRoot`, which renders a `<div style="display: contents">` wrapper that breaks Workbench's DOM structure.
-
-### 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` | `duration`, `split`, `stagger` — text content passed as children, styling via `style` prop or CSS classes |
-| `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,68 +0,0 @@
----
-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 (`Workbench`, `Configuration`, `Timegroup`, `Video`, `Audio`, `Text`, `Captions`). It is designed for projects using the `editframe` stack profile.
-
-**TimelineRoot check:** If `TimelineRoot` is used inside `Workbench`, report it as an error — it renders a `<div style="display: contents">` wrapper that breaks Workbench's DOM structure. The correct structure is `Workbench > Configuration > Timegroup`.
-
-## 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

@@ -1,107 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
----
-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`.