fancy-ui-svelte 0.7.0 → 0.9.0

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

@@ -1,8 +1,4 @@
-interface ColorRGB {
-    r: number;
-    g: number;
-    b: number;
-}
+import { type ColorRGB, type FluidCursorHandle } from "./fluid-shared.js";
 interface Props {
     simResolution?: number;
     dyeResolution?: number;
@@ -29,6 +25,16 @@ interface Props {
     splatOnMount?: boolean;
     allowMultiple?: boolean;
     contained?: boolean;
+    hdr?: boolean;
+    hdrBoost?: number;
+    /**
+     * Called once the fluid engine is live, with an imperative handle to
+     * drive the simulation programmatically (trace a path via
+     * `moveTo`/`penUp`, fire a one-off `burst`) and read back the actual
+     * `renderLevel`. Pair with `interactive={false}` to drive it entirely
+     * without a real cursor.
+     */
+    onReady?: (handle: FluidCursorHandle) => void;
 }
 declare const FluidCursor: import("svelte").Component<Props, {}, "">;
 type FluidCursor = ReturnType<typeof FluidCursor>;

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

@@ -66,6 +66,35 @@ describe("FluidCursor", () => {
             vi.unstubAllGlobals();
         });
     });
+    describe("hdr props", () => {
+        it("renders without error with hdr={true} when WebGPU is unavailable", () => {
+            const { container } = render(FluidCursor, { props: { hdr: true } });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("renders without error when hdrBoost is out of [1,4] range (clamped internally)", () => {
+            const { container } = render(FluidCursor, { props: { hdr: true, hdrBoost: 100 } });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("falls back cleanly when WebGPU is present but no adapter is returned", async () => {
+            const requestAdapter = vi.fn(async () => null);
+            // Define `gpu` on the real navigator instead of replacing it, so the
+            // Navigator prototype (userAgent, etc.) stays intact.
+            Object.defineProperty(navigator, "gpu", {
+                value: { requestAdapter },
+                configurable: true,
+            });
+            try {
+                const { container } = render(FluidCursor, { props: { hdr: true } });
+                // Let the async WebGPU attempt resolve and fall back.
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                expect(requestAdapter).toHaveBeenCalled();
+                expect(container.querySelector("canvas")).toBeInTheDocument();
+            }
+            finally {
+                delete navigator.gpu;
+            }
+        });
+    });
     describe("color props", () => {
         it("renders without error when fluidColor is provided", () => {
             const { container } = render(FluidCursor, { props: { fluidColor: "#00ffcc" } });
@@ -98,4 +127,23 @@ describe("FluidCursor", () => {
             expect(container.querySelector("canvas")).toBeInTheDocument();
         });
     });
+    describe("onReady handle", () => {
+        // jsdom provides no WebGL context, so this exercises the no-renderer path.
+        it('reports renderLevel "none" when no renderer is available', () => {
+            const onReady = vi.fn();
+            render(FluidCursor, { props: { onReady } });
+            expect(onReady).toHaveBeenCalledTimes(1);
+            expect(onReady.mock.calls[0][0].renderLevel).toBe("none");
+        });
+        it("hands over an inert handle that is safe to call", () => {
+            const onReady = vi.fn();
+            render(FluidCursor, { props: { onReady } });
+            const handle = onReady.mock.calls[0][0];
+            expect(() => {
+                handle.moveTo(0.5, 0.5);
+                handle.penUp();
+                handle.burst(0.5, 0.5, 10, 10, { r: 1, g: 0, b: 0 });
+            }).not.toThrow();
+        });
+    });
 });

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

@@ -5,6 +5,7 @@ A WebGL-based fluid simulation that follows the cursor, creating beautiful flowi
 ## Features
 
 - WebGL2 fluid simulation with WebGL1 fallback
+- Optional HDR mode rendered by a WebGPU engine (wide gamut + extended tone mapping)
 - Mouse and touch support
 - Configurable simulation parameters
 - Transparent background support
@@ -23,6 +24,7 @@ A WebGL-based fluid simulation that follows the cursor, creating beautiful flowi
 ### WebGL Implementation
 
 The component implements a full Navier-Stokes fluid simulation with:
+
 - Curl/vorticity computation
 - Pressure solving with iterative Jacobi method
 - Advection for both velocity and dye
@@ -30,12 +32,12 @@ The component implements a full Navier-Stokes fluid simulation with:
 
 ## Color Props
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `fluidColor` | `string` (hex) | — | Fixed fluid color. Disables random cycling. |
-| `fluidColors` | `string[]` (hex) | — | Palette to cycle through on each splat. |
-| `colorIntensity` | `number` | `0.15` | Intensity multiplier applied to fluid colors (0–1). |
-| `backColor` | `{ r, g, b }` or `string` (hex) | `{ r: 0.5, g: 0, b: 0 }` | Background color — accepts RGB object or hex string. |
+| Prop             | Type                            | Default                  | Description                                          |
+| ---------------- | ------------------------------- | ------------------------ | ---------------------------------------------------- |
+| `fluidColor`     | `string` (hex)                  | —                        | Fixed fluid color. Disables random cycling.          |
+| `fluidColors`    | `string[]` (hex)                | —                        | Palette to cycle through on each splat.              |
+| `colorIntensity` | `number`                        | `0.15`                   | Intensity multiplier applied to fluid colors (0–1).  |
+| `backColor`      | `{ r, g, b }` or `string` (hex) | `{ r: 0.5, g: 0, b: 0 }` | Background color — accepts RGB object or hex string. |
 
 **Priority**: `fluidColor` > `fluidColors` > random HSV
 
@@ -52,8 +54,57 @@ The component implements a full Navier-Stokes fluid simulation with:
 <FluidCursor backColor="#1a1a2e" />
 ```
 
+### Contained-mode splat scaling
+
+`splatRadius` is defined as a fraction of the canvas, which would make the
+effect look tiny inside small containers (e.g. docs demos). In `contained`
+mode both engines grow the aspect-corrected radius with the
+viewport/container height ratio — sub-linearly in apparent size (×√k), so a
+small demo reads bigger without mimicking fullscreen 1:1 — capped at ~30% of
+the container height (`scaleRadiusForContainer` in `fluid-shared.ts`).
+Fullscreen and viewport-sized containers are unaffected.
+
 ### Event Handling
 
 - Window-level mouse/touch events for full-screen tracking
 - First-move handlers to start animation only when user interacts
 - Proper cleanup of all event listeners on component unmount
+
+## HDR Mode
+
+```svelte
+<FluidCursor hdr hdrBoost={2} fluidColors={["#a142ff", "#42cfff"]} />
+```
+
+With `hdr` enabled the component tries a WebGPU engine (`webgpu-engine.ts`, a
+WGSL port of the same simulation) that renders into an `rgba16float` canvas
+configured with `colorSpace: "display-p3"` and `toneMapping: { mode: "extended" }`.
+On an HDR display, dye values pushed above `1.0` by `hdrBoost` render brighter
+than SDR white; on a wide-gamut (P3) display colors are noticeably more
+saturated even without HDR headroom.
+
+| Prop       | Type      | Default | Description                                                                          |
+| ---------- | --------- | ------- | ------------------------------------------------------------------------------------ |
+| `hdr`      | `boolean` | `false` | Opt into the WebGPU HDR engine with automatic fallback.                              |
+| `hdrBoost` | `number`  | `1.5`   | Display exposure multiplier, clamped to `[1, 4]`. Only applied by the WebGPU engine. |
+
+### Support cascade
+
+The component degrades silently (the level is logged to the console in dev):
+
+1. **`webgpu-hdr`** — WebGPU available: float16 backbuffer, P3, extended tone
+   mapping (Chrome/Edge 129+, Safari 26+; browsers that ignore `toneMapping`
+   still get the float16 + P3 rendering, clamped to SDR).
+2. **`webgl-p3`** — no WebGPU: the regular WebGL engine with
+   `drawingBufferColorSpace = "display-p3"` (Chrome/Edge 104+, Safari 16.4+,
+   Firefox 132+). Wide gamut only, no extra brightness; `hdrBoost` is ignored.
+3. **`sdr`** — everything else: the unchanged default rendering.
+
+Notes:
+
+- Colors are intentionally reinterpreted in P3 space rather than converted
+  from sRGB — the resulting saturation push is the point of the effect.
+- The glow requires an HDR-capable display (`matchMedia("(dynamic-range: high)")`).
+  On SDR displays HDR mode is still safe, just clamped.
+- With `hdr={false}` (the default) the WebGPU code path is never taken and
+  rendering is identical to previous versions.

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

@@ -0,0 +1,72 @@
+export interface ColorRGB {
+    r: number;
+    g: number;
+    b: number;
+}
+export interface Pointer {
+    id: number;
+    texcoordX: number;
+    texcoordY: number;
+    prevTexcoordX: number;
+    prevTexcoordY: number;
+    deltaX: number;
+    deltaY: number;
+    down: boolean;
+    moved: boolean;
+    color: ColorRGB;
+}
+export declare function pointerPrototype(): Pointer;
+export declare function hexToRgb(hex: string): ColorRGB;
+export declare function HSVtoRGB(h: number, s: number, v: number): ColorRGB;
+export declare function wrap(value: number, min: number, max: number): number;
+/** Sim/dye grid size for a given base resolution and drawing buffer dimensions. */
+export declare function getSimResolution(resolution: number, bufferWidth: number, bufferHeight: number): {
+    width: number;
+    height: number;
+};
+export declare function correctRadius(radius: number, width: number, height: number): number;
+/**
+ * In contained mode the splat radius is a fraction of the canvas, so the same
+ * settings that look right fullscreen produce a tiny effect inside a small
+ * demo container. Grow the radius with the viewport/container ratio —
+ * sub-linearly in apparent size (the gaussian's characteristic length is
+ * sqrt(radius), so `radius * k` scales the length by sqrt(k)): a small demo
+ * reads bigger without mimicking fullscreen 1:1. Must be applied to the
+ * final, aspect-corrected radius; the 0.09 cap keeps the characteristic
+ * length under ~30% of the container height.
+ */
+export declare function scaleRadiusForContainer(radius: number, containerHeight: number, viewportHeight: number): number;
+export declare function correctDeltaX(delta: number, width: number, height: number): number;
+export declare function correctDeltaY(delta: number, width: number, height: number): number;
+/**
+ * How the fluid is actually being rendered, surfaced as data so callers can
+ * react (e.g. tell true HDR output apart from a clamped fallback):
+ * - "webgpu-hdr": WebGPU with extended tone mapping active AND a display
+ *   reporting `(dynamic-range: high)` — true HDR output.
+ * - "webgpu-sdr": WebGPU float16 + P3, but the browser clamped tone mapping or
+ *   the output display is SDR.
+ * - "webgl-p3":   WebGL fallback with a display-p3 drawing buffer.
+ * - "webgl-sdr":  WebGL fallback, plain sRGB.
+ * - "none":       no GPU rendering available at all; the handle is inert.
+ *
+ * Sampled once when the handle is created: it does not update if the window
+ * later moves to a display with a different dynamic range.
+ */
+export type FluidRenderLevel = "webgpu-hdr" | "webgpu-sdr" | "webgl-p3" | "webgl-sdr" | "none";
+/**
+ * Imperative control surface handed to `FluidCursor`'s `onReady` callback so a
+ * parent can drive the simulation programmatically (trace a path, fire a
+ * one-off burst) and read back which render path actually engaged. Coordinates
+ * are in [0,1] with the ORIGIN AT THE TOP-LEFT (CSS convention); velocity is
+ * derived from consecutive `moveTo` calls, so smooth paths feel like a real
+ * cursor. Any engine-specific Y flip is internal.
+ */
+export interface FluidCursorHandle {
+    /** Drive the synthetic pointer like a mouse. The next `moveTo` after `penUp` repositions without drawing. */
+    moveTo(x: number, y: number, color?: ColorRGB): void;
+    /** Lift the pen so the next `moveTo` repositions without producing a connecting streak. */
+    penUp(): void;
+    /** One-off impulse (click-like burst). Same coord convention; dx/dy in engine velocity units. */
+    burst(x: number, y: number, dx: number, dy: number, color: ColorRGB): void;
+    readonly renderLevel: FluidRenderLevel;
+}

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

@@ -0,0 +1,125 @@
+// Pure helpers shared by the WebGL and WebGPU fluid engines.
+export function pointerPrototype() {
+    return {
+        id: -1,
+        texcoordX: 0,
+        texcoordY: 0,
+        prevTexcoordX: 0,
+        prevTexcoordY: 0,
+        deltaX: 0,
+        deltaY: 0,
+        down: false,
+        moved: false,
+        color: { r: 0, g: 0, b: 0 },
+    };
+}
+export function hexToRgb(hex) {
+    const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+    if (!result) {
+        console.warn(`[FluidCursor] Invalid hex color: "${hex}". Expected format: "#rrggbb". Falling back to white.`);
+        return { r: 1, g: 1, b: 1 };
+    }
+    return {
+        r: parseInt(result[1], 16) / 255,
+        g: parseInt(result[2], 16) / 255,
+        b: parseInt(result[3], 16) / 255,
+    };
+}
+export function HSVtoRGB(h, s, v) {
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    const i = Math.floor(h * 6);
+    const f = h * 6 - i;
+    const p = v * (1 - s);
+    const q = v * (1 - f * s);
+    const t = v * (1 - (1 - f) * s);
+    switch (i % 6) {
+        case 0:
+            r = v;
+            g = t;
+            b = p;
+            break;
+        case 1:
+            r = q;
+            g = v;
+            b = p;
+            break;
+        case 2:
+            r = p;
+            g = v;
+            b = t;
+            break;
+        case 3:
+            r = p;
+            g = q;
+            b = v;
+            break;
+        case 4:
+            r = t;
+            g = p;
+            b = v;
+            break;
+        case 5:
+            r = v;
+            g = p;
+            b = q;
+            break;
+    }
+    return { r, g, b };
+}
+export function wrap(value, min, max) {
+    const range = max - min;
+    if (range === 0)
+        return min;
+    return ((value - min) % range) + min;
+}
+/** Sim/dye grid size for a given base resolution and drawing buffer dimensions. */
+export function getSimResolution(resolution, bufferWidth, bufferHeight) {
+    const aspectRatio = bufferWidth / bufferHeight;
+    const aspect = aspectRatio < 1 ? 1 / aspectRatio : aspectRatio;
+    const min = Math.round(resolution);
+    const max = Math.round(resolution * aspect);
+    if (bufferWidth > bufferHeight) {
+        return { width: max, height: min };
+    }
+    return { width: min, height: max };
+}
+export function correctRadius(radius, width, height) {
+    const aspectRatio = width / height;
+    if (aspectRatio > 1)
+        return radius * aspectRatio;
+    return radius;
+}
+/**
+ * In contained mode the splat radius is a fraction of the canvas, so the same
+ * settings that look right fullscreen produce a tiny effect inside a small
+ * demo container. Grow the radius with the viewport/container ratio —
+ * sub-linearly in apparent size (the gaussian's characteristic length is
+ * sqrt(radius), so `radius * k` scales the length by sqrt(k)): a small demo
+ * reads bigger without mimicking fullscreen 1:1. Must be applied to the
+ * final, aspect-corrected radius; the 0.09 cap keeps the characteristic
+ * length under ~30% of the container height.
+ */
+export function scaleRadiusForContainer(radius, containerHeight, viewportHeight) {
+    if (containerHeight <= 0 || viewportHeight <= 0)
+        return radius;
+    const k = viewportHeight / containerHeight;
+    if (k <= 1)
+        return radius;
+    // The cap only limits the auto-scaling — a caller-provided radius that is
+    // already larger must never be shrunk by entering a small container.
+    return Math.max(radius, Math.min(radius * k, 0.09));
+}
+export function correctDeltaX(delta, width, height) {
+    const aspectRatio = width / height;
+    if (aspectRatio < 1)
+        return delta * aspectRatio;
+    return delta;
+}
+export function correctDeltaY(delta, width, height) {
+    const aspectRatio = width / height;
+    if (aspectRatio > 1)
+        return delta / aspectRatio;
+    return delta;
+}

package/dist/fancy-ui/fluid-cursor/fluid-shared.test.d.ts

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

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

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { scaleRadiusForContainer, correctRadius, getSimResolution } from "./fluid-shared.js";
+describe("scaleRadiusForContainer", () => {
+    it("keeps the radius unchanged at viewport size (fullscreen)", () => {
+        expect(scaleRadiusForContainer(0.002, 900, 900)).toBe(0.002);
+    });
+    it("keeps the radius unchanged when the container is larger than the viewport", () => {
+        expect(scaleRadiusForContainer(0.002, 1800, 900)).toBe(0.002);
+    });
+    it("grows the radius linearly with the viewport/container ratio (sqrt(k) in apparent size)", () => {
+        // Container 4x smaller than viewport: radius x4, characteristic
+        // length x2 in container fractions.
+        expect(scaleRadiusForContainer(0.002, 250, 1000)).toBeCloseTo(0.008, 10);
+    });
+    it("caps the radius so a splat stays under ~30% of a tiny container", () => {
+        expect(scaleRadiusForContainer(0.01, 50, 1000)).toBe(0.09);
+    });
+    it("never shrinks a caller-provided radius already above the cap", () => {
+        expect(scaleRadiusForContainer(0.2, 250, 1000)).toBe(0.2);
+    });
+    it("is defensive about degenerate dimensions", () => {
+        expect(scaleRadiusForContainer(0.002, 0, 1000)).toBe(0.002);
+        expect(scaleRadiusForContainer(0.002, 250, 0)).toBe(0.002);
+    });
+});
+describe("correctRadius", () => {
+    it("stretches the radius by aspect ratio on landscape canvases", () => {
+        expect(correctRadius(0.01, 200, 100)).toBe(0.02);
+    });
+    it("leaves portrait canvases unchanged", () => {
+        expect(correctRadius(0.01, 100, 200)).toBe(0.01);
+    });
+});
+describe("getSimResolution", () => {
+    it("puts the larger grid dimension along the larger canvas axis", () => {
+        expect(getSimResolution(128, 1000, 500)).toEqual({ width: 256, height: 128 });
+        expect(getSimResolution(128, 500, 1000)).toEqual({ width: 128, height: 256 });
+    });
+});

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

@@ -3,3 +3,4 @@ export { default as FluidCursor } from "./FluidCursor.svelte";
  * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
  */
 export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";
+export type { FluidCursorHandle, FluidRenderLevel } from "./fluid-shared.js";

package/dist/fancy-ui/fluid-cursor/webgpu-engine.d.ts

@@ -0,0 +1,36 @@
+import { type ColorRGB, type FluidCursorHandle } from "./fluid-shared.js";
+export interface WebGpuFluidOptions {
+    simResolution: number;
+    dyeResolution: number;
+    densityDissipation: number;
+    velocityDissipation: number;
+    pressure: number;
+    pressureIterations: number;
+    curl: number;
+    splatRadius: number;
+    splatForce: number;
+    shading: boolean;
+    colorUpdateSpeed: number;
+    /** Display exposure multiplier — values above 1 create the HDR glow. */
+    exposure: number;
+    contained: boolean;
+    interactive: boolean;
+    autoSplat: boolean;
+    autoSplatInterval: number;
+    pauseWhenHidden: boolean;
+    splatOnMount: boolean;
+    generateColor: () => ColorRGB;
+}
+/**
+ * Full WebGPU setup for FluidCursor: engine + pointer wiring + rAF loop +
+ * visibility pause + auto splats. Resolves with a {@link FluidCursorHandle}
+ * (augmented with `cleanup`), or with `null` when WebGPU is unavailable
+ * (caller falls back to the WebGL path).
+ *
+ * Handle coordinates are top-left origin in [0,1]; WebGPU texcoords already
+ * use a top-origin convention, so no Y flip happens here (the WebGL path owns
+ * its own flip).
+ */
+export declare function startWebGpuFluid(canvas: HTMLCanvasElement, opts: WebGpuFluidOptions): Promise<(FluidCursorHandle & {
+    cleanup(): void;
+}) | null>;