@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/components/effects/MeshGradient/MeshGradient.utils.js

@@ -0,0 +1,112 @@
+import { contrastTone } from '../../../utils/colorUtils.js';
+
+/**
+ * Deterministic hashing + color helpers for MeshGradient.
+ *
+ * The string-hash idea comes from boring-avatars
+ * (https://github.com/boringdesigners/boring-avatars, MIT License). We turn the
+ * `seed` into a numeric seed, then draw well-distributed blob positions/colors
+ * from a tiny deterministic PRNG so the same `seed` always yields the same
+ * mesh — but the blobs spread across the surface instead of clustering.
+ */
+/**
+ * Curated vibrant palettes. Each is a designer-grade cool→warm sweep (so within
+ * one tile distinct colors meet and blend, the way boring-avatars' marble does).
+ * The DEFAULT is the boring-avatars marble palette itself — variety comes from
+ * each `seed` emphasizing different colors *within* the palette (not from
+ * swapping palettes), which keeps a whole set cohesive yet distinct. Pass any of
+ * these (or your own) to the `colors` prop; `pickPalette` is offered for
+ * consumers who instead want the seed to choose a palette.
+ */
+const MESH_PALETTES = [
+    ["#00686C", "#32C2B9", "#EDECB3", "#FAD928", "#FF9915"], // Marble (boring-avatars) — default
+    ["#264653", "#2A9D8F", "#E9C46A", "#F4A261", "#E76F51"], // Terra    (teal→sand→terracotta)
+    ["#F72585", "#B5179E", "#7209B7", "#4361EE", "#4CC9F0"], // Spectrum (magenta→violet→cyan)
+    ["#2EC4B6", "#80ED99", "#CBF3F0", "#FFBF69", "#FF9F1C"], // Mint     (teal→mint→peach)
+    ["#00F5D4", "#00BBF9", "#9B5DE5", "#F15BB5", "#FEE440"], // Neon     (cyan→violet→pink→yellow)
+];
+/** Default palette — the boring-avatars marble set. */
+const DEFAULT_MESH_COLORS = MESH_PALETTES[0];
+/** Named handles for the curated palettes (ergonomic alternative to indexing). */
+const MESH_PALETTE_BY_NAME = {
+    marble: MESH_PALETTES[0],
+    terra: MESH_PALETTES[1],
+    spectrum: MESH_PALETTES[2],
+    mint: MESH_PALETTES[3],
+    neon: MESH_PALETTES[4],
+};
+/** Deterministic 32-bit hash of a string. Same input → same output. */
+const hashCode = (name) => {
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        const character = name.charCodeAt(i);
+        hash = (hash << 5) - hash + character;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+};
+/** Deterministically pick one of the curated `MESH_PALETTES` from a seed. */
+const pickPalette = (seed) => MESH_PALETTES[hashCode(seed) % MESH_PALETTES.length];
+/** viewBox size the marble is authored in (mirrors boring-avatars). */
+const MESH_SIZE = 80;
+/**
+ * Two fixed, irregular polygon paths (verbatim from boring-avatars' marble,
+ * MIT). Filled with a color, transformed per-seed, and heavily Gaussian-blurred,
+ * they melt into the smooth flowing veins that define the marble look.
+ */
+const MARBLE_PATHS = [
+    "M32.414 59.35L50.376 70.5H72.5v-71H33.728L26.5 13.381l19.057 27.08L32.414 59.35z",
+    "M22.216 24L0 46.75l14.108 38.129L78 86l-3.081-59.276-22.378 4.005 12.972 20.186-23.35 27.395L22.215 24z",
+];
+/** nth decimal digit of a number (boring-avatars helper). */
+const getDigit = (number, ntn) => Math.floor((number / Math.pow(10, ntn)) % 10);
+/** Value in (−range, range) seeded by `number`; sign flips on an even digit. */
+const getUnit = (number, range, index) => {
+    const value = number % range;
+    if (index && getDigit(number, index) % 2 === 0)
+        return -value;
+    return value;
+};
+/** First shape sits normal on the base; the rest composite to enrich the blend. */
+const BLENDS = ["normal", "overlay", "soft-light", "overlay"];
+/**
+ * Derive a deterministic marble field from a seed + palette — a faithful port of
+ * boring-avatars' marble. Colors are *consecutive* palette entries
+ * (`palette[(hash + i) % len]`): always neighbouring hues, which is what keeps
+ * every tile harmonious and smooth. Each shape gets a seeded translate/rotate/
+ * scale and is heavily blurred at render; the 2nd shape onward composites with
+ * overlay/soft-light. Same `seed` → same field.
+ */
+const generateMarble = (seed, colors, count) => {
+    const num = hashCode(seed);
+    const range = colors.length || 1;
+    const color = (i) => { var _a; return (_a = colors[(num + i) % range]) !== null && _a !== void 0 ? _a : colors[0]; };
+    const shapes = Array.from({ length: count }, (_unused, k) => {
+        const i = k + 1; // element index — 0 is the base
+        return {
+            color: color(i),
+            translateX: getUnit(num * (i + 1), MESH_SIZE / 10, 1),
+            translateY: getUnit(num * (i + 1), MESH_SIZE / 10, 2),
+            rotate: getUnit(num * (i + 1), 360, 1),
+            scale: 1.2 + getUnit(num * (i + 1), MESH_SIZE / 20) / 10,
+            path: MARBLE_PATHS[k % MARBLE_PATHS.length],
+            blend: BLENDS[k % BLENDS.length],
+        };
+    });
+    return { base: color(0), shapes };
+};
+/**
+ * The text tone (`"light"` | `"dark"`) that reads best over the mesh a given
+ * seed produces. Decided from the **base** color — the full-tile ground that
+ * best predicts overall darkness. (Averaging in the small, blurred bright shapes
+ * mis-reads dark tiles like a teal base with a cream accent.) Pass `threshold`
+ * to bias toward light text on more mid-tones (see `contrastTone`). Map the
+ * result to the theme-stable neutral tokens at the call site, e.g.
+ * `tone === "dark" ? "var(--color-mono-950)" : "var(--color-mono-50)"`.
+ */
+const getMeshTextTone = (seed, colors, count, threshold) => {
+    const { base } = generateMarble(seed, colors, count);
+    return contrastTone(base, { threshold });
+};
+
+export { DEFAULT_MESH_COLORS, MARBLE_PATHS, MESH_PALETTES, MESH_PALETTE_BY_NAME, MESH_SIZE, generateMarble, getMeshTextTone, hashCode, pickPalette };

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

@@ -0,0 +1,4 @@
+export { MeshGradient } from "./MeshGradient";
+export type { MeshGradientProps, MeshGradientBlendMode, } from "./MeshGradient.types";
+export { DEFAULT_MESH_COLORS, MESH_PALETTES, MESH_PALETTE_BY_NAME, pickPalette, getMeshTextTone, } from "./MeshGradient.utils";
+export type { MeshPaletteName } from "./MeshGradient.utils";

package/dist/components/effects/Metaballs/Metaballs.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import type { MetaballsProps } from "./Metaballs.types";
+/**
+ * Animated lava-lamp-style blobby merging balls. WebGL2-powered; falls back
+ * to a static CSS radial-gradient cluster when WebGL2 is unavailable or the
+ * user prefers reduced motion.
+ */
+export declare const Metaballs: React.FC<MetaballsProps>;

package/dist/components/effects/Metaballs/Metaballs.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useMemo, useRef } from 'react';
+import { useReducedMotion } from 'motion/react';
+import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { cn } from '../../../utils/cn.js';
+import { ShaderCanvas } from '../shared/ShaderCanvas/ShaderCanvas.js';
+import { resolveShaderColors, resolveShaderColor } from '../shared/resolveShaderColor.js';
+import { metaballsFragmentShader } from './Metaballs.shaders.js';
+import { METABALLS_MAX_COLORS } from './Metaballs.types.js';
+
+const DEFAULT_COLORS = ["var(--color-primary-300)", "var(--color-primary)", "var(--color-primary-700)"];
+const DEFAULT_COLOR_BACK = "var(--color-background)";
+function useWebgl2Supported(disabled) {
+    return useMemo(() => {
+        if (disabled || typeof document === "undefined")
+            return false;
+        try {
+            return !!document.createElement("canvas").getContext("webgl2");
+        }
+        catch (_a) {
+            return false;
+        }
+    }, [disabled]);
+}
+/**
+ * Animated lava-lamp-style blobby merging balls. WebGL2-powered; falls back
+ * to a static CSS radial-gradient cluster when WebGL2 is unavailable or the
+ * user prefers reduced motion.
+ */
+const Metaballs = ({ colorBack = DEFAULT_COLOR_BACK, colors = DEFAULT_COLORS, count = 10, size = 0.6, speed = 1, className, style, ...props }) => {
+    var _a, _b, _c, _d;
+    const isClient = useIsClient();
+    const shouldReduceMotion = useReducedMotion();
+    const isDark = useDarkMode();
+    const webglSupported = useWebgl2Supported(!!shouldReduceMotion);
+    const safeColors = colors.length > 0 ? colors.slice(0, METABALLS_MAX_COLORS) : DEFAULT_COLORS;
+    const resolvedColors = useMemo(() => resolveShaderColors(safeColors), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [safeColors.join("|"), isDark]);
+    const resolvedBack = useMemo(() => resolveShaderColor(colorBack), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [colorBack, isDark]);
+    const uniformsRef = useRef({});
+    for (let i = 0; i < METABALLS_MAX_COLORS; i++) {
+        uniformsRef.current[`u_colors[${i}]`] =
+            (_b = (_a = resolvedColors[i]) !== null && _a !== void 0 ? _a : resolvedColors[resolvedColors.length - 1]) !== null && _b !== void 0 ? _b : [0, 0, 0, 0];
+    }
+    uniformsRef.current.u_colorsCount = resolvedColors.length;
+    uniformsRef.current.u_colorBack = resolvedBack;
+    uniformsRef.current.u_count = count;
+    uniformsRef.current.u_size = size;
+    uniformsRef.current.u_speed = speed;
+    const fallbackGradient = `radial-gradient(circle at 30% 40%, ${(_c = safeColors[0]) !== null && _c !== void 0 ? _c : "var(--color-primary)"}, transparent 60%), radial-gradient(circle at 70% 60%, ${(_d = safeColors[safeColors.length - 1]) !== null && _d !== void 0 ? _d : "var(--color-primary)"}, transparent 60%), ${colorBack}`;
+    return (jsx("div", { className: cn("absolute inset-0 overflow-hidden pointer-events-none select-none", className), style: style, "aria-hidden": "true", ...props, children: isClient && webglSupported ? (jsx(ShaderCanvas, { fragmentShader: metaballsFragmentShader, uniformsRef: uniformsRef })) : (jsx("div", { className: "absolute inset-0", style: { background: fallbackGradient } })) }));
+};
+
+export { Metaballs };

package/dist/components/effects/Metaballs/Metaballs.shaders.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Metaballs fragment shader — adapted from paper-design/shaders' `metaballs.ts`
+ * (https://github.com/paper-design/shaders, Apache License 2.0).
+ *
+ * Simplified from the original: plain centered/aspect-corrected UV
+ * (gl_FragCoord/iResolution) instead of paper-design's ShaderSizingParams
+ * fit/scale/rotation engine; pure-hash GLSL (see shared/shaderNoise.glsl.ts)
+ * instead of pre-generated noise-texture sampling.
+ */
+export declare const metaballsFragmentShader = "#version 300 es\nprecision mediump float;\n\nuniform float iTime;\nuniform vec2 iResolution;\n\nuniform vec4 u_colorBack;\nuniform vec4 u_colors[8];\nuniform float u_colorsCount;\nuniform float u_size;\nuniform float u_count;\nuniform float u_speed;\n\nout vec4 fragColor;\n\n\nconst float PI = 3.14159265359;\nconst float TWO_PI = 6.28318530718;\n\n\nfloat randomR(vec2 st) {\n  return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123);\n}\n\n\nfloat noise(float x) {\n  float i = floor(x);\n  float f = fract(x);\n  float u = f * f * (3.0 - 2.0 * f);\n  vec2 p0 = vec2(i, 0.0);\n  vec2 p1 = vec2(i + 1.0, 0.0);\n  return mix(randomR(p0), randomR(p1), u);\n}\n\nfloat getBallShape(vec2 uv, vec2 c, float p) {\n  float s = .5 * length(uv - c);\n  s = 1. - clamp(s, 0., 1.);\n  s = pow(s, p);\n  return s;\n}\n\nvoid main() {\n  vec2 objectUV = (gl_FragCoord.xy - 0.5 * iResolution.xy) / min(iResolution.x, iResolution.y);\n  vec2 shape_uv = objectUV + .5;\n\n  const float firstFrameOffset = 2503.4;\n  float t = .2 * u_speed * iTime + firstFrameOffset;\n\n  vec3 totalColor = vec3(0.);\n  float totalShape = 0.;\n  float totalOpacity = 0.;\n\n  for (int i = 0; i < 20; i++) {\n    if (i >= int(ceil(u_count))) break;\n    float idxFract = float(i) / float(20);\n    float angle = TWO_PI * idxFract;\n    float speed = 1. - .2 * idxFract;\n    float noiseX = noise(angle * 10. + float(i) + t * speed);\n    float noiseY = noise(angle * 20. + float(i) - t * speed);\n    vec2 pos = vec2(.5) + 1e-4 + .9 * (vec2(noiseX, noiseY) - .5);\n\n    int safeIndex = i % int(u_colorsCount + 0.5);\n    vec4 ballColor = u_colors[safeIndex];\n    ballColor.rgb *= ballColor.a;\n\n    float sizeFrac = 1.;\n    if (float(i) > floor(u_count - 1.)) {\n      sizeFrac *= fract(u_count);\n    }\n\n    float shape = getBallShape(shape_uv, pos, 45. - 30. * u_size * sizeFrac);\n    shape *= pow(u_size, .2);\n    shape = smoothstep(0., 1., shape);\n\n    totalColor += ballColor.rgb * shape;\n    totalShape += shape;\n    totalOpacity += ballColor.a * shape;\n  }\n\n  totalColor /= max(totalShape, 1e-4);\n  totalOpacity /= max(totalShape, 1e-4);\n\n  float edge_width = fwidth(totalShape);\n  float finalShape = smoothstep(.4, .4 + edge_width, totalShape);\n\n  vec3 color = totalColor * finalShape;\n  float opacity = totalOpacity * finalShape;\n  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;\n  color = color + bgColor * (1. - opacity);\n  opacity = opacity + u_colorBack.a * (1. - opacity);\n\n  fragColor = vec4(color, opacity);\n}\n";

package/dist/components/effects/Metaballs/Metaballs.shaders.js

@@ -0,0 +1,102 @@
+import 'react/jsx-runtime';
+import 'react';
+import { glslDeclarePI, glslHashFloat } from '../shared/shaderNoise.glsl.js';
+
+/**
+ * Metaballs fragment shader — adapted from paper-design/shaders' `metaballs.ts`
+ * (https://github.com/paper-design/shaders, Apache License 2.0).
+ *
+ * Simplified from the original: plain centered/aspect-corrected UV
+ * (gl_FragCoord/iResolution) instead of paper-design's ShaderSizingParams
+ * fit/scale/rotation engine; pure-hash GLSL (see shared/shaderNoise.glsl.ts)
+ * instead of pre-generated noise-texture sampling.
+ */
+const metaballsFragmentShader = `#version 300 es
+precision mediump float;
+
+uniform float iTime;
+uniform vec2 iResolution;
+
+uniform vec4 u_colorBack;
+uniform vec4 u_colors[8];
+uniform float u_colorsCount;
+uniform float u_size;
+uniform float u_count;
+uniform float u_speed;
+
+out vec4 fragColor;
+
+${glslDeclarePI}
+${glslHashFloat}
+
+float noise(float x) {
+  float i = floor(x);
+  float f = fract(x);
+  float u = f * f * (3.0 - 2.0 * f);
+  vec2 p0 = vec2(i, 0.0);
+  vec2 p1 = vec2(i + 1.0, 0.0);
+  return mix(randomR(p0), randomR(p1), u);
+}
+
+float getBallShape(vec2 uv, vec2 c, float p) {
+  float s = .5 * length(uv - c);
+  s = 1. - clamp(s, 0., 1.);
+  s = pow(s, p);
+  return s;
+}
+
+void main() {
+  vec2 objectUV = (gl_FragCoord.xy - 0.5 * iResolution.xy) / min(iResolution.x, iResolution.y);
+  vec2 shape_uv = objectUV + .5;
+
+  const float firstFrameOffset = 2503.4;
+  float t = .2 * u_speed * iTime + firstFrameOffset;
+
+  vec3 totalColor = vec3(0.);
+  float totalShape = 0.;
+  float totalOpacity = 0.;
+
+  for (int i = 0; i < 20; i++) {
+    if (i >= int(ceil(u_count))) break;
+    float idxFract = float(i) / float(20);
+    float angle = TWO_PI * idxFract;
+    float speed = 1. - .2 * idxFract;
+    float noiseX = noise(angle * 10. + float(i) + t * speed);
+    float noiseY = noise(angle * 20. + float(i) - t * speed);
+    vec2 pos = vec2(.5) + 1e-4 + .9 * (vec2(noiseX, noiseY) - .5);
+
+    int safeIndex = i % int(u_colorsCount + 0.5);
+    vec4 ballColor = u_colors[safeIndex];
+    ballColor.rgb *= ballColor.a;
+
+    float sizeFrac = 1.;
+    if (float(i) > floor(u_count - 1.)) {
+      sizeFrac *= fract(u_count);
+    }
+
+    float shape = getBallShape(shape_uv, pos, 45. - 30. * u_size * sizeFrac);
+    shape *= pow(u_size, .2);
+    shape = smoothstep(0., 1., shape);
+
+    totalColor += ballColor.rgb * shape;
+    totalShape += shape;
+    totalOpacity += ballColor.a * shape;
+  }
+
+  totalColor /= max(totalShape, 1e-4);
+  totalOpacity /= max(totalShape, 1e-4);
+
+  float edge_width = fwidth(totalShape);
+  float finalShape = smoothstep(.4, .4 + edge_width, totalShape);
+
+  vec3 color = totalColor * finalShape;
+  float opacity = totalOpacity * finalShape;
+  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;
+  color = color + bgColor * (1. - opacity);
+  opacity = opacity + u_colorBack.a * (1. - opacity);
+
+  fragColor = vec4(color, opacity);
+}
+`;
+
+export { metaballsFragmentShader };

package/dist/components/effects/Metaballs/Metaballs.types.d.ts

@@ -0,0 +1,16 @@
+import type React from "react";
+export declare const METABALLS_MAX_COLORS = 8;
+export declare const METABALLS_MAX_COUNT = 20;
+export interface MetaballsProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Background CSS color. Default: 'var(--color-background)'. */
+    colorBack?: string;
+    /** Ball colors, cycled across balls, up to 8. Default: a 3-stop primary ramp. */
+    colors?: string[];
+    /** Number of balls, 1-20 (fractional values fade the last ball in). Default: 10. */
+    count?: number;
+    /** Ball size multiplier. Default: 0.6. */
+    size?: number;
+    /** Animation speed multiplier. Default: 1. */
+    speed?: number;
+    className?: string;
+}

package/dist/components/effects/Metaballs/Metaballs.types.js

@@ -0,0 +1,3 @@
+const METABALLS_MAX_COLORS = 8;
+
+export { METABALLS_MAX_COLORS };

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

@@ -0,0 +1,2 @@
+export { Metaballs } from "./Metaballs";
+export type { MetaballsProps } from "./Metaballs.types";

package/dist/components/effects/Neumorphic/InsetCircleButton.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+export interface InsetCircleButtonProps {
+    children: React.ReactNode;
+    size?: number;
+    className?: string;
+    classNameDisc?: string;
+    classNameHover?: string;
+    onClick?: () => void;
+}
+export declare function InsetCircleButton({ children, size, className, classNameDisc, classNameHover, onClick, }: InsetCircleButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/effects/Neumorphic/InsetCircleButton.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import 'react';
+
+function InsetCircleButton({ children, size = 44, className, classNameDisc, classNameHover, onClick, }) {
+    return (jsx("div", { className: cn("neu-circle-groove group shrink-0 cursor-pointer bg-neutral-200/80 dark:bg-neutral-900", className), style: { width: size, height: size }, onClick: onClick, children: jsxs(motion.div, { className: cn("neu-circle-disc bg-linear-to-br from-neutral-100 to-neutral-300 dark:from-neutral-700 dark:to-neutral-900", classNameDisc), whileHover: { scale: 1 }, whileTap: { scale: 0.975 }, transition: { type: "spring", stiffness: 200, damping: 20 }, children: [jsx("div", { className: cn("absolute inset-0 rounded-full bg-linear-to-br from-neutral-300 to-neutral-200 dark:from-neutral-900 dark:to-neutral-700 opacity-0 group-hover:opacity-100 transition-opacity duration-300", classNameHover) }), jsx("div", { className: "relative z-2", children: children })] }) }));
+}
+
+export { InsetCircleButton };

package/dist/components/effects/Neumorphic/InsetPill.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+export interface InsetPillProps {
+    children: React.ReactNode;
+    className?: string;
+    padding?: string;
+    onClick?: () => void;
+}
+export declare function InsetPill({ children, className, padding, onClick, }: InsetPillProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/effects/Neumorphic/InsetPill.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+
+function InsetPill({ children, className, padding = "10px 18px", onClick, }) {
+    return (jsx("div", { className: `neu-inset inline-flex items-center gap-2 cursor-pointer rounded-full bg-neutral-200/60 dark:bg-neutral-800/80 ${className !== null && className !== void 0 ? className : ""}`, style: { padding }, onClick: onClick, children: jsx("div", { className: "relative z-2 flex items-center gap-2", children: children }) }));
+}
+
+export { InsetPill };

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

@@ -0,0 +1,4 @@
+export { InsetCircleButton } from "./InsetCircleButton";
+export type { InsetCircleButtonProps } from "./InsetCircleButton";
+export { InsetPill } from "./InsetPill";
+export type { InsetPillProps } from "./InsetPill";

package/dist/components/effects/NoiseOverlay/NoiseOverlay.d.ts

@@ -25,4 +25,4 @@ import type { NoiseOverlayProps } from "./NoiseOverlay.types";
  * </div>
  * ```
  */
-export declare const NoiseOverlay: React.FC<NoiseOverlayProps>;
+export declare const NoiseOverlay: React.ForwardRefExoticComponent<NoiseOverlayProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/effects/NoiseOverlay/NoiseOverlay.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useId, useRef, useEffect } from 'react';
+import React__default, { useId, useRef, useEffect } from 'react';
 import { useReducedMotion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 
@@ -28,7 +29,7 @@ import { cn } from '../../../utils/cn.js';
  * </div>
  * ```
  */
-const NoiseOverlay = ({ opacity = 0.15, frequency = 0.65, octaves = 4, blendMode = "overlay", animated = false, className, style, ...props }) => {
+const NoiseOverlay = React__default.forwardRef(({ opacity = 0.15, frequency = 0.65, octaves = 4, blendMode = "overlay", animated = false, className, style, ...props }, ref) => {
     const filterId = useId();
     const shouldReduceMotion = useReducedMotion();
     const turbulenceRef = useRef(null);
@@ -50,12 +51,12 @@ const NoiseOverlay = ({ opacity = 0.15, frequency = 0.65, octaves = 4, blendMode
             clearInterval(intervalId);
         };
     }, [isAnimating]);
-    return (jsx("div", { className: cn("absolute inset-0 pointer-events-none", className), style: {
+    return (jsx("div", { ref: ref, className: cn("absolute inset-0 pointer-events-none", className), style: {
             mixBlendMode: blendMode,
             opacity,
             ...style,
         }, "aria-hidden": "true", ...props, children: jsxs("svg", { className: "absolute inset-0 w-full h-full", xmlns: "http://www.w3.org/2000/svg", preserveAspectRatio: "none", children: [jsx("filter", { id: filterId, children: jsx("feTurbulence", { ref: turbulenceRef, type: "fractalNoise", baseFrequency: frequency, numOctaves: octaves, stitchTiles: "stitch", seed: 0 }) }), jsx("rect", { width: "100%", height: "100%", filter: `url(#${filterId})` })] }) }));
-};
+});
 NoiseOverlay.displayName = "NoiseOverlay";
 
 export { NoiseOverlay };

package/dist/components/effects/Overlay/Overlay.js

@@ -1,11 +1,13 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useRef } from 'react';
+import React__default, { useRef, useCallback, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
-import { useOverlay } from '../../../hooks/useOverlay.js';
+import { useOverlay, lockScroll, unlockScroll } from '../../../hooks/useOverlay.js';
 import { useFocusTrap } from '../../../hooks/useFocusTrap.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
 import { overlayTheme, overlayPositionVariants } from './Overlay.theme.js';
 
 /**
@@ -81,14 +83,41 @@ const Overlay = React__default.forwardRef(({ isOpen, onClose, closeOnOverlayClic
     // Ref for focus trap container
     const focusTrapRef = useRef(null);
     useFocusTrap(focusTrapRef, enableFocusTrap && isOpen);
-    // Use overlay hook for behavior (escape key, scroll lock, click handling)
+    // Memoized ref callback to avoid recreation on every animation frame
+    const mergedRef = useCallback((node) => {
+        focusTrapRef.current = node;
+        if (typeof ref === "function")
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref]);
+    // Use overlay hook for behavior (escape key, click handling)
+    // Scroll lock is managed separately below so we can tie unlock to animation completion
     const { handleOverlayClick } = useOverlay({
         isOpen,
         onClose,
         closeOnEsc,
         closeOnOverlayClick,
-        enableScrollLock,
+        enableScrollLock: false, // managed below via lockScroll/unlockScroll
     });
+    // Lock scroll immediately on open; track via ref so we can unlock in onExitComplete
+    const hasLockedScroll = useRef(false);
+    useEffect(() => {
+        if (isOpen && enableScrollLock) {
+            lockScroll();
+            hasLockedScroll.current = true;
+        }
+        // No unlock here — onExitComplete handles it after the exit animation finishes
+    }, [isOpen, enableScrollLock]);
+    // Safety: unlock on unmount (e.g. parent unmounts while overlay is still open)
+    useEffect(() => {
+        return () => {
+            if (hasLockedScroll.current) {
+                unlockScroll();
+                hasLockedScroll.current = false;
+            }
+        };
+    }, []);
     // Merge custom animations with defaults
     const overlayAnimations = (animations === null || animations === void 0 ? void 0 : animations.overlay) || defaultOverlayAnimations;
     const contentAnimations = (animations === null || animations === void 0 ? void 0 : animations.content) || defaultContentAnimations;
@@ -97,18 +126,22 @@ const Overlay = React__default.forwardRef(({ isOpen, onClose, closeOnOverlayClic
     const finalContentAnimations = { ...contentAnimations };
     if (animationDuration) {
         if (animationDuration.enter && finalOverlayAnimations.animate) {
-            finalOverlayAnimations.animate.transition = {
-                ...finalOverlayAnimations.animate.transition,
+            const animate = finalOverlayAnimations.animate;
+            animate.transition = {
+                ...animate.transition,
                 duration: animationDuration.enter,
             };
         }
         if (animationDuration.exit && finalOverlayAnimations.exit) {
-            finalOverlayAnimations.exit.transition = {
-                ...finalOverlayAnimations.exit.transition,
+            const exit = finalOverlayAnimations.exit;
+            exit.transition = {
+                ...exit.transition,
                 duration: animationDuration.exit,
             };
         }
     }
+    // Detect dark mode reactively via a shared MutationObserver-backed hook (SSR-safe)
+    const isDarkMode = useDarkMode();
     // Determine portal target
     const target = portalTarget !== undefined
         ? portalTarget
@@ -119,23 +152,17 @@ const Overlay = React__default.forwardRef(({ isOpen, onClose, closeOnOverlayClic
     if (!target) {
         return null;
     }
-    // Detect dark mode from document
-    const isDarkMode = isClient &&
-        (document.documentElement.classList.contains("dark") ||
-            document.body.classList.contains("dark") ||
-            document.querySelector(".dark") !== null);
-    const content = (jsx(AnimatePresence, { mode: "wait", children: isOpen && (jsxs(motion.div, { className: cn(isDarkMode && "dark", overlayTheme.backdrop, overlayPositionVariants[position], overlayClassName), onClick: handleOverlayClick, variants: finalOverlayAnimations, initial: "initial", animate: "animate", exit: "exit", transition: instantTransition, children: [jsx("div", { className: overlayTheme.pattern, style: {
-                        backgroundImage: "url(/overlay-dots.svg)",
-                        backgroundRepeat: "repeat",
-                        backgroundSize: "540px 540px",
-                    } }), jsx(motion.div, { ref: (node) => {
-                        // Merge external ref and focus trap ref
-                        focusTrapRef.current = node;
-                        if (typeof ref === "function")
-                            ref(node);
-                        else if (ref)
-                            ref.current = node;
-                    }, className: cn(overlayTheme.content, contentClassName), style: contentStyle, variants: finalContentAnimations, initial: "initial", animate: "animate", exit: "exit", transition: instantTransition, onClick: (e) => e.stopPropagation(), ...(role ? { role } : {}), ...(ariaModal ? { "aria-modal": true } : {}), ...(ariaLabelledBy ? { "aria-labelledby": ariaLabelledBy } : {}), ...(ariaDescribedBy
+    const content = (jsx(AnimatePresence, { mode: "wait", onExitComplete: () => {
+            if (hasLockedScroll.current) {
+                unlockScroll();
+                hasLockedScroll.current = false;
+            }
+        }, children: isOpen && (jsxs(motion.div, { className: cn(isDarkMode && "dark", overlayTheme.backdrop, overlayPositionVariants[position], overlayClassName), onClick: handleOverlayClick, variants: finalOverlayAnimations, initial: "initial", animate: "animate", exit: "exit", transition: instantTransition, children: [jsx("div", { className: overlayTheme.pattern, style: {
+                        backgroundImage: "radial-gradient(circle, rgba(250,250,250,0.08) 1.5px, transparent 1.5px)",
+                        backgroundSize: "30px 30px",
+                        maskImage: "radial-gradient(ellipse at center, black 0%, transparent 70%)",
+                        WebkitMaskImage: "radial-gradient(ellipse at center, black 0%, transparent 70%)",
+                    } }), jsx(motion.div, { ref: mergedRef, className: cn(overlayTheme.content, contentClassName), style: contentStyle, variants: finalContentAnimations, initial: "initial", animate: "animate", exit: "exit", transition: instantTransition, onClick: (e) => e.stopPropagation(), ...(role ? { role } : {}), ...(ariaModal ? { "aria-modal": true } : {}), ...(ariaLabelledBy ? { "aria-labelledby": ariaLabelledBy } : {}), ...(ariaDescribedBy
                         ? { "aria-describedby": ariaDescribedBy }
                         : {}), children: children })] })) }));
     return createPortal(content, target);

package/dist/components/effects/Overlay/Overlay.theme.js

@@ -1,7 +1,6 @@
 const overlayTheme = {
     /** Full-screen backdrop with blur */
-    backdrop: "fixed inset-0 bg-[var(--overlay-bg)] z-50 ",
-    // backdrop-blur-[var(--overlay-blur)]
+    backdrop: "fixed inset-0 bg-[var(--overlay-bg)] z-50 backdrop-blur-[var(--overlay-blur)] ",
     /** Dots / pattern layer behind content */
     pattern: "absolute inset-0 w-full h-full z-0 pointer-events-none",
     /** Content wrapper (sits above pattern) */

package/dist/components/effects/PaperTexture/PaperTexture.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import type { PaperTextureProps } from "./PaperTexture.types";
+/**
+ * Paper-grain image filter — normal-maps a source image with a fiber/
+ * roughness texture and re-lights it, giving it a textured-paper look.
+ * WebGL2-powered; falls back to the plain source image (via
+ * `object-fit: cover`) when WebGL2 is unavailable.
+ */
+export declare const PaperTexture: React.FC<PaperTextureProps>;

package/dist/components/effects/PaperTexture/PaperTexture.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useState, useMemo, useRef, useCallback } from 'react';
+import { useIsClient } from '../../../hooks/useIsClient.js';
+import 'motion/react';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { cn } from '../../../utils/cn.js';
+import { ShaderCanvas } from '../shared/ShaderCanvas/ShaderCanvas.js';
+import { resolveShaderColor } from '../shared/resolveShaderColor.js';
+import { paperTextureFragmentShader } from './PaperTexture.shaders.js';
+
+const DEFAULT_COLOR_FRONT = "var(--color-text-primary)";
+const DEFAULT_COLOR_BACK = "var(--color-background)";
+function useWebgl2Supported() {
+    return useMemo(() => {
+        if (typeof document === "undefined")
+            return false;
+        try {
+            return !!document.createElement("canvas").getContext("webgl2");
+        }
+        catch (_a) {
+            return false;
+        }
+    }, []);
+}
+/**
+ * Paper-grain image filter — normal-maps a source image with a fiber/
+ * roughness texture and re-lights it, giving it a textured-paper look.
+ * WebGL2-powered; falls back to the plain source image (via
+ * `object-fit: cover`) when WebGL2 is unavailable.
+ */
+const PaperTexture = ({ image, colorFront = DEFAULT_COLOR_FRONT, colorBack = DEFAULT_COLOR_BACK, contrast = 0.5, roughness = 0.5, fiber = 0.5, fiberSize = 1, className, style, ...props }) => {
+    const isClient = useIsClient();
+    const isDark = useDarkMode();
+    const webglSupported = useWebgl2Supported();
+    const [imageAspectRatio, setImageAspectRatio] = useState(16 / 9);
+    const resolvedFront = useMemo(() => resolveShaderColor(colorFront), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [colorFront, isDark]);
+    const resolvedBack = useMemo(() => resolveShaderColor(colorBack), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [colorBack, isDark]);
+    const texturesRef = useRef({ u_image: image });
+    texturesRef.current.u_image = image;
+    const handleTextureLoad = useCallback((name, aspectRatio) => {
+        if (name === "u_image")
+            setImageAspectRatio(aspectRatio);
+    }, []);
+    const uniformsRef = useRef({});
+    uniformsRef.current.u_colorFront = resolvedFront;
+    uniformsRef.current.u_colorBack = resolvedBack;
+    uniformsRef.current.u_imageAspectRatio = imageAspectRatio;
+    uniformsRef.current.u_contrast = contrast;
+    uniformsRef.current.u_roughness = roughness;
+    uniformsRef.current.u_fiber = fiber;
+    uniformsRef.current.u_fiberSize = fiberSize;
+    const imageSrc = typeof image === "string" ? image : image.src;
+    return (jsx("div", { className: cn("absolute inset-0 overflow-hidden pointer-events-none select-none", className), style: style, "aria-hidden": "true", ...props, children: isClient && webglSupported ? (jsx(ShaderCanvas, { fragmentShader: paperTextureFragmentShader, uniformsRef: uniformsRef, texturesRef: texturesRef, onTextureLoad: handleTextureLoad })) : (jsx("img", { src: imageSrc, alt: "", className: "absolute inset-0 w-full h-full object-cover" })) }));
+};
+
+export { PaperTexture };