scrolltube 2.1.2 → 2.1.4

package/AGENTS.md

@@ -1,46 +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 stube create <input_path> --cloud --depth --prompt "main subject" [-s 2]
-```
-- **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)
 
 ---
 
@@ -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)
@@ -58,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) 
 
@@ -73,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) 
 
@@ -121,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.d.ts

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