fancy-ui-svelte 0.6.0 → 0.8.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/registry.js

@@ -935,6 +935,18 @@ export const registry = {
                 default: "true",
                 description: "Confine simulation to parent container",
             },
+            {
+                name: "hdr",
+                type: "boolean",
+                default: "false",
+                description: "Render via the WebGPU HDR engine — wide gamut + brighter-than-white glow on HDR displays. Needs Chrome/Edge 129+ or Safari 26+; falls back to wide-gamut WebGL (Chrome 104+, Safari 16.4+, Firefox 132+), then to standard rendering",
+            },
+            {
+                name: "hdrBoost",
+                type: "number",
+                default: "1.5",
+                description: "Display exposure multiplier in HDR mode, clamped to [1, 4]",
+            },
         ],
     },
     "glow-border": {
@@ -1634,6 +1646,74 @@ export const registry = {
             },
         ],
     },
+    "frosted-glass": {
+        name: "FrostedGlass",
+        slug: "frosted-glass",
+        description: "Frosted glass surface with organic turbulence-noise refraction, an alternative to LiquidGlass",
+        category: "effects",
+        status: "done",
+        tags: ["glass", "effect", "svg", "filter", "turbulence", "displacement", "blur", "navbar"],
+        props: [
+            { name: "radius", type: "number", default: "24", description: "Border radius in pixels" },
+            {
+                name: "baseFrequency",
+                type: "number",
+                default: "0.008",
+                description: "Turbulence noise frequency (lower = wider waves)",
+            },
+            {
+                name: "numOctaves",
+                type: "number",
+                default: "2",
+                description: "Turbulence octaves controlling noise detail",
+            },
+            { name: "seed", type: "number", default: "92", description: "Turbulence random seed" },
+            {
+                name: "noiseBlur",
+                type: "number",
+                default: "2",
+                description: "Gaussian blur softening the noise before displacement",
+            },
+            { name: "scale", type: "number", default: "70", description: "Displacement intensity" },
+            {
+                name: "tint",
+                type: "string",
+                default: '"hsla(0, 0%, 100%, 0.25)"',
+                description: "Overlay tint color",
+            },
+            {
+                name: "highlight",
+                type: "string",
+                default: '"hsla(0, 0%, 100%, 0.75)"',
+                description: "Specular rim highlight color",
+            },
+            {
+                name: "border",
+                type: "boolean",
+                default: "true",
+                description: "Show the conic-gradient glass border",
+            },
+            {
+                name: "fallbackBlur",
+                type: "number",
+                default: "20",
+                description: "Backdrop blur in pixels for the Safari fallback",
+            },
+            {
+                name: "fallbackSaturation",
+                type: "number",
+                default: "180",
+                description: "Backdrop saturation percentage for the Safari fallback",
+            },
+            {
+                name: "containerClass",
+                type: "string",
+                default: '""',
+                description: "CSS classes for the outer container",
+            },
+        ],
+        slots: [{ name: "children", description: "Content rendered on top of the glass" }],
+    },
     "liquid-glass": {
         name: "LiquidGlass",
         slug: "liquid-glass",
@@ -1711,6 +1791,18 @@ export const registry = {
             },
             { name: "scale", type: "number", default: "-180", description: "Displacement scale" },
             { name: "frost", type: "number", default: "0.05", description: "Frosted glass opacity" },
+            {
+                name: "fallbackBlur",
+                type: "number",
+                default: "20",
+                description: "Backdrop blur in pixels for the Safari fallback",
+            },
+            {
+                name: "fallbackSaturation",
+                type: "number",
+                default: "180",
+                description: "Backdrop saturation percentage for the Safari fallback",
+            },
             {
                 name: "containerClass",
                 type: "string",
@@ -2157,6 +2249,106 @@ export const registry = {
             },
         ],
     },
+    "liquid-text": {
+        name: "LiquidText",
+        slug: "liquid-text",
+        description: "Big text that liquefies along the cursor's path via a raw-WebGL fluid solver, with chromatic-aberration fringing that relaxes back over time",
+        category: "text",
+        status: "done",
+        credits: [
+            { source: "Inspired by ryanritzenthaler.com (behavioral study)" },
+            { source: "Fluid solver after Pavel Dobryakov's WebGL fluid simulation" },
+        ],
+        tags: ["text", "webgl", "fluid", "displacement", "cursor", "shader", "chromatic-aberration"],
+        props: [
+            { name: "text", type: "string", default: '"Liquid"', description: "Text to display" },
+            {
+                name: "font",
+                type: "string",
+                default: '""',
+                description: "Font family; empty string resolves via getComputedStyle(host).fontFamily",
+            },
+            {
+                name: "fontSize",
+                type: "number",
+                default: "0",
+                description: "Font size in pixels; 0 auto-fits to the container width",
+            },
+            {
+                name: "fontWeight",
+                type: "number | string",
+                default: "700",
+                description: "Font weight",
+            },
+            {
+                name: "lightColor",
+                type: "string",
+                default: '"#000000"',
+                description: "Text color in light mode",
+            },
+            {
+                name: "darkColor",
+                type: "string",
+                default: '"#ffffff"',
+                description: "Text color in dark mode",
+            },
+            { name: "class", type: "string", description: "Additional CSS classes" },
+            {
+                name: "strength",
+                type: "number",
+                default: "0.5",
+                description: "Geometric UV warp gain",
+            },
+            {
+                name: "radius",
+                type: "number",
+                default: "160",
+                description: "Splat radius in screen pixels",
+            },
+            {
+                name: "forceGain",
+                type: "number",
+                default: "17",
+                description: "Mouse-delta to force multiplier",
+            },
+            {
+                name: "dissipation",
+                type: "number",
+                default: "0.98",
+                description: "Per-frame velocity decay factor",
+            },
+            {
+                name: "viscosity",
+                type: "number",
+                default: "4",
+                description: "Jacobi viscous diffusion strength (8 iterations)",
+            },
+            {
+                name: "chromaticRatio",
+                type: "number",
+                default: "0.2",
+                description: "Chromatic offset as a ratio of the warp",
+            },
+            {
+                name: "staticBelow",
+                type: "number",
+                default: "1024",
+                description: "innerWidth at/below which the component renders as static DOM text (also used at mount)",
+            },
+            {
+                name: "interactive",
+                type: "boolean",
+                default: "true",
+                description: "Whether pointer movement drives the fluid simulation",
+            },
+            {
+                name: "pauseWhenHidden",
+                type: "boolean",
+                default: "true",
+                description: "Pause the render loop while the document is hidden",
+            },
+        ],
+    },
 };
 // =============================================================================
 // Registry Helpers

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

@@ -0,0 +1,38 @@
+/**
+ * Theme registry (docs-site theming data).
+ *
+ * A named theme is a set of CSS-variable overrides applied on top of the base
+ * light/dark token sets defined in `src/routes/layout.css`. The theme store
+ * (`src/lib/stores/theme.svelte.ts`) applies a theme by setting these variables
+ * inline on `<html>`, toggling the `.dark` class per `colorScheme`, and setting
+ * a `data-theme` attribute.
+ *
+ * NOTE: this module is docs/theming data only. It is NOT imported by any shipped
+ * component in `src/lib/fancy-ui/*`, so it does not affect the published package.
+ */
+export type ColorScheme = "light" | "dark";
+export interface ThemeDef {
+    /** Stable id, used as the `data-theme` value and persistence key. */
+    name: string;
+    /** Human label shown in the switcher. */
+    label: string;
+    /** Whether the theme reads as light or dark (drives the `.dark` class). */
+    colorScheme: ColorScheme;
+    /** CSS custom-property overrides applied on top of the base light/dark set. */
+    tokens: Record<string, string>;
+    /** Four representative colors for the switcher swatch. */
+    swatch: [string, string, string, string];
+}
+/** Every CSS variable a theme may set. The store clears these before applying a theme. */
+export declare const MANAGED_VARS: readonly ["--background", "--foreground", "--card", "--card-foreground", "--popover", "--popover-foreground", "--primary", "--primary-foreground", "--secondary", "--secondary-foreground", "--muted", "--muted-foreground", "--accent", "--accent-foreground", "--border", "--input", "--ring", "--radius", "--rainbow-1", "--rainbow-2", "--rainbow-3", "--rainbow-4", "--rainbow-5", "--sidebar", "--sidebar-foreground", "--sidebar-primary", "--sidebar-primary-foreground", "--sidebar-accent", "--sidebar-accent-foreground", "--sidebar-border"];
+/**
+ * The theme list.
+ *
+ * `light` and `dark` carry no token overrides — they are the base look defined
+ * by `:root` / `.dark` in `layout.css`. The remaining themes are self-contained.
+ * `sunset` / `ocean` / `mono` mirror the theme-generator presets.
+ */
+export declare const themes: ThemeDef[];
+export declare function getTheme(name: string): ThemeDef | undefined;
+export declare const themeNames: string[];
+export declare const DEFAULT_THEME = "light";