fancy-ui-react 0.2.0 → 0.2.1

package/README.md

@@ -139,8 +139,14 @@ pnpm install                              # at the repo root
 pnpm --filter fancy-ui-react test         # vitest + testing-library
 pnpm --filter fancy-ui-react check        # tsc --noEmit
 pnpm --filter fancy-ui-react build        # vite lib build + d.ts via tsc, then the dist gates
+pnpm --filter fancy-ui-react-demo dev     # the demo site (examples/react-demo) on http://localhost:3200
 ```
 
+Two consumer apps live under `examples/`: `next-app`, the App Router census
+that CI builds as the SSR/hydration gate, and `react-demo`, a one-page demo
+site built as a static export (`next build` → `examples/react-demo/out/`).
+Both resolve `fancy-ui-react` to `react/dist`, so run `build` first.
+
 `build` does more than build. After Vite and `tsc` it runs four scripts in
 `react/scripts/`, each guarding something no other gate can see:
 

package/dist/components/fluid-cursor/FluidCursor.js

@@ -3,7 +3,7 @@ import { jsx } from "react/jsx-runtime";
 import { useState, useRef, useEffect } from "react";
 import { useLiveRef } from "../../internals/dom/use-live-ref.js";
 import { cn } from "../../utils.js";
-import { hexToRgb, DEV, wrap, pointerPrototype, scaleRadiusForContainer, HSVtoRGB } from "./fluid-shared.js";
+import { hexToRgb, clickBoost, DEV, wrap, pointerPrototype, scaleRadiusForContainer, HSVtoRGB } from "./fluid-shared.js";
 import { startWebGpuFluid } from "./webgpu-engine.js";
 function FluidCursor({
   simResolution = 128,
@@ -38,13 +38,19 @@ function FluidCursor({
   ditherLevels = 4,
   onReady
 }) {
-  const [derived] = useState(() => ({
-    clampedColorIntensity: Math.max(0, Math.min(1, colorIntensity)),
-    clampedHdrBoost: Math.max(1, Math.min(4, hdrBoost)),
-    clampedDitherPixelSize: Math.max(1, ditherPixelSize),
-    clampedDitherLevels: Math.max(2, Math.min(16, Math.floor(ditherLevels))),
-    resolvedBackColor: typeof backColor === "string" ? hexToRgb(backColor) : backColor
-  }));
+  const [derived] = useState(() => {
+    const clampedColorIntensity = Math.max(0, Math.min(1, colorIntensity));
+    return {
+      clampedColorIntensity,
+      // A click's extra brightness, capped so it never compounds
+      // colorIntensity into the dither pass's clamp — see clickBoost().
+      clickColorBoost: clickBoost(clampedColorIntensity),
+      clampedHdrBoost: Math.max(1, Math.min(4, hdrBoost)),
+      clampedDitherPixelSize: Math.max(1, ditherPixelSize),
+      clampedDitherLevels: Math.max(2, Math.min(16, Math.floor(ditherLevels))),
+      resolvedBackColor: typeof backColor === "string" ? hexToRgb(backColor) : backColor
+    };
+  });
   const canvasRef = useRef(null);
   const activeInstanceRef = useRef(null);
   const mountCounterRef = useRef(0);
@@ -61,11 +67,11 @@ function FluidCursor({
   const onReadyRef = useLiveRef(onReady);
   function getScaledColor(hex) {
     const { r, g, b } = hexToRgb(hex);
-    return {
+    return Object.freeze({
       r: r * derived.clampedColorIntensity,
       g: g * derived.clampedColorIntensity,
       b: b * derived.clampedColorIntensity
-    };
+    });
   }
   function getCachedFluidColor(hex) {
     const cache = colorCacheRef.current;
@@ -186,7 +192,8 @@ function FluidCursor({
         autoSplatInterval,
         pauseWhenHidden,
         splatOnMount,
-        generateColor
+        generateColor,
+        clickBoost: derived.clickColorBoost
       }).then((handle) => {
         if (disposed) {
           handle?.cleanup();
@@ -581,13 +588,19 @@ function FluidCursor({
 			uniform vec3 color;
 			uniform vec2 point;
 			uniform float radius;
+			uniform float saturate;
 
 			void main () {
 				vec2 p = vUv - point.xy;
 				p.x *= aspectRatio;
 				vec3 splat = exp(-dot(p, p) / radius) * color;
 				vec3 base = texture2D(uTarget, vUv).xyz;
-				gl_FragColor = vec4(base + splat, 1.0);
+				// A click splat lifts each texel to its own profile instead of adding
+				// to it: what is already there never rises past what one click would
+				// leave at that spot, so a burst of clicks paints the same disc once
+				// instead of summing towards white and widening with every click.
+				vec3 sum = saturate > 0.5 ? max(base, splat) : base + splat;
+				gl_FragColor = vec4(sum, 1.0);
 			}
 		`
       );
@@ -1211,15 +1224,17 @@ function FluidCursor({
         splat(pointer.texcoordX, pointer.texcoordY, dx, dy, pointer.color);
       }
       function clickSplat(pointer) {
-        const color = generateColor();
-        color.r *= 10;
-        color.g *= 10;
-        color.b *= 10;
+        const base = generateColor();
+        const color = {
+          r: base.r * derived.clickColorBoost,
+          g: base.g * derived.clickColorBoost,
+          b: base.b * derived.clickColorBoost
+        };
         const dx = 10 * (Math.random() - 0.5);
         const dy = 30 * (Math.random() - 0.5);
-        splat(pointer.texcoordX, pointer.texcoordY, dx, dy, color);
+        splat(pointer.texcoordX, pointer.texcoordY, dx, dy, color, true);
       }
-      function splat(x, y, dx, dy, color) {
+      function splat(x, y, dx, dy, color, saturate = false) {
         splatProgram.bind();
         if (splatProgram.uniforms.uTarget) {
           gl.uniform1i(splatProgram.uniforms.uTarget, velocity.read.attach(0));
@@ -1233,6 +1248,9 @@ function FluidCursor({
         if (splatProgram.uniforms.color) {
           gl.uniform3f(splatProgram.uniforms.color, dx, dy, 0);
         }
+        if (splatProgram.uniforms.saturate) {
+          gl.uniform1f(splatProgram.uniforms.saturate, 0);
+        }
         if (splatProgram.uniforms.radius) {
           let radius = correctRadius(config.SPLAT_RADIUS / 100);
           if (containedRef.current) {
@@ -1248,6 +1266,9 @@ function FluidCursor({
         if (splatProgram.uniforms.color) {
           gl.uniform3f(splatProgram.uniforms.color, color.r, color.g, color.b);
         }
+        if (splatProgram.uniforms.saturate) {
+          gl.uniform1f(splatProgram.uniforms.saturate, saturate ? 1 : 0);
+        }
         blit(dye.write);
         dye.swap();
       }
@@ -1347,6 +1368,9 @@ function FluidCursor({
         updatePointerDownData(pointer, -1, posX, posY);
         clickSplat(pointer);
       }
+      function handlePointerUp() {
+        pointers[0].down = false;
+      }
       function handleFirstMouseMove(e) {
         const pointer = pointers[0];
         const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
@@ -1389,11 +1413,14 @@ function FluidCursor({
       }
       if (interactive) {
         window.addEventListener("mousedown", handleMouseDown);
+        window.addEventListener("mouseup", handlePointerUp);
         document.body.addEventListener("mousemove", handleFirstMouseMove);
         window.addEventListener("mousemove", handleMouseMove);
         document.body.addEventListener("touchstart", handleFirstTouchStart);
         window.addEventListener("touchstart", handleTouchStart, false);
         window.addEventListener("touchmove", handleTouchMove, false);
+        window.addEventListener("touchend", handlePointerUp);
+        window.addEventListener("touchcancel", handlePointerUp);
       }
       let observer = null;
       if (pauseWhenHidden) {
@@ -1432,11 +1459,14 @@ function FluidCursor({
         if (autoSplatTimer) clearInterval(autoSplatTimer);
         if (interactive) {
           window.removeEventListener("mousedown", handleMouseDown);
+          window.removeEventListener("mouseup", handlePointerUp);
           document.body.removeEventListener("mousemove", handleFirstMouseMove);
           window.removeEventListener("mousemove", handleMouseMove);
           document.body.removeEventListener("touchstart", handleFirstTouchStart);
           window.removeEventListener("touchstart", handleTouchStart);
           window.removeEventListener("touchmove", handleTouchMove);
+          window.removeEventListener("touchend", handlePointerUp);
+          window.removeEventListener("touchcancel", handlePointerUp);
         }
         if (contained) {
           window.removeEventListener("resize", updateCanvasRectCache);

package/dist/components/fluid-cursor/fluid-shared.d.ts

@@ -36,6 +36,24 @@ export declare function correctRadius(radius: number, width: number, height: num
  * length under ~30% of the container height.
  */
 export declare function scaleRadiusForContainer(radius: number, containerHeight: number, viewportHeight: number): number;
+/**
+ * Dye a click deposits at its centre, in multiples of the hue: the engine's
+ * default `colorIntensity` (0.15) times the ×10 boost the solver has always
+ * given a click — the amount that reads as a bright pop on every renderer.
+ */
+export declare const CLICK_PEAK = 1.5;
+/**
+ * The boost a click applies to an already intensity-scaled colour, chosen so
+ * the peak lands on CLICK_PEAK whatever `colorIntensity` is.
+ *
+ * The historical fixed ×10 compounded `colorIntensity`. At the default 0.15
+ * that is a 1.5 peak; but the dither pass asks consumers to raise the
+ * intensity to ≈0.4+, and at 0.6 the same ×10 stacked 5.4 per click into an
+ * unclamped half-float dye buffer that the dither display then clamps to 1
+ * and quantises — every click grew a flat, saturated disc that never read as
+ * a splat. Capping the boost at 10 keeps intensities ≤ 0.15 byte-identical.
+ */
+export declare function clickBoost(colorIntensity: number): number;
 export declare function correctDeltaX(delta: number, width: number, height: number): number;
 export declare function correctDeltaY(delta: number, width: number, height: number): number;
 /**

package/dist/components/fluid-cursor/fluid-shared.js

@@ -95,6 +95,11 @@ function scaleRadiusForContainer(radius, containerHeight, viewportHeight) {
   if (k <= 1) return radius;
   return Math.max(radius, Math.min(radius * k, 0.09));
 }
+const CLICK_PEAK = 1.5;
+function clickBoost(colorIntensity) {
+  if (!(colorIntensity > 0)) return 0;
+  return Math.min(10, CLICK_PEAK / colorIntensity);
+}
 function correctDeltaX(delta, width, height) {
   const aspectRatio = width / height;
   if (aspectRatio < 1) return delta * aspectRatio;
@@ -107,8 +112,10 @@ function correctDeltaY(delta, width, height) {
 }
 const DEV = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
 export {
+  CLICK_PEAK,
   DEV,
   HSVtoRGB,
+  clickBoost,
   correctDeltaX,
   correctDeltaY,
   correctRadius,

package/dist/components/fluid-cursor/webgpu-engine.d.ts

@@ -20,6 +20,12 @@ export interface WebGpuFluidOptions {
     pauseWhenHidden: boolean;
     splatOnMount: boolean;
     generateColor: () => ColorRGB;
+    /**
+     * Multiplier a click applies to the (already intensity-scaled) colour
+     * `generateColor()` returns — `clickBoost(colorIntensity)` from
+     * fluid-shared, so the peak is the same whatever the intensity.
+     */
+    clickBoost: number;
 }
 /**
  * Full WebGPU setup for FluidCursor: engine + pointer wiring + rAF loop +

package/dist/components/fluid-cursor/webgpu-engine.js

@@ -52,7 +52,11 @@ fn fs_splat(in: VSOut) -> @location(0) vec4f {
 	p.x = p.x * u.aspect;
 	let splat = exp(-dot(p, p) / u.radius) * u.color.rgb;
 	let base = textureSample(tex0, smpLinear, in.uv).rgb;
-	return vec4f(base + splat, 1.0);
+	// color.a is the click flag: a click splat lifts each texel to its own
+	// profile instead of adding to it, so a burst of clicks paints the same
+	// disc once instead of summing towards white and widening every click.
+	let sum = select(base + splat, max(base, splat), u.color.a > 0.5);
+	return vec4f(sum, 1.0);
 }
 
 @fragment
@@ -233,7 +237,7 @@ async function createWebGpuFluid(canvas, opts) {
         scratch[OFF_COLOR] = v.color[0];
         scratch[OFF_COLOR + 1] = v.color[1];
         scratch[OFF_COLOR + 2] = v.color[2];
-        scratch[OFF_COLOR + 3] = 1;
+        scratch[OFF_COLOR + 3] = v.color[3] ?? 0;
       }
       scratch[OFF_DT] = v.dt ?? 0;
       scratch[OFF_DISSIPATION] = v.dissipation ?? 0;
@@ -368,7 +372,7 @@ async function createWebGpuFluid(canvas, opts) {
         canvas.height = height;
         initTextures();
       }
-    }, splat = function(x, y, dx, dy, color) {
+    }, splat = function(x, y, dx, dy, color, saturate = false) {
       if (destroyed || lost || !velocity || !dye) return;
       let radius = correctRadius(opts.splatRadius / 100, canvas.width, canvas.height);
       if (opts.contained) {
@@ -383,7 +387,7 @@ async function createWebGpuFluid(canvas, opts) {
       });
       writeUniforms(uSplatDye, {
         point: [x, y],
-        color: [color.r, color.g, color.b],
+        color: [color.r, color.g, color.b, saturate ? 1 : 0],
         aspect,
         radius
       });
@@ -716,13 +720,15 @@ async function startWebGpuFluid(canvas, opts) {
     engine.splat(pointer.texcoordX, pointer.texcoordY, dx, dy, pointer.color);
   }
   function clickSplat(pointer) {
-    const color = opts.generateColor();
-    color.r *= 10;
-    color.g *= 10;
-    color.b *= 10;
+    const base = opts.generateColor();
+    const color = {
+      r: base.r * opts.clickBoost,
+      g: base.g * opts.clickBoost,
+      b: base.b * opts.clickBoost
+    };
     const dx = 10 * (Math.random() - 0.5);
     const dy = 30 * (Math.random() - 0.5);
-    engine.splat(pointer.texcoordX, pointer.texcoordY, dx, dy, color);
+    engine.splat(pointer.texcoordX, pointer.texcoordY, dx, dy, color, true);
   }
   function multipleSplats(steps) {
     const angle = Math.random() * Math.PI * 2;
@@ -780,6 +786,9 @@ async function startWebGpuFluid(canvas, opts) {
     updatePointerDownData(pointer, -1, posX, posY);
     clickSplat(pointer);
   }
+  function handlePointerUp() {
+    pointers[0].down = false;
+  }
   function handleFirstMouseMove(e) {
     const pointer = pointers[0];
     const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
@@ -826,11 +835,14 @@ async function startWebGpuFluid(canvas, opts) {
   }
   if (opts.interactive) {
     window.addEventListener("mousedown", handleMouseDown);
+    window.addEventListener("mouseup", handlePointerUp);
     document.body.addEventListener("mousemove", handleFirstMouseMove);
     window.addEventListener("mousemove", handleMouseMove);
     document.body.addEventListener("touchstart", handleFirstTouchStart);
     window.addEventListener("touchstart", handleTouchStart, false);
     window.addEventListener("touchmove", handleTouchMove, false);
+    window.addEventListener("touchend", handlePointerUp);
+    window.addEventListener("touchcancel", handlePointerUp);
   }
   let observer = null;
   if (opts.pauseWhenHidden) {
@@ -903,11 +915,14 @@ async function startWebGpuFluid(canvas, opts) {
       if (autoSplatTimer) clearInterval(autoSplatTimer);
       if (opts.interactive) {
         window.removeEventListener("mousedown", handleMouseDown);
+        window.removeEventListener("mouseup", handlePointerUp);
         document.body.removeEventListener("mousemove", handleFirstMouseMove);
         window.removeEventListener("mousemove", handleMouseMove);
         document.body.removeEventListener("touchstart", handleFirstTouchStart);
         window.removeEventListener("touchstart", handleTouchStart);
         window.removeEventListener("touchmove", handleTouchMove);
+        window.removeEventListener("touchend", handlePointerUp);
+        window.removeEventListener("touchcancel", handlePointerUp);
       }
       if (opts.contained) {
         window.removeEventListener("resize", updateCanvasRectCache);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fancy-ui-react",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Animated UI components for React — the React counterpart of fancy-ui-svelte. WebGL, GSAP and CSS motion, styled with Tailwind CSS v4.",
   "license": "MIT",
   "type": "module",