visualfries 0.1.10115 → 0.3.2

package/dist/managers/RenderManager.js

@@ -2,32 +2,41 @@ import { StateManager } from './StateManager.svelte.js';
 import { EventManager } from './EventManager.js';
 import { AppManager } from './AppManager.svelte.js';
 import { LayersManager } from './LayersManager.svelte.js';
+import { shouldPrepareMediaAtTime } from '../utils/mediaWindow.js';
+import { isTimeWithinTimeline } from '../utils/timelineWindow.js';
 export class RenderManager {
     state;
     componentsManager;
     eventManager;
     appManager;
     layersManager;
-    // Track last visibility to ensure we run one more update to hide components that just became invisible
+    // Track last prepared/visible state so media hooks get one final update to release resources.
     lastActiveById = new Map();
     lastRenderTime = -1;
+    renderInFlight = null;
+    rerenderRequested = false;
+    boundHandleBeforeRender;
+    boundRender;
+    boundHandleChangeState;
     constructor(cradle) {
         this.state = cradle.stateManager;
         this.componentsManager = cradle.componentsManager;
         this.eventManager = cradle.eventManager;
         this.appManager = cradle.appManager;
         this.layersManager = cradle.layersManager;
+        this.boundHandleBeforeRender = this.handleBeforeRender.bind(this);
+        this.boundRender = this.render.bind(this);
+        this.boundHandleChangeState = (event) => {
+            if (event.detail.state !== 'playing')
+                void this.render();
+        };
         this.initializeEventListeners();
     }
     initializeEventListeners() {
-        this.eventManager.on('beforerender', this.handleBeforeRender.bind(this));
-        this.eventManager.on('timeupdate', this.render.bind(this));
-        this.eventManager.on('rerender', this.render.bind(this));
-        this.eventManager.on('changestate', (event) => {
-            if (event.detail.state !== 'playing') {
-                this.render();
-            }
-        });
+        this.eventManager.on('beforerender', this.boundHandleBeforeRender);
+        this.eventManager.on('timeupdate', this.boundRender);
+        this.eventManager.on('rerender', this.boundRender);
+        this.eventManager.on('changestate', this.boundHandleChangeState);
     }
     async handleBeforeRender() { }
     #syncLayerDisplayObjects() {
@@ -43,33 +52,70 @@ export class RenderManager {
         }
     }
     async render() {
+        if (this.renderInFlight) {
+            this.rerenderRequested = true;
+            return this.renderInFlight;
+        }
+        this.renderInFlight = this.#drainRenderQueue();
+        return this.renderInFlight;
+    }
+    async #drainRenderQueue() {
+        try {
+            do {
+                this.rerenderRequested = false;
+                await this.#renderOnce();
+            } while (this.rerenderRequested);
+        }
+        finally {
+            this.renderInFlight = null;
+        }
+    }
+    async #renderOnce() {
         const components = this.componentsManager.getAll();
         const currentTime = this.state.currentTime;
         const entries = components.map((component) => {
             const startAt = component.props.timeline.startAt ?? 0;
             const endAt = component.props.timeline.endAt ?? this.state.duration;
-            const isVisibleByTime = currentTime >= startAt && currentTime <= endAt;
+            const isVisibleByTime = isTimeWithinTimeline(currentTime, startAt, endAt);
             const isExplicitlyVisible = component.props.visible !== false;
-            const shouldBeVisible = (isVisibleByTime && isExplicitlyVisible) || component.type === 'VIDEO';
+            const shouldBeVisible = isVisibleByTime && isExplicitlyVisible;
+            const shouldPrepareMedia = component.type === 'VIDEO' || component.type === 'AUDIO'
+                ? shouldPrepareMediaAtTime({
+                    type: component.type,
+                    visible: component.props.visible,
+                    timeline: component.props.timeline,
+                    source: { url: component.props.sourceUrl }
+                }, currentTime)
+                : false;
             const wasVisible = this.lastActiveById.get(component.id) === true;
-            return { component, shouldBeVisible, wasVisible };
+            return { component, shouldBeVisible, shouldPrepareMedia, wasVisible };
         });
-        const toUpdate = entries
-            .filter((e) => e.shouldBeVisible || e.wasVisible)
-            .map((e) => e.component);
+        // Server output is correctness-first: every display hook reasserts timeline
+        // visibility on every frame. The optimized preview path can otherwise leave
+        // a stale outgoing image visible across a cut in a long frame-range render.
+        const toUpdate = this.state.environment === 'server'
+            ? components
+            : entries
+                // Every component needs one initial update so its display hook can hide it
+                // when the first rendered frame is outside its timeline.
+                .filter((e) => !this.lastActiveById.has(e.component.id) ||
+                e.shouldBeVisible ||
+                e.wasVisible ||
+                e.shouldPrepareMedia)
+                .map((e) => e.component);
         await Promise.all(toUpdate.map((component) => component.update()));
-        // Update visibility cache after updates
+        // Keep one extra tick after the warm window ends so media hooks can release pooled resources.
         for (const e of entries) {
-            this.lastActiveById.set(e.component.id, e.shouldBeVisible);
+            this.lastActiveById.set(e.component.id, e.shouldBeVisible || e.shouldPrepareMedia);
         }
         this.#syncLayerDisplayObjects();
         this.appManager.render();
         this.lastRenderTime = currentTime;
     }
     destroy() {
-        this.eventManager.removeEventListener('beforerender', this.handleBeforeRender);
-        this.eventManager.removeEventListener('timeupdate', this.render);
-        this.eventManager.removeEventListener('rerender', this.render);
-        this.eventManager.removeEventListener('changestate', this.render);
+        this.eventManager.removeEventListener('beforerender', this.boundHandleBeforeRender);
+        this.eventManager.removeEventListener('timeupdate', this.boundRender);
+        this.eventManager.removeEventListener('rerender', this.boundRender);
+        this.eventManager.removeEventListener('changestate', this.boundHandleChangeState);
     }
 }

package/dist/managers/StateManager.svelte.d.ts

@@ -22,6 +22,8 @@ export declare class StateManager implements IStateManager {
     private loop;
     private timeManager;
     private layersManager;
+    private disabledTimeZonesCache;
+    private disabledTimeZonesCacheKey;
     constructor(cradle: {
         sceneData: SceneData;
         environment: RenderEnvironment;
@@ -647,6 +649,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -1266,6 +1274,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -1859,6 +1873,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -2450,6 +2470,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -3075,6 +3101,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -3670,6 +3702,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -4216,6 +4254,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -4767,6 +4811,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;
@@ -5311,6 +5361,12 @@ export declare class StateManager implements IStateManager {
                             unit: "px" | "em" | "rem" | "%";
                         } | null | undefined;
                         textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" | undefined;
+                        padding?: number | {
+                            top: number;
+                            right: number;
+                            bottom: number;
+                            left: number;
+                        } | undefined;
                         shadow?: {
                             enabled?: boolean | undefined;
                             preset?: string | undefined;

package/dist/managers/StateManager.svelte.js

@@ -15,6 +15,8 @@ export class StateManager {
     loop = false;
     timeManager;
     layersManager;
+    disabledTimeZonesCache = [];
+    disabledTimeZonesCacheKey = '';
     constructor(cradle) {
         const sceneDataRune = $state(cradle.sceneData);
         this.currentSceneData = sceneDataRune;
@@ -35,14 +37,9 @@ export class StateManager {
         this.currentSceneData.settings.subtitles = subtitlesSettings;
     }
     get currentTime() {
-        if (this.currentTimeRune >= this.endTime) {
-            return this.endTime;
-        }
-        else if (this.currentTimeRune <= this.startTime) {
-            return this.startTime;
-        }
-        // Could cache fps if it doesn't change frequently
-        return this.timeManager.transformTime(this.currentTimeRune);
+        const clampedTime = Math.max(this.startTime, Math.min(this.currentTimeRune, this.endTime));
+        const frameTime = this.timeManager.getCurrentFrameTime(clampedTime, true);
+        return Math.min(frameTime, this.endTime);
     }
     get data() {
         return this.currentSceneData;
@@ -71,7 +68,7 @@ export class StateManager {
         return Math.min(this.data.settings.endAt || this.duration, this.duration);
     }
     setCurrentTime(time) {
-        const currentTime = this.timeManager.transformTime(Math.max(this.startTime, Math.min(time, this.endTime)));
+        const currentTime = Math.max(this.startTime, Math.min(time, this.endTime));
         this.currentTimeRune = currentTime;
         if (time >= this.endTime && this.isPlaying) {
             if (this.loop) {
@@ -101,63 +98,68 @@ export class StateManager {
         }
     }
     get currentFrame() {
-        return Math.round(this.currentTime * this.data.settings.fps);
+        const clampedTime = Math.max(this.startTime, Math.min(this.currentTimeRune, this.endTime));
+        return this.timeManager.getFrameIndex(clampedTime, 'current', true);
     }
     get disabledTimeZones() {
-        const start = $derived(this.data.settings.startAt);
-        const end = $derived(this.data.settings.endAt);
-        const excluded_timestamps = $derived(this.data.settings.trimZones);
-        const duration = $derived(this.data.settings.duration);
-        const zones = $derived.by(() => {
-            const output = [];
-            if (start && start > 0) {
-                output.push({
-                    start: 0,
-                    end: start
-                });
-            }
-            if (excluded_timestamps && excluded_timestamps.length) {
-                for (const disabledZone of excluded_timestamps) {
-                    const { start, end } = disabledZone;
-                    if (end < duration) {
-                        output.push({
-                            start,
-                            end
-                        });
-                    }
+        const start = this.data.settings.startAt;
+        const end = this.data.settings.endAt;
+        const excludedTimestamps = this.data.settings.trimZones ?? [];
+        const duration = this.data.settings.duration;
+        const cacheKey = [
+            start ?? '',
+            end ?? '',
+            duration,
+            excludedTimestamps.map((zone) => `${zone.start}:${zone.end}`).join('|')
+        ].join('::');
+        if (cacheKey === this.disabledTimeZonesCacheKey) {
+            return this.disabledTimeZonesCache;
+        }
+        const output = [];
+        if (start && start > 0) {
+            output.push({
+                start: 0,
+                end: start
+            });
+        }
+        if (excludedTimestamps.length) {
+            for (const disabledZone of excludedTimestamps) {
+                const { start, end } = disabledZone;
+                if (end < duration) {
+                    output.push({
+                        start,
+                        end
+                    });
                 }
             }
-            if (end && end < duration) {
-                output.push({
-                    start: end,
-                    end: duration
-                });
+        }
+        if (end && end < duration) {
+            output.push({
+                start: end,
+                end: duration
+            });
+        }
+        output.sort((a, b) => a.start - b.start);
+        const mergedZones = [];
+        let currentZone = null;
+        for (const zone of output) {
+            if (!currentZone) {
+                currentZone = { ...zone };
             }
-            // Sort zones by start time
-            output.sort((a, b) => a.start - b.start);
-            // Merge overlapping zones
-            const mergedZones = [];
-            let currentZone = null;
-            for (const zone of output) {
-                if (!currentZone) {
-                    currentZone = { ...zone };
-                }
-                else if (zone.start <= currentZone.end) {
-                    // Zones overlap, extend the current zone
-                    currentZone.end = Math.max(currentZone.end, zone.end);
-                }
-                else {
-                    // No overlap, push current zone and start a new one
-                    mergedZones.push(currentZone);
-                    currentZone = { ...zone };
-                }
+            else if (zone.start <= currentZone.end) {
+                currentZone.end = Math.max(currentZone.end, zone.end);
             }
-            if (currentZone) {
+            else {
                 mergedZones.push(currentZone);
+                currentZone = { ...zone };
             }
-            return mergedZones;
-        });
-        return zones;
+        }
+        if (currentZone) {
+            mergedZones.push(currentZone);
+        }
+        this.disabledTimeZonesCacheKey = cacheKey;
+        this.disabledTimeZonesCache = mergedZones;
+        return this.disabledTimeZonesCache;
     }
     changeState(updateState) {
         let newState = this.determineNewState(updateState);

package/dist/managers/SubtitlesManager.svelte.js

@@ -208,9 +208,7 @@ function buildSubtitlesManager(timeManager, eventManager, sceneData, subtitles)
             for (const [lang, langIndex] of Object.entries(assetIndex)) {
                 for (const [subtitleId, subtitle] of Object.entries(langIndex)) {
                     const text = subtitle.text;
-                    // Use Array.from to properly handle multi-codepoint characters (emojis, etc.)
-                    // This prevents splitting emojis into unpaired surrogates that cause encodeURIComponent to fail
-                    const characters = Array.from(text);
+                    const characters = text.split('');
                     if (characters && characters.length > 0) {
                         for (const char of characters) {
                             if (!charactersList.includes(char)) {

package/dist/managers/TimeManager.svelte.d.ts

@@ -1,6 +1,10 @@
 export declare class TimeManager {
     fps: number;
     duration: number;
+    private static readonly FRAME_EPSILON;
+    getFrameIndex(time: number, mode?: 'nearest' | 'current', skipDurationCheck?: boolean): number;
+    getTimeForFrame(frame: number, skipDurationCheck?: boolean): number;
     transformTime(time: number, skipDurationCheck?: boolean): number;
+    getCurrentFrameTime(time: number, skipDurationCheck?: boolean): number;
     updateTimeConfig(newFps: number, newDuration: number): void;
 }

package/dist/managers/TimeManager.svelte.js

@@ -1,15 +1,31 @@
 export class TimeManager {
     fps = $state(30); // Default
     duration = $state(0);
-    transformTime(time, skipDurationCheck = false) {
-        // Round to nearest frame boundary (1/fps seconds)
-        let frameAdjustedTime = Math.round(time * this.fps) / this.fps;
-        frameAdjustedTime = Math.max(frameAdjustedTime, 0);
+    static FRAME_EPSILON = 1e-4;
+    getFrameIndex(time, mode = 'nearest', skipDurationCheck = false) {
+        let adjustedTime = Math.max(time, 0);
+        if (!skipDurationCheck) {
+            adjustedTime = Math.min(adjustedTime, this.duration);
+        }
+        const scaledTime = adjustedTime * this.fps;
+        if (mode === 'current') {
+            return Math.max(0, Math.floor(scaledTime + TimeManager.FRAME_EPSILON));
+        }
+        return Math.max(0, Math.round(scaledTime));
+    }
+    getTimeForFrame(frame, skipDurationCheck = false) {
+        const frameTime = Math.max(0, frame) / this.fps;
         if (!skipDurationCheck) {
-            // Keep duration check since endTime is always <= duration
-            return frameAdjustedTime > this.duration ? this.duration : frameAdjustedTime;
+            return frameTime > this.duration ? this.duration : frameTime;
         }
-        return frameAdjustedTime;
+        return frameTime;
+    }
+    transformTime(time, skipDurationCheck = false) {
+        const frame = this.getFrameIndex(time, 'current', skipDurationCheck);
+        return this.getTimeForFrame(frame, skipDurationCheck);
+    }
+    getCurrentFrameTime(time, skipDurationCheck = false) {
+        return this.transformTime(time, skipDurationCheck);
     }
     updateTimeConfig(newFps, newDuration) {
         this.fps = newFps;

package/dist/schemas/runtime/deterministic.d.ts

@@ -63,6 +63,9 @@ export type DeterministicDiagnosticsReport = {
     providerMisses: number;
     cacheHits: number;
     cacheHitRatio: number;
+    selectedRendererType: 'canvas' | 'webgl';
+    rendererFallbackOccurred: boolean;
+    rendererFallbackReason?: string;
     readyAttempts: number;
     extraRenderPasses: number;
     blurRedraws: number;

package/dist/schemas/runtime/deterministic.js

@@ -8,7 +8,11 @@ export const DeterministicMediaConfigShape = z.object({
     loadingMaxAttempts: z.number().int().positive().prefault(2),
     readyYieldMs: z.number().int().nonnegative().prefault(0),
     blurDownscale: z.number().positive().max(1).prefault(0.33),
-    provider: z.custom().optional()
+    provider: z
+        .custom((value) => typeof value === 'object' &&
+        value !== null &&
+        typeof value.getFrame === 'function', 'provider must implement getFrame(request)')
+        .optional()
 }).prefault({});
 export const defaultDeterministicMediaConfig = DeterministicMediaConfigShape.parse(undefined);
 export class DeterministicRenderError extends Error {

package/dist/schemas/runtime/types.d.ts

@@ -4,6 +4,7 @@ import type { ComponentsManager } from '../../managers/ComponentsManager.svelte.
 import type { LayersManager } from '../../managers/LayersManager.svelte.js';
 import type { SubtitlesManager } from '../../managers/SubtitlesManager.svelte.js';
 import type { EventManager } from '../../managers/EventManager.js';
+import type { PixiAnimationTarget } from '../../animations/PixiAnimationTarget.js';
 import type { Component as SceneLayerComponent, ComponentBase, AppearanceInput, Scene, RenderEnvironment, ComponentInput, SceneLayerInput, SceneLayer, VideoComponentShape, ImageComponentShape, GifComponentShape, Subtitle } from '../..';
 import type { DeterministicMediaConfig, DeterministicFrameProvider, DeterministicDiagnosticsReport, FrameImageEncodingOptions, RenderFrameRangeOptions, RenderFrameRangeSummary } from './deterministic.js';
 declare const SCENE_LAYER_COMPONENT_TYPE: readonly ["IMAGE", "GIF", "VIDEO", "TEXT", "SHAPE", "AUDIO", "COLOR", "GRADIENT", "SUBTITLES"];
@@ -88,7 +89,7 @@ export interface ResourceManager<T, D, F> {
     get(id: string): T | undefined;
     getAll(): T[];
     update(id: string, data: Partial<F>, refreshType?: ComponentRefreshType): void;
-    delete(id: string): void;
+    delete(id: string): void | Promise<void>;
     create(data: D): Promise<T | null>;
     setOrder(id: string, newOrder: number): void;
     moveUp(id: string): void;
@@ -99,7 +100,7 @@ export interface ResourceManager<T, D, F> {
         id: string;
         data: Partial<F>;
     }>): void;
-    bulkDelete(ids: string[]): void;
+    bulkDelete(ids: string[]): void | Promise<void>;
     hide(id: string): void;
     show(id: string): void;
     toggle(id: string): void;
@@ -109,14 +110,16 @@ export type ComponentData = SceneLayerComponent;
 export type ComponentProps = ComponentBase & {
     checksum: string;
     duration: number;
+    sourceUrl?: string | undefined;
+    sourceStartAt?: number | undefined;
     setStart(start: number): void;
     setEnd(end: number): void;
     getData(): ComponentData;
     update(data: Partial<AppearanceInput>): void;
-    updateText(text: string): Promise<void>;
-    updateAppearance(appearance: Partial<AppearanceInput>): Promise<void>;
-    setVisible(visible: boolean): Promise<void>;
-    setOrder(order: number): Promise<void>;
+    updateText(text: string): void;
+    updateAppearance(appearance: Partial<AppearanceInput>): void;
+    setVisible(visible: boolean): void;
+    setOrder(order: number): void;
 };
 export interface PixiComponent {
     displayObject: Container;
@@ -131,6 +134,7 @@ export interface ComponentBuilder {
     withHtmlText(): ComponentBuilder;
     withHtmlAnimation(): ComponentBuilder;
     withAnimation(): ComponentBuilder;
+    withPixiAnimationTarget(): ComponentBuilder;
     withSubtitles(): ComponentBuilder;
     withDisplayObject(): ComponentBuilder;
     withTexture(): ComponentBuilder;
@@ -139,6 +143,7 @@ export interface ComponentBuilder {
     withGif(): ComponentBuilder;
     withShape(): ComponentBuilder;
     withCanvasShape(): ComponentBuilder;
+    withCanvasFill(): ComponentBuilder;
     withProgressShape(): ComponentBuilder;
     withHtmlToCanvasHook(): ComponentBuilder;
 }
@@ -155,14 +160,14 @@ export interface Component {
     setup(): void;
     update(): void;
     refresh(type?: ComponentRefreshType): void;
-    destroy(): void;
+    destroy(): Promise<void>;
     setStart(start: number): Component;
     setEnd(end: number): Component;
-    updateAppearance(appearance: Partial<AppearanceInput>): Promise<Component>;
-    updateText(text: string): Promise<Component>;
-    setText(text: string): Promise<Component>;
-    setVisible(visible: boolean): Promise<Component>;
-    setOrder(order: number): Promise<Component>;
+    updateAppearance(appearance: Partial<AppearanceInput>): Component;
+    updateText(text: string): Component;
+    setText(text: string): Component;
+    setVisible(visible: boolean): Component;
+    setOrder(order: number): Component;
     onChange(callback: (changes: ComponentData) => void): () => void;
     onTimelineChange(callback: (time: number) => void): () => void;
 }
@@ -193,7 +198,7 @@ export interface ResourceTypes {
     pixiContainer: Container | undefined;
     wrapperHtmlEl: HTMLElement | undefined;
     htmlEl: HTMLElement | undefined;
-    animationTarget: HTMLElement | Container | undefined;
+    animationTarget: HTMLElement | Container | PixiAnimationTarget | undefined;
     animationData: Record<string, any> | undefined;
     pixiRenderObject: Container | undefined;
     htmlRenderObject: HTMLDivElement | undefined;
@@ -228,6 +233,21 @@ type Zone = {
     start: number;
     end: number;
 };
+export type ComponentAnimationExplanation = {
+    componentId: string;
+    type: ComponentData['type'];
+    time: number;
+    active: boolean;
+    relativeTime: number;
+    targetKind: 'html' | 'pixi' | 'none';
+    targetOwner: 'wrapper' | 'element' | 'pixi' | 'none';
+    computed: Record<string, number | string>;
+    animations: Array<{
+        id: string;
+        enabled: boolean;
+        startAt: number;
+    }>;
+};
 export interface SceneBuilder {
     readonly sceneData: Scene;
     readonly environment: RenderEnvironment;
@@ -245,7 +265,7 @@ export interface SceneBuilder {
     readonly components: ComponentsManager;
     readonly subtitles: SubtitlesManager;
     readonly htmlContainer: HTMLElement;
-    readonly canvasContainer: HTMLElement;
+    readonly canvasContainer: HTMLCanvasElement;
     readonly disabledTimeZones: Zone[];
     syncChanges: () => void;
     addExcludedTimestamp(start: number, end: number): void;
@@ -259,6 +279,7 @@ export interface SceneBuilder {
     markDirty(): void;
     initialize(): Promise<void>;
     seek(time: number): Promise<void>;
+    explainComponentState(componentId: string): ComponentAnimationExplanation | null;
     replaceSourceOnTime(time: number, componentId: string, base64data: string): Promise<void>;
     setDeterministicFrameProvider(provider: DeterministicFrameProvider | null): void;
     getDeterministicFrameProvider(): DeterministicFrameProvider | null;
@@ -276,7 +297,7 @@ export interface SceneBuilder {
     removeLoadingComponent(componentId: string): void;
     buildCharactersList(): void;
     render(): void;
-    destroy(): void;
+    destroy(): Promise<void>;
     addComponent(componentData: ComponentInput): Promise<ComponentData | undefined>;
     addLayer(layerInput: SceneLayerInput): Promise<Layer | undefined>;
     addNewLayerWithComponents(components: ComponentInput[]): Promise<Layer | undefined>;