scrollcraft 2.0.5 → 2.0.7

package/README.md

@@ -1,53 +1,69 @@
-# 🎞️ ScrollCraft 2.0
+# ScrollCraft 
 
-**Transform cinematic motion into interactive web experiences.**
+**Transform media into interactive web experiences.**
 
-ScrollCraft 2.0 is a modern animation SDK built for the era of high-performance, agent-driven development. It allows you to transform standard video or image sequences into "Intelligent Assets" that precisely track subjects and depth.
+ScrollCraft is a modern animation SDK built for the era of high-performance, agent-driven development. It allows you to transform standard video or images into web assets that precisely track subjects and depth.
 
 ---
 
-## 🚀 Quick Start
+## Installation
 
 ```bash
-# 1. Transform your video into an intelligent asset sequence
-npx scft create "examples/sample-media/jabko.mp4" --cloud --depth --prompt "apple" 
+npm install scrollcraft
+```
+
+---
 
-# this command will output a folder named scrollcraft-project 
+## Quick Start
+
+Initialize your project:
+
+```bash
+# 1. Transform your video into a ScrollCraft project
+# This will extract frames, track the subject, and generate optimized variants and depth maps using cloud AI processing.
+npx scft create "your-video.mp4" --name "my-project" --track "apple" --cloud --depth
 ```
 
 ```tsx
-// 2. Drop it into your React app
-import project from './scrollcraft-project/scrollcraft.json';
+// 2. Drop it into your Next.js app
+import project from './my-project/scrollcraft.json';
 import { ScrollCraftProvider, ScrollCraftCanvas, SubjectLayer } from 'scrollcraft';
 
 const App = () => (
-  <ScrollCraftProvider project={project}>
-    <ScrollCraftCanvas />
-    <SubjectLayer offset={{ x: 10, y: -5 }}>
-       <h2>Pin UI to moving objects.</h2>
-    </SubjectLayer>
+  <ScrollCraftProvider 
+    project={project} 
+    scrub={0.1} // Smooth interpolation (0 = instant, 1 = heavy lag)
+  >
+    <div style={{ height: '400vh' }}>
+      <ScrollCraftCanvas />
+      
+      {/* Automatically follows the 'apple' tracked in the CLI */}
+      <SubjectLayer id="main">
+         <h2>Pinned Element</h2>
+      </SubjectLayer>
+    </div>
   </ScrollCraftProvider>
 );
 ```
 
 ---
 
-## 📖 Documentation & Guides
+## Documentation & Guides
 
 Choose your path based on your role:
 
 ### 👤 For Humans
-- [**Core Architecture**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/architecture.md): Understand the state-snapshot engine.
-- [**Asset Pipeline**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/asset-pipeline.md): Learn how to use the CLI and AI tracking.
-- [**React Hooks**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/react-integration.md): Build custom interactive components.
+- [**Core Architecture**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/app/docs/architecture/page.md): Understand the state-snapshot engine.
+- [**Asset Pipeline**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/app/docs/asset-pipeline/page.md): Learn how to use the CLI and AI tracking.
+- [**React Hooks**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/app/docs/react-integration/page.md): Build custom interactive components.
 
 ### 🤖 For AI Agents
 - [**AGENTS.md**](https://github.com/aleskozelsky/scrollcraft/blob/main/AGENTS.md): Technical standard operating procedures for the repository.
-- [**AI Integration Protocol**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/ai-integration.md): How to prompt agents to build scenes for you.
+- [**AI Integration Protocol**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/app/docs/ai-integration/page.md): How to prompt agents to build scenes for you.
 
 ---
 
-## 🛠️ Performance & Tech
+## Performance & Tech
 - **WebGL Accelerated**: High-FPS rendering even for 4K sequences.
 - **AI Subject Tracking**: Automatic (x,y) pinning via SAM 3.
 - **Mouse-Interactive Parallax**: Automatic 3D depth map generation and rendering.

package/dist/cli/fal-service.js

@@ -117,7 +117,7 @@ class FalService {
             }
         });
         // Debug output to see what Fal is actually returning
-        await fs.writeFile('debug_fal.json', JSON.stringify(result, null, 2));
+        //await fs.writeFile('debug_fal.json', JSON.stringify(result, null, 2));
         const payload = result.data || result;
         if (!payload.video || !payload.video.url) {
             throw new Error(`AI Depth Map generation failed. No video URL returned. Saved response to debug_fal.json`);

package/dist/cli/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import 'dotenv/config';

package/dist/cli/index.js

@@ -43,9 +43,69 @@ const fs = __importStar(require("fs-extra"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const ffmpeg_static_1 = __importDefault(require("ffmpeg-static"));
-const fal_service_1 = require("./fal-service");
-const processor_1 = require("./processor");
+const pipeline_1 = require("../pipeline");
+const readline = __importStar(require("readline"));
+require("dotenv/config");
 const pkg = require('../../package.json');
+/**
+ *  MEDIA QUERY BUILDER
+ */
+function buildVariantsFromIds(input) {
+    const result = [];
+    const orientations = ['portrait', 'landscape'];
+    // 1. Process each "Target" resolution
+    input.forEach(item => {
+        let res = 0;
+        if (typeof item === 'number')
+            res = item;
+        else if (typeof item === 'string')
+            res = parseInt(item);
+        else if (item.height)
+            res = item.height; // Assume height is the defining metric
+        if (!res || isNaN(res))
+            return;
+        orientations.forEach(orient => {
+            const isPortrait = orient === 'portrait';
+            const width = isPortrait ? res : Math.round(res * (16 / 9));
+            const height = isPortrait ? Math.round(res * (16 / 9)) : res;
+            result.push({
+                id: `${res}p_${orient.substring(0, 1)}`,
+                width,
+                height,
+                orientation: orient,
+                aspectRatio: isPortrait ? '9:16' : '16:9',
+                media: `(orientation: ${orient})` // Minimal fallback
+            });
+        });
+    });
+    // 2. Sort by height (ascending) so the engine finds the first one that fits
+    return result.sort((a, b) => a.height - b.height);
+}
+/**
+ * CONFIG LOADER
+ * Looks for scrollcraft.config.js/ts in the current working directory.
+ */
+async function loadProjectConfig() {
+    const possiblePaths = [
+        path.join(process.cwd(), 'scrollcraft.cli.config.js'),
+        path.join(process.cwd(), 'scrollcraft.cli.config.cjs'),
+        path.join(process.cwd(), 'scrollcraft.cli.config.ts')
+    ];
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            try {
+                // For simplicity in CLI we handle commonjs/esm basics
+                // If it's TS, it might need jiti or ts-node, but let's assume JS for now
+                // or use a simple dynamic import if supported.
+                return require(p);
+            }
+            catch (e) {
+                console.warn(chalk_1.default.yellow(`⚠️  Found config at ${p} but failed to load it. Skipping...`));
+            }
+        }
+    }
+    return null;
+}
 /**
  * Robust FFmpeg Detection
  * Prioritizes bundled static binary, then system PATH.
@@ -68,16 +128,33 @@ program
     .name('scft')
     .description('ScrollCraft CLI - Immersive Web SDK')
     .version(pkg.version);
+/**
+ * Interactive Helper
+ */
+async function prompt(question, defaultValue) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    return new Promise(resolve => {
+        rl.question(`${chalk_1.default.cyan('?')} ${question}${defaultValue ? ` (${defaultValue})` : ''}: `, (answer) => {
+            rl.close();
+            resolve(answer.trim() || defaultValue || '');
+        });
+    });
+}
 program
     .command('create')
     .description('ONE-STEP: Transform video/images into a responsive ScrollCraft')
-    .argument('<input>', 'Path to input video or directory of images')
-    .option('-o, --output <dir>', 'Output directory', './scrollcraft-project')
-    .option('-p, --prompt <text>', 'Text prompt for subject tracking', 'main subject')
+    .argument('[input]', 'Path to input video or directory of images')
+    .option('-o, --output <dir>', 'Output directory (deprecated, use --name)')
+    .option('-p, --track <text>', 'Text prompt for subject tracking', 'main subject')
+    .option('-n, --name <string>', 'Name of the project')
+    .option('-v, --variants <string>', 'Comma-separated target resolutions (e.g. 720,1080)')
     .option('-s, --step <number>', 'Process every Nth frame (default: 1)', '1')
     .option('--cloud', 'Use Fal.ai for tracking and refinement', false)
     .option('--depth', 'Generate a 3D depth map for the displacement effect (Requires --cloud)', false)
-    .action(async (input, opts) => {
+    .action(async (inputArg, opts) => {
     console.log(chalk_1.default.bold.blue('\n🎞️  ScrollCraft Asset Pipeline\n'));
     // 0. PRE-FLIGHT CHECK
     const ffmpegPath = getFFmpegPath();
@@ -87,79 +164,76 @@ program
         console.log('Please install it manually or ensure regular npm install was successful.');
         process.exit(1);
     }
-    const outDir = path.resolve(opts.output);
-    const tempDir = path.join(outDir, '.temp-frames');
-    const step = parseInt(opts.step) || 1;
-    try {
-        await fs.ensureDir(outDir);
-        await fs.ensureDir(tempDir);
-        // 1. FRAME EXTRACTION
-        if (fs.statSync(input).isFile()) {
-            console.log(chalk_1.default.yellow(`📦 Extracting frames from video: ${input}`));
-            // Extract 30 frames per second (matching our default)
-            // Using the robust path discovered in pre-flight
-            (0, child_process_1.execSync)(`"${ffmpegPath}" -i "${input}" -vf "fps=30" "${tempDir}/frame_%04d.png"`, { stdio: 'inherit' });
-        }
-        else {
-            console.log(chalk_1.default.yellow(`📂 Using images from: ${input}`));
-            if (opts.cloud || opts.depth) {
-                console.error(chalk_1.default.red('\n❌ AI Cloud features (tracking/depth) currently require a video file as input.'));
-                console.log(chalk_1.default.yellow('To use a directory of images, please use local mode (disable --cloud and --depth).'));
-                process.exit(1);
-            }
-            const files = (await fs.readdir(input))
-                .filter(f => /\.(png|jpg|jpeg|webp)$/i.test(f))
-                .sort((a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }));
-            if (files.length === 0) {
-                throw new Error(`No compatible images (png, jpg, webp) found in ${input}`);
-            }
-            console.log(chalk_1.default.dim(`📦 Standardizing ${files.length} images...`));
-            for (let i = 0; i < files.length; i++) {
-                const ext = path.extname(files[i]);
-                const frameName = `frame_${(i + 1).toString().padStart(4, '0')}${ext}`;
-                await fs.copy(path.join(input, files[i]), path.join(tempDir, frameName));
-            }
-        }
-        // 2. SUBJECT TRACKING & DEPTH MAP
-        let trackingData = [];
-        let hasDepth = false;
-        if (opts.cloud) {
-            const fal = new fal_service_1.FalService();
-            // Tracking
-            trackingData = await fal.trackSubject(input, opts.prompt);
-            // Depth Map
-            if (opts.depth) {
-                console.log(chalk_1.default.yellow(`\n🕳️  Generating Depth Map via AI...`));
-                const depthUrl = await fal.generateDepthMap(input);
-                console.log(chalk_1.default.yellow(`📥 Downloading Depth Map Video...`));
-                const res = await fetch(depthUrl);
-                const arrayBuffer = await res.arrayBuffer();
-                const depthVideoPath = path.join(tempDir, 'depth_video.mp4');
-                await fs.writeFile(depthVideoPath, Buffer.from(arrayBuffer));
-                console.log(chalk_1.default.yellow(`📦 Extracting depth frames...`));
-                (0, child_process_1.execSync)(`"${ffmpegPath}" -i "${depthVideoPath}" -vf "fps=30" "${tempDir}/depth_%04d.png"`, { stdio: 'inherit' });
-                hasDepth = true;
-            }
-        }
-        else {
-            console.log(chalk_1.default.dim('ℹ️  Local tracking not yet implemented. Using center-pinned defaults.'));
-            const frames = (await fs.readdir(tempDir)).filter(f => f.startsWith('frame_'));
-            trackingData = frames.map((_, i) => ({ frame: i, x: 0.5, y: 0.5, scale: 0 }));
+    const projectConfig = await loadProjectConfig();
+    let input = inputArg;
+    let track = opts.track;
+    let projectName = opts.name;
+    let useTracking = opts.cloud; // Default to cloud if flag set
+    let useDepth = opts.depth;
+    let customVariants = projectConfig?.variants || (opts.variants ? buildVariantsFromIds(opts.variants.split(',')) : null);
+    // 1. INPUT VALIDATION (Immediate)
+    if (!input) {
+        input = await prompt('Path to input video or directory of images');
+    }
+    if (!input || !fs.existsSync(input)) {
+        console.error(chalk_1.default.red(`\n❌ Error: Input path "${input || ''}" does not exist.`));
+        process.exit(1);
+    }
+    // 2. PROJECT NAME & SETTINGS
+    if (!projectName) {
+        projectName = await prompt('Project name', 'scrollcraft-project');
+    }
+    let step = parseInt(opts.step) || 1;
+    if (!inputArg) {
+        const stepInput = await prompt('Process every Nth frame (Step size)', '1');
+        step = parseInt(stepInput) || 1;
+    }
+    // AI Tracking logic preserved in CLI wrapper...
+    // ...
+    const pipeline = new pipeline_1.AssetPipeline({
+        apiKey: process.env.FAL_KEY,
+        onProgress: (p) => {
+            // You could add a progress bar here
         }
-        // 3. VARIANT GENERATION (Mobile/Desktop)
-        const processor = new processor_1.AssetProcessor(outDir);
-        const variants = await processor.processVariants(tempDir, trackingData, { step, hasDepth });
-        // 4. CLEANUP & SAVE
-        await processor.saveConfig(variants);
-        await fs.remove(tempDir);
+    });
+    try {
+        await pipeline.create({
+            input: input,
+            name: projectName,
+            track: useTracking ? track : undefined,
+            hasDepth: useDepth,
+            variants: customVariants || [720, 1080],
+            step: step
+        });
         console.log(chalk_1.default.bold.green(`\n✅ Project Created Successfully!`));
-        console.log(chalk_1.default.white(`📍 Output: ${outDir}`));
+        console.log(chalk_1.default.white(`📍 Output: ${projectName}`));
         console.log(chalk_1.default.white(`📜 Config: scrollcraft.json`));
         console.log(chalk_1.default.cyan(`\nNext: Import the .json into your <ScrollCraftProvider />\n`));
     }
     catch (err) {
-        console.error(chalk_1.default.red(`\n❌ Error: ${err.message}`));
+        console.error(chalk_1.default.red(`\n❌ Error during pipeline: ${err.message}`));
+        process.exit(1);
+    }
+});
+// NEW UPDATE COMMAND
+program
+    .command('update')
+    .description('Rerun extraction and tracking on an existing project')
+    .argument('<dir>', 'Project directory')
+    .option('-p, --track <text>', 'Additional subject to track')
+    .action(async (dir, opts) => {
+    console.log(chalk_1.default.bold.yellow('\n♻️  ScrollCraft Update Pipeline\n'));
+    const projectPath = path.resolve(dir);
+    const configPath = path.join(projectPath, 'scrollcraft.json');
+    if (!fs.existsSync(configPath)) {
+        console.error(chalk_1.default.red('❌ Not a valid ScrollCraft project directory (missing scrollcraft.json).'));
         process.exit(1);
     }
+    const config = await fs.readJson(configPath);
+    if (config.version !== pkg.version) {
+        console.warn(chalk_1.default.yellow(`⚠️  Version Mismatch: Project is ${config.version}, CLI is ${pkg.version}`));
+        // In a real implementation, we might offer to upgrade or handle incompatibilities
+    }
+    console.log(chalk_1.default.dim('Skeletal update implemented. Continuing in next iteration...'));
 });
 program.parse(process.argv);

package/dist/cli/processor.d.ts

@@ -15,6 +15,7 @@ export declare class AssetProcessor {
     processVariants(sourceFramesDir: string, trackingData: SubjectFrameData[], options?: {
         step?: number;
         hasDepth?: boolean;
+        variants?: any[];
     }): Promise<AssetVariant[]>;
     private subjectToSharpPosition;
     /**

package/dist/cli/processor.js

@@ -40,6 +40,7 @@ exports.AssetProcessor = void 0;
 const fs = __importStar(require("fs-extra"));
 const path = __importStar(require("path"));
 const sharp_1 = __importDefault(require("sharp"));
+const pkg = require('../../package.json');
 /**
  * LOCAL ASSET PROCESSOR
  *
@@ -65,7 +66,7 @@ class AssetProcessor {
         const framesToProcess = allFrames.filter((_, i) => i % step === 0);
         const variants = [];
         // Define our target variants
-        const configs = [
+        const configs = options.variants || [
             { id: 'mobile', width: 720, height: 1280, media: '(max-width: 600px)' },
             { id: 'desktop', width: 1920, height: 1080, media: '(min-width: 601px)' }
         ];
@@ -101,8 +102,9 @@ class AssetProcessor {
                             fit: 'cover',
                             position: this.subjectToSharpPosition(subject)
                         })
-                            // We grayscale and save as webp
+                            // Grayscale, then blur slightly to prevent "staircase" effects in displacement
                             .grayscale()
+                            .blur(2)
                             .webp({ quality: 80 })
                             .toFile(depthTargetPath);
                     }
@@ -113,14 +115,20 @@ class AssetProcessor {
                     frame: i
                 });
             }
+            // Extract tracking data into its own file
+            const trackingPath = path.join(variantDir, '000_tracking-main.json');
+            await fs.writeJson(trackingPath, variantTracking, { spaces: 2 });
             variants.push({
                 id: config.id,
                 media: config.media,
+                width: config.width,
+                height: config.height,
+                orientation: config.orientation,
                 path: `./${config.id}`, // Relative path in the final output
-                aspectRatio: config.id === 'mobile' ? '9:16' : '16:9',
+                aspectRatio: config.aspectRatio,
                 frameCount: framesToProcess.length,
                 hasDepthMap: options.hasDepth,
-                subjectTracking: variantTracking
+                subjects: ['main']
             });
         }
         return variants;
@@ -138,9 +146,8 @@ class AssetProcessor {
      */
     async saveConfig(variants) {
         const config = {
-            version: "2.0.1",
+            version: pkg.version,
             settings: {
-                fps: 30,
                 baseResolution: { width: 1920, height: 1080 },
                 scrollMode: 'vh'
             },

package/dist/core/CoreEngine.d.ts

@@ -1,6 +1,6 @@
 import { ProjectConfiguration } from './types';
 /**
- * SCROLLCRAFT 2.0 CORE ENGINE
+ * SCROLLCRAFT CORE ENGINE
  *
  * A declarative, performant engine that maps scroll progress
  * to high-performance image sequence rendering.
@@ -12,10 +12,23 @@ export declare class CoreEngine {
     private canvas;
     private ctx;
     private renderer;
+    basePath: string;
+    scrub: number;
+    private targetProgress;
+    private currentProgress;
+    private rafId;
+    private destroyed;
     private imageCache;
     private depthCache;
     private scrollTimeout;
-    constructor(config: ProjectConfiguration);
+    private trackingDataCache;
+    onFrameChange?: (frame: number, progress: number) => void;
+    private boundResize;
+    constructor(config: ProjectConfiguration, options?: {
+        scrub?: number;
+    });
+    destroy(): void;
+    static init(container: HTMLElement, configUrl: string): Promise<CoreEngine>;
     /**
      * ATTACH CANVAS
      * Connects the engine to a DOM element for rendering.
@@ -23,24 +36,29 @@ export declare class CoreEngine {
     attachCanvas(canvas: HTMLCanvasElement): void;
     private resizeCanvas;
     /**
-     * ADAPTIVE RENDERING
-     * Selects the best image folder based on current browser media queries.
+     * SMART VARIANT SELECTION
+     * Selects the best image variant based on physical pixel requirements
+     * and the dimensions of the parent container.
      */
     private detectBestVariant;
     private clearCache;
     private preloadInitial;
     /**
      * THE PLAYER ENGINE
-     * Maps global scroll progress (0-1) to local scene frames.
+     * Sets the target scroll progress. Actual rendering interpolates to this value.
      */
-    update(progress: number): {
-        frame: number;
-        subjectCoords: {
-            x: number;
-            y: number;
-        };
-    } | undefined;
-    private getSubjectCoords;
+    update(progress: number): void;
+    private updateLoop;
+    private calculateFrame;
+    /**
+     * LOAD SUBJECT TRACKING (On-Demand)
+     */
+    loadTrackingData(subjectId: string): Promise<void>;
+    getTrackedCoords(subjectId: string, frame: number): {
+        x: number;
+        y: number;
+        scale?: number;
+    };
     /**
      * RENDER LOOP
      * Draws the image to the canvas with object-fit: cover logic.

package/dist/core/index.d.ts

@@ -1 +1,4 @@
 export * from './types';
+export { CoreEngine } from './CoreEngine';
+import { CoreEngine } from './CoreEngine';
+export default CoreEngine;

package/dist/core/scrollcraft.umd.min.js

@@ -11,4 +11,4 @@
 */
 
 
-!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.ScrollCraft=t():e.ScrollCraft=t()}(this,()=>(()=>{"use strict";var e={};return e=e.default})());
+!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ScrollCraft=e():t.ScrollCraft=e()}(this,()=>(()=>{"use strict";var t={d:(e,i)=>{for(var s in i)t.o(i,s)&&!t.o(e,s)&&Object.defineProperty(e,s,{enumerable:!0,get:i[s]})},o:(t,e)=>Object.prototype.hasOwnProperty.call(t,e)},e={};t.d(e,{default:()=>a});class i{constructor(t){if(this.targetMouse={x:0,y:0},this.currentMouse={x:0,y:0},this.animationFrameId=0,this.animate=()=>{if(this.currentMouse.x+=.1*(this.targetMouse.x-this.currentMouse.x),this.currentMouse.y+=.1*(this.targetMouse.y-this.currentMouse.y),this.gl&&this.program){this.gl.useProgram(this.program);const t=this.gl.getUniformLocation(this.program,"u_mouse");this.gl.uniform2f(t,this.currentMouse.x,this.currentMouse.y),this.draw()}this.animationFrameId=requestAnimationFrame(this.animate)},this.gl=t.getContext("webgl",{alpha:!1,antialias:!1}),!this.gl)throw new Error("WebGL not supported");this.program=this.createProgram("\n            attribute vec2 a_position;\n            varying vec2 v_texCoord;\n            void main() {\n                gl_Position = vec4(a_position, 0.0, 1.0);\n                // Convert -1 -> 1 to 0 -> 1 for UVs\n                v_texCoord = a_position * 0.5 + 0.5;\n                v_texCoord.y = 1.0 - v_texCoord.y;\n            }\n        ","\n            precision mediump float;\n            uniform sampler2D u_image;\n            uniform sampler2D u_depthMap;\n            uniform vec2 u_resolution;\n            uniform vec2 u_imageResolution;\n            uniform vec2 u_mouse;\n            uniform bool u_hasDepth;\n            varying vec2 v_texCoord;\n\n            void main() {\n                // object-fit: cover math\n                vec2 ratio = vec2(\n                    min((u_resolution.x / u_resolution.y) / (u_imageResolution.x / u_imageResolution.y), 1.0),\n                    min((u_resolution.y / u_resolution.x) / (u_imageResolution.y / u_imageResolution.x), 1.0)\n                );\n                vec2 uv = vec2(\n                    v_texCoord.x * ratio.x + (1.0 - ratio.x) * 0.5,\n                    v_texCoord.y * ratio.y + (1.0 - ratio.y) * 0.5\n                );\n\n                if (u_hasDepth) {\n                    float depth = texture2D(u_depthMap, uv).r;\n                    // White is close (1), Black is far (0). We move close objects more.\n                    vec2 parallax = u_mouse * depth * 0.04;\n                    uv += parallax;\n                }\n                \n                gl_FragColor = texture2D(u_image, uv);\n            }\n        "),this.gl.useProgram(this.program),this.positionBuffer=this.gl.createBuffer(),this.gl.bindBuffer(this.gl.ARRAY_BUFFER,this.positionBuffer),this.gl.bufferData(this.gl.ARRAY_BUFFER,new Float32Array([-1,-1,1,-1,-1,1,-1,1,1,-1,1,1]),this.gl.STATIC_DRAW),this.texture=this.gl.createTexture(),this.depthTexture=this.gl.createTexture(),window.addEventListener("mousemove",t=>{this.targetMouse.x=t.clientX/window.innerWidth*2-1,this.targetMouse.y=-t.clientY/window.innerHeight*2+1}),this.animate()}createProgram(t,e){const i=this.gl.createShader(this.gl.VERTEX_SHADER);this.gl.shaderSource(i,t),this.gl.compileShader(i);const s=this.gl.createShader(this.gl.FRAGMENT_SHADER);this.gl.shaderSource(s,e),this.gl.compileShader(s);const r=this.gl.createProgram();return this.gl.attachShader(r,i),this.gl.attachShader(r,s),this.gl.linkProgram(r),r}render(t,e,i,s){this.gl.useProgram(this.program),this.gl.activeTexture(this.gl.TEXTURE0),this.gl.bindTexture(this.gl.TEXTURE_2D,this.texture),this.gl.texImage2D(this.gl.TEXTURE_2D,0,this.gl.RGBA,this.gl.RGBA,this.gl.UNSIGNED_BYTE,t),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_WRAP_S,this.gl.CLAMP_TO_EDGE),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_WRAP_T,this.gl.CLAMP_TO_EDGE),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_MIN_FILTER,this.gl.LINEAR),this.gl.activeTexture(this.gl.TEXTURE1),this.gl.bindTexture(this.gl.TEXTURE_2D,this.depthTexture),e&&(this.gl.texImage2D(this.gl.TEXTURE_2D,0,this.gl.RGBA,this.gl.RGBA,this.gl.UNSIGNED_BYTE,e),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_WRAP_S,this.gl.CLAMP_TO_EDGE),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_WRAP_T,this.gl.CLAMP_TO_EDGE),this.gl.texParameteri(this.gl.TEXTURE_2D,this.gl.TEXTURE_MIN_FILTER,this.gl.LINEAR)),this.gl.uniform1i(this.gl.getUniformLocation(this.program,"u_image"),0),this.gl.uniform1i(this.gl.getUniformLocation(this.program,"u_depthMap"),1),this.gl.uniform1i(this.gl.getUniformLocation(this.program,"u_hasDepth"),e?1:0),this.gl.uniform2f(this.gl.getUniformLocation(this.program,"u_resolution"),i,s),this.gl.uniform2f(this.gl.getUniformLocation(this.program,"u_imageResolution"),t.naturalWidth,t.naturalHeight);const r=this.gl.getAttribLocation(this.program,"a_position");this.gl.enableVertexAttribArray(r),this.gl.bindBuffer(this.gl.ARRAY_BUFFER,this.positionBuffer),this.gl.vertexAttribPointer(r,2,this.gl.FLOAT,!1,0,0),this.gl.viewport(0,0,i,s),this.draw()}draw(){this.gl.drawArrays(this.gl.TRIANGLES,0,6)}destroy(){cancelAnimationFrame(this.animationFrameId)}}var s=function(t,e,i,s){return new(i||(i=Promise))(function(r,a){function n(t){try{h(s.next(t))}catch(t){a(t)}}function o(t){try{h(s.throw(t))}catch(t){a(t)}}function h(t){var e;t.done?r(t.value):(e=t.value,e instanceof i?e:new i(function(t){t(e)})).then(n,o)}h((s=s.apply(t,e||[])).next())})};class r{constructor(t,e={}){this.currentFrame=-1,this.activeVariant=null,this.canvas=null,this.ctx=null,this.renderer=null,this.basePath="",this.scrub=0,this.targetProgress=0,this.currentProgress=0,this.rafId=0,this.destroyed=!1,this.imageCache=new Map,this.depthCache=new Map,this.scrollTimeout=null,this.trackingDataCache=new Map,this.config=t,this.basePath=t.settings.basePath||"",this.scrub=e.scrub||0,this.detectBestVariant(),this.boundResize=()=>{this.detectBestVariant(),this.resizeCanvas(),this.render()},window.addEventListener("resize",this.boundResize),this.updateLoop=this.updateLoop.bind(this),this.rafId=requestAnimationFrame(this.updateLoop)}destroy(){this.destroyed=!0,this.rafId&&cancelAnimationFrame(this.rafId),window.removeEventListener("resize",this.boundResize),this.scrollTimeout&&clearTimeout(this.scrollTimeout),this.clearCache(),this.trackingDataCache.clear(),this.canvas=null,this.ctx=null,this.renderer=null,this.onFrameChange=void 0}static init(t,e){return s(this,void 0,void 0,function*(){const i=yield fetch(e);if(!i.ok)throw new Error(`Failed to load config: ${i.statusText}`);const s=yield i.json(),a=e.substring(0,e.lastIndexOf("/"));s.settings||(s.settings={baseResolution:{width:1920,height:1080},scrollMode:"vh"}),s.settings.basePath=s.settings.basePath||a;const n=new r(s,{scrub:"object"==typeof s.settings?s.settings.scrub:0});let o=t.querySelector("canvas");return o||(o=document.createElement("canvas"),o.style.width="100%",o.style.height="100%",o.style.display="block",o.style.objectFit="cover",t.appendChild(o)),n.attachCanvas(o),n})}attachCanvas(t){this.canvas=t;try{this.renderer=new i(t)}catch(e){console.warn("WebGL failed, falling back to 2D",e),this.ctx=t.getContext("2d",{alpha:!1})}this.resizeCanvas(),this.render()}resizeCanvas(){if(!this.canvas)return;const t=window.innerWidth,e=window.innerHeight,i=window.devicePixelRatio||1;this.canvas.width=t*i,this.canvas.height=e*i,this.ctx&&this.ctx.scale(i,i)}detectBestVariant(){var t;const e=this.config.assets[0];if(!e)return;const i=this.canvas?this.canvas.getBoundingClientRect():{width:window.innerWidth,height:window.innerHeight},s=i.height>i.width,r=i.width*(window.devicePixelRatio||1),a=e.variants.filter(t=>{const e="portrait"===t.orientation||parseInt(t.aspectRatio.split(":")[1])>parseInt(t.aspectRatio.split(":")[0]);return s===e});a.sort((t,e)=>t.frameCount-e.frameCount);const n=a.find(t=>t.width>=r)||a[a.length-1];n?(null===(t=this.activeVariant)||void 0===t?void 0:t.id)!==n.id&&(console.log(`🎯 Variant Switched: ${n.id} (${s?"Portrait":"Landscape"})`),this.activeVariant=n,this.clearCache(),this.preloadInitial()):console.warn("[CoreEngine] No suitable variant found")}clearCache(){this.imageCache.clear(),this.depthCache.clear()}preloadInitial(){for(let t=0;t<15;t++)this.getImage(t)}update(t){this.targetProgress=Math.max(0,Math.min(1,t))}updateLoop(){if(this.destroyed)return;this.rafId=requestAnimationFrame(this.updateLoop);const t=this.scrub;if(t>0){const e=Math.max(.01,1-t);this.currentProgress+=(this.targetProgress-this.currentProgress)*e}else this.currentProgress=this.targetProgress;Math.abs(this.targetProgress-this.currentProgress)<1e-4&&(this.currentProgress=this.targetProgress),this.calculateFrame(this.currentProgress)}calculateFrame(t){const e=this.config.timeline.scenes[0];if(!e)return;const i=e.assetRange[1]-e.assetRange[0],s=Math.floor(e.assetRange[0]+t*i),r=Math.max(0,Math.min(s,e.assetRange[1]));r!==this.currentFrame&&(this.currentFrame=r,this.render(),this.getImage(this.currentFrame+5),this.getImage(this.currentFrame+10),this.scrollTimeout&&clearTimeout(this.scrollTimeout),this.scrollTimeout=setTimeout(()=>{this.loadDepthMap(this.currentFrame)},100),this.onFrameChange&&this.onFrameChange(this.currentFrame,t))}loadTrackingData(t){return s(this,void 0,void 0,function*(){var e;if(!this.activeVariant)return;if(!(null===(e=this.activeVariant.subjects)||void 0===e?void 0:e.includes(t)))return void console.warn(`[CoreEngine] Subject ${t} not found in active variant ${this.activeVariant.id}`);const i=`${this.activeVariant.id}_${t}`;if(!this.trackingDataCache.has(i))try{const e=`${this.basePath?`${this.basePath}/`:""}${this.activeVariant.path}/000_tracking-${t}.json`;console.log(`[CoreEngine] Fetching tracking data: ${e}`);const s=yield fetch(e);if(!s.ok)throw new Error(s.statusText);const r=yield s.json();this.trackingDataCache.set(i,r)}catch(e){console.error(`[CoreEngine] Failed to load tracking data for ${t}`,e)}})}getTrackedCoords(t,e){if(!this.activeVariant)return{x:.5,y:.5};const i=`${this.activeVariant.id}_${t}`,s=this.trackingDataCache.get(i);if(!s)return{x:.5,y:.5};const r=s.find(t=>t.frame===e);return r?{x:r.x,y:r.y,scale:r.scale}:{x:.5,y:.5}}render(){var t;if(!this.canvas||-1===this.currentFrame)return;const e=this.getImage(this.currentFrame);if(!e||!e.complete)return;const i=window.innerWidth,s=window.innerHeight;let r=null;if((null===(t=this.activeVariant)||void 0===t?void 0:t.hasDepthMap)&&(r=this.getDepthImage(this.currentFrame),r&&!r.complete&&(r=null)),this.renderer)this.renderer.render(e,r,i*(window.devicePixelRatio||1),s*(window.devicePixelRatio||1));else if(this.ctx){const t=e.naturalWidth/e.naturalHeight;let r,a,n,o;t>i/s?(a=s,r=s*t,n=(i-r)/2,o=0):(r=i,a=i/t,n=0,o=(s-a)/2),this.ctx.clearRect(0,0,i,s),this.ctx.drawImage(e,n,o,r,a)}}getImage(t){if(!this.activeVariant)return null;if(t<0||t>=this.activeVariant.frameCount)return null;const e=`${this.activeVariant.id}_${t}`;if(this.imageCache.has(e))return this.imageCache.get(e);const i=this.basePath?`${this.basePath}/`:"",s=new Image;return s.crossOrigin="anonymous",s.src=`${i}${this.activeVariant.path}/index_${t}.webp`,s.onload=()=>{this.currentFrame===t&&this.render()},this.imageCache.set(e,s),s}loadDepthMap(t){var e;if(!(null===(e=this.activeVariant)||void 0===e?void 0:e.hasDepthMap))return void console.log("[CoreEngine] activeVariant does not define hasDepthMap=true");console.log(`[CoreEngine] Lazy requesting depth map for frame: ${t}`);this.getDepthImage(t)}getDepthImage(t){var e;if(!(null===(e=this.activeVariant)||void 0===e?void 0:e.hasDepthMap))return null;if(t<0||t>=this.activeVariant.frameCount)return null;const i=`${this.activeVariant.id}_depth_${t}`;if(this.depthCache.has(i))return this.depthCache.get(i);const s=this.basePath?`${this.basePath}/`:"";console.log(`[CoreEngine] Downloading: ${s}${this.activeVariant.path}/index_${t}_depth.webp`);const r=new Image;return r.crossOrigin="anonymous",r.src=`${s}${this.activeVariant.path}/index_${t}_depth.webp`,r.onload=()=>{console.log(`[CoreEngine] Depth map loaded for frame: ${t}`),this.currentFrame===t&&this.render()},r.onerror=e=>{console.error(`[CoreEngine] Depth map failed to load for frame: ${t}`,e)},this.depthCache.set(i,r),r}}const a=r;return e=e.default})());

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * SCROLLCRAFT 2.0 - DECLARATIVE SCHEMA
+ * SCROLLCRAFT - DECLARATIVE SCHEMA
  *
  * This file defines the core data structures that allow an AI Agent
  * to describe a scroll experience in one step.
@@ -11,12 +11,12 @@ export interface ProjectConfiguration {
     timeline: TimelineDefinition;
 }
 export interface ProjectSettings {
-    fps: number;
     baseResolution: {
         width: number;
         height: number;
     };
     scrollMode: 'vh' | 'px';
+    basePath?: string;
 }
 /**
  * ASSET SYSTEM
@@ -32,8 +32,11 @@ export interface AssetVariant {
     path: string;
     aspectRatio: string;
     frameCount: number;
+    width: number;
+    height: number;
+    orientation: 'portrait' | 'landscape';
     hasDepthMap?: boolean;
-    subjectTracking?: SubjectFrameData[];
+    subjects?: string[];
 }
 export interface SubjectFrameData {
     frame: number;
@@ -97,76 +100,3 @@ export interface LayerAnimation {
     end: number;
     easing?: string;
 }
-/**
- * LEGACY TYPES (V1 Compatibility)
- * These are required for existing modules to compile.
- */
-export interface BlockInstanceInterface {
-    destroy(): void;
-    resize(params: {
-        wiWidth: number;
-        wiHeight: number;
-    }): void;
-}
-export type MediaGroupPositionAndSize = {
-    bgSize?: 'contain' | 'cover' | 'custom';
-    bgPosition?: {
-        x: number;
-        y: number;
-    };
-};
-export type ImagesUrlListArray = Array<string | {
-    i: string;
-    dur?: number;
-}>;
-export type ImageGroupUrlList = MediaGroupPositionAndSize & {
-    type: 'urlList';
-    prefix?: string;
-    suffix?: string;
-    images: ImagesUrlListArray;
-    duration?: number;
-};
-export type ImageGroupGap = {
-    type: 'gap';
-    duration: number;
-};
-export type VideoGroupUrl = MediaGroupPositionAndSize & {
-    type: 'urlVideo';
-    video?: string;
-    duration?: number;
-};
-export type ImageGroupWp = MediaGroupPositionAndSize & {
-    type: 'wpMedia';
-    images: number[];
-    duration?: number;
-};
-export type VideoGroupWp = MediaGroupPositionAndSize & {
-    type: 'wpVideo';
-    video?: number;
-    duration?: number;
-};
-export type MediaGroup = ImageGroupGap | ImageGroupUrlList | VideoGroupUrl | ImageGroupWp | VideoGroupWp;
-export type MediaGroups = MediaGroup[];
-export type AttributesCanvas2d = {
-    mediaGroups: MediaGroups;
-    markers: boolean;
-    scrub: number;
-    triggerStart: number;
-    triggerEnd: number;
-    pin: boolean;
-    pinSpacing: boolean;
-};
-export type AttributesScene = {
-    scenePosition: 'flow' | 'sticky' | 'fixed';
-    stickyType: 'css' | 'js';
-    height: number;
-    heightUnit: string;
-    duration: number;
-    durationUnit: string;
-    top: number;
-    topUnit: string;
-    markers: boolean;
-    scrub: number;
-    triggerStart: number;
-    triggerEnd: number;
-};