visualfries 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ContentFries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# VisualFries
+
+[![npm version](https://badge.fury.io/js/visualfries.svg)](https://badge.fury.io/js/visualfries)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**VisualFries** is a **Svelte 5** library for programmatically creating (not just) bite-sized video content for social media. Built on PIXI.js and GSAP (for powerful animations), it's designed primarily for headless rendering of dynamic scenes.
+
+A key feature of VisualFries is its unique approach to text rendering. It uses SVG `<foreignObject>` to render standard HTML and CSS, allowing you to style scenes and create complex text animations with familiar tools and the full power of GSAP.
+
+> ⚠️ **Alpha Software Notice** ⚠️
+>
+> This library is currently in an **alpha** stage. It is not recommended for production use. The API is unstable and may change without notice. There are known bugs and likely many unknown ones. I welcome feedback and bug reports, but please be aware of its experimental nature.
+
+## Project Philosophy & Status
+
+**VisualFries is currently a solo project maintained by me, its creator.** I use this as a backbone of my SaaS, ContentFries.
+
+This means development is driven by a singular vision and you have a direct line to the person who built it. It also means resources are limited. I'm opening this up to the community to share what I've built, get feedback, and see where it goes. I wholeheartedly welcome contributions, bug reports, and ideas.
+
+## Key Features
+
+- **Built for Svelte 5:**
+- **Declarative, JSON-based Scenes:** Define your entire video as a structured, type-safe JSON object.
+- **HTML & CSS for Text:** Style text and overlays with standard CSS. No need to learn a proprietary canvas styling API.
+- **Powerful Animation Engine:** Leverage the full GSAP ecosystem for complex, timeline-based animations.
+- **Component-Based Architecture:** Build scenes by composing Videos, Images, Text, Shapes, and Subtitles.
+- **Fluent Scene Composition:** Use composer utilities to programmatically build scenes, layers, and components with a clean, chainable API.
+- **Headless & Server-Side Ready:** Designed for automated, server-side video generation.
+- **MIT Licensed:** Truly open-source and free for all uses.
+
+## Installation
+
+**Prerequisite:** Your project must be using **Svelte 5** or newer.
+
+```bash
+npm install visualfries
+```
+
+## Quick Start
+
+The best way to use VisualFries is within a Svelte component.
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+	import { onMount, onDestroy } from 'svelte';
+	import { createSceneBuilder, type ISceneBuilder, type Scene } from 'visualfries';
+
+	let canvasContainer: HTMLDivElement;
+	let sceneBuilder: ISceneBuilder;
+
+	// Define your scene using a declarative JSON object
+	const myScene: Scene = {
+		id: 'my-first-scene',
+		version: '2.0',
+		settings: {
+			width: 1080,
+			height: 1080,
+			duration: 10,
+			fps: 30,
+			backgroundColor: '#1a1a1a'
+		},
+		layers: [
+			// ... your layers and components defined here
+		],
+		assets: []
+	};
+
+	onMount(async () => {
+		if (canvasContainer) {
+			sceneBuilder = await createSceneBuilder(myScene, canvasContainer, {
+				environment: 'client',
+				autoPlay: true
+			});
+		}
+	});
+
+	onDestroy(() => {
+		sceneBuilder?.destroy();
+	});
+</script>
+
+<div class="scene-container" bind:this={canvasContainer} />
+
+<style>
+	.scene-container {
+		width: 540px; /* Example scaled size */
+		height: 540px;
+		border: 1px solid #333;
+	}
+</style>
+```
+
+## Scene Composition API
+
+While you can write the scene JSON by hand, the library includes a fluent API to make this process simple and type-safe.
+
+```typescript
+import { createSceneComposer, createLayerComposer, createComponentComposer } from 'visualfries';
+
+// 1. Create a composer for a TEXT component
+const headline = createComponentComposer('headline-text', 'TEXT', { startAt: 0, endAt: 5 })
+	.setAppearance({
+		x: 50,
+		y: 100,
+		width: 980,
+		height: 250,
+		text: {
+			fontFamily: 'Montserrat',
+			fontSize: 90,
+			fontWeight: '800',
+			color: '#FFFFFF',
+			textAlign: 'center'
+		}
+	})
+	.setText('Hello, VisualFries!')
+	.compose();
+
+// 2. Create a layer and add the component
+const mainLayer = createLayerComposer('layer-1').addComponent(headline).compose();
+
+// 3. Create the scene
+const myScene = createSceneComposer('my-scene', {
+	width: 1080,
+	height: 1080,
+	duration: 10,
+	fps: 30
+})
+	.addLayer(mainLayer)
+	.compose();
+```
+
+## Custom Fonts Support
+
+VisualFries needs to load font files (.ttf, .woff2, etc.) to render text. The library uses a flexible font provider chain to allow you to load fonts from any source while retaining default support for Google Fonts.
+
+### Default Behavior: Google Fonts
+
+By default, with no configuration, VisualFries will automatically fetch fonts from Google Fonts. This works out of the box for any client-side application.
+
+### Extending Font Loading
+
+Instead of replacing the default behavior, you can add your own font providers to the front of the chain. This is the recommended approach for loading local or custom fonts.
+
+A font provider is a simple async function that receives a font family and must return a Promise<ArrayBuffer | null>. If it returns null, the library will try the next provider in the chain.
+
+**Example:** Adding a provider for local fonts while keeping Google Fonts as a fallback.
+
+Create your custom provider:
+
+```typescript
+// src/lib/localFontProvider.ts
+import type { FontProvider } from 'visualfries';
+
+export const localFontProvider: FontProvider = async (fontFamily) => {
+	// We only handle fonts that start with our special prefix
+	if (!fontFamily.startsWith('local://')) {
+		// For all other fonts (e.g., "Roboto"), we do nothing and
+		// let the next provider in the chain (the Google provider) handle it.
+		return null;
+	}
+
+	const fontName = fontFamily.replace('local://', '');
+	const fontUrl = `/fonts/${fontName}.ttf`; // Assuming fonts are in /static/fonts
+
+	try {
+		const response = await fetch(fontUrl);
+		if (!response.ok) {
+			console.error(`Failed to load local font: ${fontUrl}`);
+			return null;
+		}
+		return response.arrayBuffer();
+	} catch (error) {
+		console.error(`Error fetching local font: ${fontUrl}`, error);
+		return null;
+	}
+};
+```
+
+Configure the fontProviders array:
+
+When initializing the SceneBuilder, provide your custom provider and the default Google Fonts provider. The library will check yours first.
+
+```typescript
+// In your Svelte component
+import { createSceneBuilder, createGoogleFontsProvider } from 'visualfries';
+import { localFontProvider } from '$lib/localFontProvider';
+
+const builder = await createSceneBuilder(sceneData, container, {
+	environment: 'client',
+	fontProviders: [
+		// 1. Your provider is checked first.
+		localFontProvider,
+
+		// 2. If your provider returns null, the default provider is checked next.
+		createGoogleFontsProvider()
+	]
+});
+```
+
+## Contributing
+
+As an early-stage, solo-developed project, contributions are highly encouraged! The best way to contribute right now is by:
+
+- Opening an issue to report a bug or suggest a feature
+- Improving the documentation by clarifying confusing sections or adding new examples
+- Sharing your creations! Seeing what people build is the best motivation
+
+Please feel free to get in touch through GitHub Issues.
+
+## License
+
+VisualFries is licensed under the MIT License.

package/dist/DIContainer.d.ts

@@ -0,0 +1,4 @@
+import { type AwilixContainer } from 'awilix/browser';
+import type { Scene as SceneData } from './';
+export declare const registerNewContainer: (data: SceneData, instances: [string, unknown][]) => AwilixContainer;
+export declare const removeContainer: (sceneId: string) => void;

package/dist/DIContainer.js

@@ -0,0 +1,145 @@
+import { createContainer, asClass, asValue, Lifetime } from 'awilix/browser';
+import { SceneBuilder } from './SceneBuilder.svelte.js';
+import { RenderManager } from './managers/RenderManager.js';
+import { StateManager } from './managers/StateManager.svelte.js';
+import { TimelineManager } from './managers/TimelineManager.svelte.js';
+import { EventManager } from './managers/EventManager.js';
+import { DomManager } from './managers/DomManager.js';
+import { AppManager } from './managers/AppManager.svelte.js';
+import { ComponentsManager } from './managers/ComponentsManager.svelte.js';
+import { MediaManager } from './managers/MediaManager.js';
+import { SubtitlesManager } from './managers/SubtitlesManager.svelte.js';
+import { ComponentDirector } from './directors/ComponentDirector.js';
+import { PixiComponentBuilder } from './builders/PixiComponentBuilder.js';
+import { MediaHook } from './components/hooks/MediaHook.js';
+import { VerifyMediaHook } from './components/hooks/VerifyMediaHook.js';
+import { ImageHook } from './components/hooks/ImageHook.js';
+import { VerifyImageHook } from './components/hooks/VerifyImageHook.js';
+import { PixiVideoTextureHook } from './components/hooks/PixiVideoTextureHook.js';
+import { PixiSplitScreenDisplayObjectHook } from './components/hooks/PixiSplitScreenDisplayObjectHook.js';
+import { HtmlTextHook } from './components/hooks/HtmlTextHook.js';
+import { HtmlAnimationHook } from './components/hooks/HtmlAnimationHook.js';
+import { AnimationHook } from './components/hooks/AnimationHook.js';
+import { SubtitlesHook } from './components/hooks/SubtitlesHook.js';
+import { PixiTextureHook } from './components/hooks/PixiTextureHook.js';
+import { PixiDisplayObjectHook } from './components/hooks/PixiDisplayObjectHook.js';
+import { PixiGifHook } from './components/hooks/PixiGifHook.js';
+import { CanvasShapeHook } from './components/hooks/CanvasShapeHook.js';
+import { PixiProgressShapeHook } from './components/hooks/PixiProgressShapeHook.js';
+import { HtmlToCanvasHook } from './components/hooks/HtmlToCanvasHook.js';
+import { PlayCommand } from './commands/PlayCommand.js';
+import { PauseCommand } from './commands/PauseCommand.js';
+import { SeekCommand } from './commands/SeekCommand.js';
+import { ReplaceSourceOnTimeCommand } from './commands/ReplaceSourceOnTimeCommand.js';
+import { RenderFrameCommand } from './commands/RenderFrameCommand.js';
+import { UpdateComponentCommand } from './commands/UpdateComponentCommand.js';
+import { RenderCommand } from './commands/RenderCommand.js';
+import { CommandRunner } from './commands/CommandRunner.js';
+import { Component } from './components/Component.svelte.js';
+import { ComponentContext } from './components/ComponentContext.svelte.js';
+import { Layer } from './layers/Layer.svelte.js';
+import { LayersManager } from './managers/LayersManager.svelte.js';
+import { MediaSeekingHook } from './components/hooks/MediaSeekingHook.js';
+import { VerifyGifHook } from './components/hooks/VerifyGifHook.js';
+import { ComponentAnimationTransformer } from './animations/transformers/AnimationReferenceTransformer.js';
+import { AnimationPresetsRegister } from './animations/AnimationPresetsRegister.js';
+import { SplitTextCache } from './animations/SplitTextCache.js';
+import { TimeManager } from './managers/TimeManager.svelte.js';
+const containers = new Map();
+export const registerNewContainer = function (data, instances) {
+    if (containers.has(data.id)) {
+        return containers.get(data.id);
+    }
+    const childContainer = createContainer();
+    const paramMap = new Map(instances);
+    const subtitlesCollection = paramMap.get('subtitlesCollection') || {};
+    // Register constant values
+    childContainer.register({
+        containerId: asValue(data.id),
+        sceneData: asValue(data),
+        container: asValue(childContainer),
+        ...Object.fromEntries(instances.map(([name, value]) => [
+            name, // Awilix uses lowercase by convention
+            asValue(value)
+        ]))
+    });
+    // Register all managers as singletons
+    childContainer.register({
+        timeManager: asClass(TimeManager, { lifetime: Lifetime.SINGLETON }),
+        subtitlesManager: asClass(SubtitlesManager, { lifetime: Lifetime.SINGLETON }),
+        stateManager: asClass(StateManager, { lifetime: Lifetime.SINGLETON }),
+        appManager: asClass(AppManager, { lifetime: Lifetime.SINGLETON }),
+        eventManager: asClass(EventManager, { lifetime: Lifetime.SINGLETON }),
+        timelineManager: asClass(TimelineManager, { lifetime: Lifetime.SINGLETON }),
+        componentsManager: asClass(ComponentsManager, { lifetime: Lifetime.SINGLETON }),
+        renderManager: asClass(RenderManager, { lifetime: Lifetime.SINGLETON }),
+        domManager: asClass(DomManager, { lifetime: Lifetime.SINGLETON }),
+        mediaManager: asClass(MediaManager, { lifetime: Lifetime.SINGLETON }),
+        sceneBuilder: asClass(SceneBuilder, { lifetime: Lifetime.SINGLETON }),
+        layersManager: asClass(LayersManager, { lifetime: Lifetime.SINGLETON }),
+        // transients
+        // SceneBuilder ?
+        componentDirector: asClass(ComponentDirector),
+        pixiComponentBuilder: asClass(PixiComponentBuilder),
+        mediaHook: asClass(MediaHook, { lifetime: Lifetime.TRANSIENT }),
+        mediaSeekingHook: asClass(MediaSeekingHook, { lifetime: Lifetime.TRANSIENT }),
+        verifyMediaHook: asClass(VerifyMediaHook, { lifetime: Lifetime.TRANSIENT }),
+        imageHook: asClass(ImageHook, { lifetime: Lifetime.TRANSIENT }),
+        verifyImageHook: asClass(VerifyImageHook, { lifetime: Lifetime.TRANSIENT }),
+        verifyGifHook: asClass(VerifyGifHook, { lifetime: Lifetime.TRANSIENT }),
+        videoTextureHook: asClass(PixiVideoTextureHook, { lifetime: Lifetime.TRANSIENT }),
+        splitScreenHook: asClass(PixiSplitScreenDisplayObjectHook, { lifetime: Lifetime.TRANSIENT }),
+        htmlTextHook: asClass(HtmlTextHook, { lifetime: Lifetime.TRANSIENT }),
+        htmlAnimationHook: asClass(HtmlAnimationHook, { lifetime: Lifetime.TRANSIENT }),
+        animationHook: asClass(AnimationHook, { lifetime: Lifetime.TRANSIENT }),
+        subtitlesHook: asClass(SubtitlesHook, { lifetime: Lifetime.TRANSIENT }),
+        textureHook: asClass(PixiTextureHook, { lifetime: Lifetime.TRANSIENT }),
+        objectHook: asClass(PixiDisplayObjectHook, { lifetime: Lifetime.TRANSIENT }),
+        gifHook: asClass(PixiGifHook, { lifetime: Lifetime.TRANSIENT }),
+        canvasShapeHook: asClass(CanvasShapeHook, { lifetime: Lifetime.TRANSIENT }),
+        pixiProgressShapeHook: asClass(PixiProgressShapeHook, { lifetime: Lifetime.TRANSIENT }),
+        htmlToCanvasHook: asClass(HtmlToCanvasHook, { lifetime: Lifetime.TRANSIENT }),
+        componentAnimationTransformer: asClass(ComponentAnimationTransformer, {
+            lifetime: Lifetime.TRANSIENT
+        }),
+        animationPresetsRegister: asClass(AnimationPresetsRegister, { lifetime: Lifetime.SINGLETON }),
+        splitTextCache: asClass(SplitTextCache, { lifetime: Lifetime.SINGLETON }),
+        // Register commands
+        playCommand: asClass(PlayCommand, { lifetime: Lifetime.SINGLETON }),
+        pauseCommand: asClass(PauseCommand, { lifetime: Lifetime.SINGLETON }),
+        seekCommand: asClass(SeekCommand, { lifetime: Lifetime.SINGLETON }),
+        replaceSourceOnTimeCommand: asClass(ReplaceSourceOnTimeCommand, {
+            lifetime: Lifetime.SINGLETON
+        }),
+        renderFrameCommand: asClass(RenderFrameCommand, { lifetime: Lifetime.SINGLETON }),
+        updateComponentCommand: asClass(UpdateComponentCommand, { lifetime: Lifetime.SINGLETON }),
+        renderCommand: asClass(RenderCommand, { lifetime: Lifetime.SINGLETON }),
+        // Register the command runner
+        commandRunner: asClass(CommandRunner, { lifetime: Lifetime.SINGLETON }),
+        component: asClass(Component, {
+            lifetime: Lifetime.TRANSIENT // New instance per component
+        }),
+        layer: asClass(Layer),
+        componentContext: asClass(ComponentContext, {
+            lifetime: Lifetime.TRANSIENT // New instance per component
+        })
+    });
+    // Resolve core dependencies to ensure initialization
+    childContainer.resolve('stateManager');
+    childContainer.resolve('eventManager');
+    childContainer.resolve('timelineManager');
+    childContainer.resolve('domManager');
+    childContainer.resolve('appManager');
+    childContainer.resolve('componentsManager');
+    childContainer.resolve('renderManager');
+    childContainer.resolve('subtitlesManager');
+    containers.set(data.id, childContainer);
+    return childContainer;
+};
+export const removeContainer = function (sceneId) {
+    if (containers.has(sceneId)) {
+        const container = containers.get(sceneId);
+        container.dispose();
+        containers.delete(sceneId);
+    }
+};