thanosfx 0.0.0-stage → 0.1.0
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 +61 -0
- package/LICENSE +21 -0
- package/README.md +259 -2
- package/dist/chunk-CKJFWVQU.js +858 -0
- package/dist/chunk-CKJFWVQU.js.map +1 -0
- package/dist/index.cjs +877 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +14 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/react.cjs +887 -0
- package/dist/react.cjs.map +1 -0
- package/dist/react.d.cts +17 -0
- package/dist/react.d.ts +17 -0
- package/dist/react.js +31 -0
- package/dist/react.js.map +1 -0
- package/dist/types-BoMZtjIa.d.cts +57 -0
- package/dist/types-BoMZtjIa.d.ts +57 -0
- package/llms.txt +311 -0
- package/package.json +108 -4
package/AGENTS.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# ThanosFx repository guide
|
|
2
|
+
|
|
3
|
+
This file is for agents working on the ThanosFx repository. For library usage and API details, read [`llms.txt`](./llms.txt).
|
|
4
|
+
|
|
5
|
+
## Stack
|
|
6
|
+
|
|
7
|
+
- TypeScript
|
|
8
|
+
- Vite for the demo
|
|
9
|
+
- tsup for the library build
|
|
10
|
+
- Vitest for tests
|
|
11
|
+
- ESLint and Prettier
|
|
12
|
+
|
|
13
|
+
## Commands
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm install
|
|
17
|
+
npm run dev # demo at http://localhost:5173/
|
|
18
|
+
npm run verify # format, lint, typecheck and tests
|
|
19
|
+
npm run build # library + demo
|
|
20
|
+
npm run build:lib
|
|
21
|
+
npm run build:demo
|
|
22
|
+
npm test
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Layout
|
|
26
|
+
|
|
27
|
+
- `src/` — the library.
|
|
28
|
+
- `src/core/` — capture, WebGL, options, effects and the run loop.
|
|
29
|
+
- `src/core/effects/burn.ts` — burn particles, collision and attraction.
|
|
30
|
+
- `src/core/effects/assemble.ts` — burn played backwards.
|
|
31
|
+
- `demo/` — the single-page site.
|
|
32
|
+
- `demo/quickstart.ts` — agent prompt panels.
|
|
33
|
+
- `demo/recycle.ts` — live task-list demo.
|
|
34
|
+
- `demo/tuner.ts` — controls and generated code.
|
|
35
|
+
- `demo/video/` — development-only video capture harness.
|
|
36
|
+
- `tests/` — Vitest tests.
|
|
37
|
+
- `llms.txt` — agent-facing library guide.
|
|
38
|
+
- `demo/public/media/` — demo videos and posters.
|
|
39
|
+
|
|
40
|
+
## Product constraints
|
|
41
|
+
|
|
42
|
+
- Only two effects: `burn` and `assemble`.
|
|
43
|
+
- No preset system.
|
|
44
|
+
- One demo page. Do not split the landing page and playground.
|
|
45
|
+
- The Quick Start section is framework-agnostic.
|
|
46
|
+
- Keep the page theme-aware and accessible.
|
|
47
|
+
- WebGL2 is required. Reduced motion falls back to a short fade.
|
|
48
|
+
- Keep runtime dependencies at zero.
|
|
49
|
+
- The video capture harness is not part of the production build.
|
|
50
|
+
- GitHub Pages is served from `/thanosfx/` via `VITE_BASE_PATH`.
|
|
51
|
+
|
|
52
|
+
## Before finishing
|
|
53
|
+
|
|
54
|
+
Run:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
npm run verify
|
|
58
|
+
npm run build
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Check the light and dark themes, desktop and mobile layouts, the Quick Start copy buttons, and the live demo.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ThanosFx contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,260 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ThanosFx
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/thanosfx)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
[](./package.json)
|
|
6
|
+
[](https://ehsania.github.io/thanosfx/)
|
|
7
|
+
|
|
8
|
+
WebGL burn and assemble effects for real DOM elements.
|
|
9
|
+
|
|
10
|
+
- **Burn** — the element turns to carbon and falls away as dust. The dust can bounce off page elements, be pulled into a target, or drift away.
|
|
11
|
+
- **Assemble** — burn played backwards. Dust gathers and the element becomes visible.
|
|
12
|
+
|
|
13
|
+
Every effect captures the real element as a texture, draws it on a full-screen WebGL2 overlay, and animates it with a GPU shader. Text, borders, gradients, and images stay exactly as they render on the page.
|
|
14
|
+
|
|
15
|
+
## Demo
|
|
16
|
+
|
|
17
|
+
[Live demo](https://ehsania.github.io/thanosfx/) · [Dark video](https://ehsania.github.io/thanosfx/media/three-modes.mp4) · [Light video](https://ehsania.github.io/thanosfx/media/three-modes-light.mp4)
|
|
18
|
+
|
|
19
|
+
[](https://ehsania.github.io/thanosfx/)
|
|
20
|
+
|
|
21
|
+
## Agent guide
|
|
22
|
+
|
|
23
|
+
Point a coding agent at [`llms.txt`](./llms.txt). The same file ships with the package at `node_modules/thanosfx/llms.txt`.
|
|
24
|
+
|
|
25
|
+
Repository contributors can start with [`AGENTS.md`](./AGENTS.md).
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
npm install thanosfx
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
React is optional and only needed for the `thanosfx/react` entry point:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
npm install react
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { burn } from "thanosfx";
|
|
43
|
+
|
|
44
|
+
const card = document.querySelector<HTMLElement>(".card");
|
|
45
|
+
if (!card) throw new Error("Missing .card");
|
|
46
|
+
|
|
47
|
+
const handle = burn(card, {
|
|
48
|
+
duration: 1700,
|
|
49
|
+
density: 0.9,
|
|
50
|
+
gravity: 3200,
|
|
51
|
+
spread: 210,
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
handle.promise.then(() => {
|
|
55
|
+
console.log("gone");
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`burn` and `assemble` share the same one-shot API.
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import { assemble } from "thanosfx";
|
|
63
|
+
|
|
64
|
+
const fresh = document.querySelector<HTMLElement>(".new-card");
|
|
65
|
+
if (!fresh) throw new Error("Missing .new-card");
|
|
66
|
+
|
|
67
|
+
assemble(fresh, {
|
|
68
|
+
duration: 1800,
|
|
69
|
+
removeTarget: false,
|
|
70
|
+
}).promise.then(() => {
|
|
71
|
+
console.log("restored");
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Particle modes
|
|
76
|
+
|
|
77
|
+
Burn has three useful configurations:
|
|
78
|
+
|
|
79
|
+
| Mode | Options | Behavior |
|
|
80
|
+
| ------------- | ---------------------------------------------- | --------------------------------------------- |
|
|
81
|
+
| **Collision** | `collision: true`, `collideWith: elements` | Dust bounces off the listed elements. |
|
|
82
|
+
| **Attract** | `attractTo`, `attractStrength`, `attractSwirl` | Dust spirals into an element, rect, or point. |
|
|
83
|
+
| **Dissolve** | `collision: false`, no `attractTo` | Dust falls and drifts with no target. |
|
|
84
|
+
|
|
85
|
+
### Collision
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
const cards = [...document.querySelectorAll<HTMLElement>(".task")];
|
|
89
|
+
const card = cards[0];
|
|
90
|
+
if (!card) throw new Error("Missing .task");
|
|
91
|
+
|
|
92
|
+
await burn(card, {
|
|
93
|
+
collision: true,
|
|
94
|
+
collideWith: cards.filter((element) => element !== card),
|
|
95
|
+
}).promise;
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Attract
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
const bin = document.querySelector<HTMLElement>(".recycle-bin")!;
|
|
102
|
+
|
|
103
|
+
await burn(card, {
|
|
104
|
+
attractTo: bin,
|
|
105
|
+
attractStrength: 0.9,
|
|
106
|
+
attractSwirl: 0.3,
|
|
107
|
+
collision: false,
|
|
108
|
+
}).promise;
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`attractTo` accepts an element, a `DOMRect`, a rect object, a `[x, y, width, height]` tuple, or an `{ x, y }` point. When the dust reaches the target, it spreads across a small arrival radius instead of collapsing into a single pixel.
|
|
112
|
+
|
|
113
|
+
### Dissolve
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
await burn(card, {
|
|
117
|
+
collision: false,
|
|
118
|
+
gravity: 450,
|
|
119
|
+
spread: 240,
|
|
120
|
+
lift: 210,
|
|
121
|
+
}).promise;
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Assemble from a source
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
const addButton = document.querySelector<HTMLElement>(".add-task")!;
|
|
128
|
+
const list = document.querySelector<HTMLElement>(".task-list")!;
|
|
129
|
+
const fresh = document.createElement("div");
|
|
130
|
+
fresh.className = "task";
|
|
131
|
+
list.prepend(fresh);
|
|
132
|
+
|
|
133
|
+
await assemble(fresh, {
|
|
134
|
+
attractTo: addButton,
|
|
135
|
+
attractStrength: 0.9,
|
|
136
|
+
attractSwirl: 0.3,
|
|
137
|
+
collision: false,
|
|
138
|
+
removeTarget: false,
|
|
139
|
+
}).promise;
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## API
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { assemble, burn, createEffect, effectNames, playEffect } from "thanosfx";
|
|
146
|
+
import type { AttractorLike, EffectHandle, EffectName, EffectOptions, RectLike } from "thanosfx";
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- `burn(target, options)` starts a burn effect.
|
|
150
|
+
- `assemble(target, options)` starts the reverse effect.
|
|
151
|
+
- `playEffect(target, effect, options)` starts an effect by name.
|
|
152
|
+
- `createEffect(target, effect, options)` is the generic form of `playEffect`.
|
|
153
|
+
- `effectNames` is `["burn", "assemble"]`.
|
|
154
|
+
- Every call returns an `EffectHandle` with `promise` and `cancel()`.
|
|
155
|
+
|
|
156
|
+
## Options
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
interface EffectOptions {
|
|
160
|
+
duration?: number; // ms
|
|
161
|
+
removeTarget?: boolean; // defaults depend on effect
|
|
162
|
+
reducedMotion?: "auto" | "allow" | "reduce";
|
|
163
|
+
dpr?: number;
|
|
164
|
+
|
|
165
|
+
// Burn / assemble
|
|
166
|
+
burnMs?: number;
|
|
167
|
+
density?: number;
|
|
168
|
+
gravity?: number;
|
|
169
|
+
bounce?: number;
|
|
170
|
+
spread?: number;
|
|
171
|
+
life?: number;
|
|
172
|
+
friction?: number;
|
|
173
|
+
lift?: number;
|
|
174
|
+
particleScale?: number;
|
|
175
|
+
embers?: boolean;
|
|
176
|
+
collision?: boolean;
|
|
177
|
+
mode?: "sweep" | "instant";
|
|
178
|
+
collideWith?: RectLike[];
|
|
179
|
+
attractTo?: AttractorLike | null;
|
|
180
|
+
attractStrength?: number; // 0–1, higher pulls earlier in each particle's life
|
|
181
|
+
attractSwirl?: number; // sideways curl along the path to the target
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## React
|
|
186
|
+
|
|
187
|
+
```tsx
|
|
188
|
+
import { useRef } from "react";
|
|
189
|
+
import { useThanosFx } from "thanosfx/react";
|
|
190
|
+
import type { EffectName } from "thanosfx";
|
|
191
|
+
|
|
192
|
+
export function DeleteCard({ effect }: { effect: EffectName }) {
|
|
193
|
+
const ref = useRef<HTMLDivElement>(null);
|
|
194
|
+
const { play, cancel } = useThanosFx(ref, effect, { duration: 1700 });
|
|
195
|
+
|
|
196
|
+
return (
|
|
197
|
+
<div ref={ref}>
|
|
198
|
+
<button onClick={play}>Delete</button>
|
|
199
|
+
<button onClick={cancel}>Cancel</button>
|
|
200
|
+
</div>
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## How it works
|
|
206
|
+
|
|
207
|
+
1. **Capture** — the element is rasterized to a canvas via an SVG `foreignObject` snapshot. `html2canvas` is used automatically if present.
|
|
208
|
+
2. **Texture** — the canvas is uploaded to a WebGL2 texture with `UNPACK_FLIP_Y_WEBGL`.
|
|
209
|
+
3. **Render** — a shader draws a quad over the element's screen rect. Burn also draws a point-sprite particle system that can collide with page elements and spiral into an attractor.
|
|
210
|
+
4. **Cleanup** — the overlay and GPU resources are released, then the element is removed, or restored for `assemble`.
|
|
211
|
+
|
|
212
|
+
Reduced motion falls back to a short opacity fade. WebGL2 is required.
|
|
213
|
+
|
|
214
|
+
## Development
|
|
215
|
+
|
|
216
|
+
```sh
|
|
217
|
+
npm install
|
|
218
|
+
npm run dev # demo site at http://localhost:5173/
|
|
219
|
+
npm run build # library + demo
|
|
220
|
+
npm run build:lib # library only
|
|
221
|
+
npm run build:demo # demo only
|
|
222
|
+
npm run preview
|
|
223
|
+
npm test
|
|
224
|
+
npm run typecheck
|
|
225
|
+
npm run lint
|
|
226
|
+
npm run format:check
|
|
227
|
+
npm run verify # format, lint, typecheck and tests together
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
The `demo/video/` page is a development-only capture harness. It is not part of the production build.
|
|
231
|
+
|
|
232
|
+
## Deployment
|
|
233
|
+
|
|
234
|
+
The demo deploys to GitHub Pages on every push to `main` through `.github/workflows/pages.yml`.
|
|
235
|
+
|
|
236
|
+
- Pages source: **GitHub Actions**
|
|
237
|
+
- Site URL: <https://ehsania.github.io/thanosfx/>
|
|
238
|
+
- Base path: `/thanosfx/` via `VITE_BASE_PATH`
|
|
239
|
+
|
|
240
|
+
To test the Pages build locally:
|
|
241
|
+
|
|
242
|
+
```sh
|
|
243
|
+
VITE_BASE_PATH=/thanosfx/ npm run build:demo
|
|
244
|
+
npx vite preview --base /thanosfx/
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## Release
|
|
248
|
+
|
|
249
|
+
The package publishes to npm from tags that start with `v` through `.github/workflows/release.yml`.
|
|
250
|
+
|
|
251
|
+
```sh
|
|
252
|
+
npm version patch
|
|
253
|
+
git push --follow-tags
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Add an `NPM_TOKEN` repository secret before the first automated release.
|
|
257
|
+
|
|
258
|
+
## License
|
|
259
|
+
|
|
260
|
+
MIT
|