Editor Gui

Editor Toolkit

Build a video editing interface by composing GUI components. Each component is a self-contained custom element. Each component connects to your composition through a target attribute. Build the composition itself with the composition skill. These components add the controls and views around it.

Quick Start

<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>

ef-timegroup sets no mode here, so it defaults to contain. Its duration comes from video.mp4's own length, not from a hardcoded number. See the composition skill's Timegroups & sequencing section for the full duration model.

Core Concepts: Target & 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. This resolves directly.
2. Otherwise, it walks up through ancestor ef-controls, ef-preview, and ef-configuration elements. An ancestor with its own target resolves there, in one hop. A bare ef-configuration ancestor resolves to itself. The control climbs past a bare ef-controls or ef-preview ancestor to look further up.
3. As a last resort, it resolves to the nearest enclosing temporal root.

ef-controls is a pure proxy. It renders nothing itself. It gives a group of descendant controls a shared target, so each control does not need its own:

<ef-timegroup id="my-video" mode="contain">…</ef-timegroup>

<!-- Elsewhere in the DOM -->
<ef-controls target="my-video">
  <ef-toggle-play></ef-toggle-play>
  <ef-scrubber></ef-scrubber>
</ef-controls>

ef-canvas, ef-hierarchy, and ef-timeline share selection state through a separate, independent mechanism: a shared SelectionBridge, keyed by the resolved composition root. This is not the playback bridge above. Selecting a row in ef-hierarchy highlights it in ef-canvas, and the reverse also works. Neither element needs to reference the other directly.

Preview & Canvas

ef-preview is a thin passthrough container. It tracks which element the pointer hovers over, and fires focus-changed. ef-canvas uses it internally for hover highlighting.

ef-canvas wraps your composition as light-DOM children, the same as ef-preview. It adds click-to-select, drag-to-move, corner-resize, and rotate directly on top of your composition. It shares selection state with ef-hierarchy and ef-timeline through SelectionBridge. When you set no explicit target, it auto-assigns one from the first slotted temporal child's id. Set readonly to keep the overlays visible but non-interactive.

<ef-canvas class="relative">
  <ef-timegroup id="scene" mode="contain" class="w-[1920px] h-[1080px]">
    <ef-video id="bg" src="/bg.mp4" class="absolute inset-0 size-full object-cover"></ef-video>
    <ef-text id="title" duration="5s" class="absolute top-12 left-12 text-6xl text-white">Title</ef-text>
  </ef-timegroup>
</ef-canvas>

• Click a selectable element, any TemporalElement with an id, to select it. This replaces the current selection.
• Click the empty canvas background to deselect.
• Drag from the empty background to draw a marquee. This selects every element the marquee touches. Hold Shift or Cmd/Ctrl while you release, to add to the existing selection instead of replacing it.
• Drag a selection box's body to move it.
• Drag a corner or edge handle to resize it. Hold Shift to lock the aspect ratio. Hold Cmd/Ctrl to resize from the center.
• Drag the rotate handle to rotate. Hold Shift to snap to 15° increments.
• ef-canvas fires a single canvas-transform event ({ elementId }) once a drag, resize, or rotate gesture ends. It does not fire continuously during the drag.
• ef-canvas has no built-in keyboard support: no arrow-key nudge, no delete, and so on. It also has no multi-select through a Shift-click or Cmd-click on a single element. Only marquee-drag supports additive multi-select.

ef-pan-zoom wraps its content in a pannable, zoomable viewport. Drag to pan. Use the wheel or a pinch gesture to zoom. It exposes screenToCanvas(), canvasToScreen(), reset(), and fitToContent() methods, plus a transform-changed event. It has no shadow root. Its content wrapper is a plain light-DOM child, exposed as [part="content"].

ef-fit-scale is a light-DOM container. It scales its first child to fit the available space, while it preserves the aspect ratio. It recalculates the scale on every ResizeObserver or MutationObserver change. Use it, typically, to wrap a fixed-resolution composition inside ef-pan-zoom.

Playback & Display Controls

ef-play and ef-pause each hide themselves while playing or paused. Wrap your own button as their default-slot content. ef-toggle-play swaps its slot="play"/slot="pause" content on click. ef-toggle-loop toggles loop mode on click. All three resolve their target through the target/bridge pattern above.

ef-volume is a native range slider, from 0 to 1, bound to the resolved composition's volume. ef-mute swaps its slot="muted"/slot="unmuted" content on click. ef-fullscreen and ef-pip toggle the Fullscreen and Picture-in-Picture APIs on their target. Each swaps its slot="enter"/slot="exit" content on click. ef-pip's target can be a <video>, a <canvas> (through captureStream()), or a container to search within. ef-resolution is a dropdown plus custom width/height inputs. It sets a target element's inline CSS size and fires resolution-change.

Timeline

ef-timeline composes a sticky hierarchy column, per-element track rows, and a time ruler into one scrollable region. It adds trim handles, thumbnail strips, and waveform strips automatically, per row, for each trimmable video or audio element. There is no flag to enable them.

<ef-timegroup id="comp" mode="sequence" class="w-[1920px] h-[1080px]">
  <ef-video src="/clip.mp4" duration="5s"></ef-video>
  <ef-text duration="5s">Title</ef-text>
</ef-timegroup>

<div class="h-64">
  <ef-timeline target="comp" pixels-per-second="80"></ef-timeline>
</div>

ef-timeline shares selection with ef-canvas/ef-hierarchy through SelectionBridge and fires timeline-select per row. It has no filtering attributes (hide/show), no zoom-limit attribute, and no panel-visibility attribute. See the Element Reference below for its actual, small attribute set.

Standalone timeline pieces (each also usable outside ef-timeline, and each covered fully by the Element Reference below):

• ef-scrubber — a playhead scrubber. orientation="horizontal" (the default) renders a progress bar with a drag handle, sized to the track's own width. orientation="vertical" renders a thin playhead line, positioned through pixels-per-second, for use inside a scrolling timeline track. Its times use milliseconds (current-time-ms, duration-ms).
• ef-time-display — formats currentTime / duration, in seconds, as M:SS / M:SS, from the resolved PlaybackBridge. It accepts only target. It does not accept standalone current-time-ms/duration-ms override attributes.
• ef-timeline-ruler — canvas-rendered tick marks and second labels. It reads duration, pixels-per-second, and fps, or duration-ms and zoom-scale for Motion-Designer-style timelines.
• ef-trim-handles — draggable in and out points. mode="standalone" shows a full draggable region between the two handles. mode="track" pins the handles to the container's edges. ef-timeline's rows use this mode. Its times use seconds (intrinsic-duration, pixels-per-second), a different unit convention than ef-scrubber. value ({start, end}) is a JS property, not an attribute. It fires trim-change continuously, and fires trim-change-end once.
• ef-thumbnail-strip and ef-waveform-strip — mirror a source <ef-video>/<ef-audio>'s own attributes directly: src, variants, sourcein/sourceout, trimstart/trimend. Neither takes a target id reference. For standalone use, set these attributes side by side with the source element, or copy them from it. Inside ef-timeline, this wiring happens automatically, per row.

Transform & Manipulation

ef-transform-handles is a controlled overlay. It does not track a target element itself. Position it explicitly through its bounds JS property: {x, y, width, height, rotation?}, in the host's local pixel space. Then apply the result of its bounds-change/rotation-change events back onto your own target element, and back onto bounds.

<div style="position: relative;">
  <ef-video id="clip" src="/clip.mp4" style="position: absolute;"></ef-video>
  <ef-transform-handles id="handles" enable-rotation></ef-transform-handles>
</div>
<script>
  const clip = document.getElementById("clip");
  const handles = document.getElementById("handles");
  handles.bounds = { x: 0, y: 0, width: 320, height: 180 };
  handles.addEventListener("bounds-change", (e) => {
    const { x, y, width, height } = e.detail.bounds;
    Object.assign(clip.style, { left: `${x}px`, top: `${y}px`, width: `${width}px`, height: `${height}px` });
    handles.bounds = e.detail.bounds;
  });
</script>

Resizing supports Shift to lock the aspect ratio, through lock-aspect-ratio-style constraints, and a rotation-step for angle snapping. corners-only hides the edge handles. enable-drag, enable-resize, and enable-rotation each toggle one interaction independently. This element is the general-purpose building block behind ef-canvas's own built-in selection boxes. Use it directly when you need transform handles decoupled from canvas selection.

ef-dial is a circular drag control. It produces a value in degrees, from 0 to 360, wrapping. value is a JS property only. It has no observed HTML attribute. <ef-dial value="45"> will not initialize the dial at 45°. Set .value after you create the element instead. Hold Shift while you drag, to snap to 15° increments. It fires change.

Overlay System

ef-overlay-layer and ef-overlay-item implement a pattern different from target/bridge. They passively follow a target element's on-screen position every frame, through the shared RAF scheduler, instead of controlling playback. ef-overlay-layer must be a sibling of ef-pan-zoom, or nested inside it, to stay aligned as the user pans and zooms.

<ef-pan-zoom>
  <ef-fit-scale>
    <ef-timegroup id="comp" mode="contain" class="w-[1920px] h-[1080px]">
      <ef-video id="clip" src="/clip.mp4"></ef-video>
    </ef-timegroup>
  </ef-fit-scale>
</ef-pan-zoom>
<ef-overlay-layer>
  <ef-overlay-item id="clip-overlay">
    <div class="border-2 border-blue-500"></div>
  </ef-overlay-item>
</ef-overlay-layer>
<script>
  document.getElementById("clip-overlay").target = "clip";
</script>

Set the target through the target JS property. Pass a CSS selector string (this falls back to getElementById for a plain id) or a direct element reference. The element-id HTML attribute offers an alternate lookup: it matches a target's data-element-id/data-timegroup-id attribute instead. Nothing in a composition sets these two data attributes by default. Add them yourself. This element fires position-changed, with the tracked target's {x, y, width, height, rotation}, whenever the target moves by more than 0.01px.

Editor Shells

ef-workbench composes a hierarchy panel, a canvas with selection, a timeline, and transport controls into a full three-panel editor layout. Transport controls (play, pause, loop, time) are separate from the toolbar. ef-workbench takes a single default slot, your composition, and auto-wraps it in <ef-configuration>/<ef-canvas> when not already wrapped. There are no slot="canvas", slot="hierarchy", or slot="timeline" slots.

<ef-workbench class="w-full h-screen" resolution="1920x1080">
  <ef-timegroup mode="sequence" class="w-[1920px] h-[1080px]">
    <ef-timegroup mode="fixed" duration="3s">
      <ef-text duration="3s">Opening</ef-text>
    </ef-timegroup>
    <ef-video src="/clip.mp4"></ef-video>
  </ef-timegroup>
</ef-workbench>

resolution ("WIDTHxHEIGHT") sets the composition's true rendered size. This is the fixed-size stage that ef-pan-zoom/fitToContent() scales to fit. Call .exportVideo(options?) to render the composition to an MP4, through an offscreen render clone. The live preview stays untouched. This method dispatches bubbling export-start, export-progress, export-complete, and export-error events. The toolbar Export button uses this same method. A .previewMode JS property ("dom" | "canvas", not an attribute) switches between the live DOM composition and a canvas-rasterized preview. A native render host sets rendering to collapse the workbench to just the bare stage. Do not use rendering as a "hide toolbar" convenience flag for normal use.

ef-hierarchy is a standalone layer-panel tree. Use it independently, without ef-workbench. It shares the same target/selection-sharing pattern as ef-canvas. Point both elements at the same composition root id, not at ef-canvas's own id, so their SelectionBridges resolve to the same root and stay in sync:

<ef-hierarchy target="comp" show-header header="Layers" class="w-64"></ef-hierarchy>
<ef-canvas>
  <ef-timegroup id="comp" mode="contain" class="w-[1920px] h-[1080px]">…</ef-timegroup>
</ef-canvas>

It shares selection with ef-canvas/ef-timeline through SelectionBridge, not through @lit/context. This version of Editframe removes @lit/context entirely. .select(id) and .getSelectedElementId() control selection. .setHighlighted(el) and .getHighlightedElement() control hover-highlight, and fire hierarchy-highlight. Dragging a row fires hierarchy-reorder, with { sourceId, targetId, position }. hideSelectors and showSelectors (string-array JS properties, not attributes) filter which elements appear, by CSS selector.

Element Reference

ef-canvas

Adds a selection and hover overlay to a composition's DOM subtree, with click-to-select, drag-to-move, and corner-resize.

Attributes

Slots

• (default slot) — Composition elements registered with the canvas for selection, drag, and resize actions.

Fires

• canvas-transform ({ elementId: string }) — Fires when a drag, resize, or rotate gesture on a selection box ends.

ef-canvas-selection-box

This element draws one selection or hover box.

ef-composition-thumbnail-strip

This element is a nested-composition filmstrip.

Attributes

CSS parts

• canvas — This part is the canvas that renders the filmstrip.

ef-controls

The <ef-controls target="#preview"> element works as a proxy container.

Attributes

ef-dial

This is a circular dial that a user drags to set a value between 0 and 360 degrees.

CSS custom properties

CSS parts

• container — The circular background of the dial.
• handle — A draggable knob that shows the current value.
• value — The numeric readout at the center of the dial.

Fires

• change ({ value: number }) — Fires each time the user drags the dial to a new value.

ef-fit-scale

This element is a light DOM container.

Attributes

ef-fullscreen

This element toggles the browser Fullscreen API on a target element.

Attributes

CSS parts

• button — The click target that contains the slotted enter and exit content.

Slots

• slot="enter" — Shown when the target element is not in fullscreen mode. Click the target to enter fullscreen.
• slot="exit" — Shown while the target element is in fullscreen mode. Click the target to exit fullscreen.

ef-hierarchy

This tree is aware of the DOM composition.

Attributes

CSS custom properties

CSS parts

• header — The optional header above the tree items. This part appears when the show-header attribute is set.
• list — The outer container that holds the hierarchy tree.

Fires

• hierarchy-highlight ({ element: Element \| null }) — Fires when the highlighted element changes, for example when the user hovers over it in ef-canvas. This event fires through EFHierarchyElement.setHighlighted.
• hierarchy-reorder ({ sourceId: string; targetId: string; position: "before" \| "after" \| "inside" }) — Fires when the user drags a row to a new position.
• hierarchy-select ({ elementId: string \| null }) — Fires when the user clicks an element row, or when a script calls EFHierarchyElement.select directly.

Methods

• select(elementId: string | null): void — Select an element by its ID. Pass null instead to clear the selection.
• getSelectedElementId(): string | null — Returns the ID of the first selected element. Returns null if nothing is selected.
• getHighlightedElement(): Element | null — Returns the element currently highlighted through setHighlighted. Returns null if no element is highlighted.
• setHighlighted(el: Element | null): void — Sets the element that is highlighted from outside this element. For example, code can call this when the user hovers over the element in ef-canvas. This method also dispatches the hierarchy-highlight event.

ef-hierarchy-item

This element renders one row for EFHierarchyElement.

CSS custom properties

CSS parts

• badge — The badge span that shows the element type.
• children — The wrapper for nested child items.
• label — The span that shows the element name.
• row — The container for this item's row. This part receives the data-focused and data-selected attributes.

ef-mute

A click on this element toggles mute.

Attributes

CSS parts

• button — The click target that contains the slotted muted and unmuted content.

Slots

• slot="muted" — Shown while the target is muted. Click the target to unmute it.
• slot="unmuted" — Shown while the target is unmuted. Click the target to mute it.

ef-overlay-item

This element is a passive overlay item.

Attributes

Slots

• (default slot) — This slot holds the content that appears over the target element.

Fires

• position-changed ({ x: number; y: number; width: number; height: number; rotation: number; }) — This event fires when the target element's position, size, or rotation changes by more than 0.01px.

ef-overlay-layer

This element is an overlay container.

Slots

• (default slot) — This slot accepts one or more ef-overlay-item or ef-transform-handles elements.

ef-pause

This element hides itself while the target is paused.

Attributes

CSS parts

• button — The click target that contains the slotted icon or label content.

Slots

• (default slot) — Place your own button or icon element here. Click it to pause playback.

ef-pip

This element is a Picture-in-Picture toggle.

Attributes

CSS parts

• button — The click target that contains the slotted enter and exit content.

Slots

• slot="enter" — Shown when the target is not in Picture-in-Picture mode. Click the target to enter Picture-in-Picture mode.
• slot="exit" — Shown while the target is in Picture-in-Picture mode. Click the target to exit Picture-in-Picture mode.

ef-play

This element hides itself while the target plays.

Attributes

CSS parts

• button — The click target that contains the slotted icon or label content.

Slots

• (default slot) — Place your own button or icon element here. Click it to start playback.

ef-preview

This is a thin passthrough container.

Fires

• focus-changed ({ element: HTMLElement \| null }) — Fires when the hovered element changes. The detail.element field holds the new element, or null when nothing is focused.

ef-resolution

This element is a resolution picker for the inline CSS width and height styles of a target element.

Attributes

CSS custom properties

CSS parts

• height-input — The custom height number input. This part appears only in custom mode.
• select — The dropdown list of preset resolutions.
• separator — The "×" symbol between the width and height inputs.
• width-input — The custom width number input. This part appears only in custom mode.

Fires

• resolution-change ({ width: number; height: number }) — Fires with a { width, height } detail when the resolution changes. The change can come from a preset choice or a custom width and height input.

ef-scrubber

This element is a playhead scrubber.

Attributes

CSS custom properties

CSS parts

• handle — This part is the draggable circular knob.
• playhead — This part is the vertical line at the current time position.
• progress — This part is the filled portion. It shows the current position.
• scrubber — This part is the outer track container.

Fires

• seek (number) — This event fires when the user drags the scrubber to a new position.

ef-thumbnail-strip

This element is a video filmstrip with the same zoom and scroll behavior as the old EFThumbnailStrip.

Attributes

CSS parts

• canvas — This part is the canvas that renders the filmstrip.

ef-time-display

This element formats the currentTime and duration values, in seconds, from the resolved PlaybackBridge.

Attributes

CSS custom properties

CSS parts

• time — The span that shows the formatted current time and duration text.

ef-timeline

This element renders the hierarchy and the track rows for a composition.

Attributes

CSS parts

• scrub-overlay — This part is the full-area overlay. It captures pointer drags while the user scrubs.

ef-timeline-row

This element renders one timeline row.

CSS custom properties

CSS parts

• bar — This part is the colored clip bar.
• label — This part is the row's label area. It shows the element name, an icon, and detail text.
• track — This part is the row's track area. It displays the clip bar.

Fires

• timeline-select ({ elementId: string }) — This event fires when the user clicks this row.

ef-timeline-ruler

This element is a time ruler with tick marks and second labels.

Attributes

CSS parts

• canvas — This part is the tick-mark canvas.
• container — This part is the outer ruler wrapper.

ef-toggle-loop

A click on this element toggles loop mode on the resolved PlaybackBridge.

Attributes

CSS parts

• button — The click target. This part sits directly on the <slot> element.

Slots

• (default slot) — Place your own button or icon element here. Click it to toggle loop mode.

ef-toggle-play

A click on this element toggles between play and pause.

Attributes

CSS parts

• button — The click target that contains the slotted play and pause content.

Slots

• slot="pause" — Shown while the target plays. Click the target to pause it.
• slot="play" — Shown while playback is paused. Click the target to start playback.

ef-transform-handles

This element is a selection overlay with drag, resize, and optional rotation handles.

Attributes

CSS custom properties

CSS parts

• drag-area — This part is an invisible drag surface that covers the overlay. It appears only when enable-drag is true.
• handle — This part matches every resize handle. There are eight handles by default, or four when corners-only is true.
• handle-e — This part is the resize handle on the east edge.
• handle-n — This part is the resize handle on the north edge.
• handle-ne — This part is the resize handle in the northeast corner.
• handle-nw — This part is the resize handle in the northwest corner.
• handle-s — This part is the resize handle on the south edge.
• handle-se — This part is the resize handle in the southeast corner.
• handle-sw — This part is the resize handle in the southwest corner.
• handle-w — This part is the resize handle on the west edge.
• overlay — This part is the outer bounding box that sits over the selected element.
• rotate-handle — This part is the hit area of the rotation handle. It appears only when enable-rotation is true.
• rotate-handle-circle — This part is the visible circular knob inside the rotation handle.

Fires

• bounds-change ({ bounds: { x: number; y: number; width: number; height: number; rotation?: number; } }) — This event fires on every pointer move during a drag or a resize action.
• rotation-change ({ rotation: number }) — This event fires during a rotation drag.

ef-tree

This element is a generic, data-driven tree.

Attributes

CSS custom properties

CSS parts

• container — This part is the outer tree wrapper.
• empty — This part is the empty-state message.
• header — This part is the optional header. It appears when show-header is true.

Fires

• tree-select ({ id: string \| null; item: TreeItem \| null }) — This event fires when the user clicks a row.

ef-tree-item

This element renders one row and a recursive children container, for EFTreeElement.

CSS custom properties

CSS parts

• children — This part is the wrapper around the nested child items. It receives the data-collapsed attribute.
• expand-icon — This part is the expand and collapse chevron.
• icon — This part is the optional item icon.
• label — This part is the item label text.
• row — This part is the item row. It receives the data-selected attribute.

ef-trim-handles

This element renders trim-in and trim-out handles, in seconds.

Attributes

CSS custom properties

…(truncated)