@instantshader/react 0.5.0 → 0.6.1

package/README.md

@@ -4,8 +4,9 @@
 
 React bindings for [instantshader](https://www.npmjs.com/package/instantshader), a
 zero-dependency animated WebGL gradient engine. Drop a `<Flow>`, `<Beam>`, `<Bloom>`, `<Halo>`, `<Strata>`, `<Dune>` or
-`<Whorl>` component into any sized wrapper to mount a live, animated gradient. Built by
-[InstantGradient](https://instantgradient.com/app).
+`<Whorl>` component into any sized wrapper to mount a live, animated gradient, and
+add dither, pixelate, halftone or ASCII effects over it or over your own image.
+Built by [InstantGradient](https://instantgradient.com/app).
 
 ## Install
 
@@ -56,7 +57,43 @@ import { Bloom } from "@instantshader/react";
 
 See the [`instantshader` README](https://www.npmjs.com/package/instantshader)
 for what each param does and for the shader defs themselves (re-exported from
-here as `flow`, `beam` and `bloom`).
+here as `flow`, `beam`, `bloom`, `halo`, `strata`, `dune` and `whorl`).
+
+## Effects
+
+Every shader component takes an `effects` prop: a list of layers, bottom
+first, each an effect def with its params.
+
+```tsx
+import { Bloom, dither } from "@instantshader/react";
+
+<Bloom
+  colors={["#140f30", "#9c2168", "#eb6a4e", "#fcd87c"]}
+  effects={[{ effect: dither, params: { pattern: "blueNoise", colorMode: "palette", levels: 4 } }]}
+  style={{ width: "100%", height: "100%" }}
+/>;
+```
+
+`<ShaderStack>` takes a `source` instead of a fixed shader, which is how you
+put effects over an image. Any `<img>`, `<canvas>` or `<video>` element works
+as `media`:
+
+```tsx
+import { ShaderStack, halftone } from "@instantshader/react";
+
+<ShaderStack
+  source={{ kind: "media", media: img, fit: "cover" }}
+  colors={["#111111", "#f4f1ea"]}
+  effects={[{ effect: halftone, params: { size: 20, angle: 30 } }]}
+  style={{ width: "100%", height: "100%" }}
+/>;
+```
+
+Changing `effects` or their params updates the canvas in place. A new
+`source`, `seed`, `background` or `fontFamily` remounts it. The four effect
+defs (`pixelate`, `dither`, `halftone`, `ascii`) are re-exported from here,
+and the [repository README](https://github.com/ugolbck/instantshader#effects)
+lists every param with its range.
 
 ## Seamless loops
 
@@ -67,7 +104,7 @@ at the wrap:
 <Flow colors={colors} loopSeconds={30} style={{ width: "100%", height: "100%" }} />
 ```
 
-15–60s is the comfortable range, and the period is measured in animation
-seconds (so it interacts with `speed`). See the
+15 to 60s is the comfortable range, and the period is measured in animation
+seconds, so it interacts with `speed`. See the
 [`instantshader` README](https://www.npmjs.com/package/instantshader) for the
 full details.

package/dist/index.d.ts

@@ -1,53 +1,79 @@
 import { CSSProperties, ReactElement } from "react";
-import { ParamDef, ShaderDef, ShaderDef as ShaderDef$1, beam, bloom, dune, flow, halo, strata, whorl } from "instantshader";
+import { EffectDef, EffectLayer, EffectLayer as EffectLayer$1, EffectParamDef, ParamDef, ParamValue, ShaderDef, ShaderDef as ShaderDef$1, Source, Source as Source$1, ascii, beam, bloom, dither, dune, flow, halftone, halo, pixelate, strata, whorl } from "instantshader";
 
-//#region src/ShaderCanvas.d.ts
-interface ShaderCanvasProps {
-  shader: ShaderDef$1;
+//#region src/ShaderStack.d.ts
+interface ShaderStackProps {
+  source: Source$1;
+  /** Effect layers, bottom to top. A new array with the same content does
+  * not recompile anything. */
+  effects?: EffectLayer$1[];
+  /** Palette. Generators draw with it; effects in "palette" color mode map
+  * tone through it. */
   colors: string[];
   /**
-  * Merged into the shader's current params (removed/omitted keys are NOT
-  * reset to their default — they keep whatever value was last applied).
-  * Setting this prop back to `undefined` does not revert to defaults
-  * either: the underlying MountHandle is only updated when `params` is
-  * truthy, so the last applied values simply stick.
-  */
-  params?: Record<string, number>;
-  /**
   * Setting this prop back to `undefined` does NOT revert playback to the
-  * default speed — the underlying MountHandle is only updated when `speed`
-  * is not `undefined`, so whatever speed was last applied keeps playing.
+  * default speed — the underlying handle is only updated when `speed` is
+  * not `undefined`, so whatever speed was last applied keeps playing.
   */
   speed?: number;
   seed?: number;
-  /**
-  * Makes the animation repeat seamlessly every `loopSeconds` animation
-  * seconds. Unlike `params` and `speed`, setting this back to `undefined`
-  * DOES take effect — it turns looping off — because "no loop" is a real
-  * state the underlying handle can be put into.
-  */
+  /** Makes the animation repeat seamlessly every `loopSeconds` animation
+  * seconds. Setting it back to `undefined` turns looping off. */
   loopSeconds?: number;
   paused?: boolean;
+  /** Shown behind contain-fit media and under media alpha. Mount-time only. */
+  background?: string;
+  /** CSS font-family for effects that draw text (ASCII). Load it first with
+  * `document.fonts.load`. Mount-time only. */
+  fontFamily?: string;
   className?: string;
   style?: CSSProperties;
 }
 /**
-* Mounts a live InstantShader gradient into a wrapper `<div>`. The canvas
-* fills that div at 100%/100% (mountGradient styles it that way), so the
-* consumer MUST give the wrapper an explicit size (via `style`, `className`,
-* or a sized parent) — this component does not impose one beyond
-* `position: relative`.
+* Mounts a live stack into a wrapper `<div>`. The canvas fills that div at
+* 100%/100%, so the consumer MUST give the wrapper an explicit size (via
+* `style`, `className`, or a sized parent) — this component does not impose
+* one beyond `position: relative`.
 */
-declare function ShaderCanvas({
-  shader,
+declare function ShaderStack({
+  source,
+  effects,
   colors,
-  params,
   speed,
   seed,
   loopSeconds,
   paused,
+  background,
+  fontFamily,
   className,
   style
+}: ShaderStackProps): ReactElement;
+//#endregion
+//#region src/ShaderCanvas.d.ts
+interface ShaderCanvasProps extends Omit<ShaderStackProps, "source" | "effects" | "background"> {
+  shader: ShaderDef$1;
+  /**
+  * Merged into the shader's current params (removed/omitted keys are NOT
+  * reset to their default — they keep whatever value was last applied).
+  * Setting this prop back to `undefined` does not revert to defaults
+  * either: the underlying handle is only updated when `params` is truthy,
+  * so the last applied values simply stick.
+  */
+  params?: Record<string, number>;
+  /** Effect layers drawn over the gradient, bottom to top:
+  * `[{ effect: dither, params: { size: 4, colorMode: "palette" } }]`. */
+  effects?: EffectLayer$1[];
+}
+/**
+* Mounts a live InstantShader gradient, optionally with effects over it. See
+* ShaderStack for sizing: the consumer MUST give the wrapper an explicit size.
+* Remounts only when `shader` or `seed` changes.
+*/
+declare function ShaderCanvas({
+  shader,
+  params,
+  effects,
+  ...rest
 }: ShaderCanvasProps): ReactElement;
 //#endregion
 //#region src/shaders.d.ts
@@ -59,4 +85,4 @@ declare function Strata(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
 declare function Dune(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
 declare function Whorl(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
 //#endregion
-export { Beam, Bloom, Dune, Flow, Halo, type ParamDef, ShaderCanvas, type ShaderCanvasProps, type ShaderDef, Strata, Whorl, beam, bloom, dune, flow, halo, strata, whorl };
+export { Beam, Bloom, Dune, type EffectDef, type EffectLayer, type EffectParamDef, Flow, Halo, type ParamDef, type ParamValue, ShaderCanvas, type ShaderCanvasProps, type ShaderDef, ShaderStack, type ShaderStackProps, type Source, Strata, Whorl, ascii, beam, bloom, dither, dune, flow, halftone, halo, pixelate, strata, whorl };

package/dist/index.js

@@ -1,30 +1,38 @@
 "use client";
 import { useEffect, useMemo, useRef } from "react";
-import { beam, beam as beam$1, bloom, bloom as bloom$1, dune, dune as dune$1, flow, flow as flow$1, halo, halo as halo$1, mountGradient, strata, strata as strata$1, whorl, whorl as whorl$1 } from "instantshader";
+import { ascii, beam, beam as beam$1, bloom, bloom as bloom$1, dither, dune, dune as dune$1, flow, flow as flow$1, halftone, halo, halo as halo$1, mountStack, pixelate, strata, strata as strata$1, whorl, whorl as whorl$1 } from "instantshader";
 import { jsx } from "react/jsx-runtime";
 
-//#region src/ShaderCanvas.tsx
+//#region src/ShaderStack.tsx
+function sortedSig(o) {
+	if (!o) return "";
+	return Object.keys(o).sort().map((k) => `${k}:${String(o[k])}`).join(",");
+}
 /**
-* Mounts a live InstantShader gradient into a wrapper `<div>`. The canvas
-* fills that div at 100%/100% (mountGradient styles it that way), so the
-* consumer MUST give the wrapper an explicit size (via `style`, `className`,
-* or a sized parent) — this component does not impose one beyond
-* `position: relative`.
+* Mounts a live stack into a wrapper `<div>`. The canvas fills that div at
+* 100%/100%, so the consumer MUST give the wrapper an explicit size (via
+* `style`, `className`, or a sized parent) — this component does not impose
+* one beyond `position: relative`.
 */
-function ShaderCanvas({ shader, colors, params, speed, seed, loopSeconds, paused, className, style }) {
+function ShaderStack({ source, effects, colors, speed, seed, loopSeconds, paused, background, fontFamily, className, style }) {
 	const containerRef = useRef(null);
 	const handleRef = useRef(null);
-	const p = useMemo(() => params, [params ? Object.entries(params).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${k}:${v}`).join(",") : ""]);
+	const sourceIdentity = source.kind === "generator" ? source.shader : source.media;
+	const fit = source.kind === "media" ? source.fit : void 0;
+	const sourceParams = useMemo(() => source.kind === "generator" ? source.params : void 0, [source.kind === "generator" ? sortedSig(source.params) : ""]);
+	const layers = useMemo(() => effects ?? [], [(effects ?? []).map((l) => `${l.effect.id}|${l.enabled ?? true}|${sortedSig(l.params)}`).join(";")]);
 	useEffect(() => {
 		const container = containerRef.current;
 		if (!container) return;
-		const handle = mountGradient(container, {
-			shader,
+		const handle = mountStack(container, {
+			source,
+			effects: layers,
 			colors,
-			params: p,
 			speed,
 			seed,
-			loopSeconds
+			loopSeconds,
+			background,
+			fontFamily
 		});
 		handleRef.current = handle;
 		if (paused) handle.pause();
@@ -32,13 +40,22 @@ function ShaderCanvas({ shader, colors, params, speed, seed, loopSeconds, paused
 			handle.dispose();
 			handleRef.current = null;
 		};
-	}, [shader, seed]);
+	}, [
+		sourceIdentity,
+		fit,
+		seed,
+		background,
+		fontFamily
+	]);
 	useEffect(() => {
 		handleRef.current?.setColors(colors);
 	}, [colors]);
 	useEffect(() => {
-		if (p) handleRef.current?.setParams(p);
-	}, [p]);
+		if (sourceParams) handleRef.current?.setSourceParams(sourceParams);
+	}, [sourceParams]);
+	useEffect(() => {
+		handleRef.current?.setEffects(layers);
+	}, [layers]);
 	useEffect(() => {
 		if (speed !== void 0) handleRef.current?.setSpeed(speed);
 	}, [speed]);
@@ -59,6 +76,25 @@ function ShaderCanvas({ shader, colors, params, speed, seed, loopSeconds, paused
 	});
 }
 
+//#endregion
+//#region src/ShaderCanvas.tsx
+/**
+* Mounts a live InstantShader gradient, optionally with effects over it. See
+* ShaderStack for sizing: the consumer MUST give the wrapper an explicit size.
+* Remounts only when `shader` or `seed` changes.
+*/
+function ShaderCanvas({ shader, params, effects,...rest }) {
+	return /* @__PURE__ */ jsx(ShaderStack, {
+		source: {
+			kind: "generator",
+			shader,
+			params
+		},
+		effects,
+		...rest
+	});
+}
+
 //#endregion
 //#region src/shaders.tsx
 function Flow(props) {
@@ -105,4 +141,4 @@ function Whorl(props) {
 }
 
 //#endregion
-export { Beam, Bloom, Dune, Flow, Halo, ShaderCanvas, Strata, Whorl, beam, bloom, dune, flow, halo, strata, whorl };
+export { Beam, Bloom, Dune, Flow, Halo, ShaderCanvas, ShaderStack, Strata, Whorl, ascii, beam, bloom, dither, dune, flow, halftone, halo, pixelate, strata, whorl };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@instantshader/react",
-  "version": "0.5.0",
-  "description": "React bindings for InstantShader animated WebGL gradients.",
+  "version": "0.6.1",
+  "description": "React components for InstantShader: animated WebGL gradients and image effects.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "react"
   ],
   "dependencies": {
-    "instantshader": "0.5.0"
+    "instantshader": "0.6.1"
   },
   "peerDependencies": {
     "react": "^18 || ^19",