visualfries 0.1.0

package/dist/composers/componentComposer.d.ts

@@ -0,0 +1,55 @@
+import { type Component, type ComponentInput, type AnimationInput, type AppearanceInput } from '..';
+import type { ComponentEffect, ComponentSourceInput } from '..';
+/**
+ * A fluent composer for a single Component object.
+ */
+declare class ComponentComposer {
+    private readonly _component;
+    constructor(id: string, type: ComponentInput['type'], timeline: ComponentInput['timeline']);
+    /**
+     * Deeply merges new appearance settings into the existing ones using lodash.
+     * Allows for updating nested properties like `text.color` without overwriting the whole `text` object.
+     * @param appearance A partial object of appearance settings to merge.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    setAppearance(appearance: Partial<AppearanceInput>): this;
+    setText(text: string): this;
+    setSource(source: Partial<ComponentSourceInput>): this;
+    /**
+     * Adds an animation to the component's animation list.
+     * @param animation The animation object to add.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    addAnimation(animation: AnimationInput): this;
+    /**
+     * Adds an effect to the component's effects map.
+     * @param key A unique key for the effect (e.g., "mainBlur", "layoutSplit").
+     * @param effect The effect object.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    addEffect(key: string, effect: ComponentEffect): this;
+    /**
+     * Sets extra properties on the component (e.g., `text`, `source`, `shape`).
+     * @param props A partial object of component properties to merge.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    setProps(props: Partial<ComponentInput>): this;
+    setName(name: string): this;
+    setOrder(order: number): this;
+    setVisible(visible: boolean): this;
+    /**
+     * Validates and finalizes the component object.
+     * @returns A fully formed and validated Component object.
+     */
+    compose(): Component;
+    safeCompose(): Component | undefined;
+}
+/**
+ * Factory function to create a new ComponentComposer.
+ * @param id The component's unique ID.
+ * @param type The component's type (e.g., 'TEXT', 'IMAGE').
+ * @param timeline The component's timeline.
+ * @returns A new instance of ComponentComposer.
+ */
+export declare function createComponentComposer(id: string, type: ComponentInput['type'], timeline: ComponentInput['timeline']): ComponentComposer;
+export {};

package/dist/composers/componentComposer.js

@@ -0,0 +1,118 @@
+import { merge } from 'lodash-es';
+import { ComponentShape } from '..';
+/**
+ * A fluent composer for a single Component object.
+ */
+class ComponentComposer {
+    _component;
+    constructor(id, type, timeline) {
+        this._component = {
+            id,
+            type,
+            timeline,
+            name: type.charAt(0).toUpperCase() + type.slice(1).toLowerCase(),
+            // Appearance is initialized as an empty object and built up
+            appearance: {}
+        };
+    }
+    /**
+     * Deeply merges new appearance settings into the existing ones using lodash.
+     * Allows for updating nested properties like `text.color` without overwriting the whole `text` object.
+     * @param appearance A partial object of appearance settings to merge.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    setAppearance(appearance) {
+        // Use lodash's merge for a robust deep merge.
+        // It mutates the first argument, which is exactly what we want here.
+        merge(this._component.appearance, appearance);
+        return this;
+    }
+    setText(text) {
+        if (this._component.type === 'TEXT') {
+            this._component.text = text;
+        }
+        return this;
+    }
+    setSource(source) {
+        if (this._component.type === 'IMAGE' ||
+            this._component.type === 'GIF' ||
+            this._component.type === 'VIDEO' ||
+            this._component.type === 'SUBTITLES') {
+            this._component.source = source;
+        }
+        return this;
+    }
+    /**
+     * Adds an animation to the component's animation list.
+     * @param animation The animation object to add.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    addAnimation(animation) {
+        if (!this._component.animations)
+            this._component.animations = { enabled: true, list: [] };
+        if (!this._component.animations.list)
+            this._component.animations.list = [];
+        this._component.animations.list.push(animation);
+        return this;
+    }
+    /**
+     * Adds an effect to the component's effects map.
+     * @param key A unique key for the effect (e.g., "mainBlur", "layoutSplit").
+     * @param effect The effect object.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    addEffect(key, effect) {
+        if (!this._component.effects)
+            this._component.effects = { enabled: true, map: {} };
+        if (!this._component.effects.map)
+            this._component.effects.map = {};
+        this._component.effects.map[key] = effect;
+        return this;
+    }
+    /**
+     * Sets extra properties on the component (e.g., `text`, `source`, `shape`).
+     * @param props A partial object of component properties to merge.
+     * @returns The ComponentComposer instance for further chaining.
+     */
+    setProps(props) {
+        Object.assign(this._component, props);
+        return this;
+    }
+    setName(name) {
+        this._component.name = name;
+        return this;
+    }
+    setOrder(order) {
+        this._component.order = order;
+        return this;
+    }
+    setVisible(visible) {
+        this._component.visible = visible;
+        return this;
+    }
+    /**
+     * Validates and finalizes the component object.
+     * @returns A fully formed and validated Component object.
+     */
+    compose() {
+        return ComponentShape.parse(this._component);
+    }
+    safeCompose() {
+        const resp = ComponentShape.safeParse(this._component);
+        if (!resp.success) {
+            console.error('Invalid component input:', resp.error.format());
+            return undefined;
+        }
+        return resp.data;
+    }
+}
+/**
+ * Factory function to create a new ComponentComposer.
+ * @param id The component's unique ID.
+ * @param type The component's type (e.g., 'TEXT', 'IMAGE').
+ * @param timeline The component's timeline.
+ * @returns A new instance of ComponentComposer.
+ */
+export function createComponentComposer(id, type, timeline) {
+    return new ComponentComposer(id, type, timeline);
+}

package/dist/composers/layerComposer.d.ts

@@ -0,0 +1,46 @@
+import { type SceneLayer, type Component } from '..';
+/**
+ * A fluent composer for a single SceneLayer object.
+ */
+declare class LayerComposer {
+    private readonly _layer;
+    constructor(id: string);
+    /**
+     * Adds a pre-composed component to the layer.
+     * @param component The final component object, typically from `componentComposer.compose()`.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    addComponent(component: Component): this;
+    /**
+     * Sets the visibility of the layer.
+     * @param isVisible Whether the layer should be visible.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setVisible(isVisible: boolean): this;
+    /**
+     * Sets the stacking order of the layer. Higher numbers are on top.
+     * @param order The numerical order.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setOrder(order: number): this;
+    /**
+     * Sets the name of the layer.
+     * @param name The desired name.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setName(name: string): this;
+    setMuted(muted: boolean): this;
+    /**
+     * Validates and finalizes the layer object.
+     * @returns A fully formed and validated SceneLayer object.
+     */
+    compose(): SceneLayer;
+    safeCompose(): SceneLayer | undefined;
+}
+/**
+ * Factory function to create a new LayerComposer.
+ * @param id The layer's unique ID.
+ * @returns A new instance of LayerComposer.
+ */
+export declare function createLayerComposer(id: string): LayerComposer;
+export {};

package/dist/composers/layerComposer.js

@@ -0,0 +1,79 @@
+import { SceneLayerShape } from '..'; // Adjust path as needed
+/**
+ * A fluent composer for a single SceneLayer object.
+ */
+class LayerComposer {
+    _layer;
+    constructor(id) {
+        this._layer = {
+            id,
+            components: []
+        };
+    }
+    /**
+     * Adds a pre-composed component to the layer.
+     * @param component The final component object, typically from `componentComposer.compose()`.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    addComponent(component) {
+        if (!this._layer.components) {
+            this._layer.components = [];
+        }
+        this._layer.components.push(component);
+        return this;
+    }
+    /**
+     * Sets the visibility of the layer.
+     * @param isVisible Whether the layer should be visible.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setVisible(isVisible) {
+        this._layer.visible = isVisible;
+        return this;
+    }
+    /**
+     * Sets the stacking order of the layer. Higher numbers are on top.
+     * @param order The numerical order.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setOrder(order) {
+        this._layer.order = order;
+        return this;
+    }
+    /**
+     * Sets the name of the layer.
+     * @param name The desired name.
+     * @returns The LayerComposer instance for further chaining.
+     */
+    setName(name) {
+        this._layer.name = name;
+        return this;
+    }
+    setMuted(muted) {
+        this._layer.muted = muted;
+        return this;
+    }
+    /**
+     * Validates and finalizes the layer object.
+     * @returns A fully formed and validated SceneLayer object.
+     */
+    compose() {
+        return SceneLayerShape.parse(this._layer);
+    }
+    safeCompose() {
+        const resp = SceneLayerShape.safeParse(this._layer);
+        if (!resp.success) {
+            console.error('Invalid layer input:', resp.error.format());
+            return undefined;
+        }
+        return resp.data;
+    }
+}
+/**
+ * Factory function to create a new LayerComposer.
+ * @param id The layer's unique ID.
+ * @returns A new instance of LayerComposer.
+ */
+export function createLayerComposer(id) {
+    return new LayerComposer(id);
+}

package/dist/composers/sceneComposer.d.ts

@@ -0,0 +1,48 @@
+import { type Scene, type SceneSettingsInput, type SceneLayer, type SceneAssetInput, type AudioTrackInput, type SceneSubtitlesSettings } from '..';
+/**
+ * A fluent, composable builder for creating a valid Scene object.
+ */
+declare class SceneComposer {
+    private _scene;
+    constructor(id: string, settings: SceneSettingsInput);
+    /**
+     * Merges new settings into the existing scene settings.
+     * @param settings A partial object of scene settings to update.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    setSettings(settings: Partial<SceneSettingsInput>): this;
+    setName(name: string): this;
+    setSubtitles(subtitles: SceneSubtitlesSettings): this;
+    /**
+     * Adds a pre-composed layer to the scene.
+     * @param layer The final layer object, from `layerComposer.compose()`.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addLayer(layer: SceneLayer): this;
+    /**
+     * Adds an asset to the scene's asset registry.
+     * @param asset The asset object to add.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addAsset(asset: SceneAssetInput): this;
+    /**
+     * Adds a global audio track to the scene.
+     * @param audioTrack The audio track object to add.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addAudioTrack(audioTrack: AudioTrackInput): this;
+    /**
+     * Validates and finalizes the entire scene object.
+     * @returns A fully formed and validated Scene object.
+     */
+    compose(): Scene;
+    safeCompose(): Scene | undefined;
+}
+/**
+ * Factory function to create a new SceneComposer.
+ * @param id The scene's unique ID.
+ * @param settings The initial scene settings.
+ * @returns A new instance of SceneComposer.
+ */
+export declare function createSceneComposer(id: string, settings: SceneSettingsInput): SceneComposer;
+export {};

package/dist/composers/sceneComposer.js

@@ -0,0 +1,92 @@
+import { SceneShape } from '..'; // Adjust path as needed
+/**
+ * A fluent, composable builder for creating a valid Scene object.
+ */
+class SceneComposer {
+    _scene;
+    constructor(id, settings) {
+        this._scene = {
+            id,
+            settings,
+            layers: [],
+        };
+    }
+    /**
+     * Merges new settings into the existing scene settings.
+     * @param settings A partial object of scene settings to update.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    setSettings(settings) {
+        // Perform a shallow merge to update settings
+        this._scene.settings = { ...this._scene.settings, ...settings };
+        return this;
+    }
+    setName(name) {
+        this._scene.name = name;
+        return this;
+    }
+    setSubtitles(subtitles) {
+        this._scene.settings.subtitles = subtitles;
+        return this;
+    }
+    /**
+     * Adds a pre-composed layer to the scene.
+     * @param layer The final layer object, from `layerComposer.compose()`.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addLayer(layer) {
+        if (!this._scene.layers) {
+            this._scene.layers = [];
+        }
+        this._scene.layers.push(layer);
+        return this;
+    }
+    /**
+     * Adds an asset to the scene's asset registry.
+     * @param asset The asset object to add.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addAsset(asset) {
+        if (!this._scene.assets) {
+            this._scene.assets = [];
+        }
+        this._scene.assets.push(asset);
+        return this;
+    }
+    /**
+     * Adds a global audio track to the scene.
+     * @param audioTrack The audio track object to add.
+     * @returns The SceneComposer instance for further chaining.
+     */
+    addAudioTrack(audioTrack) {
+        if (!this._scene.audioTracks) {
+            this._scene.audioTracks = [];
+        }
+        this._scene.audioTracks.push(audioTrack);
+        return this;
+    }
+    /**
+     * Validates and finalizes the entire scene object.
+     * @returns A fully formed and validated Scene object.
+     */
+    compose() {
+        return SceneShape.parse(this._scene);
+    }
+    safeCompose() {
+        const resp = SceneShape.safeParse(this._scene);
+        if (!resp.success) {
+            console.error('Invalid scene input:', resp.error.format());
+            return undefined;
+        }
+        return resp.data;
+    }
+}
+/**
+ * Factory function to create a new SceneComposer.
+ * @param id The scene's unique ID.
+ * @param settings The initial scene settings.
+ * @returns A new instance of SceneComposer.
+ */
+export function createSceneComposer(id, settings) {
+    return new SceneComposer(id, settings);
+}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const PIXI_DEFAULTS: {
+    eventMode: "none";
+    autoStart: boolean;
+    backgroundAlpha: number;
+    eventFeatures: {
+        move: boolean;
+        /** disables the global move events which can be expensive in large scenes */
+        globalMove: boolean;
+        click: boolean;
+        wheel: boolean;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,14 @@
+export const PIXI_DEFAULTS = {
+    // preference: "webgl" as const, // webgpu
+    eventMode: 'none',
+    autoStart: false,
+    backgroundAlpha: 0,
+    // antialias: false,
+    eventFeatures: {
+        move: false,
+        /** disables the global move events which can be expensive in large scenes */
+        globalMove: false,
+        click: false,
+        wheel: false
+    }
+};

package/dist/directors/ComponentDirector.d.ts

@@ -0,0 +1,20 @@
+import type { IComponentBuilder, ComponentData } from '..';
+import { StateManager } from '../managers/StateManager.svelte.js';
+export declare class ComponentDirector {
+    private builder;
+    private data;
+    private sceneState;
+    constructor(cradle: {
+        stateManager: StateManager;
+    });
+    setBuilder(builder: IComponentBuilder): void;
+    setComponentData(data: ComponentData): void;
+    constructAuto(): import("..").IComponent;
+    constructVideo(): import("..").IComponent;
+    constructAudio(): import("..").IComponent;
+    constructImage(): import("..").IComponent;
+    constructGif(): import("..").IComponent;
+    constructShape(): import("..").IComponent;
+    constructSubtitle(): import("..").IComponent;
+    constructText(): import("..").IComponent;
+}

package/dist/directors/ComponentDirector.js

@@ -0,0 +1,86 @@
+import { StateManager } from '../managers/StateManager.svelte.js';
+export class ComponentDirector {
+    builder;
+    data;
+    sceneState;
+    constructor(cradle) {
+        this.sceneState = cradle.stateManager;
+    }
+    setBuilder(builder) {
+        this.builder = builder;
+    }
+    setComponentData(data) {
+        this.data = data;
+    }
+    constructAuto() {
+        switch (this.data.type) {
+            case 'VIDEO':
+                return this.constructVideo();
+            case 'AUDIO':
+                return this.constructAudio();
+            case 'IMAGE':
+                return this.constructImage();
+            case 'GIF':
+                return this.constructGif();
+            case 'SHAPE':
+                return this.constructShape();
+            case 'SUBTITLES':
+                return this.constructSubtitle();
+            case 'TEXT':
+                return this.constructText();
+            case 'COLOR':
+            case 'GRADIENT':
+                return this.builder.getComponent();
+            default:
+                throw new Error(`Unsupported component type`);
+        }
+    }
+    constructVideo() {
+        this.builder.withMedia().withMediaSeeking();
+        // if (this.sceneState.environment === 'server') {
+        // 	this.builder.withMediaSeeking();
+        // }
+        this.builder.withVideoTexture().withSplitScreen();
+        return this.builder.getComponent();
+    }
+    constructAudio() {
+        this.builder.withMedia();
+        return this.builder.getComponent();
+    }
+    constructImage() {
+        this.builder.withImage().withTexture().withDisplayObject();
+        return this.builder.getComponent();
+    }
+    constructGif() {
+        this.builder.withGif(); //.withDisplayObject();
+        return this.builder.getComponent();
+    }
+    constructShape() {
+        // Check if this is a progress shape to use the appropriate hook
+        const shapeData = this.data;
+        if (shapeData.shape?.type === 'progress') {
+            // Progress shapes use GPU-based PIXI Graphics rendering
+            // Still need DisplayObjectHook to add the progress display object to the stage
+            this.builder.withProgressShape().withDisplayObject();
+        }
+        else {
+            // Regular shapes use canvas-based rendering
+            this.builder.withCanvasShape().withTexture().withDisplayObject();
+        }
+        return this.builder.getComponent();
+    }
+    constructSubtitle() {
+        this.builder.withSubtitles().withHtmlText().withAnimation();
+        if (this.sceneState.environment === 'server') {
+            this.builder.withHtmlToCanvasHook();
+        }
+        return this.builder.getComponent();
+    }
+    constructText() {
+        this.builder.withHtmlText().withAnimation();
+        if (this.sceneState.environment === 'server') {
+            this.builder.withHtmlToCanvasHook();
+        }
+        return this.builder.getComponent();
+    }
+}

package/dist/factories/SceneBuilderFactory.d.ts

@@ -0,0 +1,15 @@
+import type { Scene, RenderEnvironment, Subtitle, FontType, SubtitleCollection } from '..';
+import { SceneBuilder } from '../SceneBuilder.svelte.js';
+import type { FontProvider } from '../fonts/types.js';
+type Config = {
+    environment: RenderEnvironment;
+    subtitles: Record<string, Subtitle[]> | Record<string, SubtitleCollection>;
+    fonts: FontType[];
+    forceCanvas: boolean;
+    scale: number;
+    autoPlay?: boolean;
+    loop?: boolean;
+    fontProviders?: FontProvider[];
+};
+export declare const createSceneBuilder: (sceneData: Scene, container: HTMLDivElement, config?: Partial<Config>) => Promise<SceneBuilder>;
+export {};

package/dist/factories/SceneBuilderFactory.js

@@ -0,0 +1,51 @@
+import { asClass, Lifetime } from 'awilix/browser';
+import { registerNewContainer } from '../DIContainer.js';
+import { SceneBuilder } from '../SceneBuilder.svelte.js';
+import { get } from 'lodash-es';
+import { setFontProviders } from '../fonts/fontLoader.js';
+class SceneBuilderFactory {
+    scene;
+    constructor(cradle) {
+        this.scene = cradle.sceneBuilder;
+    }
+    getInstance() {
+        return this.scene;
+    }
+}
+const defaultConfig = {
+    environment: 'client',
+    subtitles: {},
+    fonts: [],
+    forceCanvas: false,
+    scale: 1,
+    autoPlay: false,
+    loop: false
+};
+export const createSceneBuilder = async function (sceneData, container, config) {
+    setFontProviders(config?.fontProviders);
+    const sceneConfig = config ? { ...defaultConfig, ...config } : defaultConfig;
+    const sceneSubs = get(sceneData, 'settings.subtitles.data', null);
+    const subs = sceneSubs ? sceneSubs : sceneConfig.subtitles;
+    const childContainer = registerNewContainer(sceneData, [
+        ['environment', sceneConfig.environment],
+        ['containerElement', container],
+        ['subtitles', subs],
+        ['fonts', sceneConfig.fonts],
+        ['forceCanvas', sceneConfig.forceCanvas],
+        ['scale', sceneConfig.scale],
+        ['autoPlay', sceneConfig.autoPlay],
+        ['loop', sceneConfig.loop]
+    ]);
+    // Register the factory
+    childContainer.register({
+        sceneBuilderFactory: asClass(SceneBuilderFactory, { lifetime: Lifetime.SINGLETON })
+    });
+    const factory = childContainer.resolve('sceneBuilderFactory');
+    const instance = factory.getInstance();
+    instance.buildCharactersList();
+    await instance.initialize();
+    if (sceneConfig.autoPlay) {
+        instance.play();
+    }
+    return instance;
+};

package/dist/fonts/GoogleFontsProvider.d.ts

@@ -0,0 +1,12 @@
+import type { FontProvider } from './types.js';
+/**
+ * Creates a browser-only font provider for Google Fonts.
+ *
+ * This provider fetches fonts in the woff2 format, as it cannot
+ * set the User-Agent header to request TTF files. For environments
+ * that strictly require TTF (like server-side rendering with some libraries),
+ * a custom server-backed provider is necessary.
+ *
+ * @returns A FontProvider function with its own internal cache.
+ */
+export declare const createGoogleFontsProvider: () => FontProvider;