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 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
- # Temporary Holding Version
1
+ # ThanosFx
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/thanosfx.svg)](https://www.npmjs.com/package/thanosfx)
4
+ [![license](https://img.shields.io/npm/l/thanosfx.svg)](./LICENSE)
5
+ [![zero dependencies](https://img.shields.io/badge/runtime_dependencies-0-brightgreen.svg)](./package.json)
6
+ [![live demo](https://img.shields.io/badge/demo-GitHub%20Pages-111111.svg)](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
+ [![ThanosFx collision, attract and dissolve modes](https://ehsania.github.io/thanosfx/media/three-modes-poster.png)](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