visualfries 0.1.1097 → 0.1.1099

package/dist/DIContainer.js

@@ -41,10 +41,12 @@ import { Layer } from './layers/Layer.svelte.js';
 import { LayersManager } from './managers/LayersManager.svelte.js';
 import { MediaSeekingHook } from './components/hooks/MediaSeekingHook.js';
 import { VerifyGifHook } from './components/hooks/VerifyGifHook.js';
+import { DeterministicMediaFrameHook } from './components/hooks/DeterministicMediaFrameHook.js';
 import { ComponentAnimationTransformer } from './animations/transformers/AnimationReferenceTransformer.js';
 import { AnimationPresetsRegister } from './animations/AnimationPresetsRegister.js';
 import { SplitTextCache } from './animations/SplitTextCache.js';
 import { TimeManager } from './managers/TimeManager.svelte.js';
+import { DeterministicMediaManager } from './managers/DeterministicMediaManager.js';
 const containers = new Map();
 export const registerNewContainer = function (data, instances) {
     if (containers.has(data.id)) {
@@ -75,6 +77,9 @@ export const registerNewContainer = function (data, instances) {
         renderManager: asClass(RenderManager, { lifetime: Lifetime.SINGLETON }),
         domManager: asClass(DomManager, { lifetime: Lifetime.SINGLETON }),
         mediaManager: asClass(MediaManager, { lifetime: Lifetime.SINGLETON }),
+        deterministicMediaManager: asClass(DeterministicMediaManager, {
+            lifetime: Lifetime.SINGLETON
+        }),
         sceneBuilder: asClass(SceneBuilder, { lifetime: Lifetime.SINGLETON }),
         layersManager: asClass(LayersManager, { lifetime: Lifetime.SINGLETON }),
         // transients
@@ -87,6 +92,9 @@ export const registerNewContainer = function (data, instances) {
         imageHook: asClass(ImageHook, { lifetime: Lifetime.TRANSIENT }),
         verifyImageHook: asClass(VerifyImageHook, { lifetime: Lifetime.TRANSIENT }),
         verifyGifHook: asClass(VerifyGifHook, { lifetime: Lifetime.TRANSIENT }),
+        deterministicMediaFrameHook: asClass(DeterministicMediaFrameHook, {
+            lifetime: Lifetime.TRANSIENT
+        }),
         videoTextureHook: asClass(PixiVideoTextureHook, { lifetime: Lifetime.TRANSIENT }),
         splitScreenHook: asClass(PixiSplitScreenDisplayObjectHook, { lifetime: Lifetime.TRANSIENT }),
         htmlTextHook: asClass(HtmlTextHook, { lifetime: Lifetime.TRANSIENT }),

package/dist/SceneBuilder.svelte.d.ts

@@ -8,7 +8,9 @@ import { DomManager } from './managers/DomManager.js';
 import { AppManager } from './managers/AppManager.svelte.js';
 import { ComponentsManager } from './managers/ComponentsManager.svelte.js';
 import type { EventMap, EventType, EventPayload, BuilderState, ISceneBuilder } from './';
+import type { DeterministicFrameProvider, DeterministicMediaConfig, DeterministicDiagnosticsReport, RenderFrameRangeOptions, RenderFrameRangeSummary } from './';
 import { MediaManager } from './managers/MediaManager.js';
+import { DeterministicMediaManager } from './managers/DeterministicMediaManager.js';
 import { LayersManager } from './managers/LayersManager.svelte.js';
 import { SubtitlesManager } from './managers/SubtitlesManager.svelte.js';
 import type { Component } from './components/Component.svelte.js';
@@ -24,6 +26,7 @@ export declare class SceneBuilder implements ISceneBuilder {
     private stateManager;
     private commandRunner;
     private mediaManager;
+    private deterministicMediaManager;
     private subtitlesManager;
     private fonts;
     constructor(cradle: {
@@ -36,6 +39,7 @@ export declare class SceneBuilder implements ISceneBuilder {
         stateManager: StateManager;
         commandRunner: CommandRunner;
         mediaManager: MediaManager;
+        deterministicMediaManager: DeterministicMediaManager;
         subtitlesManager: SubtitlesManager;
         fonts: FontType[];
     });
@@ -5369,6 +5373,10 @@ export declare class SceneBuilder implements ISceneBuilder {
     splitComponent(component: Component): Promise<boolean>;
     seek(time: number): Promise<void>;
     replaceSourceOnTime(time: number, componentId: string, base64data: string): Promise<void>;
+    setDeterministicFrameProvider(provider: DeterministicFrameProvider | null): void;
+    getDeterministicFrameProvider(): DeterministicFrameProvider | null;
+    getDeterministicMediaConfig(): DeterministicMediaConfig;
+    getDiagnosticsReport(): DeterministicDiagnosticsReport | null;
     seekAndRenderFrame(time: number, target?: PIXI.DisplayObject | PIXI.RenderTexture, format?: string, quality?: number): Promise<string | ArrayBuffer | Blob>;
     /**
      * Check if seeking to a specific time would result in visual changes
@@ -5395,6 +5403,7 @@ export declare class SceneBuilder implements ISceneBuilder {
      */
     isSceneDirty(time: number): Promise<boolean>;
     renderFrame(target?: PIXI.DisplayObject | PIXI.RenderTexture, format?: string, quality?: number): Promise<string | ArrayBuffer | Blob>;
+    renderFrameRange(options: RenderFrameRangeOptions): Promise<RenderFrameRangeSummary>;
     log(message: string): void;
     play(changeState?: boolean): void;
     pause(changeState?: boolean): void;

package/dist/SceneBuilder.svelte.js

@@ -13,6 +13,7 @@ import { AppManager } from './managers/AppManager.svelte.js';
 import { ComponentsManager } from './managers/ComponentsManager.svelte.js';
 import { v4 as uuidv4 } from 'uuid';
 import { MediaManager } from './managers/MediaManager.js';
+import { DeterministicMediaManager } from './managers/DeterministicMediaManager.js';
 import { LayersManager } from './managers/LayersManager.svelte.js';
 import { SubtitlesManager } from './managers/SubtitlesManager.svelte.js';
 import { removeContainer } from './DIContainer.js';
@@ -28,6 +29,7 @@ export class SceneBuilder {
     stateManager;
     commandRunner;
     mediaManager;
+    deterministicMediaManager;
     subtitlesManager;
     fonts;
     // Replace constructor with cradle pattern
@@ -41,6 +43,7 @@ export class SceneBuilder {
         this.stateManager = cradle.stateManager;
         this.commandRunner = cradle.commandRunner;
         this.mediaManager = cradle.mediaManager;
+        this.deterministicMediaManager = cradle.deterministicMediaManager;
         this.subtitlesManager = cradle.subtitlesManager;
         this.fonts = cradle.fonts;
         // TODO - check scene is v2
@@ -295,6 +298,18 @@ export class SceneBuilder {
             base64data
         });
     }
+    setDeterministicFrameProvider(provider) {
+        this.deterministicMediaManager.setProvider(provider);
+    }
+    getDeterministicFrameProvider() {
+        return this.deterministicMediaManager.getProvider();
+    }
+    getDeterministicMediaConfig() {
+        return this.deterministicMediaManager.config;
+    }
+    getDiagnosticsReport() {
+        return this.deterministicMediaManager.getDiagnosticsReport();
+    }
     async seekAndRenderFrame(time, target, format = 'png', quality = 1) {
         await this.seek(time);
         // Ensure scene is rendered after seek so media hooks apply their updates
@@ -345,6 +360,66 @@ export class SceneBuilder {
         }
         return frame;
     }
+    async renderFrameRange(options) {
+        if (this.environment !== 'server') {
+            throw new Error('renderFrameRange is only available in server environment');
+        }
+        const format = options.format ?? 'blob';
+        const quality = options.quality ?? 1;
+        const skipDuplicates = options.skipDuplicates ?? false;
+        const fromFrame = Math.max(0, Math.floor(options.fromFrame));
+        const toFrame = Math.max(fromFrame, Math.floor(options.toFrame));
+        let framesRendered = 0;
+        let framesSkipped = 0;
+        let aborted = false;
+        let previousFrame = null;
+        for (let frameIndex = fromFrame; frameIndex < toFrame; frameIndex += 1) {
+            if (options.signal?.aborted) {
+                aborted = true;
+                break;
+            }
+            let frame;
+            let isDuplicate = false;
+            const frameTime = frameIndex / this.fps;
+            if (skipDuplicates) {
+                const isDirty = await this.isSceneDirty(frameTime);
+                if (!isDirty && previousFrame) {
+                    frame = previousFrame;
+                    isDuplicate = true;
+                    framesSkipped += 1;
+                }
+                else {
+                    frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality);
+                    previousFrame = frame;
+                }
+            }
+            else {
+                frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality);
+                previousFrame = frame;
+            }
+            let released = false;
+            const release = () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+            };
+            await options.onFrame({
+                frameIndex,
+                frame,
+                isDuplicate,
+                release
+            });
+            release();
+            framesRendered += 1;
+        }
+        return {
+            framesRendered,
+            framesSkipped,
+            aborted,
+            diagnostics: this.getDiagnosticsReport()
+        };
+    }
     log(message) {
         $effect.root(function () {
             $inspect(message);
@@ -401,6 +476,7 @@ export class SceneBuilder {
         this.componentsManager.destroy();
         // media manages should be destroyed last
         this.mediaManager.destroy();
+        void this.deterministicMediaManager.destroy();
         // Remove the container from the DI container cache
         removeContainer(this.sceneData.id);
     }

package/dist/builders/PixiComponentBuilder.d.ts

@@ -20,6 +20,7 @@ type PixiComponentCradle = {
     pixiProgressShapeHook: ComponentHook;
     htmlToCanvasHook: ComponentHook;
     mediaSeekingHook: ComponentHook;
+    deterministicMediaFrameHook: ComponentHook;
 };
 export declare class PixiComponentBuilder implements IComponentBuilder {
     private component;
@@ -41,11 +42,13 @@ export declare class PixiComponentBuilder implements IComponentBuilder {
     private htmlToCanvasHook;
     private animationHook;
     private mediaSeekingHook;
+    private deterministicMediaFrameHook;
     constructor(cradle: PixiComponentCradle);
     withCanvasShape(): this;
     withProgressShape(): this;
     withMedia(): this;
     withMediaSeeking(): this;
+    withDeterministicMedia(): this;
     withImage(): this;
     withTexture(): this;
     withDisplayObject(): this;

package/dist/builders/PixiComponentBuilder.js

@@ -19,6 +19,7 @@ export class PixiComponentBuilder {
     htmlToCanvasHook;
     animationHook;
     mediaSeekingHook;
+    deterministicMediaFrameHook;
     constructor(cradle) {
         this.component = cradle.component;
         this.mediaHook = cradle.mediaHook;
@@ -39,6 +40,7 @@ export class PixiComponentBuilder {
         this.pixiProgressShapeHook = cradle.pixiProgressShapeHook;
         this.htmlToCanvasHook = cradle.htmlToCanvasHook;
         this.mediaSeekingHook = cradle.mediaSeekingHook;
+        this.deterministicMediaFrameHook = cradle.deterministicMediaFrameHook;
     }
     withCanvasShape() {
         this.component.addHook(this.canvasShapeHook);
@@ -57,6 +59,10 @@ export class PixiComponentBuilder {
         this.component.addHook(this.mediaSeekingHook);
         return this;
     }
+    withDeterministicMedia() {
+        this.component.addHook(this.deterministicMediaFrameHook, 4);
+        return this;
+    }
     withImage() {
         this.component.addHook(this.verifyImageHook);
         this.component.addHook(this.imageHook);

package/dist/builders/_ComponentState.svelte.d.ts

@@ -15,7 +15,7 @@ export declare class ComponentState implements ComponentProps {
     setRefreshCallback(callback: () => Promise<void>): void;
     private maybeAutoRefresh;
     get id(): string;
-    get type(): "IMAGE" | "GIF" | "VIDEO" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
+    get type(): "VIDEO" | "GIF" | "IMAGE" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
     get name(): string;
     get start_at(): number;
     get end_at(): number;

package/dist/commands/RenderFrameCommand.d.ts

@@ -2,16 +2,20 @@ import type { Command } from './Command.js';
 import { StateManager } from '../managers/StateManager.svelte.js';
 import { DomManager } from '../managers/DomManager.js';
 import { AppManager } from '../managers/AppManager.svelte.js';
+import { DeterministicMediaManager } from '../managers/DeterministicMediaManager.js';
 export declare class RenderFrameCommand implements Command<string | ArrayBuffer | Blob | null> {
     private sceneState;
     private domManager;
     private appManager;
     private lastRenderedFrame;
     private lastRenderArgs;
+    private deterministicMediaManager?;
+    private lastDeterministicFingerprint;
     constructor(cradle: {
         stateManager: StateManager;
         domManager: DomManager;
         appManager: AppManager;
+        deterministicMediaManager?: DeterministicMediaManager;
     });
     execute(args: unknown): Promise<string | ArrayBuffer | Blob | null>;
 }

package/dist/commands/RenderFrameCommand.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { StateManager } from '../managers/StateManager.svelte.js';
 import { DomManager } from '../managers/DomManager.js';
 import { AppManager } from '../managers/AppManager.svelte.js';
+import { DeterministicMediaManager } from '../managers/DeterministicMediaManager.js';
 const replaceSourceOnTimeSchema = z.object({
     format: z.enum(['arraybuffer', 'blob', 'png', 'jpg', 'jpeg']),
     quality: z.number().min(0).max(1),
@@ -13,10 +14,13 @@ export class RenderFrameCommand {
     appManager;
     lastRenderedFrame = null;
     lastRenderArgs = null;
+    deterministicMediaManager;
+    lastDeterministicFingerprint = '';
     constructor(cradle) {
         this.sceneState = cradle.stateManager;
         this.domManager = cradle.domManager;
         this.appManager = cradle.appManager;
+        this.deterministicMediaManager = cradle.deterministicMediaManager;
     }
     async execute(args) {
         const check = replaceSourceOnTimeSchema.safeParse(args);
@@ -24,6 +28,7 @@ export class RenderFrameCommand {
             return null;
         }
         const { format, quality, target } = check.data;
+        const currentDeterministicFingerprint = this.deterministicMediaManager?.isEnabled() ? this.deterministicMediaManager.getFingerprint() : '';
         // Server optimization: Return cached frame if nothing changed visually and render args match
         if (this.sceneState.environment === 'server' && !this.sceneState.isDirty) {
             if (this.lastRenderedFrame && this.lastRenderArgs) {
@@ -31,7 +36,7 @@ export class RenderFrameCommand {
                 const argsMatch = this.lastRenderArgs.format === format &&
                     this.lastRenderArgs.quality === quality &&
                     this.lastRenderArgs.target === target;
-                if (argsMatch) {
+                if (argsMatch && this.lastDeterministicFingerprint === currentDeterministicFingerprint) {
                     return this.lastRenderedFrame;
                 }
             }
@@ -86,6 +91,7 @@ export class RenderFrameCommand {
         if (this.sceneState.environment === 'server') {
             this.lastRenderedFrame = frame;
             this.lastRenderArgs = { format, quality, target };
+            this.lastDeterministicFingerprint = currentDeterministicFingerprint;
             this.sceneState.clearDirty();
         }
         return frame;

package/dist/commands/ReplaceSourceOnTimeCommand.d.ts

@@ -1,4 +1,13 @@
 import type { Command } from './Command.js';
+import { StateManager } from '../managers/StateManager.svelte.js';
+import { DeterministicMediaManager } from '../managers/DeterministicMediaManager.js';
 export declare class ReplaceSourceOnTimeCommand implements Command<void> {
+    #private;
+    private stateManager;
+    private deterministicMediaManager;
+    constructor(cradle: {
+        stateManager: StateManager;
+        deterministicMediaManager: DeterministicMediaManager;
+    });
     execute(args: unknown): Promise<void>;
 }

package/dist/commands/ReplaceSourceOnTimeCommand.js

@@ -1,22 +1,55 @@
 import { z } from 'zod';
+import { StateManager } from '../managers/StateManager.svelte.js';
+import { DeterministicMediaManager } from '../managers/DeterministicMediaManager.js';
 const replaceSourceOnTimeSchema = z.object({
     componentId: z.string(),
     base64data: z.string(),
     time: z.number()
 });
 export class ReplaceSourceOnTimeCommand {
+    stateManager;
+    deterministicMediaManager;
+    constructor(cradle) {
+        this.stateManager = cradle.stateManager;
+        this.deterministicMediaManager = cradle.deterministicMediaManager;
+    }
     async execute(args) {
-        // TODO: Complete implementation - this is work in progress
-        // if (this.sceneBuilder.environment != 'server') {
-        // 	this.sceneBuilder.log('replaceSource is only available in server environment');
-        // 	return;
-        // }
         const check = replaceSourceOnTimeSchema.safeParse(args);
         if (!check.success) {
-            // this.sceneBuilder.log('ReplaceSourceOnTimeCommand failed with error: ' + check.error);
             return;
         }
-        // WIP: Need to implement the actual source replacement logic
+        const { componentId, base64data, time } = check.data;
+        if (!this.deterministicMediaManager.isEnabled()) {
+            return;
+        }
+        const frameIndex = Math.max(0, Math.round(time * (this.stateManager.data.settings.fps || 30)));
+        const blob = this.#base64ToBlob(base64data);
+        if (!blob) {
+            return;
+        }
+        const cacheKey = `replace:${componentId}:${frameIndex}:${base64data.length}`;
+        this.deterministicMediaManager.setOneTimeOverride(componentId, frameIndex, {
+            kind: 'blob',
+            cacheKey,
+            blob
+        });
+        this.stateManager.markDirty();
         return;
     }
+    #base64ToBlob(base64Data) {
+        try {
+            const [header, encoded] = base64Data.split(',', 2);
+            const mimeMatch = /data:(.*?);base64/.exec(header ?? '');
+            const mimeType = mimeMatch?.[1] || 'image/png';
+            const binary = atob(encoded ?? base64Data);
+            const bytes = new Uint8Array(binary.length);
+            for (let index = 0; index < binary.length; index += 1) {
+                bytes[index] = binary.charCodeAt(index);
+            }
+            return new Blob([bytes], { type: mimeType });
+        }
+        catch {
+            return null;
+        }
+    }
 }

package/dist/components/Component.svelte.d.ts

@@ -8,7 +8,7 @@ export declare class Component implements IComponent {
         componentContext: ComponentContext;
     });
     get id(): string;
-    get type(): "IMAGE" | "GIF" | "VIDEO" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
+    get type(): "VIDEO" | "GIF" | "IMAGE" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
     get props(): ComponentProps;
     get displayObject(): import("pixi.js-legacy").Container<import("pixi.js-legacy").DisplayObject> | undefined;
     get context(): IComponentContext;

package/dist/components/ComponentContext.svelte.d.ts

@@ -16,7 +16,7 @@ export declare class ComponentContext implements IComponentContext {
     get contextData(): ComponentData;
     get data(): ComponentData;
     get id(): string;
-    get type(): "IMAGE" | "GIF" | "VIDEO" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
+    get type(): "VIDEO" | "GIF" | "IMAGE" | "TEXT" | "SHAPE" | "AUDIO" | "COLOR" | "GRADIENT" | "SUBTITLES";
     get isActive(): boolean;
     get progress(): number;
     get currentComponentTime(): number;

package/dist/components/hooks/DeterministicMediaFrameHook.d.ts

@@ -0,0 +1,13 @@
+import type { HookType, IComponentContext, IComponentHook } from '../..';
+import { DeterministicMediaManager } from '../../managers/DeterministicMediaManager.js';
+import { StateManager } from '../../managers/StateManager.svelte.js';
+export declare class DeterministicMediaFrameHook implements IComponentHook {
+    #private;
+    types: HookType[];
+    priority: number;
+    constructor(cradle: {
+        stateManager: StateManager;
+        deterministicMediaManager: DeterministicMediaManager;
+    });
+    handle(type: HookType, context: IComponentContext): Promise<void>;
+}

package/dist/components/hooks/DeterministicMediaFrameHook.js

@@ -0,0 +1,89 @@
+import { DeterministicRenderError } from '../../schemas/runtime/deterministic.js';
+import { DeterministicMediaManager } from '../../managers/DeterministicMediaManager.js';
+import { StateManager } from '../../managers/StateManager.svelte.js';
+export class DeterministicMediaFrameHook {
+    types = ['setup', 'update', 'destroy'];
+    priority = 4;
+    #context;
+    #state;
+    #manager;
+    constructor(cradle) {
+        this.#state = cradle.stateManager;
+        this.#manager = cradle.deterministicMediaManager;
+    }
+    #clearDeterministicResources(componentId) {
+        const cacheKeyChanged = this.#manager.clearCacheKey(componentId);
+        this.#context.removeResource('pixiResource');
+        this.#context.removeResource('imageElement');
+        return cacheKeyChanged;
+    }
+    async #handleUpdate() {
+        if (!this.#manager.isEnabled() || this.#state.environment !== 'server') {
+            return;
+        }
+        const fps = this.#state.data.settings.fps || 30;
+        const data = this.#context.contextData;
+        if (!this.#context.isActive) {
+            const cacheKeyChanged = this.#clearDeterministicResources(data.id);
+            if (cacheKeyChanged) {
+                this.#state.markDirty();
+            }
+            return;
+        }
+        const frameIndex = Math.max(0, Math.round(this.#context.currentComponentTime * fps));
+        const override = await this.#manager.resolveOverride({
+            componentId: data.id,
+            componentType: data.type === 'GIF' ? 'GIF' : 'VIDEO',
+            frameIndex,
+            fps,
+            width: this.#state.width,
+            height: this.#state.height
+        });
+        if (!override) {
+            const cacheKeyChanged = this.#clearDeterministicResources(data.id);
+            if (cacheKeyChanged) {
+                this.#state.markDirty();
+            }
+            if (this.#manager.config.strict && this.#manager.getProvider()) {
+                throw new DeterministicRenderError('Deterministic frame provider returned null', {
+                    componentId: data.id,
+                    frameIndex,
+                    sceneTime: this.#state.currentTime
+                });
+            }
+            return;
+        }
+        this.#context.setResource('pixiResource', override.pixiResource);
+        if (override.imageElement) {
+            this.#context.setResource('imageElement', override.imageElement);
+        }
+        const cacheKeyChanged = this.#manager.commitCacheKey(data.id, override.cacheKey);
+        if (cacheKeyChanged) {
+            this.#state.markDirty();
+        }
+    }
+    async #handleDestroy() {
+        const data = this.#context.contextData;
+        this.#clearDeterministicResources(data.id);
+        try {
+            await this.#manager.releaseComponent(data.id);
+        }
+        catch {
+            // Best-effort cleanup only.
+        }
+    }
+    async handle(type, context) {
+        this.#context = context;
+        const data = this.#context.contextData;
+        if (data.type !== 'VIDEO' && data.type !== 'GIF') {
+            return;
+        }
+        if (type === 'update') {
+            await this.#handleUpdate();
+            return;
+        }
+        if (type === 'destroy') {
+            await this.#handleDestroy();
+        }
+    }
+}

package/dist/components/hooks/ImageHook.js

@@ -1,37 +1,93 @@
 import { ImageComponentShape } from '../..';
 import { z } from 'zod';
 export class ImageHook {
-    types = ['setup', 'destroy'];
+    types = ['setup', 'refresh', 'refresh:content', 'destroy'];
     #handlers = {
         setup: this.#handleSetup.bind(this),
+        refresh: this.#handleRefreshContent.bind(this),
+        'refresh:content': this.#handleRefreshContent.bind(this),
         destroy: this.#handleDestroy.bind(this)
     };
     priority = 1;
     #context;
     #imageElement;
+    #lastUrl;
     componentElement;
-    async #handleSetup() {
-        if (this.#imageElement) {
-            return;
-        }
+    async #loadImage(url) {
         const img = new Image();
-        img.src = this.componentElement.source.url;
+        // crossOrigin must be set before src to ensure CORS mode is applied from the first request
         img.crossOrigin = 'anonymous';
-        // Wait for the image to load
+        img.src = url;
         await new Promise((resolve, reject) => {
             img.onload = resolve;
-            img.onerror = (error) => reject(new Error(`Failed to load image: ${this.componentElement.source.url}`));
+            img.onerror = () => reject(new Error(`Failed to load image: ${url}`));
         });
+        return img;
+    }
+    #clearResources() {
+        if (this.#imageElement) {
+            this.#imageElement.remove();
+            this.#imageElement = undefined;
+        }
+        this.#lastUrl = undefined;
+        this.#context.removeResource('imageElement');
+        this.#context.removeResource('pixiResource');
+    }
+    #resolveUrl() {
+        const url = this.componentElement.source.url;
+        if (!url || typeof url !== 'string') {
+            // Clear stale resources before disabling so downstream hooks never see
+            // an old image/pixiResource paired with the now-invalid source URL.
+            this.#clearResources();
+            this.#context.disabled = true;
+            throw new Error(`ImageHook: source.url is missing or invalid (got ${JSON.stringify(url)})`);
+        }
+        return url;
+    }
+    async #handleSetup() {
+        const url = this.#resolveUrl();
+        if (this.#imageElement && this.#lastUrl === url) {
+            // Already loaded and URL unchanged — re-assert resources in case context was cleared
+            this.#context.setResource('imageElement', this.#imageElement);
+            this.#context.setResource('pixiResource', this.#imageElement);
+            return;
+        }
+        if (this.#imageElement) {
+            this.#clearResources();
+        }
+        const img = await this.#loadImage(url);
         this.#imageElement = img;
+        this.#lastUrl = url;
+        this.#context.setResource('imageElement', img);
+        this.#context.setResource('pixiResource', img);
+    }
+    async #handleRefreshContent() {
+        const url = this.#resolveUrl();
+        if (this.#lastUrl === url) {
+            // URL unchanged — re-assert resources in case context was cleared between frames
+            if (this.#imageElement) {
+                this.#context.setResource('imageElement', this.#imageElement);
+                this.#context.setResource('pixiResource', this.#imageElement);
+            }
+            return;
+        }
+        this.#clearResources();
+        const img = await this.#loadImage(url);
+        this.#imageElement = img;
+        this.#lastUrl = url;
         this.#context.setResource('imageElement', img);
         this.#context.setResource('pixiResource', img);
     }
     async #handleDestroy() {
-        // remove event listeners from video
-        this.#imageElement.remove();
+        this.#clearResources();
     }
     async handle(type, context) {
         this.#context = context;
+        // Destroy must run regardless of whether imageShape is present,
+        // so that stale resources are always cleaned up.
+        if (type === 'destroy') {
+            return await this.#handleDestroy();
+        }
         const data = this.#context.getResource('imageShape');
         if (!data) {
             return;