@viji-dev/core 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -249,7 +249,7 @@ declare interface ButtonParameter {
  * The canvas rendering context a scene actually locked. Detected at runtime
  * (authoritative) once the context is acquired. See {@link SceneData.contextType}.
  */
-export declare type CanvasContextType = '2d' | 'webgl' | 'webgl2';
+export declare type CanvasContextType = '2d' | 'webgl' | 'webgl2' | 'webgpu';
 
 /**
  * An immediate edge in a capability's consumed-meaningfully state, delivered
@@ -277,7 +277,12 @@ export declare interface CapabilityTransition {
 export declare interface CaptureFrameOptions {
     /** Output format: `'blob'` for an encoded image, `'bitmap'` for a GPU-friendly `ImageBitmap`. Default: `'blob'`. */
     format?: 'blob' | 'bitmap';
-    /** MIME type for `'blob'` output (ignored for `'bitmap'`). Examples: `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
+    /**
+     * MIME type for `'blob'` output (ignored for `'bitmap'`). Examples:
+     * `'image/png'`, `'image/jpeg'`, `'image/webp'`. Default: `'image/png'`
+     * (lossless, preserves alpha). Pass a lossy type for smaller files when
+     * transparency does not matter.
+     */
     type?: string;
     /**
      * Encoding quality for lossy `'blob'` formats (`'image/jpeg'`, `'image/webp'`),
@@ -1317,6 +1322,12 @@ export declare interface PerformanceStats {
     resolution: Resolution;
     scale: number;
     frameRate: FrameRateInfo;
+    /**
+     * Worker spawn scheme the sandbox selected (see {@link WorkerSpawnScheme});
+     * `undefined` until the worker is up. Mirrors `getSceneData().workerSpawn`
+     * so support can read it from a stats snapshot alone.
+     */
+    workerSpawn?: WorkerSpawnScheme;
     cv?: {
         activeFeatures: CVFeature[];
         processingTime: number;
@@ -1593,11 +1604,17 @@ export declare interface SceneData {
     p5CanvasMode?: P5CanvasMode;
     /**
      * The canvas context the scene actually locked (`'2d'` / `'webgl'` /
-     * `'webgl2'`), detected at runtime. Present once the context locks (first
+     * `'webgl2'` / `'webgpu'`), detected at runtime. Present once the context locks (first
      * render); `undefined` before that. Authoritative — Core locks the context,
      * so this is exact even for native scenes with dynamic `useContext`.
      */
     contextType?: CanvasContextType;
+    /**
+     * Worker spawn scheme the sandbox selected for this core (see
+     * {@link WorkerSpawnScheme}). Present once the worker is up; `undefined`
+     * before initialization completes.
+     */
+    workerSpawn?: WorkerSpawnScheme;
     /** Capabilities the scene's code declares it uses (inclusive-biased). */
     capabilities: SceneCapabilities;
     /** Total number of parameters the scene defines. */
@@ -2308,7 +2325,7 @@ declare interface TouchPoint {
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.14.0";
+export declare const VERSION = "0.16.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2506,6 +2523,8 @@ export declare interface VijiAPI {
     ctx?: OffscreenCanvasRenderingContext2D;
     /** WebGL rendering context. `undefined` until `viji.useContext('webgl')` or `'webgl2'` is called; afterwards equals the cached context. */
     gl?: WebGLRenderingContext | WebGL2RenderingContext;
+    /** WebGPU canvas context. `undefined` until `viji.useContext('webgpu')` (or a direct `viji.canvas.getContext('webgpu')`) succeeds; afterwards equals the acquired context. Stays `undefined` on browsers without WebGPU support. */
+    gpu?: GPUCanvasContext;
     /** Current canvas width in pixels. Updates automatically when the host resizes the canvas; read every frame. */
     width: number;
     /** Current canvas height in pixels. Updates automatically when the host resizes the canvas; read every frame. */
@@ -2646,6 +2665,28 @@ export declare interface VijiAPI {
      * `null`. Choose ONE type and use it for the entire scene.
      */
     useContext(type: 'webgl2'): WebGL2RenderingContext | null;
+    /**
+     * Selects a WebGPU canvas context. Returns the raw `GPUCanvasContext` and
+     * also stores it on `viji.gpu`. Adapter and device acquisition stay in scene
+     * code (`navigator.gpu` is available; top-level `await` works), and the
+     * scene must call `configure()` on the context before rendering. A canvas
+     * only supports one context type. Returns `null` when a different context
+     * type was already requested OR when the browser has no WebGPU support,
+     * so always guard and provide a fallback. Choose ONE type and use it for
+     * the entire scene.
+     *
+     * @example
+     * const gctx = viji.useContext('webgpu');
+     * if (!navigator.gpu || !gctx) {
+     *   // fall back, e.g. render a message via a 2d scene variant
+     * } else {
+     *   const adapter = await navigator.gpu.requestAdapter();
+     *   const device = await adapter.requestDevice();
+     *   const format = navigator.gpu.getPreferredCanvasFormat();
+     *   gctx.configure({ device, format, alphaMode: 'opaque' });
+     * }
+     */
+    useContext(type: 'webgpu'): GPUCanvasContext | null;
 }
 
 /**
@@ -2690,6 +2731,8 @@ export declare class VijiCore {
     private sceneP5CanvasMode?;
     private sceneConsumesAnalysedFrame;
     private sceneContextType?;
+    /** Worker spawn scheme the sandbox selected; set once the worker is up. */
+    private sceneWorkerSpawn?;
     private parametersInitialized;
     private isAwaitingSceneAnalysis;
     private analysisWindowSceneError;
@@ -2711,6 +2754,12 @@ export declare class VijiCore {
      * Capture current scene frame
      * @param options.format 'blob' = encoded image, 'bitmap' = GPU-friendly ImageBitmap
      *
+     * Blob captures default to `'image/png'` (lossless, preserves alpha);
+     * pass a lossy `type` for smaller files. Alpha survives end to end on
+     * both formats, and bitmap captures always carry PREMULTIPLIED alpha
+     * regardless of renderer — dropping the alpha channel downstream always
+     * equals compositing the scene on black.
+     *
      * Readiness: the request queues in the worker and drains in the
      * post-render slot of the first tick where artist drawing code dispatched
      * cleanly against a canvas with a rendering context. Ticks where the scene
@@ -3940,4 +3989,14 @@ export declare class VijiCoreError extends Error {
     constructor(message: string, code: string, context?: any | undefined);
 }
 
+/**
+ * Worker spawn scheme selected by the iframe's capability probe: `'blob'`
+ * where a blob worker inside the sandbox is already a secure context
+ * (Firefox, Safari), `'data'` where it is not (Chromium), in which case the
+ * worker is spawned from a data: stub so scene code gains `[SecureContext]`
+ * APIs such as WebGPU. Diagnostic; surfaced in `getSceneData()` and
+ * `getStats()`.
+ */
+export declare type WorkerSpawnScheme = 'blob' | 'data';
+
 export { }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as E, I as o, V as s, a as C, b as I } from "./index-BYp7SdOD.js";
+import { C as E, I as o, V as s, a as C, b as I } from "./index-dImdtnwN.js";
 export {
   E as CV_FEATURE_KEYS,
   o as INPUT_CAPABILITY_KEYS,

package/package.json

@@ -1,116 +1,117 @@
-{
-  "name": "@viji-dev/core",
-  "version": "0.14.0",
-  "description": "Universal execution engine for Viji Creative scenes",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./scene-analysis": {
-      "import": "./dist/scene-analysis.js",
-      "types": "./dist/scene-analysis.d.ts"
-    },
-    "./param-inference": {
-      "import": "./dist/param-inference.js",
-      "types": "./dist/param-inference.d.ts"
-    },
-    "./package.json": "./package.json",
-    "./artist-global": {
-      "types": "./dist/artist-global.d.ts"
-    },
-    "./artist-dts": {
-      "import": "./dist/artist-dts.js",
-      "types": "./dist/artist-dts.d.ts"
-    },
-    "./artist-jsdoc": {
-      "types": "./dist/artist-jsdoc.d.ts"
-    },
-    "./artist-js-ambient": {
-      "types": "./dist/artist-js-ambient.d.ts"
-    },
-    "./artist-dts-p5": {
-      "import": "./dist/artist-dts-p5.js",
-      "types": "./dist/artist-dts-p5.d.ts"
-    },
-    "./artist-global-p5": {
-      "types": "./dist/artist-global-p5.d.ts"
-    },
-    "./shader-uniforms": {
-      "import": "./dist/shader-uniforms.js",
-      "types": "./dist/shader-uniforms.d.ts"
-    },
-    "./docs-api": {
-      "import": "./dist/docs-api.js",
-      "types": "./dist/docs-api.d.ts"
-    }
-  },
-  "files": [
-    "dist/*.js",
-    "dist/*.d.ts",
-    "dist/assets",
-    "!dist/**/*.map",
-    "README.md"
-  ],
-  "scripts": {
-    "audio-lab": "vite --config audio-lab/vite.config.mjs",
-    "prebuild": "node scripts/prebuild-clean.mjs && node scripts/sync-version.mjs",
-    "version": "npm run build && git add -A",
-    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/minify-dist.mjs && node scripts/build-artist-types.mjs && node scripts/lint-artist-types-drift.mjs && node scripts/build-docs-api.mjs",
-    "build:docs": "node scripts/build-docs-api.mjs",
-    "lint:ai-prompts-drift": "node scripts/lint-ai-prompts-drift.mjs",
-    "dev": "node scripts/sync-version.mjs && vite build --watch",
-    "integration": "vite --config integration-example/vite.config.ts",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "test:coverage": "vitest --coverage",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts"
-  },
-  "keywords": [
-    "viji",
-    "creative",
-    "webgl",
-    "audio-reactive",
-    "canvas",
-    "webworker"
-  ],
-  "author": "Viji Team",
-  "license": "SEE LICENSE IN LICENSE",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/p5": "^1.7.6",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "@vitest/coverage-v8": "^1.0.0",
-    "dts-bundle-generator": "^9.5.1",
-    "eslint": "^8.0.0",
-    "github-slugger": "^2.0.0",
-    "happy-dom": "^18.0.1",
-    "mdast-util-to-string": "^4.0.0",
-    "remark-parse": "^11.0.0",
-    "typescript": "^5.0.0",
-    "unified": "^11.0.5",
-    "vite": "^5.0.0",
-    "vite-plugin-dts": "^3.0.0",
-    "vitest": "^1.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@mediapipe/tasks-vision": "^0.10.20",
-    "@noble/ciphers": "2.3.0",
-    "@noble/curves": "^2.2.0",
-    "@noble/hashes": "2.2.0",
-    "acorn": "8.15.0",
-    "essentia.js": "^0.1.3",
-    "fft.js": "^4.0.4",
-    "sucrase": "^3.35.1"
-  }
-}
+{
+  "name": "@viji-dev/core",
+  "version": "0.16.0",
+  "description": "Universal execution engine for Viji Creative scenes",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./scene-analysis": {
+      "import": "./dist/scene-analysis.js",
+      "types": "./dist/scene-analysis.d.ts"
+    },
+    "./param-inference": {
+      "import": "./dist/param-inference.js",
+      "types": "./dist/param-inference.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./artist-global": {
+      "types": "./dist/artist-global.d.ts"
+    },
+    "./artist-dts": {
+      "import": "./dist/artist-dts.js",
+      "types": "./dist/artist-dts.d.ts"
+    },
+    "./artist-jsdoc": {
+      "types": "./dist/artist-jsdoc.d.ts"
+    },
+    "./artist-js-ambient": {
+      "types": "./dist/artist-js-ambient.d.ts"
+    },
+    "./artist-dts-p5": {
+      "import": "./dist/artist-dts-p5.js",
+      "types": "./dist/artist-dts-p5.d.ts"
+    },
+    "./artist-global-p5": {
+      "types": "./dist/artist-global-p5.d.ts"
+    },
+    "./shader-uniforms": {
+      "import": "./dist/shader-uniforms.js",
+      "types": "./dist/shader-uniforms.d.ts"
+    },
+    "./docs-api": {
+      "import": "./dist/docs-api.js",
+      "types": "./dist/docs-api.d.ts"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/assets",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "scripts": {
+    "audio-lab": "vite --config audio-lab/vite.config.mjs",
+    "prebuild": "node scripts/prebuild-clean.mjs && node scripts/sync-version.mjs",
+    "version": "npm run build && git add -A",
+    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/minify-dist.mjs && node scripts/build-artist-types.mjs && node scripts/lint-artist-types-drift.mjs && node scripts/build-docs-api.mjs",
+    "build:docs": "node scripts/build-docs-api.mjs",
+    "lint:ai-prompts-drift": "node scripts/lint-ai-prompts-drift.mjs",
+    "dev": "node scripts/sync-version.mjs && vite build --watch",
+    "integration": "vite --config integration-example/vite.config.ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest --coverage",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "viji",
+    "creative",
+    "webgl",
+    "audio-reactive",
+    "canvas",
+    "webworker"
+  ],
+  "author": "Viji Team",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/p5": "^1.7.6",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "@webgpu/types": "0.1.72",
+    "dts-bundle-generator": "^9.5.1",
+    "eslint": "^8.0.0",
+    "github-slugger": "^2.0.0",
+    "happy-dom": "^18.0.1",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "typescript": "^5.0.0",
+    "unified": "^11.0.5",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mediapipe/tasks-vision": "^0.10.20",
+    "@noble/ciphers": "2.3.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "2.2.0",
+    "acorn": "8.15.0",
+    "essentia.js": "^0.1.3",
+    "fft.js": "^4.0.4",
+    "sucrase": "^3.35.1"
+  }
+}