@instantshader/react 0.4.1 → 0.6.0

package/README.md

@@ -1,8 +1,10 @@
+![InstantShader](https://raw.githubusercontent.com/ugolbck/instantshader/main/.github/assets/banner.jpg)
+
 # @instantshader/react
 
 React bindings for [instantshader](https://www.npmjs.com/package/instantshader), a
-zero-dependency animated WebGL gradient engine. Drop a `<Flow>`, `<Beam>` or
-`<Bloom>` component into any sized wrapper to mount a live, animated gradient. Built by
+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).
 
 ## Install
@@ -35,6 +37,10 @@ One component per shader, each a thin wrapper over the same props:
 | `<Flow>` | Isotropic swirling currents with defined luminous edges and calm negative space. | `scale`, `curl`, `drift`, `openness`, `grain` |
 | `<Beam>` | One wide beam of soft light crossing a near-black frame, the palette walking its length. | `scale`, `width`, `glow`, `angle`, `grain` |
 | `<Bloom>` | A fan of huge soft petals radiating from the bottom edge, palette as concentric scalloped bands. | `scale`, `petals`, `pinch`, `bend`, `sway`, `colorflow`, `grain` |
+| `<Halo>` | An eclipse disc with a bright limb and flowing corona; `x` / `y` place it, and the default is a glowing horizon arc. | `radius`, `x`, `y`, `glow`, `crescent`, `flares`, `grain` |
+| `<Strata>` | Stacked cut-paper layers with soft shadows. | `scale`, `layers`, `warp`, `ridges`, `stretch`, `depth`, `blend`, `angle`, `grain` |
+| `<Dune>` | Overlapping crests, crisp on top and airbrushed below. | `layers`, `swell`, `waves`, `fade`, `soft`, `angle`, `grain` |
+| `<Whorl>` | A spiral of curved blades, positionable with `x` / `y`. | `blades`, `twist`, `depth`, `scale`, `wobble`, `x`, `y`, `grain` |
 
 ```tsx
 import { Bloom } from "@instantshader/react";

package/dist/index.d.ts

@@ -1,58 +1,88 @@
 import { CSSProperties, ReactElement } from "react";
-import { ParamDef, ShaderDef, ShaderDef as ShaderDef$1, beam, bloom, flow } 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
 declare function Flow(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
 declare function Beam(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
 declare function Bloom(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
+declare function Halo(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
+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, Flow, type ParamDef, ShaderCanvas, type ShaderCanvasProps, type ShaderDef, beam, bloom, flow };
+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, flow, flow as flow$1, mountGradient } 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) {
@@ -79,6 +115,30 @@ function Bloom(props) {
 		...props
 	});
 }
+function Halo(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: halo$1,
+		...props
+	});
+}
+function Strata(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: strata$1,
+		...props
+	});
+}
+function Dune(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: dune$1,
+		...props
+	});
+}
+function Whorl(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: whorl$1,
+		...props
+	});
+}
 
 //#endregion
-export { Beam, Bloom, Flow, ShaderCanvas, beam, bloom, flow };
+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,6 +1,6 @@
 {
   "name": "@instantshader/react",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "React bindings for InstantShader animated WebGL gradients.",
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "react"
   ],
   "dependencies": {
-    "instantshader": "0.4.1"
+    "instantshader": "0.6.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",