scrolltube 2.1.3 → 2.1.4

package/AGENTS.md

@@ -1,47 +1,61 @@
-<!-- BEGIN:scrolltube-agent-rules -->
-# ScrollTube Implementation Protocol
-
-This document is for AI agents tasked with implementing ScrollTube in a host application. 
-
-## 🤖 Agent Persona
-You are a ScrollTube Implementation Expert. Your goal is to transform static media into high-performance, interactive scroll experiences.
-
-## 🛠️ Implementation Workflow
-
-### Step 1: Asset Preparation (The CLI)
-Before writing any UI code, you MUST process the raw assets (video or images) into a ScrollTube project.
-```bash
-npx scrolltube create <input_path> --cloud --depth --track "main subject"
-
-```
-- **Why?** This generates optimized multi-resolution frames, optional AI-tracked subject coordinates, and optional depth maps.
-- **Output**: A directory containing `scrolltube.json` and variant folders (`mobile/`, `desktop/`).
-
-### Step 2: Project Architecture (React)
-Import the generated `scrolltube.json` and wrap your scene in the `ScrollTubeProvider`.
-```tsx
-import project from './path/to/scrolltube.json';
-import { ScrollTubeProvider, ScrollTubeCanvas, SubjectLayer } from 'scrolltube/react';
-
-// Goal: 1 ScrollTubeProvider per interactive section.
-```
-
-### Step 3: Immersive Layering
-Use high-level components to build the scene. Avoid manual coordinate math.
-- **`<ScrollTubeCanvas />`**: Renders the image sequence (WebGL).
-- **`<SubjectLayer />`**: Pins HTML content to the moving product automatically.
-- **`useScrollTube()`**: Hook for custom triggers based on `progress` (0-1) or `frame`.
-
-## 📚 Docs
-- [**Core Architecture**](docs/architecture.md): Understand the State-Snapshot Engine.
-- [**Asset Pipeline**](docs/asset-pipeline.md): Detailed CLI options (Smart-Crop, Variants, Step).
-- [**React Integration**](docs/react-integration.md): Component API reference.
-- [**AI Protocol**](docs/ai-integration.md): How to prompt other agents to build creative scenes for you.
-
-## ⚠️ Critical Constraints
-1. **Coordination System**: ALWAYS use percentages (0-100) for Layer offsets relative to the Subject Focal Point.
-2. **Performance**: Recommend `--step 2` or `--step 3` for mobile-first projects to reduce payload.
-3. **Responsive**: The engine handles folder swapping (Mobile/Desktop) automatically based on viewport.
-4. **Interactive**: Enable `depthEnabled` on the Canvas for 3D parallax effects if depth maps exist.
-
-<!-- END:scrolltube-agent-rules -->
+<!-- BEGIN:scrolltube-agent-rules -->
+
+## ScrollTube Orchestration Protocol (for AI Agents)
+
+This document defines the technical persona and workflow for AI agents tasked with implementing ScrollTube experiences.
+
+## 🤖 Agent Persona
+You are a **ScrollTube Orchestration Specialist**. You move away from imperative animation math and towards declarative scene design. Your goal is to transform raw media into immersive experiences using the ScrollTube Universal SDK.
+
+## 🛠️ The Two-Phase Workflow
+
+### Phase A: Asset Intelligence (CLI)
+Before writing UI code, you must initialize the project by processing raw media.
+```bash
+npx scrolltube create <input_path> --name "my-project" --track "main subject" --cloud --depth
+```
+- **Inputs**: Path to video or directory of images.
+- **Why?** This generates optimized multi-resolution frames, AI-tracked coordinates, and 3D depth maps.
+- **Output**: A directory with `scrolltube.json`, variants, and a backup of the source media.
+
+### Phase B: Immersive Implementation (React)
+Import the generated JSON and build the UI. Use the provider to sync the engine with React state.
+
+```tsx
+import project from './my-project/scrolltube.json';
+import { ScrollTubeProvider, ScrollTubeCanvas, SubjectLayer } from 'scrolltube/react';
+
+export const MyExperience = () => (
+  // 1. Set global scroll duration and smoothing
+  <ScrollTubeProvider containerHeight="300vh" scrub={0.1}>
+    
+    {/* 2. Render the WebGL layer (Supports JSON Object or URL) */}
+    <ScrollTubeCanvas project={project} depthtilt={0.3} />
+    
+    {/* 3. Pin UI to the tracked subject automatically */}
+    <SubjectLayer id="main" offset={{ x: 10, y: -5 }}>
+      <div className="info-box">
+        Hello From ScrollTube
+      </div>
+    </SubjectLayer>
+
+  </ScrollTubeProvider>
+);
+```
+
+## 📚 Technical Protocol for Child Agents
+If you are prompting another agent to build a scene, include this snippet:
+
+> You are a ScrollTube specialist. Follow these principles:
+> 1. **Engine-Aware**: Use 'ScrollTubeProvider' for state synchronization.
+> 2. **Subject-Focal**: Use 'SubjectLayer' to pin UI to tracked coordinates.
+> 3. **Declarative**: Use 'useScrollTube()' for progress (0-1) and frame hooks.
+> 4. **Responsive**: For Mobile, place text layers ABOVE or BELOW the subject focal point. For Desktop, place them to the SIDES.
+
+## ⚠️ Critical Constraints
+1. **Coordinates**: Use Subject-Relative offsets in 'SubjectLayer' for perfect pinning.
+2. **Sync**: Never use manual scroll listeners; the engine drives all child animations.
+3. **Performance**: Recommend `--step 10` for fast previews and `--step 1` or `2` for high-end production.
+4. **Hardware**: Enable `depthtilt` on the Canvas for 3D parallax effects if depth maps exist.
+
+<!-- END:scrolltube-agent-rules -->

package/README.md

@@ -4,7 +4,7 @@
 
 ScrollTube 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.
 
-[scroll.tube](https://www.scroll.tube)
+[www.scroll.tube](https://www.scroll.tube)
 
 ---
 
@@ -59,7 +59,6 @@ const project = await pipeline.create({
 All you have to do now, is to drop the scrolltube.json project into your ScrollTubeProvider.
 
 #### Vanilla JS Integration
-For full implementation, please refer to the [Vanilla JS Example](https://github.com/aleskozelsky/scrolltube/blob/main/demos/html/index.html).
 
 [Live Demo](https://demo-html.scroll.tube) 
 
@@ -74,9 +73,9 @@ For full implementation, please refer to the [Vanilla JS Example](https://github
 </script>
 ```
 
+For full implementation, please refer to the [Vanilla JS Example](https://github.com/aleskozelsky/scrolltube/blob/main/demos/html/index.html).
 
 #### React Integration
-For full implementation, please refer to the [React Integration Example](https://github.com/aleskozelsky/scrolltube/blob/main/demos/create-next-app/src/app/page.tsx).
 
 [Live Demo](https://demo-nextjs.scroll.tube) 
 
@@ -122,6 +121,8 @@ const AppleInfo = () => {
 
 ```
 
+For full implementation, please refer to the [React Integration Example](https://github.com/aleskozelsky/scrolltube/blob/main/demos/create-next-app/src/app/page.tsx).
+
 ---
 
 ## Documentation & Guides

package/dist/cli/index copy.d.ts

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

package/dist/cli/index copy.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+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 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 scrolltube.config.js/ts in the current working directory.
+ */
+async function loadProjectConfig() {
+    const possiblePaths = [
+        path.join(process.cwd(), 'scrolltube.cli.config.js'),
+        path.join(process.cwd(), 'scrolltube.cli.config.cjs'),
+        path.join(process.cwd(), 'scrolltube.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.
+ */
+function getFFmpegPath() {
+    // 1. Try bundled ffmpeg-static
+    if (ffmpeg_static_1.default)
+        return ffmpeg_static_1.default;
+    // 2. Try system PATH
+    try {
+        (0, child_process_1.execSync)('ffmpeg -version', { stdio: 'ignore' });
+        return 'ffmpeg';
+    }
+    catch (e) {
+        return null;
+    }
+}
+const program = new commander_1.Command();
+program
+    .name('scrolltube')
+    .description('ScrollTube 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 ScrollTube')
+    .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')
+    .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')
+    .option('--depth', 'Generate a 3D depth map for the displacement effect (Requires --cloud)')
+    .action(async (inputArg, opts) => {
+    console.log(chalk_1.default.bold.blue('\n🎞️  ScrollTube Asset Pipeline\n'));
+    // 0. PRE-FLIGHT CHECK
+    const ffmpegPath = getFFmpegPath();
+    if (!ffmpegPath) {
+        console.error(chalk_1.default.red('\n❌ FFmpeg not found!'));
+        console.log(chalk_1.default.yellow('This CLI requires FFmpeg to process videos.'));
+        console.log('Please install it manually or ensure regular npm install was successful.');
+        process.exit(1);
+    }
+    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)
+    while (!input || !fs.existsSync(input)) {
+        if (input && !fs.existsSync(input)) {
+            console.error(chalk_1.default.red(`\n❌ Error: Input path "${input}" does not exist.`));
+        }
+        input = await prompt('Path to input video or directory of images');
+    }
+    // 2. PROJECT NAME & SETTINGS
+    if (!projectName) {
+        projectName = await prompt('Project name', 'scrolltube-project');
+    }
+    let step = parseInt(opts.step) || 1;
+    if (!inputArg) {
+        // 2. PROJECT SETTINGS
+        const stepInput = await prompt('Process every Nth frame (Step size)', '1');
+        step = parseInt(stepInput) || 1;
+        // 3. AI TRACKING & DEPTH
+        const trackPrompt = await prompt('AI Subject Tracking? (e.g. "red car", leave empty to skip)');
+        if (trackPrompt) {
+            useTracking = true;
+            track = trackPrompt;
+        }
+        const depthPrompt = await prompt('Generate 3D depth map? (y/n)', 'n');
+        useDepth = depthPrompt.toLowerCase().startsWith('y');
+    }
+    // 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
+        }
+    });
+    try {
+        await pipeline.create({
+            input: input,
+            name: projectName,
+            track: useTracking ? track : undefined,
+            depth: 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: ${projectName}`));
+        console.log(chalk_1.default.white(`📜 Config: scrolltube.json`));
+        console.log(chalk_1.default.cyan(`\nNext: Import the .json into your <ScrollTubeCanvas project={...} />\n`));
+    }
+    catch (err) {
+        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♻️  ScrollTube Update Pipeline\n'));
+    const projectPath = path.resolve(dir);
+    const configPath = path.join(projectPath, 'scrolltube.json');
+    if (!fs.existsSync(configPath)) {
+        console.error(chalk_1.default.red('❌ Not a valid ScrollTube project directory (missing scrolltube.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}`));
+    }
+    console.log(chalk_1.default.red('⚠️  UNDER CONSTRUCTION'));
+    console.log(chalk_1.default.yellow('The "update" command is currently being refactored for the Universal Pipeline.'));
+    console.log(chalk_1.default.dim('Please use "scft create" to regenerate your project for now.\n'));
+    process.exit(0);
+});
+program.parse(process.argv);

package/dist/cli/index.js

@@ -148,12 +148,12 @@ program
     .description('ONE-STEP: Transform video/images into a responsive ScrollTube')
     .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('-p, --track <text>', 'Text prompt for subject tracking')
     .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)
+    .option('--cloud', 'Use Fal.ai for tracking and refinement')
+    .option('--depth', 'Generate a 3D depth map for the displacement effect (Requires --cloud)')
     .action(async (inputArg, opts) => {
     console.log(chalk_1.default.bold.blue('\n🎞️  ScrollTube Asset Pipeline\n'));
     // 0. PRE-FLIGHT CHECK
@@ -186,11 +186,37 @@ program
     if (!inputArg) {
         const stepInput = await prompt('Process every Nth frame (Step size)', '1');
         step = parseInt(stepInput) || 1;
+        // New Interactive Prompts
+        const trackSubject = await prompt(`Track a specific subject? ${chalk_1.default.dim('(Optional, AI requires key - e.g. "red car")')}`, '');
+        if (trackSubject) {
+            track = trackSubject;
+            useTracking = true;
+        }
+        const wantDepth = await prompt(`Generate 3D depth maps? ${chalk_1.default.dim('(Optional, AI requires key)')} [y/N]`, 'n');
+        if (wantDepth.toLowerCase() === 'y') {
+            useDepth = true;
+        }
+    }
+    // 3. KEY & AI VALIDATION
+    const stubeKey = process.env.SCROLLTUBE_KEY;
+    const falKey = process.env.FAL_KEY;
+    const hasKey = !!(stubeKey || falKey);
+    if ((useTracking || useDepth) && !hasKey) {
+        console.log(chalk_1.default.yellow(`\n⚠️  The AI features you selected (${[useTracking ? 'Tracking' : '', useDepth ? 'Depth' : ''].filter(Boolean).join('/')}) require a Cloud Key.`));
+        console.log(chalk_1.default.white('To enable these features, please:'));
+        console.log(chalk_1.default.white(`   1. Get a key at ${chalk_1.default.bold.cyan('https://scroll.tube/api-key')}`));
+        console.log(chalk_1.default.white(`   2. Set it in your .env: ${chalk_1.default.bold('SCROLLTUBE_KEY')}='scrolltube_key_****************' ${chalk_1.default.dim('(or FAL_KEY)')}\n`));
+        const choice = await prompt('Continue without AI features (local fallback)? [y/N]', 'n');
+        if (choice.toLowerCase() !== 'y') {
+            console.log(chalk_1.default.red('\nProcess aborted. Please set your API key and try again.\n'));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.dim('\nFalling back to local processing (center-pinned, no depth)...\n'));
+        useTracking = false;
+        useDepth = false;
     }
-    // AI Tracking logic preserved in CLI wrapper...
-    // ...
     const pipeline = new pipeline_1.AssetPipeline({
-        apiKey: process.env.FAL_KEY,
+        apiKey: hasKey ? (stubeKey || falKey) : undefined,
         onProgress: (p) => {
             // You could add a progress bar here
         }
@@ -207,7 +233,7 @@ program
         console.log(chalk_1.default.bold.green(`\n✅ Project Created Successfully!`));
         console.log(chalk_1.default.white(`📍 Output: ${projectName}`));
         console.log(chalk_1.default.white(`📜 Config: scrolltube.json`));
-        console.log(chalk_1.default.cyan(`\nNext: Import the .json into your <ScrollTubeProvider />\n`));
+        console.log(chalk_1.default.cyan(`\nNext: Import the .json into your <ScrollTubeCanvas project={...} />\n`));
     }
     catch (err) {
         console.error(chalk_1.default.red(`\n❌ Error during pipeline: ${err.message}`));
@@ -234,7 +260,7 @@ program
     }
     console.log(chalk_1.default.red('⚠️  UNDER CONSTRUCTION'));
     console.log(chalk_1.default.yellow('The "update" command is currently being refactored for the Universal Pipeline.'));
-    console.log(chalk_1.default.dim('Please use "scft create" to regenerate your project for now.\n'));
+    console.log(chalk_1.default.dim('Please use "scrolltube create" to regenerate your project for now.\n'));
     process.exit(0);
 });
 program.parse(process.argv);

package/dist/cli/index_salvaged.d.ts

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

package/dist/cli/index_salvaged.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+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 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.
+ */
+function getFFmpegPath() {
+    // 1. Try bundled ffmpeg-static
+    if (ffmpeg_static_1.default)
+        return ffmpeg_static_1.default;
+    // 2. Try system PATH
+    try {
+        (0, child_process_1.execSync)('ffmpeg -version', { stdio: 'ignore' });
+        return 'ffmpeg';
+    }
+    catch (e) {
+        return null;
+    }
+}
+const program = new commander_1.Command();
+program
+    .name('scft')
+    .description('ScrollCraft CLI - Immersive Web SDK')
+    .version(pkg.version);
+/**
+ * Interactive Helper
+ */
+async function interactiveHelper(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 (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 AI for tracking and refinement', false)
+    .option('--depth', 'Generate a 3D depth map for the displacement effect', false)
+    .action(async (inputArg, opts) => {
+    console.log(chalk_1.default.bold.blue('\n🎞️  ScrollCraft Asset Pipeline\n'));
+    // 0. PRE-FLIGHT CHECK
+    const ffmpegPath = getFFmpegPath();
+    if (!ffmpegPath) {
+        console.error(chalk_1.default.red('\n❌ FFmpeg not found!'));
+        console.log(chalk_1.default.yellow('This CLI requires FFmpeg to process videos.'));
+        console.log('Please install it manually or ensure regular npm install was successful.');
+        process.exit(1);
+    }
+    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 interactiveHelper('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 interactiveHelper('Project name', 'scrollcraft-project');
+    }
+    let step = parseInt(opts.step) || 1;
+    if (!inputArg) {
+        const stepInput = await interactiveHelper('Process every Nth frame (Step size)', '1');
+        step = parseInt(stepInput) || 1;
+        // New Interactive Prompts
+        const trackSubject = await interactiveHelper(`Track a specific subject? ${chalk_1.default.dim('(Optional, AI requires key - e.g. "red car")')}`, '');
+        if (trackSubject) {
+            track = trackSubject;
+            useTracking = true;
+        }
+        const wantDepth = await interactiveHelper(`Generate 3D depth maps? ${chalk_1.default.dim('(Optional, AI requires key)')} [y/N]`, 'n');
+        if (wantDepth.toLowerCase() === 'y') {
+            useDepth = true;
+        }
+    }
+    // 3. KEY & AI VALIDATION
+    const scftKey = process.env.SCROLLCRAFT_KEY;
+    const falKey = process.env.FAL_KEY;
+    const hasKey = !!(scftKey || falKey);
+    if ((useTracking || useDepth) && !hasKey) {
+        console.log(chalk_1.default.yellow(`\n⚠️  The AI features you selected (${[useTracking ? 'Tracking' : '', useDepth ? 'Depth' : ''].filter(Boolean).join('/')}) require a Cloud Key.`));
+        console.log(chalk_1.default.white('To enable these features, please:'));
+        console.log(chalk_1.default.white(`   1. Get a key at ${chalk_1.default.bold.cyan('https://scrollcraft.dev/api-key')}`));
+        console.log(chalk_1.default.white(`   2. Set it in your .env: ${chalk_1.default.bold('SCROLLCRAFT_KEY')}='your_key' ${chalk_1.default.dim('(or FAL_KEY)')}\n`));
+        console.log(chalk_1.default.dim('Falling back to local processing (center-pinned, no depth)...\n'));
+        useTracking = false;
+        useDepth = false;
+    }
+    const pipeline = new pipeline_1.AssetPipeline({
+        apiKey: scftKey || falKey,
+        onProgress: (p) => {
+            // Progress reporting
+        }
+    });
+    try {
+        await pipeline.create({
+            input: input,
+            name: projectName,
+            track: useTracking ? track : undefined,
+            depth: 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: ${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 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}`));
+    }
+    console.log(chalk_1.default.red('⚠️  UNDER CONSTRUCTION'));
+    console.log(chalk_1.default.yellow('The "update" command is currently being refactored for the Universal Pipeline.'));
+    console.log(chalk_1.default.dim('Please use "scft create" to regenerate your project for now.\n'));
+    process.exit(0);
+});
+program.parse(process.argv);

package/docs/ai-integration.md

@@ -13,7 +13,7 @@ The agent should first use the CLI to process raw media into an intelligent Scro
 npx scrolltube create input.mp4 --name "my-project" --track "main product" --cloud --depth
 
 ```
-**Output:** A directory containing optimized frames, depth maps, and a `scrolltube.json` file.
+**Output:** A directory containing optimized frames, depth maps in variants for specific resolutions and a `scrolltube.json` file and a copy of the source - raw media.
 
 ### Phase B: Immersive Implementation (React)
 The agent then uses the generated JSON to build the UI components.
@@ -31,7 +31,7 @@ export const MyExperience = () => (
         {/* Pins content to the tracked subject automatically */}
         <SubjectLayer offset={{ x: 10, y: -5 }}>
           <div className="info-box">
-             Premium Tubesmanship
+            Hello From ScrollTube
           </div>
         </SubjectLayer>
       </div>
@@ -72,3 +72,9 @@ This workflow enables a powerful business model:
 3. **The AI Agent** uses that intelligence to write the perfectly synced creative layer.
 
 You provide the **SDK**, the AI provides the **Implementation**.
+yer.
+
+You provide the **SDK**, the AI provides the **Implementation**.
+yer.
+
+You provide the **SDK**, the AI provides the **Implementation**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrolltube",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "ScrollTube is a web-based tool for scroll-triggered animations.",
   "main": "dist/core/scrolltube.umd.min.js",
   "module": "dist/core/scrolltube.umd.min.js",