scrolltube 2.1.2 → 2.1.3

package/AGENTS.md

@@ -11,7 +11,8 @@ You are a ScrollTube Implementation Expert. Your goal is to transform static med
 ### 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 stube create <input_path> --cloud --depth --prompt "main subject" [-s 2]
+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/`).

package/README.md

@@ -28,7 +28,8 @@ Transform your video into a ScrollTube project from your terminal:
 
 ```bash
 # This will extract frames, track the subject, and generate optimized variants and depth maps.
-npx stube create "your-video.mp4" --name "my-project" --track "apple" --cloud --depth
+npx scrolltube create "your-video.mp4" --name "my-project" --track "apple" --cloud --depth
+
 ```
 
 #### Programmatic Usage (Browser/Node)

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,240 @@
+#!/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', '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 (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) {
+        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
+        }
+    });
+    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 <ScrollTubeProvider />\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/core/types.d.ts

@@ -9,6 +9,7 @@ export interface ProjectConfiguration {
     settings: ProjectSettings;
     assets: SequenceAsset[];
     timeline: TimelineDefinition;
+    source?: string;
 }
 export interface ProjectSettings {
     baseResolution: {

package/dist/pipeline/browser-driver.d.ts

@@ -8,7 +8,12 @@ export declare class BrowserDriver implements IPipelineDriver {
     exists(path: string): Promise<boolean>;
     readdir(dirPath: string): Promise<string[]>;
     remove(path: string): Promise<void>;
+    copyFile(src: string, dest: string): Promise<void>;
     join(...parts: string[]): string;
+    getVideoDimensions(input: string | File | Blob): Promise<{
+        width: number;
+        height: number;
+    }>;
     resolve(...parts: string[]): string;
     /**
      * EXTRACT FRAMES (via ffmpeg.wasm)

package/dist/pipeline/browser-driver.js

@@ -80,9 +80,38 @@ class BrowserDriver {
             }
         }
     }
+    async copyFile(src, dest) {
+        const data = await this.readFile(src);
+        await this.writeFile(dest, data);
+    }
     join(...parts) {
         return parts.join('/').replace(/\/+/g, '/');
     }
+    async getVideoDimensions(input) {
+        return new Promise((resolve, reject) => {
+            let url;
+            if (typeof input === 'string') {
+                // Fallback for paths if they represent URLs in browser
+                url = input;
+            }
+            else {
+                url = URL.createObjectURL(input);
+            }
+            const video = document.createElement('video');
+            video.onloadedmetadata = () => {
+                const dimensions = { width: video.videoWidth, height: video.videoHeight };
+                if (typeof input !== 'string')
+                    URL.revokeObjectURL(url);
+                resolve(dimensions);
+            };
+            video.onerror = (e) => {
+                if (typeof input !== 'string')
+                    URL.revokeObjectURL(url);
+                reject(new Error('Failed to load video metadata in browser.'));
+            };
+            video.src = url;
+        });
+    }
     resolve(...parts) {
         return this.join(...parts);
     }
@@ -109,7 +138,7 @@ class BrowserDriver {
             const inputName = 'input.mp4';
             await ffmpeg.writeFile(inputName, await fetchFile(videoSource));
             // Extract as PNGs/WebPs (WebP might be faster if supported in the WASM build)
-            await ffmpeg.exec(['-i', inputName, `${outputDir}/frame_%04d.png`]);
+            await ffmpeg.exec(['-hide_banner', '-loglevel', 'error', '-i', inputName, `${outputDir}/frame_%04d.png`]);
             // Move files from FFmpeg VFS to our Map FS
             const files = await ffmpeg.listDir(outputDir);
             for (const file of files) {

package/dist/pipeline/index.d.ts

@@ -17,5 +17,5 @@ export declare class AssetPipeline {
     create(opts: CreateCommandOptions): Promise<ProjectConfiguration | Uint8Array<ArrayBufferLike>>;
     private normalizeVariants;
     private processVariants;
-    saveConfig(variants: AssetVariant[], outDir: string): Promise<ProjectConfiguration>;
+    saveConfig(variants: AssetVariant[], outDir: string, sourcePath?: string): Promise<ProjectConfiguration>;
 }

package/dist/pipeline/index.js

@@ -32,9 +32,13 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssetPipeline = void 0;
 const cloud_service_1 = require("./cloud-service");
+const chalk_1 = __importDefault(require("chalk"));
 class AssetPipeline {
     driver;
     options;
@@ -88,11 +92,76 @@ class AssetPipeline {
         const tempDir = this.driver.join(outDir, '.temp-frames');
         const framesDir = this.driver.join(tempDir, 'frames');
         const depthsDir = this.driver.join(tempDir, 'depths');
+        // Inform users of agents using this command, that this may take a few minutes to complete. 
+        console.log(chalk_1.default.yellow('\n⚠️  This may take a few minutes to complete.\n'));
         this.report('initializing', 0, `Creating project: ${name}`);
         await this.driver.mkdir(outDir);
         await this.driver.mkdir(tempDir);
         await this.driver.mkdir(framesDir);
         await this.driver.mkdir(depthsDir);
+        // 0. PRE-FLIGHT: DIMENSIONS & VARIANT FILTERING
+        this.report('initializing', 5, 'Detecting source dimensions...');
+        let sourceDimensions = { width: 1920, height: 1080 }; // Default fallback
+        try {
+            sourceDimensions = await this.driver.getVideoDimensions(input);
+            console.log(chalk_1.default.cyan(`🎞️  Source Resolution: ${sourceDimensions.width}x${sourceDimensions.height}`));
+        }
+        catch (e) {
+            console.warn(chalk_1.default.yellow(`⚠️  Could not detect source dimensions. Proceeding with defaults.`));
+        }
+        const requestedVariants = this.normalizeVariants(opts.variants);
+        const validVariants = requestedVariants.filter(v => {
+            const isTooLarge = v.width > sourceDimensions.width || v.height > sourceDimensions.height;
+            if (isTooLarge) {
+                console.warn(chalk_1.default.yellow(`⚠️  Skipping variant ${v.id} (${v.width}x${v.height}) as it exceeds source resolution. (Upscaling is disabled)`));
+                return false;
+            }
+            return true;
+        });
+        if (validVariants.length === 0 && requestedVariants.length > 0) {
+            console.warn(chalk_1.default.bold.red(`\n❌ All requested variants were too large for the source video!`));
+            console.log(chalk_1.default.white(`Hint: Upscale your video first, or request smaller variants.\n`));
+            // Re-add at least one matching the source? No, let's let the user decide or use a safe fallback.
+            // For now, let's use the source resolution as a single variant if everything else failed.
+            const sourceVariant = {
+                id: 'source-res',
+                width: sourceDimensions.width,
+                height: sourceDimensions.height,
+                orientation: sourceDimensions.width > sourceDimensions.height ? 'landscape' : 'portrait',
+                aspectRatio: `${sourceDimensions.width}:${sourceDimensions.height}`,
+                media: '(min-width: 0px)'
+            };
+            validVariants.push(sourceVariant);
+            console.log(chalk_1.default.blue(`ℹ️  Falling back to source resolution variant: ${sourceDimensions.width}x${sourceDimensions.height}`));
+        }
+        // 0. SAVE SOURCE (Copy input video to the project directory)
+        let sourceRelPath = '';
+        try {
+            let sourceFileName = 'video-source';
+            let extension = '.mp4';
+            if (typeof input === 'string') {
+                const parts = input.split('.');
+                if (parts.length > 1)
+                    extension = `.${parts.pop()}`;
+                sourceFileName += extension;
+                await this.driver.copyFile(input, this.driver.join(outDir, sourceFileName));
+                sourceRelPath = `./${sourceFileName}`;
+            }
+            else if (input && input.arrayBuffer) {
+                // Handle File/Blob (Browser)
+                const fileName = input.name || 'source.mp4';
+                const parts = fileName.split('.');
+                if (parts.length > 1)
+                    extension = `.${parts.pop()}`;
+                sourceFileName += extension;
+                const buffer = await input.arrayBuffer();
+                await this.driver.writeFile(this.driver.join(outDir, sourceFileName), new Uint8Array(buffer));
+                sourceRelPath = `./${sourceFileName}`;
+            }
+        }
+        catch (e) {
+            console.warn(chalk_1.default.yellow(`⚠️  Could not save a local copy of source video: ${e instanceof Error ? e.message : String(e)}`));
+        }
         // 1. FRAME EXTRACTION
         this.report('extracting', 10, 'Extracting frames from source...');
         await this.driver.extractFrames(input, framesDir);
@@ -127,12 +196,12 @@ class AssetPipeline {
         const variants = await this.processVariants(tempDir, trackingData, {
             step,
             depth: isDepthActive,
-            variants: this.normalizeVariants(opts.variants),
+            variants: validVariants,
             outDir
         });
         // 4. SAVE CONFIG
         this.report('saving', 90, 'Finalizing project configuration...');
-        const config = await this.saveConfig(variants, outDir);
+        const config = await this.saveConfig(variants, outDir, sourceRelPath);
         // Cleanup
         await this.driver.remove(tempDir);
         this.report('saving', 100, 'Project ready!');
@@ -206,7 +275,7 @@ class AssetPipeline {
         }
         return assetVariants;
     }
-    async saveConfig(variants, outDir) {
+    async saveConfig(variants, outDir, sourcePath) {
         const pkg = require('../../package.json');
         const config = {
             version: pkg.version,
@@ -216,10 +285,13 @@ class AssetPipeline {
                 totalDuration: "300vh",
                 scenes: [{
                         id: "scene-1", assetId: "main-sequence", startProgress: 0, duration: 1,
-                        assetRange: [0, variants[0].frameCount - 1], layers: []
+                        assetRange: [0, (variants.length > 0 ? variants[0].frameCount : 1) - 1], layers: []
                     }]
             }
         };
+        if (sourcePath) {
+            config.source = sourcePath;
+        }
         await this.driver.writeFile(this.driver.join(outDir, 'scrolltube.json'), JSON.stringify(config, null, 2));
         return config;
     }

package/dist/pipeline/node-driver.d.ts

@@ -8,8 +8,14 @@ export declare class NodeDriver implements IPipelineDriver {
     exists(filePath: string): Promise<boolean>;
     readdir(dirPath: string): Promise<string[]>;
     remove(filePath: string): Promise<void>;
+    copyFile(src: string, dest: string): Promise<void>;
     join(...parts: string[]): string;
     resolve(...parts: string[]): string;
+    getVideoDimensions(input: string): Promise<{
+        width: number;
+        height: number;
+    }>;
+    private parseDimensions;
     extractFrames(videoSource: string, outputDir: string, onProgress?: (percent: number) => void): Promise<void>;
     processImage(input: Uint8Array | string, config: VariantConfig, options?: {
         grayscale?: boolean;

package/dist/pipeline/node-driver.js

@@ -70,19 +70,45 @@ class NodeDriver {
     async remove(filePath) {
         await fs.remove(filePath);
     }
+    async copyFile(src, dest) {
+        await fs.copy(src, dest);
+    }
     join(...parts) {
         return path.join(...parts);
     }
     resolve(...parts) {
         return path.resolve(...parts);
     }
+    async getVideoDimensions(input) {
+        return new Promise((resolve, reject) => {
+            try {
+                const result = (0, child_process_1.execSync)(`"${this.ffmpegPath}" -i "${input}"`, { stdio: 'pipe' }).toString();
+                // ffmpeg outputs info to stderr, which execSync might throw on if -i is used without an output file
+                this.parseDimensions(result, resolve, reject);
+            }
+            catch (err) {
+                // execSync throws if exit code != 0, but ffmpeg -i returns 1 because no output file 
+                const output = err.stderr ? err.stderr.toString() : (err.stdout ? err.stdout.toString() : '');
+                this.parseDimensions(output, resolve, reject);
+            }
+        });
+    }
+    parseDimensions(output, resolve, reject) {
+        const match = output.match(/, (\d{2,5})x(\d{2,5})/);
+        if (match) {
+            resolve({ width: parseInt(match[1]), height: parseInt(match[2]) });
+        }
+        else {
+            reject(new Error('Could not parse video dimensions.'));
+        }
+    }
     async extractFrames(videoSource, outputDir, onProgress) {
         return new Promise((resolve, reject) => {
             // For simplicity, we use execSync in a promise or spawn for progress
             try {
                 // ffmpeg -i input output%04d.png
                 // For now, let's keep it simple like existing CLI
-                (0, child_process_1.execSync)(`"${this.ffmpegPath}" -i "${videoSource}" "${outputDir}/frame_%04d.png"`, { stdio: 'inherit' });
+                (0, child_process_1.execSync)(`"${this.ffmpegPath}" -hide_banner -loglevel error -i "${videoSource}" "${outputDir}/frame_%04d.png"`, { stdio: 'inherit' });
                 resolve();
             }
             catch (err) {

package/dist/pipeline/types.d.ts

@@ -18,8 +18,13 @@ export interface IPipelineDriver {
     exists(path: string): Promise<boolean>;
     readdir(path: string): Promise<string[]>;
     remove(path: string): Promise<void>;
+    copyFile(src: string, dest: string): Promise<void>;
     join(...parts: string[]): string;
     resolve(...parts: string[]): string;
+    getVideoDimensions(input: string | File | Blob): Promise<{
+        width: number;
+        height: number;
+    }>;
     extractFrames(videoSource: string | File | Blob, outputDir: string, onProgress?: (percent: number) => void): Promise<void>;
     processImage(input: Uint8Array | string, config: VariantConfig, options: {
         grayscale?: boolean;

package/docs/ai-integration.md

@@ -10,7 +10,8 @@ For an AI to successfully build an experience, it must follow these two phases:
 The agent should first use the CLI to process raw media into an intelligent ScrollTube project.
 ```bash
 # Example: Process a video with AI tracking and depth maps
-npx stube create input.mp4 --name "my-project" --track "main product" --cloud --depth
+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.
 
@@ -47,7 +48,8 @@ Paste this into your chat to turn an AI into a ScrollTube specialist:
 You are the ScrollTube Implementation Specialist. Your goal is to design immersive scroll experiences.
 
 Workflow:
-1. CLI FIRST: Start by suggesting `npx stube create` to process assets.
+1. CLI FIRST: Start by suggesting `npx scrolltube create` to process assets.
+
 2. ENGINE AWARE: Use 'ScrollTubeProvider' to sync the engine with React state.
 3. SUBJECT PINS: Use 'SubjectLayer' to attach UI to the product coordinates found by the AI tracker.
 4. DYNAMIC UI: Use the 'progress' (0-1) or 'frame' count from 'useScrollTube' for custom triggers.

package/docs/architecture.md

@@ -15,6 +15,8 @@ The engine expects a `ProjectConfiguration` object (defined in `src/core/types.t
 - **`settings`**: Base resolutions, scroll modes, and base path.
 - **`assets`**: An array of `SequenceAsset` with multiple `variants` (Mobile vs Desktop).
 - **`timeline`**: A map of `scenes` and `layers`.
+- **`source`**: (New) Relative path to the original source video file, preserved for future edits or variant regenerations.
+
 
 ---
 

package/docs/asset-pipeline.md

@@ -18,12 +18,17 @@ This means you have a single source of truth for your processing logic, while be
 
 ## 2. CLI Usage
 
-The `npx stube create` command is the primary wrapper for the pipeline on your local machine.
+The `npx scrolltube create` command is the primary wrapper for the pipeline on your local machine.
+
  
  ```bash
- npx stube create <input> [options]
+ npx scrolltube create <input> [options]
  ```
  
+-> [!TIP]
+-> **Interactive Mode**: If you omit the input path or provide an invalid one, the CLI will now prompt you to try again instead of exiting.
+
+ 
  ### Options:
  - `-n, --name <string>`: Project folder name.
  - `-p, --track <text>`: Target object to track (e.g. "red car").
@@ -56,14 +61,16 @@ const zip = await pipeline.create({
 ```
 
 ### Core Pipeline Steps:
- 1.  **Auto-Upload**: If you provide a local `.mp4`, it's automatically uploaded to the cloud for processing.
- 2.  **Extraction**: Converts video files into high-quality image sequences.
+ 1.  **Source Preservation**: Automatically saves a copy of your original video as `video-source.[ext]` in the project directory for future-proofing.
+ 2.  **Extraction**: Converts video files into high-quality image sequences (with minimal terminal noise).
  3.  **AI Tracking**: Identifies the main subject (using **SAM 3**). Our engine now features **Sticky Tracking**—if the subject is obscured for a few frames, the coordinates hold their last known position.
- 4.  **Variant Generation**: 
+ 4.  **Upscale Protection**: Automatically detects source dimensions and filters out any requested variants that would require upscaling, ensuring maximum performance and visual quality.
+ 5.  **Variant Generation**: 
      - **Smart Crop**: Centers the images based on the tracked subject.
      - **Resolution Factory**: Creates Portrait (9:16) and Landscape (16:9) pairs for each target resolution (e.g. 720p, 1080p).
     - **Compression**: Optimized `.webp` generation via Sharp (Node) or Canvas (Browser).
- 5.  **Metadata Export**: Generates the final `scrolltube.json` with **root-relative paths** for easier deployment.
+ 6.  **Metadata Export**: Generates the final `scrolltube.json` with **root-relative paths** and source file references.
+
  
  ---
  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrolltube",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "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",
@@ -23,7 +23,7 @@
   },
   "types": "dist/core/index.d.ts",
   "bin": {
-    "stube": "dist/cli/index.js"
+    "scrolltube": "dist/cli/index.js"
   },
   "files": [
     "dist",