@viji-dev/sdk 1.0.0

package/.gitignore

@@ -0,0 +1,29 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Documentation for other project parts
+/core_docs
+/backend_docs
+/sdk_docs

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko.  
+All rights reserved.
+
+Permission is granted to install and use this software for the purpose of 
+developing creative scenes or related content for the VIJI platform.
+
+Artists may freely use the SDK to create, test, and share their own scenes 
+without restriction. Redistribution or modification of the SDK itself, or 
+use of the SDK for purposes unrelated to developing for the VIJI platform, 
+is prohibited without prior written permission from the copyright holders.
+
+This license does not grant any rights to copy, sublicense, or commercialize 
+the SDK itself, nor to use the VIJI name or brand without permission.

package/README.md

@@ -0,0 +1,103 @@
+# Viji SDK
+
+Professional toolkit for creating interactive Viji scenes. Includes a CLI, workspace management, local development UI (Vite-based), and a production build pipeline that outputs a single deployable `scene.js`. Uses `@viji-dev/core` under the hood.
+
+## Installation
+
+```bash
+npm install -g @viji-dev/sdk
+```
+
+## Quick Start
+
+```bash
+# Create a new workspace
+mkdir my-viji-workspace
+cd my-viji-workspace
+viji init .
+
+# Create your first scene
+viji create my-scene --lang=ts
+
+# Start development server
+viji dev
+```
+
+## CLI Commands
+
+### `viji init [workspace-name]`
+Initialize a new Viji workspace with complete development environment.
+- Use `viji init .` to initialize in current directory
+- Use `viji init my-workspace` to create new directory
+
+### `viji create <scene-name> [--lang=js|ts]`
+Create a new scene in the current workspace.
+- Must be run inside a Viji workspace
+- Creates scene in `scenes/<scene-name>/` folder
+
+### `viji dev [--port=5173] [--host=localhost] [--open]`
+Start development server with hot reload.
+- Must be run inside a Viji workspace
+- Opens browser-based development UI
+
+### `viji build <scene-name> [--output=dist/scene.js]`
+Build a scene for platform deployment.
+- Compiles multi-file project to single JS file
+- Ready for copy-paste to Viji platform
+
+## Workspace Structure
+
+```
+my-workspace/
+├── src/                    # Development UI (React + Vite)
+├── scenes/                 # Your scenes
+│   ├── my-scene/          
+│   │   └── main.ts        # Scene entry point
+│   └── another-scene/
+├── vite.config.ts         # Vite configuration
+├── package.json           # Dependencies
+└── ...                    # TypeScript configs, etc.
+```
+
+## Scene Development
+
+Each scene is a folder in `scenes/` with a `main.js` or `main.ts` entry point:
+
+```typescript
+// scenes/my-scene/main.ts
+export const parameters = [
+  // Parameter definitions
+];
+
+export function init(canvas: HTMLCanvasElement, audioContext: AudioContext) {
+  // Initialization code
+}
+
+export function render(state: any, inputs: any, params: any) {
+  // Main render loop
+}
+```
+
+## Features
+
+- **🎨 Complete Development Environment**: Full React UI for scene development
+- **🔥 Hot Reload**: Instant updates when you save scene files
+- **📁 Workspace Management**: Organize multiple scenes in one project
+- **🛠️ TypeScript Support**: Full type safety and IDE integration
+- **📦 Single-File Build**: Compile to platform-ready scene.js
+- **🎯 Platform Compatible**: Uses same Core runtime as Viji platform
+
+## Documentation
+
+- SDK package: `docs/02-sdk-package.md`
+- Implementation guide: `docs/06-cursor-implementation-guide.md`
+
+## 📄 License
+
+Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko.  
+All rights reserved - see the LICENSE file for details.
+
+## Contributor License Agreement
+
+By contributing, you agree to the [CLA](./CLA.md).  
+Please also confirm your agreement by filling out this short [form](https://forms.gle/A49WTz8nj5b99Yev7).

package/bin/viji.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Viji SDK Command Line Interface
+ * Professional toolkit for creating interactive Viji scenes
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { program } = require('commander');
+import { createCommand } from '../src/cli/commands/create.js';
+import { devCommand } from '../src/cli/commands/dev.js';
+import { buildCommand } from '../src/cli/commands/build.js';
+import { initCommand } from '../src/cli/commands/init.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+// Get package.json version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packagePath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packagePath, 'utf8'));
+
+program
+  .name('viji')
+  .description('🎨 Viji SDK - Professional toolkit for creating interactive scenes')
+  .version(packageJson.version);
+
+// Command: Initialize new workspace
+program
+  .command('init')
+  .argument('[workspace-name]', 'Name of the workspace (use "." for current directory)', '.')
+  .description('Initialize a new Viji workspace')
+  .action(initCommand);
+
+// Command: Create new scene
+program
+  .command('create')
+  .argument('<scene-name>', 'Name of the new scene')
+  .option('--lang <lang>', 'Scene language (js|ts)', 'js')
+  .description('Create a new scene in the current workspace')
+  .action(createCommand);
+
+// Command: Start development server
+program
+  .command('dev')
+  .option('-p, --port <port>', 'Development server port', '5173')
+  .option('-h, --host <host>', 'Development server host', 'localhost')
+  .option('--open', 'Open browser automatically', false)
+  .description('Start development server with hot reload')
+  .action(devCommand);
+
+// Command: Build for production
+program
+  .command('build')
+  .argument('<scene-name>', 'Name of the scene to build')
+  .option('-o, --output <file>', 'Output file path', 'dist/scene.js')
+  .description('Build scene: bundle multi-file projects into one, no minify')
+  .action(buildCommand);
+
+
+// Global error handling
+process.on('uncaughtException', (error) => {
+  console.error('💥 Unexpected error:', error.message);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  console.error('💥 Unhandled promise rejection:', reason);
+  process.exit(1);
+});
+
+// Parse and execute
+program.parse();

package/eslint.config.js

@@ -0,0 +1,37 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { globalIgnores } from 'eslint/config'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['scenes/**/*.{js,ts}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: {
+        ...globals.browser,
+        viji: 'readonly',
+        render: 'readonly',
+      },
+    },
+    rules: {
+      'no-undef': 'off',
+    },
+  },
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/favicon.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>VIJI SDK - Creative Development Toolkit</title>
+    
+    <!-- Security headers for @viji-dev/core workers and iframes -->
+    <meta http-equiv="Cross-Origin-Embedder-Policy" content="credentialless" />
+    <meta http-equiv="Cross-Origin-Opener-Policy" content="same-origin" />
+    
+    <!-- Permissions for media access -->
+    <meta http-equiv="Feature-Policy" content="camera 'self'; microphone 'self'; display-capture 'self'" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@viji-dev/sdk",
+  "private": false,
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Professional toolkit for creating interactive Viji scenes",
+  "keywords": [
+    "viji",
+    "interactive",
+    "visualization",
+    "art",
+    "sdk",
+    "cli"
+  ],
+  "author": "Viji Team",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "viji": "./bin/viji.js"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "cli:dev": "node bin/viji.js dev",
+    "cli:build": "node bin/viji.js build",
+    "cli:create": "node bin/viji.js create"
+  },
+  "main": "src/main.tsx",
+  "files": [
+    "bin/",
+    "src/",
+    "scenes/",
+    "public/",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig*.json",
+    "tailwind.config.js",
+    "postcss.config.js",
+    "eslint.config.js",
+    ".gitignore",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/viji-dev/sdk.git"
+  },
+  "homepage": "https://github.com/viji-dev/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/viji-dev/sdk/issues"
+  },
+  "dependencies": {
+    "@heroicons/react": "^2.2.0",
+    "@heroui/react": "^2.7.11",
+    "@viji-dev/core": "^0.2.4",
+    "autoprefixer": "^10.4.21",
+    "chokidar": "^4.0.0",
+    "clsx": "^2.1.1",
+    "commander": "^12.0.0",
+    "framer-motion": "^12.18.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "tailwind-merge": "^3.3.1",
+    "tailwindcss": "^3.4.17",
+    "zustand": "^5.0.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.33.0",
+    "@types/node": "^24.3.0",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "@vitejs/plugin-react": "^4.5.2",
+    "eslint": "^9.33.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.3.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.39.1",
+    "vite": "^6.3.5"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}; 

package/scenes/audio-visualizer/main.js

@@ -0,0 +1,287 @@
+// Audio Reactive Visualizer Scene - Parameter Object API
+console.log('🎵 AUDIO VISUALIZER SCENE LOADED');
+
+// Define parameters using helper functions (returns parameter objects)
+const primaryColor = viji.color('#ff6b6b', {
+  label: 'Primary Color',
+  description: 'Main color for frequency bars',
+  group: 'colors'
+});
+
+const secondaryColor = viji.color('#4ecdc4', {
+  label: 'Secondary Color',
+  description: 'Background and accent color',
+  group: 'colors'
+});
+
+const backgroundColor = viji.color('#1a1a2e', {
+  label: 'Background Color',
+  description: 'Scene background color',
+  group: 'colors'
+});
+
+const audioSensitivity = viji.slider(2.0, {
+  min: 0.1,
+  max: 5.0,
+  step: 0.1,
+  label: 'Audio Sensitivity',
+  description: 'Overall sensitivity to audio input',
+  group: 'audio',
+  category: 'audio'
+});
+
+const bassBoost = viji.slider(1.5, {
+  min: 0.5,
+  max: 3.0,
+  step: 0.1,
+  label: 'Bass Boost',
+  description: 'Amplification for bass frequencies',
+  group: 'audio',
+  category: 'audio'
+});
+
+const trebleBoost = viji.slider(1.2, {
+  min: 0.5,
+  max: 3.0,
+  step: 0.1,
+  label: 'Treble Boost',
+  description: 'Amplification for treble frequencies',
+  group: 'audio',
+  category: 'audio'
+});
+
+const barCount = viji.slider(64, {
+  min: 8,
+  max: 128,
+  step: 8,
+  label: 'Bar Count',
+  description: 'Number of frequency analysis bars',
+  group: 'visual'
+});
+
+const barSpacing = viji.slider(2, {
+  min: 0,
+  max: 10,
+  step: 1,
+  label: 'Bar Spacing',
+  description: 'Space between frequency bars',
+  group: 'visual'
+});
+
+const showWaveform = viji.toggle(true, {
+  label: 'Show Waveform',
+  description: 'Display audio waveform overlay',
+  group: 'visual'
+});
+
+const showCenterCircle = viji.toggle(true, {
+  label: 'Show Center Circle',
+  description: 'Show reactive circle in center',
+  group: 'visual'
+});
+
+const rotationSpeed = viji.slider(0.5, {
+  min: -2.0,
+  max: 2.0,
+  step: 0.1,
+  label: 'Rotation Speed',
+  description: 'Speed of circular rotation',
+  group: 'animation'
+});
+
+const pulseIntensity = viji.slider(0.8, {
+  min: 0.0,
+  max: 2.0,
+  step: 0.1,
+  label: 'Pulse Intensity',
+  description: 'Intensity of audio-driven pulsing',
+  group: 'animation'
+});
+
+const smoothing = viji.slider(0.7, {
+  min: 0.0,
+  max: 0.95,
+  step: 0.05,
+  label: 'Smoothing',
+  description: 'Temporal smoothing of audio data',
+  group: 'animation'
+});
+
+const mouseInfluence = viji.toggle(true, {
+  label: 'Mouse Influence',
+  description: 'Allow mouse to affect visualization',
+  group: 'interaction',
+  category: 'interaction'
+});
+
+const mouseRadius = viji.slider(100, {
+  min: 50,
+  max: 300,
+  step: 10,
+  label: 'Mouse Radius',
+  description: 'Radius of mouse influence',
+  group: 'interaction',
+  category: 'interaction'
+});
+
+// Render function using parameter object API with interactions, audio, and video
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  
+  // Get interaction state
+  const mouse = viji.mouse;
+  const keyboard = viji.keyboard;
+  const touches = viji.touches;
+  
+  // Get audio state
+  const audio = viji.audio;
+  
+  // Get video state
+  const video = viji.video;
+  
+  // Clear background
+  ctx.fillStyle = backgroundColor.value;
+  ctx.fillRect(0, 0, viji.width, viji.height);
+  
+  // Only proceed if audio is connected
+  if (!audio || !audio.isConnected) {
+    // Show instructions when no audio
+    ctx.fillStyle = primaryColor.value;
+    ctx.font = '24px Arial';
+    ctx.textAlign = 'center';
+    ctx.fillText('🎵 Connect audio to see visualization', viji.width / 2, viji.height / 2);
+    
+    ctx.font = '16px Arial';
+    ctx.fillStyle = secondaryColor.value;
+    ctx.fillText('Use the audio controls to connect microphone, file, or screen audio', viji.width / 2, viji.height / 2 + 40);
+    return;
+  }
+  
+  const centerX = viji.width / 2;
+  const centerY = viji.height / 2;
+  
+  // Get audio data with parameters
+  const currentVolume = (((audio && audio.volume && audio.volume.rms) || 0)) * audioSensitivity.value;
+  const bassEnergy = ((((audio && audio.bands && audio.bands.bass) || 0) + ((audio && audio.bands && audio.bands.subBass) || 0)) / 2) * bassBoost.value;
+  const trebleEnergy = ((((audio && audio.bands && audio.bands.treble) || 0) + ((audio && audio.bands && audio.bands.presence) || 0)) / 2) * trebleBoost.value;
+  
+  // Center reactive circle
+  if (showCenterCircle.value) {
+    const circleRadius = 50 + (currentVolume * pulseIntensity.value * 100);
+    const circleAlpha = Math.min(1, currentVolume * 2);
+    
+    // Outer circle (bass reactive)
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, circleRadius + (bassEnergy * 50), 0, Math.PI * 2);
+    ctx.strokeStyle = primaryColor.value + Math.floor(circleAlpha * 128).toString(16).padStart(2, '0');
+    ctx.lineWidth = 3;
+    ctx.stroke();
+    
+    // Inner circle (treble reactive)
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, circleRadius * 0.6 + (trebleEnergy * 30), 0, Math.PI * 2);
+    ctx.fillStyle = secondaryColor.value + Math.floor(circleAlpha * 64).toString(16).padStart(2, '0');
+    ctx.fill();
+  }
+  
+  // Frequency bars in circular arrangement
+  const radius = Math.min(viji.width, viji.height) * 0.3;
+  const bands = ['subBass', 'bass', 'lowMid', 'mid', 'highMid', 'presence', 'brilliance', 'treble'];
+  
+  for (let i = 0; i < barCount.value; i++) {
+    const angle = (i / barCount.value) * Math.PI * 2 + (viji.time * rotationSpeed.value);
+    const bandIndex = Math.floor((i / barCount.value) * bands.length);
+    const bandValue = (audio && audio.bands ? (audio.bands[bands[bandIndex]] || 0) : 0);
+    
+    // Apply audio sensitivity
+    const barHeight = bandValue * audioSensitivity.value * 200;
+    
+    // Mouse influence
+    let mouseInfluenceValue = 1;
+    if (mouseInfluence.value && mouse && mouse.isInCanvas) {
+      const barX = centerX + Math.cos(angle) * radius;
+      const barY = centerY + Math.sin(angle) * radius;
+      const distToMouse = Math.sqrt((barX - mouse.x) ** 2 + (barY - mouse.y) ** 2);
+      
+      if (distToMouse < mouseRadius.value) {
+        mouseInfluenceValue = 1 + (1 - distToMouse / mouseRadius.value) * 2;
+      }
+    }
+    
+    const finalBarHeight = barHeight * mouseInfluenceValue;
+    
+    // Calculate bar position
+    const startX = centerX + Math.cos(angle) * radius;
+    const startY = centerY + Math.sin(angle) * radius;
+    const endX = centerX + Math.cos(angle) * (radius + finalBarHeight);
+    const endY = centerY + Math.sin(angle) * (radius + finalBarHeight);
+    
+    // Color based on frequency band
+    const hue = (bandIndex / bands.length) * 360;
+    const intensity = Math.min(1, bandValue * audioSensitivity.value * 3);
+    ctx.strokeStyle = `hsla(${hue}, 80%, ${50 + intensity * 30}%, ${0.6 + intensity * 0.4})`;
+    ctx.lineWidth = Math.max(1, (viji.width / barCount.value) - barSpacing.value);
+    
+    // Draw frequency bar
+    ctx.beginPath();
+    ctx.moveTo(startX, startY);
+    ctx.lineTo(endX, endY);
+    ctx.stroke();
+  }
+  
+  // Waveform overlay
+  if (showWaveform.value && audio.isConnected) {
+    ctx.strokeStyle = primaryColor.value + '60';
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    
+    // Simulate waveform
+    for (let x = 0; x < viji.width; x += 4) {
+      const waveY = centerY + Math.sin(x * 0.02 + viji.time * 3 + bassEnergy * 10) * 
+                    (currentVolume * 50) + 
+                    Math.sin(x * 0.05 + viji.time * 5 + trebleEnergy * 15) * 
+                    (currentVolume * 25);
+      
+      if (x === 0) {
+        ctx.moveTo(x, waveY);
+      } else {
+        ctx.lineTo(x, waveY);
+      }
+    }
+    ctx.stroke();
+  }
+  
+  // Audio info display
+  ctx.fillStyle = primaryColor.value + 'CC';
+  ctx.font = '14px monospace';
+  ctx.textAlign = 'left';
+  
+  let infoY = 20;
+  ctx.fillText('🎵 AUDIO REACTIVE VISUALIZER', 20, infoY);
+  infoY += 20;
+  ctx.fillText(`Volume: ${(currentVolume * 100).toFixed(1)}%`, 20, infoY);
+  infoY += 16;
+  ctx.fillText(`Bass: ${(bassEnergy * 100).toFixed(1)}%`, 20, infoY);
+  infoY += 16;
+  ctx.fillText(`Treble: ${(trebleEnergy * 100).toFixed(1)}%`, 20, infoY);
+  infoY += 16;
+  ctx.fillText(`Bars: ${barCount.value}`, 20, infoY);
+  
+  // Mouse interaction indicator
+  if (mouseInfluence.value && mouse && mouse.isInCanvas) {
+    ctx.strokeStyle = secondaryColor.value + '80';
+    ctx.lineWidth = 2;
+    ctx.setLineDash([5, 5]);
+    ctx.beginPath();
+    ctx.arc(mouse.x, mouse.y, mouseRadius.value, 0, Math.PI * 2);
+    ctx.stroke();
+    ctx.setLineDash([]);
+  }
+  
+  // Performance info
+  ctx.fillStyle = secondaryColor.value + 'AA';
+  ctx.font = '12px monospace';
+  ctx.textAlign = 'right';
+  ctx.fillText(`Frame: ${viji.frameCount}`, viji.width - 20, viji.height - 25);
+  ctx.fillText(`Time: ${viji.time.toFixed(1)}s`, viji.width - 20, viji.height - 10);
+}