# vshaders

vshaders is a registry of composable WGSL shader effects built on [vgpu](https://vgpu.sh). This file tells AI agents what exists today and what does not.

## The two-layer model

- Pure WGSL modules: functions only, no bindings, no entry points. These ship as versioned npm packages under `@vshaders/*` and are imported from shaders through vgpu's WGSL module system.
- Effects: complete entry shaders that compose those modules, plus a React wrapper. Effects are copied into consumer projects and owned there, in the spirit of shadcn/ui.

## What exists today

- Five packages on npm at 0.2.0, installable now: `@vshaders/sdf` (signed distance functions and operators), `@vshaders/color` (OKLab and OKLCH conversions, perceptual mixing, cosine palettes), `@vshaders/dither` (ordered Bayer dithering), `@vshaders/ease` (easing curves and motion shaping), `@vshaders/fluid` (Stable Fluids simulation kernels).
- Eleven effects, rendered live on this site with editors at `/effects/<slug>`: mesh gradient, metaballs, palette field, flow, ripple, dither, fluid, displacement, god rays, heatmap, undertones. Fluid is a real multi-pass simulation (advection, pressure projection, vorticity confinement), driven only by the cursor, contained walls by default.
- Every shader in the registry passes `vgpu check --require-validation`.

## The shadcn-compatible registry

The registry works today. Index at [/r/registry.json](/r/registry.json); eleven installable items: [/r/mesh-gradient.json](/r/mesh-gradient.json), [/r/metaballs.json](/r/metaballs.json), [/r/palette-field.json](/r/palette-field.json), [/r/flow.json](/r/flow.json), [/r/ripple.json](/r/ripple.json), [/r/dither.json](/r/dither.json), [/r/fluid.json](/r/fluid.json), [/r/displacement.json](/r/displacement.json), [/r/god-rays.json](/r/god-rays.json), [/r/heatmap.json](/r/heatmap.json), [/r/undertones.json](/r/undertones.json).

- Install: `npx shadcn@latest add https://vshaders.com/r/mesh-gradient.json`
- Or register the namespace once (`npx shadcn@latest registry add @vshaders=https://vshaders.com/r/{name}.json`), then `npx shadcn@latest add @vshaders/mesh-gradient`
- The `add` step needs a valid `components.json` first; `/docs/effects` shows a minimal hand-written one for CI or agent runs (no Tailwind setup needed).

All eleven items install cleanly: their npm dependencies are published. The fluid and displacement items ship their own runners (`lib/fluid-runner.ts`, `lib/displacement-runner.ts`) in place of the shared `lib/run-effect.ts`; dither and heatmap ship the filter pass alone. Things to know, all spelled out in each item's `docs` field (printed by the CLI on install and reproduced on the effect's page under Install):

- Displacement's background is an image the registry does not ship: pass the component's `imageUrl` prop at an asset of your project.
- Heatmap and displacement bridge CPU pixels to the GPU through a storage buffer plus one unpack pass (vgpu targets take no direct pixel upload); the heatmap item ships `shaders/heatmap-unpack.wgsl` for exactly this, and `/docs/effects` documents the pattern.
- Color spaces differ by effect: generative effects take linear-light RGB (convert hex through the sRGB transfer function, or use the editor's Copy params button); dither, heatmap, and ripple's ring color are display-referred sRGB. `/docs/effects` has the conversion snippet.

## What is coming

- Composition ids that encode tuned uniform values, installed with `vshaders add <id>`.
- A read-only MCP endpoint for searching and fetching effects.