scrollcraft 2.0.12 → 2.0.15

package/AGENTS.md

@@ -0,0 +1,46 @@
+<!-- BEGIN:scrollcraft-agent-rules -->
+# ScrollCraft Implementation Protocol
+
+This document is for AI agents tasked with implementing ScrollCraft in a host application. 
+
+## 🤖 Agent Persona
+You are a ScrollCraft 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 ScrollCraft project.
+```bash
+npx scft 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 `scrollcraft.json` and variant folders (`mobile/`, `desktop/`).
+
+### Step 2: Project Architecture (React)
+Import the generated `scrollcraft.json` and wrap your scene in the `ScrollCraftProvider`.
+```tsx
+import project from './path/to/scrollcraft.json';
+import { ScrollCraftProvider, ScrollCraftCanvas, SubjectLayer } from 'scrollcraft/react';
+
+// Goal: 1 ScrollCraftProvider per interactive section.
+```
+
+### Step 3: Immersive Layering
+Use high-level components to build the scene. Avoid manual coordinate math.
+- **`<ScrollCraftCanvas />`**: Renders the image sequence (WebGL).
+- **`<SubjectLayer />`**: Pins HTML content to the moving product automatically.
+- **`useScrollCraft()`**: 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:scrollcraft-agent-rules -->

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -4,6 +4,8 @@
 
 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.
 
+[scrollcraft.dev](https://www.scrollcraft.dev)
+
 ---
 
 ## Installation
@@ -36,7 +38,7 @@ You can also import the pipeline into your own React apps or dashboard:
 import { AssetPipeline } from 'scrollcraft/pipeline';
 
 const pipeline = new AssetPipeline({ 
-  apiKey: process.env.FAL_KEY, 
+  apiKey: process.env.SCROLLCRAFT_KEY || process.env.FAL_KEY, 
   onProgress: (p) => console.log(`${p.step}: ${p.percent}%`)
 });
 
@@ -44,6 +46,8 @@ const pipeline = new AssetPipeline({
 const project = await pipeline.create({
   input: videoFile, // Can be a File object or Path
   name: "my-project",
+  track: "apple",
+  depth: true,
   variants: [720, 1080],
   outputZip: true // Perfect for CMS uploads
 });
@@ -56,6 +60,8 @@ All you have to do now, is to drop the scrollcraft.json project into your Scroll
 #### Vanilla JS Integration
 For full implementation, please refer to the [Vanilla JS Example](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/examples/html/index.html).
 
+[Live Demo](https://example-html.scrollcraft.dev) 
+
 ```html
 <!-- 2. Drop it into your HTML -->
 <script type="module">
@@ -71,6 +77,9 @@ For full implementation, please refer to the [Vanilla JS Example](https://github
 #### React Integration
 For full implementation, please refer to the [React Integration Example](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/examples/create-next-app/src/app/page.tsx).
 
+[Live Demo](https://example-next.scrollcraft.dev) 
+
+
 ```tsx
 // 2. Drop it into your Next.js app
 import myproject from './example-apple-project/scrollcraft.json';
@@ -119,13 +128,13 @@ const AppleInfo = () => {
 Choose your path based on your role:
 
 ### 👤 For Humans
-- [**Core Architecture**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/content/architecture.md): Understand the state-snapshot engine.
-- [**Asset Pipeline**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/content/asset-pipeline.md): Learn how to use the CLI and AI tracking.
-- [**React Hooks**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/docs/content/react-integration.md): Build custom interactive components.
+- [**Core Architecture**](https://docs.scrollcraft.dev/architecture): Understand the state-snapshot engine.
+- [**Asset Pipeline**](https://docs.scrollcraft.dev/asset-pipeline): Learn how to use the CLI and AI tracking.
+- [**React Hooks**](https://docs.scrollcraft.dev/react-integration): 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/content/ai-integration.md): How to prompt agents to build scenes for you.
+- [**AGENTS.md**](https://github.com/aleskozelsky/scrollcraft/blob/main/packages/scrollcraft/AGENTS.md): Technical standard operating procedures for the repository.
+- [**AI Integration Protocol**](https://docs.scrollcraft.dev/ai-integration): How to prompt agents to build scenes for you.
 
 ---
 

package/dist/cli/index.js

@@ -131,7 +131,7 @@ program
 /**
  * Interactive Helper
  */
-async function prompt(question, defaultValue) {
+async function interactiveHelper(question, defaultValue) {
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout
@@ -152,8 +152,8 @@ program
     .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 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
@@ -173,7 +173,7 @@ program
     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');
+        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.`));
@@ -181,19 +181,44 @@ program
     }
     // 2. PROJECT NAME & SETTINGS
     if (!projectName) {
-        projectName = await prompt('Project name', 'scrollcraft-project');
+        projectName = await interactiveHelper('Project name', 'scrollcraft-project');
     }
     let step = parseInt(opts.step) || 1;
     if (!inputArg) {
-        const stepInput = await prompt('Process every Nth frame (Step size)', '1');
+        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`));
+        const proceed = await interactiveHelper('Continue with local fallback (no tracking, no depth)? [y/N]', 'n');
+        if (proceed.toLowerCase() !== 'y') {
+            console.log(chalk_1.default.dim('\nAborting. Please set your key and try again.\n'));
+            process.exit(0);
+        }
+        useTracking = false;
+        useDepth = false;
     }
-    // AI Tracking logic preserved in CLI wrapper...
-    // ...
     const pipeline = new pipeline_1.AssetPipeline({
-        apiKey: process.env.FAL_KEY,
+        apiKey: scftKey || falKey,
         onProgress: (p) => {
-            // You could add a progress bar here
+            // Progress reporting
         }
     });
     try {
@@ -201,7 +226,7 @@ program
             input: input,
             name: projectName,
             track: useTracking ? track : undefined,
-            hasDepth: useDepth,
+            depth: useDepth,
             variants: customVariants || [720, 1080],
             step: step
         });

package/dist/pipeline/browser-driver.js

@@ -70,7 +70,15 @@ class BrowserDriver {
         return results;
     }
     async remove(path) {
+        // 1. Delete the exact file/folder key
         this.files.delete(path);
+        // 2. Delete all children (recursive cleanup for virtual folders)
+        const prefix = path.endsWith('/') ? path : `${path}/`;
+        for (const key of this.files.keys()) {
+            if (key.startsWith(prefix)) {
+                this.files.delete(key);
+            }
+        }
     }
     join(...parts) {
         return parts.join('/').replace(/\/+/g, '/');

package/dist/pipeline/cloud-service.d.ts

@@ -0,0 +1,17 @@
+import { IPipelineDriver } from './types';
+import { SubjectFrameData } from '../core/types';
+export interface CloudOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    proxyUrl?: string;
+}
+export declare class CloudService {
+    private options;
+    private isScrollCraft;
+    constructor(options?: CloudOptions);
+    private getAuthHeaders;
+    trackSubject(input: string | File | Blob, driver: IPipelineDriver, prompt?: string): Promise<SubjectFrameData[]>;
+    generateDepthMap(input: string | File | Blob, driver: IPipelineDriver): Promise<string>;
+    private uploadFile;
+    private mapBoxesToTrackingData;
+}

package/dist/pipeline/cloud-service.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudService = void 0;
+const client_1 = require("@fal-ai/client");
+class CloudService {
+    options;
+    isScrollCraft = false;
+    constructor(options = {}) {
+        this.options = options;
+        // Prioritize SCROLLCRAFT_KEY from environment or options
+        const envScft = typeof process !== 'undefined' ? process.env?.SCROLLCRAFT_KEY : '';
+        const envFal = typeof process !== 'undefined' ? process.env?.FAL_KEY : '';
+        const key = options.apiKey || envScft || envFal;
+        if (envScft || (options.apiKey && options.apiKey.startsWith('scft_'))) {
+            this.isScrollCraft = true;
+        }
+        if (!key && !options.proxyUrl) {
+            // Don't throw yet, only when a cloud method is called
+        }
+    }
+    getAuthHeaders() {
+        // For now, fal-ai/client uses the env variable FE_FAL_KEY or the key provided to it.
+        // In the future, once we use a proxy, we'll manually set headers here.
+        return {};
+    }
+    async trackSubject(input, driver, prompt = "main subject") {
+        let videoUrl;
+        if (typeof input === 'string') {
+            // Local path or URL
+            if (await driver.exists(input)) {
+                videoUrl = await this.uploadFile(input, driver);
+            }
+            else {
+                videoUrl = input;
+            }
+        }
+        else {
+            // File or Blob
+            videoUrl = await client_1.fal.storage.upload(input);
+        }
+        console.log(`🤖 AI is tracking "${prompt}" via SAM 3...`);
+        const result = await client_1.fal.subscribe("fal-ai/sam-3/video-rle", {
+            input: {
+                video_url: videoUrl,
+                prompt: prompt,
+            },
+            logs: true,
+        });
+        const payload = result.data || result;
+        const boxes = payload.boxes;
+        if (!boxes || !Array.isArray(boxes) || boxes.length === 0) {
+            throw new Error(`AI tracking returned no data.`);
+        }
+        return this.mapBoxesToTrackingData(boxes);
+    }
+    async generateDepthMap(input, driver) {
+        let videoUrl;
+        if (typeof input === 'string') {
+            if (await driver.exists(input)) {
+                videoUrl = await this.uploadFile(input, driver);
+            }
+            else {
+                videoUrl = input;
+            }
+        }
+        else {
+            videoUrl = await client_1.fal.storage.upload(input);
+        }
+        console.log(`🤖 AI is generating Depth Map...`);
+        const result = await client_1.fal.subscribe("fal-ai/video-depth-anything", {
+            input: {
+                video_url: videoUrl,
+                model_size: "VDA-Base",
+            },
+            logs: true
+        });
+        const payload = result.data || result;
+        if (!payload.video || !payload.video.url) {
+            throw new Error(`AI Depth Map generation failed.`);
+        }
+        return payload.video.url;
+    }
+    async uploadFile(filePath, driver) {
+        const data = await driver.readFile(filePath);
+        return await client_1.fal.storage.upload(new Blob([data]));
+    }
+    mapBoxesToTrackingData(boxes) {
+        let lastKnown = { x: 0.5, y: 0.5, scale: 0 };
+        return boxes.map((frameBoxes, i) => {
+            if (frameBoxes && Array.isArray(frameBoxes)) {
+                let box = null;
+                if (typeof frameBoxes[0] === 'number' && frameBoxes.length >= 4) {
+                    box = frameBoxes;
+                }
+                else if (Array.isArray(frameBoxes[0]) && frameBoxes[0].length >= 4) {
+                    box = frameBoxes[0];
+                }
+                else if (typeof frameBoxes[0] === 'object' && frameBoxes[0].box_2d) {
+                    box = frameBoxes[0].box_2d;
+                }
+                if (box) {
+                    lastKnown = { x: box[0], y: box[1], scale: box[2] * box[3] };
+                }
+            }
+            return { frame: i, ...lastKnown };
+        });
+    }
+}
+exports.CloudService = CloudService;

package/dist/pipeline/index.d.ts

@@ -3,7 +3,7 @@ import { ProjectConfiguration, AssetVariant } from '../core/types';
 export declare class AssetPipeline {
     private driver;
     private options;
-    private fal;
+    private cloud;
     constructor(options?: PipelineOptions);
     /**
      * INITIALIZE DRIVER

package/dist/pipeline/index.js

@@ -34,14 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssetPipeline = void 0;
-const fal_service_1 = require("./fal-service");
+const cloud_service_1 = require("./cloud-service");
 class AssetPipeline {
     driver;
     options;
-    fal;
+    cloud;
     constructor(options = {}) {
         this.options = options;
-        this.fal = new fal_service_1.FalService({ apiKey: options.apiKey, proxyUrl: options.proxyUrl });
+        this.cloud = new cloud_service_1.CloudService({ apiKey: options.apiKey, proxyUrl: options.proxyUrl });
     }
     /**
      * INITIALIZE DRIVER
@@ -83,38 +83,42 @@ class AssetPipeline {
      */
     async create(opts) {
         await this.init();
-        const { input, name, track, hasDepth, step = 1 } = opts;
+        const { input, name, track, depth, step = 1 } = opts;
         const outDir = this.driver.resolve(name);
         const tempDir = this.driver.join(outDir, '.temp-frames');
+        const framesDir = this.driver.join(tempDir, 'frames');
+        const depthsDir = this.driver.join(tempDir, 'depths');
         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);
         // 1. FRAME EXTRACTION
         this.report('extracting', 10, 'Extracting frames from source...');
-        await this.driver.extractFrames(input, tempDir);
+        await this.driver.extractFrames(input, framesDir);
         // 2. AI TRACKING & DEPTH
         let trackingData = [];
         let isDepthActive = false;
-        if (track || hasDepth) {
+        if (track || depth) {
             this.report('tracking', 30, 'Performing AI analysis...');
             if (track) {
-                trackingData = await this.fal.trackSubject(input, this.driver, track);
+                trackingData = await this.cloud.trackSubject(input, this.driver, track);
             }
-            if (hasDepth) {
+            if (depth) {
                 this.report('depth', 40, 'Generating depth maps...');
-                const depthVideoUrl = await this.fal.generateDepthMap(input, this.driver);
+                const depthVideoUrl = await this.cloud.generateDepthMap(input, this.driver);
                 // Download and extract depth frames
                 const response = await fetch(depthVideoUrl);
                 const buffer = await response.arrayBuffer();
-                const depthPath = this.driver.join(tempDir, 'depth_video.mp4');
-                await this.driver.writeFile(depthPath, new Uint8Array(buffer));
-                await this.driver.extractFrames(depthPath, tempDir); // Note: needs to handle prefix
+                const depthVideoPath = this.driver.join(tempDir, 'depth_video.mp4');
+                await this.driver.writeFile(depthVideoPath, new Uint8Array(buffer));
+                await this.driver.extractFrames(depthVideoPath, depthsDir);
                 isDepthActive = true;
             }
         }
         // Default tracking if none
         if (trackingData.length === 0) {
-            const files = await this.driver.readdir(tempDir);
+            const files = await this.driver.readdir(framesDir);
             const frameFiles = files.filter(f => f.startsWith('frame_'));
             trackingData = frameFiles.map((_, i) => ({ frame: i, x: 0.5, y: 0.5, scale: 0 }));
         }
@@ -122,7 +126,7 @@ class AssetPipeline {
         this.report('processing', 60, 'Generating optimized variants...');
         const variants = await this.processVariants(tempDir, trackingData, {
             step,
-            hasDepth: isDepthActive,
+            depth: isDepthActive,
             variants: this.normalizeVariants(opts.variants),
             outDir
         });
@@ -159,7 +163,9 @@ class AssetPipeline {
     }
     async processVariants(tempDir, trackingData, options) {
         const { step, outDir } = options;
-        const allFiles = await this.driver.readdir(tempDir);
+        const framesDir = this.driver.join(tempDir, 'frames');
+        const depthsDir = this.driver.join(tempDir, 'depths');
+        const allFiles = await this.driver.readdir(framesDir);
         const allFrames = allFiles.filter(f => f.startsWith('frame_')).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
         const framesToProcess = allFrames.filter((_, i) => i % step === 0);
         const assetVariants = [];
@@ -170,16 +176,14 @@ class AssetPipeline {
             for (let i = 0; i < framesToProcess.length; i++) {
                 const originalIndex = i * step;
                 const frameName = framesToProcess[i];
-                const framePath = this.driver.join(tempDir, frameName);
+                const framePath = this.driver.join(framesDir, frameName);
                 const targetPath = this.driver.join(variantDir, `index_${i}.webp`);
                 const subject = trackingData.find(f => f.frame === originalIndex) || { frame: originalIndex, x: 0.5, y: 0.5, scale: 0 };
                 const imageBuffer = await this.driver.processImage(framePath, config, {});
                 await this.driver.writeFile(targetPath, imageBuffer);
-                if (options.hasDepth) {
-                    const numStr = frameName.match(/(\d+)/)?.[1] || "";
-                    const depthFile = allFiles.find(f => f.startsWith('depth_') && f.includes(numStr));
-                    if (depthFile) {
-                        const depthPath = this.driver.join(tempDir, depthFile);
+                if (options.depth) {
+                    const depthPath = this.driver.join(depthsDir, frameName);
+                    if (await this.driver.exists(depthPath)) {
                         const depthBuffer = await this.driver.processImage(depthPath, config, { grayscale: true, blur: 2 });
                         await this.driver.writeFile(this.driver.join(variantDir, `index_${i}_depth.webp`), depthBuffer);
                     }
@@ -196,14 +200,14 @@ class AssetPipeline {
                 aspectRatio: config.aspectRatio,
                 path: `./${config.id}`,
                 frameCount: framesToProcess.length,
-                hasDepthMap: options.hasDepth,
+                hasDepthMap: options.depth,
                 subjects: ['main']
             });
         }
         return assetVariants;
     }
     async saveConfig(variants, outDir) {
-        const pkg = { version: '2.0.6' }; // In real app, import from package.json
+        const pkg = require('../../package.json');
         const config = {
             version: pkg.version,
             settings: { baseResolution: { width: 1920, height: 1080 }, scrollMode: 'vh' },

package/dist/pipeline/types.d.ts

@@ -36,7 +36,7 @@ export interface CreateCommandOptions {
     input: string | File | Blob;
     name: string;
     track?: string;
-    hasDepth?: boolean;
+    depth?: boolean;
     variants: number[] | VariantConfig[];
     step?: number;
     outputZip?: boolean;

package/docs/ai-integration.md

@@ -0,0 +1,72 @@
+# AI Agent Workflow
+
+ScrollCraft is built for **Agent-Led Development**. The goal is to move from "writing code" to "orchestrating workflows."
+
+## 1. The Two-Phase Workflow
+
+For an AI to successfully build an experience, it must follow these two phases:
+
+### Phase A: Asset Intelligence (CLI Execution)
+The agent should first use the CLI to process raw media into an intelligent ScrollCraft project.
+```bash
+# Example: Process a video with AI tracking and depth maps
+npx scft create input.mp4 --name "my-project" --track "main product" --cloud --depth
+```
+**Output:** A directory containing optimized frames, depth maps, and a `scrollcraft.json` file.
+
+### Phase B: Immersive Implementation (React)
+The agent then uses the generated JSON to build the UI components.
+
+```tsx
+import project from './scrollcraft-project/scrollcraft.json';
+import { ScrollCraftProvider, ScrollCraftCanvas, SubjectLayer } from 'scrollcraft/react';
+
+export const MyExperience = () => (
+  <ScrollCraftProvider project={project} scrub={0.1}>
+    <div style={{ height: '300vh' }}>
+      <div style={{ sticky: 'top-0', height: '100vh' }}>
+        <ScrollCraftCanvas />
+        
+        {/* Pins content to the tracked subject automatically */}
+        <SubjectLayer offset={{ x: 10, y: -5 }}>
+          <div className="info-box">
+             Premium Craftsmanship
+          </div>
+        </SubjectLayer>
+      </div>
+    </div>
+  </ScrollCraftProvider>
+);
+```
+
+## 2. Protocol for AI Agents (Claude/GPT)
+
+Paste this into your chat to turn an AI into a ScrollCraft specialist:
+
+```markdown
+You are the ScrollCraft Implementation Specialist. Your goal is to design immersive scroll experiences.
+
+Workflow:
+1. CLI FIRST: Start by suggesting `npx scft create` to process assets.
+2. ENGINE AWARE: Use 'ScrollCraftProvider' 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 'useScrollCraft' for custom triggers.
+
+Guiding Principles:
+- Don't hardcode animations; let the ScrollCraft engine handle interpolation.
+- Use 'Subject-Relative' coordinates wherever possible for perfect pinning.
+- For Mobile, consider centering text layers ABOVE or BELOW the subject focal point.
+- For Desktop, place text layers to the SIDES of the subject focal point.
+
+```
+
+---
+
+## 3. The "Intelligence-as-a-Service" Model
+
+This workflow enables a powerful business model:
+1. **The CLI** handles the "hard" computer vision (tracking, depth, optimization).
+2. **The JSON** stores this intelligence.
+3. **The AI Agent** uses that intelligence to write the perfectly synced creative layer.
+
+You provide the **SDK**, the AI provides the **Implementation**.

package/docs/architecture.md

@@ -0,0 +1,55 @@
+# Architecture: Declarative Animation
+
+ScrollCraft 2.0 is a **State-Snapshot Engine**. Unlike traditional animation libraries that rely on imperative callbacks, this engine treats the entire scroll project as a piece of data.
+
+## 1. The Project Configuration (`scrollcraft.json`)
+
+The heart of every project is a JSON file that describes the entire experience. This allows the state to be:
+- **Portable**: Can be generated by an AI, a server, or a visual editor.
+- **Serializable**: Can be stored in a database or passed via API.
+- **Versioned**: Changes to the animation are tracked like code.
+
+### Core Schema Overview
+The engine expects a `ProjectConfiguration` object (defined in `src/core/types.ts`):
+
+- **`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`.
+
+---
+
+## 2. Decoupled Rendering Pipeline
+
+State management is separated from pixels.
+
+1.  **Core Engine**: A non-UI class that manages the `scroll -> frame` math, image preloading, and subject tracking coordinates.
+2.  **React Provider**: Wraps the Engine in a reactive context.
+3.  **UI Components**: `<ScrollCraftCanvas />` and `<SubjectLayer />` represent the "view." You can have multiple view layers tied to the same engine state.
+
+### How it works:
+1.  **Detection**: On initialization and resize, the engine calculates the required **Physical Resolution** (`width * devicePixelRatio`) and checks the `canvas` element's own dimensions.
+2.  **Selection**: It selects the variant that best matches or exceeds the required resolution for the current orientation (Portrait vs Landscape).
+3.  **Hot-Swapping**: If the container size changes or the phone is rotated, the engine immediately swaps to the better-fit image folder without losing scroll place.
+
+---
+
+## 3. Subject-Relative Coordinates
+
+This is the key technological shift:
+
+- **Traditional**: Content is fixed at `x: 50vw`.
+- **v2.0**: Content is anchored to a `Subject`.
+
+Each Asset Variant can contain `subjectTracking` data—frame-by-frame (x,y) coordinates of the main object. The engine combines the image's "Local Coordinates" with your layer's "Relative Offset" to calculate the final screen position.
+
+**Formula**: 
+`Screen Position = (Subject Center (x,y) + Relative Offset)`
+
+This ensures the text follows the product even if the image is cropped or scaled for mobile.
+
+---
+
+## 4. 3D Parallax & Depth Maps
+
+ScrollCraft 2.0 introduces **Depth-Aware Rendering**. 
+By supplying a grayscale depth map (where white is closer and black is farther), the WebGL shader can apply a subtle displacement effect based on mouse or gyro movement. This gives the scroll sequence a premium "3D Parallax" feel without the weight of actual 3D models.

package/docs/asset-pipeline.md

@@ -0,0 +1,105 @@
+# Asset Pipeline: The Universal Engine
+ 
+
+The ScrollCraft Asset Pipeline is a platform-agnostic engine designed to do the "hard work" of segmentation, tracking, and optimization. It runs exactly the same logic whether you are in your terminal or a WordPress dashboard.
+
+## 1. Universal Architecture
+
+The pipeline uses a **Strategy Pattern** with two primary drivers:
+
+| Driver | Environment | Technology |
+| :--- | :--- | :--- |
+| **NodeDriver** | CLI / Backend | `sharp`, `ffmpeg-static` |
+| **BrowserDriver** | CMS / Frontend | `ffmpeg.wasm`, `OffscreenCanvas` |
+
+This means you have a single source of truth for your processing logic, while benefiting from the best native tools available to each platform.
+
+---
+
+## 2. CLI Usage
+
+The `npx scft create` command is the primary wrapper for the pipeline on your local machine.
+ 
+ ```bash
+ npx scft create <input> [options]
+ ```
+ 
+ ### Options:
+ - `-n, --name <string>`: Project folder name.
+ - `-p, --track <text>`: Target object to track (e.g. "red car").
+ - `-v, --variants <string>`: Comma-separated target resolutions (e.g. `720,1080`).
+ - `-s, --step <number>`: Process every Nth frame. **VITAL for performance**.
+ - `--cloud`: Use Fal.ai for tracking (requires `FAL_KEY`).
+ - `--depth`: Generate a corresponding image sequence of depth maps for the 3D parallax effect.
+ 
+
+---
+
+## 3. Programmatic Usage (SDK)
+
+For building your own CMS plugins or web-based authoring tools, you can import the pipeline directly:
+
+```typescript
+import { AssetPipeline } from 'scrollcraft/pipeline';
+
+const pipeline = new AssetPipeline({ 
+  apiKey: '...', 
+  onProgress: (p) => updateUI(p.percent) 
+});
+
+// Returns a ZIP blob containing the entire project
+const zip = await pipeline.create({
+  input: myFileObject,
+  name: 'project-name',
+  outputZip: true
+});
+```
+
+### 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.
+ 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**: 
+     - **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 `scrollcraft.json` with **root-relative paths** for easier deployment.
+ 
+ ---
+ 
+## 2. Cloud vs Local Processing
+
+The pipeline is split into a **Local Implementation** path and a **Cloud-Accelerated** path.
+
+### 🏠 Local Implementation (Free)
+- Uses **FFmpeg** on your machine for extraction.
+- Uses **Sharp** for resizing and cropping.
+- Does **not** include automatic AI point-tracking (uses center-pinned defaults).
+
+### ☁️ Cloud-Accelerated Implementation (Paid)
+- **Fal.ai Integration**: Triggers high-end GPUs to run SAM 3 tracking.
+- **Refinement**: Can be configured to auto-remove backgrounds or upscale low-res sequences using ESRGAN.
+- **CDN Ready**: Prepares assets for cloud hosting.
+
+## 4. Environment Drivers
+
+### 🏠 NodeDriver
+- **Extraction**: Native FFmpeg binary.
+- **Image Engine**: **Sharp** (C++).
+
+### 🌐 BrowserDriver
+- **Extraction**: **ffmpeg.wasm**.
+- **Image Engine**: **OffscreenCanvas** (Hardware-accelerated).
+- **Output**: Persistent IndexedDB or a downloadable **ZIP**.
+
+---
+
+## 3. Configuration (.env.local)
+
+To use the cloud features, you must provide your own API keys in your `.env.local`:
+
+```bash
+FAL_KEY="your-fal-api-key"
+```
+
+*Note: This mimics the Remotion "Bring Your Own Key" model for indie developers.*

package/docs/react-integration.md

@@ -0,0 +1,89 @@
+# React Integration
+
+The ScrollCraft React library is a thin, high-performance wrapper around the Core Engine.
+
+## 1. The Provider Pattern
+
+Everything starts with the `ScrollCraftProvider`. It initializes the engine and provides a reactive context for all child components.
+
+```tsx
+import { ScrollCraftProvider } from 'scrollcraft/react';
+import projectConfig from './my-project.json';
+
+function App() {
+  return (
+    <ScrollCraftProvider project={projectConfig} scrub={0.1}>
+      {/* 
+          The actual canvas that renders the sequence.
+          Can be placed anywhere inside the provider.
+      */}
+      <ScrollCraftCanvas 
+        style={{ width: '100%', height: '100vh', objectFit: 'cover' }} 
+      />
+      
+      <MyContent />
+    </ScrollCraftProvider>
+  );
+}
+```
+### Provider Props:
+- **`project`**: The JSON configuration file generated by the CLI.
+- **`scrub`**: (Optional) Number between `0` and `1`. Sets the smoothing/interpolation factor. `0` is instant, `1` is smooth, `2`+ is heavy lag.
+- **`basePath`**: (Optional) Override the base URL for asset loading.
+
+---
+
+The rendering engine is decoupled from the provider. You must include a `<ScrollCraftCanvas />` to see your images.
+
+### Key Props:
+- **`style`**: Standard React styles. Use `objectFit: 'cover'` to ensure the sequence behaves like a background.
+- **`assetId`**: (Optional) Specify which asset from the JSON to render. Defaults to the first one.
+- **`depthEnabled`**: (Optional) Boolean. If true (and if depth maps exist in the assets), enables the mouse-parallax displacement effect.
+
+---
+
+## 3. Using the `<SubjectLayer />`
+
+The `<SubjectLayer>` is the primary way to add content that "sticks" to the product in your sequence.
+
+```tsx
+import { SubjectLayer } from 'scrollcraft/react';
+
+<SubjectLayer offset={{ x: 15, y: -10 }}>
+  <div className="callout">
+    <h4>4K Ultra Wide</h4>
+    <p>Captured at 120fps.</p>
+  </div>
+</SubjectLayer>
+```
+
+### Key Props:
+- **`offset`**: `{ x: number, y: number }`. Positioning relative to the **Subject Center**. This is measured in viewport percentage units (0-100).
+- **`zIndex`**: Control the depth of the layer.
+
+---
+
+## 4. The `useScrollCraft` Hook
+
+For custom components, you can hook directly into the engine's state.
+
+```tsx
+import { useScrollCraft } from 'scrollcraft/react';
+
+const MyCustomStats = () => {
+  const { progress, frame, subjectCoords } = useScrollCraft();
+
+  return (
+    <div style={{ opacity: progress }}>
+      Current Frame: {frame}
+    </div>
+  );
+};
+```
+
+---
+
+## 5. Context Properties
+- `progress`: Number (0 to 1). The global scroll position.
+- `frame`: Number. The current frame index of the active scene.
+- `subjectCoords`: `{ x: number, y: number }`. The current normalized (0-1) position of the subject on the screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrollcraft",
-  "version": "2.0.12",
+  "version": "2.0.15",
   "description": "ScrollCraft is a web-based tool for scroll-triggered animations.",
   "main": "dist/core/scrollcraft.umd.min.js",
   "module": "dist/core/scrollcraft.umd.min.js",
@@ -27,7 +27,10 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs"
   ],
   "scripts": {
     "build": "npm run sync-readme && npm run build:web && npm run build:pipeline",