hz-particles 1.0.0 → 1.0.1

package/README.md

@@ -1,7 +1,7 @@
 # hz-particles
 
 [![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/TODO/hz-particles/blob/main/LICENSE)
+[![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.
@@ -34,11 +34,15 @@ npm install hz-particles
 
 ## Quick Start
 
+### Option 1: Using the built-in WebGPU helper
+
 ```javascript
 import { initWebGPU, ParticleSystemManager } from 'hz-particles';
 
-// 1. Setup WebGPU context
+// 1. Setup WebGPU context with the convenience helper
 const canvas = document.getElementById('webgpu-canvas');
+canvas.width = 800;
+canvas.height = 600;
 const { device, context, format } = await initWebGPU(canvas);
 
 // 2. Create particle system manager
@@ -92,6 +96,37 @@ function render() {
 render();
 ```
 
+### Option 2: Using an existing WebGPU setup
+
+If you already have a WebGPU device and context (e.g., from an existing project or framework), you can skip `initWebGPU()` and use the library directly:
+
+```javascript
+import { ParticleSystemManager, createRenderTextures, createDepthTexture } from 'hz-particles';
+
+// Assume you already have these from your existing WebGPU setup
+const device = yourExistingDevice;
+const context = yourExistingContext;
+const format = navigator.gpu.getPreferredCanvasFormat();
+const canvas = yourExistingCanvas;
+
+// Create particle system manager with your device
+const manager = new ParticleSystemManager(device);
+
+// Create a particle system
+const systemId = manager.createParticleSystem({
+  maxParticles: 10000,
+  particleCount: 1000,
+});
+
+// Initialize and use as shown in Option 1
+const system = manager.getActiveSystem();
+await system.initComputePipeline(device);
+
+// Your render loop...
+```
+
+This approach is ideal for integrating into existing WebGPU applications, frameworks, or when you need custom WebGPU initialization.
+
 ## React Three Fiber Integration
 
 While `hz-particles` uses native WebGPU (not Three.js internally), you can integrate it into React Three Fiber applications:
@@ -111,6 +146,8 @@ function ParticleLayer() {
     async function init() {
       // Create dedicated WebGPU canvas
       const canvas = canvasRef.current;
+      canvas.width = window.innerWidth;
+      canvas.height = window.innerHeight;
       const { device, context, format } = await initWebGPU(canvas);
 
       // Setup particle system
@@ -194,12 +231,12 @@ function App() {
 
 ## API Reference
 
-### `initWebGPU(canvas?)`
+### `initWebGPU(canvas)`
 
-Initialize WebGPU context and device.
+Convenience helper to initialize WebGPU context and device. **Library consumers with their own WebGPU setup do NOT need to use this function** — you can pass your existing `device`, `context`, `format`, and `canvas` directly to the library's components.
 
 ```typescript
-async function initWebGPU(canvas?: HTMLCanvasElement): Promise<{
+async function initWebGPU(canvas: HTMLCanvasElement): Promise<{
   device: GPUDevice,
   context: GPUCanvasContext,
   format: GPUTextureFormat,
@@ -208,11 +245,15 @@ async function initWebGPU(canvas?: HTMLCanvasElement): Promise<{
 ```
 
 **Parameters:**
-- `canvas` (optional) — Canvas element. If omitted, looks for `document.getElementById('webgpu-canvas')`
+- `canvas` (required) — Canvas element for WebGPU rendering. You must size the canvas before calling this function.
 
 **Returns:** Object with WebGPU device, canvas context, texture format, and canvas element
 
-**Throws:** Error if WebGPU is not supported
+**Throws:**
+- Error if `canvas` is not provided
+- Error if WebGPU is not supported
+
+**Note:** This function does NOT handle canvas sizing. You should set `canvas.width` and `canvas.height` before calling `initWebGPU()`.
 
 ---
 
@@ -407,7 +448,7 @@ input.addEventListener('change', async (event) => {
 
 ## Online Editor
 
-Try the interactive particle editor: [Online Editor](https://your-domain.com/editor) (deployment URL coming soon)
+Try the interactive particle editor at `http://localhost:8110/editor` when running the Docker container (`docker-compose up` from the repository root)
 
 The editor provides a visual interface for:
 - Real-time particle system configuration