ujjwalvivek/substrate: A tiny (~1000 LOC) vanilla JS procedural wallpaper engine with theme support.

A tiny (~1000 LOC) vanilla JS procedural wallpaper engine with theme support. - ujjwalvivek/substrate

Summary

Substrate is a composable procedural graphics engine with a GPU runtime that renders WGSL primitives through WebGPU, plus a Canvas2D reference runtime for comparison and fallback. The repository's description also mentions a tiny (~1000 LOC) vanilla JS procedural wallpaper engine with theme support, though the README does not document that component in detail.

What it is useful for

Substrate is useful for engineers building procedural visuals — generative patterns, animated backgrounds, or themed wallpapers — without hand-rolling a WebGPU pipeline from scratch. Because shaders are written in WGSL, it fits teams already working in that language or targeting modern browsers. The Canvas2D runtime gives you a fallback for environments without WebGPU, and the colors subpath exposes getThemeColors, which is a way to drive visuals from a theme palette.

How engineers can use it

The README documents this workflow:

1. Install and start the playground:

npm install
npm run dev

This builds the package and serves a playground on port 4321.

2. Build or inspect the package:

npm run build       # builds the package and playground, stages the playground
npm run pack:check  # shows exactly what the npm package would contain

3. Import the GPU engine from the package root:

import {
  SubstrateGPU,
  compose,
  primitives,
  shaderDescriptors,
} from "@ujjwalvivek/substrate";

4. Use the Canvas2D reference engine or color helpers via subpath imports:

import * as CPU from "@ujjwalvivek/substrate/cpu";
import { getThemeColors } from "@ujjwalvivek/substrate/colors";

5. Add custom shaders by placing a *.wgsl file under packages/substrate/src/shaders/primitives/. Each file must include a /* @substrate { ... } */ metadata block and one or more supported primitive functions; the renderer discovers them at build time.

6. Run npm run validate to confirm all primitive WGSL files are well-formed.

Documented limitations: the README does not list the supported primitive functions, specify the fields allowed inside the @substrate metadata block, or describe how the wallpaper engine is structured — those details live in the shader contract README at packages/substrate/src/shaders/primitives/README.md.