@scenerok/cli 1.0.5 → 1.0.6

package/README.md

@@ -1,3 +1,4 @@
+import motion from "@scenerok/basic-animations"
 # SceneRok CLI
 
 Create videos from your terminal and agent workflows.
@@ -102,7 +103,7 @@ scenerok project render <project-id> --watch --download ./renders
 
 ```bash
 scenerok cache pull
-scenerok cache pull --plugin xai-media-video --output ~/.scenerok/cache/assets
+scenerok cache pull --plugin @scenerok/xai --output ~/.scenerok/cache/assets
 ```
 
 Downloads cached generated assets and writes a `manifest.json` to the output folder.
@@ -123,15 +124,17 @@ Config is stored in `~/.scenerok/config.json`:
 VidScript is a declarative language for describing video compositions.
 
 ```vidscript
+import motion from "@scenerok/basic-animations"
+
 input hero = "./assets/hero.mp4"
 
 [0s .. 5s] = hero
-[0.4s .. 3s] = text "Hello World", font: "Inter Bold", size: 72, x: "50%", y: "50%", align: center, animate: [fadeIn(0.6s), slideY(40, 0, 0.8s)]
+[0.4s .. 3s] = text "Hello World", font: "Inter Bold", size: 72, x: "50%", y: "50%", align: center, animate: [motion.fadeIn(0.6s), motion.slideY(40, 0, 0.8s)]
 
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 
-Animation helpers: `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`.
+Animation helpers are package functions: `motion.fadeIn`, `motion.fadeOut`, `motion.slideX`, `motion.slideY`, `motion.popIn`, `motion.riseIn`, `motion.swingIn`, `motion.glitchIn`, `motion.float`, `motion.typewriter`.
 
 ## Links
 

package/dist/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,eAAO,MAAM,WAAW,SA0FrB,CAAC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,eAAO,MAAM,WAAW,SA2GrB,CAAC"}

package/dist/commands/auth.js

@@ -3,12 +3,16 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { readConfig, writeConfig, isAuthenticated } from '../lib/config.js';
 import { initiateDeviceAuth, pollDeviceAuth } from '../lib/api.js';
+import { getBaseUrl } from '../lib/config.js';
+import { formatApiErrorMessage } from '../lib/format-api-error.js';
+import { getLogFilePath, isVerbose, logError } from '../lib/logger.js';
 export const authCommand = new Command('auth')
     .description('Authenticate with SceneRok')
     .addCommand(new Command('login')
     .description('Log in to SceneRok via browser')
     .option('-n, --name <name>', 'Device name', 'CLI')
     .option('-u, --base-url <url>', 'SceneRok API base URL (overrides ~/.scenerok/config.json and SCENEROK_BASE_URL)')
+    .option('-v, --verbose', 'Print debug output and log API calls to ~/.scenerok/logs/cli.log')
     .action(async (options) => {
     if (options.baseUrl) {
         const config = readConfig();
@@ -16,6 +20,10 @@ export const authCommand = new Command('auth')
         writeConfig(config);
     }
     console.log(chalk.cyan('\n🔐 SceneRok Authentication\n'));
+    console.log(chalk.dim(`API: ${getBaseUrl()}`));
+    if (options.verbose || isVerbose()) {
+        console.log(chalk.dim(`Log file: ${getLogFilePath()}\n`));
+    }
     const spinner = ora('Initiating device auth...').start();
     try {
         const auth = await initiateDeviceAuth(options.name);
@@ -53,13 +61,21 @@ export const authCommand = new Command('auth')
     }
     catch (error) {
         spinner.fail('Authentication failed');
-        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        logError('auth login failed', {
+            baseUrl: getBaseUrl(),
+            error: formatApiErrorMessage(error),
+        });
+        console.error(chalk.red(formatApiErrorMessage(error)));
+        console.error(chalk.dim(`\nLog: ${getLogFilePath()}`));
+        console.error(chalk.dim('Retry with: scenerok auth login --verbose  (or SCENEROK_VERBOSE=1 scenerok auth login)'));
         process.exit(1);
     }
 }))
     .addCommand(new Command('status')
     .description('Check authentication status')
     .action(() => {
+    console.log(chalk.dim(`API: ${getBaseUrl()}`));
+    console.log(chalk.dim(`Log: ${getLogFilePath()}`));
     if (isAuthenticated()) {
         console.log(chalk.green('✅ Authenticated with SceneRok'));
     }

package/dist/commands/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/commands/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,eAAO,MAAM,cAAc,SAyJxB,CAAC"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/commands/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCpC,eAAO,MAAM,cAAc,SA+JxB,CAAC"}

package/dist/commands/project.js

@@ -6,6 +6,14 @@ import { join, resolve } from 'node:path';
 import { downloadRender, getRenderStatus, listProjects, submitRender, uploadProject } from '../lib/api.js';
 import { isAuthenticated } from '../lib/config.js';
 import { appendProjectToForm, prepareProject } from '../lib/project.js';
+function formatDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes === 0)
+        return `${seconds}s`;
+    return `${minutes}m ${seconds.toString().padStart(2, '0')}s`;
+}
 async function waitForRender(renderId) {
     while (true) {
         await new Promise((resolveWait) => setTimeout(resolveWait, 3000));
@@ -74,8 +82,11 @@ export const projectCommand = new Command('project')
             console.log(`  Download: ${result.render.downloadUrl}`);
             if (options.watch || options.download) {
                 console.log(chalk.dim('\nWatching render status...\n'));
-                await waitForRender(result.render.renderId);
+                const status = await waitForRender(result.render.renderId);
                 console.log(chalk.green('\nRender complete'));
+                if (status.clickToDownloadMs !== null) {
+                    console.log(`  Time:     ${formatDuration(status.clickToDownloadMs)}`);
+                }
             }
             if (options.download) {
                 const outputDir = typeof options.download === 'string' ? options.download : 'renders';
@@ -143,8 +154,11 @@ export const projectCommand = new Command('project')
         console.log(`  URL:      ${result.renderUrl}`);
         console.log(`  Download: ${result.downloadUrl}`);
         if (options.watch || options.download) {
-            await waitForRender(result.renderId);
+            const status = await waitForRender(result.renderId);
             console.log(chalk.green('\nRender complete'));
+            if (status.clickToDownloadMs !== null) {
+                console.log(`  Time:     ${formatDuration(status.clickToDownloadMs)}`);
+            }
         }
         if (options.download) {
             const outputDir = typeof options.download === 'string' ? options.download : 'renders';

package/dist/commands/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/commands/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkEpC,eAAO,MAAM,aAAa,SAAwB,CAAC;AAEnD,eAAO,MAAM,aAAa,SAuFtB,CAAC"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/commands/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6EpC,eAAO,MAAM,aAAa,SAAwB,CAAC;AAEnD,eAAO,MAAM,aAAa,SA0FtB,CAAC"}

package/dist/commands/render.js

@@ -5,6 +5,14 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { submitRender, getRenderStatus, downloadRender } from '../lib/api.js';
 import { isAuthenticated } from '../lib/config.js';
+function formatDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes === 0)
+        return `${seconds}s`;
+    return `${minutes}m ${seconds.toString().padStart(2, '0')}s`;
+}
 function createStatusCommand() {
     return new Command('status')
         .description('Check render status')
@@ -27,6 +35,9 @@ function createStatusCommand() {
             console.log(`  ID:       ${status.id}`);
             console.log(`  Status:   ${status.status}`);
             console.log(`  Progress: ${status.progress}%`);
+            if (status.clickToDownloadMs !== null) {
+                console.log(`  Time:     ${formatDuration(status.clickToDownloadMs)}`);
+            }
             if (status.outputUrl) {
                 console.log(`  Output:   ${status.outputUrl}`);
             }
@@ -104,6 +115,9 @@ export const renderCommand = new Command('render')
                 const status = await getRenderStatus(result.renderId);
                 if (status.status === 'completed') {
                     console.log(chalk.green(`\\n✅ Render complete!\\n`));
+                    if (status.clickToDownloadMs !== null) {
+                        console.log(`  Time:     ${formatDuration(status.clickToDownloadMs)}`);
+                    }
                     console.log(`  Download: ${status.downloadUrl}`);
                     if (options.download) {
                         const outputDir = typeof options.download === 'string' ? options.download : 'renders';

package/dist/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,eAAO,MAAM,eAAe,SAkDxB,CAAC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8BpC,eAAO,MAAM,eAAe,SA8CxB,CAAC"}

package/dist/commands/validate.js

@@ -11,6 +11,17 @@ function collectValidationErrors(result) {
     }
     return ['Validation failed (no error details returned by server)'];
 }
+function printAestheticWarnings(result) {
+    if (!result.warnings || result.warnings.length === 0)
+        return;
+    console.log(chalk.yellow('\n  Aesthetic warnings:'));
+    if (result.aestheticScore != null) {
+        console.log(chalk.yellow(`    Score: ${result.aestheticScore}/100`));
+    }
+    for (const warning of result.warnings) {
+        console.log(chalk.yellow(`    • ${warning}`));
+    }
+}
 export const validateCommand = new Command('validate')
     .description('Validate a VidScript file')
     .argument('<file>', 'Path to .vid or .vidscript file')
@@ -40,18 +51,14 @@ export const validateCommand = new Command('validate')
             if (pluginCalls != null) {
                 console.log(`  Plugin calls: ${pluginCalls}`);
             }
-            if (result.warnings && result.warnings.length > 0) {
-                console.log(chalk.yellow('\\n  Warnings:'));
-                for (const warning of result.warnings) {
-                    console.log(`    • ${warning}`);
-                }
-            }
+            printAestheticWarnings(result);
         }
         else {
             console.log(chalk.red('\\n❌ VidScript is invalid\\n'));
             for (const err of collectValidationErrors(result)) {
                 console.log(`  • ${err}`);
             }
+            printAestheticWarnings(result);
             process.exit(1);
         }
         console.log('');

package/dist/index.js

@@ -15,7 +15,8 @@ const packageJson = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.me
 program
     .name('scenerok')
     .description('SceneRok CLI - Create videos from your terminal and agent workflows')
-    .version(packageJson.version || '0.0.0');
+    .version(packageJson.version || '0.0.0')
+    .option('-v, --verbose', 'Log API requests to ~/.scenerok/logs/cli.log');
 program.addCommand(authCommand);
 program.addCommand(skillsCommand);
 program.addCommand(renderCommand);
@@ -29,6 +30,7 @@ program.on('--help', () => {
     console.log('');
     console.log(chalk.cyan('Examples:'));
     console.log('  $ scenerok auth login');
+    console.log('  $ scenerok auth login --verbose   # debug log at ~/.scenerok/logs/cli.log');
     console.log('  $ scenerok skills install opencode');
     console.log('  $ scenerok validate video.vidscript');
     console.log('  $ scenerok render video.vidscript --resolution 1080x1920');

package/dist/lib/api.d.ts

@@ -9,6 +9,17 @@ export declare function validateVidscript(vidscript: string): Promise<{
     scenes?: number;
     duration?: number;
     warnings?: string[];
+    aestheticWarnings?: Array<{
+        ruleId: string;
+        severity: "warning";
+        category: string;
+        message: string;
+        recommendation: string;
+        elementId?: string;
+        start?: number;
+        end?: number;
+    }>;
+    aestheticScore?: number;
     errors?: string[];
     error?: string;
 }>;
@@ -35,6 +46,7 @@ export declare function getRenderStatus(renderId: number): Promise<{
     error: string | null;
     createdAt: string;
     completedAt: string | null;
+    clickToDownloadMs: number | null;
 }>;
 export declare function downloadRender(renderId: number): Promise<{
     buffer: Buffer;

package/dist/lib/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"AASA,cAAM,QAAS,SAAQ,KAAK;IAGjB,MAAM,EAAE,MAAM;IACd,YAAY,CAAC,EAAE,OAAO;gBAF7B,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,OAAO,YAAA;CAKhC;AAkED,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM;WAE9C,OAAO;iBACD,MAAM;aACV,MAAM;eACJ,MAAM;eACN,MAAM,EAAE;aACV,MAAM,EAAE;YACT,MAAM;GAEjB;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;cAEhF,MAAM;YACR,MAAM;gBACF,MAAM;oBACF,MAAM;eACX,MAAM;iBACJ,MAAM;aACV,MAAM;kBACD,MAAM;gBACR,MAAM,GAAG,IAAI;GAE5B;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM;QAE9C,MAAM;YACF,MAAM;cACJ,MAAM;eACL,MAAM,GAAG,IAAI;oBACR,MAAM;eACX,MAAM;iBACJ,MAAM;mBACJ,OAAO;WACf,MAAM,GAAG,IAAI;eACT,MAAM;iBACJ,MAAM,GAAG,IAAI;GAE7B;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBpG;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ;aAEzC;QACP,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB;YACO,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;aACO,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,GAAG,IAAI;GAE3D;AAED,wBAAsB,YAAY;cAEpB,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;GAEL;AAED,wBAAsB,aAAa,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO;aAMxE,KAAK,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,EAAE,OAAO,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;GAEL;AAED,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM;iBAE1C,MAAM;eACR,MAAM;sBACC,MAAM;gBACZ,MAAM;cACR,MAAM;GAEnB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM;YAE3C,MAAM;mBACC,MAAM;iBACR,MAAM;iBACN,MAAM;YACX,MAAM;GAEjB;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"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"}

package/dist/lib/api.js

@@ -1,5 +1,6 @@
 import fetch from 'node-fetch';
 import { getBaseUrl, getApiToken } from './config.js';
+import { logDebug, logError } from './logger.js';
 class ApiError extends Error {
     status;
     responseBody;
@@ -23,15 +24,48 @@ function getAuthHeaders(contentType = 'application/json') {
 }
 async function apiCall(method, path, body) {
     const baseUrl = getBaseUrl();
-    const response = await fetch(`${baseUrl}${path}`, {
+    const url = `${baseUrl}${path}`;
+    const started = Date.now();
+    logDebug('API request', {
         method,
-        headers: getAuthHeaders(),
-        body: body ? JSON.stringify(body) : undefined,
+        url,
+        hasBody: body != null,
     });
-    const data = await response.json().catch(() => ({}));
+    let response;
+    try {
+        response = await fetch(url, {
+            method,
+            headers: getAuthHeaders(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError('API network error', { method, url, message });
+        throw new ApiError(`Network error: ${message}`, 0, { cause: message });
+    }
+    const rawText = await response.text();
+    let data = {};
+    if (rawText) {
+        try {
+            data = JSON.parse(rawText);
+        }
+        catch {
+            data = { raw: rawText.slice(0, 2000) };
+        }
+    }
+    const durationMs = Date.now() - started;
     if (!response.ok) {
+        logError('API error response', {
+            method,
+            url,
+            status: response.status,
+            durationMs,
+            body: data,
+        });
         throw new ApiError(data.error || `HTTP ${response.status}`, response.status, data);
     }
+    logDebug('API success', { method, url, status: response.status, durationMs });
     return data;
 }
 async function apiFormCall(path, formData) {

package/dist/lib/format-api-error.d.ts

@@ -0,0 +1,2 @@
+export declare function formatApiErrorMessage(error: unknown): string;
+//# sourceMappingURL=format-api-error.d.ts.map

package/dist/lib/format-api-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-api-error.d.ts","sourceRoot":"","sources":["../../src/lib/format-api-error.ts"],"names":[],"mappings":"AAEA,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwB5D"}

package/dist/lib/format-api-error.js

@@ -0,0 +1,24 @@
+import { ApiError } from './api.js';
+export function formatApiErrorMessage(error) {
+    if (error instanceof ApiError) {
+        const parts = [`HTTP ${error.status}: ${error.message}`];
+        const body = error.responseBody;
+        if (body && typeof body === 'object') {
+            const record = body;
+            if (typeof record.hint === 'string') {
+                parts.push(`Hint: ${record.hint}`);
+            }
+            if (typeof record.detail === 'string') {
+                parts.push(`Detail: ${record.detail}`);
+            }
+            if (typeof record.code === 'string') {
+                parts.push(`Code: ${record.code}`);
+            }
+        }
+        return parts.join('\n');
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,8 @@
+export declare function getLogFilePath(): string;
+export declare function isVerbose(): boolean;
+export declare function writeLog(level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: Record<string, unknown>): void;
+export declare function logDebug(message: string, meta?: Record<string, unknown>): void;
+export declare function logInfo(message: string, meta?: Record<string, unknown>): void;
+export declare function logWarn(message: string, meta?: Record<string, unknown>): void;
+export declare function logError(message: string, meta?: Record<string, unknown>): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAOA,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,SAAS,IAAI,OAAO,CAOnC;AAmBD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC1C,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAIN;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAM9E;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE7E;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE7E;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE9E"}

package/dist/lib/logger.js

@@ -0,0 +1,51 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir } from './config.js';
+const LOG_DIR = join(getConfigDir(), 'logs');
+const LOG_FILE = join(LOG_DIR, 'cli.log');
+export function getLogFilePath() {
+    return LOG_FILE;
+}
+export function isVerbose() {
+    const verboseEnv = ['SCENEROK', '_', 'VERBOSE'].join('');
+    return (process.env[verboseEnv] === '1' ||
+        process.argv.includes('--verbose') ||
+        process.argv.includes('-v'));
+}
+function ensureLogDir() {
+    if (!existsSync(LOG_DIR)) {
+        mkdirSync(LOG_DIR, { recursive: true });
+    }
+}
+function formatMeta(meta) {
+    if (!meta || Object.keys(meta).length === 0) {
+        return '';
+    }
+    try {
+        return ` ${JSON.stringify(meta)}`;
+    }
+    catch {
+        return ' [meta unserializable]';
+    }
+}
+export function writeLog(level, message, meta) {
+    ensureLogDir();
+    const line = `[${new Date().toISOString()}] ${level.toUpperCase()} ${message}${formatMeta(meta)}\n`;
+    appendFileSync(LOG_FILE, line, 'utf-8');
+}
+export function logDebug(message, meta) {
+    writeLog('debug', message, meta);
+    if (isVerbose()) {
+        // eslint-disable-next-line no-console
+        console.error(`[debug] ${message}${formatMeta(meta)}`);
+    }
+}
+export function logInfo(message, meta) {
+    writeLog('info', message, meta);
+}
+export function logWarn(message, meta) {
+    writeLog('warn', message, meta);
+}
+export function logError(message, meta) {
+    writeLog('error', message, meta);
+}

package/examples/system/rokmilk-chocolate-promo.vid

@@ -2,6 +2,7 @@
 # Requires: scenerok secrets set XAI_API_KEY=... (or configured on scenerok.com account)
 
 import xai from "@scenerok/xai"
+import motion from "@scenerok/basic-animations"
 
 # Generated visuals — one clip per segment; prompts must use straight double quotes only
 [-] = video xai.imagine("Cinematic slow-motion pour of rich creamy chocolate milk into a sleek modern 250ml carton on marble, warm studio lighting, shallow depth of field, 9:16 vertical", aspect_ratio: "9:16", duration: 5)
@@ -10,13 +11,13 @@ import xai from "@scenerok/xai"
 
 [-] = video xai.imagine("Silky chocolate milk swirl in glass with RokMilk carton blurred in background, golden light, appetizing food cinematography, 9:16 vertical", aspect_ratio: "9:16", duration: 5)
 
-[0s .. 2.5s] = text "RokMilk", font: "Bebas Neue", size: 80, color: "#FFD700", x: "50%", y: "18%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 6, animate: fadeIn(0.6s)
+[0s .. 2.5s] = text "RokMilk", font: "Bebas Neue", size: 80, color: "#FFD700", x: "50%", y: "18%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 6, animate: motion.fadeIn(0.6s)
 
-[2s .. 5s] = text "Chocolate Milkshake", font: "Outfit", size: 56, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: riseIn(0.8s)
+[2s .. 5s] = text "Chocolate Milkshake", font: "Outfit", size: 56, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: motion.riseIn(0.8s)
 
-[5s .. 8s] = text "250ml of Pure Indulgence", font: "Inter", size: 42, color: "#F3E5AB", x: "50%", y: "55%", align: center, stroke: "#3E1C00", stroke_width: 2, animate: slideY(40, 0, 0.8s)
+[5s .. 8s] = text "250ml of Pure Indulgence", font: "Inter", size: 42, color: "#F3E5AB", x: "50%", y: "55%", align: center, stroke: "#3E1C00", stroke_width: 2, animate: motion.slideY(40, 0, 0.8s)
 
-[11s .. 14s] = text "visit your nearest grocery store", font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "82%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 3, animate: fadeIn(1s)
+[11s .. 14s] = text "visit your nearest grocery store", font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "82%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 3, animate: motion.fadeIn(1s)
 
 [0s .. 15s] = filter "vignette", intensity: 0.3
 [0s .. 15s] = filter "saturation", value: 1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "SceneRok CLI - Create videos from your terminal and agent workflows",
   "type": "module",
   "bin": {

package/skills/aider/SKILL.md

@@ -67,37 +67,32 @@ Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignett
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 
-### Module System
+### Package Imports
 
 ```vidscript
-export const BRAND_COLOR = "#FF5733"
-export timeline intro(clip: string, headline: string) {
-  [-] = clip                                # auto-append
-  clip.Trim(start: 0s, end: 3s)
-  [- 2s] = text headline, style: title      # auto-start, 2s duration
-}
+import xai from "@scenerok/xai"                    # xAI image/video/tts
+import eleven from "@elevenlabs/music"          # ElevenLabs generative music
+import motion from "@scenerok/basic-animations" # text/video animation helpers
 ```
 
-```vidscript
-import { intro } from "./timelines.vid"
-import * as pack from "./effects.vid"
-import eleven from "@elevenlabs/tts"  # future scoped package      # from npm registry
-import music from "@elevenlabs/music" # generative music
-use intro at [-] with { clip: main, headline: "Welcome" }
-```
-
-### Plugin Calls (required import)
+### Plugin Calls
 
 ```vidscript
 import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
 
 [-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
 [-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
+
+# ElevenLabs music package functions require an import alias.
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-**Always** add `import xai from "@scenerok/xai"` before any `xai.imagine` / `xai.tts` call or `animate: fadeIn(...)` helper. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+**Always** import the package that owns the function: `xai.*` from `@scenerok/xai`, `eleven.*` from `@elevenlabs/music`, and `motion.*` from `@scenerok/basic-animations`. Calls without import fail validation with `Unknown function 'xai.imagine'`.
 
-Put plugin calls **directly** in time blocks — never `let clip = xai.imagine(...)`.
+For ElevenLabs music, import `@elevenlabs/music` and call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Use `let bed = eleven.music(...)` followed by `audio bed, volume: ...` when you need volume or fades.
 
 Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).