@flikk/ui 1.0.0-beta.29 → 1.0.0-beta.30

package/dist/components/effects/{AIOrb/variants/Aura → shared/ShaderCanvas}/ShaderCanvas.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useRef, useEffect } from 'react';
 
@@ -10,11 +11,13 @@ void main() {
  * Minimal raw WebGL2 canvas renderer for fullscreen fragment shaders.
  * - Built-in uniforms: iTime (float), iResolution (vec2)
  * - Custom uniforms read from `uniformsRef` each frame (no stale closures)
+ * - Optional sampler2D uniforms read from `texturesRef` (image loading,
+ *   texture upload, mipmaps, transparent-pixel placeholder while unset/loading)
  * - ResizeObserver for responsive canvas sizing
- * - rAF animation loop with cleanup on unmount
+ * - rAF animation loop, paused while the tab is hidden, with cleanup on unmount
  * - Graceful degradation: renders nothing if WebGL2 unavailable
  */
-const ShaderCanvas = ({ fragmentShader, uniformsRef, maxDpr = 2, className, style, }) => {
+const ShaderCanvas = ({ fragmentShader, uniformsRef, texturesRef, onTextureLoad, maxDpr = 2, className, style, }) => {
     const canvasRef = useRef(null);
     useEffect(() => {
         const canvas = canvasRef.current;
@@ -80,6 +83,81 @@ const ShaderCanvas = ({ fragmentShader, uniformsRef, maxDpr = 2, className, styl
             }
             return (_a = customLocs.get(name)) !== null && _a !== void 0 ? _a : null;
         };
+        // ── Texture uniforms ───────────────────────────────────────────────
+        const textureEntries = new Map();
+        let nextTextureUnit = 0;
+        // Operates on whatever texture is currently bound to TEXTURE_2D — every
+        // call site binds the target texture immediately before calling this.
+        const configureTexture = () => {
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        };
+        const createPlaceholderTexture = () => {
+            const texture = gl.createTexture();
+            gl.bindTexture(gl.TEXTURE_2D, texture);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([0, 0, 0, 0]));
+            configureTexture();
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+            return texture;
+        };
+        const uploadImage = (entry, img, name) => {
+            if (hasBeenDisposed)
+                return;
+            gl.bindTexture(gl.TEXTURE_2D, entry.texture);
+            gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+            gl.generateMipmap(gl.TEXTURE_2D);
+            configureTexture();
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+            gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+            const naturalWidth = img.naturalWidth || img.width;
+            const naturalHeight = img.naturalHeight || img.height;
+            if (naturalWidth > 0 && naturalHeight > 0) {
+                onTextureLoad === null || onTextureLoad === void 0 ? void 0 : onTextureLoad(name, naturalWidth / naturalHeight);
+            }
+        };
+        const loadTexture = (entry, source, name) => {
+            if (typeof source === "string") {
+                const img = new Image();
+                img.crossOrigin = "anonymous";
+                img.onload = () => uploadImage(entry, img, name);
+                img.src = source;
+            }
+            else if (source.complete && source.naturalWidth > 0) {
+                uploadImage(entry, source, name);
+            }
+            else {
+                source.addEventListener("load", () => uploadImage(entry, source, name), {
+                    once: true,
+                });
+            }
+        };
+        const syncTextures = () => {
+            const sources = texturesRef === null || texturesRef === void 0 ? void 0 : texturesRef.current;
+            if (!sources)
+                return;
+            for (const name in sources) {
+                let entry = textureEntries.get(name);
+                if (!entry) {
+                    entry = {
+                        texture: createPlaceholderTexture(),
+                        sourceKey: undefined,
+                        unit: nextTextureUnit++,
+                    };
+                    textureEntries.set(name, entry);
+                }
+                const source = sources[name];
+                if (source && source !== entry.sourceKey) {
+                    entry.sourceKey = source;
+                    loadTexture(entry, source, name);
+                }
+                else if (!source) {
+                    entry.sourceKey = undefined;
+                }
+            }
+        };
         // ── Resize handling ────────────────────────────────────────────────
         const dpr = Math.min(window.devicePixelRatio || 1, maxDpr);
         let width = 0;
@@ -103,9 +181,11 @@ const ShaderCanvas = ({ fragmentShader, uniformsRef, maxDpr = 2, className, styl
         gl.enable(gl.BLEND);
         gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         let rafId = 0;
+        let hasBeenDisposed = false;
         const startTime = performance.now();
         const frame = () => {
             rafId = requestAnimationFrame(frame);
+            syncTextures();
             const t = (performance.now() - startTime) / 1000;
             gl.uniform1f(uTime, t);
             gl.uniform2f(uRes, width, height);
@@ -128,12 +208,38 @@ const ShaderCanvas = ({ fragmentShader, uniformsRef, maxDpr = 2, className, styl
                         gl.uniform4f(loc, val[0], val[1], val[2], val[3]);
                 }
             }
+            // Bind texture uniforms
+            for (const [name, entry] of textureEntries) {
+                const loc = getCustomLoc(name);
+                if (!loc)
+                    continue;
+                gl.activeTexture(gl.TEXTURE0 + entry.unit);
+                gl.bindTexture(gl.TEXTURE_2D, entry.texture);
+                gl.uniform1i(loc, entry.unit);
+            }
             gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
         };
-        rafId = requestAnimationFrame(frame);
+        const handleVisibilityChange = () => {
+            if (document.hidden) {
+                cancelAnimationFrame(rafId);
+                rafId = 0;
+            }
+            else if (rafId === 0) {
+                rafId = requestAnimationFrame(frame);
+            }
+        };
+        if (!document.hidden) {
+            rafId = requestAnimationFrame(frame);
+        }
+        document.addEventListener("visibilitychange", handleVisibilityChange);
         return () => {
+            hasBeenDisposed = true;
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
             cancelAnimationFrame(rafId);
             observer.disconnect();
+            for (const entry of textureEntries.values()) {
+                gl.deleteTexture(entry.texture);
+            }
             gl.deleteProgram(program);
             gl.deleteShader(vs);
             gl.deleteShader(fs);

package/dist/components/effects/shared/ShaderCanvas/ShaderCanvas.types.d.ts

@@ -0,0 +1,18 @@
+import type React from "react";
+/** A texture source: a URL to fetch, or an already-available image element. */
+export type ShaderTextureSource = string | HTMLImageElement;
+export interface ShaderCanvasProps {
+    fragmentShader: string;
+    uniformsRef: React.MutableRefObject<Record<string, number | number[]>>;
+    /**
+     * Optional sampler2D uniforms, keyed by GLSL uniform name (e.g. "u_image").
+     * A key with an `undefined` value binds a 1x1 transparent placeholder so the
+     * shader never samples garbage while an image is loading or unset.
+     */
+    texturesRef?: React.MutableRefObject<Record<string, ShaderTextureSource | undefined>>;
+    /** Fires once a texture finishes loading, with its natural aspect ratio (width / height). */
+    onTextureLoad?: (name: string, aspectRatio: number) => void;
+    maxDpr?: number;
+    className?: string;
+    style?: React.CSSProperties;
+}

package/dist/components/effects/shared/ShaderCanvas/index.d.ts

@@ -0,0 +1,2 @@
+export { ShaderCanvas } from "./ShaderCanvas";
+export type { ShaderCanvasProps, ShaderTextureSource } from "./ShaderCanvas.types";

package/dist/components/effects/shared/bayerMatrices.glsl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared ordered-dithering (Bayer matrix) GLSL, adapted from paper-design/shaders'
+ * Dithering and ImageDithering fragment shaders
+ * (https://github.com/paper-design/shaders, Apache License 2.0). Both effects
+ * in this repo (`Dithering`, `ImageDithering`) interpolate this identical
+ * lookup-table logic rather than duplicating it.
+ *
+ * Consume via template-literal interpolation (e.g. `${glslBayerMatrices}`).
+ */
+export declare const glslBayerMatrices = "\nconst int bayer2x2[4] = int[4](0, 2, 3, 1);\nconst int bayer4x4[16] = int[16](\n  0, 8, 2, 10,\n  12, 4, 14, 6,\n  3, 11, 1, 9,\n  15, 7, 13, 5\n);\nconst int bayer8x8[64] = int[64](\n  0, 32, 8, 40, 2, 34, 10, 42,\n  48, 16, 56, 24, 50, 18, 58, 26,\n  12, 44, 4, 36, 14, 46, 6, 38,\n  60, 28, 52, 20, 62, 30, 54, 22,\n  3, 35, 11, 43, 1, 33, 9, 41,\n  51, 19, 59, 27, 49, 17, 57, 25,\n  15, 47, 7, 39, 13, 45, 5, 37,\n  63, 31, 55, 23, 61, 29, 53, 21\n);\n\nfloat getBayerValue(vec2 uv, int size) {\n  ivec2 pos = ivec2(fract(uv / float(size)) * float(size));\n  int index = pos.y * size + pos.x;\n\n  if (size == 2) {\n    return float(bayer2x2[index]) / 4.0;\n  } else if (size == 4) {\n    return float(bayer4x4[index]) / 16.0;\n  } else if (size == 8) {\n    return float(bayer8x8[index]) / 64.0;\n  }\n  return 0.0;\n}\n";

package/dist/components/effects/shared/bayerMatrices.glsl.js

@@ -0,0 +1,44 @@
+/**
+ * Shared ordered-dithering (Bayer matrix) GLSL, adapted from paper-design/shaders'
+ * Dithering and ImageDithering fragment shaders
+ * (https://github.com/paper-design/shaders, Apache License 2.0). Both effects
+ * in this repo (`Dithering`, `ImageDithering`) interpolate this identical
+ * lookup-table logic rather than duplicating it.
+ *
+ * Consume via template-literal interpolation (e.g. `${glslBayerMatrices}`).
+ */
+const glslBayerMatrices = `
+const int bayer2x2[4] = int[4](0, 2, 3, 1);
+const int bayer4x4[16] = int[16](
+  0, 8, 2, 10,
+  12, 4, 14, 6,
+  3, 11, 1, 9,
+  15, 7, 13, 5
+);
+const int bayer8x8[64] = int[64](
+  0, 32, 8, 40, 2, 34, 10, 42,
+  48, 16, 56, 24, 50, 18, 58, 26,
+  12, 44, 4, 36, 14, 46, 6, 38,
+  60, 28, 52, 20, 62, 30, 54, 22,
+  3, 35, 11, 43, 1, 33, 9, 41,
+  51, 19, 59, 27, 49, 17, 57, 25,
+  15, 47, 7, 39, 13, 45, 5, 37,
+  63, 31, 55, 23, 61, 29, 53, 21
+);
+
+float getBayerValue(vec2 uv, int size) {
+  ivec2 pos = ivec2(fract(uv / float(size)) * float(size));
+  int index = pos.y * size + pos.x;
+
+  if (size == 2) {
+    return float(bayer2x2[index]) / 4.0;
+  } else if (size == 4) {
+    return float(bayer4x4[index]) / 16.0;
+  } else if (size == 8) {
+    return float(bayer8x8[index]) / 64.0;
+  }
+  return 0.0;
+}
+`;
+
+export { glslBayerMatrices };

package/dist/components/effects/shared/imageUV.glsl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared "cover fit" image-UV helper for the image-filter effects (Water,
+ * ImageDithering, PaperTexture, FlutedGlass, HalftoneDots, HalftoneCmyk).
+ * Maps the fullscreen fragment UV to the image's own UV space so the image
+ * fills its container edge-to-edge without distortion (matching CSS
+ * `object-fit: cover`), given the image's aspect ratio (natural width /
+ * natural height) as a uniform. Assumes the fragment UV is
+ * `gl_FragCoord.xy / iResolution.xy` and the texture was uploaded with
+ * `UNPACK_FLIP_Y_WEBGL = true` (see shared/ShaderCanvas), so this produces a
+ * right-side-up sample with no manual Y-flip needed at the call site.
+ */
+export declare const glslImageCoverUV = "\nvec2 getImageCoverUV(vec2 fragUV, vec2 resolution, float imageAspectRatio) {\n  float containerAspect = resolution.x / resolution.y;\n  // Container wider (relative to its height) than the image: sample a\n  // narrower vertical slice of the image (crop top/bottom) so it fills the\n  // container width with no letterboxing. Container narrower/taller than\n  // the image: sample a narrower horizontal slice (crop left/right) instead.\n  vec2 scale = containerAspect > imageAspectRatio\n    ? vec2(1.0, imageAspectRatio / containerAspect)\n    : vec2(containerAspect / imageAspectRatio, 1.0);\n  return (fragUV - 0.5) * scale + 0.5;\n}\n";

package/dist/components/effects/shared/imageUV.glsl.js

@@ -0,0 +1,26 @@
+/**
+ * Shared "cover fit" image-UV helper for the image-filter effects (Water,
+ * ImageDithering, PaperTexture, FlutedGlass, HalftoneDots, HalftoneCmyk).
+ * Maps the fullscreen fragment UV to the image's own UV space so the image
+ * fills its container edge-to-edge without distortion (matching CSS
+ * `object-fit: cover`), given the image's aspect ratio (natural width /
+ * natural height) as a uniform. Assumes the fragment UV is
+ * `gl_FragCoord.xy / iResolution.xy` and the texture was uploaded with
+ * `UNPACK_FLIP_Y_WEBGL = true` (see shared/ShaderCanvas), so this produces a
+ * right-side-up sample with no manual Y-flip needed at the call site.
+ */
+const glslImageCoverUV = `
+vec2 getImageCoverUV(vec2 fragUV, vec2 resolution, float imageAspectRatio) {
+  float containerAspect = resolution.x / resolution.y;
+  // Container wider (relative to its height) than the image: sample a
+  // narrower vertical slice of the image (crop top/bottom) so it fills the
+  // container width with no letterboxing. Container narrower/taller than
+  // the image: sample a narrower horizontal slice (crop left/right) instead.
+  vec2 scale = containerAspect > imageAspectRatio
+    ? vec2(1.0, imageAspectRatio / containerAspect)
+    : vec2(containerAspect / imageAspectRatio, 1.0);
+  return (fragUV - 0.5) * scale + 0.5;
+}
+`;
+
+export { glslImageCoverUV };

package/dist/components/effects/shared/index.d.ts

@@ -0,0 +1,7 @@
+export { ShaderCanvas } from "./ShaderCanvas";
+export type { ShaderCanvasProps, ShaderTextureSource } from "./ShaderCanvas";
+export { resolveShaderColor, resolveShaderColors } from "./resolveShaderColor";
+export type { RGBA } from "./resolveShaderColor";
+export { glslHashFloat, glslHashVec2, glslValueNoise, glslSimplexNoise2D, glslSimplexFbm, glslDeclarePI, glslRotate2, } from "./shaderNoise.glsl";
+export { glslBayerMatrices } from "./bayerMatrices.glsl";
+export { glslImageCoverUV } from "./imageUV.glsl";

package/dist/components/effects/shared/resolveShaderColor.d.ts

@@ -0,0 +1,13 @@
+/** Normalized RGBA color as 0-1 floats, suitable for a WebGL uniform. */
+export type RGBA = [number, number, number, number];
+/**
+ * Resolves any valid CSS color string — hex, rgb()/rgba(), oklch(), named
+ * colors, or a `var(--custom-property)` reference (including FlikkUI theme
+ * tokens defined on :root/.dark) — to a normalized [r, g, b, a] float array
+ * (0-1) suitable for a WebGL uniform. Client-only; must be called after
+ * mount, never at module scope (SSR safety, CLAUDE.md §11). Returns
+ * `fallback` if the string can't be resolved (e.g. during SSR).
+ */
+export declare function resolveShaderColor(colorStr: string, fallback?: RGBA): RGBA;
+/** Resolves an array of colors in one pass, reusing a single probe element. */
+export declare function resolveShaderColors(colorStrs: string[], fallback?: RGBA): RGBA[];

package/dist/components/effects/shared/resolveShaderColor.js

@@ -0,0 +1,62 @@
+"use client";
+const DEFAULT_FALLBACK = [0.5, 0.5, 0.5, 1];
+let probeEl = null;
+let probeCtx;
+function getProbeEl() {
+    if (!probeEl) {
+        probeEl = document.createElement("span");
+        probeEl.style.position = "absolute";
+        probeEl.style.width = "0";
+        probeEl.style.height = "0";
+        probeEl.style.overflow = "hidden";
+        probeEl.style.pointerEvents = "none";
+        probeEl.setAttribute("aria-hidden", "true");
+    }
+    return probeEl;
+}
+/** Lazily-created 1x1 canvas used to normalize any CSS color (rgb, hex, named,
+ *  oklch, lab, color(), etc.) to straight sRGB bytes via getImageData — canvas
+ *  fillStyle accepts every CSS color syntax and always renders into sRGB,
+ *  which getComputedStyle's `color` serialization does not reliably do (some
+ *  browsers echo back oklch()/lab() strings for tokens authored in that space). */
+function getProbeCtx() {
+    if (probeCtx === undefined) {
+        const canvas = document.createElement("canvas");
+        canvas.width = 1;
+        canvas.height = 1;
+        probeCtx = canvas.getContext("2d", { willReadFrequently: true });
+    }
+    return probeCtx;
+}
+/**
+ * Resolves any valid CSS color string — hex, rgb()/rgba(), oklch(), named
+ * colors, or a `var(--custom-property)` reference (including FlikkUI theme
+ * tokens defined on :root/.dark) — to a normalized [r, g, b, a] float array
+ * (0-1) suitable for a WebGL uniform. Client-only; must be called after
+ * mount, never at module scope (SSR safety, CLAUDE.md §11). Returns
+ * `fallback` if the string can't be resolved (e.g. during SSR).
+ */
+function resolveShaderColor(colorStr, fallback = DEFAULT_FALLBACK) {
+    if (typeof document === "undefined")
+        return fallback;
+    const el = getProbeEl();
+    el.style.color = "";
+    el.style.color = colorStr;
+    document.body.appendChild(el);
+    const computed = getComputedStyle(el).color;
+    document.body.removeChild(el);
+    const ctx = getProbeCtx();
+    if (!ctx)
+        return fallback;
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = computed;
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    return [r / 255, g / 255, b / 255, a / 255];
+}
+/** Resolves an array of colors in one pass, reusing a single probe element. */
+function resolveShaderColors(colorStrs, fallback = DEFAULT_FALLBACK) {
+    return colorStrs.map((c) => resolveShaderColor(c, fallback));
+}
+
+export { resolveShaderColor, resolveShaderColors };

package/dist/components/effects/shared/resolveShaderColor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/effects/shared/shaderNoise.glsl.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared GLSL noise primitives, consumed via template-literal interpolation
+ * (e.g. `${glslHashFloat}`) inside individual `*.shaders.ts` fragment shader
+ * sources. There is no GLSL `#include` mechanism, so consumers must
+ * interpolate snippets in dependency order (e.g. glslHashFloat before
+ * glslValueNoise, glslSimplexNoise2D before glslSimplexFbm).
+ *
+ * These pure-hash functions stand in for paper-design/shaders' pre-generated
+ * noise-texture sampling (`u_noiseTexture` + `textureRandomizerR`) — a
+ * deliberate simplification that removes an entire texture-generation
+ * subsystem in exchange for a tiny amount of extra ALU cost per pixel.
+ */
+/** Pure-hash pseudo-random float in [0,1) for a vec2 input, no texture lookup.
+ *  Adapted from paper-design/shaders' DotOrbit/GodRays/SmokeRing fragment
+ *  shaders (https://github.com/paper-design/shaders, Apache License 2.0). */
+export declare const glslHashFloat = "\nfloat randomR(vec2 st) {\n  return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123);\n}\n";
+/** Pure-hash pseudo-random vec2, no texture lookup. Same source as glslHashFloat. */
+export declare const glslHashVec2 = "\nvec2 randomGB(vec2 st) {\n  return vec2(\n    fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123),\n    fract(sin(dot(st, vec2(93.9898, 67.345))) * 24634.6345123)\n  );\n}\n";
+/** Bilinear-interpolated value noise built on glslHashFloat. Requires
+ *  glslHashFloat to be interpolated earlier in the same shader source. */
+export declare const glslValueNoise = "\nfloat valueNoise(vec2 st) {\n  vec2 i = floor(st);\n  vec2 f = fract(st);\n  float a = randomR(i);\n  float b = randomR(i + vec2(1.0, 0.0));\n  float c = randomR(i + vec2(0.0, 1.0));\n  float d = randomR(i + vec2(1.0, 1.0));\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float x1 = mix(a, b, u.x);\n  float x2 = mix(c, d, u.x);\n  return mix(x1, x2, u.y);\n}\n";
+/** Ashima Arts / Stefan Gustavson 2D simplex noise (ISC license) — generic,
+ *  ubiquitous prior art in the WebGL shader ecosystem, NOT paper-design's own
+ *  IP. Used as the low-level noise primitive under some ported effects whose
+ *  higher-level composition logic IS credited to paper-design in their own
+ *  doc comments (e.g. GrainGradient, Dithering, Water, LiquidMetal). */
+export declare const glslSimplexNoise2D = "\nvec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec2 mod289(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec3 permute(vec3 x) { return mod289(((x * 34.0) + 1.0) * x); }\n\nfloat snoise(vec2 v) {\n  const vec4 C = vec4(0.211324865405187, 0.366025403784439,\n                       -0.577350269189626, 0.024390243902439);\n  vec2 i  = floor(v + dot(v, C.yy));\n  vec2 x0 = v - i + dot(i, C.xx);\n\n  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);\n  vec4 x12 = x0.xyxy + C.xxzz;\n  x12.xy -= i1;\n\n  i = mod289(i);\n  vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));\n\n  vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);\n  m = m * m;\n  m = m * m;\n\n  vec3 x = 2.0 * fract(p * C.www) - 1.0;\n  vec3 h = abs(x) - 0.5;\n  vec3 ox = floor(x + 0.5);\n  vec3 a0 = x - ox;\n\n  m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);\n\n  vec3 g;\n  g.x = a0.x * x0.x + h.x * x0.y;\n  g.yz = a0.yz * x12.xz + h.yz * x12.yw;\n  return 130.0 * dot(m, g);\n}\n";
+/** Small fractional-Brownian-motion built on glslSimplexNoise2D. Requires
+ *  glslSimplexNoise2D to be interpolated earlier in the same shader source. */
+export declare const glslSimplexFbm = "\nfloat fbm(vec2 st) {\n  float value = 0.0;\n  float amplitude = 0.5;\n  for (int i = 0; i < 4; i++) {\n    value += amplitude * snoise(st);\n    st *= 2.0;\n    amplitude *= 0.5;\n  }\n  return value;\n}\n";
+/** Common PI / TWO_PI constants, interpolated first in most shaders. */
+export declare const glslDeclarePI = "\nconst float PI = 3.14159265359;\nconst float TWO_PI = 6.28318530718;\n";
+/** 2D rotation helper matching paper-design's `rotate(vec2, float)` signature. */
+export declare const glslRotate2 = "\nvec2 rotate(vec2 v, float angle) {\n  float s = sin(angle);\n  float c = cos(angle);\n  return mat2(c, -s, s, c) * v;\n}\n";

package/dist/components/effects/shared/shaderNoise.glsl.js

@@ -0,0 +1,84 @@
+/**
+ * Shared GLSL noise primitives, consumed via template-literal interpolation
+ * (e.g. `${glslHashFloat}`) inside individual `*.shaders.ts` fragment shader
+ * sources. There is no GLSL `#include` mechanism, so consumers must
+ * interpolate snippets in dependency order (e.g. glslHashFloat before
+ * glslValueNoise, glslSimplexNoise2D before glslSimplexFbm).
+ *
+ * These pure-hash functions stand in for paper-design/shaders' pre-generated
+ * noise-texture sampling (`u_noiseTexture` + `textureRandomizerR`) — a
+ * deliberate simplification that removes an entire texture-generation
+ * subsystem in exchange for a tiny amount of extra ALU cost per pixel.
+ */
+/** Pure-hash pseudo-random float in [0,1) for a vec2 input, no texture lookup.
+ *  Adapted from paper-design/shaders' DotOrbit/GodRays/SmokeRing fragment
+ *  shaders (https://github.com/paper-design/shaders, Apache License 2.0). */
+const glslHashFloat = `
+float randomR(vec2 st) {
+  return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123);
+}
+`;
+/** Pure-hash pseudo-random vec2, no texture lookup. Same source as glslHashFloat. */
+const glslHashVec2 = `
+vec2 randomGB(vec2 st) {
+  return vec2(
+    fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123),
+    fract(sin(dot(st, vec2(93.9898, 67.345))) * 24634.6345123)
+  );
+}
+`;
+/** Ashima Arts / Stefan Gustavson 2D simplex noise (ISC license) — generic,
+ *  ubiquitous prior art in the WebGL shader ecosystem, NOT paper-design's own
+ *  IP. Used as the low-level noise primitive under some ported effects whose
+ *  higher-level composition logic IS credited to paper-design in their own
+ *  doc comments (e.g. GrainGradient, Dithering, Water, LiquidMetal). */
+const glslSimplexNoise2D = `
+vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec2 mod289(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec3 permute(vec3 x) { return mod289(((x * 34.0) + 1.0) * x); }
+
+float snoise(vec2 v) {
+  const vec4 C = vec4(0.211324865405187, 0.366025403784439,
+                       -0.577350269189626, 0.024390243902439);
+  vec2 i  = floor(v + dot(v, C.yy));
+  vec2 x0 = v - i + dot(i, C.xx);
+
+  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  vec4 x12 = x0.xyxy + C.xxzz;
+  x12.xy -= i1;
+
+  i = mod289(i);
+  vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
+
+  vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);
+  m = m * m;
+  m = m * m;
+
+  vec3 x = 2.0 * fract(p * C.www) - 1.0;
+  vec3 h = abs(x) - 0.5;
+  vec3 ox = floor(x + 0.5);
+  vec3 a0 = x - ox;
+
+  m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);
+
+  vec3 g;
+  g.x = a0.x * x0.x + h.x * x0.y;
+  g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+  return 130.0 * dot(m, g);
+}
+`;
+/** Common PI / TWO_PI constants, interpolated first in most shaders. */
+const glslDeclarePI = `
+const float PI = 3.14159265359;
+const float TWO_PI = 6.28318530718;
+`;
+/** 2D rotation helper matching paper-design's `rotate(vec2, float)` signature. */
+const glslRotate2 = `
+vec2 rotate(vec2 v, float angle) {
+  float s = sin(angle);
+  float c = cos(angle);
+  return mat2(c, -s, s, c) * v;
+}
+`;
+
+export { glslDeclarePI, glslHashFloat, glslHashVec2, glslRotate2, glslSimplexNoise2D };

package/dist/components/forms/Checkbox/Checkbox.animations.js

@@ -1,3 +1,4 @@
+"use client";
 const smoothEase = [0.65, 0, 0.35, 1];
 /**
  * Checkmark SVG path draw-on animation

package/dist/components/forms/Checkbox/Checkbox.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useId, useState, useRef, useEffect } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
@@ -36,12 +37,11 @@ const CheckboxComponent = React__default.forwardRef(({ id: idProp, name: namePro
     else {
         isChecked = internalChecked;
     }
-    // A checked checkbox has been acted upon, so it should no longer read as an
-    // error: once checked it clears its own invalid styling (box border + label).
-    // The group-level error message stays under the consumer's control — this only
-    // resolves the per-item state so unchecked siblings keep signalling the error.
-    const showInvalid = isInvalid && !(isChecked && !indeterminate);
-    const visualState = isDisabled ? "disabled" : showInvalid ? "invalid" : "default";
+    // Message-led invalid: the control + label stay neutral (mirrors Radio). The
+    // group's required asterisk + error message carry the error (see CheckboxGroup).
+    // `data-state=invalid` is still emitted on the input as an unstyled hook, and
+    // `aria-invalid`/`aria-errormessage` live on the group fieldset, not each input.
+    const visualState = isDisabled ? "disabled" : "default";
     const inputRef = useRef(null);
     // Set indeterminate property on the input element
     useEffect(() => {
@@ -69,13 +69,13 @@ const CheckboxComponent = React__default.forwardRef(({ id: idProp, name: namePro
         }
         onChange === null || onChange === void 0 ? void 0 : onChange(e.target.checked, value);
     };
-    return (jsxs("div", { className: cn(checkboxTheme.baseStyle, className), ...restProps, children: [jsxs("div", { className: cn(checkboxTheme.inputContainerStyle, checkboxTheme.sizes[size]), children: [jsx("input", { ref: (node) => {
+    return (jsxs("div", { className: cn(checkboxTheme.baseStyle, className), children: [jsxs("div", { className: cn(checkboxTheme.inputContainerStyle, checkboxTheme.sizes[size]), children: [jsx("input", { ref: (node) => {
                             inputRef.current = node;
                             if (typeof ref === "function")
                                 ref(node);
                             else if (ref)
                                 ref.current = node;
-                        }, type: "checkbox", id: id, name: name, value: value, checked: isChecked, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "aria-invalid": showInvalid || undefined, "data-state": visualState, className: cn(checkboxTheme.inputStyle, checkboxTheme.sizes[size], indeterminate && "bg-neutral-200") }), jsxs(AnimatePresence, { mode: "wait", children: [indeterminate && (jsx(motion.svg, { viewBox: "0 0 16 16", fill: "none", className: cn("pointer-events-none col-start-1 row-start-1 self-center justify-self-center text-neutral-600", size === "sm" ? "size-3" : size === "lg" ? "size-5" : "size-4"), children: jsx(motion.path, { d: "M3.5 8 L12.5 8", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", variants: shouldReduceMotion ? reducedMotionVariants : indeterminateVariants, initial: "unchecked", animate: "checked", exit: "unchecked" }) }, "indeterminate")), isChecked && !indeterminate && (jsx(motion.svg, { viewBox: "0 0 16 16", fill: "none", className: cn("pointer-events-none col-start-1 row-start-1 self-center justify-self-center text-white", size === "sm" ? "size-3" : size === "lg" ? "size-5" : "size-4"), children: jsx(motion.path, { d: "M3.5 8.5 L6.5 11.5 L12.5 4.5", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", strokeLinejoin: "round", variants: shouldReduceMotion ? reducedMotionVariants : checkmarkVariants, initial: "unchecked", animate: "checked", exit: "unchecked" }) }, "checkmark"))] })] }), (label || description) && (jsxs("label", { htmlFor: id, className: cn("cursor-pointer", isDisabled && "cursor-not-allowed"), children: [label && (typeof label === 'string' ? (jsx("span", { className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[visualState], "mb-0"), children: label })) : (label)), description && (typeof description === 'string' ? (jsx("div", { id: `${id}-description`, className: checkboxTheme.descriptionStyle, children: description })) : (description))] }))] }));
+                        }, type: "checkbox", ...restProps, id: id, name: name, value: value, checked: isChecked, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "aria-invalid": !isInGroup && isInvalid ? true : undefined, "data-state": isDisabled ? "disabled" : isInvalid ? "invalid" : "default", className: cn(checkboxTheme.inputStyle, checkboxTheme.sizes[size], indeterminate && "bg-neutral-200") }), jsxs(AnimatePresence, { mode: "wait", children: [indeterminate && (jsx(motion.svg, { viewBox: "0 0 16 16", fill: "none", className: cn("pointer-events-none col-start-1 row-start-1 self-center justify-self-center text-neutral-600", size === "sm" ? "size-3" : size === "lg" ? "size-5" : "size-4"), children: jsx(motion.path, { d: "M3.5 8 L12.5 8", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", variants: shouldReduceMotion ? reducedMotionVariants : indeterminateVariants, initial: "unchecked", animate: "checked", exit: "unchecked" }) }, "indeterminate")), isChecked && !indeterminate && (jsx(motion.svg, { viewBox: "0 0 16 16", fill: "none", className: cn("pointer-events-none col-start-1 row-start-1 self-center justify-self-center text-[var(--color-primary-contrast)]", size === "sm" ? "size-3" : size === "lg" ? "size-5" : "size-4"), children: jsx(motion.path, { d: "M3.5 8.5 L6.5 11.5 L12.5 4.5", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", strokeLinejoin: "round", variants: shouldReduceMotion ? reducedMotionVariants : checkmarkVariants, initial: "unchecked", animate: "checked", exit: "unchecked" }) }, "checkmark"))] })] }), (label || description) && (jsxs("label", { htmlFor: id, className: cn("cursor-pointer", isDisabled && "cursor-not-allowed"), children: [label && (typeof label === 'string' ? (jsx("span", { className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[visualState], "mb-0"), children: label })) : (label)), description && (typeof description === 'string' ? (jsx("div", { id: `${id}-description`, className: checkboxTheme.descriptionStyle, children: description })) : (description))] }))] }));
 });
 CheckboxComponent.displayName = "Checkbox";
 const Checkbox = Object.assign(CheckboxComponent, {

package/dist/components/forms/Checkbox/Checkbox.theme.js

@@ -6,7 +6,7 @@ const checkboxTheme = {
     baseStyle: "relative flex items-start gap-3",
     inputContainerStyle: "relative flex-shrink-0 group grid grid-cols-1",
     // Input styles with light and dark mode variants
-    inputStyle: "col-start-1 row-start-1 appearance-none rounded-[calc(var(--radius-base)*0.75)] border-2 transition-all duration-400 " +
+    inputStyle: "col-start-1 row-start-1 appearance-none rounded-[var(--checkbox-radius)] border-2 transition-all duration-400 " +
         // Default state - light
         "border-[var(--color-border)] bg-[var(--color-surface)] " +
         // Default state - dark
@@ -24,9 +24,10 @@ const checkboxTheme = {
         "data-[state=disabled]:border-[var(--color-border)] data-[state=disabled]:bg-[var(--color-background-disabled)] data-[state=disabled]:cursor-not-allowed " +
         // Disabled state - dark
         "dark:disabled:bg-[var(--color-neutral-800)] dark:disabled:border-[var(--color-neutral-600)] " +
-        "dark:data-[state=disabled]:bg-[var(--color-neutral-700)] dark:data-[state=disabled]:border-[var(--color-neutral-600)] " +
-        // Invalid state
-        "data-[state=invalid]:border-[var(--color-danger)] data-[state=invalid]:focus-visible:outline-[var(--color-danger)]",
+        "dark:data-[state=disabled]:bg-[var(--color-neutral-700)] dark:data-[state=disabled]:border-[var(--color-neutral-600)]",
+    // Invalid is message-led: the control stays neutral (mirrors Radio). The group's
+    // required asterisk + error message carry the error (see CheckboxGroup). `data-state=invalid`
+    // is still emitted on the input as an unstyled consumer/test hook.
     // Description text - light and dark
     descriptionStyle: "text-sm mt-0.5 " + "text-[var(--color-text-secondary)]/80 " + " ",
     sizes: {

package/dist/components/forms/Checkbox/CheckboxContext.js

@@ -1,3 +1,4 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 const CheckboxGroupContext = createContext(undefined);

package/dist/components/forms/Checkbox/CheckboxGroup.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useId, useState, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -36,7 +37,9 @@ const CheckboxGroup = React__default.forwardRef(({ value: controlledValue, defau
         size,
         state,
     }), [groupName, currentValue, size, state]);
-    const labelState = state === "invalid" ? "invalid" : state === "disabled" ? "disabled" : "default";
+    // Message-led invalid: the legend text stays neutral; the red required asterisk
+    // + the error message below carry the error (mirrors RadioGroup).
+    const labelState = state === "disabled" ? "disabled" : "default";
     return (jsx(CheckboxGroupContext.Provider, { value: contextValue, children: jsxs("fieldset", { ref: ref, role: "group", "aria-labelledby": label ? labelId : undefined, "aria-describedby": description ? descriptionId : undefined, "aria-required": required || undefined, "aria-invalid": resolvedError ? true : undefined, "aria-errormessage": resolvedError ? errorId : undefined, className: cn("border-0 p-0 m-0", checkboxTheme.groupStyle, className), ...props, children: [label && (typeof label === 'string' ? (jsxs("legend", { id: labelId, className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[labelState]), children: [label, required && (jsx("span", { className: formLabelTheme.requiredIndicatorStyle, children: "*" }))] })) : (label)), description && (typeof description === 'string' ? (jsx("p", { id: descriptionId, className: checkboxTheme.groupDescriptionStyle, children: description })) : (description)), jsx("div", { className: cn(checkboxTheme.groupItemsStyle, orientation === "horizontal" &&
                         checkboxTheme.groupHorizontalStyle), children: children }), resolvedError && (typeof resolvedError === 'string' ? (jsx("p", { id: errorId, role: "alert", className: checkboxTheme.groupErrorStyle, children: resolvedError })) : (resolvedError))] }) }));
 });