fancy-ui-svelte 0.4.0 → 0.5.0

package/README.md

@@ -119,21 +119,35 @@ Beautiful animation and UI components for **Svelte 5**.
 **Install via npm:**
 
 ```bash
-npm install fancy-ui
+npm install fancy-ui-svelte
 ```
 
 Then import any component:
 
 ```ts
-import { Marquee, BorderBeam, Confetti } from 'fancy-ui';
+import { Marquee, BorderBeam, Confetti } from 'fancy-ui-svelte';
 ```
 
-To include Tailwind classes, add this to your app's CSS:
+Add the Tailwind integration to your app's CSS (e.g. `src/app.css`):
 
 ```css
-@import "fancy-ui/tailwind.css";
+@import "tailwindcss";
+@import "fancy-ui-svelte/tailwind.css";
 ```
 
+This single import tells Tailwind v4 to scan the library's components so all utility classes are generated automatically. No manual `@source` path needed.
+
+<details>
+<summary>Alternative: manual @source (without the CSS import)</summary>
+
+```css
+@import "tailwindcss";
+@source "../node_modules/fancy-ui-svelte/dist";
+```
+
+The path is relative to your CSS file location.
+</details>
+
 **Or browse and copy a component:**
 1. Find the component you need in the [live demo](https://fancy-ui.rama.app)
 2. Copy the source from `src/lib/fancy-ui/[component-name]/`

package/dist/fancy-ui/animated-beam/README.md

@@ -12,27 +12,6 @@ Creates animated SVG beams that connect two elements with smooth gradients and c
 - Reversible animation direction
 - Position offsets for fine-tuning
 
-## Implementation Notes
-
-### Vue → Svelte Conversions
-- `ref()` → `$state()`
-- `computed()` → `$derived()`
-- `watchEffect()` → `$effect()` (via `onMount`)
-- Template refs → `bind:this`
-- Props handling with destructuring defaults
-
-### Key Differences
-1. **Element References**: Svelte uses `bind:this` instead of Vue's `ref` template attribute
-2. **Lifecycle**: Setup logic moved to `onMount` with cleanup return
-3. **Derived Values**: Functions returning derived values (x1, x2, y1, y2) instead of computed refs
-4. **Conditional Rendering**: Used `{#if}` blocks to ensure refs are defined before rendering beams
-
-### Implementation Details
-- ResizeObserver for responsive path updates
-- SVG path calculation using quadratic Bezier curves (Q command)
-- Direction detection for vertical/horizontal beams
-- Unique gradient IDs to prevent conflicts with multiple instances
-
 ## Demo
 See `/demo/animated-beam` for usage examples.
 

package/dist/fancy-ui/confetti/Confetti.svelte

@@ -11,7 +11,7 @@
 	interface Props {
 		options?: ConfettiOptions;
 		globalOptions?: ConfettiGlobalOptions;
-		manualstart?: boolean;
+		manualStart?: boolean;
 		class?: string;
 		children?: Snippet;
 	}
@@ -19,7 +19,7 @@
 	let {
 		options = {},
 		globalOptions = {},
-		manualstart = false,
+		manualStart = false,
 		class: className = "",
 		children,
 	}: Props = $props();
@@ -39,7 +39,7 @@
 			resize: true,
 		});
 
-		if (!manualstart) {
+		if (!manualStart) {
 			fire();
 		}
 

package/dist/fancy-ui/confetti/Confetti.svelte.d.ts

@@ -3,7 +3,7 @@ import type { GlobalOptions as ConfettiGlobalOptions, Options as ConfettiOptions
 interface Props {
     options?: ConfettiOptions;
     globalOptions?: ConfettiGlobalOptions;
-    manualstart?: boolean;
+    manualStart?: boolean;
     class?: string;
     children?: Snippet;
 }

package/dist/fancy-ui/confetti/README.md

@@ -11,7 +11,7 @@ Canvas wrapper that creates a confetti instance.
 |------|------|---------|-------------|
 | `options` | `ConfettiOptions` | `{}` | Default confetti options |
 | `globalOptions` | `ConfettiGlobalOptions` | `{}` | Canvas creation options |
-| `manualstart` | `boolean` | `false` | Skip auto-fire on mount |
+| `manualStart` | `boolean` | `false` | Skip auto-fire on mount |
 | `class` | `string` | `''` | Canvas CSS classes |
 
 ### ConfettiButton

package/dist/fancy-ui/fluid-cursor/FluidCursor.svelte

@@ -2,6 +2,9 @@
 	import { cn } from "../../utils.js";
 	import { onMount } from "svelte";
 
+	// Module-level singleton registry
+	let activeInstance: (() => void) | null = null;
+
 	interface ColorRGB {
 		r: number;
 		g: number;
@@ -21,9 +24,19 @@
 		splatForce?: number;
 		shading?: boolean;
 		colorUpdateSpeed?: number;
-		backColor?: ColorRGB;
+		backColor?: ColorRGB | string;
 		transparent?: boolean;
+		fluidColor?: string;
+		fluidColors?: string[];
+		colorIntensity?: number;
 		class?: string;
+		autoSplat?: boolean;
+		autoSplatInterval?: number;
+		interactive?: boolean;
+		pauseWhenHidden?: boolean;
+		splatOnMount?: boolean;
+		allowMultiple?: boolean;
+		contained?: boolean;
 	}
 
 	let {
@@ -41,9 +54,39 @@
 		colorUpdateSpeed = 10,
 		backColor = { r: 0.5, g: 0, b: 0 },
 		transparent = true,
+		fluidColor,
+		fluidColors,
+		colorIntensity = 0.15,
 		class: className = "",
+		autoSplat = false,
+		autoSplatInterval = 1500,
+		interactive = true,
+		pauseWhenHidden = true,
+		splatOnMount = false,
+		allowMultiple = false,
+		contained = true,
 	}: Props = $props();
 
+	function hexToRgb(hex: string): ColorRGB {
+		const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+		if (!result) {
+			console.warn(
+				`[FluidCursor] Invalid hex color: "${hex}". Expected format: "#rrggbb". Falling back to white.`
+			);
+			return { r: 1, g: 1, b: 1 };
+		}
+		return {
+			r: parseInt(result[1], 16) / 255,
+			g: parseInt(result[2], 16) / 255,
+			b: parseInt(result[3], 16) / 255,
+		};
+	}
+
+	const clampedColorIntensity = Math.max(0, Math.min(1, colorIntensity));
+
+	const resolvedBackColor: ColorRGB =
+		typeof backColor === "string" ? hexToRgb(backColor) : backColor;
+
 	let canvasRef: HTMLCanvasElement;
 
 	onMount(() => {
@@ -94,7 +137,7 @@
 			SHADING: shading,
 			COLOR_UPDATE_SPEED: colorUpdateSpeed,
 			PAUSED: false,
-			BACK_COLOR: backColor,
+			BACK_COLOR: resolvedBackColor,
 			TRANSPARENT: transparent,
 		};
 
@@ -930,15 +973,72 @@
 			return Math.floor(input * pixelRatio);
 		}
 
+		let canvasRectCache: DOMRect | null = null;
+		function updateCanvasRectCache() {
+			if (contained && canvas) canvasRectCache = canvas.getBoundingClientRect();
+		}
+		if (contained) {
+			window.addEventListener("resize", updateCanvasRectCache, { passive: true });
+			window.addEventListener("scroll", updateCanvasRectCache, { passive: true });
+			updateCanvasRectCache();
+		}
+
+		function getCanvasPos(clientX: number, clientY: number): { x: number; y: number } {
+			if (contained) {
+				if (!canvasRectCache) updateCanvasRectCache();
+				const rect = canvasRectCache!;
+				return {
+					x: scaleByPixelRatio(clientX - rect.left),
+					y: scaleByPixelRatio(clientY - rect.top),
+				};
+			}
+			return { x: scaleByPixelRatio(clientX), y: scaleByPixelRatio(clientY) };
+		}
+
 		// Simulation Setup
 		updateKeywords();
 		initFramebuffers();
 
 		let lastUpdateTime = Date.now();
 		let colorUpdateTimer = 0.0;
+		let colorIndex = 0;
 		let animationFrameId: number;
 
+		// Cached pre-scaled colors to avoid re-parsing hex on every splat
+		let cachedFluidColorHex: string | undefined;
+		let cachedFluidColor: ColorRGB | null = null;
+		let cachedFluidColorsRef: string[] | undefined;
+		let cachedFluidColorsScaled: ColorRGB[] = [];
+
+		function getScaledColor(hex: string): ColorRGB {
+			const { r, g, b } = hexToRgb(hex);
+			return {
+				r: r * clampedColorIntensity,
+				g: g * clampedColorIntensity,
+				b: b * clampedColorIntensity,
+			};
+		}
+
+		function getCachedFluidColor(hex: string): ColorRGB {
+			if (cachedFluidColor === null || cachedFluidColorHex !== hex) {
+				cachedFluidColorHex = hex;
+				cachedFluidColor = getScaledColor(hex);
+			}
+			return cachedFluidColor;
+		}
+
+		function getCachedFluidColors(colors: string[]): ColorRGB[] {
+			if (cachedFluidColorsRef !== colors) {
+				cachedFluidColorsRef = colors;
+				cachedFluidColorsScaled = colors.map(getScaledColor);
+			}
+			return cachedFluidColorsScaled;
+		}
+
+		let isVisible = true;
+
 		function updateFrame() {
+			if (!isVisible) return;
 			const dt = calcDeltaTime();
 			if (resizeCanvas()) initFramebuffers();
 			updateColors(dt);
@@ -1189,6 +1289,36 @@
 			dye.swap();
 		}
 
+		function multipleSplats(steps: number) {
+			// Simulate a cursor sweep along a random arc — each step on its own frame
+			// so the velocity field has time to evolve between injections.
+			const angle = Math.random() * Math.PI * 2;
+			const cx = 0.25 + Math.random() * 0.5;
+			const cy = 0.25 + Math.random() * 0.5;
+			const arcSpan = Math.PI * (0.8 + Math.random() * 0.8);
+			let i = 0;
+
+			function step() {
+				if (i >= steps) return;
+				const t = i / Math.max(1, steps - 1);
+				const a = angle + t * arcSpan;
+				const r = 0.15 + 0.05 * Math.sin(t * Math.PI);
+				const x = cx + Math.cos(a) * r;
+				const y = cy + Math.sin(a) * r;
+				const color = generateColor();
+				splat(
+					x,
+					y,
+					-Math.sin(a) * config.SPLAT_FORCE * 0.5,
+					Math.cos(a) * config.SPLAT_FORCE * 0.5,
+					color
+				);
+				i++;
+				if (i < steps) requestAnimationFrame(step);
+			}
+			requestAnimationFrame(step);
+		}
+
 		function correctRadius(radius: number) {
 			const aspectRatio = canvas.width / canvas.height;
 			if (aspectRatio > 1) radius *= aspectRatio;
@@ -1232,10 +1362,19 @@
 		}
 
 		function generateColor(): ColorRGB {
+			if (fluidColor) {
+				return getCachedFluidColor(fluidColor);
+			}
+			if (fluidColors && fluidColors.length > 0) {
+				const colors = getCachedFluidColors(fluidColors);
+				const idx = colorIndex % colors.length;
+				colorIndex++;
+				return colors[idx];
+			}
 			const c = HSVtoRGB(Math.random(), 1.0, 1.0);
-			c.r *= 0.15;
-			c.g *= 0.15;
-			c.b *= 0.15;
+			c.r *= clampedColorIntensity;
+			c.g *= clampedColorIntensity;
+			c.b *= clampedColorIntensity;
 			return c;
 		}
 
@@ -1293,37 +1432,30 @@
 		// Event Listeners
 		function handleMouseDown(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
 			updatePointerDownData(pointer, -1, posX, posY);
 			clickSplat(pointer);
 		}
 
 		function handleFirstMouseMove(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
 			const color = generateColor();
-			updateFrame();
 			updatePointerMoveData(pointer, posX, posY, color);
 			document.body.removeEventListener("mousemove", handleFirstMouseMove);
 		}
 
 		function handleMouseMove(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
-			const color = pointer.color;
-			updatePointerMoveData(pointer, posX, posY, color);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
+			updatePointerMoveData(pointer, posX, posY, pointer.color);
 		}
 
 		function handleFirstTouchStart(e: TouchEvent) {
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
-				updateFrame();
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerDownData(pointer, touches[i].identifier, posX, posY);
 			}
 			document.body.removeEventListener("touchstart", handleFirstTouchStart);
@@ -1333,8 +1465,7 @@
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerDownData(pointer, touches[i].identifier, posX, posY);
 			}
 		}
@@ -1343,36 +1474,108 @@
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerMoveData(pointer, posX, posY, pointer.color);
 			}
 		}
 
 		// Add event listeners
-		window.addEventListener("mousedown", handleMouseDown);
-		document.body.addEventListener("mousemove", handleFirstMouseMove);
-		window.addEventListener("mousemove", handleMouseMove);
-		document.body.addEventListener("touchstart", handleFirstTouchStart);
-		window.addEventListener("touchstart", handleTouchStart, false);
-		window.addEventListener("touchmove", handleTouchMove, false);
+		if (interactive) {
+			window.addEventListener("mousedown", handleMouseDown);
+			document.body.addEventListener("mousemove", handleFirstMouseMove);
+			window.addEventListener("mousemove", handleMouseMove);
+			document.body.addEventListener("touchstart", handleFirstTouchStart);
+			window.addEventListener("touchstart", handleTouchStart, false);
+			window.addEventListener("touchmove", handleTouchMove, false);
+		}
+
+		// Pause animation when scrolled out of view
+		let observer: IntersectionObserver | null = null;
+		if (pauseWhenHidden) {
+			observer = new IntersectionObserver(
+				([entry]) => {
+					const wasVisible = isVisible;
+					isVisible = entry.isIntersecting;
+					if (isVisible && !wasVisible) {
+						lastUpdateTime = Date.now();
+						animationFrameId = requestAnimationFrame(updateFrame);
+					}
+				},
+				{ threshold: 0 }
+			);
+			observer.observe(canvas);
+		}
 
 		// Start animation
 		updateFrame();
+		if (splatOnMount) multipleSplats(Math.floor(Math.random() * 6) + 10);
+
+		// Auto-splat timer
+		let autoSplatTimer: ReturnType<typeof setInterval> | null = null;
+		if (autoSplat) {
+			autoSplatTimer = setInterval(() => {
+				const color = generateColor();
+				splat(
+					Math.random(),
+					Math.random(),
+					(Math.random() - 0.5) * 200,
+					(Math.random() - 0.5) * 200,
+					color
+				);
+			}, autoSplatInterval);
+		}
 
 		// Cleanup
-		return () => {
+		function cleanup() {
 			cancelAnimationFrame(animationFrameId);
-			window.removeEventListener("mousedown", handleMouseDown);
-			document.body.removeEventListener("mousemove", handleFirstMouseMove);
-			window.removeEventListener("mousemove", handleMouseMove);
-			document.body.removeEventListener("touchstart", handleFirstTouchStart);
-			window.removeEventListener("touchstart", handleTouchStart);
-			window.removeEventListener("touchmove", handleTouchMove);
-		};
+			if (observer) observer.disconnect();
+			if (autoSplatTimer) clearInterval(autoSplatTimer);
+			if (interactive) {
+				window.removeEventListener("mousedown", handleMouseDown);
+				document.body.removeEventListener("mousemove", handleFirstMouseMove);
+				window.removeEventListener("mousemove", handleMouseMove);
+				document.body.removeEventListener("touchstart", handleFirstTouchStart);
+				window.removeEventListener("touchstart", handleTouchStart);
+				window.removeEventListener("touchmove", handleTouchMove);
+			}
+			if (contained) {
+				window.removeEventListener("resize", updateCanvasRectCache);
+				window.removeEventListener("scroll", updateCanvasRectCache);
+			}
+		}
+
+		if (!allowMultiple) {
+			if (activeInstance) {
+				if (import.meta.env.DEV) {
+					console.warn(
+						"[FluidCursor] Destroying previous instance. Only one instance is allowed by default. Use `allowMultiple={true}` to opt out of singleton behavior."
+					);
+				}
+				activeInstance();
+			}
+			activeInstance = cleanup;
+			return () => {
+				cleanup();
+				if (activeInstance === cleanup) {
+					activeInstance = null;
+				}
+			};
+		}
+
+		return cleanup;
 	});
 </script>
 
-<div class={cn("pointer-events-none fixed top-0 left-0 z-50 size-full", className)}>
-	<canvas bind:this={canvasRef} id="fluid" class="block h-screen w-screen"></canvas>
+<div
+	class={cn(
+		contained
+			? "pointer-events-none absolute inset-0 h-full w-full"
+			: "pointer-events-none fixed top-0 left-0 z-50 size-full",
+		className
+	)}
+>
+	<canvas
+		bind:this={canvasRef}
+		class={contained ? "block h-full w-full" : "block h-screen w-screen"}
+	></canvas>
 </div>

package/dist/fancy-ui/fluid-cursor/FluidCursor.svelte.d.ts

@@ -16,9 +16,19 @@ interface Props {
     splatForce?: number;
     shading?: boolean;
     colorUpdateSpeed?: number;
-    backColor?: ColorRGB;
+    backColor?: ColorRGB | string;
     transparent?: boolean;
+    fluidColor?: string;
+    fluidColors?: string[];
+    colorIntensity?: number;
     class?: string;
+    autoSplat?: boolean;
+    autoSplatInterval?: number;
+    interactive?: boolean;
+    pauseWhenHidden?: boolean;
+    splatOnMount?: boolean;
+    allowMultiple?: boolean;
+    contained?: boolean;
 }
 declare const FluidCursor: import("svelte").Component<Props, {}, "">;
 type FluidCursor = ReturnType<typeof FluidCursor>;

package/dist/fancy-ui/fluid-cursor/FluidCursor.test.js

@@ -1,5 +1,5 @@
 import { render, cleanup } from "@testing-library/svelte";
-import { afterEach, describe, it, expect } from "vitest";
+import { afterEach, describe, it, expect, vi } from "vitest";
 import FluidCursor from "./FluidCursor.svelte";
 describe("FluidCursor", () => {
     afterEach(cleanup);
@@ -13,24 +13,27 @@ describe("FluidCursor", () => {
         const canvas = container.querySelector("canvas");
         expect(canvas).toBeInTheDocument();
     });
-    it('canvas has id="fluid"', () => {
-        const { container } = render(FluidCursor);
-        const canvas = container.querySelector("canvas#fluid");
-        expect(canvas).toBeInTheDocument();
-    });
     it("container has pointer-events-none class", () => {
         const { container } = render(FluidCursor);
         const div = container.firstElementChild;
         expect(div?.className).toContain("pointer-events-none");
     });
-    it("container has fixed positioning class", () => {
+    it("defaults to contained mode (absolute positioning)", () => {
         const { container } = render(FluidCursor);
         const div = container.firstElementChild;
-        expect(div?.className).toContain("fixed");
+        expect(div?.className).toContain("absolute");
+        expect(div?.className).toContain("inset-0");
     });
-    it("container has z-50 class", () => {
+    it("canvas fills container in contained mode", () => {
         const { container } = render(FluidCursor);
+        const canvas = container.querySelector("canvas");
+        expect(canvas?.className).toContain("h-full");
+        expect(canvas?.className).toContain("w-full");
+    });
+    it("uses fixed positioning when contained={false}", () => {
+        const { container } = render(FluidCursor, { props: { contained: false } });
         const div = container.firstElementChild;
+        expect(div?.className).toContain("fixed");
         expect(div?.className).toContain("z-50");
     });
     it("applies custom class names", () => {
@@ -38,4 +41,61 @@ describe("FluidCursor", () => {
         const div = container.firstElementChild;
         expect(div?.className).toContain("my-fluid");
     });
+    describe("interaction props", () => {
+        it("interactive={false} does not register mouse event listeners", () => {
+            const addSpy = vi.spyOn(window, "addEventListener");
+            render(FluidCursor, { props: { interactive: false } });
+            const mousedownCalls = addSpy.mock.calls.filter(([event]) => event === "mousedown");
+            expect(mousedownCalls).toHaveLength(0);
+            const mousemoveCalls = addSpy.mock.calls.filter(([event]) => event === "mousemove");
+            expect(mousemoveCalls).toHaveLength(0);
+            addSpy.mockRestore();
+        });
+        it("mounts without error with autoSplat={true} and splatOnMount={true}", () => {
+            const { container } = render(FluidCursor, {
+                props: { autoSplat: true, splatOnMount: true },
+            });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("pauseWhenHidden={false} does not instantiate IntersectionObserver", () => {
+            const observeSpy = vi.fn();
+            const mockObserver = vi.fn(() => ({ observe: observeSpy, disconnect: vi.fn() }));
+            vi.stubGlobal("IntersectionObserver", mockObserver);
+            render(FluidCursor, { props: { pauseWhenHidden: false } });
+            expect(mockObserver).not.toHaveBeenCalled();
+            vi.unstubAllGlobals();
+        });
+    });
+    describe("color props", () => {
+        it("renders without error when fluidColor is provided", () => {
+            const { container } = render(FluidCursor, { props: { fluidColor: "#00ffcc" } });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("renders without error when fluidColors is provided", () => {
+            const { container } = render(FluidCursor, {
+                props: { fluidColors: ["#ff0080", "#00ffcc", "#7700ff"] },
+            });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("renders without error when fluidColor and fluidColors are both provided (fluidColor takes priority)", () => {
+            const { container } = render(FluidCursor, {
+                props: { fluidColor: "#ff0000", fluidColors: ["#00ffcc", "#7700ff"] },
+            });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("renders without error when backColor is a hex string", () => {
+            const { container } = render(FluidCursor, { props: { backColor: "#1a1a2e" } });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("warns and falls back when an invalid hex string is passed to backColor", () => {
+            const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+            render(FluidCursor, { props: { backColor: "not-a-color" } });
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining("[FluidCursor] Invalid hex color"));
+            warn.mockRestore();
+        });
+        it("renders without error when colorIntensity is out of [0,1] range (clamped internally)", () => {
+            const { container } = render(FluidCursor, { props: { colorIntensity: 5 } });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+    });
 });

package/dist/fancy-ui/fluid-cursor/README.md

@@ -9,6 +9,7 @@ A WebGL-based fluid simulation that follows the cursor, creating beautiful flowi
 - Configurable simulation parameters
 - Transparent background support
 - Automatic canvas resizing
+- Controllable fluid colors via hex strings (fixed color, palette cycling, or random)
 
 ## Implementation Notes
 
@@ -27,6 +28,30 @@ The component implements a full Navier-Stokes fluid simulation with:
 - Advection for both velocity and dye
 - Gradient subtraction for incompressible flow
 
+## Color Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `fluidColor` | `string` (hex) | — | Fixed fluid color. Disables random cycling. |
+| `fluidColors` | `string[]` (hex) | — | Palette to cycle through on each splat. |
+| `colorIntensity` | `number` | `0.15` | Intensity multiplier applied to fluid colors (0–1). |
+| `backColor` | `{ r, g, b }` or `string` (hex) | `{ r: 0.5, g: 0, b: 0 }` | Background color — accepts RGB object or hex string. |
+
+**Priority**: `fluidColor` > `fluidColors` > random HSV
+
+### Examples
+
+```svelte
+<!-- Fixed teal fluid -->
+<FluidCursor fluidColor="#00ffcc" />
+
+<!-- Cycling palette -->
+<FluidCursor fluidColors={["#ff0080", "#00ffcc", "#7700ff"]} colorIntensity={0.3} />
+
+<!-- Hex background -->
+<FluidCursor backColor="#1a1a2e" />
+```
+
 ### Event Handling
 
 - Window-level mouse/touch events for full-screen tracking

package/dist/fancy-ui/fluid-cursor/index.d.ts

@@ -1 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
+/**
+ * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
+ */
+export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";

package/dist/fancy-ui/fluid-cursor/index.js

@@ -1 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
+/**
+ * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
+ */
+export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";