fancy-ui-svelte 0.4.1 → 0.6.0

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;
@@ -27,6 +30,13 @@
 		fluidColors?: string[];
 		colorIntensity?: number;
 		class?: string;
+		autoSplat?: boolean;
+		autoSplatInterval?: number;
+		interactive?: boolean;
+		pauseWhenHidden?: boolean;
+		splatOnMount?: boolean;
+		allowMultiple?: boolean;
+		contained?: boolean;
 	}
 
 	let {
@@ -48,6 +58,13 @@
 		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 {
@@ -956,6 +973,28 @@
 			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();
@@ -996,7 +1035,10 @@
 			return cachedFluidColorsScaled;
 		}
 
+		let isVisible = true;
+
 		function updateFrame() {
+			if (!isVisible) return;
 			const dt = calcDeltaTime();
 			if (resizeCanvas()) initFramebuffers();
 			updateColors(dt);
@@ -1247,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;
@@ -1360,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);
@@ -1400,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);
 			}
 		}
@@ -1410,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

@@ -22,6 +22,13 @@ interface Props {
     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

@@ -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,6 +41,31 @@ 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" } });
@@ -50,7 +78,6 @@ describe("FluidCursor", () => {
             expect(container.querySelector("canvas")).toBeInTheDocument();
         });
         it("renders without error when fluidColor and fluidColors are both provided (fluidColor takes priority)", () => {
-            // Both props accepted without throw — fluidColor priority is exercised at runtime
             const { container } = render(FluidCursor, {
                 props: { fluidColor: "#ff0000", fluidColors: ["#00ffcc", "#7700ff"] },
             });

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

@@ -1,2 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
-export { default as FluidCursorAdvanced } from "./FluidCursorAdvanced.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,2 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
-export { default as FluidCursorAdvanced } from "./FluidCursorAdvanced.svelte";
+/**
+ * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
+ */
+export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";

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

@@ -11,6 +11,7 @@ export * from "./border-beam/index.js";
 export * from "./glow-border/index.js";
 export * from "./marquee/index.js";
 export * from "./compare/index.js";
+export * from "./dock/index.js";
 export * from "./image-trail-cursor/index.js";
 export * from "./interactive-grid-pattern/index.js";
 export * from "./interactive-hover-button/index.js";
@@ -53,4 +54,7 @@ export * from "./tracing-beam/index.js";
 export * from "./displacement-text/index.js";
 export * from "./matrix-rain/index.js";
 export * from "./terminal-text/index.js";
+export * from "./noise-reveal/index.js";
+export * from "./line-reveal/index.js";
+export * from "./editorial-engine/index.js";
 export { registry, categories, categoryLabels, categoryDescriptions, getAllComponents, getComponent, getComponentsByStatus, getComponentsByCategory, getComponentsGroupedByCategory, getComponentsGroupedByStatus, searchComponents, getStats, hasComponent, getComponentCategory, } from "./registry.js";

package/dist/fancy-ui/index.js

@@ -16,6 +16,7 @@ export * from "./border-beam/index.js";
 export * from "./glow-border/index.js";
 export * from "./marquee/index.js";
 export * from "./compare/index.js";
+export * from "./dock/index.js";
 export * from "./image-trail-cursor/index.js";
 export * from "./interactive-grid-pattern/index.js";
 export * from "./interactive-hover-button/index.js";
@@ -58,6 +59,9 @@ export * from "./tracing-beam/index.js";
 export * from "./displacement-text/index.js";
 export * from "./matrix-rain/index.js";
 export * from "./terminal-text/index.js";
+export * from "./noise-reveal/index.js";
+export * from "./line-reveal/index.js";
+export * from "./editorial-engine/index.js";
 // =============================================================================
 // Registry
 // =============================================================================

package/dist/fancy-ui/line-reveal/LineReveal.svelte

@@ -0,0 +1,168 @@
+<script lang="ts" module>
+	/**
+	 * Props for LineReveal
+	 *
+	 * Reveals text line by line with a staggered slide-up animation.
+	 * Line breaks are computed with @chenglou/pretext (canvas text
+	 * measurement), so no DOM splitting or reflow measurement is needed.
+	 */
+	export interface LineRevealProps {
+		/** Text to reveal */
+		text: string;
+		/**
+		 * CSS font shorthand used for both measurement and rendering
+		 * (canvas `ctx.font` format, e.g. "600 32px Inter, sans-serif").
+		 * Prefer named families: `system-ui` can resolve differently between
+		 * canvas measurement and DOM rendering.
+		 */
+		font?: string;
+		/** Line height in pixels (defaults to 1.2 × font size) */
+		lineHeight?: number;
+		/** Delay between lines in seconds */
+		stagger?: number;
+		/** Animation duration per line in seconds */
+		duration?: number;
+		/** Initial delay before the first line in seconds */
+		delay?: number;
+		/** Animate only the first time the component enters the viewport */
+		once?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import { cn } from "../../utils.js";
+	import { onMount } from "svelte";
+	import {
+		prepareWithSegments,
+		layoutWithLines,
+		type PreparedTextWithSegments,
+	} from "@chenglou/pretext";
+
+	let {
+		text,
+		// Named families only: canvas and CSS can resolve `system-ui` to
+		// different fonts (notably on macOS), which skews measured widths.
+		font = '600 32px "Helvetica Neue", Helvetica, Arial, sans-serif',
+		lineHeight,
+		stagger = 0.08,
+		duration = 0.7,
+		delay = 0,
+		once = true,
+		class: className,
+	}: LineRevealProps = $props();
+
+	const fontSize = $derived(Number(/(\d+(?:\.\d+)?)px/.exec(font)?.[1] ?? 32));
+	const resolvedLineHeight = $derived(lineHeight ?? Math.round(fontSize * 1.2));
+
+	let containerRef: HTMLDivElement;
+	let containerWidth = $state(0);
+	let revealed = $state(false);
+	let prepared = $state<PreparedTextWithSegments | null>(null);
+
+	// Measurement requires a canvas context, so this only runs in the browser
+	// ($effect never runs during SSR). Web fonts must be loaded first or the
+	// canvas silently measures with the fallback font.
+	$effect(() => {
+		const currentText = text;
+		const currentFont = font;
+		let cancelled = false;
+
+		document.fonts
+			.load(currentFont)
+			.catch(() => {})
+			.then(() => {
+				if (!cancelled) {
+					prepared = prepareWithSegments(currentText, currentFont);
+				}
+			});
+
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	// Pure arithmetic on cached measurements — cheap to re-run on every resize
+	// (containerWidth is tracked by Svelte's bind:clientWidth ResizeObserver).
+	const layoutResult = $derived(
+		prepared && containerWidth > 0
+			? layoutWithLines(prepared, containerWidth, resolvedLineHeight)
+			: null
+	);
+
+	onMount(() => {
+		const observer = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting) {
+						revealed = true;
+						if (once) observer.disconnect();
+					} else if (!once) {
+						revealed = false;
+					}
+				}
+			},
+			{ threshold: 0.1 }
+		);
+
+		observer.observe(containerRef);
+
+		return () => observer.disconnect();
+	});
+</script>
+
+<div
+	bind:this={containerRef}
+	bind:clientWidth={containerWidth}
+	class={cn("relative w-full", className)}
+	style:font
+	style:line-height="{resolvedLineHeight}px"
+	style:height={layoutResult ? `${layoutResult.height}px` : undefined}
+>
+	<span class="sr-only">{text}</span>
+	{#if layoutResult}
+		{#each layoutResult.lines as line, i (i)}
+			<div class="line-mask" style:height="{resolvedLineHeight}px" aria-hidden="true">
+				<div
+					class="line"
+					class:revealed
+					style:transition-duration="{duration}s"
+					style:transition-delay="{delay + i * stagger}s"
+				>
+					{line.text}
+				</div>
+			</div>
+		{/each}
+	{:else}
+		<!-- SSR / pre-measure fallback: keeps text in the HTML and reserves space -->
+		<div style:visibility="hidden" aria-hidden="true">{text}</div>
+	{/if}
+</div>
+
+<style>
+	.line-mask {
+		overflow: hidden;
+		/* preserve exact spacing so rendered width matches pretext measurement */
+		white-space: pre;
+	}
+
+	.line {
+		opacity: 0;
+		transform: translateY(105%);
+		transition-property: transform, opacity;
+		transition-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+	}
+
+	.line.revealed {
+		opacity: 1;
+		transform: translateY(0);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.line {
+			transition-duration: 0.1s !important;
+			transition-delay: 0s !important;
+		}
+	}
+</style>

package/dist/fancy-ui/line-reveal/LineReveal.svelte.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Props for LineReveal
+ *
+ * Reveals text line by line with a staggered slide-up animation.
+ * Line breaks are computed with @chenglou/pretext (canvas text
+ * measurement), so no DOM splitting or reflow measurement is needed.
+ */
+export interface LineRevealProps {
+    /** Text to reveal */
+    text: string;
+    /**
+     * CSS font shorthand used for both measurement and rendering
+     * (canvas `ctx.font` format, e.g. "600 32px Inter, sans-serif").
+     * Prefer named families: `system-ui` can resolve differently between
+     * canvas measurement and DOM rendering.
+     */
+    font?: string;
+    /** Line height in pixels (defaults to 1.2 × font size) */
+    lineHeight?: number;
+    /** Delay between lines in seconds */
+    stagger?: number;
+    /** Animation duration per line in seconds */
+    duration?: number;
+    /** Initial delay before the first line in seconds */
+    delay?: number;
+    /** Animate only the first time the component enters the viewport */
+    once?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}
+declare const LineReveal: import("svelte").Component<LineRevealProps, {}, "">;
+type LineReveal = ReturnType<typeof LineReveal>;
+export default LineReveal;

package/dist/fancy-ui/line-reveal/README.md

@@ -0,0 +1,42 @@
+# LineReveal
+
+Reveals text line by line with a staggered slide-up animation.
+
+Unlike DOM-splitting approaches, line breaks are computed with
+[@chenglou/pretext](https://github.com/chenglou/pretext) — canvas-accurate text
+measurement in pure JS. Each computed line is rendered as its own masked
+element, so the per-line stagger works without measuring or mutating the DOM,
+and lines re-wrap instantly on container resize.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { LineReveal } from "$lib/fancy-ui/line-reveal";
+</script>
+
+<LineReveal
+	text="Text measurement and layout without touching the DOM."
+	font="700 40px Helvetica, Arial, sans-serif"
+/>
+```
+
+## Props
+
+| Prop         | Type      | Default                          | Description                                                  |
+| ------------ | --------- | -------------------------------- | ------------------------------------------------------------ |
+| `text`       | `string`  | — (required)                     | Text to reveal                                               |
+| `font`       | `string`  | `"600 32px \"Helvetica Neue\", Helvetica, Arial, sans-serif"` | CSS font shorthand, used for both measurement and rendering |
+| `lineHeight` | `number`  | `1.2 × font size`                | Line height in pixels                                        |
+| `stagger`    | `number`  | `0.08`                           | Delay between lines in seconds                               |
+| `duration`   | `number`  | `0.7`                            | Animation duration per line in seconds                       |
+| `delay`      | `number`  | `0`                              | Initial delay in seconds                                     |
+| `once`       | `boolean` | `true`                           | Animate only on first viewport entry                         |
+| `class`      | `string`  | —                                | Additional CSS classes                                       |
+
+## Notes
+
+- `font` must be a valid canvas `ctx.font` shorthand (weight, size in px, family).
+- Measurement happens client-side only (pretext needs a canvas); during SSR the
+  raw text is rendered hidden so content stays in the HTML.
+- Resizing the container re-wraps lines without replaying the animation.

package/dist/fancy-ui/line-reveal/index.d.ts

@@ -0,0 +1,2 @@
+export { default as LineReveal } from "./LineReveal.svelte";
+export type { LineRevealProps } from "./LineReveal.svelte";