@viji-dev/sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Professional toolkit for creating interactive Viji scenes. Install globally, create scenes with a single command, and launch a local development server with live reload. Uses `@viji-dev/core` under the hood.
 
 ## Installation
 
@@ -8,96 +8,191 @@ Professional toolkit for creating interactive Viji scenes. Includes a CLI, works
 npm install -g @viji-dev/sdk
 ```
 
+No other prerequisites required — just your IDE.
+
 ## Quick Start
 
 ```bash
-# Create a new workspace
-mkdir my-viji-workspace
-cd my-viji-workspace
-viji init .
+# Create a project directory and enter it
+mkdir my-project && cd my-project
 
-# Create your first scene
-viji create my-scene --lang=ts
+# Create your first scene (native renderer is the default)
+viji create my-scene
 
-# Start development server
+# Start the development server
 viji dev
 ```
 
+Open `http://localhost:3000` in your browser to see the SDK UI. Edit `scenes/my-scene/main.js` in your IDE — changes appear in real time.
+
 ## 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> [--renderer <type>]`
+
+Create a new scene in the `scenes/` folder.
+
+- `viji create my-scene` — native renderer (Canvas 2D / WebGL), the default
+- `viji create my-scene --renderer p5` — P5.js renderer
+- `viji create my-scene --renderer shader` — GLSL fragment shader
+
+Creates the following structure:
+
+```
+scenes/
+└── my-scene/
+    └── main.js        # or main.glsl for shader scenes
+global.d.ts            # generated once for IDE type support
+```
+
+### `viji dev [--port <port>] [--host <host>] [--open]`
+
+Start the development server with live reload.
 
-### `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
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port` | `3000` | Server port |
+| `--host` | `localhost` | Server host |
+| `--open` | `false` | Open browser automatically |
 
-### `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
+The server watches the `scenes/` directory for changes and pushes updates to the browser UI in real time via WebSocket.
 
-### `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
+### `viji build <scene-name> [-o <file>]`
 
-## Workspace Structure
+Bundle a scene into a single file for deployment.
 
+```bash
+viji build my-scene                       # outputs dist/my-scene.js
+viji build my-scene -o bundle/output.js   # custom output path
 ```
-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.
+
+Multi-file scenes (with local imports) are resolved and concatenated automatically.
+
+## Scene API
+
+### Native Renderer
+
+```javascript
+// @renderer native
+
+const speed = viji.slider(1.0, { min: 0.1, max: 5.0, label: 'Speed' });
+const baseColor = viji.color('#4488ff', { label: 'Color' });
+
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  const { width, height, time } = viji;
+
+  ctx.fillStyle = '#000000';
+  ctx.fillRect(0, 0, width, height);
+
+  const x = width / 2 + Math.cos(time * speed.value) * 100;
+  const y = height / 2 + Math.sin(time * speed.value) * 100;
+
+  ctx.beginPath();
+  ctx.arc(x, y, 40, 0, Math.PI * 2);
+  ctx.fillStyle = baseColor.value;
+  ctx.fill();
+}
 ```
 
-## Scene Development
+Available contexts: `viji.useContext('2d')`, `viji.useContext('webgl')`, `viji.useContext('webgl2')`.
+
+### P5 Renderer
 
-Each scene is a folder in `scenes/` with a `main.js` or `main.ts` entry point:
+```javascript
+// @renderer p5
 
-```typescript
-// scenes/my-scene/main.ts
-export const parameters = [
-  // Parameter definitions
-];
+const speed = viji.slider(1.0, { min: 0.1, max: 5.0, label: 'Speed' });
 
-export function init(canvas: HTMLCanvasElement, audioContext: AudioContext) {
-  // Initialization code
+function render(viji, p5) {
+  p5.background(0);
+  const x = viji.width / 2 + p5.cos(viji.time * speed.value) * 100;
+  const y = viji.height / 2 + p5.sin(viji.time * speed.value) * 100;
+  p5.noStroke();
+  p5.fill(255);
+  p5.ellipse(x, y, 80, 80);
 }
+```
+
+### GLSL Shader
 
-export function render(state: any, inputs: any, params: any) {
-  // Main render loop
+```glsl
+// @renderer shader
+precision highp float;
+
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform vec2 u_mouse;
+
+void main() {
+    vec2 uv = gl_FragCoord.xy / u_resolution;
+    vec3 col = 0.5 + 0.5 * cos(u_time + uv.xyx + vec3(0.0, 2.0, 4.0));
+    gl_FragColor = vec4(col, 1.0);
 }
 ```
 
-## Features
+Shader scenes receive a full set of uniforms automatically: `u_resolution`, `u_time`, `u_deltaTime`, `u_mouse`, `u_audio*`, `u_video*`, and more. See the core documentation for the complete uniform list.
+
+## Parameter System
+
+Parameters create UI controls that artists can tweak in real time:
+
+```javascript
+const speed = viji.slider(1.0, { min: 0, max: 10, label: 'Speed' });
+const tint = viji.color('#ff0000', { label: 'Tint' });
+const mirror = viji.toggle(false, { label: 'Mirror' });
+const mode = viji.select('circles', { options: ['circles', 'squares', 'lines'], label: 'Mode' });
+const label = viji.text('Hello', { label: 'Label' });
+const count = viji.number(5, { min: 1, max: 100, step: 1, label: 'Count' });
+const bg = viji.image(null, { label: 'Background' });
+const reset = viji.button({ label: 'Reset' });
+```
+
+Access values via `speed.value`, `tint.value`, etc. Button parameters expose `reset.pressed`.
+
+## Viji API
+
+The `viji` object passed to `render()` provides:
 
-- **🎨 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
+| Property | Type | Description |
+|----------|------|-------------|
+| `canvas` | `OffscreenCanvas` | The rendering canvas |
+| `width`, `height` | `number` | Canvas dimensions |
+| `time` | `number` | Elapsed time in seconds |
+| `deltaTime` | `number` | Time since last frame |
+| `frameCount` | `number` | Total frames rendered |
+| `fps` | `number` | Current frames per second |
+| `audio` | `AudioAPI` | Audio analysis (volume, bands, beat, spectral) |
+| `video` | `VideoAPI` | Video input |
+| `mouse` | `MouseAPI` | Mouse position and buttons |
+| `keyboard` | `KeyboardAPI` | Key states (`isPressed`, `wasPressed`, `wasReleased`) |
+| `touches` | `TouchAPI` | Touch points |
+| `pointer` | `PointerAPI` | Unified pointer input |
+| `device` | `DeviceSensorState` | Accelerometer, gyroscope |
 
-## Documentation
+## Project Structure
+
+After creating a few scenes, your project looks like this:
+
+```
+my-project/
+├── scenes/
+│   ├── my-scene/
+│   │   └── main.js
+│   ├── shader-demo/
+│   │   └── main.glsl
+│   └── p5-sketch/
+│       └── main.js
+└── global.d.ts          # IDE type support (auto-generated)
+```
 
-- SDK package: `docs/02-sdk-package.md`
-- Implementation guide: `docs/06-cursor-implementation-guide.md`
+No configuration files, no `node_modules`, no build tools in the artist's directory. Everything is handled by the globally installed SDK.
 
-## 📄 License
+## License
 
-Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko.  
-All rights reserved - see the LICENSE file for details.
+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).
+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

@@ -1,22 +1,15 @@
 #!/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');
@@ -24,52 +17,39 @@ const packageJson = JSON.parse(readFileSync(packagePath, 'utf8'));
 
 program
   .name('viji')
-  .description('🎨 Viji SDK - Professional toolkit for creating interactive scenes')
+  .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')
+  .option('--renderer <type>', 'Renderer type (native|p5|shader)', 'native')
   .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('-p, --port <port>', 'Development server port', '3000')
+  .option('--host <host>', 'Development server host', 'localhost')
   .option('--open', 'Open browser automatically', false)
-  .description('Start development server with hot reload')
+  .description('Start development server with live 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')
+  .option('-o, --output <file>', 'Output file path')
+  .description('Build scene: bundle multi-file projects into one')
   .action(buildCommand);
 
-
-// Global error handling
 process.on('uncaughtException', (error) => {
-  console.error('💥 Unexpected error:', error.message);
+  console.error('Unexpected error:', error.message);
   process.exit(1);
 });
 
 process.on('unhandledRejection', (reason) => {
-  console.error('💥 Unhandled promise rejection:', reason);
+  console.error('Unhandled promise rejection:', reason);
   process.exit(1);
 });
 
-// Parse and execute
 program.parse();