visualfries 0.1.10110 → 0.1.10120

package/README.md

@@ -198,6 +198,31 @@ const builder = await createSceneBuilder(sceneData, container, {
 });
 ```
 
+## Server Renderer Mode (Canvas vs WebGL)
+
+Server mode remains canvas-first by default for backward compatibility:
+
+```typescript
+await createSceneBuilder(sceneData, container, {
+	environment: 'server'
+	// serverRendererMode defaults to "canvas"
+});
+```
+
+To opt into GPU rendering on server/headless runtimes:
+
+```typescript
+await createSceneBuilder(sceneData, container, {
+	environment: 'server',
+	serverRendererMode: 'webgl',
+	preferWebGL2: true,
+	powerPreference: 'high-performance'
+});
+```
+
+If WebGL is unavailable or initialization fails, Visualfries automatically falls back to canvas so deterministic render jobs keep running. When deterministic diagnostics are enabled, renderer selection and fallback reason are included in `getDiagnosticsReport()`.
+In `serverRendererMode: 'webgl'`, `fillBackgroundBlur` uses native `PIXI.BlurFilter` (same rendering path as client mode).
+
 ## Contributing
 
 As an early-stage, solo-developed project, contributions are highly encouraged! The best way to contribute right now is by:

package/dist/SceneBuilder.svelte.js

@@ -403,7 +403,9 @@ export class SceneBuilder {
                     framesSkipped += 1;
                 }
                 else {
-                    frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality, imageOptions);
+                    // isSceneDirty() already sought and prepared server deterministic state.
+                    // Render directly to avoid a second seek in the dirty path.
+                    frame = await this.renderFrame(undefined, format, quality, imageOptions);
                     previousFrame = frame;
                 }
             }

package/dist/commands/SeekCommand.js

@@ -13,6 +13,7 @@ export class SeekCommand {
     renderManager;
     componentsManager;
     deterministicMediaManager;
+    #didAwaitFontsReady = false;
     constructor(cradle) {
         this.timeline = cradle.timelineManager;
         this.state = cradle.stateManager;
@@ -61,17 +62,62 @@ export class SeekCommand {
         }
         return pending;
     }
+    #getCurrentSceneFrameIndex() {
+        const fps = this.state.data?.settings?.fps || 30;
+        const currentTime = this.state.currentTime ?? 0;
+        return Math.max(0, Math.round(currentTime * fps));
+    }
+    async #delay(ms) {
+        if (ms <= 0) {
+            const immediate = globalThis.setImmediate;
+            if (typeof immediate === 'function') {
+                await new Promise((resolve) => {
+                    immediate(resolve);
+                });
+                return;
+            }
+            await Promise.resolve();
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async #awaitFontsReadyOnce() {
+        if (this.#didAwaitFontsReady) {
+            return;
+        }
+        this.#didAwaitFontsReady = true;
+        if (typeof document === 'undefined' || !document.fonts?.ready) {
+            return;
+        }
+        try {
+            await Promise.race([
+                document.fonts.ready,
+                new Promise((resolve) => setTimeout(resolve, 2000))
+            ]);
+        }
+        catch {
+            // Font readiness is best-effort in seek path.
+        }
+    }
     async #renderUntilDeterministicReady() {
-        const maxAttempts = 12;
+        const pendingBeforeRetry = this.#getPendingDeterministicComponents();
+        if (pendingBeforeRetry.length === 0) {
+            return;
+        }
+        const maxAttempts = this.deterministicMediaManager.config.seekMaxAttempts ?? 4;
+        const readyYieldMs = this.deterministicMediaManager.config.readyYieldMs ?? 0;
+        const sceneFrameIndex = this.#getCurrentSceneFrameIndex();
+        let pending = pendingBeforeRetry;
         for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+            this.deterministicMediaManager.recordReadyAttempt(sceneFrameIndex);
+            this.deterministicMediaManager.recordExtraRenderPass(sceneFrameIndex);
+            await this.#delay(readyYieldMs);
             await this.renderManager.render();
-            const pending = this.#getPendingDeterministicComponents();
+            pending = this.#getPendingDeterministicComponents();
             if (pending.length === 0) {
                 return;
             }
-            await new Promise((resolve) => setTimeout(resolve, 0));
         }
-        const pending = this.#getPendingDeterministicComponents();
         if (pending.length > 0) {
             throw new Error(`Deterministic media was not ready after seek for active components: ${pending.join(', ')}`);
         }
@@ -85,28 +131,18 @@ export class SeekCommand {
         this.timeline.seek(time);
         // Ensure a deterministic render on server after seek to advance media frames
         if (this.state.environment === 'server') {
-            // Wait for fonts to be ready before rendering
-            // This is critical for subtitle animations that use SplitText -
-            // if fonts aren't loaded, text measurements will be wrong and
-            // animations may fail silently or not appear on first subtitles
-            if (typeof document !== 'undefined' && document.fonts?.ready) {
-                try {
-                    await Promise.race([
-                        document.fonts.ready,
-                        new Promise((resolve) => setTimeout(resolve, 2000)) // 2s timeout
-                    ]);
-                }
-                catch {
-                    // Ignore font loading errors, continue with rendering
-                }
+            const deterministicEnabled = this.deterministicMediaManager.isEnabled();
+            if (deterministicEnabled) {
+                await this.#awaitFontsReadyOnce();
             }
-            // Try multiple render passes until loading state clears or attempts exhausted
-            const maxAttempts = 10;
-            for (let i = 0; i < maxAttempts; i += 1) {
+            const readyYieldMs = this.deterministicMediaManager.config.readyYieldMs ?? 0;
+            const loadingMaxAttempts = this.deterministicMediaManager.config.loadingMaxAttempts ?? 2;
+            const sceneFrameIndex = this.#getCurrentSceneFrameIndex();
+            await this.renderManager.render();
+            for (let i = 0; i < loadingMaxAttempts && this.state.state === 'loading'; i += 1) {
+                this.deterministicMediaManager.recordExtraRenderPass(sceneFrameIndex);
+                await this.#delay(readyYieldMs);
                 await this.renderManager.render();
-                if (this.state.state !== 'loading')
-                    break;
-                await new Promise((resolve) => setTimeout(resolve, 30));
             }
             if (this.state.state === 'loading') {
                 console.warn('SeekCommand: Max render attempts exhausted while still loading');
@@ -116,7 +152,7 @@ export class SeekCommand {
             // This fixes the race condition where subtitle animations are added
             // AFTER the initial seek, causing them to miss their initial state.
             this.timeline.seek(time);
-            if (this.deterministicMediaManager.isEnabled()) {
+            if (deterministicEnabled) {
                 await this.#renderUntilDeterministicReady();
             }
             else {

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

@@ -2,14 +2,20 @@ import type { IComponentContext, IComponentHook, HookType } from '../..';
 import { ImageComponentShape, VideoComponentShape } from '../..';
 import { z } from 'zod';
 import type { StateManager } from '../../managers/StateManager.svelte.ts';
+import type { DeterministicMediaManager } from '../../managers/DeterministicMediaManager.ts';
+import type { AppManager } from '../../managers/AppManager.svelte.ts';
 export declare class PixiSplitScreenDisplayObjectHook implements IComponentHook {
     #private;
     types: HookType[];
     priority: number;
     componentElement: z.infer<typeof VideoComponentShape> | z.infer<typeof ImageComponentShape>;
     private sceneState;
+    private deterministicMediaManager?;
+    private appManager?;
     constructor(cradle: {
         stateManager: StateManager;
+        deterministicMediaManager?: DeterministicMediaManager;
+        appManager?: AppManager;
     });
     get sceneWidth(): number;
     get sceneHeight(): number;

package/dist/components/hooks/PixiSplitScreenDisplayObjectHook.js

@@ -16,10 +16,20 @@ export class PixiSplitScreenDisplayObjectHook {
     #pixiTexture;
     #displayObject;
     #bgCanvas = undefined;
+    #bgSprite = undefined;
+    #blurStrength = 50;
+    #blurDownscale = 0.33;
+    #lastBlurFrameKey = '';
+    #resourceIds = new WeakMap();
+    #nextResourceId = 1;
     componentElement;
     sceneState;
+    deterministicMediaManager;
+    appManager;
     constructor(cradle) {
         this.sceneState = cradle.stateManager;
+        this.deterministicMediaManager = cradle.deterministicMediaManager;
+        this.appManager = cradle.appManager;
     }
     get sceneWidth() {
         return this.#context.sceneState.width;
@@ -29,10 +39,21 @@ export class PixiSplitScreenDisplayObjectHook {
     }
     initBlurBackground(strength = 50) {
         const sanitizedStrength = this.#sanitizeBlurStrength(strength);
+        this.#blurDownscale = this.#getBlurDownscale();
+        this.#blurStrength = sanitizedStrength;
+        this.#lastBlurFrameKey = '';
         const backgroundSprite = new PIXI.Sprite(this.#pixiTexture);
+        this.#bgSprite = backgroundSprite;
         this.setupBackground(backgroundSprite, sanitizedStrength);
         this.#displayObject.addChild(backgroundSprite);
     }
+    #getBlurDownscale() {
+        const configured = this.deterministicMediaManager?.config.blurDownscale ?? 0.33;
+        if (!Number.isFinite(configured)) {
+            return 0.33;
+        }
+        return Math.max(0.05, Math.min(1, configured));
+    }
     setupBackground(backgroundSprite, strength = 50) {
         const sanitizedStrength = this.#sanitizeBlurStrength(strength);
         const sceneRatio = this.sceneWidth / this.sceneHeight;
@@ -51,39 +72,83 @@ export class PixiSplitScreenDisplayObjectHook {
         // Center the background sprite
         backgroundSprite.x = (this.sceneWidth - backgroundSprite.width) / 2;
         backgroundSprite.y = (this.sceneHeight - backgroundSprite.height) / 2;
-        if (this.sceneState.environment === 'server') {
+        if (this.sceneState.environment === 'server' && !this.#isWebGLRendererActive()) {
             // Create a temporary canvas for blur effect
             const bgCanvas = document.createElement('canvas');
-            bgCanvas.width = backgroundSprite.width;
-            bgCanvas.height = backgroundSprite.height;
+            bgCanvas.width = Math.max(1, Math.round(backgroundSprite.width * this.#blurDownscale));
+            bgCanvas.height = Math.max(1, Math.round(backgroundSprite.height * this.#blurDownscale));
             this.#bgCanvas = bgCanvas;
-            this.#drawBlurredBackground(sanitizedStrength);
+            this.#drawBlurredBackground(sanitizedStrength, true);
             const blurredTexture = PIXI.Texture.from(bgCanvas);
             backgroundSprite.texture = blurredTexture;
         }
         else {
-            // Create new PIXI texture from blurred canvas
+            // Client mode and server webgl mode both use PIXI blur filter.
+            this.#bgCanvas = undefined;
             const blurFilter = new PIXI.BlurFilter(sanitizedStrength, 50, 1, 7);
             backgroundSprite.filters = [blurFilter];
         }
     }
-    #drawBlurredBackground(strength = 50) {
+    #isWebGLRendererActive() {
+        const renderer = this.appManager?.app?.renderer;
+        if (renderer?.gl || renderer?.context?.gl || renderer?.context?.webGLVersion) {
+            return true;
+        }
+        return this.deterministicMediaManager?.getSelectedRendererType?.() === 'webgl';
+    }
+    #drawBlurredBackground(strength = 50, force = false) {
         if (!this.#bgCanvas) {
-            return;
+            return false;
         }
         // Validate and sanitize strength parameter
         const sanitizedStrength = this.#sanitizeBlurStrength(strength);
         const ctx = this.#bgCanvas.getContext('2d');
-        // Use sanitized value to prevent XSS
-        ctx.filter = `blur(${sanitizedStrength}px)`;
         // Get the source element (video/image)
         const sourceElement = this.#context.getResource('videoElement') || this.#context.getResource('imageElement');
         if (!sourceElement) {
             // Video or Image element not ready yet - will be called again on next update
-            return;
+            return false;
         }
+        const fps = this.sceneState.data.settings.fps || 30;
+        const componentFrameIndex = Math.max(0, Math.round(this.#context.currentComponentTime * fps));
+        const textureToken = this.#context.getResource('pixiTexture') ?? sourceElement;
+        const frameKey = `${componentFrameIndex}:${this.#resourceToken(textureToken)}`;
+        if (!force && frameKey === this.#lastBlurFrameKey) {
+            return false;
+        }
+        this.#lastBlurFrameKey = frameKey;
+        // Use sanitized value to prevent XSS
+        const effectiveBlurStrength = sanitizedStrength * this.#blurDownscale;
+        ctx.filter = `blur(${effectiveBlurStrength}px)`;
+        ctx.clearRect(0, 0, this.#bgCanvas.width, this.#bgCanvas.height);
         // Draw the original texture with blur
-        ctx.drawImage(sourceElement, 0, 0, this.#bgCanvas.width, this.#bgCanvas.height);
+        try {
+            ctx.drawImage(sourceElement, 0, 0, this.#bgCanvas.width, this.#bgCanvas.height);
+        }
+        catch {
+            return false;
+        }
+        const texture = this.#bgSprite?.texture;
+        texture.baseTexture?.update?.();
+        texture.update?.();
+        this.deterministicMediaManager?.recordBlurRedraw(this.#currentSceneFrameIndex());
+        return true;
+    }
+    #resourceToken(value) {
+        if (typeof value === 'object' && value !== null) {
+            let id = this.#resourceIds.get(value);
+            if (!id) {
+                id = this.#nextResourceId;
+                this.#nextResourceId += 1;
+                this.#resourceIds.set(value, id);
+            }
+            return `obj-${id}`;
+        }
+        return String(value);
+    }
+    #currentSceneFrameIndex() {
+        const fps = this.sceneState.data.settings.fps || 30;
+        return Math.max(0, Math.round(this.sceneState.currentTime * fps));
     }
     /**
      * Sanitizes blur strength parameter to prevent XSS and ensure valid numeric values
@@ -187,9 +252,6 @@ export class PixiSplitScreenDisplayObjectHook {
     }
     async #handleUpdate() {
         const isActive = this.#context.isActive;
-        if (isActive) {
-            this.#drawBlurredBackground();
-        }
         if (this.#displayObject) {
             // Texture swaps are frequent in deterministic mode; update sprite textures
             // in-place instead of rebuilding split/blur geometry each frame.
@@ -197,6 +259,9 @@ export class PixiSplitScreenDisplayObjectHook {
             if (currentTexture && currentTexture !== this.#pixiTexture) {
                 this.#swapDisplayTexture(currentTexture);
             }
+            if (isActive && this.#bgCanvas) {
+                this.#drawBlurredBackground(this.#blurStrength);
+            }
             // Always re-assert the resource in case the context was cleared or updated
             this.#context.setResource('pixiRenderObject', this.#displayObject);
             if (this.#displayObject.visible != isActive) {
@@ -244,6 +309,8 @@ export class PixiSplitScreenDisplayObjectHook {
     async #handleDestroy() {
         // remove event listeners from video
         this.#bgCanvas = undefined;
+        this.#bgSprite = undefined;
+        this.#lastBlurFrameKey = '';
     }
     async handle(type, context) {
         this.#context = context;

package/dist/factories/SceneBuilderFactory.d.ts

@@ -7,6 +7,9 @@ type Config = {
     subtitles: Record<string, Subtitle[]> | Record<string, SubtitleCollection>;
     fonts: FontType[];
     forceCanvas: boolean;
+    serverRendererMode: 'canvas' | 'webgl';
+    preferWebGL2: boolean;
+    powerPreference: 'default' | 'high-performance' | 'low-power';
     scale: number;
     autoPlay?: boolean;
     loop?: boolean;

package/dist/factories/SceneBuilderFactory.js

@@ -18,6 +18,9 @@ const defaultConfig = {
     subtitles: {},
     fonts: [],
     forceCanvas: false,
+    serverRendererMode: 'canvas',
+    preferWebGL2: true,
+    powerPreference: 'high-performance',
     scale: 1,
     autoPlay: false,
     loop: false,
@@ -35,6 +38,9 @@ export const createSceneBuilder = async function (sceneData, container, config)
         ['subtitles', subs],
         ['fonts', sceneConfig.fonts],
         ['forceCanvas', sceneConfig.forceCanvas],
+        ['serverRendererMode', sceneConfig.serverRendererMode],
+        ['preferWebGL2', sceneConfig.preferWebGL2],
+        ['powerPreference', sceneConfig.powerPreference],
         ['scale', sceneConfig.scale],
         ['autoPlay', sceneConfig.autoPlay],
         ['loop', sceneConfig.loop],

package/dist/layers/Layer.svelte.js

@@ -57,8 +57,8 @@ export class Layer {
         if (!this.#displayObject) {
             return false;
         }
-        for (let index = 0; index < this.components.length; index += 1) {
-            const component = this.components[index];
+        let componentDisplayIndex = 0;
+        for (const component of this.components) {
             const displayObject = component.displayObject;
             if (!displayObject) {
                 continue;
@@ -68,16 +68,51 @@ export class Layer {
                 if (parent && typeof parent.removeChild === 'function') {
                     parent.removeChild(displayObject);
                 }
-                this.#displayObject.addChild(displayObject);
+                const childCount = this.#displayObject.children?.length ?? 0;
+                const insertIndex = Math.max(0, Math.min(componentDisplayIndex, childCount));
+                if (typeof this.#displayObject.addChildAt === 'function') {
+                    this.#displayObject.addChildAt(displayObject, insertIndex);
+                }
+                else {
+                    this.#displayObject.addChild(displayObject);
+                }
                 changed = true;
             }
             if (typeof this.#displayObject.getChildIndex === 'function' &&
                 typeof this.#displayObject.setChildIndex === 'function') {
+                const childCount = this.#displayObject.children?.length ?? 0;
+                if (childCount > 0) {
+                    const currentIndex = this.#displayObject.getChildIndex(displayObject);
+                    const targetIndex = Math.max(0, Math.min(componentDisplayIndex, childCount - 1));
+                    if (currentIndex >= 0 && currentIndex !== targetIndex) {
+                        this.#displayObject.setChildIndex(displayObject, targetIndex);
+                        changed = true;
+                    }
+                }
+            }
+            componentDisplayIndex += 1;
+        }
+        // Ensure deterministic ordering among only component display objects without
+        // assuming a 1:1 mapping with all container children.
+        if (typeof this.#displayObject.getChildIndex === 'function' &&
+            typeof this.#displayObject.setChildIndex === 'function') {
+            let nextIndex = 0;
+            for (const component of this.components) {
+                const displayObject = component.displayObject;
+                if (!displayObject || displayObject.parent !== this.#displayObject) {
+                    continue;
+                }
+                const childCount = this.#displayObject.children?.length ?? 0;
+                if (childCount === 0) {
+                    break;
+                }
                 const currentIndex = this.#displayObject.getChildIndex(displayObject);
-                if (currentIndex !== index) {
-                    this.#displayObject.setChildIndex(displayObject, index);
+                const targetIndex = Math.max(0, Math.min(nextIndex, childCount - 1));
+                if (currentIndex >= 0 && currentIndex !== targetIndex) {
+                    this.#displayObject.setChildIndex(displayObject, targetIndex);
                     changed = true;
                 }
+                nextIndex += 1;
             }
         }
         return changed;

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

@@ -1,15 +1,26 @@
 import * as PIXI from 'pixi.js-legacy';
 import { DomManager } from './DomManager.js';
 import { StateManager } from './StateManager.svelte.js';
+import type { DeterministicMediaManager } from './DeterministicMediaManager.js';
+type ServerRendererMode = 'canvas' | 'webgl';
+type PowerPreference = 'default' | 'high-performance' | 'low-power';
 export declare class AppManager {
     #private;
     private state;
     private dom;
     private forceCanvas;
+    private serverRendererMode;
+    private preferWebGL2;
+    private powerPreference;
+    private deterministicMediaManager?;
     constructor(cradle: {
         stateManager: StateManager;
         domManager: DomManager;
         forceCanvas: boolean;
+        serverRendererMode?: ServerRendererMode;
+        preferWebGL2?: boolean;
+        powerPreference?: PowerPreference;
+        deterministicMediaManager?: DeterministicMediaManager;
     });
     get app(): PIXI.Application;
     get stage(): PIXI.Container;
@@ -21,3 +32,4 @@ export declare class AppManager {
     scale(scale: number): void;
     destroy(): void;
 }
+export {};

package/dist/managers/AppManager.svelte.js

@@ -9,10 +9,18 @@ export class AppManager {
     state;
     dom;
     forceCanvas; // ForceCanvas
+    serverRendererMode;
+    preferWebGL2;
+    powerPreference;
+    deterministicMediaManager;
     constructor(cradle) {
         this.state = cradle.stateManager;
         this.dom = cradle.domManager;
         this.forceCanvas = cradle.forceCanvas;
+        this.serverRendererMode = cradle.serverRendererMode ?? 'canvas';
+        this.preferWebGL2 = cradle.preferWebGL2 ?? true;
+        this.powerPreference = cradle.powerPreference ?? 'high-performance';
+        this.deterministicMediaManager = cradle.deterministicMediaManager;
     }
     get app() {
         return this.#app;
@@ -30,29 +38,190 @@ export class AppManager {
         const { width, height, environment, scale } = this.state;
         this.#destroyed = false;
         const canvas = this.dom.canvas;
-        if (environment === 'server') {
-            const ctx = canvas.getContext('2d', { willReadFrequently: true });
+        let rendererSelection = this.#resolveRendererSelection(environment);
+        if (environment === 'server' && rendererSelection.forceCanvas) {
+            canvas.getContext('2d', { willReadFrequently: true });
         }
         const { PixiPlugin } = await registerGsapPlugins();
         // give the plugin a reference to the PIXI object
-        PixiPlugin.registerPIXI(this.app);
-        const options = {
+        PixiPlugin.registerPIXI(PIXI);
+        const baseOptions = {
             ...PIXI_DEFAULTS,
             preserveDrawingBuffer: environment === 'server',
             // clearBeforeRender: environment === 'server' ? false : true,
             width,
             height,
             view: canvas,
-            forceCanvas: environment === 'server' || this.forceCanvas,
             backgroundColor: environment === 'server' ? 'transparent' : '#ffffff',
             backgroundAlpha: environment === 'server' ? 0 : 1
         };
-        this.#app = new PIXI.Application(options);
+        let options = this.#buildRendererOptions(baseOptions, environment, rendererSelection);
+        try {
+            this.#app = new PIXI.Application(options);
+        }
+        catch (error) {
+            if (!rendererSelection.forceCanvas) {
+                const fallbackReason = this.#buildInitFallbackReason(error);
+                this.#warnRendererFallback(fallbackReason);
+                rendererSelection = {
+                    requestedMode: rendererSelection.requestedMode,
+                    selectedMode: 'canvas',
+                    forceCanvas: true,
+                    fallbackOccurred: true,
+                    fallbackReason
+                };
+                canvas.getContext('2d', { willReadFrequently: true });
+                options = this.#buildRendererOptions(baseOptions, environment, rendererSelection);
+                this.#app = new PIXI.Application(options);
+            }
+            else {
+                throw error;
+            }
+        }
+        if (!rendererSelection.forceCanvas) {
+            const actualRenderer = this.#detectRendererType();
+            if (actualRenderer !== 'webgl') {
+                const fallbackReason = 'Renderer initialized as canvas despite serverRendererMode="webgl"';
+                this.#warnRendererFallback(fallbackReason);
+                rendererSelection = {
+                    requestedMode: rendererSelection.requestedMode,
+                    selectedMode: 'canvas',
+                    forceCanvas: true,
+                    fallbackOccurred: true,
+                    fallbackReason
+                };
+            }
+            else {
+                rendererSelection = { ...rendererSelection, selectedMode: actualRenderer };
+            }
+        }
         if (scale !== 1) {
             this.scale(scale);
         }
         // Stop the default ticker as we'll use GSAP's ticker
         this.#app.ticker.stop();
+        this.deterministicMediaManager?.recordRendererSelection({
+            rendererType: rendererSelection.selectedMode,
+            fallbackOccurred: rendererSelection.fallbackOccurred,
+            fallbackReason: rendererSelection.fallbackReason
+        });
+    }
+    #buildRendererOptions(baseOptions, environment, selection) {
+        const options = {
+            ...baseOptions,
+            forceCanvas: selection.forceCanvas
+        };
+        if (environment === 'server' && selection.selectedMode === 'webgl' && !selection.forceCanvas) {
+            this.#configureWebGLEnvironmentPreference();
+            options.preference = 'webgl';
+            options.powerPreference = this.powerPreference;
+        }
+        return options;
+    }
+    #resolveRendererSelection(environment) {
+        if (environment !== 'server') {
+            return {
+                requestedMode: 'canvas',
+                selectedMode: this.forceCanvas ? 'canvas' : 'webgl',
+                forceCanvas: this.forceCanvas,
+                fallbackOccurred: false
+            };
+        }
+        const requestedMode = this.serverRendererMode;
+        if (this.forceCanvas) {
+            if (requestedMode === 'webgl') {
+                const fallbackReason = 'serverRendererMode="webgl" requested but forceCanvas=true override is enabled';
+                this.#warnRendererFallback(fallbackReason);
+                return {
+                    requestedMode,
+                    selectedMode: 'canvas',
+                    forceCanvas: true,
+                    fallbackOccurred: true,
+                    fallbackReason
+                };
+            }
+            return {
+                requestedMode,
+                selectedMode: 'canvas',
+                forceCanvas: true,
+                fallbackOccurred: false
+            };
+        }
+        if (requestedMode === 'canvas') {
+            return {
+                requestedMode,
+                selectedMode: 'canvas',
+                forceCanvas: true,
+                fallbackOccurred: false
+            };
+        }
+        const support = this.#checkWebGLSupport();
+        if (!support.supported) {
+            this.#warnRendererFallback(support.reason);
+            return {
+                requestedMode,
+                selectedMode: 'canvas',
+                forceCanvas: true,
+                fallbackOccurred: true,
+                fallbackReason: support.reason
+            };
+        }
+        return {
+            requestedMode,
+            selectedMode: 'webgl',
+            forceCanvas: false,
+            fallbackOccurred: false
+        };
+    }
+    #checkWebGLSupport() {
+        try {
+            if (typeof document === 'undefined') {
+                return { supported: false, reason: 'WebGL unavailable: no document in server environment' };
+            }
+            const probe = document.createElement('canvas');
+            if (this.preferWebGL2 && probe.getContext('webgl2')) {
+                return { supported: true, reason: '' };
+            }
+            if (probe.getContext('webgl') || probe.getContext('experimental-webgl')) {
+                return { supported: true, reason: '' };
+            }
+            return { supported: false, reason: 'WebGL unavailable: context creation failed' };
+        }
+        catch {
+            return { supported: false, reason: 'WebGL unavailable: context probe failed' };
+        }
+    }
+    #configureWebGLEnvironmentPreference() {
+        const pixiAny = PIXI;
+        if (!pixiAny.settings || !pixiAny.ENV) {
+            return;
+        }
+        if (this.preferWebGL2 && pixiAny.ENV.WEBGL2 !== undefined) {
+            pixiAny.settings.PREFER_ENV = pixiAny.ENV.WEBGL2;
+            return;
+        }
+        if (pixiAny.ENV.WEBGL !== undefined) {
+            pixiAny.settings.PREFER_ENV = pixiAny.ENV.WEBGL;
+        }
+    }
+    #detectRendererType() {
+        if (!this.#app) {
+            return 'canvas';
+        }
+        const renderer = this.#app.renderer;
+        if (renderer?.gl || renderer?.context?.gl || renderer?.context?.webGLVersion) {
+            return 'webgl';
+        }
+        return 'canvas';
+    }
+    #buildInitFallbackReason(error) {
+        if (error instanceof Error && error.message) {
+            return `WebGL initialization failed: ${error.message}`;
+        }
+        return 'WebGL initialization failed with unknown error';
+    }
+    #warnRendererFallback(reason) {
+        console.warn(`[AppManager] Falling back to canvas renderer. ${reason}`);
     }
     async extractBase64(target, format = 'png', quality = 1) {
         if (!this.#app)

package/dist/managers/ComponentsManager.svelte.js

@@ -199,11 +199,38 @@ export class ComponentsManager {
         const displayObject = layer.displayObject;
         if (!displayObject)
             return;
-        // Sync displayObject children order with components array
-        layer.components.forEach((component, index) => {
-            if (component.displayObject) {
-                displayObject.setChildIndex(component.displayObject, index);
+        // Sync displayObject children order with components array while clamping indexes.
+        let nextIndex = 0;
+        layer.components.forEach((component) => {
+            const componentDisplayObject = component.displayObject;
+            if (!componentDisplayObject) {
+                return;
             }
+            const parent = componentDisplayObject.parent;
+            if (parent !== displayObject) {
+                if (parent && typeof parent.removeChild === 'function') {
+                    parent.removeChild(componentDisplayObject);
+                }
+                const insertMax = displayObject.children?.length ?? 0;
+                const insertIndex = Math.max(0, Math.min(nextIndex, insertMax));
+                if (typeof displayObject.addChildAt === 'function') {
+                    displayObject.addChildAt(componentDisplayObject, insertIndex);
+                }
+                else {
+                    displayObject.addChild(componentDisplayObject);
+                }
+            }
+            const childCount = displayObject.children?.length ?? 0;
+            if (childCount > 0 &&
+                typeof displayObject.getChildIndex === 'function' &&
+                typeof displayObject.setChildIndex === 'function') {
+                const currentIndex = displayObject.getChildIndex(componentDisplayObject);
+                const targetIndex = Math.max(0, Math.min(nextIndex, childCount - 1));
+                if (currentIndex >= 0 && currentIndex !== targetIndex) {
+                    displayObject.setChildIndex(componentDisplayObject, targetIndex);
+                }
+            }
+            nextIndex += 1;
         });
     }
     bulkUpdate(updates) {

package/dist/managers/DeterministicMediaManager.d.ts

@@ -16,6 +16,15 @@ export declare class DeterministicMediaManager {
     getFingerprint(): string;
     setOneTimeOverride(componentId: string, frameIndex: number, payload: DeterministicFramePayload): void;
     getDiagnosticsReport(): DeterministicDiagnosticsReport | null;
+    getSelectedRendererType(): 'canvas' | 'webgl';
+    recordRendererSelection(args: {
+        rendererType: 'canvas' | 'webgl';
+        fallbackOccurred?: boolean;
+        fallbackReason?: string;
+    }): void;
+    recordReadyAttempt(sceneFrameIndex: number, count?: number): void;
+    recordExtraRenderPass(sceneFrameIndex: number, count?: number): void;
+    recordBlurRedraw(sceneFrameIndex: number, count?: number): void;
     destroy(): Promise<void>;
     releaseComponent(componentId: string): Promise<void>;
 }

package/dist/managers/DeterministicMediaManager.js

@@ -4,6 +4,13 @@ const createDefaultDiagnosticsState = () => ({
     providerHits: 0,
     providerMisses: 0,
     cacheHits: 0,
+    selectedRendererType: 'canvas',
+    rendererFallbackOccurred: false,
+    rendererFallbackReason: undefined,
+    readyAttempts: 0,
+    extraRenderPasses: 0,
+    blurRedraws: 0,
+    perFrame: new Map(),
     latencyCount: 0,
     latencyTotalMs: 0,
     latencyMinMs: Number.POSITIVE_INFINITY,
@@ -127,11 +134,26 @@ export class DeterministicMediaManager {
             ? this.#diagnostics.latencyTotalMs / this.#diagnostics.latencyCount
             : 0;
         const minLatency = this.#diagnostics.latencyCount > 0 ? this.#diagnostics.latencyMinMs : 0;
+        const perFrame = {};
+        for (const [frameIndex, counters] of [...this.#diagnostics.perFrame.entries()].sort(([a], [b]) => a - b)) {
+            perFrame[String(frameIndex)] = {
+                readyAttempts: counters.readyAttempts,
+                extraRenderPasses: counters.extraRenderPasses,
+                blurRedraws: counters.blurRedraws
+            };
+        }
         return {
             providerHits: this.#diagnostics.providerHits,
             providerMisses: this.#diagnostics.providerMisses,
             cacheHits: this.#diagnostics.cacheHits,
             cacheHitRatio,
+            selectedRendererType: this.#diagnostics.selectedRendererType,
+            rendererFallbackOccurred: this.#diagnostics.rendererFallbackOccurred,
+            rendererFallbackReason: this.#diagnostics.rendererFallbackReason,
+            readyAttempts: this.#diagnostics.readyAttempts,
+            extraRenderPasses: this.#diagnostics.extraRenderPasses,
+            blurRedraws: this.#diagnostics.blurRedraws,
+            perFrame,
             latency: {
                 minMs: minLatency,
                 maxMs: this.#diagnostics.latencyMaxMs,
@@ -139,6 +161,28 @@ export class DeterministicMediaManager {
             }
         };
     }
+    getSelectedRendererType() {
+        return this.#diagnostics.selectedRendererType;
+    }
+    recordRendererSelection(args) {
+        try {
+            this.#diagnostics.selectedRendererType = args.rendererType;
+            this.#diagnostics.rendererFallbackOccurred = Boolean(args.fallbackOccurred);
+            this.#diagnostics.rendererFallbackReason = args.fallbackReason;
+        }
+        catch {
+            // Diagnostics are best-effort and never allowed to fail the render path.
+        }
+    }
+    recordReadyAttempt(sceneFrameIndex, count = 1) {
+        this.#recordRuntimeCounter(sceneFrameIndex, 'readyAttempts', count);
+    }
+    recordExtraRenderPass(sceneFrameIndex, count = 1) {
+        this.#recordRuntimeCounter(sceneFrameIndex, 'extraRenderPasses', count);
+    }
+    recordBlurRedraw(sceneFrameIndex, count = 1) {
+        this.#recordRuntimeCounter(sceneFrameIndex, 'blurRedraws', count);
+    }
     async destroy() {
         for (const [cacheKey, cached] of this.#cacheByCacheKey.entries()) {
             this.#disposeCachedOverride(cacheKey, cached);
@@ -314,6 +358,27 @@ export class DeterministicMediaManager {
             // Diagnostics are best-effort and never allowed to fail the render path.
         }
     }
+    #recordRuntimeCounter(sceneFrameIndex, counter, count) {
+        if (!this.config.diagnostics) {
+            return;
+        }
+        if (!Number.isFinite(count) || count <= 0) {
+            return;
+        }
+        try {
+            this.#diagnostics[counter] += count;
+            const existing = this.#diagnostics.perFrame.get(sceneFrameIndex) ?? {
+                readyAttempts: 0,
+                extraRenderPasses: 0,
+                blurRedraws: 0
+            };
+            existing[counter] += count;
+            this.#diagnostics.perFrame.set(sceneFrameIndex, existing);
+        }
+        catch {
+            // Diagnostics are best-effort and never allowed to fail the render path.
+        }
+    }
     #countSceneMediaComponents(sceneData) {
         return sceneData.layers.reduce((count, layer) => {
             const mediaCount = layer.components.filter((component) => component.type === 'VIDEO' || component.type === 'GIF').length;

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

@@ -35,6 +35,10 @@ export type DeterministicMediaConfig = {
     strict: boolean;
     diagnostics: boolean;
     maxCachedTextures?: number;
+    seekMaxAttempts?: number;
+    loadingMaxAttempts?: number;
+    readyYieldMs?: number;
+    blurDownscale?: number;
     provider?: DeterministicFrameProvider;
 };
 export declare const DeterministicMediaConfigShape: z.ZodPrefault<z.ZodObject<{
@@ -42,6 +46,10 @@ export declare const DeterministicMediaConfigShape: z.ZodPrefault<z.ZodObject<{
     strict: z.ZodPrefault<z.ZodBoolean>;
     diagnostics: z.ZodPrefault<z.ZodBoolean>;
     maxCachedTextures: z.ZodOptional<z.ZodNumber>;
+    seekMaxAttempts: z.ZodPrefault<z.ZodNumber>;
+    loadingMaxAttempts: z.ZodPrefault<z.ZodNumber>;
+    readyYieldMs: z.ZodPrefault<z.ZodNumber>;
+    blurDownscale: z.ZodPrefault<z.ZodNumber>;
     provider: z.ZodOptional<z.ZodCustom<DeterministicFrameProvider, DeterministicFrameProvider>>;
 }, z.core.$strip>>;
 export declare const defaultDeterministicMediaConfig: DeterministicMediaConfig;
@@ -55,6 +63,17 @@ export type DeterministicDiagnosticsReport = {
     providerMisses: number;
     cacheHits: number;
     cacheHitRatio: number;
+    selectedRendererType: 'canvas' | 'webgl';
+    rendererFallbackOccurred: boolean;
+    rendererFallbackReason?: string;
+    readyAttempts: number;
+    extraRenderPasses: number;
+    blurRedraws: number;
+    perFrame: Record<string, {
+        readyAttempts: number;
+        extraRenderPasses: number;
+        blurRedraws: number;
+    }>;
     latency: {
         minMs: number;
         maxMs: number;

package/dist/schemas/runtime/deterministic.js

@@ -4,6 +4,10 @@ export const DeterministicMediaConfigShape = z.object({
     strict: z.boolean().prefault(false),
     diagnostics: z.boolean().prefault(false),
     maxCachedTextures: z.number().int().positive().optional(),
+    seekMaxAttempts: z.number().int().positive().prefault(4),
+    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()
 }).prefault({});
 export const defaultDeterministicMediaConfig = DeterministicMediaConfigShape.parse(undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visualfries",
-  "version": "0.1.10110",
+  "version": "0.1.10120",
   "license": "MIT",
   "author": "ContentFries",
   "repository": {
@@ -90,6 +90,7 @@
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "test": "pnpm run test:unit -- --run",
     "test:unit": "vitest",
+    "bench:deterministic": "pnpm vitest tests/perf/deterministic-server-render.perf.test.ts --run",
     "lint": "eslint . && prettier --check .",
     "format": "prettier --write .",
     "knip": "knip",