fancy-ui-svelte 0.8.0 → 0.9.0

package/dist/fancy-ui/card-3d/CardContainer.test.js

@@ -0,0 +1,118 @@
+import { render, cleanup, fireEvent } from "@testing-library/svelte";
+import { createRawSnippet } from "svelte";
+import { afterEach, describe, it, expect } from "vitest";
+import CardContainer from "./CardContainer.svelte";
+import CardBody from "./CardBody.svelte";
+import CardItem from "./CardItem.svelte";
+function textSnippet(html) {
+    return createRawSnippet(() => ({ render: () => html }));
+}
+describe("CardContainer", () => {
+    afterEach(cleanup);
+    it("renders the perspective wrapper and the 3d inner container", () => {
+        const { container } = render(CardContainer);
+        const outer = container.firstElementChild;
+        const inner = outer.firstElementChild;
+        expect(outer.getAttribute("style")).toContain("perspective: 1000px");
+        expect(inner.getAttribute("style")).toContain("transform-style: preserve-3d");
+    });
+    it("applies containerClass to the outer wrapper and class to the inner container", () => {
+        const { container } = render(CardContainer, {
+            props: { containerClass: "my-outer", class: "my-inner" },
+        });
+        const outer = container.firstElementChild;
+        const inner = outer.firstElementChild;
+        expect(outer.className).toContain("my-outer");
+        expect(inner.className).toContain("my-inner");
+    });
+    it("renders children content", () => {
+        const { container } = render(CardContainer, {
+            props: { children: textSnippet("<p data-testid='content'>card body</p>") },
+        });
+        expect(container.querySelector("[data-testid='content']")?.textContent).toBe("card body");
+    });
+    it("rotates the inner container on mousemove and resets on mouseleave", async () => {
+        const { container } = render(CardContainer);
+        const inner = container.firstElementChild.firstElementChild;
+        // jsdom's getBoundingClientRect() is all zeros, so rotateY = clientX / 25
+        // and rotateX = clientY / 25 for this component's handler.
+        await fireEvent.mouseMove(inner, { clientX: 50, clientY: 25 });
+        expect(inner.style.transform).toBe("rotateY(2deg) rotateX(1deg)");
+        await fireEvent.mouseLeave(inner);
+        expect(inner.style.transform).toBe("rotateY(0deg) rotateX(0deg)");
+    });
+});
+describe("CardBody", () => {
+    afterEach(cleanup);
+    it("renders with the fixed 3d-card dimensions", () => {
+        const { container } = render(CardBody);
+        const body = container.firstElementChild;
+        expect(body.className).toContain("h-96");
+        expect(body.className).toContain("w-96");
+        expect(body.getAttribute("style")).toContain("transform-style: preserve-3d");
+    });
+    it("applies custom class names", () => {
+        const { container } = render(CardBody, { props: { class: "my-body" } });
+        const body = container.firstElementChild;
+        expect(body.className).toContain("my-body");
+    });
+    it("renders children content", () => {
+        const { container } = render(CardBody, {
+            props: { children: textSnippet("<span data-testid='inner'>x</span>") },
+        });
+        expect(container.querySelector("[data-testid='inner']")).toBeTruthy();
+    });
+});
+describe("CardItem", () => {
+    afterEach(cleanup);
+    // CardItem reads its hover state from CardContainer via setContext/getContext
+    // under the "card3d:mouseEntered" key. @testing-library/svelte forwards a
+    // `context` mount option straight to Svelte's mount(), so it can be tested
+    // standalone without mounting a full CardContainer tree.
+    function withContext(mouseEntered) {
+        return new Map([["card3d:mouseEntered", () => mouseEntered]]);
+    }
+    it("sits at the zero transform when the container reports no hover", () => {
+        const { container } = render(CardItem, {
+            props: { translateX: 20, rotateZ: 10 },
+            context: withContext(false),
+        });
+        const el = container.firstElementChild;
+        expect(el.style.transform).toContain("translateX(0px)");
+        expect(el.style.transform).toContain("rotateZ(0deg)");
+    });
+    it("applies the configured translate/rotate values once the container reports hover", () => {
+        const { container } = render(CardItem, {
+            props: { translateX: 20, translateY: -10, rotateZ: 10 },
+            context: withContext(true),
+        });
+        const el = container.firstElementChild;
+        expect(el.style.transform).toContain("translateX(20px)");
+        expect(el.style.transform).toContain("translateY(-10px)");
+        expect(el.style.transform).toContain("rotateZ(10deg)");
+    });
+    it("renders the element specified by the as prop", () => {
+        const { container } = render(CardItem, {
+            props: { as: "span" },
+            context: withContext(false),
+        });
+        expect(container.firstElementChild?.tagName.toLowerCase()).toBe("span");
+    });
+    it("defaults to a div and merges custom class names", () => {
+        const { container } = render(CardItem, {
+            props: { class: "my-item" },
+            context: withContext(false),
+        });
+        const el = container.firstElementChild;
+        expect(el.tagName.toLowerCase()).toBe("div");
+        expect(el.className).toContain("my-item");
+        expect(el.className).toContain("w-fit");
+    });
+    it("renders children content", () => {
+        const { container } = render(CardItem, {
+            props: { children: textSnippet("<em data-testid='item-child'>x</em>") },
+            context: withContext(false),
+        });
+        expect(container.querySelector("[data-testid='item-child']")).toBeTruthy();
+    });
+});

package/dist/fancy-ui/card-spotlight/CardSpotlight.test.d.ts

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

package/dist/fancy-ui/card-spotlight/CardSpotlight.test.js

@@ -0,0 +1,58 @@
+import { render, cleanup, fireEvent } from "@testing-library/svelte";
+import { createRawSnippet } from "svelte";
+import { afterEach, describe, it, expect } from "vitest";
+import CardSpotlight from "./CardSpotlight.svelte";
+function textSnippet(html) {
+    return createRawSnippet(() => ({ render: () => html }));
+}
+describe("CardSpotlight", () => {
+    afterEach(cleanup);
+    it("renders the wrapper with the base card classes", () => {
+        const { container } = render(CardSpotlight);
+        const wrapper = container.firstElementChild;
+        expect(wrapper.className).toContain("rounded-xl");
+        expect(wrapper.className).toContain("overflow-hidden");
+    });
+    it("applies custom class names to the wrapper", () => {
+        const { container } = render(CardSpotlight, { props: { class: "my-spotlight" } });
+        const wrapper = container.firstElementChild;
+        expect(wrapper.className).toContain("my-spotlight");
+    });
+    it("applies slotClass to the content wrapper", () => {
+        const { container } = render(CardSpotlight, { props: { slotClass: "my-slot" } });
+        const slot = container.querySelector(".relative.z-10");
+        expect(slot.className).toContain("my-slot");
+    });
+    it("renders children content", () => {
+        const { container } = render(CardSpotlight, {
+            props: { children: textSnippet("<p data-testid='content'>hi</p>") },
+        });
+        expect(container.querySelector("[data-testid='content']")).toBeTruthy();
+    });
+    // The overlay's `style="background: {backgroundStyle}; opacity: {gradientOpacity}"`
+    // attribute never materializes under this repo's vitest+jsdom setup — verified
+    // with a from-scratch minimal component reproduction, unrelated to mouse
+    // tracking or gradientSize/gradientColor: any style attribute shaped like
+    // `style="prop: {dyn}; prop2: value"` on a plain element renders with no
+    // style attribute at all (confirmed via getAttribute, .style.cssText, and
+    // the individual .style.* properties, all empty). Because vite.config.ts
+    // forces `resolve: { conditions: ['browser'] }`, tests compile the same
+    // client output real browsers get, so this is worth a maintainer checking
+    // in an actual browser rather than something to chase further here — see
+    // the gradient/opacity plumbing tests below, which stay on structure only.
+    it("accepts gradientSize/gradientColor/gradientOpacity without throwing and keeps the overlay in the DOM", () => {
+        const { container } = render(CardSpotlight, {
+            props: { gradientSize: 300, gradientColor: "#ff0000", gradientOpacity: 0.5 },
+        });
+        const overlay = container.querySelector(".pointer-events-none.absolute.inset-0");
+        expect(overlay).toBeTruthy();
+    });
+    it("responds to mousemove and mouseleave without throwing", async () => {
+        const { container } = render(CardSpotlight);
+        const wrapper = container.firstElementChild;
+        await fireEvent.mouseMove(wrapper, { clientX: 40, clientY: 30 });
+        await fireEvent.mouseLeave(wrapper);
+        // The awaits above would reject if either handler threw.
+        expect(container.querySelector(".pointer-events-none.absolute.inset-0")).toBeTruthy();
+    });
+});

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

@@ -0,0 +1,39 @@
+# DisplacementText
+
+Large text rendered as a Three.js plane whose surface bulges toward the viewer near the cursor, via a vertex-shader displacement driven by raycasting against an invisible hit-plane. The text itself is rasterized to a canvas texture, not drawn with real DOM glyphs.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { DisplacementText } from "fancy-ui-svelte";
+</script>
+
+<DisplacementText text="Hover Me" fontSize={220} class="h-[400px] w-full" />
+```
+
+```svelte
+<!-- Fixed color instead of following light/dark mode -->
+<DisplacementText text="Fancy" color="#ff4d4d" font="Georgia, serif" />
+```
+
+## Props
+
+| Prop         | Type     | Default               | Description                                                                          |
+| ------------ | -------- | --------------------- | ------------------------------------------------------------------------------------ |
+| `text`       | `string` | `"Hover Me"`          | Text to display                                                                      |
+| `fontSize`   | `number` | `200`                 | Font size in pixels, used when rasterizing the text texture                          |
+| `font`       | `string` | `"Inter, sans-serif"` | Font family                                                                          |
+| `color`      | `string` | —                     | Fixed text color; overrides `lightColor`/`darkColor` and disables dark-mode tracking |
+| `lightColor` | `string` | `"#000000"`           | Text color in light mode                                                             |
+| `darkColor`  | `string` | `"#ffffff"`           | Text color in dark mode                                                              |
+| `class`      | `string` | `""`                  | Additional CSS classes on the root                                                   |
+
+## Implementation notes
+
+- The whole Three.js scene (renderer, camera, geometry, material) is created and torn down inside a single `$effect` that depends on `text`, `fontSize`, `font`, `color`, `lightColor`, and `darkColor` — any of those changing disposes the old scene and builds a new one from scratch rather than updating it incrementally. This is simple but not cheap; avoid binding these props to something that changes every frame.
+- Displacement comes from a plane geometry (100×100 segments) whose vertex shader offsets `z` based on distance from a `uDisplacement` uniform, updated every `pointermove` by raycasting against a large (500×500), fully transparent hit-plane placed in the same scene — the visible text plane itself is not the raycast target.
+- Text is rasterized once per texture rebuild via a 2048×2048 `<canvas>` with `ctx.fillText`, then uploaded as a `THREE.CanvasTexture`.
+- When `color` is not set, a `MutationObserver` watches `document.documentElement`'s `class` attribute (the app's dark-mode toggle) and regenerates the text texture — disposing the old one — whenever the resolved color actually changes. This observer is not created at all when `color` is set.
+- Cleanup on effect teardown: removes the `pointermove` and `resize` listeners, cancels the animation frame, disconnects the `MutationObserver`, removes the renderer's canvas from the DOM, and disposes the renderer, geometry, material, and texture.
+- No `prefers-reduced-motion` handling — the render loop and pointer tracking run regardless of user preference.

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

@@ -1,6 +1,6 @@
 # Dock
 
-A macOS-style dock component with icon magnification on hover.
+An icon dock component whose items magnify smoothly as the cursor approaches.
 
 ## Components
 

package/dist/fancy-ui/editorial-engine/EditorialEngine.test.d.ts

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

package/dist/fancy-ui/editorial-engine/EditorialEngine.test.js

@@ -0,0 +1,54 @@
+import { render, cleanup } from "@testing-library/svelte";
+import { afterEach, beforeEach, describe, it, expect } from "vitest";
+import EditorialEngine from "./EditorialEngine.svelte";
+// The real engine measures text via @chenglou/pretext, which needs a canvas
+// 2d context or OffscreenCanvas — neither exists under jsdom
+// (HTMLCanvasElement.prototype.getContext is mocked to return null in
+// src/test-setup.ts). Stubbing `document.fonts.ready` with a promise that
+// never resolves keeps the component pinned on its pre-engine fallback
+// branch (the only branch that's meaningfully testable under jsdom) instead
+// of letting the effect's `.then()` handler call into pretext and throw.
+function stubNeverReadyFonts() {
+    Object.defineProperty(document, "fonts", {
+        configurable: true,
+        writable: true,
+        value: { ready: new Promise(() => { }) },
+    });
+}
+describe("EditorialEngine", () => {
+    beforeEach(stubNeverReadyFonts);
+    afterEach(cleanup);
+    it("mounts and renders the stage without throwing", () => {
+        const { container } = render(EditorialEngine);
+        expect(container.querySelector(".ee-stage")).toBeTruthy();
+    });
+    it("applies custom class names to the stage", () => {
+        const { container } = render(EditorialEngine, { props: { class: "my-stage" } });
+        const stage = container.querySelector(".ee-stage");
+        expect(stage.className).toContain("my-stage");
+    });
+    it("sets the font-family style from the fontFamily prop", () => {
+        const { container } = render(EditorialEngine, { props: { fontFamily: "Georgia, serif" } });
+        const stage = container.querySelector(".ee-stage");
+        expect(stage.style.fontFamily).toContain("Georgia");
+    });
+    it("renders the pre-engine fallback with the headline and body before the engine is ready", () => {
+        const { container } = render(EditorialEngine, {
+            props: { headline: "HELLO WORLD", body: "Some body copy." },
+        });
+        const fallback = container.querySelector(".ee-fallback");
+        expect(fallback).toBeTruthy();
+        expect(fallback?.querySelector("h2")?.textContent).toBe("HELLO WORLD");
+        expect(fallback?.querySelector("p")?.textContent).toBe("Some body copy.");
+    });
+    it("does not carry the ready class while pretext has not measured yet", () => {
+        const { container } = render(EditorialEngine);
+        const stage = container.querySelector(".ee-stage");
+        expect(stage.classList.contains("ready")).toBe(false);
+    });
+    it("unmounts cleanly", () => {
+        const { container, unmount } = render(EditorialEngine);
+        expect(() => unmount()).not.toThrow();
+        expect(container.querySelector(".ee-stage")).toBeFalsy();
+    });
+});

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

@@ -4,6 +4,8 @@
 	import {
 		type ColorRGB,
 		type Pointer,
+		type FluidCursorHandle,
+		type FluidRenderLevel,
 		pointerPrototype,
 		hexToRgb,
 		HSVtoRGB,
@@ -46,6 +48,14 @@
 		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;
 	}
 
 	let {
@@ -76,6 +86,7 @@
 		contained = true,
 		hdr = false,
 		hdrBoost = 1.5,
+		onReady,
 	}: Props = $props();
 
 	const clampedColorIntensity = Math.max(0, Math.min(1, colorIntensity));
@@ -157,6 +168,31 @@
 		return cleanup;
 	}
 
+	// Inert handle for environments where no renderer came up at all, so a
+	// consumer waiting on onReady can tell "unsupported" from "still starting".
+	const noRendererHandle: FluidCursorHandle = {
+		moveTo() {},
+		penUp() {},
+		burst() {},
+		renderLevel: "none",
+	};
+
+	// Hand the handle to the consumer. Guarded because the WebGPU path invokes
+	// this inside its startup promise chain: an exception from the callback would
+	// otherwise be caught as a WebGPU setup failure, retrying WebGL on a canvas
+	// already claimed by WebGPU and dropping the registered cleanup. Re-thrown
+	// asynchronously so it still surfaces as an unhandled error.
+	function notifyReady(handle: FluidCursorHandle) {
+		if (!onReady) return;
+		try {
+			onReady(handle);
+		} catch (error) {
+			queueMicrotask(() => {
+				throw error;
+			});
+		}
+	}
+
 	onMount(() => {
 		const canvas = canvasRef;
 		if (!canvas) return;
@@ -209,23 +245,26 @@
 				splatOnMount,
 				generateColor,
 			})
-				.then((cleanup) => {
+				.then((handle) => {
 					if (disposed) {
-						cleanup?.();
+						handle?.cleanup();
 						return;
 					}
 					// A newer singleton instance mounted while we were starting up:
 					// registering now would destroy it (newest-mount-wins would
 					// invert). Discard this stale completion instead.
 					if (!allowMultiple && mountToken !== mountCounter) {
-						cleanup?.();
+						handle?.cleanup();
 						return;
 					}
-					if (!cleanup) {
+					if (!handle) {
+						// WebGPU unavailable: the WebGL fallback surfaces its own
+						// handle through onReady.
 						activeCleanup = startWebGl() ?? null;
 						return;
 					}
-					activeCleanup = registerInstance(cleanup);
+					activeCleanup = registerInstance(handle.cleanup);
+					notifyReady(handle);
 				})
 				.catch((error) => {
 					// Unexpected failure while wiring the WebGPU path: fall back
@@ -245,9 +284,24 @@
 
 		// WebGL engine path (default, and fallback when WebGPU is missing).
 		function startWebGl(): (() => void) | undefined {
+			// Wide-gamut probe result, surfaced through the handle's renderLevel.
+			let renderLevel: FluidRenderLevel = "webgl-sdr";
+			// Dedicated synthetic pointer driven programmatically through the
+			// handle. It lives alongside the mouse pointer in the same list, so
+			// applyInputs splats both and the two inputs coexist. Only created
+			// when a consumer asked for the handle: an unused extra pointer would
+			// still consume the shared fluidColors sequence in updateColors.
+			const autopilotPointer = onReady ? pointerPrototype() : null;
+			if (autopilotPointer) pointers.push(autopilotPointer);
+			let penWasUp = true;
+
 			// Get WebGL context
 			const context = getWebGLContext(canvas);
-			if (!context.gl || !context.ext) return;
+			if (!context.gl || !context.ext) {
+				// No renderer at all (WebGPU already failed if it was tried).
+				notifyReady(noRendererHandle);
+				return;
+			}
 
 			// These are guaranteed non-null after the check above
 			const gl = context.gl;
@@ -282,15 +336,24 @@
 
 				// HDR fallback: wide-gamut backbuffer when the WebGPU engine is
 				// unavailable. Colors are reinterpreted in P3 (more saturated).
+				// The property is read back because assigning an unsupported color
+				// space silently leaves the buffer in sRGB.
 				if (hdr && "drawingBufferColorSpace" in gl) {
 					try {
 						gl.drawingBufferColorSpace = "display-p3";
-						if (import.meta.env.DEV) {
-							console.info("[FluidCursor] HDR level: webgl-p3 (wide gamut fallback)");
+						if (gl.drawingBufferColorSpace === "display-p3") {
+							renderLevel = "webgl-p3";
 						}
 					} catch {
 						// Unsupported color space: buffer stays sRGB.
 					}
+					if (import.meta.env.DEV) {
+						console.info(
+							renderLevel === "webgl-p3"
+								? "[FluidCursor] HDR level: webgl-p3 (wide gamut fallback)"
+								: "[FluidCursor] HDR level: webgl-sdr (display-p3 drawing buffer rejected)"
+						);
+					}
 				}
 
 				const isWebGL2 = "drawBuffers" in gl;
@@ -1157,6 +1220,10 @@
 				if (colorUpdateTimer >= 1) {
 					colorUpdateTimer = wrap(colorUpdateTimer, 0, 1);
 					pointers.forEach((p) => {
+						// The synthetic pointer's color belongs to the handle: pulling
+						// from the generator here would advance the shared fluidColors
+						// index twice per update and overwrite explicit stroke colors.
+						if (p === autopilotPointer) return;
 						p.color = generateColor();
 					});
 				}
@@ -1467,6 +1534,49 @@
 				return delta;
 			}
 
+			// Programmatic drive surface (exposed through onReady).
+			//
+			// x,y in [0,1], top-left origin. `updatePointerMoveData` applies
+			// `texcoordY = 1 - posY / height`, so feeding it a top-left pixel Y
+			// yields the same path a real mouse event's clientY takes. This is the
+			// only Y flip on the WebGL path.
+			function autopilotMoveTo(x: number, y: number, color?: ColorRGB) {
+				if (!autopilotPointer) return;
+				const posX = x * canvas.width;
+				const posY = y * canvas.height;
+				if (penWasUp) {
+					// First move of a new stroke: reposition only (mirrors
+					// updatePointerDownData) so the jump from the previous stroke's
+					// end never draws a connecting streak.
+					penWasUp = false;
+					autopilotPointer.down = true;
+					autopilotPointer.moved = false;
+					autopilotPointer.texcoordX = posX / canvas.width;
+					autopilotPointer.texcoordY = 1 - posY / canvas.height;
+					autopilotPointer.prevTexcoordX = autopilotPointer.texcoordX;
+					autopilotPointer.prevTexcoordY = autopilotPointer.texcoordY;
+					autopilotPointer.deltaX = 0;
+					autopilotPointer.deltaY = 0;
+					// A stroke with no explicit color takes a fresh generated one, as
+					// a real pointer-down does: the prototype's black would inject
+					// invisible dye.
+					autopilotPointer.color = color ?? generateColor();
+					return;
+				}
+				updatePointerMoveData(autopilotPointer, posX, posY, color ?? autopilotPointer.color);
+			}
+			function autopilotPenUp() {
+				// `moved` is deliberately left alone: applyInputs consumes and clears
+				// it on the next frame, so clearing it here would swallow the final
+				// segment of a stroke finished synchronously before that frame.
+				penWasUp = true;
+				if (autopilotPointer) autopilotPointer.down = false;
+			}
+			// Top-left origin in, bottom-up texcoords out: flip y and negate dy.
+			function autopilotBurst(x: number, y: number, dx: number, dy: number, color: ColorRGB) {
+				splat(x, 1 - y, dx, -dy, color);
+			}
+
 			// Event Listeners
 			function handleMouseDown(e: MouseEvent) {
 				const pointer = pointers[0];
@@ -1582,7 +1692,18 @@
 				}
 			}
 
-			return registerInstance(cleanup);
+			// Register before notifying: a throwing callback must not cost us the
+			// cleanup registration (listeners, rAF loop and GL resources would
+			// otherwise outlive the component).
+			const dispose = registerInstance(cleanup);
+			notifyReady({
+				moveTo: autopilotMoveTo,
+				penUp: autopilotPenUp,
+				burst: autopilotBurst,
+				renderLevel,
+			});
+
+			return dispose;
 		}
 	});
 </script>

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

@@ -1,4 +1,4 @@
-import { type ColorRGB } from "./fluid-shared.js";
+import { type ColorRGB, type FluidCursorHandle } from "./fluid-shared.js";
 interface Props {
     simResolution?: number;
     dyeResolution?: number;
@@ -27,6 +27,14 @@ interface Props {
     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

@@ -127,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/fluid-shared.d.ts

@@ -38,3 +38,35 @@ export declare function correctRadius(radius: number, width: number, height: num
 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/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

@@ -1,4 +1,4 @@
-import { type ColorRGB } from "./fluid-shared.js";
+import { type ColorRGB, type FluidCursorHandle } from "./fluid-shared.js";
 export interface WebGpuFluidOptions {
     simResolution: number;
     dyeResolution: number;
@@ -23,7 +23,14 @@ export interface WebGpuFluidOptions {
 }
 /**
  * Full WebGPU setup for FluidCursor: engine + pointer wiring + rAF loop +
- * visibility pause + auto splats. Resolves with a cleanup function, or with
- * `null` when WebGPU is unavailable (caller falls back to the WebGL path).
+ * 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<(() => void) | null>;
+export declare function startWebGpuFluid(canvas: HTMLCanvasElement, opts: WebGpuFluidOptions): Promise<(FluidCursorHandle & {
+    cleanup(): void;
+}) | null>;