@jayf0x/fluidity-js 0.1.5 → 0.1.7

package/README.md

@@ -1,56 +1,62 @@
-# fluidity-js
-
-**WebGL fluid simulation for React — interactive text and image effects powered by Navier-Stokes.**
+# fluidity-js - 🔥Upgrade your UX🔥
 
 [![npm](https://img.shields.io/npm/v/@jayf0x/fluidity-js)](https://www.npmjs.com/package/@jayf0x/fluidity-js)
 [![license](https://img.shields.io/npm/l/@jayf0x/fluidity-js)](./LICENSE)
 [![size](https://img.shields.io/bundlephobia/minzip/@jayf0x/fluidity-js)](https://bundlephobia.com/package/@jayf0x/fluidity-js)
 
-[**Live demo →**](https://jayf0x.github.io/fluidity)
-
----
+ <a href="https://jayf0x.github.io/fluidity">
+  <p align="center" title='Try if you can make this effect.'>
+      <img align="center" src="assets/preview.gif" alt="preview" height="300px"/>
+  </p>
 
-## Install
+  <p align="center">
+    <strong>
+    Live demo →
+    </strong>
+  </p>
+</a>
 
 ```bash
-npm i @jayf0x/fluidity-js
+bun add @jayf0x/fluidity-js
+yarn install @jayf0x/fluidity-js
+pnpm install @jayf0x/fluidity-js
 ```
 
-Requires React ≥ 17 and WebGL (WebGL2 recommended; WebGL1 supported as fallback).
+> uses latest `WebGPU` 🔥 With WebGL2 or WebGL1 supported as fallback
 
 ---
 
-## Usage
+## React examples
 
-### FluidText
+**FluidText:**
 
 ```tsx
 import { FluidText } from '@jayf0x/fluidity-js';
 
-export function Hero() {
+export const FancyHero = () => {
   return (
     <div style={{ width: '100%', height: 300 }}>
-      <FluidText text="hello" fontSize={120} color="#ffffff" />
+      <FluidText text="🔥 SupportsEmoji 🔥" fontSize={120} color="#ffffff" />
     </div>
   );
-}
+};
 ```
 
-### FluidImage
+**FluidImage:**
 
 ```tsx
 import { FluidImage } from '@jayf0x/fluidity-js';
 
 export function Cover() {
   return (
-    <div style={{ width: '100%', height: '100vh' }}>
+    <div className="size-full">
       <FluidImage src="/hero.jpg" algorithm="aurora" />
     </div>
   );
 }
 ```
 
-### Ref API
+**Handle custom events with a ref**
 
 ```tsx
 import { useRef } from 'react';
@@ -58,13 +64,10 @@ import { useRef } from 'react';
 import { FluidText } from '@jayf0x/fluidity-js';
 
 export function Interactive() {
-  const fluid = useRef<FluidHandle>(null);
-
+  const fluidRef = useRef<FluidHandle>(null);
   return (
     <>
-      <div style={{ width: '100%', height: 300 }}>
-        <FluidText ref={fluid} text="fluid" fontSize={120} color="#fff" />
-      </div>
+      <FluidText ref={fluidRef} isMouseEnabled={false} text="Amazing" fontSize={120} color="#fff" />
       <button onClick={() => fluid.current?.reset()}>Reset</button>
       <button onClick={() => fluid.current?.updateConfig({ curl: 0.3 })}>Swirl</button>
     </>
@@ -72,9 +75,7 @@ export function Interactive() {
 }
 ```
 
-`FluidHandle` is a global type — no import needed.
-
-More examples → [`demo/src/examples/`](./demo/src/examples/)
+Official examples → [`demo/src/examples/`](./demo/src/examples/)
 
 ---
 
@@ -100,18 +101,19 @@ More examples → [`demo/src/examples/`](./demo/src/examples/)
 
 ### Shared props
 
-| Prop              | Type                   | Default      |
-| ----------------- | ---------------------- | ------------ |
-| `config`          | `Partial<FluidConfig>` | —            |
-| `preset`          | `PresetKey`            | —            |
-| `algorithm`       | `FluidAlgorithm`       | `'standard'` |
-| `backgroundColor` | `string`               | `'#0a0a0a'`  |
-| `backgroundSrc`   | `string`               | —            |
-| `backgroundSize`  | `string \| number`     | `'cover'`    |
-| `isMouseEnabled`  | `boolean`              | `true`       |
-| `isWorkerEnabled` | `boolean`              | `true`       |
-| `className`       | `string`               | —            |
-| `style`           | `CSSProperties`        | —            |
+| Prop              | Type                   | Default                |
+| ----------------- | ---------------------- | ---------------------- |
+| `config`          | `Partial<FluidConfig>` | —                      |
+| `preset`          | `PresetKey`            | —                      |
+| `algorithm`       | `FluidAlgorithm`       | `'standard'`           |
+| `quality`         | `FluidQuality`         | `{ dpr: 1, sim: 0.5 }` |
+| `backgroundColor` | `string`               | `'#0a0a0a'`            |
+| `backgroundSrc`   | `string`               | —                      |
+| `backgroundSize`  | `string \| number`     | `'cover'`              |
+| `isMouseEnabled`  | `boolean`              | `true`                 |
+| `isWorkerEnabled` | `boolean`              | `true`                 |
+| `className`       | `string`               | —                      |
+| `style`           | `CSSProperties`        | —                      |
 
 ---
 
@@ -132,6 +134,31 @@ More examples → [`demo/src/examples/`](./demo/src/examples/)
 
 ---
 
+## Quality
+
+`quality` controls rendering resolution on two independent axes. Both props are reactive — you can adjust them at runtime.
+
+| Field | Range   | Default | Description                                                                                                                                 |
+| ----- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dpr` | 0.1 – 1 | `1`     | Canvas backing resolution as a fraction of `devicePixelRatio`. `0.5` on a Retina screen renders at 1× instead of 2×, saving ~75% fill rate. |
+| `sim` | 0.1 – 1 | `0.5`   | Simulation FBO size as a fraction of canvas size. Lower = cheaper GPU, less fluid detail.                                                   |
+
+```tsx
+<FluidText text="hello" quality={{ dpr: 0.75, sim: 0.25 }} />
+```
+
+`dpr` and `sim` are independent — you can run a sharp canvas at a coarser simulation:
+
+```tsx
+// Sharp display, cheap simulation
+<FluidImage src="/hero.jpg" quality={{ dpr: 1, sim: 0.2 }} />
+
+// Lower display res, full simulation quality
+<FluidImage src="/hero.jpg" quality={{ dpr: 0.5, sim: 1 }} />
+```
+
+---
+
 ## FluidConfig
 
 | Key                   | Default            | Description                               |

package/dist/globals.d.ts

@@ -2,6 +2,18 @@
 
 type FluidAlgorithm = 'standard' | 'glass' | 'ink' | 'aurora' | 'ripple';
 
+/**
+ * Granular performance/quality controls. Both axes are independent — you can
+ * run a sharp display at a coarser simulation, or vice versa.
+ * Reactive: changes after mount are applied on the next animation frame.
+ */
+interface FluidQuality {
+  /** devicePixelRatio multiplier for canvas backing resolution. Range [0.1, 1]. Default 1 (native). On Retina, 0.5 → 1× pixels (75% less fill). */
+  dpr?: number;
+  /** Simulation FBO size as a fraction of canvas size. Range [0.1, 1]. Default 0.5 (current behavior). Higher = more fluid detail, more GPU. */
+  sim?: number;
+}
+
 interface FluidConfig {
   densityDissipation: number;
   velocityDissipation: number;
@@ -22,8 +34,8 @@ type PresetKey = 'calm' | 'sand' | 'wave' | 'neon' | 'smoke';
 
 interface FluidHandle {
   reset(): void;
-  move(opts: { x: number; y: number; strength?: number }): void;
-  splat(x: number, y: number, vx: number, vy: number, strength?: number): void;
+  move(x: number, y: number, strength?: number): void;
+  splat(x: number, y: number, velocityX: number, velocityY: number, strength?: number): void;
   updateConfig(config: Partial<FluidConfig>): void;
 }
 
@@ -33,6 +45,7 @@ interface FluidBaseProps {
   config?: Partial<FluidConfig>;
   isMouseEnabled?: boolean;
   isWorkerEnabled?: boolean;
+  quality?: FluidQuality;
   preset?: PresetKey;
   algorithm?: FluidAlgorithm;
   backgroundColor?: string;