hz-particles 1.0.15 → 1.3.0

package/README.md

@@ -1,59 +1,239 @@
 # hz-particles
 
+**Prompt-generated, real-time WebGPU FX for Three.js and React Three Fiber.**
+
+Design particle effects in the HZ editor — by hand or **from a prompt** — export them as
+`JSON` / `.hzfx` presets, and render them **faithfully** in your app with the *same* WebGPU
+engine the editor uses. What you design is exactly what renders.
+
 [![npm version](https://img.shields.io/npm/v/hz-particles.svg)](https://www.npmjs.com/package/hz-particles)
 [![license](https://img.shields.io/npm/l/hz-particles.svg)](https://github.com/jguyet/particle-system/blob/main/LICENSE)
 [![WebGPU](https://img.shields.io/badge/WebGPU-required-blue.svg)](https://caniuse.com/webgpu)
 
-A high-performance WebGPU particle engine for the web. Use it as a standalone WebGPU renderer or as a plug-and-play React Three Fiber component.
+```tsx
+import { HZFaithfulFX } from 'hz-particles/r3f';
+import firePreset from './fire.json';
+
+export function Scene() {
+  return <HZFaithfulFX preset={firePreset} position={[0, 1, 0]} />;
+}
+```
+
+<!-- TODO: fill in the real public URLs (see PR / message) -->
+- **Prompt FX generator / editor:** https://YOUR-SITE
+- **Live demo:** https://YOUR-SITE/demo
+- **Docs:** https://YOUR-SITE/docs
+- **NPM:** https://www.npmjs.com/package/hz-particles
+
+## Why hz-particles?
+
+Most AI/VFX tools generate **videos** or **spritesheets**. hz-particles generates **real-time,
+editable FX presets** that run inside your Three.js / R3F scene.
+
+- **Not a video** — effects are simulated in real time, on the GPU, every frame.
+- **Not a screenshot** — presets are editable `JSON` / `.hzfx` files you can re-tune or re-prompt.
+- **Not a separate renderer** — the R3F component renders the *same engine* as the editor, so
+  there's no "looked great in the editor, renders wrong in-game" gap.
+- **Game-ready** — moving emitters, trails, depth occlusion, bloom, GLB-mesh particles.
+
+> **Text-to-realtime-FX, not text-to-video.** The HZ editor turns a prompt into an editable
+> preset; this package is the runtime that renders it in your app.
+
+The full pipeline:
+
+```
+HZ editor (manual or prompt)  →  preset (JSON / .hzfx)  →  faithful WebGPU runtime  →  Three.js / R3F
+```
 
 ## Features
 
 - **WebGPU Compute Shaders** — GPU-accelerated particle physics simulation
-- **GPU Instancing** — Efficient rendering of thousands of particles
-- **GLB Model Support** — Use 3D models as particle shapes with automatic texture extraction
-- **Skeletal Animations** — Animated GLB models with full animation control
-- **Scene Serialization** — Save/load particle configurations as JSON
-- **Multiple Emitter Shapes** — Sphere, cube, cylinder, circle, square emission patterns
-- **Real-time Physics** — Gravity, attractors, drag, velocity, and lifetime management
-- **React Three Fiber Component** — Drop-in `HZParticlesFX` component with preset support
-- **3D Object Support** — Static 3D objects alongside particle systems
+- **GPU Instancing** — efficient rendering of thousands of particles
+- **Engine-faithful R3F component** — `HZFaithfulFX` runs the real overlay inline on three's
+  `WebGPURenderer`: shader shapes, noise, per-system blending, multi-pass bloom, faithful trails,
+  depth occlusion. Editor parity by construction.
+- **Faithful trails & moving emitters** — comet trails that follow an arbitrary path (ball trails)
+- **GLB model support** — use 3D models as particle shapes, with automatic texture extraction
+- **Skeletal animations** — animated GLB models with full animation control
+- **20+ emitter shapes** — volumes & surfaces: sphere, cube, cylinder, cone, torus, capsule,
+  frustum, hemisphere, disc, annulus, arc, spiral, polygon, `cubeSurface`, `sphereSurface`,
+  `boxFrame`, and more
+- **Real-time physics** — gravity, attractors, drag, velocity, lifetime
+- **Serialized presets** — self-contained `.hzfx` binary package (textures + GLB inlined) or plain JSON
+- **3D object support** — static 3D objects alongside particle systems
 
 ## Requirements
 
-**WebGPU-compatible browser required:**
-- Chrome/Edge 113+ (stable)
+**A WebGPU-capable browser is required:**
+- Chrome / Edge 113+ (stable)
 - Firefox Nightly (experimental)
-- Safari Technology Preview (experimental)
+- Safari Technology Preview / Safari 18+ (experimental)
 
 Check browser support: [caniuse.com/webgpu](https://caniuse.com/webgpu)
 
 ## Installation
 
-### WebGPU
-
 ```bash
 npm install hz-particles
 ```
 
 ```javascript
-import { initWebGPU, ParticleSystemManager } from 'hz-particles';
+// React Three Fiber (recommended)
+import { HZFaithfulFX } from 'hz-particles/r3f';
+
+// Standalone WebGPU / overlay
+import { initHzFxOverlay, ParticleSystemManager } from 'hz-particles';
 ```
 
-### React Three Fiber
+For R3F usage you also need the peers: `react`, `three` (with its WebGPU backend), and
+`@react-three/fiber`.
 
-```bash
-npm install hz-particles
+## Usage modes
+
+Pick the entry point that matches how much control you need:
+
+### 1. Drop-in R3F FX — `<HZFaithfulFX />`
+The fastest path. Give it a preset, drop it in your scene, done. Engine-faithful by construction.
+
+### 2. Overlay / inline renderer — `initHzFxOverlay()`
+For non-React apps, custom render loops, post-processing pipelines, or when you want to host many
+coexisting effects and drive the camera yourself. Same faithful engine, full control.
+
+### 3. Low-level particle engine — `ParticleSystemManager` / `ParticleSystem`
+Build your own engine on top of the raw compute + render pipelines.
+
+## Quick Start (React Three Fiber)
+
+`<HZFaithfulFX>` runs the **real engine** inline on three's `WebGPURenderer`: shader-drawn shapes,
+noise, per-system blending, multi-pass bloom, faithful trails, and depth occlusion. Pass a
+`position` for a static FX, or a `positionRef` for a moving one (e.g. a ball trail) — the overlay
+pulls the ref each frame.
+
+Your R3F `Canvas` must use a **WebGPU** renderer. With `@react-three/fiber` v9 and `three/webgpu`:
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import * as THREE from 'three/webgpu';
+import { useRef } from 'react';
+import { HZFaithfulFX } from 'hz-particles/r3f';
+import firePreset from './fire.json';
+import trailPreset from './trail.json';
+
+export function App() {
+  const ballRef = useRef<THREE.Vector3>(null); // updated by your app each frame
+
+  return (
+    <Canvas
+      // Provide a WebGPURenderer instead of the default WebGLRenderer:
+      gl={async (props) => {
+        const renderer = new THREE.WebGPURenderer(props as any);
+        await renderer.init();
+        return renderer;
+      }}
+      camera={{ position: [0, 2, 6], fov: 50 }}
+    >
+      <HZFaithfulFX preset={firePreset} position={[0, 1, 0]} />        {/* static FX */}
+      <HZFaithfulFX preset={trailPreset} positionRef={ballRef} scale={1.5} /> {/* ball trail */}
+    </Canvas>
+  );
+}
+```
+
+> **Important integration note —** `<HZFaithfulFX>` **drives rendering**: its `useFrame` calls
+> `gl.render` itself, so R3F stops auto-rendering. This is what guarantees the FX composites on
+> top of your scene with correct depth occlusion.
+>
+> - Use `<HZFaithfulFX>` when it can own the frame (the common case).
+> - If your host owns its own render loop (custom RAF, a post-processing / EffectComposer
+>   pipeline), use [`initHzFxOverlay()`](#engine-faithful-overlay) directly instead so *you* stay
+>   in control of when the scene and the FX render.
+>
+> Re-trigger an effect by remounting it (change its `key`).
+
+### Loading `.hzfx` presets
+
+The `preset` prop is a plain `SceneData` object. JSON presets can be imported directly (above).
+For the binary `.hzfx` package, fetch it with `fetchPreset` (auto-detects `.hzfx` vs JSON):
+
+```tsx
+import { useEffect, useState } from 'react';
+import { fetchPreset } from 'hz-particles/r3f';
+import { HZFaithfulFX } from 'hz-particles/r3f';
+
+function Fire() {
+  const [preset, setPreset] = useState(null);
+  useEffect(() => { fetchPreset('/fx/fire.hzfx').then(setPreset); }, []);
+  return preset ? <HZFaithfulFX preset={preset} position={[0, 1, 0]} /> : null;
+}
 ```
 
+### Props reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `preset` | `SceneData` | — | Particle preset (JSON object exported from the editor) |
+| `position` | `[number, number, number]` | `[0, 0, 0]` | Static emitter world position (when `positionRef` is omitted) |
+| `positionRef` | `RefObject<Vector3 \| null>` | — | Moving emitter (e.g. a ball trail): the overlay reads this ref every frame |
+| `scale` | `number` | `1` | Uniform scale applied to the preset (sizes, speeds, emission, trail) |
+| `active` | `boolean` | `true` | When false, a moving emitter pauses (no new trail) |
+| `renderPriority` | `number` | `1` | `useFrame` priority. This component drives rendering, so keep it > 0 |
+| `noOcclusion` | `boolean` | `false` | Skip scene-depth occlusion (particles never hidden behind geometry) |
+
+The `hz-particles/r3f` entry also exports `HZTrailRibbon` (a lightweight ribbon-trail mesh driven
+by a `positionRef`) and the helpers `scalePreset`, `computeParticleSize`, `computeParticleOpacity`.
+
+## Engine-faithful overlay
+
+`initHzFxOverlay()` is **the same render loop the HZ previews and editor use** — shader-drawn
+shapes, per-system blending, noise distortion, GLB-mesh particles + animation, multi-pass bloom,
+and faithful trails. It's the recommended way to drop HZ effects into any app (vanilla JS,
+TypeScript, or a React app with its own render loop — one core, no per-framework reimplementation).
+
 ```javascript
-import { HZParticlesFX } from 'hz-particles/r3f';
+import { initHzFxOverlay, makeThreeSceneDepth } from 'hz-particles';
+
+// OVERLAY mode: pass a canvas — the overlay owns its WebGPU context and renders on a
+// transparent background. Stack it above your scene with pointer-events: none.
+const fx = await initHzFxOverlay(canvas);
+await fx.loadPreset(preset);                       // or fx.setEmitters([{ preset, position }])
+
+function frame(dt) {
+  fx.setCamera(proj, view, [cx, cy, cz]);          // column-major matrices + camera world pos
+  fx.render(dt);
+}
+
+// INLINE mode (share your own WebGPU renderer, e.g. three's WebGPURenderer):
+const fx2 = await initHzFxOverlay(
+  { device, context, canvas },
+  { getSceneDepth: makeThreeSceneDepth(renderer) } // one-line occlusion behind your geometry
+);
+// each frame, AFTER renderer.render(scene, camera): fx2.setCamera(...); fx2.render(dt);
 ```
 
-> **Important:** Your R3F `Canvas` must use `WebGPURenderer`. Pass `gl={{ powerPreference: 'high-performance' }}` and configure Three.js to use its WebGPU backend, or use `@react-three/fiber` with a WebGPU-capable renderer setup.
+**Coexisting groups & moving emitters** — one overlay hosts many FX at once. `addEmitter(preset, pos)`
+adds a static group; `addMovingEmitter(preset, { getPosition })` adds a moving one (e.g. a ball trail)
+whose comet trail follows the path you supply (the overlay *pulls* `getPosition()` each frame; return
+`null` to pause). Both return `{ remove() }`.
+
+| Method | Description |
+| --- | --- |
+| `setCamera(proj, view, pos)` / `setCameraMVP(mvp, pos)` | Drive the camera (column-major). |
+| `loadPreset(preset, pos?)` / `setEmitters([...])` | (Re)build emitters. |
+| `addEmitter(preset, pos?)` → `{ remove }` | Add a STATIC group that coexists with others. |
+| `addMovingEmitter(preset, { getPosition })` → `{ setPosition, remove }` | Add a MOVING group (ball trail). |
+| `render(dt)` | Simulate + render one frame (inline: call after your scene render). |
+| `resize()` | Recreate render textures (also auto-detected from the canvas). |
+| `clearCaches()` | Drop cached bind groups after a `replaceSystems`/`addSystems` that reuses ids. |
+| `trackHistoryGroup(ids, getPosition)` → `{ remove }` | Give existing manager systems a moving trail (history only). |
+| `destroy()` | Release GPU resources. |
+
+Options: `{ getSceneDepth, autoRespawn, manager }`. Pass `manager` to **share an existing
+`ParticleSystemManager`** so your app keeps owning it while the overlay is the single render path.
 
-## Quick Start
+## Advanced: standalone WebGPU engine
 
-### WebGPU
+If you want to build your own renderer on the raw engine (no overlay, no R3F), drive the
+`ParticleSystemManager` / `ParticleSystem` directly:
 
 ```javascript
 import { initWebGPU, ParticleSystemManager } from 'hz-particles';
@@ -64,31 +244,25 @@ canvas.width = 800;
 canvas.height = 600;
 const { device, context, format } = await initWebGPU(canvas);
 
-// 2. Create particle system manager
+// 2. Create manager + a particle system
 const manager = new ParticleSystemManager(device);
+manager.createParticleSystem({ maxParticles: 10000, particleCount: 1000 });
 
-// 3. Create a particle system
-const systemId = manager.createParticleSystem({
-  maxParticles: 10000,
-  particleCount: 1000,
-});
-
-// 4. Initialize compute pipeline
+// 3. Initialize the compute pipeline
 const system = manager.getActiveSystem();
 await system.initComputePipeline(device);
 
-// 5. Render loop
+// 4. Render loop
 let lastTime = performance.now();
-
 function render() {
-  const currentTime = performance.now();
-  const deltaTime = (currentTime - lastTime) / 1000;
-  lastTime = currentTime;
+  const now = performance.now();
+  const dt = (now - lastTime) / 1000;
+  lastTime = now;
 
-  manager.updateAllSystems(deltaTime);
+  manager.updateAllSystems(dt);
 
-  const commandEncoder = device.createCommandEncoder();
-  const renderPass = commandEncoder.beginRenderPass({
+  const encoder = device.createCommandEncoder();
+  const pass = encoder.beginRenderPass({
     colorAttachments: [{
       view: context.getCurrentTexture().createView(),
       clearValue: { r: 0, g: 0, b: 0, a: 1 },
@@ -96,106 +270,40 @@ function render() {
       storeOp: 'store',
     }],
   });
-
-  system.render(renderPass);
-  renderPass.end();
-  device.queue.submit([commandEncoder.finish()]);
+  system.render(pass);
+  pass.end();
+  device.queue.submit([encoder.finish()]);
 
   requestAnimationFrame(render);
 }
-
 render();
 ```
 
-### React Three Fiber
+## Preset configuration
 
-**Minimal example with a preset file:**
-
-```jsx
-import { HZParticlesFX } from 'hz-particles/r3f';
-import explosionPreset from './presets/explosion.json';
-
-function Scene() {
-  return (
-    <HZParticlesFX
-      preset={explosionPreset}
-      position={[0, 1, 0]}
-    />
-  );
-}
-```
-
-**Complete example with all key props:**
-
-```jsx
-import { useRef, useState } from 'react';
-import { HZParticlesFX } from 'hz-particles/r3f';
-import explosionPreset from './presets/explosion.json';
-
-function Scene() {
-  const targetRef = useRef();
-  const [resetKey, setResetKey] = useState(0);
-
-  return (
-    <>
-      <mesh ref={targetRef} position={[0, 1, 0]}>
-        <boxGeometry />
-        <meshStandardMaterial />
-      </mesh>
-
-      <HZParticlesFX
-        preset={explosionPreset}
-        positionRef={targetRef}
-        scale={1.5}
-        resetKey={resetKey}
-        onComplete={() => console.log('effect finished')}
-      />
-
-      <button onClick={() => setResetKey(k => k + 1)}>
-        Replay
-      </button>
-    </>
-  );
-}
-```
-
-## Props Reference
-
-The `HZParticlesFX` component accepts the following props:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `preset` | `SceneData \| string` | — | Particle preset — pass a JSON object or a URL/path to a JSON file |
-| `position` | `[number, number, number]` | `[0, 0, 0]` | Static world-space position of the effect |
-| `positionRef` | `React.RefObject<Object3D>` | — | Attach the effect to a scene object; position tracks the ref each frame |
-| `autoPlay` | `boolean` | `true` | Start playing immediately when mounted |
-| `visible` | `boolean` | `true` | Show or hide the effect without unmounting |
-| `scale` | `number` | `1` | Uniform scale applied to the entire effect |
-| `resetKey` | `number` | `0` | Increment to reset and respawn the particle system |
-| `onComplete` | `() => void` | — | Callback fired when the effect finishes playing |
-
-## Preset Configuration
-
-Presets are plain JSON files that describe a particle scene. Key fields:
+Presets are plain `SceneData`. A few key per-system fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `particleCount` | `number` | Number of active particles |
 | `lifetime` | `number` | Particle lifetime in seconds |
 | `emissionRate` | `number` | Particles emitted per second |
-| `emissionShape` | `string` | Emitter shape: `sphere`, `cube`, `cylinder`, `circle`, `square` |
+| `emissionShape` | `string` | Emitter shape (default `cube`). Volumes: `cube`/`box`, `sphere`, `cylinder`, `cone`, `torus`, `capsule`, `frustum`, `hemisphere`, `spiral`. Flat: `circle`, `square`, `rectangle`, `disc`, `annulus`, `arc`, `polygon`, `plain`, `line`. Surfaces: `cubeSurface`, `sphereSurface`, `boxFrame` |
 | `particleSize` | `number` | Base size of each particle |
-| `colors` | `string[]` | Array of hex color values interpolated over lifetime |
+| `colors` | `string[]` | Hex colors interpolated over lifetime |
 | `fadeIn` | `number` | Opacity fade-in duration (0–1, fraction of lifetime) |
 | `fadeOut` | `number` | Opacity fade-out start (0–1, fraction of lifetime) |
 | `bloom` | `boolean` | Enable bloom glow on particles |
 | `gravity` | `number` | Gravity strength applied to particles |
 | `damping` | `number` | Velocity damping factor (0 = no drag, 1 = full stop) |
 | `emissionTrailEnabled` | `boolean` | Enable particle trail rendering |
-| `emissionTrailDuration` | `number` | How long trail segments persist in seconds |
+| `emissionTrailDuration` | `number` | How long trail segments persist (seconds) |
 | `emissionTrailWidth` | `number` | Width of the emission trail |
 
-## API Reference
+`serializeSystemConfig(config)` is the single source of truth for the full set of serializable
+fields (used by `saveScene` and the editor's code export).
+
+## API reference
 
 ### `initWebGPU(canvas)`
 
@@ -210,14 +318,7 @@ async function initWebGPU(canvas: HTMLCanvasElement): Promise<{
 }>
 ```
 
-**Parameters:**
-- `canvas` (required) — Canvas element. Set `canvas.width` and `canvas.height` before calling.
-
-**Returns:** Object with WebGPU device, canvas context, texture format, and canvas element.
-
-**Throws:** Error if `canvas` is missing or WebGPU is not supported.
-
----
+Set `canvas.width` / `canvas.height` before calling. Throws if WebGPU is unsupported.
 
 ### `ParticleSystem`
 
@@ -229,25 +330,19 @@ class ParticleSystem {
 }
 ```
 
-**Config options:**
-- `maxParticles` (number, default `10000`) — Maximum particle buffer size
-- `particleCount` (number, default `100`) — Initial active particle count
-
-**Key Methods:**
+**Config:** `maxParticles` (default `10000`), `particleCount` (default `100`).
 
 | Method | Description |
 |--------|-------------|
-| `initComputePipeline(device)` | Initialize GPU compute and render pipelines. Must be called before rendering. |
+| `initComputePipeline(device)` | Initialize GPU compute and render pipelines. Call before rendering. |
 | `setTexture(imageBitmap)` | Set particle texture from an `ImageBitmap`. |
-| `setGLBModel(arrayBuffer)` | Use GLB model geometry as particle shape. Automatically extracts textures. |
+| `setGLBModel(arrayBuffer)` | Use GLB model geometry as particle shape (auto-extracts textures). |
 | `updateParticles(deltaTime)` | Execute a physics simulation step on the GPU. |
 | `spawnParticles()` | Emit new particles according to emitter configuration. |
 | `setGravity(value)` | Set gravity strength (default `9.8`). |
-| `setAttractor(strength, position)` | Set an attractor point with strength and 3D position `[x, y, z]`. |
+| `setAttractor(strength, position)` | Set an attractor point `[x, y, z]`. |
 | `render(renderPass)` | Render particles to the current render pass. |
 
----
-
 ### `ParticleSystemManager`
 
 Manages multiple particle systems within a single scene.
@@ -258,25 +353,21 @@ class ParticleSystemManager {
 }
 ```
 
-**Key Methods:**
-
 | Method | Description |
 |--------|-------------|
 | `createParticleSystem(config?)` | Create a new particle system. Returns system ID. |
-| `getActiveSystem()` | Get the currently active `ParticleSystem` instance. |
+| `getActiveSystem()` | Get the currently active `ParticleSystem`. |
 | `getActiveConfig()` | Get the active system configuration object. |
-| `setActiveSystem(index)` | Switch active system by index. Returns success status. |
-| `removeSystem(index)` | Remove a system by index. Returns success status. |
+| `setActiveSystem(index)` | Switch active system by index. |
+| `removeSystem(index)` | Remove a system by index. |
 | `updateAllSystems(deltaTime)` | Update physics for all systems. |
-| `getSystemsList()` | Get list of all systems with `name`, `id`, `index`, `isActive`. |
+| `getSystemsList()` | List all systems (`name`, `id`, `index`, `isActive`). |
 | `duplicateActiveSystem()` | Clone the active system. Returns new system ID. |
-| `replaceSystems(sceneData)` | Load a scene from serialized data. Returns success status. |
-
----
+| `replaceSystems(sceneData)` | Load a scene from serialized data. |
 
 ### `parseGLB(arrayBuffer)`
 
-Parse GLB binary format and extract geometry data.
+Parse GLB binary and extract geometry.
 
 ```typescript
 async function parseGLB(arrayBuffer: ArrayBuffer): Promise<{
@@ -291,16 +382,13 @@ async function parseGLB(arrayBuffer: ArrayBuffer): Promise<{
 }>
 ```
 
----
-
 ### `GLBAnimator`
 
-Handles skeletal animation playback for animated GLB models.
+Skeletal animation playback for animated GLB models.
 
 ```typescript
 class GLBAnimator {
   constructor(animationData: object)
-
   currentTime: number
   playing: boolean
   speed: number   // default 1.0
@@ -308,115 +396,95 @@ class GLBAnimator {
 }
 ```
 
-**Key Methods:**
-
 | Method | Description |
 |--------|-------------|
-| `setRestPose(positions, normals)` | Set the T-pose/bind pose for animation. |
+| `setRestPose(positions, normals)` | Set the T-pose/bind pose. |
 | `update(deltaTime)` | Advance animation. Returns `{ positions, normals, changed }`. |
 | `setAnimation(index)` | Switch to animation clip by index. |
-| `getAnimationNames()` | Get list of available animation clip names. |
+| `getAnimationNames()` | List available animation clip names. |
 
-## GLB Models & Animation
+## GLB models & animation
 
 ```javascript
 import { parseGLB, GLBAnimator } from 'hz-particles';
 
-// Load GLB file
-const response = await fetch('model.glb');
-const arrayBuffer = await response.arrayBuffer();
+const arrayBuffer = await (await fetch('model.glb')).arrayBuffer();
 const glbData = await parseGLB(arrayBuffer);
 
-// Use as particle shape
-await system.setGLBModel(arrayBuffer);
+await system.setGLBModel(arrayBuffer); // use as particle shape
 
-// Setup animation (if model has animations)
 if (glbData.animationData) {
   const animator = new GLBAnimator(glbData.animationData);
   animator.setRestPose(glbData.positions, glbData.normals);
   animator.playing = true;
-  animator.loop = true;
-  animator.speed = 1.0;
 
-  // In render loop:
+  // in the render loop:
   const { positions, normals, changed } = animator.update(deltaTime);
-  if (changed) {
-    // Update particle system with new geometry
-    // (See full API documentation for geometry update methods)
-  }
+  if (changed) { /* push updated geometry to the system */ }
 }
 ```
 
-## Scene Save/Load
+## Scene save / load
 
 ```javascript
 import { saveScene, loadScene } from 'hz-particles';
 
-// Save current scene
-document.getElementById('save-button').addEventListener('click', () => {
-  saveScene(manager);  // Downloads scene.json
-});
+// Save (downloads a self-contained .hzfx package; Alt-click → JSON):
+saveButton.addEventListener('click', () => saveScene(manager));
 
-// Load scene from file input
-document.getElementById('file-input').addEventListener('change', async (event) => {
-  const success = await loadScene(event, manager);
-  if (success) {
-    console.log('Scene loaded successfully');
-  }
+// Load from a file input (.hzfx or JSON, auto-detected):
+fileInput.addEventListener('change', async (e) => {
+  if (await loadScene(e, manager)) console.log('Scene loaded');
 });
 ```
 
 ## TypeScript
 
-Type declarations are not yet included in this package. For TypeScript projects, suppress the import error with:
+Type declarations **are shipped** — the package's `types` entry points at
+`dist-lib/hz-particles.d.ts` (and `dist-lib/hz-particles-r3f.d.ts` for the `hz-particles/r3f`
+subpath), so imports are fully typed out of the box:
 
 ```typescript
-// @ts-ignore
-import { ParticleSystem, initWebGPU } from 'hz-particles';
-// @ts-ignore
-import { HZParticlesFX } from 'hz-particles/r3f';
+import { initHzFxOverlay, ParticleSystemManager, serializeSystemConfig } from 'hz-particles';
+import { HZFaithfulFX } from 'hz-particles/r3f';
 ```
 
-Community-contributed type definitions are welcome via PR.
-
-## Secondary Exports
+## Secondary exports
 
-The following modules are also exported for advanced usage:
+Also exported for advanced usage:
 
-- **`ParticleEmitter`** — Emission shape configuration (sphere, cube, cylinder, circle, square)
-- **`ParticlePhysics`** — Physics simulation parameter management
-- **`ParticleTextureManager`** — Texture loading utilities
+- **`fetchPreset(url)`** — load a preset from a URL (`.hzfx` or JSON, auto-detected)
+- **`packHZFX` / `unpackHZFX` / `isHZFX`** — build/read the `.hzfx` binary package format
+- **`serializeSystemConfig(config)`** — single source of truth for a system's serializable fields
+- **`saveScene(manager)` / `loadScene(event)`** — export/import a scene (`.hzfx` or JSON)
+- **`ParticleEmitter`** — emission-shape configuration
+- **`ParticlePhysics`** — physics parameter management
+- **`ParticleTextureManager`** — texture loading utilities
 - **`Objects3DManager`** — 3D object scene management
-- **`saveScene(manager)`** — Export scene as JSON file download
-- **`loadScene(event)`** — Load scene from file input event
-- **`extractGLBTexture(arrayBuffer)`** — Extract base color texture from GLB file
-- **Shader exports** — WGSL shader code for compute and rendering pipelines
-- **Geometry helpers** — Primitive shape generators (cube, sphere, etc.)
-- **Render pipeline creators** — Low-level WebGPU pipeline construction
+- **`extractGLBTexture(arrayBuffer)`** — extract base color texture from a GLB
+- **Shader / geometry / pipeline helpers** — low-level WGSL and pipeline construction
 
-## Online Editor
+## Online editor
 
-Try the interactive particle editor at `http://localhost:8110/editor` when running the Docker container (`docker-compose up` from the repository root).
+Generate effects from a prompt — or build them by hand — in the HZ editor, then export a preset and
+render it with this package.
 
-The editor provides a visual interface for:
-- Real-time particle system configuration
-- Emitter shape selection and tuning
-- GLB model import and animation control
-- Scene preset library
-- Export/import scene JSON
+<!-- TODO: replace with the public editor URL -->
+- Hosted editor & prompt FX generator: https://YOUR-SITE
+- Local: `http://localhost:8110/editor` (run `docker-compose up` from the repo root)
 
-## Contributing
+The editor provides real-time configuration, emitter-shape tuning, GLB import + animation control, a
+preset library, and `JSON` / `.hzfx` export.
 
-Contributions are welcome! Please follow these steps:
+## Contributing
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+3. Commit your changes
+4. Push and open a Pull Request
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License — see [LICENSE](LICENSE).
 
 Copyright (c) 2025 HZ