@shader-gallery/components

The framework-agnostic shader-as-data toolkit. A shader.gallery effect is one self-contained .frag carrying an embedded /*@shader … */ JSON header; this package turns any conforming frag into the { frag, meta } the @shader-gallery/runtime already consumes, plus the schema, the shared GLSL prelude, and the import/validate/typegen CLIs.

This is the foundation decided in ADR-0004: the catalog is the whole corpus exposed uniformly, growing by author-one-frag, not a curated marquee set. The full authoring spec an AI writes against is CONTRACT.md.

It is the framework-agnostic half only. The typed components live in the existing @shader-gallery/react / vue / svelte packages, which each gained a shader() export built on this package's parseShader

• splitProps. There is no @shader-gallery/components/react subpath.

npm install @shader-gallery/components

Author one frag

An effect is a single fragment shader with a JSON header in a leading GLSL comment. The header names the effect and declares its tweakable uniform float params; the body is ordinary WebGL1 GLSL that reads the runtime uniforms (u_time, u_resolution, u_mouse, u_pixelRatio, u_palette[4]) plus your params.

/*@shader
{
  "name": "Pulse",
  "slug": "pulse",
  "defaultPalette": "midnight",
  "params": [
    { "uniform": "u_speed", "label": "Speed", "min": 0, "max": 4, "step": 0.01,
      "default": 1.0, "effect": "How fast the pulse breathes out from the centre." }
  ]
}
*/
precision highp float;
uniform float u_time;
uniform vec2  u_resolution;
uniform vec3  u_palette[4];
uniform float u_speed;            // a param -> becomes the `speed` component prop

void main() {
  vec2  uv = gl_FragCoord.xy / u_resolution;
  float d  = distance(uv, vec2(0.5));
  float p  = 0.5 + 0.5 * sin(u_time * u_speed - d * 12.0);
  gl_FragColor = vec4(mix(u_palette[0], u_palette[2], p), 1.0);
}

That one file is the whole artifact: drop it on the CDN to load by slug, or bundle it through any framework's shader(). The header is valid GLSL (a comment), so the frag still compiles untouched.

Only name, slug, and params are required, and a param only needs uniform + default. A scratch frag can skip the header entirely — declare a default in a trailing comment and parseShader derives the param:

uniform float u_speed;   // (default 1.0)

Library API (browser-safe)

import { parseShader, splitProps, shader, deriveParams, THEME_NAMES, POST_PRESETS }
  from '@shader-gallery/components';

// split a single-file frag into the runtime's { frag, meta }
const { frag, meta } = parseShader(src);

// map friendly component props -> runtime opts (waveSpeed -> u_waveSpeed)
const { palette, post, uniforms } = splitProps(meta, { speed: 1.6, palette: 'opal' });

// vanilla factory: shader(src).mount(target, props) -> runtime handle
const pulse = shader(src);
const handle = pulse.mount('#bg', { speed: 1.6 });
handle.setPalette('ember');
handle.destroy();

parseShader accepts both tiers: a frag with a header (catalog grade), or a headerless scratch frag whose float params are derived from uniform float u_x; // (default N) comments.

CLIs

The author → ship pipeline:

sg-import <corpus-dir> [--out f] [--stdout]   # corpus frag+meta.json -> one effects/<slug>.frag
sg-validate <file.frag> [...]                 # schema + param-coverage check
sg-typegen <file.frag> [--out f] [--stdout]   # per-effect .d.ts of props (opt-in autocomplete)

# validate before shipping, then emit prop types for the bundled-frag path
npx sg-validate pulse.frag
npx sg-typegen pulse.frag --out pulse.d.ts

sg-import embeds the sidecar meta.json as the header and expands the prelude (//@sg-include prelude) inline, so the shipped frag is self-contained. sg-validate checks both directions: no param without a uniform in the GLSL, no tweakable uniform left undeclared.

Layout

| path | what | | --- | --- | | parse.js | parseShader — header split + scratch fallback | | derive.js | scratch-tier param derivation from // (default N) | | props.js | propName/uniformName/splitProps (prop <-> uniform seam) | | mount.js | shader() vanilla factory over the runtime | | expand.js | authoring-time prelude expansion (Node-only) | | schema.json | the /*@shader*/ header schema (draft-07) | | prelude.glsl | the ~15-fn shared GLSL stdlib | | CONTRACT.md | the authoring spec | | effects/ | imported single-file effects (reference: billow.frag) | | bin/ | the three CLIs |

Test

npm test   # node --test over the browser-safe core (zero deps)

MIT © E. T. Carter · shader.gallery · [email protected]