@viji-dev/core 0.15.0 → 0.16.0

package/dist/docs-api.js

@@ -1,7 +1,7 @@
 export const docsApi = {
   "version": "1.1.0",
-  "coreVersion": "0.15.0",
-  "generatedAt": "2026-08-25T15:25:24.042Z",
+  "coreVersion": "0.16.0",
+  "generatedAt": "2026-08-26T17:41:23.222Z",
   "navigation": [
     {
       "id": "getting-started",
@@ -1748,6 +1748,11 @@ export const docsApi = {
           "level": 3,
           "text": "Shorthand: viji.gpu"
         },
+        {
+          "id": "transparency",
+          "level": 2,
+          "text": "Transparency"
+        },
         {
           "id": "resolution-agnostic-drawing",
           "level": 2,
@@ -1817,7 +1822,7 @@ export const docsApi = {
         },
         {
           "type": "text",
-          "markdown": "### Shorthand: `viji.gpu`\r\n\r\nAfter a successful `viji.useContext('webgpu')` (or a direct `viji.canvas.getContext('webgpu')`), the same context is also available as `viji.gpu`.\r\n\r\nGet a fresh swapchain texture with `getCurrentTexture()` every frame inside `render()`; never cache it across frames. A failed WebGPU request doesn't bind the canvas, so the fallback branch can still acquire `'2d'`. A GPU device can be lost (driver reset, tab backgrounding on some platforms): listen on `device.lost`, then re-request the adapter and device and `configure()` again. The engine tolerates reconfiguration at any time. For running ONNX models on the WebGPU execution provider, see [External Libraries](/native/external-libraries).\r\n\r\n## Resolution-Agnostic Drawing\r\n\r\nThe canvas can be any size, from a small preview to fullscreen 4K, and the host can resize it at any time. Your scene must adapt automatically.\r\n\r\n> [!NOTE]\r\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\r\n\r\n### Dimension Properties\r\n\r\n| Property | Type | Description |\r\n|----------|------|-------------|\r\n| `viji.width` | `number` | Current canvas width in pixels |\r\n| `viji.height` | `number` | Current canvas height in pixels |\r\n\r\nBoth values update automatically when the host resizes the canvas. Read them every frame inside `render()`: don't cache them at the top level.\r\n\r\n### Centering and Proportional Sizing\r\n\r\nExpress all positions and sizes relative to the canvas dimensions:\r\n\r\n```javascript\r\n// Good: scales with canvas\r\nconst cx = viji.width / 2;\r\nconst cy = viji.height / 2;\r\nconst r = Math.min(viji.width, viji.height) * 0.3;\r\n\r\n// Bad: breaks at different resolutions\r\nconst cx = 400;\r\nconst cy = 300;\r\nconst r = 150;\r\n```\r\n\r\nUse `Math.min(viji.width, viji.height)` when you need uniform scaling: it ensures elements stay proportional regardless of aspect ratio. Use `viji.width` or `viji.height` individually when you want an element to stretch with one axis (e.g., a full-width bar).\r\n\r\n### Proportional Margins and Spacing\r\n\r\n```javascript\r\nconst margin = Math.min(viji.width, viji.height) * 0.05;\r\nconst usableW = viji.width - margin * 2;\r\nconst usableH = viji.height - margin * 2;\r\n```\r\n\r\n### Comparison Across Renderers\r\n\r\n| Concept | Native | P5 | Shader |\r\n|---------|--------|-----|--------|\r\n| Canvas width | `viji.width` | `viji.width` / `p5.width` | `u_resolution.x` |\r\n| Canvas height | `viji.height` | `viji.height` / `p5.height` | `u_resolution.y` |\r\n| Aspect ratio | `viji.width / viji.height` | `viji.width / viji.height` | `u_resolution.x / u_resolution.y` |\r\n| Uniform scale | `Math.min(viji.width, viji.height)` | `Math.min(viji.width, viji.height)` | `min(u_resolution.x, u_resolution.y)` |\r\n\r\n## Environment Constraints\r\n\r\n> [!WARNING]\r\n> Scenes run in a Web Worker. There is no `window`, `document`, `Image()`, `localStorage`, or any DOM API. All inputs (audio, video, images) are provided through the Viji API. One exception: `fetch()` is available, so you can load external data (JSON, etc.) from CDNs.\r\n\r\n## Next Steps\r\n\r\n- [Timing](/native/timing): [`viji.time`](/native/timing), [`viji.deltaTime`](/native/timing), frame counting\r\n- [Parameters](/native/parameters): sliders, colors, toggles\r\n- [P5 Canvas & Resolution](/p5/canvas-resolution): how P5 handles canvas and sizing\r\n- [Shader Resolution](/shader/resolution): `u_resolution` and coordinate normalization\r\n- [API Reference](/native/api-reference): full list of everything available"
+          "markdown": "### Shorthand: `viji.gpu`\r\n\r\nAfter a successful `viji.useContext('webgpu')` (or a direct `viji.canvas.getContext('webgpu')`), the same context is also available as `viji.gpu`.\r\n\r\nGet a fresh swapchain texture with `getCurrentTexture()` every frame inside `render()`; never cache it across frames. A failed WebGPU request doesn't bind the canvas, so the fallback branch can still acquire `'2d'`. A GPU device can be lost (driver reset, tab backgrounding on some platforms): listen on `device.lost`, then re-request the adapter and device and `configure()` again. The engine tolerates reconfiguration at any time. For running ONNX models on the WebGPU execution provider, see [External Libraries](/native/external-libraries).\r\n\r\n## Transparency\r\n\r\nA scene that leaves alpha below 1 renders with a transparent background: whatever the host shows behind the canvas stays visible through unpainted and semi-transparent pixels. Skip the opaque background fill and the pixels stay clear. What appears behind a transparent scene is the host's choice, not the scene's.\r\n\r\nPer context:\r\n\r\n- **2D**: use alpha as usual (`'rgba(...)'` fills and clears). The browser handles the pixel format.\r\n- **WebGL / WebGL2**: the drawing buffer is premultiplied. Output premultiplied colors or use the premultiplied blend mode (`gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)`). Three.js manages this for you.\r\n- **WebGPU**: configure with `alphaMode: 'premultiplied'` instead of `'opaque'`.\r\n\r\n## Resolution-Agnostic Drawing\r\n\r\nThe canvas can be any size, from a small preview to fullscreen 4K, and the host can resize it at any time. Your scene must adapt automatically.\r\n\r\n> [!NOTE]\r\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\r\n\r\n### Dimension Properties\r\n\r\n| Property | Type | Description |\r\n|----------|------|-------------|\r\n| `viji.width` | `number` | Current canvas width in pixels |\r\n| `viji.height` | `number` | Current canvas height in pixels |\r\n\r\nBoth values update automatically when the host resizes the canvas. Read them every frame inside `render()`: don't cache them at the top level.\r\n\r\n### Centering and Proportional Sizing\r\n\r\nExpress all positions and sizes relative to the canvas dimensions:\r\n\r\n```javascript\r\n// Good: scales with canvas\r\nconst cx = viji.width / 2;\r\nconst cy = viji.height / 2;\r\nconst r = Math.min(viji.width, viji.height) * 0.3;\r\n\r\n// Bad: breaks at different resolutions\r\nconst cx = 400;\r\nconst cy = 300;\r\nconst r = 150;\r\n```\r\n\r\nUse `Math.min(viji.width, viji.height)` when you need uniform scaling: it ensures elements stay proportional regardless of aspect ratio. Use `viji.width` or `viji.height` individually when you want an element to stretch with one axis (e.g., a full-width bar).\r\n\r\n### Proportional Margins and Spacing\r\n\r\n```javascript\r\nconst margin = Math.min(viji.width, viji.height) * 0.05;\r\nconst usableW = viji.width - margin * 2;\r\nconst usableH = viji.height - margin * 2;\r\n```\r\n\r\n### Comparison Across Renderers\r\n\r\n| Concept | Native | P5 | Shader |\r\n|---------|--------|-----|--------|\r\n| Canvas width | `viji.width` | `viji.width` / `p5.width` | `u_resolution.x` |\r\n| Canvas height | `viji.height` | `viji.height` / `p5.height` | `u_resolution.y` |\r\n| Aspect ratio | `viji.width / viji.height` | `viji.width / viji.height` | `u_resolution.x / u_resolution.y` |\r\n| Uniform scale | `Math.min(viji.width, viji.height)` | `Math.min(viji.width, viji.height)` | `min(u_resolution.x, u_resolution.y)` |\r\n\r\n## Environment Constraints\r\n\r\n> [!WARNING]\r\n> Scenes run in a Web Worker. There is no `window`, `document`, `Image()`, `localStorage`, or any DOM API. All inputs (audio, video, images) are provided through the Viji API. One exception: `fetch()` is available, so you can load external data (JSON, etc.) from CDNs.\r\n\r\n## Next Steps\r\n\r\n- [Timing](/native/timing): [`viji.time`](/native/timing), [`viji.deltaTime`](/native/timing), frame counting\r\n- [Parameters](/native/parameters): sliders, colors, toggles\r\n- [P5 Canvas & Resolution](/p5/canvas-resolution): how P5 handles canvas and sizing\r\n- [Shader Resolution](/shader/resolution): `u_resolution` and coordinate normalization\r\n- [API Reference](/native/api-reference): full list of everything available"
         }
       ]
     },
@@ -7241,7 +7246,7 @@ export const docsApi = {
       "content": [
         {
           "type": "text",
-          "markdown": "# Shader Basics\n\nThe shader renderer lets you write GLSL fragment shaders that run on the GPU. Viji handles the fullscreen quad, uniform injection, and compilation pipeline. This page covers the fundamentals: how a shader scene is structured, what Viji auto-injects, and how GLSL versions work.\n\n## The `@renderer` Directive\n\n> [!IMPORTANT]\n> P5 and shader scenes must declare their renderer type as the first comment:\n> ```\n> // @renderer p5\n> ```\n> or\n> ```\n> // @renderer shader\n> ```\n> Without this directive, the scene defaults to the native renderer.\n\n## Fragment Shader Structure\n\nA Viji shader scene is a GLSL fragment shader. You write only `void main()` (and optional helper functions): Viji provides everything else:\n\n```glsl\n// @renderer shader\n\nvoid main() {\n  vec2 uv = gl_FragCoord.xy / u_resolution;\n  gl_FragColor = vec4(uv, 0.5, 1.0);\n}\n```\n\nThere is no vertex shader to write. Viji renders a fullscreen quad that covers the entire canvas: your fragment shader determines the color of every pixel."
+          "markdown": "# Shader Basics\n\nThe shader renderer lets you write GLSL fragment shaders that run on the GPU. Viji handles the fullscreen quad, uniform injection, and compilation pipeline. This page covers the fundamentals: how a shader scene is structured, what Viji auto-injects, and how GLSL versions work.\n\n## The `@renderer` Directive\n\n> [!IMPORTANT]\n> P5 and shader scenes must declare their renderer type as the first comment:\n> ```\n> // @renderer p5\n> ```\n> or\n> ```\n> // @renderer shader\n> ```\n> Without this directive, the scene defaults to the native renderer.\n\n## Fragment Shader Structure\n\nA Viji shader scene is a GLSL fragment shader. You write only `void main()` (and optional helper functions): Viji provides everything else:\n\n```glsl\n// @renderer shader\n\nvoid main() {\n  vec2 uv = gl_FragCoord.xy / u_resolution;\n  gl_FragColor = vec4(uv, 0.5, 1.0);\n}\n```\n\nThere is no vertex shader to write. Viji renders a fullscreen quad that covers the entire canvas: your fragment shader determines the color of every pixel.\n\nWrite the color and alpha your math produces: alpha below 1 makes the scene transparent there, showing whatever the host displays behind the canvas. The engine premultiplies your output for you; do not multiply rgb by alpha yourself."
         },
         {
           "type": "live-example",
@@ -9707,7 +9712,7 @@ export const docsApi = {
       "content": [
         {
           "type": "text",
-          "markdown": "# Backbuffer & Feedback\n\nThe backbuffer gives your shader access to the previous frame's output as a `sampler2D` texture. This enables feedback effects, trails, motion blur, paint strokes, and accumulation patterns, where each frame builds on the last.\n\n## How to Enable\n\nReference `backbuffer` anywhere in your shader code. Viji detects the word via a string search and activates the ping-pong framebuffer system automatically: no directive or configuration is needed:\n\n```glsl\nvec4 prev = texture2D(backbuffer, uv);\n```\n\n> [!WARNING]\n> The detection is a literal string search across the entire shader source. If `backbuffer` appears in a comment, even `// TODO: add backbuffer later`, the system activates. Remove or rename such comments to avoid unnecessary resource allocation.\n\n## Uniform Reference\n\n| Property | Value |\n|----------|-------|\n| Name | `backbuffer` |\n| Type | `sampler2D` |\n| Prefix | None: `backbuffer`, not `u_backbuffer` |\n| Resolution | Matches canvas size exactly ([`u_resolution`](/shader/resolution#u_resolution)) |\n| Format | RGBA, 8 bits per channel (`gl_UNSIGNED_BYTE`) |\n| Filtering | Linear (bilinear interpolation between texels) |\n| Wrapping | Clamp-to-edge on both axes |\n| Initial state | `vec4(0.0)`: transparent black on the first frame |\n\nThe uniform is auto-injected when the system is active. Do not redeclare it.\n\n## Sampling\n\nSample the backbuffer with standard texture lookup. The texture coordinates match the canvas UV space:\n\n```glsl\nvec2 uv = gl_FragCoord.xy / u_resolution;\nvec4 previous = texture2D(backbuffer, uv); // GLSL ES 1.00\n```\n\nFor GLSL ES 3.00 shaders, use `texture()` instead:\n\n```glsl\nvec4 previous = texture(backbuffer, uv); // GLSL ES 3.00\n```\n\nOn the first frame, `backbuffer` samples as `vec4(0.0, 0.0, 0.0, 0.0)` everywhere. Your shader should handle this gracefully: most feedback patterns naturally produce the correct result since mixing with black is a no-op.\n\n## Trail / Fade Effect\n\nThe most common backbuffer pattern: mix the previous frame with new content using a decay factor. Each frame, old content fades toward black while new content is drawn on top."
+          "markdown": "# Backbuffer & Feedback\n\nThe backbuffer gives your shader access to the previous frame's output as a `sampler2D` texture. This enables feedback effects, trails, motion blur, paint strokes, and accumulation patterns, where each frame builds on the last. Backbuffer texels are premultiplied: rgb is already scaled by alpha when you sample them.\n\n## How to Enable\n\nReference `backbuffer` anywhere in your shader code. Viji detects the word via a string search and activates the ping-pong framebuffer system automatically: no directive or configuration is needed:\n\n```glsl\nvec4 prev = texture2D(backbuffer, uv);\n```\n\n> [!WARNING]\n> The detection is a literal string search across the entire shader source. If `backbuffer` appears in a comment, even `// TODO: add backbuffer later`, the system activates. Remove or rename such comments to avoid unnecessary resource allocation.\n\n## Uniform Reference\n\n| Property | Value |\n|----------|-------|\n| Name | `backbuffer` |\n| Type | `sampler2D` |\n| Prefix | None: `backbuffer`, not `u_backbuffer` |\n| Resolution | Matches canvas size exactly ([`u_resolution`](/shader/resolution#u_resolution)) |\n| Format | RGBA, 8 bits per channel (`gl_UNSIGNED_BYTE`) |\n| Filtering | Linear (bilinear interpolation between texels) |\n| Wrapping | Clamp-to-edge on both axes |\n| Initial state | `vec4(0.0)`: transparent black on the first frame |\n\nThe uniform is auto-injected when the system is active. Do not redeclare it.\n\n## Sampling\n\nSample the backbuffer with standard texture lookup. The texture coordinates match the canvas UV space:\n\n```glsl\nvec2 uv = gl_FragCoord.xy / u_resolution;\nvec4 previous = texture2D(backbuffer, uv); // GLSL ES 1.00\n```\n\nFor GLSL ES 3.00 shaders, use `texture()` instead:\n\n```glsl\nvec4 previous = texture(backbuffer, uv); // GLSL ES 3.00\n```\n\nOn the first frame, `backbuffer` samples as `vec4(0.0, 0.0, 0.0, 0.0)` everywhere. Your shader should handle this gracefully: most feedback patterns naturally produce the correct result since mixing with black is a no-op.\n\n## Trail / Fade Effect\n\nThe most common backbuffer pattern: mix the previous frame with new content using a decay factor. Each frame, old content fades toward black while new content is drawn on top."
         },
         {
           "type": "live-example",

package/dist/{essentia-wasm.web-BE_39Nld.js → essentia-wasm.web-0ZL6uVXZ.js}

@@ -1,4 +1,4 @@
-import { g as kn } from "./index-CuQT5y06.js";
+import { g as kn } from "./index-dImdtnwN.js";
 function jn(Oe, ot) {
   for (var ve = 0; ve < ot.length; ve++) {
     const Z = ot[ve];

package/dist/{index-CuQT5y06.js → index-dImdtnwN.js}

@@ -533,7 +533,10 @@ class bB {
   <title>Viji Scene Container</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
-    html, body { width: 100%; height: 100%; overflow: hidden; background: #000; }
+    /* Transparent on purpose: the backdrop belongs to the host page. Scene
+       pixels with alpha < 1 (including the pre-first-paint window) show
+       whatever the host paints behind the iframe. */
+    html, body { width: 100%; height: 100%; overflow: hidden; background: transparent; }
     canvas { display: block; width: 100%; height: 100%; image-rendering: auto; }
   </style>
 </head>
@@ -594,7 +597,7 @@ class bB {
       }
   }
 }
-const HB = "" + new URL("assets/viji.worker-A8uAea-6.js", import.meta.url).href;
+const HB = "" + new URL("assets/viji.worker-Dm3yyu15.js", import.meta.url).href;
 class ZB {
   constructor(A, B, I) {
     this.iframeManager = A, this.sceneCode = B, this.init = I;
@@ -1625,7 +1628,7 @@ class zB {
     if (!this.isInitialized)
       return this.initPromise ? this.initPromise : (this.initPromise = (async () => {
         try {
-          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-BE_39Nld.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
+          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-0ZL6uVXZ.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
           let Q = B.default || B.EssentiaWASM || B.default?.EssentiaWASM;
           if (!Q)
             throw new Error("WASM module not found - check essentia-wasm.web.js export");
@@ -11998,7 +12001,7 @@ function jI(D) {
     expectedVersion: 1
   } : typeof A.senderTime != "number" ? { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" } : null;
 }
-const $I = "0.15.0";
+const $I = "0.16.0";
 export {
   _I as C,
   TI as I,

package/dist/index.d.ts

@@ -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'`),
@@ -2320,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.15.0";
+export declare const VERSION = "0.16.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2749,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

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-CuQT5y06.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,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "sideEffects": false,