@editframe/elements 0.19.4-beta.0 → 0.20.0-beta.0

package/src/elements/updateAnimations.ts

@@ -1,6 +1,5 @@
 import {
   deepGetTemporalElements,
-  isEFTemporal,
   type TemporalMixinInterface,
 } from "./EFTemporal.ts";
 
@@ -8,7 +7,7 @@ import {
 export type AnimatableElement = TemporalMixinInterface & HTMLElement;
 
 // Constants
-const ANIMATION_PRECISION_OFFSET = 0.001;
+const ANIMATION_PRECISION_OFFSET = 0.1; // Use 0.1ms to safely avoid completion threshold
 const DEFAULT_ANIMATION_ITERATIONS = 1;
 const PROGRESS_PROPERTY = "--ef-progress";
 const DURATION_PROPERTY = "--ef-duration";
@@ -39,8 +38,40 @@ export const evaluateTemporalState = (
       ? 1
       : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));
 
+  // Root timegroups should remain visible at exact end time, but other elements use exclusive end for clean transitions
+  const isRootTimegroup =
+    element.tagName.toLowerCase() === TIMEGROUP_TAGNAME &&
+    !(element as any).parentTimegroup;
+  const useInclusiveEnd = isRootTimegroup;
+
   const isVisible =
-    element.startTimeMs <= timelineTimeMs && element.endTimeMs > timelineTimeMs;
+    element.startTimeMs <= timelineTimeMs &&
+    (useInclusiveEnd
+      ? element.endTimeMs >= timelineTimeMs
+      : element.endTimeMs > timelineTimeMs);
+
+  return { progress, isVisible, timelineTimeMs };
+};
+
+/**
+ * Evaluates element visibility specifically for animation coordination
+ * Uses inclusive end boundaries to prevent animation jumps at exact boundaries
+ */
+export const evaluateTemporalStateForAnimation = (
+  element: AnimatableElement,
+): TemporalState => {
+  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup
+  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;
+
+  const progress =
+    element.durationMs <= 0
+      ? 1
+      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));
+
+  // For animation coordination, use inclusive end for ALL elements to prevent visual jumps
+  const isVisible =
+    element.startTimeMs <= timelineTimeMs &&
+    element.endTimeMs >= timelineTimeMs;
 
   return { progress, isVisible, timelineTimeMs };
 };
@@ -80,9 +111,11 @@ const updateVisualState = (
 };
 
 /**
- * Coordinates animations to match timeline
+ * Coordinates animations for a single element and its subtree, using the element as the time source
  */
-const coordinateAnimations = (element: AnimatableElement): void => {
+const coordinateAnimationsForSingleElement = (
+  element: AnimatableElement,
+): void => {
   const animations = element.getAnimations({ subtree: true });
 
   for (const animation of animations) {
@@ -96,17 +129,12 @@ const coordinateAnimations = (element: AnimatableElement): void => {
     }
 
     const target = effect.target;
-    if (!target || target.closest(TIMEGROUP_TAGNAME) !== element) {
-      continue;
-    }
-
-    const timeTarget = isEFTemporal(target)
-      ? target
-      : target.closest(TIMEGROUP_TAGNAME);
-    if (!timeTarget) {
+    if (!target) {
       continue;
     }
 
+    // For animations in this element's subtree, always use this element as the time source
+    // This handles both animations directly on the temporal element and on its non-temporal children
     const timing = effect.getTiming();
     const duration = Number(timing.duration) || 0;
     const delay = Number(timing.delay) || 0;
@@ -118,8 +146,8 @@ const coordinateAnimations = (element: AnimatableElement): void => {
       continue;
     }
 
-    // All timegroups are temporal, so always use ownCurrentTimeMs for local time coordination
-    const currentTime = timeTarget.ownCurrentTimeMs ?? 0;
+    // Use the element itself as the time source (it's guaranteed to be temporal)
+    const currentTime = element.ownCurrentTimeMs ?? 0;
 
     if (currentTime < delay) {
       animation.currentTime = 0;
@@ -130,12 +158,22 @@ const coordinateAnimations = (element: AnimatableElement): void => {
     const currentIteration = Math.floor(adjustedTime / duration);
     const currentIterationTime = adjustedTime % duration;
 
+    // Calculate the total animation timeline length (delay + duration * iterations)
+    const totalAnimationLength = delay + duration * iterations;
+
+    // CRITICAL: Always keep currentTime below totalAnimationLength to prevent completion
+    const maxSafeCurrentTime =
+      totalAnimationLength - ANIMATION_PRECISION_OFFSET;
+
     if (currentIteration >= iterations) {
-      animation.currentTime = duration - ANIMATION_PRECISION_OFFSET;
+      // Animation would be complete - clamp to just before completion
+      animation.currentTime = maxSafeCurrentTime;
     } else {
-      animation.currentTime =
+      // Animation in progress - clamp to safe value within current iteration
+      const proposedCurrentTime =
         Math.min(currentIterationTime, duration - ANIMATION_PRECISION_OFFSET) +
         delay;
+      animation.currentTime = Math.min(proposedCurrentTime, maxSafeCurrentTime);
     }
   }
 };
@@ -151,7 +189,18 @@ export const updateAnimations = (element: AnimatableElement): void => {
   });
   updateVisualState(element, temporalState);
 
-  if (temporalState.isVisible) {
-    coordinateAnimations(element);
+  // Coordinate animations - use animation-specific visibility to prevent jumps at exact boundaries
+  const animationState = evaluateTemporalStateForAnimation(element);
+  if (animationState.isVisible) {
+    coordinateAnimationsForSingleElement(element);
   }
+
+  // Coordinate animations for child elements using animation-specific visibility
+  deepGetTemporalElements(element).forEach((temporalElement) => {
+    const childAnimationState =
+      evaluateTemporalStateForAnimation(temporalElement);
+    if (childAnimationState.isVisible) {
+      coordinateAnimationsForSingleElement(temporalElement);
+    }
+  });
 };

package/src/gui/ContextMixin.browsertest.ts

@@ -4,7 +4,6 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { ContextMixin } from "./ContextMixin.js";
 
-// Required to test timeupdate event, we need a duration, and timegroups are a quick way to do that
 import "../elements/EFTimegroup.js";
 
 @customElement("test-context")
@@ -529,30 +528,6 @@ describe("ContextMixin", () => {
     });
   });
 
-  test("Time update event when the currentTimeMs changed", async () => {
-    const timegroup = document.createElement("ef-timegroup");
-    timegroup.mode = "fixed";
-    timegroup.duration = "10s";
-
-    const preview = document.createElement("test-context");
-    preview.append(timegroup);
-    document.body.append(preview);
-
-    type CurrentTimeEvent = CustomEvent<{ currentTimeMs: number }>;
-
-    // Expect the timeupdate event to be dispatched
-    const timeupdatePromise = new Promise<CurrentTimeEvent>((resolve) => {
-      preview.addEventListener(
-        "timeupdate",
-        (event: Event) => resolve(event as CurrentTimeEvent),
-        { once: true },
-      );
-    });
-    preview.currentTimeMs = 1000;
-    const event = await timeupdatePromise;
-    expect(event.detail.currentTimeMs).toBe(1000);
-  });
-
   describe("Reactivity", () => {
     test("should update durationMs when child tree changes", async () => {
       const element = document.createElement("test-context-reactivity");

package/src/gui/ContextMixin.ts

@@ -4,6 +4,8 @@ import { property, state } from "lit/decorators.js";
 import { EF_RENDERING } from "../EF_RENDERING.ts";
 import type { EFTimegroup } from "../elements/EFTimegroup.js";
 import { globalURLTokenDeduplicator } from "../transcoding/cache/URLTokenDeduplicator.js";
+import { currentTimeContext } from "./currentTimeContext.js";
+import { durationContext } from "./durationContext.js";
 import {
   type EFConfiguration,
   efConfigurationContext,
@@ -74,15 +76,12 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
     targetTimegroup: EFTimegroup | null = null;
 
     // Add reactive properties that depend on the targetTimegroup
-    @state()
-    get durationMs(): number {
-      return this.targetTimegroup?.durationMs ?? 0;
-    }
+    @provide({ context: durationContext })
+    @property({ type: Number })
+    durationMs = 0;
 
-    @state()
-    get endTimeMs(): number {
-      return this.targetTimegroup?.endTimeMs ?? 0;
-    }
+    @property({ type: Number })
+    endTimeMs = 0;
 
     @provide({ context: fetchContext })
     fetch = async (url: string, init: RequestInit = {}) => {
@@ -248,7 +247,8 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
     @property({ type: Boolean })
     rendering = false;
 
-    @state()
+    @provide({ context: currentTimeContext })
+    @property({ type: Number })
     currentTimeMs = Number.NaN;
 
     #FPS = 30;
@@ -273,11 +273,24 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
           }
         } else if (mutation.type === "attributes") {
           // Watch for attribute changes that might affect duration
+          const durationAffectingAttributes = [
+            "duration",
+            "mode",
+            "trimstart",
+            "trimend",
+            "sourcein",
+            "sourceout",
+          ];
+
           if (
-            mutation.attributeName === "duration" ||
-            mutation.attributeName === "mode" ||
+            durationAffectingAttributes.includes(
+              mutation.attributeName || "",
+            ) ||
             (mutation.target instanceof Element &&
               (mutation.target.tagName === "EF-TIMEGROUP" ||
+                mutation.target.tagName === "EF-VIDEO" ||
+                mutation.target.tagName === "EF-AUDIO" ||
+                mutation.target.tagName === "EF-CAPTIONS" ||
                 mutation.target.closest("ef-timegroup")))
           ) {
             shouldUpdate = true;
@@ -289,6 +302,8 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
         // Trigger an update to ensure reactive properties recalculate
         // Use a microtask to ensure DOM updates are complete
         queueMicrotask(() => {
+          // Recalculate duration and endTime when timegroup changes
+          this.updateDurationProperties();
           this.requestUpdate();
           // Also ensure the targetTimegroup updates its computed properties
           if (this.targetTimegroup) {
@@ -298,11 +313,29 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
       }
     });
 
+    /**
+     * Update duration properties when timegroup changes
+     */
+    updateDurationProperties(): void {
+      const newDuration = this.targetTimegroup?.durationMs ?? 0;
+      const newEndTime = this.targetTimegroup?.endTimeMs ?? 0;
+
+      if (this.durationMs !== newDuration) {
+        this.durationMs = newDuration;
+      }
+
+      if (this.endTimeMs !== newEndTime) {
+        this.endTimeMs = newEndTime;
+      }
+    }
+
     connectedCallback(): void {
       super.connectedCallback();
 
       // Initialize targetTimegroup
       this.targetTimegroup = this.querySelector("ef-timegroup");
+      // Initialize duration properties
+      this.updateDurationProperties();
 
       this.#timegroupObserver.observe(this, {
         childList: true,
@@ -342,15 +375,6 @@ export function ContextMixin<T extends Constructor<LitElement>>(superClass: T) {
               return;
             }
             this.targetTimegroup.currentTimeMs = this.currentTimeMs;
-            this.dispatchEvent(
-              new CustomEvent("timeupdate", {
-                detail: {
-                  currentTimeMs: this.currentTimeMs,
-                  progress:
-                    this.currentTimeMs / this.targetTimegroup.durationMs,
-                },
-              }),
-            );
           }
         }
       }

package/src/gui/EFControls.browsertest.ts

@@ -0,0 +1,175 @@
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { beforeEach, describe, expect, test } from "vitest";
+
+import "../elements/EFTimegroup.js";
+import { EFTargetable } from "../elements/TargetController.js";
+import { ContextMixin } from "./ContextMixin.js";
+import "./EFControls.js";
+import { EFControls } from "./EFControls.js";
+import "./EFPreview.js";
+
+@customElement("test-context")
+class TestContext extends EFTargetable(ContextMixin(LitElement)) {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+beforeEach(() => {
+  // Clean up localStorage
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (typeof key !== "string") continue;
+    localStorage.removeItem(key);
+  }
+
+  // Clean up DOM
+  while (document.body.children.length) {
+    document.body.children[0]?.remove();
+  }
+});
+
+describe("EFControls", () => {
+  test("should be defined", () => {
+    expect(EFControls).toBeDefined();
+  });
+
+  test("can find and connect to target preview by ID", async () => {
+    // Create a preview with an ID
+    const preview = document.createElement("ef-preview") as any;
+    preview.id = "test-preview";
+
+    // Add a timegroup to the preview to give it duration
+    const timegroup = document.createElement("ef-timegroup");
+    timegroup.mode = "fixed";
+    timegroup.duration = "10s";
+    preview.appendChild(timegroup);
+
+    document.body.appendChild(preview);
+
+    // Create controls targeting the preview
+    const controls = document.createElement("ef-controls");
+    controls.target = "test-preview";
+    document.body.appendChild(controls);
+
+    // Wait for both elements to complete their updates
+    await preview.updateComplete;
+    await controls.updateComplete;
+
+    // The controls should have found and connected to the preview
+    expect(controls.targetElement).toBe(preview);
+  });
+
+  test("handles missing target gracefully", async () => {
+    const controls = document.createElement("ef-controls");
+    controls.target = "nonexistent-preview";
+    document.body.appendChild(controls);
+
+    // Wait for the controller to attempt connection
+    await controls.updateComplete;
+
+    // Should have no target but not crash
+    expect(controls.targetElement).toBe(null);
+    // Note: EFControls with context proxying doesn't have playing property
+    // It only proxies context requests to the target element
+  });
+
+  test("updates when target is set after connection", async () => {
+    const controls = document.createElement("ef-controls") as EFControls;
+    document.body.appendChild(controls);
+
+    // Initially no target
+    expect(controls.targetElement).toBe(null);
+
+    // Create preview
+    const preview = document.createElement("test-context") as TestContext;
+    preview.id = "test-preview";
+
+    const timegroup = document.createElement("ef-timegroup");
+    timegroup.mode = "fixed";
+    timegroup.duration = "10s";
+    preview.appendChild(timegroup);
+
+    document.body.appendChild(preview);
+
+    // Set target after both are connected
+    controls.target = "test-preview";
+
+    // Wait for both elements to complete their updates
+    await preview.updateComplete;
+    await controls.updateComplete;
+
+    // The controls should have found and connected to the target
+    expect(controls.targetElement).toBe(preview);
+  });
+
+  test("disconnects from target when removed", async () => {
+    const preview = document.createElement("test-context") as TestContext;
+    preview.id = "test-preview";
+
+    const timegroup = document.createElement("ef-timegroup");
+    timegroup.mode = "fixed";
+    timegroup.duration = "10s";
+    preview.appendChild(timegroup);
+
+    document.body.appendChild(preview);
+
+    const controls = document.createElement("ef-controls") as EFControls;
+    controls.target = "test-preview";
+    document.body.appendChild(controls);
+
+    // Wait for both elements to complete their updates
+    await preview.updateComplete;
+    await controls.updateComplete;
+
+    // Should be connected
+    expect(controls.targetElement).toBe(preview);
+
+    // Disconnect the controls
+    document.body.removeChild(controls);
+
+    // After disconnection, targetElement persists but should have no effect
+    // (TargetController only clears targetElement when target is removed, not when consumer disconnects)
+    expect(controls.targetElement).toBe(preview);
+  });
+
+  test("works with child control elements - EFTogglePlay", async () => {
+    // Import the control element
+    await import("./EFTogglePlay.js");
+
+    const preview = document.createElement("test-context") as TestContext;
+    preview.id = "test-preview";
+    preview.playing = false;
+
+    const timegroup = document.createElement("ef-timegroup");
+    timegroup.mode = "fixed";
+    timegroup.duration = "10s";
+    preview.appendChild(timegroup);
+
+    document.body.appendChild(preview);
+
+    const controls = document.createElement("ef-controls") as EFControls;
+    controls.target = "test-preview";
+
+    const togglePlay = document.createElement("ef-toggle-play");
+    controls.appendChild(togglePlay);
+
+    document.body.appendChild(controls);
+
+    // Wait for all elements to complete their updates
+    await preview.updateComplete;
+    await controls.updateComplete;
+    await togglePlay.updateComplete;
+
+    // The toggle play should be connected to the controls' context (which syncs with preview)
+    expect((togglePlay as any).playing).toBe(false);
+
+    // Test that clicking the toggle affects the preview
+    preview.playing = true;
+    await preview.updateComplete;
+    await togglePlay.updateComplete;
+
+    expect((togglePlay as any).playing).toBe(true);
+  });
+});

package/src/gui/EFControls.ts

@@ -0,0 +1,84 @@
+import { css, html, LitElement } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+
+import { ContextProxyController } from "../elements/ContextProxiesController.js";
+import { TargetController } from "../elements/TargetController.js";
+import type { ContextMixinInterface } from "./ContextMixin.js";
+import { targetTimegroupContext } from "./ContextMixin.js";
+import { currentTimeContext } from "./currentTimeContext.js";
+import { durationContext } from "./durationContext.js";
+import { efConfigurationContext } from "./EFConfiguration.js";
+import { efContext } from "./efContext.js";
+import { fetchContext } from "./fetchContext.js";
+import { focusContext } from "./focusContext.js";
+import { focusedElementContext } from "./focusedElementContext.js";
+import { loopContext, playingContext } from "./playingContext.js";
+
+/**
+ * EFControls provides a way to control an ef-preview element that is not a direct ancestor.
+ * It bridges the contexts from a target preview element to its children controls.
+ *
+ * Usage:
+ * ```html
+ * <ef-preview id="my-preview">...</ef-preview>
+ *
+ * <ef-controls target="my-preview">
+ *   <ef-toggle-play>
+ *     <button slot="play">Play</button>
+ *     <button slot="pause">Pause</button>
+ *   </ef-toggle-play>
+ *   <ef-scrubber></ef-scrubber>
+ *   <ef-time-display></ef-time-display>
+ * </ef-controls>
+ * ```
+ */
+@customElement("ef-controls")
+export class EFControls extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+  `;
+
+  /**
+   * The ID of the ef-preview element to control
+   */
+  @property({ type: String })
+  target = "";
+
+  /**
+   * The target element (set by TargetController)
+   */
+  @state()
+  targetElement: ContextMixinInterface | null = null;
+
+  // @ts-expect-error controller is intentionally not referenced directly
+  #targetController = new TargetController(this);
+
+  // @ts-expect-error controller is intentionally not referenced directly
+  #contextProxyController = new ContextProxyController(this, {
+    target: () => this.targetElement,
+    contexts: [
+      playingContext,
+      loopContext,
+      currentTimeContext,
+      durationContext,
+      targetTimegroupContext,
+      focusedElementContext,
+      efContext,
+      fetchContext,
+      focusContext,
+      efConfigurationContext,
+    ],
+  });
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ef-controls": EFControls;
+  }
+}