@guinetik/gcanvas 1.0.0 → 1.0.2

package/docs/README.md

@@ -1,222 +1,230 @@
-# GCanvas Documentation
-
-> A minimalist 2D canvas rendering library built for learning, expression, and creative coding.
-
-GCanvas is a modular 2D rendering and game framework built on top of the HTML5 Canvas API. Inspired by the simplicity of p5.js and the composability of game engines.
-
-## Quick Navigation
-
-| Section | Description |
-|---------|-------------|
-| [Getting Started](./getting-started/installation.md) | Installation and first steps |
-| [Concepts](./concepts/architecture-overview.md) | Core architecture and design |
-| [Shapes Module](./modules/shapes/README.md) | Drawing primitives and hierarchy |
-| [Game Module](./modules/game/README.md) | Game loop and GameObjects |
-| [Particle Module](./modules/particle/README.md) | High-performance particle systems |
-| [Util Module](./modules/util/README.md) | Camera3D, Scene3D, layouts |
-| [Collision Module](./modules/collision/README.md) | Collision detection and management |
-| [State Module](./modules/state/README.md) | State machines for entities and games |
-| [Painter Module](./modules/painter/README.md) | Low-level canvas API |
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                         GCanvas                              │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │   Shapes    │  │    Game     │  │      Painter        │  │
-│  │  (Drawing)  │  │ (Lifecycle) │  │   (Canvas API)      │  │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
-├─────────────────────────────────────────────────────────────┤
-│  ┌───────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐         │
-│  │ Collision │ │  State  │ │ Motion  │ │   IO    │  ...    │
-│  │ (Physics) │ │  (FSM)  │ │ (Anim)  │ │ (Input) │         │
-│  └───────────┘ └─────────┘ └─────────┘ └─────────┘         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-GCanvas is organized into **12 core modules**:
-
-| Module | Purpose |
-|--------|---------|
-| **[shapes](./modules/shapes/README.md)** | 40+ drawable primitives and shape classes |
-| **[game](./modules/game/README.md)** | Core game loop, Pipeline, GameObjects, Scenes |
-| **[particle](./modules/particle/README.md)** | High-performance particle systems with pooling |
-| **[collision](./modules/collision/README.md)** | Collision detection algorithms and group management |
-| **[state](./modules/state/README.md)** | State machines with lifecycle callbacks |
-| **[painter](./modules/painter/README.md)** | Low-level canvas drawing API |
-| **[util](./modules/util/README.md)** | Camera3D, Scene3D, Layout, Position utilities |
-| **motion** | Animation with Tweenetik and Motion patterns |
-| **io** | Input handling (Mouse, Keyboard, Touch, Events) |
-| **math** | Random, Noise, Fractals, Patterns |
-| **mixins** | Draggable, Anchor behaviors |
-| **logger** | Debug logging system |
-
-## Two-Layer Architecture
-
-GCanvas provides two complementary ways to work:
-
-### Shape Layer (Declarative Drawing)
-
-For static visuals and simple graphics. Use shapes directly without a game loop:
-
-```js
-import { Circle, Rectangle, Painter } from 'gcanvas';
-
-Painter.init(ctx);
-
-const circle = new Circle(100, { x: 200, y: 150, color: 'red' });
-circle.draw();
-```
-
-### Game Layer (Interactive Entities)
-
-For games, simulations, and interactive applications:
-
-```js
-import { Game, Scene, GameObject, Circle } from 'gcanvas';
-
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Circle(40, { color: 'blue' });
-    this.enableInteractivity(this.shape);
-  }
-
-  update(dt) {
-    // Game logic here
-  }
-
-  render() {
-    this.shape.draw();
-  }
-}
-```
-
-[Learn more about the Two-Layer Architecture](./concepts/two-layer-architecture.md)
-
-## The Rendering Pipeline
-
-Every visual element inherits from a chain of base classes:
-
-```
-Euclidian          ─── Position (x, y) and size (width, height)
-    │
-Geometry2d         ─── Bounding boxes and constraints
-    │
-Traceable          ─── Debug visualization
-    │
-Renderable         ─── Visibility, opacity, shadows
-    │
-Transformable      ─── Rotation and scaling
-    │
-Shape              ─── Fill color, stroke, line styling
-    │
-[Circle, Rectangle, Star, Cube, ...]  ─── Concrete implementations
-```
-
-[Learn more about the Rendering Pipeline](./concepts/rendering-pipeline.md)
-
-## Quick Start
-
-### Installation
-
-```bash
-git clone https://github.com/guinetik/gcanvas.git
-cd gcanvas
-npm install
-npm run dev
-```
-
-### Hello World
-
-```html
-<canvas id="game"></canvas>
-<script type="module">
-  import { Game, Scene, Rectangle, TextShape, Group } from 'gcanvas';
-
-  class HelloWorld extends Game {
-    init() {
-      this.enableFluidSize();
-      this.backgroundColor = 'black';
-
-      const box = new Rectangle(200, 80, {
-        color: '#111',
-        stroke: '#0f0',
-        lineWidth: 2
-      });
-
-      const label = new TextShape('Hello World!', {
-        font: '18px monospace',
-        color: '#0f0',
-        align: 'center',
-        baseline: 'middle'
-      });
-
-      const group = new Group({ x: this.width / 2, y: this.height / 2 });
-      group.add(box);
-      group.add(label);
-
-      const scene = new Scene(this);
-      scene.add(group);
-      this.pipeline.add(scene);
-    }
-  }
-
-  const game = new HelloWorld(document.getElementById('game'));
-  game.start();
-</script>
-```
-
-[Full getting started guide](./getting-started/hello-world.md)
-
-## Features
-
-- **40+ Shape Primitives** - Circle, Rectangle, Star, Polygon, Heart, and more
-- **2.5D Shapes** - Cube, Cylinder, Sphere, Cone, Prism with pseudo-3D rendering
-- **Groups** - Composite shapes with collective transforms
-- **Transforms** - Rotation, scale, opacity, constraints
-- **Painter API** - Direct canvas control when needed
-- **GameObjects** - Interactive entities with lifecycle methods
-- **Scenes & Scene3D** - Hierarchical organization with optional 3D projection
-- **Camera3D** - Pseudo-3D projection with mouse-controlled rotation
-- **Particle Systems** - High-performance particles with object pooling and composable updaters
-- **Collision Detection** - AABB, circles, lines, sweep tests, and group management
-- **State Machines** - FSM with enter/update/exit lifecycle, timed transitions
-- **UI Components** - Button, ToggleButton, Cursor, Layout managers
-- **Motion System** - Stateless animation patterns (orbit, bounce, spiral...)
-- **Tweenetik** - Property-based tweening with easing
-- **Event System** - Mouse, touch, keyboard with unified input
-- **Zero Dependencies** - Pure JavaScript, works everywhere
-
-## Demo
-
-See GCanvas in action: [gcanvas.guinetik.com](https://gcanvas.guinetik.com)
-
-Or run locally:
-
-```bash
-npm run dev
-```
-
-## API Documentation
-
-- [Shapes Module](./modules/shapes/README.md) - All drawable primitives
-- [Game Module](./modules/game/README.md) - Game loop and objects
-- [Particle Module](./modules/particle/README.md) - Particle systems
-- [Util Module](./modules/util/README.md) - Camera3D, Scene3D, layouts
-- [Collision Module](./modules/collision/README.md) - Collision detection
-- [State Module](./modules/state/README.md) - State machines
-- [Painter Module](./modules/painter/README.md) - Canvas abstraction
-
-## Learn More
-
-- [Architecture Overview](./concepts/architecture-overview.md)
-- [Rendering Pipeline](./concepts/rendering-pipeline.md)
-- [Game Lifecycle](./concepts/lifecycle.md)
-- [Installation Guide](./getting-started/installation.md)
-
----
-
-**Source:** [github.com/guinetik/gcanvas](https://github.com/guinetik/gcanvas)
+# GCanvas Documentation
+
+> A minimalist 2D canvas rendering library built for learning, expression, and creative coding.
+
+GCanvas is a modular 2D rendering and game framework built on top of the HTML5 Canvas API. Inspired by the simplicity of p5.js and the composability of game engines.
+
+## Quick Navigation
+
+| Section | Description |
+|---------|-------------|
+| [Getting Started](./getting-started/installation.md) | Installation and first steps |
+| [Concepts](./concepts/architecture-overview.md) | Core architecture and design |
+| [Shapes Module](./modules/shapes/README.md) | Drawing primitives and hierarchy |
+| [Game Module](./modules/game/README.md) | Game loop and GameObjects |
+| [Particle Module](./modules/particle/README.md) | High-performance particle systems |
+| [Util Module](./modules/util/README.md) | Camera3D, Scene3D, layouts |
+| [Collision Module](./modules/collision/README.md) | Collision detection and management |
+| [State Module](./modules/state/README.md) | State machines for entities and games |
+| [Painter Module](./modules/painter/README.md) | Low-level canvas API |
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         GCanvas                              │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Shapes    │  │    Game     │  │      Painter        │  │
+│  │  (Drawing)  │  │ (Lifecycle) │  │   (Canvas API)      │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│  ┌───────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐         │
+│  │ Collision │ │  State  │ │ Motion  │ │   IO    │  ...    │
+│  │ (Physics) │ │  (FSM)  │ │ (Anim)  │ │ (Input) │         │
+│  └───────────┘ └─────────┘ └─────────┘ └─────────┘         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+GCanvas is organized into **12 core modules**:
+
+| Module | Purpose |
+|--------|---------|
+| **[shapes](./modules/shapes/README.md)** | 40+ drawable primitives and shape classes |
+| **[game](./modules/game/README.md)** | Core game loop, Pipeline, GameObjects, Scenes |
+| **[particle](./modules/particle/README.md)** | High-performance particle systems with pooling |
+| **[collision](./modules/collision/README.md)** | Collision detection algorithms and group management |
+| **[state](./modules/state/README.md)** | State machines with lifecycle callbacks |
+| **[painter](./modules/painter/README.md)** | Low-level canvas drawing API |
+| **[util](./modules/util/README.md)** | Camera3D, Scene3D, Layout, Position utilities |
+| **motion** | Animation with Tweenetik and Motion patterns |
+| **io** | Input handling (Mouse, Keyboard, Touch, Events) |
+| **math** | Random, Noise, Fractals, Patterns |
+| **mixins** | Draggable, Anchor behaviors |
+| **logger** | Debug logging system |
+
+## Two-Layer Architecture
+
+GCanvas provides two complementary ways to work:
+
+### Shape Layer (Declarative Drawing)
+
+For static visuals and simple graphics. Use shapes directly without a game loop:
+
+```js
+import { Circle, Rectangle, Painter } from '@guinetik/gcanvas';
+
+Painter.init(ctx);
+
+const circle = new Circle(100, { x: 200, y: 150, color: 'red' });
+circle.draw();
+```
+
+### Game Layer (Interactive Entities)
+
+For games, simulations, and interactive applications:
+
+```js
+import { Game, Scene, GameObject, Circle } from '@guinetik/gcanvas';
+
+class Player extends GameObject {
+  constructor(game) {
+    super(game);
+    this.shape = new Circle(40, { color: 'blue' });
+    this.enableInteractivity(this.shape);
+  }
+
+  update(dt) {
+    // Game logic here
+  }
+
+  render() {
+    this.shape.draw();
+  }
+}
+```
+
+[Learn more about the Two-Layer Architecture](./concepts/two-layer-architecture.md)
+
+## The Rendering Pipeline
+
+Every visual element inherits from a chain of base classes:
+
+```
+Euclidian          ─── Position (x, y) and size (width, height)
+    │
+Geometry2d         ─── Bounding boxes and constraints
+    │
+Traceable          ─── Debug visualization
+    │
+Renderable         ─── Visibility, opacity, shadows
+    │
+Transformable      ─── Rotation and scaling
+    │
+Shape              ─── Fill color, stroke, line styling
+    │
+[Circle, Rectangle, Star, Cube, ...]  ─── Concrete implementations
+```
+
+[Learn more about the Rendering Pipeline](./concepts/rendering-pipeline.md)
+
+## Quick Start
+
+### Installation
+
+**NPM (Recommended):**
+
+```bash
+npm install @guinetik/gcanvas
+```
+
+**Or clone the repository:**
+
+```bash
+git clone https://github.com/guinetik/gcanvas.git
+cd gcanvas
+npm install
+npm run dev
+```
+
+### Hello World
+
+```html
+<canvas id="game"></canvas>
+<script type="module">
+  import { Game, Scene, Rectangle, TextShape, Group } from '@guinetik/gcanvas';
+
+  class HelloWorld extends Game {
+    init() {
+      this.enableFluidSize();
+      this.backgroundColor = 'black';
+
+      const box = new Rectangle(200, 80, {
+        color: '#111',
+        stroke: '#0f0',
+        lineWidth: 2
+      });
+
+      const label = new TextShape('Hello World!', {
+        font: '18px monospace',
+        color: '#0f0',
+        align: 'center',
+        baseline: 'middle'
+      });
+
+      const group = new Group({ x: this.width / 2, y: this.height / 2 });
+      group.add(box);
+      group.add(label);
+
+      const scene = new Scene(this);
+      scene.add(group);
+      this.pipeline.add(scene);
+    }
+  }
+
+  const game = new HelloWorld(document.getElementById('game'));
+  game.start();
+</script>
+```
+
+[Full getting started guide](./getting-started/hello-world.md)
+
+## Features
+
+- **40+ Shape Primitives** - Circle, Rectangle, Star, Polygon, Heart, and more
+- **2.5D Shapes** - Cube, Cylinder, Sphere, Cone, Prism with pseudo-3D rendering
+- **Groups** - Composite shapes with collective transforms
+- **Transforms** - Rotation, scale, opacity, constraints
+- **Painter API** - Direct canvas control when needed
+- **GameObjects** - Interactive entities with lifecycle methods
+- **Scenes & Scene3D** - Hierarchical organization with optional 3D projection
+- **Camera3D** - Pseudo-3D projection with mouse-controlled rotation
+- **Particle Systems** - High-performance particles with object pooling and composable updaters
+- **Collision Detection** - AABB, circles, lines, sweep tests, and group management
+- **State Machines** - FSM with enter/update/exit lifecycle, timed transitions
+- **UI Components** - Button, ToggleButton, Cursor, Layout managers
+- **Motion System** - Stateless animation patterns (orbit, bounce, spiral...)
+- **Tweenetik** - Property-based tweening with easing
+- **Event System** - Mouse, touch, keyboard with unified input
+- **Zero Dependencies** - Pure JavaScript, works everywhere
+
+## Demo
+
+See GCanvas in action: [gcanvas.guinetik.com](https://gcanvas.guinetik.com)
+
+Or run locally:
+
+```bash
+npm run dev
+```
+
+## API Documentation
+
+- [Shapes Module](./modules/shapes/README.md) - All drawable primitives
+- [Game Module](./modules/game/README.md) - Game loop and objects
+- [Particle Module](./modules/particle/README.md) - Particle systems
+- [Util Module](./modules/util/README.md) - Camera3D, Scene3D, layouts
+- [Collision Module](./modules/collision/README.md) - Collision detection
+- [State Module](./modules/state/README.md) - State machines
+- [Painter Module](./modules/painter/README.md) - Canvas abstraction
+
+## Learn More
+
+- [Architecture Overview](./concepts/architecture-overview.md)
+- [Rendering Pipeline](./concepts/rendering-pipeline.md)
+- [Game Lifecycle](./concepts/lifecycle.md)
+- [Installation Guide](./getting-started/installation.md)
+
+---
+
+**Source:** [github.com/guinetik/gcanvas](https://github.com/guinetik/gcanvas)

package/docs/api/FluidSystem.md

@@ -0,0 +1,173 @@
+# FluidSystem
+
+High-level fluid simulation system built on `ParticleSystem`.
+
+Integrates SPH physics, collision detection, and boundary handling into a cohesive, configurable fluid simulation.
+
+## Import
+
+```javascript
+import { FluidSystem } from "gcanvas";
+```
+
+## Basic Usage
+
+```javascript
+// Create a liquid simulation
+const fluid = new FluidSystem(game, {
+  maxParticles: 500,
+  particleSize: 20,
+  bounds: { x: 50, y: 50, w: 700, h: 500 },
+  physics: 'liquid',
+});
+
+// Spawn particles
+fluid.spawn(300);
+
+// Add to game pipeline
+game.pipeline.add(fluid);
+```
+
+## Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxParticles` | number | 500 | Maximum particle count |
+| `particleSize` | number | 20 | Base particle diameter |
+| `bounds` | Object | null | Containment bounds `{ x, y, w, h }` |
+| `physics` | string | 'liquid' | Physics mode: `'liquid'`, `'gas'`, or `'blend'` |
+| `gravity` | number | 200 | Gravity strength |
+| `gravityEnabled` | boolean | true | Whether gravity is active |
+| `damping` | number | 0.98 | Velocity damping per frame |
+| `bounce` | number | 0.3 | Bounce factor on collision |
+| `maxSpeed` | number | 400 | Maximum particle speed |
+
+### Fluid Sub-Options (`options.fluid`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `smoothingRadius` | number | particleSize * 2 | SPH smoothing radius |
+| `restDensity` | number | 3.0 | Target density |
+| `pressureStiffness` | number | 80 | Pressure force multiplier |
+| `nearPressureStiffness` | number | 3 | Near pressure multiplier |
+| `viscosity` | number | 0.005 | Viscosity strength |
+
+### Collision Sub-Options (`options.collision`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | true | Enable particle collision |
+| `strength` | number | 5000 | Collision repulsion strength |
+
+### Boundary Sub-Options (`options.boundary`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | true | Enable boundary forces |
+| `strength` | number | 4000 | Boundary repulsion strength |
+| `radius` | number | particleSize * 0.8 | Boundary force range |
+
+## Methods
+
+### spawn(count, options?)
+
+Spawn particles within the bounds or at a specified position.
+
+```javascript
+// Spawn at bounds center (default)
+fluid.spawn(200);
+
+// Spawn at specific position
+fluid.spawn(100, { x: 400, y: 300, spreadX: 50, spreadY: 50 });
+```
+
+### setBounds(bounds)
+
+Update containment bounds.
+
+```javascript
+fluid.setBounds({ x: 100, y: 100, w: 600, h: 400 });
+```
+
+### reset()
+
+Reset all particles to initial spawn positions.
+
+```javascript
+fluid.reset();
+```
+
+### toggleGravity()
+
+Toggle gravity on/off. Returns new state.
+
+```javascript
+const gravityOn = fluid.toggleGravity();
+```
+
+### setPhysicsMode(mode)
+
+Switch physics mode.
+
+```javascript
+fluid.setPhysicsMode('liquid');  // SPH fluid
+fluid.setPhysicsMode('gas');     // Gas dynamics
+fluid.setPhysicsMode(0.5);       // 50% blend
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `particles` | Array | Live particle array |
+| `bounds` | Object | Current bounds `{ x, y, w, h }` |
+| `gravityEnabled` | boolean | Gravity state |
+| `physicsBlend` | number | 0 = liquid, 1 = gas |
+| `config` | Object | Merged configuration |
+
+## Example: Complete Demo
+
+```javascript
+import { Game, FluidSystem, FPSCounter } from "gcanvas";
+
+class FluidDemo extends Game {
+  init() {
+    super.init();
+    
+    // Create fluid system
+    this.fluid = new FluidSystem(this, {
+      maxParticles: 400,
+      particleSize: 25,
+      bounds: { x: 50, y: 50, w: this.width - 100, h: this.height - 100 },
+      physics: 'liquid',
+      gravity: 200,
+    });
+    
+    this.fluid.spawn(400);
+    this.pipeline.add(this.fluid);
+    this.pipeline.add(new FPSCounter(this));
+    
+    // Keyboard controls
+    window.addEventListener('keydown', (e) => {
+      if (e.key === 'g') this.fluid.toggleGravity();
+      if (e.key === 'r') this.fluid.reset();
+    });
+  }
+}
+```
+
+## Integration with Existing Code
+
+FluidSystem reuses existing modules:
+
+- `ParticleSystem` - Base particle management
+- `Collision.applyCircleSeparation()` - Particle-particle collision
+- `computeFluidForces()` - SPH physics from `math/fluid.js`
+- `computeGasForces()` - Gas dynamics from `math/fluid.js`
+
+## Performance Notes
+
+- O(n²) collision detection is used for simplicity
+- For >1000 particles, consider spatial hashing optimization
+- The `blendMode: 'source-over'` default prevents washed-out colors
+