Canvas Rendering Architecture

Image elements use a dual rendering strategy that automatically selects the optimal approach based on the image source type. This architecture provides seamless integration with Editframe's asset system while maintaining compatibility with standard web URLs.

The Problem

Using native <img> elements with a src attribute presents engineering challenges:

• Authenticated API endpoints require manual header management
• Local development servers need special routing configuration
• Cross-origin restrictions can prevent direct image loading
• Different source types require different handling approaches

Native image elements work well for public URLs but require additional infrastructure for authenticated endpoints or local development workflows.

Engineering Challenges

When using native <img> elements with different source types, developers typically need to:

• Manually construct API URLs for asset IDs
• Handle authentication headers separately
• Use separate components for different source types
• Write custom loading logic for each scenario

This creates inconsistent APIs, increases complexity, and makes it harder to switch between development and production workflows.

Architectural Solution

Editframe image elements automatically detect the source type and choose the appropriate rendering strategy:

Direct URLs (http/https): Rendered using a standard <img> element with the URL set directly. This provides native browser optimization, caching, and progressive loading for public images.

Asset IDs and Local Files: Rendered to a <canvas> element. The element handles authentication and routing automatically, providing pixel-perfect control over rendering and enabling future image processing capabilities.

The rendering strategy is transparent to developers — you use the same src or asset-id attributes regardless of the underlying implementation:

The same element works with direct URLs (rendered via <img>) or asset IDs (rendered via <canvas>) without code changes.

Concrete Benefits

Seamless Development/Production Workflow: Use src with local files during development, then switch to asset-id for production without changing your code structure. The element handles the rendering differences automatically.

Automatic Authentication: Asset IDs automatically use the correct API endpoints and authentication, eliminating manual URL construction or header management.

Future-Proof Architecture: Canvas rendering enables future capabilities like image filters, transformations, or compositing without requiring API changes.

Performance Optimization: Direct URLs use native browser image loading (progressive JPEG, WebP optimization), while canvas rendering provides precise control when needed.

Consistent API: One element handles all image source types with a unified attribute interface, reducing cognitive load and code complexity. Developers can switch between source types without learning different APIs or handling different edge cases.

---

Temporal Behavior

Image elements integrate seamlessly with Editframe's temporal composition system, providing flexible duration control that adapts to different composition needs. This architecture eliminates the need for manual duration calculations while supporting both flexible and fixed-duration use cases.

The Problem

In video composition, images need to display for specific durations. Using native image elements with explicit duration management presents engineering challenges:

• Manual duration calculations when images should fill their container
• Explicit duration setting for every image, even when you just want them to "fill available space"
• Separate logic for slideshows versus single-image displays
• Complex state management to track which images have explicit durations

Web-based solutions typically require JavaScript to calculate and update durations dynamically, making simple compositions verbose and error-prone.

Engineering Challenges

When managing image durations manually, developers face a choice between:

• Fixed durations everywhere: Verbose and inflexible — every image needs an explicit duration even when you want it to fill its parent
• Manual calculation: Complex JavaScript to compute durations based on parent containers, requiring updates when compositions change
• Separate components: Different image components for "fill parent" versus "fixed duration" use cases

These approaches create maintenance burden, increase complexity, and make it harder to create flexible compositions that adapt to different contexts.

Architectural Solution

Editframe image elements use a duration inheritance system that automatically adapts to composition context:

Default Behavior (Expanding Duration): When duration is not set or is empty, the image expands temporally to fill its parent timegroup's duration. This provides intuitive "fill available space" semantics without explicit configuration:

Explicit Duration: When duration is set to a timestring (e.g., "5s"), the image uses that exact duration regardless of its parent. This enables precise control for slideshows and timed displays:

Timegroup Integration

The timegroup's composition mode determines how child durations are calculated. Images participate in this system automatically:

Timegroup mode	Image behavior
fixed	Images expand to fill the fixed duration (unless they have their own duration)
contain	Images with fixed durations determine the timegroup's total duration
sequence	Images with fixed durations are arranged end-to-end sequentially
fit	Images expand to fill available space

This creates a declarative composition system where durations flow naturally through the hierarchy.

Concrete Benefits

Reduced Verbosity: Most images don't need explicit durations — they automatically fill their containers. This keeps compositions concise for the common case.

Intuitive Semantics: "Fill available space" is the default, matching developer expectations. Explicit durations are only needed when you want precise control.

Composition Flexibility: The same image element works in different contexts — as a single full-screen image, in a slideshow sequence, or as part of a complex nested composition — without code changes.

Automatic Adaptation: When parent timegroup durations change, images automatically adapt (unless they have explicit durations). This eliminates manual recalculation.

Declarative Composition: Duration relationships are declared in markup, not computed in JavaScript. This makes compositions easier to understand, maintain, and reason about.

Frame-Perfect Timing: The temporal system ensures images display for exactly the right duration, synchronized with the video timeline, without manual frame calculations.