@editframe/elements 0.25.1-beta.0 → 0.26.1-beta.0

package/dist/elements/updateAnimations.js

@@ -73,7 +73,9 @@ const coordinateAnimationsForSingleElement = (element) => {
 		}
 		const adjustedTime = currentTime - delay;
 		const currentIteration = Math.floor(adjustedTime / duration);
-		const currentIterationTime = adjustedTime % duration;
+		let currentIterationTime = adjustedTime % duration;
+		const direction = timing.direction || "normal";
+		if (direction === "reverse" || direction === "alternate" && currentIteration % 2 === 1 || direction === "alternate-reverse" && currentIteration % 2 === 0) currentIterationTime = duration - currentIterationTime;
 		const maxSafeCurrentTime = delay + duration * iterations - ANIMATION_PRECISION_OFFSET;
 		if (currentIteration >= iterations) animation.currentTime = maxSafeCurrentTime;
 		else {

package/dist/elements/updateAnimations.js.map

@@ -1 +1 @@
-{"version":3,"file":"updateAnimations.js","names":[],"sources":["../../src/elements/updateAnimations.ts"],"sourcesContent":["import {\n  deepGetTemporalElements,\n  type TemporalMixinInterface,\n} from \"./EFTemporal.ts\";\n\n// All animatable elements are temporal elements with HTMLElement interface\nexport type AnimatableElement = TemporalMixinInterface & HTMLElement;\n\n// Constants\nconst ANIMATION_PRECISION_OFFSET = 0.1; // Use 0.1ms to safely avoid completion threshold\nconst DEFAULT_ANIMATION_ITERATIONS = 1;\nconst PROGRESS_PROPERTY = \"--ef-progress\";\nconst DURATION_PROPERTY = \"--ef-duration\";\nconst TRANSITION_DURATION_PROPERTY = \"--ef-transition-duration\";\nconst TRANSITION_OUT_START_PROPERTY = \"--ef-transition-out-start\";\n\n/**\n * Represents the temporal state of an element relative to the timeline\n */\ninterface TemporalState {\n  progress: number;\n  isVisible: boolean;\n  timelineTimeMs: number;\n}\n\n/**\n * Evaluates what the element's state should be based on the timeline\n */\nexport const evaluateTemporalState = (\n  element: AnimatableElement,\n): TemporalState => {\n  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup\n  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;\n\n  const progress =\n    element.durationMs <= 0\n      ? 1\n      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));\n\n  // Root elements and elements aligned with composition end should remain visible at exact end time\n  // Other elements use exclusive end for clean transitions\n  const isRootElement = !(element as any).parentTimegroup;\n  const isLastElementInComposition =\n    element.endTimeMs === element.rootTimegroup?.endTimeMs;\n  const useInclusiveEnd = isRootElement || isLastElementInComposition;\n\n  const isVisible =\n    element.startTimeMs <= timelineTimeMs &&\n    (useInclusiveEnd\n      ? element.endTimeMs >= timelineTimeMs\n      : element.endTimeMs > timelineTimeMs);\n\n  return { progress, isVisible, timelineTimeMs };\n};\n\n/**\n * Evaluates element visibility specifically for animation coordination\n * Uses inclusive end boundaries to prevent animation jumps at exact boundaries\n */\nexport const evaluateTemporalStateForAnimation = (\n  element: AnimatableElement,\n): TemporalState => {\n  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup\n  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;\n\n  const progress =\n    element.durationMs <= 0\n      ? 1\n      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));\n\n  // For animation coordination, use inclusive end for ALL elements to prevent visual jumps\n  const isVisible =\n    element.startTimeMs <= timelineTimeMs &&\n    element.endTimeMs >= timelineTimeMs;\n\n  return { progress, isVisible, timelineTimeMs };\n};\n\n/**\n * Updates the visual state (CSS + display) to match temporal state\n */\nconst updateVisualState = (\n  element: AnimatableElement,\n  state: TemporalState,\n): void => {\n  // Always set progress (needed for many use cases)\n  element.style.setProperty(PROGRESS_PROPERTY, `${state.progress * 100}%`);\n\n  // Handle visibility\n  if (!state.isVisible) {\n    if (element.style.display !== \"none\") {\n      element.style.display = \"none\";\n    }\n    return;\n  }\n\n  if (element.style.display === \"none\") {\n    element.style.display = \"\";\n  }\n\n  // Set other CSS properties for visible elements only\n  element.style.setProperty(DURATION_PROPERTY, `${element.durationMs}ms`);\n  element.style.setProperty(\n    TRANSITION_DURATION_PROPERTY,\n    `${element.parentTimegroup?.overlapMs ?? 0}ms`,\n  );\n  element.style.setProperty(\n    TRANSITION_OUT_START_PROPERTY,\n    `${element.durationMs - (element.parentTimegroup?.overlapMs ?? 0)}ms`,\n  );\n};\n\n/**\n * Coordinates animations for a single element and its subtree, using the element as the time source\n */\nconst coordinateAnimationsForSingleElement = (\n  element: AnimatableElement,\n): void => {\n  const animations = element.getAnimations({ subtree: true });\n\n  for (const animation of animations) {\n    if (animation.playState === \"running\") {\n      animation.pause();\n    }\n\n    const effect = animation.effect;\n    if (!(effect && effect instanceof KeyframeEffect)) {\n      continue;\n    }\n\n    const target = effect.target;\n    if (!target) {\n      continue;\n    }\n\n    // For animations in this element's subtree, always use this element as the time source\n    // This handles both animations directly on the temporal element and on its non-temporal children\n    const timing = effect.getTiming();\n    const duration = Number(timing.duration) || 0;\n    const delay = Number(timing.delay) || 0;\n    const iterations =\n      Number(timing.iterations) || DEFAULT_ANIMATION_ITERATIONS;\n\n    if (duration <= 0) {\n      animation.currentTime = 0;\n      continue;\n    }\n\n    // Use the element itself as the time source (it's guaranteed to be temporal)\n    const currentTime = element.ownCurrentTimeMs ?? 0;\n\n    if (currentTime < delay) {\n      animation.currentTime = 0;\n      continue;\n    }\n\n    const adjustedTime = currentTime - delay;\n    const currentIteration = Math.floor(adjustedTime / duration);\n    const currentIterationTime = adjustedTime % duration;\n\n    // Calculate the total animation timeline length (delay + duration * iterations)\n    const totalAnimationLength = delay + duration * iterations;\n\n    // CRITICAL: Always keep currentTime below totalAnimationLength to prevent completion\n    const maxSafeCurrentTime =\n      totalAnimationLength - ANIMATION_PRECISION_OFFSET;\n\n    if (currentIteration >= iterations) {\n      // Animation would be complete - clamp to just before completion\n      animation.currentTime = maxSafeCurrentTime;\n    } else {\n      // Animation in progress - clamp to safe value within current iteration\n      const proposedCurrentTime =\n        Math.min(currentIterationTime, duration - ANIMATION_PRECISION_OFFSET) +\n        delay;\n      animation.currentTime = Math.min(proposedCurrentTime, maxSafeCurrentTime);\n    }\n  }\n};\n\n/**\n * Main function: synchronizes DOM element with timeline\n */\nexport const updateAnimations = (element: AnimatableElement): void => {\n  const temporalState = evaluateTemporalState(element);\n  deepGetTemporalElements(element).forEach((temporalElement) => {\n    const temporalState = evaluateTemporalState(temporalElement);\n    updateVisualState(temporalElement, temporalState);\n  });\n  updateVisualState(element, temporalState);\n\n  // Coordinate animations - use animation-specific visibility to prevent jumps at exact boundaries\n  const animationState = evaluateTemporalStateForAnimation(element);\n  if (animationState.isVisible) {\n    coordinateAnimationsForSingleElement(element);\n  }\n\n  // Coordinate animations for child elements using animation-specific visibility\n  deepGetTemporalElements(element).forEach((temporalElement) => {\n    const childAnimationState =\n      evaluateTemporalStateForAnimation(temporalElement);\n    if (childAnimationState.isVisible) {\n      coordinateAnimationsForSingleElement(temporalElement);\n    }\n  });\n};\n"],"mappings":"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"}
+{"version":3,"file":"updateAnimations.js","names":[],"sources":["../../src/elements/updateAnimations.ts"],"sourcesContent":["import {\n  deepGetTemporalElements,\n  type TemporalMixinInterface,\n} from \"./EFTemporal.ts\";\n\n// All animatable elements are temporal elements with HTMLElement interface\nexport type AnimatableElement = TemporalMixinInterface & HTMLElement;\n\n// Constants\nconst ANIMATION_PRECISION_OFFSET = 0.1; // Use 0.1ms to safely avoid completion threshold\nconst DEFAULT_ANIMATION_ITERATIONS = 1;\nconst PROGRESS_PROPERTY = \"--ef-progress\";\nconst DURATION_PROPERTY = \"--ef-duration\";\nconst TRANSITION_DURATION_PROPERTY = \"--ef-transition-duration\";\nconst TRANSITION_OUT_START_PROPERTY = \"--ef-transition-out-start\";\n\n/**\n * Represents the temporal state of an element relative to the timeline\n */\ninterface TemporalState {\n  progress: number;\n  isVisible: boolean;\n  timelineTimeMs: number;\n}\n\n/**\n * Evaluates what the element's state should be based on the timeline\n */\nexport const evaluateTemporalState = (\n  element: AnimatableElement,\n): TemporalState => {\n  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup\n  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;\n\n  const progress =\n    element.durationMs <= 0\n      ? 1\n      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));\n\n  // Root elements and elements aligned with composition end should remain visible at exact end time\n  // Other elements use exclusive end for clean transitions\n  const isRootElement = !(element as any).parentTimegroup;\n  const isLastElementInComposition =\n    element.endTimeMs === element.rootTimegroup?.endTimeMs;\n  const useInclusiveEnd = isRootElement || isLastElementInComposition;\n\n  const isVisible =\n    element.startTimeMs <= timelineTimeMs &&\n    (useInclusiveEnd\n      ? element.endTimeMs >= timelineTimeMs\n      : element.endTimeMs > timelineTimeMs);\n\n  return { progress, isVisible, timelineTimeMs };\n};\n\n/**\n * Evaluates element visibility specifically for animation coordination\n * Uses inclusive end boundaries to prevent animation jumps at exact boundaries\n */\nexport const evaluateTemporalStateForAnimation = (\n  element: AnimatableElement,\n): TemporalState => {\n  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup\n  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;\n\n  const progress =\n    element.durationMs <= 0\n      ? 1\n      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));\n\n  // For animation coordination, use inclusive end for ALL elements to prevent visual jumps\n  const isVisible =\n    element.startTimeMs <= timelineTimeMs &&\n    element.endTimeMs >= timelineTimeMs;\n\n  return { progress, isVisible, timelineTimeMs };\n};\n\n/**\n * Updates the visual state (CSS + display) to match temporal state\n */\nconst updateVisualState = (\n  element: AnimatableElement,\n  state: TemporalState,\n): void => {\n  // Always set progress (needed for many use cases)\n  element.style.setProperty(PROGRESS_PROPERTY, `${state.progress * 100}%`);\n\n  // Handle visibility\n  if (!state.isVisible) {\n    if (element.style.display !== \"none\") {\n      element.style.display = \"none\";\n    }\n    return;\n  }\n\n  if (element.style.display === \"none\") {\n    element.style.display = \"\";\n  }\n\n  // Set other CSS properties for visible elements only\n  element.style.setProperty(DURATION_PROPERTY, `${element.durationMs}ms`);\n  element.style.setProperty(\n    TRANSITION_DURATION_PROPERTY,\n    `${element.parentTimegroup?.overlapMs ?? 0}ms`,\n  );\n  element.style.setProperty(\n    TRANSITION_OUT_START_PROPERTY,\n    `${element.durationMs - (element.parentTimegroup?.overlapMs ?? 0)}ms`,\n  );\n};\n\n/**\n * Coordinates animations for a single element and its subtree, using the element as the time source\n */\nconst coordinateAnimationsForSingleElement = (\n  element: AnimatableElement,\n): void => {\n  const animations = element.getAnimations({ subtree: true });\n\n  for (const animation of animations) {\n    if (animation.playState === \"running\") {\n      animation.pause();\n    }\n\n    const effect = animation.effect;\n    if (!(effect && effect instanceof KeyframeEffect)) {\n      continue;\n    }\n\n    const target = effect.target;\n    if (!target) {\n      continue;\n    }\n\n    // For animations in this element's subtree, always use this element as the time source\n    // This handles both animations directly on the temporal element and on its non-temporal children\n    const timing = effect.getTiming();\n    const duration = Number(timing.duration) || 0;\n    const delay = Number(timing.delay) || 0;\n    const iterations =\n      Number(timing.iterations) || DEFAULT_ANIMATION_ITERATIONS;\n\n    if (duration <= 0) {\n      animation.currentTime = 0;\n      continue;\n    }\n\n    // Use the element itself as the time source (it's guaranteed to be temporal)\n    const currentTime = element.ownCurrentTimeMs ?? 0;\n\n    if (currentTime < delay) {\n      animation.currentTime = 0;\n      continue;\n    }\n\n    const adjustedTime = currentTime - delay;\n    const currentIteration = Math.floor(adjustedTime / duration);\n    let currentIterationTime = adjustedTime % duration;\n\n    // Handle animation-direction\n    const direction = timing.direction || \"normal\";\n    const shouldReverse =\n      direction === \"reverse\" ||\n      (direction === \"alternate\" && currentIteration % 2 === 1) ||\n      (direction === \"alternate-reverse\" && currentIteration % 2 === 0);\n\n    if (shouldReverse) {\n      currentIterationTime = duration - currentIterationTime;\n    }\n\n    // Calculate the total animation timeline length (delay + duration * iterations)\n    const totalAnimationLength = delay + duration * iterations;\n\n    // CRITICAL: Always keep currentTime below totalAnimationLength to prevent completion\n    const maxSafeCurrentTime =\n      totalAnimationLength - ANIMATION_PRECISION_OFFSET;\n\n    if (currentIteration >= iterations) {\n      // Animation would be complete - clamp to just before completion\n      animation.currentTime = maxSafeCurrentTime;\n    } else {\n      // Animation in progress - clamp to safe value within current iteration\n      const proposedCurrentTime =\n        Math.min(currentIterationTime, duration - ANIMATION_PRECISION_OFFSET) +\n        delay;\n      animation.currentTime = Math.min(proposedCurrentTime, maxSafeCurrentTime);\n    }\n  }\n};\n\n/**\n * Main function: synchronizes DOM element with timeline\n */\nexport const updateAnimations = (element: AnimatableElement): void => {\n  const temporalState = evaluateTemporalState(element);\n  deepGetTemporalElements(element).forEach((temporalElement) => {\n    const temporalState = evaluateTemporalState(temporalElement);\n    updateVisualState(temporalElement, temporalState);\n  });\n  updateVisualState(element, temporalState);\n\n  // Coordinate animations - use animation-specific visibility to prevent jumps at exact boundaries\n  const animationState = evaluateTemporalStateForAnimation(element);\n  if (animationState.isVisible) {\n    coordinateAnimationsForSingleElement(element);\n  }\n\n  // Coordinate animations for child elements using animation-specific visibility\n  deepGetTemporalElements(element).forEach((temporalElement) => {\n    const childAnimationState =\n      evaluateTemporalStateForAnimation(temporalElement);\n    if (childAnimationState.isVisible) {\n      coordinateAnimationsForSingleElement(temporalElement);\n    }\n  });\n};\n"],"mappings":"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"}

package/dist/gui/EFConfiguration.d.ts

@@ -1,15 +1,15 @@
-import * as lit11 from "lit";
+import * as lit9 from "lit";
 import { LitElement } from "lit";
-import * as lit_html11 from "lit-html";
+import * as lit_html9 from "lit-html";
 
 //#region src/gui/EFConfiguration.d.ts
 declare class EFConfiguration extends LitElement {
-  static styles: lit11.CSSResult[];
+  static styles: lit9.CSSResult[];
   efConfiguration: this;
   apiHost?: string;
   signingURL: string;
   mediaEngine?: "cloud" | "local";
-  render(): lit_html11.TemplateResult<1>;
+  render(): lit_html9.TemplateResult<1>;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/dist/gui/EFControls.d.ts

@@ -1,7 +1,7 @@
 import { TemporalMixinInterface } from "../elements/EFTemporal.js";
 import { ControllableInterface } from "./Controllable.js";
 import { FocusContext } from "./focusContext.js";
-import * as lit14 from "lit";
+import * as lit21 from "lit";
 import { LitElement, PropertyValueMap } from "lit";
 
 //#region src/gui/EFControls.d.ts
@@ -26,7 +26,7 @@ import { LitElement, PropertyValueMap } from "lit";
  */
 declare class EFControls extends LitElement {
   #private;
-  static styles: lit14.CSSResult;
+  static styles: lit21.CSSResult;
   createRenderRoot(): this;
   /**
    * The ID of the ef-preview element to control

package/dist/gui/EFDial.d.ts

@@ -1,6 +1,6 @@
-import * as lit25 from "lit";
+import * as lit20 from "lit";
 import { LitElement } from "lit";
-import * as lit_html22 from "lit-html";
+import * as lit_html18 from "lit-html";
 
 //#region src/gui/EFDial.d.ts
 interface DialChangeDetail {
@@ -13,12 +13,12 @@ declare class EFDial extends LitElement {
   private isDragging;
   private dragStartAngle;
   private dragStartValue;
-  static styles: lit25.CSSResult;
+  static styles: lit20.CSSResult;
   private getAngleFromPoint;
   private handlePointerDown;
   private handlePointerMove;
   private handlePointerUp;
-  render(): lit_html22.TemplateResult<1>;
+  render(): lit_html18.TemplateResult<1>;
 }
 //#endregion
 export { DialChangeDetail, EFDial };

package/dist/gui/EFFocusOverlay.d.ts

@@ -1,16 +1,16 @@
-import * as lit15 from "lit";
+import * as lit22 from "lit";
 import { LitElement } from "lit";
-import * as lit_html12 from "lit-html";
+import * as lit_html19 from "lit-html";
 import * as lit_html_directives_ref_js3 from "lit-html/directives/ref.js";
 
 //#region src/gui/EFFocusOverlay.d.ts
 declare class EFFocusOverlay extends LitElement {
-  static styles: lit15.CSSResult;
+  static styles: lit22.CSSResult;
   focusedElement?: HTMLElement | null;
   overlay: lit_html_directives_ref_js3.Ref<HTMLDivElement>;
   private animationFrame?;
   drawOverlay: () => void;
-  render(): lit_html12.TemplateResult<1>;
+  render(): lit_html19.TemplateResult<1>;
   connectedCallback(): void;
   disconnectedCallback(): void;
   protected updated(): void;

package/dist/gui/EFPause.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit19 from "lit";
+import * as lit16 from "lit";
 import { LitElement } from "lit";
-import * as lit_html16 from "lit-html";
+import * as lit_html14 from "lit-html";
 
 //#region src/gui/EFPause.d.ts
 declare const EFPause_base: (new (...args: any[]) => {
@@ -10,13 +10,13 @@ declare const EFPause_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFPause extends EFPause_base {
-  static styles: lit19.CSSResult[];
+  static styles: lit16.CSSResult[];
   playing: boolean;
   get efContext(): ControllableInterface | null;
   connectedCallback(): void;
   disconnectedCallback(): void;
   updated(changedProperties: Map<string | number | symbol, unknown>): void;
-  render(): lit_html16.TemplateResult<1>;
+  render(): lit_html14.TemplateResult<1>;
   handleClick: () => void;
 }
 declare global {

package/dist/gui/EFPlay.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit18 from "lit";
+import * as lit15 from "lit";
 import { LitElement } from "lit";
-import * as lit_html15 from "lit-html";
+import * as lit_html13 from "lit-html";
 
 //#region src/gui/EFPlay.d.ts
 declare const EFPlay_base: (new (...args: any[]) => {
@@ -10,13 +10,13 @@ declare const EFPlay_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFPlay extends EFPlay_base {
-  static styles: lit18.CSSResult[];
+  static styles: lit15.CSSResult[];
   playing: boolean;
   get efContext(): ControllableInterface | null;
   connectedCallback(): void;
   disconnectedCallback(): void;
   updated(changedProperties: Map<string | number | symbol, unknown>): void;
-  render(): lit_html15.TemplateResult<1>;
+  render(): lit_html13.TemplateResult<1>;
   handleClick: () => void;
 }
 declare global {

package/dist/gui/EFPreview.d.ts

@@ -1,19 +1,19 @@
 import { ContextMixinInterface } from "./ContextMixin.js";
-import * as lit10 from "lit";
+import * as lit11 from "lit";
 import { LitElement } from "lit";
-import * as lit_html10 from "lit-html";
+import * as lit_html11 from "lit-html";
 
 //#region src/gui/EFPreview.d.ts
 declare const EFPreview_base: (new (...args: any[]) => ContextMixinInterface) & typeof LitElement;
 declare class EFPreview extends EFPreview_base {
-  static styles: lit10.CSSResult[];
+  static styles: lit11.CSSResult[];
   focusedElement?: HTMLElement;
   /**
    * Find the closest temporal element (timegroup, video, audio, etc.)
    */
   private findClosestTemporal;
   constructor();
-  render(): lit_html10.TemplateResult<1>;
+  render(): lit_html11.TemplateResult<1>;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/dist/gui/EFResizableBox.d.ts

@@ -1,6 +1,6 @@
-import * as lit17 from "lit";
+import * as lit23 from "lit";
 import { LitElement } from "lit";
-import * as lit_html14 from "lit-html";
+import * as lit_html20 from "lit-html";
 
 //#region src/gui/EFResizableBox.d.ts
 interface BoxBounds {
@@ -18,7 +18,7 @@ declare class EFResizableBox extends LitElement {
   private dragMode;
   private interaction;
   private modifiers;
-  static styles: lit17.CSSResult;
+  static styles: lit23.CSSResult;
   private resizeObserver?;
   connectedCallback(): void;
   private handlePointerDown;
@@ -33,7 +33,7 @@ declare class EFResizableBox extends LitElement {
   private simpleConstrainBounds;
   private constrainResizeDeltas;
   private dispatchBoundsChange;
-  render(): lit_html14.TemplateResult<1>;
+  render(): lit_html20.TemplateResult<1>;
   private renderHandles;
 }
 //#endregion

package/dist/gui/EFScrubber.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit23 from "lit";
+import * as lit18 from "lit";
 import { LitElement } from "lit";
-import * as lit_html20 from "lit-html";
+import * as lit_html16 from "lit-html";
 
 //#region src/gui/EFScrubber.d.ts
 declare const EFScrubber_base: (new (...args: any[]) => {
@@ -10,7 +10,7 @@ declare const EFScrubber_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFScrubber extends EFScrubber_base {
-  static styles: lit23.CSSResult[];
+  static styles: lit18.CSSResult[];
   playing: boolean;
   currentTimeMs: number;
   durationMs: number;
@@ -22,7 +22,7 @@ declare class EFScrubber extends EFScrubber_base {
   private boundHandlePointerDown;
   private boundHandlePointerMove;
   private boundHandlePointerUp;
-  render(): lit_html20.TemplateResult<1>;
+  render(): lit_html16.TemplateResult<1>;
   connectedCallback(): void;
   disconnectedCallback(): void;
 }

package/dist/gui/EFTimeDisplay.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit24 from "lit";
+import * as lit19 from "lit";
 import { LitElement } from "lit";
-import * as lit_html21 from "lit-html";
+import * as lit_html17 from "lit-html";
 
 //#region src/gui/EFTimeDisplay.d.ts
 declare const EFTimeDisplay_base: (new (...args: any[]) => {
@@ -10,11 +10,11 @@ declare const EFTimeDisplay_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFTimeDisplay extends EFTimeDisplay_base {
-  static styles: lit24.CSSResult;
+  static styles: lit19.CSSResult;
   currentTimeMs: number;
   durationMs: number;
   private formatTime;
-  render(): lit_html21.TemplateResult<1>;
+  render(): lit_html17.TemplateResult<1>;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/dist/gui/EFToggleLoop.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit21 from "lit";
+import * as lit17 from "lit";
 import { LitElement } from "lit";
-import * as lit_html18 from "lit-html";
+import * as lit_html15 from "lit-html";
 
 //#region src/gui/EFToggleLoop.d.ts
 declare const EFToggleLoop_base: (new (...args: any[]) => {
@@ -10,9 +10,9 @@ declare const EFToggleLoop_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFToggleLoop extends EFToggleLoop_base {
-  static styles: lit21.CSSResult[];
+  static styles: lit17.CSSResult[];
   get context(): ControllableInterface | null;
-  render(): lit_html18.TemplateResult<1>;
+  render(): lit_html15.TemplateResult<1>;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/dist/gui/EFTogglePlay.d.ts

@@ -1,7 +1,7 @@
 import { ControllableInterface } from "./Controllable.js";
-import * as lit16 from "lit";
+import * as lit14 from "lit";
 import { LitElement } from "lit";
-import * as lit_html13 from "lit-html";
+import * as lit_html12 from "lit-html";
 
 //#region src/gui/EFTogglePlay.d.ts
 declare const EFTogglePlay_base: (new (...args: any[]) => {
@@ -10,12 +10,12 @@ declare const EFTogglePlay_base: (new (...args: any[]) => {
   effectiveContext: ControllableInterface | null;
 }) & typeof LitElement;
 declare class EFTogglePlay extends EFTogglePlay_base {
-  static styles: lit16.CSSResult[];
+  static styles: lit14.CSSResult[];
   playing: boolean;
   get efContext(): ControllableInterface | null;
   connectedCallback(): void;
   disconnectedCallback(): void;
-  render(): lit_html13.TemplateResult<1>;
+  render(): lit_html12.TemplateResult<1>;
   togglePlay: () => void;
 }
 declare global {

package/dist/gui/EFWorkbench.d.ts

@@ -1,21 +1,21 @@
 import { ContextMixinInterface } from "./ContextMixin.js";
-import * as lit0 from "lit";
+import * as lit10 from "lit";
 import { LitElement, PropertyValueMap } from "lit";
-import * as lit_html0 from "lit-html";
-import * as lit_html_directives_ref_js0 from "lit-html/directives/ref.js";
+import * as lit_html10 from "lit-html";
+import * as lit_html_directives_ref_js2 from "lit-html/directives/ref.js";
 
 //#region src/gui/EFWorkbench.d.ts
 declare const EFWorkbench_base: (new (...args: any[]) => ContextMixinInterface) & typeof LitElement;
 declare class EFWorkbench extends EFWorkbench_base {
-  static styles: lit0.CSSResult[];
+  static styles: lit10.CSSResult[];
   rendering: boolean;
-  focusOverlay: lit_html_directives_ref_js0.Ref<HTMLDivElement>;
+  focusOverlay: lit_html_directives_ref_js2.Ref<HTMLDivElement>;
   handleStageWheel(event: WheelEvent): void;
   connectedCallback(): void;
   disconnectedCallback(): void;
   update(changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
   drawOverlays: () => void;
-  render(): lit_html0.TemplateResult<1>;
+  render(): lit_html10.TemplateResult<1>;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/dist/style.css

@@ -827,6 +827,10 @@ video {
   --tw-blur: blur(8px);
   filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
 }
+.invert {
+  --tw-invert: invert(100%);
+  filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
+}
 .filter {
   filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
 }
@@ -838,6 +842,12 @@ video {
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
   transition-duration: 150ms;
 }
+.ease-in {
+  transition-timing-function: cubic-bezier(0.4, 0, 1, 1);
+}
+.ease-in-out {
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
 .ease-out {
   transition-timing-function: cubic-bezier(0, 0, 0.2, 1);
 }

package/dist/transcoding/types/index.d.ts

@@ -74,6 +74,7 @@ interface MediaEngine {
     audioBufferDurationMs: number;
     maxVideoBufferFetches: number;
     maxAudioBufferFetches: number;
+    bufferThresholdMs: number;
   };
   /**
    * Extract thumbnail canvases at multiple timestamps efficiently

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@editframe/elements",
-  "version": "0.25.1-beta.0",
+  "version": "0.26.1-beta.0",
   "description": "",
   "type": "module",
   "scripts": {
@@ -13,7 +13,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@bramus/style-observer": "^1.3.0",
-    "@editframe/assets": "0.25.1-beta.0",
+    "@editframe/assets": "0.26.1-beta.0",
     "@lit/context": "^1.1.6",
     "@lit/task": "^1.0.3",
     "@opentelemetry/api": "^1.9.0",

package/src/elements/EFMedia/AssetMediaEngine.ts

@@ -346,6 +346,7 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
       audioBufferDurationMs: 2000,
       maxVideoBufferFetches: 1,
       maxAudioBufferFetches: 1,
+      bufferThresholdMs: 30000, // Timeline-aware buffering threshold
     };
   }
 

package/src/elements/EFMedia/BaseMediaEngine.ts

@@ -482,4 +482,24 @@ export abstract class BaseMediaEngine {
     segmentId: number,
     rendition: VideoRendition,
   ): number[];
+
+  /**
+   * Get buffer configuration for this media engine
+   * Can be overridden by subclasses to provide custom buffer settings
+   */
+  getBufferConfig(): {
+    videoBufferDurationMs: number;
+    audioBufferDurationMs: number;
+    maxVideoBufferFetches: number;
+    maxAudioBufferFetches: number;
+    bufferThresholdMs: number;
+  } {
+    return {
+      videoBufferDurationMs: 10000, // 10 seconds
+      audioBufferDurationMs: 10000, // 10 seconds
+      maxVideoBufferFetches: 3,
+      maxAudioBufferFetches: 3,
+      bufferThresholdMs: 30000, // 30 seconds - timeline-aware buffering threshold
+    };
+  }
 }

package/src/elements/EFMedia/JitMediaEngine.browsertest.ts

@@ -155,4 +155,72 @@ describe("JitMediaEngine", () => {
         "http://localhost:63315/api/v1/transcode/{rendition}/{segmentId}.m4s?url=http%3A%2F%2Fweb%3A3000%2Fhead-moov-480p.mp4",
     });
   });
+
+  test("calculatePlayheadDistance utility function", async ({ expect }) => {
+    const { calculatePlayheadDistance } = await import(
+      "./shared/BufferUtils.js"
+    );
+
+    // Element is currently active (playhead within element bounds)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 0, endTimeMs: 2000 },
+        1000, // playhead at 1s
+      ),
+    ).toBe(0);
+
+    // Element hasn't started yet (playhead before element)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        0, // playhead at 0s
+      ),
+    ).toBe(2000);
+
+    // Element already finished (playhead after element)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 0, endTimeMs: 2000 },
+        5000, // playhead at 5s
+      ),
+    ).toBe(3000);
+
+    // Playhead at element start boundary
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        2000, // playhead exactly at start
+      ),
+    ).toBe(0);
+
+    // Playhead at element end boundary
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        4000, // playhead exactly at end
+      ),
+    ).toBe(0);
+  });
+
+  test("buffer config includes timeline threshold", async ({ expect }) => {
+    const configuration = document.createElement("ef-configuration");
+    const apiHost = `${window.location.protocol}//${window.location.host}`;
+    configuration.setAttribute("api-host", apiHost);
+    configuration.apiHost = apiHost;
+    configuration.signingURL = "";
+
+    const video = document.createElement("ef-video");
+    video.src = "http://web:3000/head-moov-480p.mp4";
+    configuration.appendChild(video);
+    document.body.appendChild(configuration);
+
+    // Wait for media engine to initialize
+    const mediaEngine = await video.mediaEngineTask.taskComplete;
+
+    // Check that buffer config includes the threshold
+    const bufferConfig = mediaEngine.getBufferConfig();
+    expect(bufferConfig.bufferThresholdMs).toBe(30000);
+
+    configuration.remove();
+  });
 });

package/src/elements/EFMedia/JitMediaEngine.ts

@@ -206,6 +206,7 @@ export class JitMediaEngine extends BaseMediaEngine implements MediaEngine {
       audioBufferDurationMs: 8000,
       maxVideoBufferFetches: 3,
       maxAudioBufferFetches: 3,
+      bufferThresholdMs: 30000, // Timeline-aware buffering threshold
     };
   }
 

package/src/elements/EFMedia/audioTasks/makeAudioBufferTask.ts

@@ -62,8 +62,19 @@ export const makeAudioBufferTask = (host: EFMedia): AudioBufferTask => {
         bufferDurationMs,
         maxParallelFetches,
         enableBuffering: host.enableAudioBuffering,
+        bufferThresholdMs: engineConfig.bufferThresholdMs,
       };
 
+      // Timeline context for priority-based buffering
+      const timelineContext =
+        host.rootTimegroup?.currentTimeMs !== undefined
+          ? {
+              elementStartMs: host.startTimeMs,
+              elementEndMs: host.endTimeMs,
+              playheadMs: host.rootTimegroup.currentTimeMs,
+            }
+          : undefined;
+
       return manageMediaBuffer<AudioRendition>(
         seekTimeMs,
         currentConfig,
@@ -99,6 +110,7 @@ export const makeAudioBufferTask = (host: EFMedia): AudioBufferTask => {
           },
           logError: console.error,
         },
+        timelineContext,
       );
     },
   });

package/src/elements/EFMedia/shared/BufferUtils.ts

@@ -21,6 +21,7 @@ export interface MediaBufferConfig {
   maxParallelFetches: number;
   enableBuffering: boolean;
   enableContinuousBuffering?: boolean;
+  bufferThresholdMs?: number; // Timeline-aware buffering threshold (default: 30000ms)
 }
 
 /**
@@ -189,6 +190,26 @@ export const getUnrequestedSegments = (
   return segmentIds.filter((id) => !bufferState.requestedSegments.has(id));
 };
 
+/**
+ * Calculate distance from element to playhead position
+ * Returns 0 if element is currently active, otherwise returns distance in milliseconds
+ */
+export const calculatePlayheadDistance = (
+  element: { startTimeMs: number; endTimeMs: number },
+  playheadMs: number,
+): number => {
+  // Element hasn't started yet
+  if (playheadMs < element.startTimeMs) {
+    return element.startTimeMs - playheadMs;
+  }
+  // Element already finished
+  if (playheadMs > element.endTimeMs) {
+    return playheadMs - element.endTimeMs;
+  }
+  // Element is currently active
+  return 0;
+};
+
 /**
  * Core media buffering orchestration logic - prefetch only, no data storage
  * Integrates with BaseMediaEngine's existing caching and request deduplication
@@ -202,11 +223,32 @@ export const manageMediaBuffer = async <
   durationMs: number,
   signal: AbortSignal,
   deps: MediaBufferDependencies<T>,
+  timelineContext?: {
+    elementStartMs: number;
+    elementEndMs: number;
+    playheadMs: number;
+  },
 ): Promise<MediaBufferState> => {
   if (!config.enableBuffering) {
     return currentState;
   }
 
+  // Timeline-aware buffering: skip if element is too far from playhead
+  if (timelineContext && config.bufferThresholdMs !== undefined) {
+    const distance = calculatePlayheadDistance(
+      {
+        startTimeMs: timelineContext.elementStartMs,
+        endTimeMs: timelineContext.elementEndMs,
+      },
+      timelineContext.playheadMs,
+    );
+
+    if (distance > config.bufferThresholdMs) {
+      // Element is too far from playhead, skip buffering
+      return currentState;
+    }
+  }
+
   const rendition = await deps.getRendition();
   if (!rendition) {
     // Cannot buffer without a rendition