Abstract
This document discloses a novel portable package format — the .vis package — implemented in IKANDY for bundling AI-generated or user-authored GPU shaders (GLSL and WGSL) together with their complete creation provenance: the original natural-language prompt, shader type classification, auto-generated thumbnail, attribution metadata, and creation timestamp. The format is designed for lossless redistribution, community sharing, and Steam Workshop integration without loss of creative origin information.
This publication is intended to establish prior art. Any subsequent patent claim covering this method or substantially similar methods is anticipated by this disclosure.
Background & Problem Statement
Real-time GPU shader communities (Shadertoy, Bonzomatic, Processing, ISF) distribute shaders as raw source code files. These files carry no structured record of:
| Missing Metadata | Consequence |
|---|---|
| Original generative prompt | AI-generated shaders lose the instruction that produced them — reproduction is impossible |
| Attribution (author, license) | Redistribution strips credit; license compliance is manual and error-prone |
| Thumbnail preview | Community browsers require running the shader to assess it; GPU cost before preview |
| Shader type / target runtime | GLSL and WGSL files are indistinguishable without inspection; wrong-runtime loads fail silently |
| Creation timestamp | Version ordering and provenance dating rely entirely on filesystem metadata, which is fragile |
No prior shader distribution format bundles generative prompt provenance, auto-captured thumbnail, and runtime type classification as a first-class structural concern alongside source code.
The .vis Package Structure
A .vis package consists of three co-located files sharing a common base name. Together they form a complete, self-describing shader unit:
or .wgsl
The GPU fragment shader source. GLSL targets WebGL via an inline renderer; WGSL targets WebGPU via the _wgpuUserScene() factory. Boilerplate (uniform struct, vertex stage, bindings) is managed by the host — the file contains only the fragment function body.
JSON sidecar. Contains: prompt (original natural-language instruction), shaderType ("glsl" or "wgsl"), code (snapshot of fragment source at save time), thumbPath (relative path to the thumbnail), specFlags (AI generation parameters), author, license, sourceUrl, createdAt (ISO 8601).
160×90 PNG auto-captured from the live canvas 3 seconds after first successful shader mount. Stored as a base64 data URL decoded server-side before write. Displayed as the card background in the preset browser without requiring the shader to re-run. Size-capped at 512 KB by the IPC handler.
// MyScene.vis.json — canonical structure { "prompt": "neon audio-reactive waves with bass bloom", "shaderType": "wgsl", "code": "@fragment fn fs_main(...) { ... }", "thumbPath": "MyScene.thumb.png", "specFlags": { "mode": "wgsl", "audioReactive": true }, "author": "IKANDY", "license": "CC0", "sourceUrl": "", "createdAt": "2026-05-14T19:43:22.000Z" }
Thumbnail Capture Method
Thumbnail generation is fully automatic and requires no user action:
Step 1 — On successful shader mount, a 3-second timer is started against the active canvas reference and the scene name.
Step 2 — After 3 seconds, the system confirms the user has not navigated away (scene name still matches). If confirmed, the canvas is drawn into a 160×90 offscreen canvas via drawImage().
Step 3 — toDataURL('image/png') encodes the frame. The data URL is transmitted to the Electron main process via IPC, decoded from base64, and written to disk as [basename].thumb.png.
Step 4 — The in-memory thumbnail cache is updated immediately. Open preset browser cards update without requiring a panel close/reopen.
On next application launch, _refreshUserScenes() issues parallel loadThumb() IPC calls for each scene entry and primes the thumbnail cache from disk. Cards show their saved previews on first panel open with no shader execution required.
Distribution & Workshop Readiness
The three-file triple (.glsl/.wgsl + .vis.json + .thumb.png) is designed for lossless packaging into a distributable archive. To produce a shareable .vis bundle, the host application zips the triple:
# Canonical .vis bundle structure MyScene.zip (renamed to MyScene.vis) ├── MyScene.wgsl # fragment source ├── MyScene.vis.json # provenance + metadata └── MyScene.thumb.png # 160×90 preview
A receiving IKANDY instance unzips the bundle, validates filename structure against the same regex used for local saves, applies the shader scrub pipeline (scrubGLSL / scrubWGSL) on import, and adds the scene to the user's local library. Attribution and prompt from .vis.json are displayed in the preset card without re-generation.
The format is designed to be the payload unit for a Steam Workshop integration. Each Workshop item is one .vis bundle. No server-side transformation is required — the bundle is self-describing at every stage of the distribution pipeline.
What Makes This Novel
Existing shader distribution systems (Shadertoy export, ISF format, Processing sketches, Bonzomatic session files) distribute source code only. No prior format bundles generative prompt provenance + auto-captured GPU-rendered thumbnail + runtime type classification + attribution metadata as co-equal first-class fields alongside the shader source in a single distributable unit.
The combination of these elements constitutes the novel format:
1 Generative prompt stored as a first-class provenance field
2 Runtime type classification (glsl / wgsl) embedded in sidecar
3 Auto-captured GPU-rendered thumbnail at fixed resolution and timing
4 Attribution and license as structured fields, not free-text comments
5 ISO 8601 creation timestamp independent of filesystem metadata
6 Three-file co-location pattern enabling atomic zip-based distribution
Security Constraints
The IPC handlers enforcing the .vis package write path implement the following safeguards: filename regex (/^[a-zA-Z0-9 _\-]+\.(thumb\.png|vis\.json)$/) rejects double-extension smuggling; path traversal (..) is blocked; .thumb.png writes are capped at 512 KB; .vis.json writes are capped at 256 KB; thumbnail payloads must be valid data:image/png;base64,… data URLs decoded server-side before disk write. Shader source imported from a .vis bundle passes through the same scrubGLSL / scrubWGSL pipeline used for all user-submitted code, which rejects fetch, XMLHttpRequest, eval, import, document, and window references.
Implementation Context
The .vis package format is implemented in IKANDY, an Electron 30-based music visualizer running on Windows. Sidecar writes are handled by main.js IPC handlers ikandy:customscenes:saveVis, :loadVis, :saveThumb, and :loadThumb. The preset browser reads sidecar data via preload.js bridge methods exposed as customScenes.saveVis(), .loadVis(), .saveThumb(), .loadThumb().
This technical disclosure was published at ikandy.app and constitutes prior art as of its effective date.