@viji-dev/sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,20 +1,26 @@
 # Viji SDK
 
-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.
+Development environment for [Viji Creative](https://viji.art) scenes. Write scene code in your IDE, preview it live in the browser with real-time parameter controls, audio analysis, video input, and interaction handling — the same execution environment as the Viji platform. Supports Canvas 2D, WebGL, P5.js, and GLSL shaders.
 
 ## Installation
 
+Requires [Node.js](https://nodejs.org/) v18 or later.
+
 ```bash
 npm install -g @viji-dev/sdk
 ```
 
-No other prerequisites required — just your IDE.
+To update to the latest version:
+
+```bash
+npm update -g @viji-dev/sdk
+```
 
 ## Quick Start
 
 ```bash
-# Create a project directory and enter it
-mkdir my-project && cd my-project
+# Create a workspace folder (any name works)
+mkdir my-viji-scenes && cd my-viji-scenes
 
 # Create your first scene (native renderer is the default)
 viji create my-scene
@@ -58,7 +64,7 @@ The server watches the `scenes/` directory for changes and pushes updates to the
 
 ### `viji build <scene-name> [-o <file>]`
 
-Bundle a scene into a single file for deployment.
+Bundle a scene into a single file for deployment to the Viji platform.
 
 ```bash
 viji build my-scene                       # outputs dist/my-scene.js
@@ -67,114 +73,20 @@ viji build my-scene -o bundle/output.js   # custom output path
 
 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();
-}
-```
-
-Available contexts: `viji.useContext('2d')`, `viji.useContext('webgl')`, `viji.useContext('webgl2')`.
-
-### P5 Renderer
-
-```javascript
-// @renderer p5
-
-const speed = viji.slider(1.0, { min: 0.1, max: 5.0, label: 'Speed' });
-
-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
-
-```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);
-}
-```
-
-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`.
+## Writing Scenes
 
-## Viji API
+The SDK includes built-in documentation for the Viji scene API, parameter system, renderers, audio/video analysis, and interaction handling.
 
-The `viji` object passed to `render()` provides:
+Start the development server and open the docs panel from the toolbar, or navigate directly to `http://localhost:3000/docs`.
 
-| 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 |
+The documentation includes live code playgrounds where you can experiment with the API directly in the browser.
 
 ## Project Structure
 
-After creating a few scenes, your project looks like this:
+After creating a few scenes, your workspace looks like this:
 
 ```
-my-project/
+my-viji-scenes/
 ├── scenes/
 │   ├── my-scene/
 │   │   └── main.js
@@ -185,7 +97,7 @@ my-project/
 └── global.d.ts          # IDE type support (auto-generated)
 ```
 
-No configuration files, no `node_modules`, no build tools in the artist's directory. Everything is handled by the globally installed SDK.
+No configuration files, no `node_modules`, no build tools in your workspace. Everything is handled by the globally installed SDK.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/sdk",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "Professional toolkit for creating interactive Viji scenes",
   "keywords": [
@@ -68,8 +68,8 @@
     "typescript-eslint": "^8.39.1",
     "vite": "^6.3.5",
     "zustand": "^5.0.6",
-    "@viji-dev/design-system": "0.1.0",
-    "@viji-dev/docs-viewer": "0.1.0"
+    "@viji-dev/docs-viewer": "0.1.0",
+    "@viji-dev/design-system": "0.1.0"
   },
   "scripts": {
     "dev": "vite",

package/src/cli/commands/create.js

@@ -1,9 +1,20 @@
-import { mkdir, writeFile } from 'fs/promises';
+import { mkdir, writeFile, readFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
-import { getSceneTemplate, getGlobalDts, getSceneFileExtension, VALID_RENDERERS } from '../../templates/scene-templates.js';
+import { join, dirname } from 'path';
+import { createRequire } from 'module';
+import { getSceneTemplate, getGlobalDtsFileName, getSceneFileExtension, VALID_RENDERERS } from '../../templates/scene-templates.js';
 import { validateProjectName } from '../utils/cli-utils.js';
 
+function resolveCoreDtsPath(fileName) {
+  try {
+    const require = createRequire(import.meta.url);
+    const coreEntry = require.resolve('@viji-dev/core');
+    return join(dirname(coreEntry), fileName);
+  } catch {
+    return null;
+  }
+}
+
 export async function createCommand(sceneName, options) {
   try {
     const renderer = options.renderer || 'native';
@@ -38,10 +49,17 @@ export async function createCommand(sceneName, options) {
 
     const globalDtsPath = join(cwd, 'global.d.ts');
     if (!existsSync(globalDtsPath)) {
-      const dtsContent = getGlobalDts(renderer);
-      if (dtsContent) {
-        await writeFile(globalDtsPath, dtsContent);
-        console.log('Created global.d.ts for IDE type support');
+      const dtsFileName = getGlobalDtsFileName(renderer);
+      if (dtsFileName) {
+        const dtsSourcePath = resolveCoreDtsPath(dtsFileName);
+        if (dtsSourcePath && existsSync(dtsSourcePath)) {
+          const dtsContent = await readFile(dtsSourcePath, 'utf-8');
+          await writeFile(globalDtsPath, dtsContent);
+          console.log('Created global.d.ts for IDE type support');
+        } else {
+          console.warn('Could not locate core type definitions — global.d.ts was not created.');
+          console.warn('IDE autocompletion for the Viji API may not be available.');
+        }
       }
     }
 

package/src/templates/scene-templates.js

@@ -60,9 +60,9 @@ void main() {
 `,
 };
 
-const GLOBAL_DTS = {
-  native: `/// <reference types="@viji-dev/core/artist-global" />\n`,
-  p5: `/// <reference types="@viji-dev/core/artist-global-p5" />\n`,
+const GLOBAL_DTS_FILE = {
+  native: 'artist-global.d.ts',
+  p5: 'artist-global-p5.d.ts',
   shader: null,
 };
 
@@ -74,8 +74,8 @@ export function getSceneTemplate(renderer = 'native') {
   return template;
 }
 
-export function getGlobalDts(renderer = 'native') {
-  return GLOBAL_DTS[renderer] ?? GLOBAL_DTS.native;
+export function getGlobalDtsFileName(renderer = 'native') {
+  return GLOBAL_DTS_FILE[renderer] ?? GLOBAL_DTS_FILE.native;
 }
 
 export function getSceneFileExtension(renderer = 'native') {