fancy-ui-svelte 0.7.0 → 0.9.0

package/dist/fancy-ui/liquid-text/LiquidText.svelte.d.ts

@@ -0,0 +1,37 @@
+export interface LiquidTextProps {
+    /** Text rendered into the fluid texture (or as static fallback text). */
+    text?: string;
+    /** CSS font-family. Empty string resolves to getComputedStyle(host).fontFamily. */
+    font?: string;
+    /** Font size in px. 0 auto-fits the text to the container's width. */
+    fontSize?: number;
+    /** CSS font-weight for the rasterized/fallback text. */
+    fontWeight?: number | string;
+    /** Text color used in light mode. */
+    lightColor?: string;
+    /** Text color used in dark mode. */
+    darkColor?: string;
+    /** Additional CSS classes applied to the root element. */
+    class?: string;
+    /** Geometric UV warp gain — how far the fluid velocity displaces the text's UVs. */
+    strength?: number;
+    /** Splat radius in screen pixels around the pointer. */
+    radius?: number;
+    /** Multiplier from mouse-delta-per-frame to splat force. */
+    forceGain?: number;
+    /** Per-frame velocity decay factor (relax-back rate for the smear). */
+    dissipation?: number;
+    /** Viscous diffusion strength (Jacobi iteration, 8 iters). */
+    viscosity?: number;
+    /** Chromatic offset = warp amount x this ratio. */
+    chromaticRatio?: number;
+    /** If window.innerWidth <= staticBelow at mount, render static DOM text instead. */
+    staticBelow?: number;
+    /** Whether the fluid sim reacts to pointer movement. */
+    interactive?: boolean;
+    /** Pause the render loop via visibilitychange when the tab/page is hidden. */
+    pauseWhenHidden?: boolean;
+}
+declare const LiquidText: import("svelte").Component<LiquidTextProps, {}, "">;
+type LiquidText = ReturnType<typeof LiquidText>;
+export default LiquidText;

package/dist/fancy-ui/liquid-text/LiquidText.test.d.ts

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

package/dist/fancy-ui/liquid-text/LiquidText.test.js

@@ -0,0 +1,219 @@
+import { render, screen, cleanup } from "@testing-library/svelte";
+import { afterEach, describe, it, expect, vi } from "vitest";
+import LiquidText from "./LiquidText.svelte";
+/**
+ * Ambient test environment (see src/test-setup.ts) already stubs:
+ *   - HTMLCanvasElement.prototype.getContext -> null   (WebGL "unavailable")
+ *   - window.matchMedia                       -> { matches: false, ... }
+ *   - ResizeObserver / IntersectionObserver    -> no-op classes
+ *
+ * Per the frozen LiquidText contract, "no WebGL" and "no reduced-motion
+ * preference" both drive the component into its DOM-fallback path. Tests
+ * below that specifically target the fallback/no-WebGL/reduced-motion
+ * behavior re-assert these overrides explicitly (mirroring the ambient
+ * default) so intent is self-documenting and independent of test-setup.ts.
+ */
+describe("LiquidText", () => {
+    afterEach(cleanup);
+    describe("accessible text node", () => {
+        it("renders the text prop as a real text node in the DOM", () => {
+            render(LiquidText, { props: { text: "Hello Liquid" } });
+            const textNode = screen.getByText("Hello Liquid");
+            expect(textNode).toBeInTheDocument();
+            // The contract only requires the *canvas* to be aria-hidden; the
+            // real text node itself must stay in the accessibility tree,
+            // whether it is the sr-only span (canvas active) or the visible
+            // fallback text.
+            expect(textNode.getAttribute("aria-hidden")).not.toBe("true");
+        });
+        it('falls back to the default text "Liquid" when no text prop is passed', () => {
+            render(LiquidText);
+            expect(screen.getByText("Liquid")).toBeInTheDocument();
+        });
+        it("marks the canvas aria-hidden when a canvas is rendered", () => {
+            const { container } = render(LiquidText, { props: { text: "Canvas Check" } });
+            const canvas = container.querySelector("canvas");
+            // The contract does not pin down whether <canvas> is always present
+            // in the markup or only mounted on the interactive/WebGL path, so
+            // this only asserts when one is actually found.
+            if (canvas) {
+                expect(canvas.getAttribute("aria-hidden")).toBe("true");
+            }
+        });
+    });
+    describe("WebGL unavailable fallback", () => {
+        it("renders visible styled fallback text, starts no rAF render loop, and logs no console errors", () => {
+            const originalGetContext = HTMLCanvasElement.prototype.getContext;
+            HTMLCanvasElement.prototype.getContext = (() => null);
+            const rafSpy = vi.spyOn(window, "requestAnimationFrame");
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            render(LiquidText, {
+                props: {
+                    text: "No WebGL",
+                    font: "Georgia, serif",
+                    fontSize: 48,
+                    fontWeight: 600,
+                    lightColor: "#123456",
+                },
+            });
+            const textNode = screen.getByText("No WebGL");
+            expect(textNode).toBeInTheDocument();
+            // Per contract: "visible styled text in fallback modes", as opposed
+            // to the sr-only span used when the canvas is actively driven. It
+            // must actually carry the prop-driven font/size/color styling, not
+            // just be present and unstyled.
+            expect(textNode.className).not.toContain("sr-only");
+            expect(textNode.style.fontFamily).toBe("Georgia, serif");
+            expect(textNode.style.fontSize).toBe("48px");
+            expect(textNode.style.fontWeight).toBe("600");
+            expect(textNode.style.color).toBe("rgb(18, 52, 86)");
+            expect(rafSpy).not.toHaveBeenCalled();
+            expect(errorSpy).not.toHaveBeenCalled();
+            rafSpy.mockRestore();
+            errorSpy.mockRestore();
+            HTMLCanvasElement.prototype.getContext = originalGetContext;
+        });
+    });
+    describe("prefers-reduced-motion fallback", () => {
+        it("renders static fallback text and starts no rAF render loop when reduced motion is preferred", () => {
+            const originalMatchMedia = window.matchMedia;
+            Object.defineProperty(window, "matchMedia", {
+                writable: true,
+                configurable: true,
+                value: (query) => ({
+                    matches: query.includes("prefers-reduced-motion"),
+                    media: query,
+                    onchange: null,
+                    addEventListener: () => { },
+                    removeEventListener: () => { },
+                    dispatchEvent: () => false,
+                    addListener: () => { },
+                    removeListener: () => { },
+                }),
+            });
+            const rafSpy = vi.spyOn(window, "requestAnimationFrame");
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            render(LiquidText, {
+                props: {
+                    text: "Reduced Motion",
+                    font: "Georgia, serif",
+                    fontSize: 32,
+                    fontWeight: 500,
+                    lightColor: "#654321",
+                },
+            });
+            const textNode = screen.getByText("Reduced Motion");
+            expect(textNode).toBeInTheDocument();
+            expect(textNode.className).not.toContain("sr-only");
+            // Same requirement as the no-WebGL fallback: styled per the props,
+            // not just present.
+            expect(textNode.style.fontFamily).toBe("Georgia, serif");
+            expect(textNode.style.fontSize).toBe("32px");
+            expect(textNode.style.fontWeight).toBe("500");
+            expect(textNode.style.color).toBe("rgb(101, 67, 33)");
+            expect(rafSpy).not.toHaveBeenCalled();
+            expect(errorSpy).not.toHaveBeenCalled();
+            rafSpy.mockRestore();
+            errorSpy.mockRestore();
+            Object.defineProperty(window, "matchMedia", {
+                writable: true,
+                configurable: true,
+                value: originalMatchMedia,
+            });
+        });
+    });
+    describe("cleanup on repeated mount/unmount", () => {
+        it("leaves window/document/body listener counts balanced and no dangling rAF after 5 mount/unmount cycles", () => {
+            const targets = [window, document, document.body];
+            const addSpies = targets.map((t) => vi.spyOn(t, "addEventListener"));
+            const removeSpies = targets.map((t) => vi.spyOn(t, "removeEventListener"));
+            let nextRafId = 1;
+            const pendingRafIds = new Set();
+            const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockImplementation(() => {
+                const id = nextRafId++;
+                pendingRafIds.add(id);
+                return id;
+            });
+            const cafSpy = vi
+                .spyOn(window, "cancelAnimationFrame")
+                .mockImplementation((id) => {
+                pendingRafIds.delete(id);
+            });
+            for (let i = 0; i < 5; i++) {
+                const { unmount } = render(LiquidText, { props: { text: `pass-${i}` } });
+                unmount();
+            }
+            // Per-event-name balance on each target: every addEventListener("x", …)
+            // must be matched by a removeEventListener("x", …) across the 5
+            // mount/unmount cycles. Checking per event name (not just raw totals)
+            // catches leaks that would otherwise cancel out coincidentally.
+            targets.forEach((_, i) => {
+                const counts = new Map();
+                for (const call of addSpies[i].mock.calls) {
+                    const name = call[0];
+                    counts.set(name, (counts.get(name) ?? 0) + 1);
+                }
+                for (const call of removeSpies[i].mock.calls) {
+                    const name = call[0];
+                    counts.set(name, (counts.get(name) ?? 0) - 1);
+                }
+                for (const [eventName, balance] of counts) {
+                    expect(balance, `"${eventName}" listener leak on target #${i}`).toBe(0);
+                }
+            });
+            expect(pendingRafIds.size).toBe(0);
+            addSpies.forEach((s) => s.mockRestore());
+            removeSpies.forEach((s) => s.mockRestore());
+            rafSpy.mockRestore();
+            cafSpy.mockRestore();
+        });
+    });
+    describe("class prop", () => {
+        it("applies the class prop to the root element", () => {
+            const { container } = render(LiquidText, { props: { class: "my-liquid-class" } });
+            const root = container.firstElementChild;
+            expect(root.className).toContain("my-liquid-class");
+        });
+        it("still renders a root element with the default empty class", () => {
+            const { container } = render(LiquidText);
+            expect(container.firstElementChild).toBeInTheDocument();
+        });
+    });
+    describe("prop defaults and full prop surface (smoke)", () => {
+        it("mounts without error using only defaults", () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const { container } = render(LiquidText);
+            expect(container.firstElementChild).toBeInTheDocument();
+            expect(screen.getByText("Liquid")).toBeInTheDocument();
+            expect(errorSpy).not.toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+        it("mounts without error with every documented prop explicitly set", () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const { container } = render(LiquidText, {
+                props: {
+                    text: "Smoke Test",
+                    font: "Arial, sans-serif",
+                    fontSize: 96,
+                    fontWeight: 800,
+                    lightColor: "#111111",
+                    darkColor: "#eeeeee",
+                    class: "smoke-root",
+                    strength: 0.75,
+                    radius: 220,
+                    forceGain: 24,
+                    dissipation: 0.95,
+                    viscosity: 6,
+                    chromaticRatio: 0.35,
+                    staticBelow: 768,
+                    interactive: false,
+                    pauseWhenHidden: false,
+                },
+            });
+            expect(container.firstElementChild).toBeInTheDocument();
+            expect(screen.getByText("Smoke Test")).toBeInTheDocument();
+            expect(errorSpy).not.toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+    });
+});

package/dist/fancy-ui/liquid-text/README.md

@@ -0,0 +1,139 @@
+# LiquidText
+
+Large display text that liquefies under the cursor: a raw-WebGL fluid velocity
+field displaces the text's UVs along the pointer's trail, with RGB chromatic
+fringing on the warped edges, then relaxes back to rest as the fluid decays.
+
+## Features
+
+- Raw WebGL2 (WebGL1 fallback) fluid simulation — no Three.js dependency
+- Any string rendered through the sim: text is rasterized to a texture via
+  Canvas2D (`fillText`), not a pre-baked image
+- Mouse-velocity-driven splats: faster cursor movement = stronger smear
+- Chromatic aberration on displaced edges (3-tap R/G/B sampling)
+- Self-relaxing: velocity field decays every frame, so the smear resolves on
+  its own roughly a second after the cursor moves away
+- Auto-fit font size to the container width when `fontSize` is unset
+- Graceful fallbacks: `prefers-reduced-motion`, no WebGL, and small viewports
+  (`staticBelow`) all render plain styled static text instead of the sim
+- Accessible by construction: a real text node is always present in the DOM;
+  only the `<canvas>` is `aria-hidden`
+- Single `requestAnimationFrame` loop, paused via `visibilitychange` when the
+  tab is hidden (`pauseWhenHidden`)
+- Exhaustive cleanup on unmount: cancels the rAF loop, removes every
+  listener, disconnects the `ResizeObserver`, and calls `WEBGL_lose_context`
+
+## Usage
+
+```svelte
+<script>
+	import { LiquidText } from "fancy-ui-svelte";
+</script>
+
+<LiquidText text="Liquid" class="text-7xl font-bold" />
+```
+
+```svelte
+<!-- Tuned for a subtler, slower-decaying smear -->
+<LiquidText
+	text="Rama Herbin"
+	font="Bricolage Grotesque, sans-serif"
+	fontWeight={700}
+	strength={0.35}
+	radius={120}
+	dissipation={0.985}
+	lightColor="#0a0a0a"
+	darkColor="#fafafa"
+/>
+```
+
+```svelte
+<!-- Force the static DOM fallback (e.g. inside a `prefers-reduced-motion`
+     conscious layout, or below a custom breakpoint) -->
+<LiquidText text="Liquid" interactive={false} staticBelow={1280} />
+```
+
+## Props
+
+| Prop             | Type                 | Default     | Description                                                                          |
+| ---------------- | -------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `text`           | `string`             | `"Liquid"`  | The text rendered into the fluid texture (or as static fallback text).                 |
+| `font`           | `string`             | `""`        | CSS font-family for the text. Empty string resolves to `getComputedStyle(host).fontFamily`. |
+| `fontSize`       | `number`             | `0`         | Font size in px. `0` auto-fits the text to the container's width.                     |
+| `fontWeight`     | `number \| string`   | `700`       | CSS font-weight for the rasterized/fallback text.                                     |
+| `lightColor`     | `string`             | `"#000000"` | Text color used in light mode.                                                        |
+| `darkColor`      | `string`             | `"#ffffff"` | Text color used in dark mode.                                                          |
+| `class`          | `string`             | `""`        | Additional class names applied to the root element.                                  |
+| `strength`       | `number`             | `0.5`       | Geometric UV warp gain — how far the fluid velocity displaces the text's UVs.         |
+| `radius`         | `number`             | `160`       | Splat radius in screen pixels around the pointer.                                    |
+| `forceGain`      | `number`             | `17`        | Multiplier from mouse-delta-per-frame to splat force.                                 |
+| `dissipation`    | `number`             | `0.98`      | Per-frame velocity decay factor (relax-back rate for the smear).                      |
+| `viscosity`      | `number`             | `4`         | Viscous diffusion strength (Jacobi iteration, 8 iters).                               |
+| `chromaticRatio` | `number`             | `0.2`       | Chromatic offset = warp amount × this ratio.                                         |
+| `staticBelow`    | `number`             | `1024`      | If `window.innerWidth <= staticBelow` at mount, render static DOM text instead.       |
+| `interactive`    | `boolean`            | `true`      | Whether the fluid sim reacts to pointer movement.                                     |
+| `pauseWhenHidden`| `boolean`            | `true`      | Pause the render loop via `visibilitychange` when the tab/page is hidden.             |
+
+## Behavior contract
+
+- A real text node is **always** in the DOM: a `sr-only` span while the
+  canvas is actively driven, or visible styled text in any fallback mode.
+- The `<canvas>` is always `aria-hidden="true"` — it is a visual effect
+  layer, not content.
+- The component falls back to plain styled DOM text (no WebGL sim, no rAF
+  loop) when any of these are true at mount: `prefers-reduced-motion` is
+  preferred, WebGL is unavailable, or `window.innerWidth <= staticBelow`.
+- Root markup shape: `<div class={...}>` wrapping the canvas and the text
+  node.
+
+## Implementation notes
+
+### Fluid simulation
+
+- Runs the velocity solve at **0.25× the canvas resolution** to keep the
+  per-frame cost low for a text-sized effect (this doesn't need dye-buffer
+  resolution the way a full-screen cursor effect does).
+- Pipeline per frame: self-advection with `dissipation` decay → pointer-velocity
+  splat (screen-px falloff `(1 - dist/radius)² × 1.5`, force ∝ mouse delta ×
+  `forceGain`) → viscous diffusion (Jacobi, `viscosity`, 8 iterations) →
+  divergence → pressure solve (Jacobi, 16 iterations) → gradient
+  subtraction/projection. Vorticity confinement is intentionally left out —
+  it isn't part of the reference behavior being reproduced and would add
+  cost without visible benefit at this scale. `dt` is fixed rather than
+  measured from real frame time, so the decay rate stays predictable
+  regardless of frame rate.
+- Text is rasterized once per (text, font, fontSize, fontWeight) combination
+  via Canvas2D `fillText` into a texture, and re-rasterized on `ResizeObserver`
+  changes that affect layout (e.g. auto-fit font size).
+
+### Chromatic sampling
+
+- The fragment shader reads the velocity field at the screen UV, derives a
+  geometric warp (`velocity * strength`) and a chromatic offset
+  (`warp * chromaticRatio`), then does 3 independent texture taps: red at
+  `uv - offset`, green at `uv`, blue at `uv + offset`. The result is a
+  visible RGB fringe exactly where the text is being smeared, which
+  disappears as the velocity field dissipates.
+
+### Fallbacks
+
+- `prefers-reduced-motion: reduce` and "no WebGL context available" both
+  short-circuit straight to the static DOM text path — no canvas sim is
+  initialized, no rAF loop starts.
+- `staticBelow` is checked once against `window.innerWidth` at mount (not
+  reactively re-checked on resize) — crossing the breakpoint after mount
+  does not retroactively swap modes.
+- All three fallback conditions render the same static markup: visible,
+  normally-styled text using `lightColor`/`darkColor` per color scheme.
+
+### Cleanup
+
+- A single `requestAnimationFrame` loop drives the sim; it is paused (not
+  cancelled) on `document.visibilitychange` when `pauseWhenHidden` is true,
+  and resumed when the tab becomes visible again.
+- On unmount: cancels the pending rAF, removes every `window`/`document`
+  listener the component registered, disconnects the `ResizeObserver`, and
+  explicitly calls the `WEBGL_lose_context` extension's `loseContext()` to
+  release GPU resources deterministically rather than waiting on GC.
+- Verified safe under repeated mount/unmount (no leaked listeners, no
+  dangling animation frames) — see `LiquidText.test.ts`.

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

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

package/dist/fancy-ui/liquid-text/index.js

@@ -0,0 +1 @@
+export { default as LiquidText } from "./LiquidText.svelte";

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

@@ -0,0 +1,57 @@
+# Marquee
+
+An infinite scrolling row (or column) of content, built by rendering multiple copies of its children side by side and animating the whole track by `-100% - gap` on a seamless loop — no JS-measured widths, no `requestAnimationFrame`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { Marquee, ReviewCard } from "fancy-ui-svelte";
+
+	const reviews = [
+		{ name: "Jack", username: "@jack", body: "Amazing.", img: "https://avatar.vercel.sh/jack" },
+	];
+</script>
+
+<Marquee pauseOnHover class="[--duration:20s]">
+	{#each reviews as review}
+		<ReviewCard {...review} />
+	{/each}
+</Marquee>
+```
+
+Two rows scrolling in opposite directions (a common pattern) are just two `<Marquee>`s, one with `reverse`:
+
+```svelte
+<Marquee pauseOnHover>
+	{#each firstRow as r}
+		<ReviewCard {...r} />
+	{/each}
+</Marquee>
+<Marquee reverse pauseOnHover>
+	{#each secondRow as r}
+		<ReviewCard {...r} />
+	{/each}
+</Marquee>
+```
+
+## Props
+
+| Prop           | Type      | Default | Description                                  |
+| -------------- | --------- | ------- | -------------------------------------------- |
+| `reverse`      | `boolean` | `false` | Reverse the scroll direction                 |
+| `pauseOnHover` | `boolean` | `false` | Pause the animation on hover                 |
+| `vertical`     | `boolean` | `false` | Scroll vertically instead of horizontally    |
+| `repeat`       | `number`  | `4`     | Number of times to repeat the children track |
+| `class`        | `string`  | —       | Additional CSS classes                       |
+
+Children are the content to repeat and scroll.
+
+`ReviewCard` is also exported as a ready-made card for testimonial-style marquees, taking `img`, `name`, `username`, and `body` props — its own prop type isn't re-exported as a named type, so consumers writing their own card don't need to match its shape exactly.
+
+## Implementation notes
+
+- Speed and gap are CSS custom properties (`--duration: 40s`, `--gap: 1rem` by default) set on the root and overridable per-instance via `class="[--duration:20s]"` — there's no `speed`/`gap` prop.
+- The seamless loop works because `repeat` renders that many identical copies of `children` in a row and animates the whole flex track by exactly `-100% - var(--gap)` (one child-set width) — too low a `repeat` on a narrow set of children can leave a visible gap on wide viewports.
+- `pauseOnHover` pauses via `group-hover:[animation-play-state:paused]` on the whole marquee group, not per-item.
+- No `prefers-reduced-motion` handling — the scroll animation runs continuously regardless of user preference.

package/dist/fancy-ui/matrix-rain/MatrixRain.test.d.ts

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

package/dist/fancy-ui/matrix-rain/MatrixRain.test.js

@@ -0,0 +1,30 @@
+import { render, cleanup } from "@testing-library/svelte";
+import { afterEach, describe, it, expect } from "vitest";
+import MatrixRain from "./MatrixRain.svelte";
+describe("MatrixRain", () => {
+    afterEach(cleanup);
+    it("renders a canvas element", () => {
+        const { container } = render(MatrixRain);
+        expect(container.querySelector("canvas")).toBeTruthy();
+    });
+    it("applies the base fill/background classes", () => {
+        const { container } = render(MatrixRain);
+        const canvas = container.querySelector("canvas");
+        expect(canvas.className).toContain("block");
+        expect(canvas.className).toContain("h-full");
+        expect(canvas.className).toContain("w-full");
+        expect(canvas.className).toContain("bg-black");
+    });
+    it("applies custom class names alongside the base classes", () => {
+        const { container } = render(MatrixRain, { props: { class: "my-rain" } });
+        const canvas = container.querySelector("canvas");
+        expect(canvas.className).toContain("my-rain");
+        expect(canvas.className).toContain("block");
+    });
+    it("mounts and unmounts without throwing when getContext('2d') is unavailable (jsdom has no canvas backend)", () => {
+        const { unmount } = render(MatrixRain, {
+            props: { color: "#ff00ff", speed: 2, density: 0.5, glyphSize: 20, fadeOpacity: 0.1 },
+        });
+        expect(() => unmount()).not.toThrow();
+    });
+});

package/dist/fancy-ui/matrix-rain/README.md

@@ -0,0 +1,42 @@
+# MatrixRain
+
+A Canvas2D "digital rain" background: columns of falling glyphs with a bright leading character and a dimmer trailing one, faded by repeatedly painting a low-opacity black rectangle over the previous frame instead of clearing it.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { MatrixRain } from "fancy-ui-svelte";
+</script>
+
+<div class="relative h-[400px] w-full">
+	<MatrixRain />
+</div>
+```
+
+```svelte
+<!-- Custom color, denser and faster -->
+<MatrixRain color="#39ff14" density={1.5} speed={1.8} />
+```
+
+The canvas fills its parent (`h-full w-full`) and paints its own black background, so size it via a wrapping element.
+
+## Props
+
+| Prop          | Type     | Default     | Description                                                             |
+| ------------- | -------- | ----------- | ----------------------------------------------------------------------- |
+| `color`       | `string` | `"#00ff41"` | Glyph color (the classic Matrix green)                                  |
+| `speed`       | `number` | `1.0`       | Fall speed multiplier (`< 1` slower, `> 1` faster)                      |
+| `density`     | `number` | `1.0`       | Column density multiplier (higher = more, narrower columns)             |
+| `glyphSize`   | `number` | `16`        | Font size of each glyph in pixels                                       |
+| `fadeOpacity` | `number` | `0.05`      | Opacity of the black overlay painted each frame — controls trail length |
+| `class`       | `string` | —           | Additional CSS classes on the canvas                                    |
+
+## Implementation notes
+
+- Glyphs are drawn from a fixed katakana + Latin + digit + symbol string (`GLYPHS`); each visible position gets a freshly randomized glyph every frame it's redrawn, so no character "stays" in place — the trail effect comes entirely from `fadeOpacity`, not glyph persistence.
+- Column count is `floor(width / (glyphSize * density))`, and both `glyphSize` and `density` are floored to a safe minimum (`glyphSize >= 1`, `density >= 0.1`) so extreme prop values can't divide by zero or blow up the column count.
+- `speed >= 1` advances every column by `speed` rows per frame; `speed < 1` instead skips frames (`frameCount % round(1/speed) === 0`), which is why speed below 1 steps down in discrete slow-motion increments rather than scaling smoothly.
+- The canvas is sized in device pixels via `window.devicePixelRatio` and a matching `ctx.setTransform`, so glyphs stay crisp on HiDPI screens; a `ResizeObserver` on the canvas re-runs the resize/init logic (which also resets column positions) whenever its box size changes.
+- The render loop is a single `requestAnimationFrame` chain started in a `$effect` and torn down (canceled, observer disconnected) in its cleanup — there's no visibility-based pausing, so it keeps painting while off-screen or the tab is backgrounded.
+- No `prefers-reduced-motion` handling — the rain animates continuously regardless of user preference.

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

@@ -0,0 +1,52 @@
+# NoiseReveal
+
+A WebGL image reveal driven by a Perlin-noise dissolve mask, a radial gradient that contracts as the reveal progresses, and a subtle wave displacement on the mesh itself. Reveals either once on scroll-into-view or under full manual control via a `revealed` prop.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { NoiseReveal } from "fancy-ui-svelte";
+</script>
+
+<!-- Reveals once when it scrolls into view -->
+<NoiseReveal
+	src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
+	alt="Mountain peak above the clouds"
+	class="h-[300px] max-w-md"
+/>
+```
+
+```svelte
+<!-- Manual control — can also be hidden again -->
+<script lang="ts">
+	import { NoiseReveal } from "fancy-ui-svelte";
+	let revealed = $state(true);
+</script>
+
+<NoiseReveal src="/photo.jpg" trigger="manual" {revealed} />
+<button onclick={() => (revealed = !revealed)}>{revealed ? "Hide" : "Reveal"}</button>
+```
+
+## Props
+
+| Prop       | Type                 | Default  | Description                                                            |
+| ---------- | -------------------- | -------- | ---------------------------------------------------------------------- |
+| `src`      | `string`             | —        | Image URL (required)                                                   |
+| `alt`      | `string`             | —        | Accessible label for the image                                         |
+| `trigger`  | `"view" \| "manual"` | `"view"` | `"view"` reveals once on viewport entry; `"manual"` follows `revealed` |
+| `revealed` | `boolean`            | `false`  | Manual reveal state — only used with `trigger="manual"`; can re-hide   |
+| `duration` | `number`             | `1.5`    | Reveal animation duration in seconds                                   |
+| `delay`    | `number`             | `0`      | Delay before reveal in seconds — only applies to `trigger="view"`      |
+| `class`    | `string`             | `""`     | Additional CSS classes on the root                                     |
+
+## Implementation notes
+
+- The dissolve mask is computed entirely in the fragment shader: a domain-warped Perlin noise (`cnoise`, classic 3D Perlin noise) combined with a radial gradient anchored at the image center that contracts as `uProgress` goes from 0 to 1, clamped and inverted into an alpha value — there's no CPU-side mask texture.
+- Progress is driven by a hand-rolled tween (`setTarget`, cubic ease-in-out) rather than a library, advanced each animation frame against `performance.now()`; under `prefers-reduced-motion: reduce` the tween is skipped entirely and the value jumps straight to its target.
+- `trigger="view"` uses an `IntersectionObserver` (`threshold: 0.1`) that disconnects itself after the first intersection — the reveal only ever fires once per mount, `delay` is applied via `setTimeout` after that first intersection, not before.
+- `trigger="manual"` re-runs `setTarget(revealed ? 1 : 0)` on every change to `revealed`, so unlike `"view"` it supports revealing and re-hiding repeatedly.
+- The image texture loads asynchronously (`THREE.TextureLoader`); until it resolves, `uTexture` is `null` and the plane renders whatever the shader produces with no texture bound — there is no separate loading placeholder.
+- The plane is a unit `PlaneGeometry` scaled at render time to exactly fill the camera frustum at `z = 0` for the current aspect ratio (`fitPlane`), and `CoverUV` in the fragment shader applies `object-fit: cover`-style UV cropping so images with a different aspect ratio than the container aren't stretched.
+- Cleanup (on effect teardown) removes the `resize` listener, cancels the render loop, removes the canvas from `container`, and disposes the renderer, geometry, material, and any loaded texture.
+- When `alt` is provided, the root gets `role="img"` and `aria-label={alt}` so the canvas-rendered image is announced to assistive tech.

package/dist/fancy-ui/rainbow-button/README.md

@@ -0,0 +1,36 @@
+# RainbowButton
+
+A button (or anchor, when `href` is set) with an animated rainbow gradient border and a matching blurred glow beneath it, built entirely from CSS gradients, background layering, and a single `background-position` keyframe animation.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { RainbowButton } from "fancy-ui-svelte";
+</script>
+
+<RainbowButton onclick={() => console.log("clicked")}>Get started</RainbowButton>
+
+<!-- Renders an <a> instead of a <button> -->
+<RainbowButton href="/pricing" speed={3}>See pricing</RainbowButton>
+```
+
+## Props
+
+| Prop       | Type                                                        | Default    | Description                                                     |
+| ---------- | ----------------------------------------------------------- | ---------- | --------------------------------------------------------------- |
+| `speed`    | `number`                                                    | `2`        | Animation speed in seconds (lower = faster)                     |
+| `href`     | `string`                                                    | —          | Renders an `<a>` instead of a `<button>` when set               |
+| `type`     | `"button" \| "submit" \| "reset"`                           | `"button"` | Native `<button>` `type` attribute (ignored when `href` is set) |
+| `disabled` | `boolean`                                                   | —          | Disables the button / marks the link `aria-disabled`            |
+| `ref`      | `HTMLButtonElement \| HTMLAnchorElement \| null` (bindable) | `null`     | Bound reference to the rendered element                         |
+| `class`    | `string`                                                    | —          | Additional CSS classes                                          |
+| `children` | `Snippet`                                                   | —          | Button label content                                            |
+
+## Implementation notes
+
+- `RainbowButtonProps` is typed as `BaseProps & Omit<HTMLButtonAttributes, ...> & Omit<HTMLAnchorAttributes, ...>` for editor completion, but the component only actually reads `class`, `speed`, `href`, `type`, `disabled`, `ref`, and `children` off `$props()` — there is no `...restProps` spread, so other native attributes typed as valid (e.g. `onclick` via `HTMLButtonAttributes`) are **not** forwarded to the rendered element. Attach event listeners with `onclick` on a wrapping element, or extend the component, if pass-through is needed beyond what's listed above.
+- When `href` is set, the rendered `<a>` gets `aria-disabled` and `tabindex="-1"` (plus `role="link"`) instead of a native `disabled` attribute, since anchors don't support `disabled`.
+- The rainbow gradient colors (`--rainbow-1`…`--rainbow-5`) are hard-coded HSL custom properties scoped to `.rainbow-button` in the component's own `<style>` block — they aren't exposed as props; only the shared `speed` (as `--rainbow-speed`) is.
+- Light/dark mode swap the button's own fill and text color (dark button + white text in light mode, light button + black text in `dark:`) while reusing the same rainbow gradient for both the border and the glow.
+- No `prefers-reduced-motion` handling — the border and glow animation run continuously regardless of user preference.