@jayf0x/fluidity-js 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +148 -0
- package/CONTRIBUTING.md +45 -0
- package/README.md +170 -94
- package/dist/globals.d.ts +7 -2
- package/dist/index.js +782 -740
- package/llms.txt +156 -0
- package/package.json +34 -6
package/llms.txt
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# fluidity-js
|
|
2
|
+
|
|
3
|
+
> WebGPU-first fluid simulation library for React. Real-time Navier-Stokes solver — text and image effects with hardware-accelerated fluid dynamics.
|
|
4
|
+
|
|
5
|
+
- npm: https://www.npmjs.com/package/@jayf0x/fluidity-js
|
|
6
|
+
- GitHub: https://github.com/jayf0x/fluidity
|
|
7
|
+
- Live demo: https://jayf0x.github.io/fluidity
|
|
8
|
+
- License: MIT
|
|
9
|
+
- Version: 0.2.2
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @jayf0x/fluidity-js
|
|
15
|
+
# bun add / yarn add / pnpm add also work
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Peer deps: react >=17, react-dom >=17
|
|
19
|
+
|
|
20
|
+
## Core concepts
|
|
21
|
+
|
|
22
|
+
- **WebGPU-first** with automatic fallback to WebGL2 → WebGL1
|
|
23
|
+
- Runs simulation in a **Web Worker** via OffscreenCanvas (configurable)
|
|
24
|
+
- Two render modes: `FluidText` (text as obstacle) and `FluidImage` (bitmap as obstacle)
|
|
25
|
+
- Navier-Stokes pipeline: advect velocity → advect density → curl/vorticity → splat → divergence → pressure solve → gradient subtract → display
|
|
26
|
+
|
|
27
|
+
## Quick start
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { FluidText, FluidImage } from '@jayf0x/fluidity-js';
|
|
31
|
+
|
|
32
|
+
// Fluid text that reacts to cursor
|
|
33
|
+
<FluidText text="Hello World" fontSize={140} color="#ffffff" />
|
|
34
|
+
|
|
35
|
+
// Fluid image with aurora algorithm
|
|
36
|
+
<FluidImage src="/hero.jpg" algorithm="aurora" />
|
|
37
|
+
|
|
38
|
+
// With preset and custom config
|
|
39
|
+
<FluidText text="Wicked" preset="neon" algorithm="glass" config={{ curl: 0.4 }} />
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## FluidText props
|
|
43
|
+
|
|
44
|
+
| Prop | Type | Default |
|
|
45
|
+
|------|------|---------|
|
|
46
|
+
| text | string | required |
|
|
47
|
+
| fontSize | number | 100 |
|
|
48
|
+
| color | string | '#ffffff' |
|
|
49
|
+
| fontFamily | string | 'sans-serif' |
|
|
50
|
+
| fontWeight | string\|number | 900 |
|
|
51
|
+
|
|
52
|
+
## FluidImage props
|
|
53
|
+
|
|
54
|
+
| Prop | Type | Default |
|
|
55
|
+
|------|------|---------|
|
|
56
|
+
| src | string | required |
|
|
57
|
+
| imageSize | string\|number | 'cover' |
|
|
58
|
+
| effect | number | 0 |
|
|
59
|
+
|
|
60
|
+
## Shared props (both components)
|
|
61
|
+
|
|
62
|
+
| Prop | Type | Default |
|
|
63
|
+
|------|------|---------|
|
|
64
|
+
| config | Partial<FluidConfig> | — |
|
|
65
|
+
| preset | PresetKey | — |
|
|
66
|
+
| algorithm | FluidAlgorithm | 'standard' |
|
|
67
|
+
| quality | FluidQuality | { dpr: 1, sim: 0.5 } |
|
|
68
|
+
| backgroundColor | string | '#0a0a0a' |
|
|
69
|
+
| backgroundSrc | string | — |
|
|
70
|
+
| backgroundSize | string\|number | 'cover' |
|
|
71
|
+
| isMouseEnabled | boolean | true |
|
|
72
|
+
| isWorkerEnabled | boolean | true |
|
|
73
|
+
| useWebGPU | boolean | true |
|
|
74
|
+
| className | string | — |
|
|
75
|
+
| style | CSSProperties | — |
|
|
76
|
+
|
|
77
|
+
## FluidHandle ref API
|
|
78
|
+
|
|
79
|
+
Access via `useRef<FluidHandle>()` and `ref` prop:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
const fluid = useRef<FluidHandle>(null);
|
|
83
|
+
<FluidText ref={fluid} text="Touch me" />
|
|
84
|
+
fluid.current?.splat(200, 200, 8, -4);
|
|
85
|
+
fluid.current?.updateConfig({ curl: 0.5 });
|
|
86
|
+
fluid.current?.reset();
|
|
87
|
+
fluid.current?.move({ x: 100, y: 100, strength: 2 });
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Algorithms
|
|
91
|
+
|
|
92
|
+
| Value | Effect |
|
|
93
|
+
|-------|--------|
|
|
94
|
+
| standard | Colour overlay + gentle refraction |
|
|
95
|
+
| glass | UV distortion only — bent glass |
|
|
96
|
+
| ink | Dense opaque pigment that accumulates |
|
|
97
|
+
| aurora | Velocity-field UV warp — liquid metal |
|
|
98
|
+
| ripple | Exaggerated normals + Fresnel rim |
|
|
99
|
+
|
|
100
|
+
## Presets
|
|
101
|
+
|
|
102
|
+
`calm` · `sand` · `wave` · `neon` · `smoke`
|
|
103
|
+
|
|
104
|
+
## FluidConfig options
|
|
105
|
+
|
|
106
|
+
| Key | Default | Description |
|
|
107
|
+
|-----|---------|-------------|
|
|
108
|
+
| densityDissipation | 0.992 | Ink persistence (0–1) |
|
|
109
|
+
| velocityDissipation | 0.93 | Velocity decay (0–1) |
|
|
110
|
+
| pressureIterations | 1 | Jacobi iterations |
|
|
111
|
+
| curl | 0.0001 | Vorticity / swirl strength |
|
|
112
|
+
| splatRadius | 0.004 | Brush radius |
|
|
113
|
+
| splatForce | 0.91 | Brush force |
|
|
114
|
+
| refraction | 0.25 | Background warp strength |
|
|
115
|
+
| specularExp | 1.01 | Specular sharpness |
|
|
116
|
+
| shine | 0.01 | Highlight intensity |
|
|
117
|
+
| waterColor | [0,0,0] | Base fluid RGB (0–1 each) |
|
|
118
|
+
| glowColor | [0.7,0.85,1.0] | Specular/glow RGB (0–1 each) |
|
|
119
|
+
| warpStrength | 0.015 | UV warp (aurora algorithm) |
|
|
120
|
+
|
|
121
|
+
## Quality control
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
// dpr: canvas backing resolution fraction (0.1–1)
|
|
125
|
+
// sim: simulation FBO size fraction (0.1–1)
|
|
126
|
+
<FluidText text="hello" quality={{ dpr: 0.75, sim: 0.25 }} />
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Both axes are independent and reactive at runtime.
|
|
130
|
+
|
|
131
|
+
## TypeScript types
|
|
132
|
+
|
|
133
|
+
All types are globally ambient — no import needed:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
// Available globally after installing the package:
|
|
137
|
+
FluidConfig
|
|
138
|
+
FluidHandle
|
|
139
|
+
FluidAlgorithm // 'standard'|'glass'|'ink'|'aurora'|'ripple'
|
|
140
|
+
FluidQuality // { dpr: number; sim: number }
|
|
141
|
+
PresetKey // 'calm'|'sand'|'wave'|'neon'|'smoke'
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Architecture summary
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
React component (FluidText / FluidImage)
|
|
148
|
+
└── useFluid hook
|
|
149
|
+
└── FluidController
|
|
150
|
+
├── [worker mode] Web Worker → FluidSimulation (OffscreenCanvas)
|
|
151
|
+
└── [main mode] FluidSimulation directly
|
|
152
|
+
└── WebGPU path (FluidSimulation.create())
|
|
153
|
+
└── WebGL2 / WebGL1 fallback
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Worker transfer: zero-copy OffscreenCanvas transfer. Background images transferred as ImageBitmap (zero-copy). Safe to destroy/recreate under React StrictMode.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jayf0x/fluidity-js",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.3",
|
|
4
|
+
"description": "WebGPU-first real-time Navier-Stokes fluid simulation for React — interactive water, ink, glass, aurora, and ripple effects on text and images. Falls back to WebGL2/WebGL1. Runs in a Web Worker.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "./dist/index.js",
|
|
7
7
|
"exports": {
|
|
@@ -13,7 +13,10 @@
|
|
|
13
13
|
"types": "./src/index.d.ts",
|
|
14
14
|
"files": [
|
|
15
15
|
"dist",
|
|
16
|
-
"README.md"
|
|
16
|
+
"README.md",
|
|
17
|
+
"AGENTS.md",
|
|
18
|
+
"llms.txt",
|
|
19
|
+
"CONTRIBUTING.md"
|
|
17
20
|
],
|
|
18
21
|
"sideEffects": false,
|
|
19
22
|
"scripts": {
|
|
@@ -30,12 +33,37 @@
|
|
|
30
33
|
"publish:npm": "bash ./scripts/publish-npm.sh"
|
|
31
34
|
},
|
|
32
35
|
"keywords": [
|
|
36
|
+
"webgpu",
|
|
33
37
|
"webgl",
|
|
38
|
+
"webgl2",
|
|
34
39
|
"fluid",
|
|
35
|
-
"simulation",
|
|
40
|
+
"fluid-simulation",
|
|
41
|
+
"fluid-dynamics",
|
|
42
|
+
"navier-stokes",
|
|
36
43
|
"react",
|
|
37
44
|
"animation",
|
|
38
|
-
"canvas"
|
|
45
|
+
"canvas",
|
|
46
|
+
"water-effect",
|
|
47
|
+
"ink-effect",
|
|
48
|
+
"glass-effect",
|
|
49
|
+
"aurora-effect",
|
|
50
|
+
"ripple-effect",
|
|
51
|
+
"interactive-animation",
|
|
52
|
+
"canvas-animation",
|
|
53
|
+
"hover-effect",
|
|
54
|
+
"text-animation",
|
|
55
|
+
"image-effect",
|
|
56
|
+
"offscreencanvas",
|
|
57
|
+
"web-worker",
|
|
58
|
+
"typescript",
|
|
59
|
+
"react-component",
|
|
60
|
+
"vorticity",
|
|
61
|
+
"gpu",
|
|
62
|
+
"shader",
|
|
63
|
+
"glsl",
|
|
64
|
+
"wgsl",
|
|
65
|
+
"visual-effect",
|
|
66
|
+
"creative-coding"
|
|
39
67
|
],
|
|
40
68
|
"author": "https://github.com/jayf0x",
|
|
41
69
|
"license": "MIT",
|
|
@@ -46,7 +74,7 @@
|
|
|
46
74
|
"bugs": {
|
|
47
75
|
"url": "https://github.com/jayf0x/fluidity/issues"
|
|
48
76
|
},
|
|
49
|
-
"homepage": "https://github.
|
|
77
|
+
"homepage": "https://jayf0x.github.io/fluidity",
|
|
50
78
|
"peerDependencies": {
|
|
51
79
|
"react": ">=17.0.0",
|
|
52
80
|
"react-dom": ">=17.0.0"
|