@aperveil/runtime

Framework-independent WebGPU runtime for portable Aperveil shaders, including simulations and meshes.

import { startAperveilShader } from "@aperveil/runtime";

const controller = startAperveilShader(canvas, wgsl, runtimeSpec, {
  initialParameters,
});

// Later:
controller.setParameters({ speed: 0.4 });
controller.stop();

toUniforms(schema, values) turns friendly values ("#7af0ff", "nebula", [0.5, 0.5]) into those uniforms, clamping numbers and falling back to defaults. onUnsupported fires when the browser has no WebGPU; hasWebGpu() checks the same.

The package has no runtime dependencies: the browser build of vgpu (MIT) is bundled in, so installing it never pulls Node's native WebGPU binding. See THIRD_PARTY_NOTICES.md.

@aperveil/runtime/gpu exposes that WebGPU layer itself (init, surface, effect, draw, target, compute, frameLoop and their types). Installed Aperveil blocks draw their multi-pass and mesh materials with it; the two entry points share one bundled copy.

React, WordPress and vanilla integrations should wrap this runtime instead of reimplementing timing, DPR, pointer coordinates, reduced-motion handling or the render loop.

New exported shaders carry a compatibility contract with schemaVersion: 1, minRuntime: "0.1.1" and maxRuntimeExclusive: "0.2.0". Shaders using logo resources, branch bend bindings, pointer-entry bindings or the Glass Medusae renderer require minRuntime: "0.1.2". Only stable major.minor.patch versions within those bounds are accepted. Validation happens before GPU allocation: an incompatible contract calls onError, or throws when there is no callback. Legacy specs without this field remain supported.

assertRuntimeCompatibility(contract) and RUNTIME_VERSION are also exported by the React, Vue and element adapters. Generated wrappers check the adapter at module load (Vue SFCs during setup), so an older adapter cannot silently ignore new metadata. Upgrade runtime and adapter together. Installation errors happen before mounting; normal rendering errors still use the adapter's fallback.

Resource-backed text/artwork pipelines remain on their application-specific paths.