visualfries 0.1.10101 → 0.1.10110

package/dist/SceneBuilder.svelte.d.ts

@@ -8,7 +8,7 @@ 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 type { DeterministicFrameProvider, DeterministicMediaConfig, DeterministicDiagnosticsReport, FrameImageEncodingOptions, RenderFrameRangeOptions, RenderFrameRangeSummary } from './';
 import { MediaManager } from './managers/MediaManager.js';
 import { DeterministicMediaManager } from './managers/DeterministicMediaManager.js';
 import { LayersManager } from './managers/LayersManager.svelte.js';
@@ -5377,7 +5377,7 @@ export declare class SceneBuilder implements ISceneBuilder {
     getDeterministicFrameProvider(): DeterministicFrameProvider | null;
     getDeterministicMediaConfig(): DeterministicMediaConfig;
     getDiagnosticsReport(): DeterministicDiagnosticsReport | null;
-    seekAndRenderFrame(time: number, target?: PIXI.DisplayObject | PIXI.RenderTexture, format?: string, quality?: number): Promise<string | ArrayBuffer | Blob>;
+    seekAndRenderFrame(time: number, target?: PIXI.DisplayObject | PIXI.RenderTexture, format?: string, quality?: number, imageOptions?: FrameImageEncodingOptions): Promise<string | ArrayBuffer | Blob>;
     /**
      * Check if seeking to a specific time would result in visual changes
      * without actually extracting frame data.
@@ -5402,7 +5402,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>;
+    renderFrame(target?: PIXI.DisplayObject | PIXI.RenderTexture, format?: string, quality?: number, imageOptions?: FrameImageEncodingOptions): Promise<string | ArrayBuffer | Blob>;
     renderFrameRange(options: RenderFrameRangeOptions): Promise<RenderFrameRangeSummary>;
     log(message: string): void;
     play(changeState?: boolean): void;

package/dist/SceneBuilder.svelte.js

@@ -3,6 +3,7 @@ import { gsap } from 'gsap';
 import { ComponentShape } from './';
 import { buildCharactersListFromComponentsAndSubtitles, changeIdDeep } from './utils/utils.js';
 import { loadFonts } from './utils/document.js';
+import { discoverRequiredFontVariants } from './fonts/fontDiscovery.js';
 import { CommandType } from './commands/CommandTypes.js';
 import { CommandRunner } from './commands/CommandRunner.js';
 import { StateManager } from './managers/StateManager.svelte.js';
@@ -172,7 +173,8 @@ export class SceneBuilder {
         this.domManager.scale(clampedScale);
     }
     async loadFonts(fonts) {
-        return await loadFonts(fonts);
+        const variants = discoverRequiredFontVariants(this.sceneData, fonts);
+        return await loadFonts(fonts, variants);
     }
     async initialize() {
         if (this.initialized) {
@@ -183,9 +185,7 @@ export class SceneBuilder {
         this.renderTicker = () => {
             this.render();
         };
-        if (this.fonts.length > 0) {
-            await this.loadFonts(this.fonts);
-        }
+        await this.loadFonts(this.fonts);
         this.layersManager.setAppManager(this.appManager);
         await this.appManager.initialize();
         if (this.stateManager.scale !== 1) {
@@ -310,14 +310,14 @@ export class SceneBuilder {
     getDiagnosticsReport() {
         return this.deterministicMediaManager.getDiagnosticsReport();
     }
-    async seekAndRenderFrame(time, target, format = 'png', quality = 1) {
+    async seekAndRenderFrame(time, target, format = 'png', quality = 1, imageOptions) {
         await this.seek(time);
         // In server mode SeekCommand performs awaited render preparation.
         // Keep client render behavior unchanged.
         if (this.environment !== 'server') {
             this.render();
         }
-        const frame = await this.renderFrame(target, format, quality);
+        const frame = await this.renderFrame(target, format, quality, imageOptions);
         return frame;
     }
     /**
@@ -354,8 +354,14 @@ export class SceneBuilder {
         this.render();
         return wasDirty || this.stateManager.isDirty;
     }
-    async renderFrame(target, format = 'png', quality = 1) {
-        const frame = (await this.run(CommandType.RENDER_FRAME, { target, format, quality }));
+    async renderFrame(target, format = 'png', quality = 1, imageOptions) {
+        const frame = (await this.run(CommandType.RENDER_FRAME, {
+            target,
+            format,
+            quality,
+            imageFormat: imageOptions?.imageFormat,
+            imageQuality: imageOptions?.imageQuality
+        }));
         if (!frame) {
             throw new Error('Rendering frame failed');
         }
@@ -367,6 +373,10 @@ export class SceneBuilder {
         }
         const format = options.format ?? 'blob';
         const quality = options.quality ?? 1;
+        const imageOptions = {
+            imageFormat: options.imageFormat,
+            imageQuality: options.imageQuality
+        };
         const skipDuplicates = options.skipDuplicates ?? false;
         const fromFrame = Math.max(0, Math.floor(options.fromFrame));
         const toFrame = Math.max(fromFrame, Math.floor(options.toFrame));
@@ -374,6 +384,7 @@ export class SceneBuilder {
         let framesSkipped = 0;
         let aborted = false;
         let previousFrame = null;
+        let previousMimeType;
         for (let frameIndex = fromFrame; frameIndex < toFrame; frameIndex += 1) {
             if (options.signal?.aborted) {
                 aborted = true;
@@ -381,23 +392,35 @@ export class SceneBuilder {
             }
             let frame;
             let isDuplicate = false;
+            let mimeType;
             const frameTime = frameIndex / this.fps;
             if (skipDuplicates) {
                 const isDirty = await this.isSceneDirty(frameTime);
                 if (!isDirty && previousFrame) {
                     frame = previousFrame;
+                    mimeType = previousMimeType;
                     isDuplicate = true;
                     framesSkipped += 1;
                 }
                 else {
-                    frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality);
+                    frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality, imageOptions);
                     previousFrame = frame;
                 }
             }
             else {
-                frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality);
+                frame = await this.seekAndRenderFrame(frameTime, undefined, format, quality, imageOptions);
                 previousFrame = frame;
             }
+            if (!mimeType && frame instanceof Blob) {
+                mimeType = frame.type || undefined;
+            }
+            if (!mimeType && format === 'blob') {
+                const imageFormat = imageOptions.imageFormat ?? 'png';
+                mimeType = imageFormat === 'jpg' || imageFormat === 'jpeg' ? 'image/jpeg' : 'image/png';
+            }
+            if (!isDuplicate) {
+                previousMimeType = mimeType;
+            }
             let released = false;
             const release = () => {
                 if (released) {
@@ -409,6 +432,7 @@ export class SceneBuilder {
                 frameIndex,
                 frame,
                 isDuplicate,
+                mimeType,
                 release
             });
             release();

package/dist/commands/RenderFrameCommand.d.ts

@@ -17,5 +17,6 @@ export declare class RenderFrameCommand implements Command<string | ArrayBuffer
         appManager: AppManager;
         deterministicMediaManager?: DeterministicMediaManager;
     });
+    private resolveBlobMimeType;
     execute(args: unknown): Promise<string | ArrayBuffer | Blob | null>;
 }

package/dist/commands/RenderFrameCommand.js

@@ -3,10 +3,13 @@ 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),
-    target: z.any()
+import { RenderFrameEncodingError } from '../schemas/runtime/deterministic.js';
+const renderFrameSchema = z.object({
+    format: z.enum(['arraybuffer', 'blob', 'png', 'jpg', 'jpeg']).prefault('png'),
+    quality: z.number().min(0).max(1).prefault(1),
+    target: z.any().optional(),
+    imageFormat: z.enum(['png', 'jpg', 'jpeg']).optional(),
+    imageQuality: z.number().min(0).max(1).optional()
 });
 export class RenderFrameCommand {
     sceneState;
@@ -22,12 +25,21 @@ export class RenderFrameCommand {
         this.appManager = cradle.appManager;
         this.deterministicMediaManager = cradle.deterministicMediaManager;
     }
+    resolveBlobMimeType(imageFormat) {
+        if (!imageFormat) {
+            return undefined;
+        }
+        if (imageFormat === 'jpg' || imageFormat === 'jpeg') {
+            return 'image/jpeg';
+        }
+        return 'image/png';
+    }
     async execute(args) {
-        const check = replaceSourceOnTimeSchema.safeParse(args);
+        const check = renderFrameSchema.safeParse(args);
         if (!check.success) {
             return null;
         }
-        const { format, quality, target } = check.data;
+        const { format, quality, target, imageFormat, imageQuality } = 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) {
@@ -35,7 +47,9 @@ export class RenderFrameCommand {
                 // Check if render args match current args
                 const argsMatch = this.lastRenderArgs.format === format &&
                     this.lastRenderArgs.quality === quality &&
-                    this.lastRenderArgs.target === target;
+                    this.lastRenderArgs.target === target &&
+                    this.lastRenderArgs.imageFormat === imageFormat &&
+                    this.lastRenderArgs.imageQuality === imageQuality;
                 if (argsMatch && this.lastDeterministicFingerprint === currentDeterministicFingerprint) {
                     return this.lastRenderedFrame;
                 }
@@ -59,11 +73,17 @@ export class RenderFrameCommand {
             }));
         }
         if (format === 'blob') {
-            frame = (await new Promise((resolve) => {
+            const mimeType = this.resolveBlobMimeType(imageFormat);
+            const blobQuality = imageQuality ?? quality;
+            frame = (await new Promise((resolve, reject) => {
                 requestAnimationFrame(() => {
                     this.domManager.canvas.toBlob((blob) => {
+                        if (!blob) {
+                            reject(new RenderFrameEncodingError(`RenderFrameCommand: canvas.toBlob returned null for format="blob" (imageFormat="${imageFormat ?? 'default'}").`));
+                            return;
+                        }
                         resolve(blob);
-                    });
+                    }, mimeType, blobQuality);
                 });
             }));
         }
@@ -73,7 +93,7 @@ export class RenderFrameCommand {
                     ? (await new Promise((resolve) => {
                         requestAnimationFrame(() => {
                             const frame = format === 'jpg' || format === 'jpeg'
-                                ? this.domManager.canvas.toDataURL('image/jpeg', quality)
+                                ? this.domManager.canvas.toDataURL('image/jpeg', imageQuality ?? quality)
                                 : this.domManager.canvas.toDataURL();
                             resolve(frame);
                         });
@@ -90,7 +110,7 @@ export class RenderFrameCommand {
         // Cache frame and render args, then clear dirty flag after successful render
         if (this.sceneState.environment === 'server') {
             this.lastRenderedFrame = frame;
-            this.lastRenderArgs = { format, quality, target };
+            this.lastRenderArgs = { format, quality, target, imageFormat, imageQuality };
             this.lastDeterministicFingerprint = currentDeterministicFingerprint;
             this.sceneState.clearDirty();
         }

package/dist/fonts/fontDiscovery.d.ts

@@ -0,0 +1,9 @@
+import type { FontType, Scene } from '..';
+export type FontVariantDescriptor = {
+    family: string;
+    weight: number;
+    source: 'google' | 'custom';
+    fileUrl?: string;
+};
+export declare const extractConfiguredFontVariants: (configuredFonts?: FontType[]) => FontVariantDescriptor[];
+export declare const discoverRequiredFontVariants: (sceneData: Scene, configuredFonts?: FontType[]) => FontVariantDescriptor[];

package/dist/fonts/fontDiscovery.js

@@ -0,0 +1,202 @@
+const NAMED_WEIGHTS = {
+    normal: 400,
+    regular: 400,
+    italic: 400,
+    bold: 700,
+    bolder: 700,
+    lighter: 300
+};
+const DEFAULT_WEIGHT = 400;
+const normalizeFamily = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim().replace(/^['"]|['"]$/g, '');
+    return trimmed.length > 0 ? trimmed : null;
+};
+const normalizeWeight = (value) => {
+    if (typeof value === 'number' && value >= 100 && value <= 900) {
+        return Math.round(value / 100) * 100;
+    }
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    if (NAMED_WEIGHTS[normalized] !== undefined) {
+        return NAMED_WEIGHTS[normalized];
+    }
+    const directNumeric = Number.parseInt(normalized, 10);
+    if (!Number.isNaN(directNumeric) && directNumeric >= 100 && directNumeric <= 900) {
+        return Math.round(directNumeric / 100) * 100;
+    }
+    const embeddedWeightMatch = normalized.match(/([1-9]00)/);
+    if (embeddedWeightMatch?.[1]) {
+        return Number.parseInt(embeddedWeightMatch[1], 10);
+    }
+    return null;
+};
+const parseWeightsFromVariants = (variants) => {
+    if (!Array.isArray(variants)) {
+        return [];
+    }
+    const weights = new Set();
+    for (const variant of variants) {
+        const normalizedWeight = normalizeWeight(variant);
+        if (normalizedWeight !== null) {
+            weights.add(normalizedWeight);
+        }
+    }
+    return [...weights];
+};
+const parseConfiguredFamilyDescriptor = (value, fallbackFamily) => {
+    const [familyPart, variantPart] = value.split(':', 2);
+    const family = normalizeFamily(familyPart) ?? normalizeFamily(fallbackFamily) ?? fallbackFamily;
+    const weights = new Set();
+    if (variantPart) {
+        const numericMatches = variantPart.matchAll(/([1-9]00)/g);
+        for (const match of numericMatches) {
+            const parsed = Number.parseInt(match[1], 10);
+            if (!Number.isNaN(parsed)) {
+                weights.add(parsed);
+            }
+        }
+        if (weights.size === 0) {
+            for (const token of variantPart.split(/[;,]/)) {
+                const parsed = normalizeWeight(token);
+                if (parsed !== null) {
+                    weights.add(parsed);
+                }
+            }
+        }
+    }
+    if (weights.size === 0) {
+        weights.add(DEFAULT_WEIGHT);
+    }
+    return {
+        family,
+        weights: [...weights]
+    };
+};
+const parseConfiguredFonts = (configuredFonts) => {
+    const parsedFonts = [];
+    for (const configuredFont of configuredFonts) {
+        const alias = normalizeFamily(configuredFont.alias);
+        const fallbackFamily = alias ?? 'Unnamed Font';
+        const configuredFamilyDescriptor = configuredFont.data?.family ?? fallbackFamily;
+        const parsedFamilyDescriptor = parseConfiguredFamilyDescriptor(configuredFamilyDescriptor, fallbackFamily);
+        const fileUrl = normalizeFamily(configuredFont.src ?? configuredFont.url);
+        parsedFonts.push({
+            family: parsedFamilyDescriptor.family,
+            source: configuredFont.source,
+            fileUrl: fileUrl ?? undefined,
+            weights: parsedFamilyDescriptor.weights,
+            aliases: alias ? [alias] : []
+        });
+    }
+    return parsedFonts;
+};
+const createConfiguredLookup = (configuredFonts) => {
+    const lookup = new Map();
+    for (const configuredFont of configuredFonts) {
+        const keys = [configuredFont.family, ...configuredFont.aliases];
+        for (const key of keys) {
+            lookup.set(key.toLowerCase(), configuredFont);
+        }
+    }
+    return lookup;
+};
+const upsertVariant = (variants, variant) => {
+    const key = `${variant.family.toLowerCase()}::${variant.weight}`;
+    const existing = variants.get(key);
+    if (!existing) {
+        variants.set(key, variant);
+        return;
+    }
+    // Prefer custom source when available and preserve fileUrl if provided by any input.
+    if (existing.source !== 'custom' && variant.source === 'custom') {
+        existing.source = 'custom';
+    }
+    if (!existing.fileUrl && variant.fileUrl) {
+        existing.fileUrl = variant.fileUrl;
+    }
+};
+const collectComponentTextVariants = (component, configuredLookup, output) => {
+    const textAppearance = component?.appearance?.text;
+    if (!textAppearance) {
+        return;
+    }
+    const family = normalizeFamily(textAppearance.fontFamily) ?? normalizeFamily(textAppearance.fontSource?.family);
+    if (!family) {
+        return;
+    }
+    const configMatch = configuredLookup.get(family.toLowerCase());
+    const source = (textAppearance.fontSource?.source ?? configMatch?.source ?? 'google');
+    const fileUrl = normalizeFamily(textAppearance.fontSource?.fileUrl) ?? configMatch?.fileUrl ?? undefined;
+    const weights = new Set();
+    const styleWeights = [
+        textAppearance.fontWeight,
+        textAppearance.activeWord?.fontWeight,
+        textAppearance.activeLine?.fontWeight
+    ];
+    for (const styleWeight of styleWeights) {
+        const parsed = normalizeWeight(styleWeight);
+        if (parsed !== null) {
+            weights.add(parsed);
+        }
+    }
+    for (const variantWeight of parseWeightsFromVariants(textAppearance.fontSource?.variants)) {
+        weights.add(variantWeight);
+    }
+    if (weights.size === 0 && configMatch?.weights?.length) {
+        for (const configuredWeight of configMatch.weights) {
+            weights.add(configuredWeight);
+        }
+    }
+    if (weights.size === 0) {
+        weights.add(DEFAULT_WEIGHT);
+    }
+    for (const weight of weights) {
+        upsertVariant(output, {
+            family,
+            weight,
+            source,
+            fileUrl
+        });
+    }
+};
+export const extractConfiguredFontVariants = (configuredFonts = []) => {
+    const variants = new Map();
+    const parsedFonts = parseConfiguredFonts(configuredFonts);
+    for (const parsedFont of parsedFonts) {
+        for (const weight of parsedFont.weights) {
+            upsertVariant(variants, {
+                family: parsedFont.family,
+                weight,
+                source: parsedFont.source,
+                fileUrl: parsedFont.fileUrl
+            });
+        }
+    }
+    return [...variants.values()];
+};
+export const discoverRequiredFontVariants = (sceneData, configuredFonts = []) => {
+    const variants = new Map();
+    const parsedConfiguredFonts = parseConfiguredFonts(configuredFonts);
+    const configuredLookup = createConfiguredLookup(parsedConfiguredFonts);
+    for (const layer of sceneData.layers ?? []) {
+        for (const component of layer.components ?? []) {
+            if (component.type !== 'TEXT' && component.type !== 'SUBTITLES') {
+                continue;
+            }
+            collectComponentTextVariants(component, configuredLookup, variants);
+        }
+    }
+    // Preserve backwards compatibility with caller-supplied fonts by including explicit config entries.
+    for (const configuredVariant of extractConfiguredFontVariants(configuredFonts)) {
+        upsertVariant(variants, configuredVariant);
+    }
+    return [...variants.values()];
+};

package/dist/layers/Layer.svelte.d.ts

@@ -18,6 +18,7 @@ export declare class Layer implements ILayer {
     });
     build(): Promise<void>;
     addComponent(component: IComponent): void;
+    syncDisplayObjects(): boolean;
     removeComponent(component: IComponent): void;
     update(props: Partial<SceneLayerInput>): void;
     setOrder(order: number): void;

package/dist/layers/Layer.svelte.js

@@ -52,6 +52,36 @@ export class Layer {
         this.components.sort((a, b) => a.props.timeline.startAt - b.props.timeline.startAt);
         this.#emit('layerschange');
     }
+    syncDisplayObjects() {
+        let changed = false;
+        if (!this.#displayObject) {
+            return false;
+        }
+        for (let index = 0; index < this.components.length; index += 1) {
+            const component = this.components[index];
+            const displayObject = component.displayObject;
+            if (!displayObject) {
+                continue;
+            }
+            const parent = displayObject.parent;
+            if (parent !== this.#displayObject) {
+                if (parent && typeof parent.removeChild === 'function') {
+                    parent.removeChild(displayObject);
+                }
+                this.#displayObject.addChild(displayObject);
+                changed = true;
+            }
+            if (typeof this.#displayObject.getChildIndex === 'function' &&
+                typeof this.#displayObject.setChildIndex === 'function') {
+                const currentIndex = this.#displayObject.getChildIndex(displayObject);
+                if (currentIndex !== index) {
+                    this.#displayObject.setChildIndex(displayObject, index);
+                    changed = true;
+                }
+            }
+        }
+        return changed;
+    }
     removeComponent(component) {
         const hasComponent = this.components.find((c) => c.id === component.id);
         if (hasComponent) {

package/dist/managers/RenderManager.d.ts

@@ -3,11 +3,14 @@ import { EventManager } from './EventManager.js';
 import type { ResourceManager, IComponent, ComponentData } from '..';
 import type { AppearanceInput } from '..';
 import { AppManager } from './AppManager.svelte.js';
+import { LayersManager } from './LayersManager.svelte.js';
 export declare class RenderManager {
+    #private;
     private state;
     private componentsManager;
     private eventManager;
     private appManager;
+    private layersManager;
     private lastActiveById;
     private lastRenderTime;
     constructor(cradle: {
@@ -15,6 +18,7 @@ export declare class RenderManager {
         componentsManager: ResourceManager<IComponent, ComponentData, AppearanceInput>;
         eventManager: EventManager;
         appManager: AppManager;
+        layersManager: LayersManager;
     });
     private initializeEventListeners;
     private handleBeforeRender;

package/dist/managers/RenderManager.js

@@ -1,11 +1,13 @@
 import { StateManager } from './StateManager.svelte.js';
 import { EventManager } from './EventManager.js';
 import { AppManager } from './AppManager.svelte.js';
+import { LayersManager } from './LayersManager.svelte.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
     lastActiveById = new Map();
     lastRenderTime = -1;
@@ -14,6 +16,7 @@ export class RenderManager {
         this.componentsManager = cradle.componentsManager;
         this.eventManager = cradle.eventManager;
         this.appManager = cradle.appManager;
+        this.layersManager = cradle.layersManager;
         this.initializeEventListeners();
     }
     initializeEventListeners() {
@@ -27,6 +30,18 @@ export class RenderManager {
         });
     }
     async handleBeforeRender() { }
+    #syncLayerDisplayObjects() {
+        const layers = this.layersManager.getAll();
+        let changed = false;
+        for (const layer of layers) {
+            if (layer.syncDisplayObjects()) {
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.state.markDirty();
+        }
+    }
     async render() {
         const components = this.componentsManager.getAll();
         const currentTime = this.state.currentTime;
@@ -47,6 +62,7 @@ export class RenderManager {
         for (const e of entries) {
             this.lastActiveById.set(e.component.id, e.shouldBeVisible);
         }
+        this.#syncLayerDisplayObjects();
         this.appManager.render();
         this.lastRenderTime = currentTime;
     }

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

@@ -65,13 +65,21 @@ export type RenderFrameRangeItem = {
     frameIndex: number;
     frame: string | ArrayBuffer | Blob;
     isDuplicate: boolean;
+    mimeType?: string;
     release: () => void;
 };
+export type FrameImageFormat = 'jpg' | 'jpeg' | 'png';
+export type FrameImageEncodingOptions = {
+    imageFormat?: FrameImageFormat;
+    imageQuality?: number;
+};
 export type RenderFrameRangeOptions = {
     fromFrame: number;
     toFrame: number;
     format?: 'arraybuffer' | 'blob' | 'png' | 'jpg' | 'jpeg';
     quality?: number;
+    imageFormat?: FrameImageFormat;
+    imageQuality?: number;
     skipDuplicates?: boolean;
     signal?: AbortSignal;
     onFrame: (item: RenderFrameRangeItem) => Promise<void> | void;
@@ -92,3 +100,6 @@ export declare class DeterministicRenderError extends Error {
         sceneTime: number;
     });
 }
+export declare class RenderFrameEncodingError extends Error {
+    constructor(message: string);
+}

package/dist/schemas/runtime/deterministic.js

@@ -19,3 +19,9 @@ export class DeterministicRenderError extends Error {
         this.sceneTime = props.sceneTime;
     }
 }
+export class RenderFrameEncodingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RenderFrameEncodingError';
+    }
+}

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

@@ -1,5 +1,5 @@
 export type { BuilderState, StateEvents, TimelineEvents, RenderEvents, PlaybackEvents, LayerEvents, ComponentEvents, SubtitlesEvents, EventMap, EventType, EventPayload, ComponentRefreshType, HookType, SceneLayerComponentType, SplitScreenChunk, SplitScreen, } from './types.js';
 export type { MediaComponent, ResourceManager, ComponentData, ComponentProps, PixiComponent, ResourceTypes, HookHandler, HookHandlers, } from './types.js';
-export { DeterministicMediaConfigShape, defaultDeterministicMediaConfig, DeterministicRenderError } from './deterministic.js';
-export type { DeterministicMediaConfig, DeterministicFrameRequest, DeterministicFramePayload, DeterministicFrameProvider, DeterministicFrameOverride, DeterministicDiagnosticsReport, RenderFrameRangeOptions, RenderFrameRangeItem, RenderFrameRangeSummary } from './deterministic.js';
+export { DeterministicMediaConfigShape, defaultDeterministicMediaConfig, DeterministicRenderError, RenderFrameEncodingError } from './deterministic.js';
+export type { DeterministicMediaConfig, DeterministicFrameRequest, DeterministicFramePayload, DeterministicFrameProvider, DeterministicFrameOverride, DeterministicDiagnosticsReport, FrameImageFormat, FrameImageEncodingOptions, RenderFrameRangeOptions, RenderFrameRangeItem, RenderFrameRangeSummary } from './deterministic.js';
 export type { Component as IComponent, Layer as ILayer, SceneBuilder as ISceneBuilder, ComponentContext as IComponentContext, ComponentBuilder as IComponentBuilder, StateManager as IStateManager, ComponentHook as IComponentHook, ComponentBuildStrategy as IComponentBuildStrategy, } from './types.js';

package/dist/schemas/runtime/index.js

@@ -1,4 +1,4 @@
 // Runtime types for the SceneBuilder application
 // These represent runtime interfaces for class instances
 // They are prefixed with "I" to distinguish from data schemas
-export { DeterministicMediaConfigShape, defaultDeterministicMediaConfig, DeterministicRenderError } from './deterministic.js';
+export { DeterministicMediaConfigShape, defaultDeterministicMediaConfig, DeterministicRenderError, RenderFrameEncodingError } from './deterministic.js';

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

@@ -5,7 +5,7 @@ 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 { Component as SceneLayerComponent, ComponentBase, AppearanceInput, Scene, RenderEnvironment, ComponentInput, SceneLayerInput, SceneLayer, VideoComponentShape, ImageComponentShape, GifComponentShape, Subtitle } from '../..';
-import type { DeterministicMediaConfig, DeterministicFrameProvider, DeterministicDiagnosticsReport, RenderFrameRangeOptions, RenderFrameRangeSummary } from './deterministic.js';
+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"];
 export type SceneLayerComponentType = (typeof SCENE_LAYER_COMPONENT_TYPE)[number];
 type MediaShape = z.infer<typeof VideoComponentShape>;
@@ -177,6 +177,7 @@ export interface Layer {
     update(layerData: Partial<SceneLayerInput>): void;
     addComponent(component: Component): void;
     removeComponent(component: Component): void;
+    syncDisplayObjects(): boolean;
     build(): Promise<void>;
     setOrder(order: number): void;
     getData(): SceneLayer;
@@ -263,10 +264,10 @@ export interface SceneBuilder {
     getDeterministicFrameProvider(): DeterministicFrameProvider | null;
     getDeterministicMediaConfig(): DeterministicMediaConfig;
     getDiagnosticsReport(): DeterministicDiagnosticsReport | null;
-    seekAndRenderFrame(time: number, target?: DisplayObject | RenderTexture, format?: string, quality?: number): Promise<string | ArrayBuffer | Blob>;
+    seekAndRenderFrame(time: number, target?: DisplayObject | RenderTexture, format?: string, quality?: number, imageOptions?: FrameImageEncodingOptions): Promise<string | ArrayBuffer | Blob>;
     renderFrameRange(options: RenderFrameRangeOptions): Promise<RenderFrameRangeSummary>;
     isSceneDirty(time: number): Promise<boolean>;
-    renderFrame(target?: DisplayObject | RenderTexture, format?: string, quality?: number): Promise<string | ArrayBuffer | Blob>;
+    renderFrame(target?: DisplayObject | RenderTexture, format?: string, quality?: number, imageOptions?: FrameImageEncodingOptions): Promise<string | ArrayBuffer | Blob>;
     log(message: string): void;
     play(changeState?: boolean): void;
     pause(changeState?: boolean): void;

package/dist/utils/document.d.ts

@@ -1,2 +1,3 @@
 import type { FontType } from '..';
-export declare const loadFonts: (fonts: FontType[]) => Promise<void>;
+import type { FontVariantDescriptor } from '../fonts/fontDiscovery.js';
+export declare const loadFonts: (fonts: FontType[], variants?: FontVariantDescriptor[]) => Promise<void>;

package/dist/utils/document.js

@@ -1,36 +1,125 @@
+import { extractConfiguredFontVariants } from '../fonts/fontDiscovery.js';
+const FONT_PROBE_TEXT = 'BESbswy';
+const FONT_PROBE_SIZE = '60px';
+const customFaceRegistry = new Set();
+const isFontApiAvailable = () => typeof document !== 'undefined' &&
+    typeof document.fonts !== 'undefined' &&
+    typeof document.createElement === 'function';
+const loadStylesheet = async (href) => {
+    await new Promise((resolve) => {
+        const link = document.createElement('link');
+        link.href = href;
+        link.rel = 'stylesheet';
+        link.onload = () => resolve();
+        link.onerror = () => {
+            console.warn(`Failed to load font stylesheet: ${href}`);
+            resolve();
+        };
+        document.head.appendChild(link);
+    });
+};
+const groupByFamily = (variants) => {
+    const grouped = new Map();
+    for (const variant of variants) {
+        if (!grouped.has(variant.family)) {
+            grouped.set(variant.family, new Set());
+        }
+        grouped.get(variant.family).add(variant.weight);
+    }
+    return grouped;
+};
+const buildGoogleCss2Url = (variants) => {
+    if (!variants.length) {
+        return null;
+    }
+    const groupedFamilies = groupByFamily(variants);
+    const familyQueryParts = [];
+    for (const [family, weights] of groupedFamilies.entries()) {
+        const encodedFamily = encodeURIComponent(family).replace(/%20/g, '+');
+        const sortedWeights = [...weights].sort((a, b) => a - b);
+        const familyPart = sortedWeights.length
+            ? `family=${encodedFamily}:wght@${sortedWeights.join(';')}`
+            : `family=${encodedFamily}`;
+        familyQueryParts.push(familyPart);
+    }
+    if (!familyQueryParts.length) {
+        return null;
+    }
+    return `https://fonts.googleapis.com/css2?${familyQueryParts.join('&')}&display=swap`;
+};
+const registerCustomFontFaces = async (variants) => {
+    const customVariants = variants.filter((variant) => variant.source === 'custom');
+    if (!customVariants.length) {
+        return;
+    }
+    const hasFontFaceApi = typeof FontFace !== 'undefined';
+    for (const variant of customVariants) {
+        if (!variant.fileUrl) {
+            console.warn(`Custom font "${variant.family}" (weight ${variant.weight}) is missing fileUrl/src and cannot be preloaded.`);
+            continue;
+        }
+        if (!hasFontFaceApi) {
+            console.warn(`FontFace API is unavailable. Skipping custom font preload for "${variant.family}" (${variant.weight}).`);
+            continue;
+        }
+        const registryKey = `${variant.family}::${variant.weight}::${variant.fileUrl}`;
+        if (customFaceRegistry.has(registryKey)) {
+            continue;
+        }
+        try {
+            const face = new FontFace(variant.family, `url("${variant.fileUrl}")`, {
+                weight: String(variant.weight),
+                style: 'normal'
+            });
+            await face.load();
+            document.fonts.add(face);
+            customFaceRegistry.add(registryKey);
+        }
+        catch (error) {
+            console.warn(`Failed to preload custom font "${variant.family}" (${variant.weight}) from ${variant.fileUrl}.`, error);
+        }
+    }
+};
+const loadDescriptors = async (variants) => {
+    const descriptorPromises = variants.map(async (variant) => {
+        const descriptor = `${variant.weight} ${FONT_PROBE_SIZE} "${variant.family}"`;
+        try {
+            const loadedFaces = await document.fonts.load(descriptor, FONT_PROBE_TEXT);
+            if (!loadedFaces.length) {
+                console.warn(`Font descriptor did not resolve any faces: ${descriptor}`);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to load font descriptor: ${descriptor}`, error);
+        }
+    });
+    await Promise.all(descriptorPromises);
+};
 async function waitForAllFonts() {
-    // Guard clause for server-side rendering or non-browser environments
-    if (typeof document === 'undefined' || !document.fonts) {
+    if (!isFontApiAvailable()) {
         return;
     }
     try {
         await document.fonts.ready;
     }
     catch (error) {
-        console.warn('One or more fonts failed to load.', error);
+        console.warn('One or more fonts failed to reach ready state.', error);
     }
 }
-export const loadFonts = async function (fonts) {
-    // const results = await PIXI.Assets.load(fonts);
-    const googleFonts = fonts.reduce((acc, font) => {
-        if (font.source == 'google' && font.data) {
-            acc.push(font.data.family);
-        }
-        return acc;
-    }, []);
-    if (document && googleFonts.length > 0 && typeof document !== 'undefined') {
-        const fontPromises = googleFonts.map((font) => new Promise((resolve) => {
-            const link = document.createElement('link');
-            link.href = `https://fonts.googleapis.com/css?family=${encodeURIComponent(font)}`;
-            link.rel = 'stylesheet';
-            link.onload = () => resolve(true);
-            link.onerror = () => {
-                console.warn(`Failed to load font: ${font}`);
-                resolve(false);
-            };
-            document.head.appendChild(link);
-        }));
-        await Promise.all(fontPromises);
+export const loadFonts = async function (fonts, variants) {
+    if (!isFontApiAvailable()) {
+        return;
+    }
+    const resolvedVariants = variants && variants.length ? variants : extractConfiguredFontVariants(fonts);
+    if (!resolvedVariants.length) {
+        return;
+    }
+    const googleVariants = resolvedVariants.filter((variant) => variant.source === 'google');
+    const googleCss2Url = buildGoogleCss2Url(googleVariants);
+    if (googleCss2Url) {
+        await loadStylesheet(googleCss2Url);
     }
+    await registerCustomFontFaces(resolvedVariants);
+    await loadDescriptors(resolvedVariants);
     await waitForAllFonts();
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visualfries",
-  "version": "0.1.10101",
+  "version": "0.1.10110",
   "license": "MIT",
   "author": "ContentFries",
   "repository": {