@guinetik/gcanvas 1.0.2 → 1.0.4

package/docs/api/FluidSystem.md

@@ -1,173 +0,0 @@
-# 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
-

package/docs/concepts/architecture-overview.md

@@ -1,204 +0,0 @@
-# Architecture Overview
-
-> High-level system architecture, module relationships, and design philosophy.
-
-## Overview
-
-GCanvas is a modular 2D rendering and game framework built on top of the HTML5 Canvas API. It follows a layered architecture where each module has a clear responsibility and minimal coupling to other modules.
-
-The library is designed around three core principles:
-
-1. **Modularity** - Use only what you need
-2. **Composability** - Combine simple parts to build complex systems
-3. **Zero Dependencies** - Pure JavaScript, works everywhere
-
-## Module Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                           GCanvas                                │
-│                         (index.js)                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                    Core Modules                           │   │
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
-│  │  │   shapes/   │  │   game/     │  │    painter/     │   │   │
-│  │  │  40+ shapes │  │  Game loop  │  │   Canvas API    │   │   │
-│  │  │  hierarchy  │  │  Pipeline   │  │   abstraction   │   │   │
-│  │  │  Group      │  │  GameObject │  │                 │   │   │
-│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                  Support Modules                          │   │
-│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │   │
-│  │  │ motion │ │   io   │ │  math  │ │  util  │ │ mixins │  │   │
-│  │  │ Tween  │ │ Events │ │ Random │ │ Layout │ │Draggable│  │   │
-│  │  │ Easing │ │ Mouse  │ │ Noise  │ │Position│ │ Anchor │  │   │
-│  │  │ Motion │ │ Keys   │ │Fractals│ │ZIndex  │ │        │  │   │
-│  │  │Tweenetik│ │ Touch  │ │Patterns│ │ Tasks  │ │        │  │   │
-│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘  │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                  Utility Modules                          │   │
-│  │                    ┌────────┐                             │   │
-│  │                    │ logger │                             │   │
-│  │                    │ Logger │                             │   │
-│  │                    │Loggable│                             │   │
-│  │                    │DebugTab│                             │   │
-│  │                    └────────┘                             │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Module Responsibilities
-
-### Core Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **shapes** | Visual primitives and rendering | `Shape`, `Circle`, `Rectangle`, `Group`, `Transformable` |
-| **game** | Game loop, lifecycle, object management | `Game`, `Pipeline`, `GameObject`, `Scene` |
-| **painter** | Canvas context abstraction | `Painter`, `PainterShapes`, `PainterText` |
-
-### Support Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **motion** | Animation and tweening | `Motion`, `Tweenetik`, `Easing`, `Tween` |
-| **io** | Input handling | `EventEmitter`, `Mouse`, `Keys`, `Touch`, `Input` |
-| **math** | Mathematical utilities | `Random`, `Noise`, `Complex`, `Fractals`, `Patterns` |
-| **util** | Layout and positioning | `Layout`, `Position`, `ZOrderedCollection` |
-| **mixins** | Composable behaviors | `applyDraggable()`, `applyAnchor()` |
-
-### Utility Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **logger** | Debug and logging | `Logger`, `Loggable`, `DebugTab` |
-
-## Data Flow
-
-```
-User Input                     Game Loop
-    │                              │
-    ▼                              ▼
-┌────────┐     events         ┌────────┐
-│   IO   │ ──────────────────►│  Game  │
-└────────┘                    └────────┘
-                                   │
-                    ┌──────────────┼──────────────┐
-                    ▼              ▼              ▼
-              ┌──────────┐  ┌──────────┐   ┌──────────┐
-              │ Pipeline │  │ Tweenetik│   │  Painter │
-              │ update() │  │ update() │   │  clear() │
-              └──────────┘  └──────────┘   └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │GameObject│
-              │ update() │
-              │ render() │
-              └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │  Shape   │
-              │  draw()  │
-              └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │ Painter  │
-              │ Canvas   │
-              └──────────┘
-```
-
-## Design Patterns
-
-### 1. Inheritance Chain (Shapes)
-
-Shapes use a linear inheritance hierarchy where each class adds specific functionality:
-
-```
-Euclidian → Geometry2d → Traceable → Renderable → Transformable → Shape
-```
-
-See: [Rendering Pipeline](./rendering-pipeline.md)
-
-### 2. Static Singleton (Painter)
-
-`Painter` is a static utility class initialized once with the canvas context:
-
-```js
-Painter.init(ctx);
-Painter.shapes.circle(100, 100, 50);
-```
-
-### 3. Component Pattern (GameObject + Shape)
-
-GameObjects compose shapes rather than inheriting from them:
-
-```js
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Circle(40, { color: 'blue' });
-  }
-}
-```
-
-### 4. Mixin Pattern (Behaviors)
-
-Optional behaviors are applied via mixin functions:
-
-```js
-applyDraggable(gameObject, gameObject.shape);
-applyAnchor(gameObject, { anchor: 'top-right' });
-```
-
-### 5. Observer Pattern (Events)
-
-The `EventEmitter` provides pub-sub event handling:
-
-```js
-game.events.on('click', (e) => { ... });
-game.events.emit('custom-event', data);
-```
-
-## Entry Point
-
-The main entry point (`src/index.js`) re-exports all modules:
-
-```js
-export * from "./util";
-export * from "./math";
-export * from "./logger";
-export * from "./painter";
-export * from "./shapes";
-export * from "./io";
-export * from "./game";
-export * from "./motion";
-export * from "./mixins";
-```
-
-This allows importing any component from the main package:
-
-```js
-import { Game, Circle, Painter, Motion } from '@guinetik/gcanvas';
-```
-
-## Related
-
-- [Two-Layer Architecture](./two-layer-architecture.md) - Shape vs Game layer
-- [Rendering Pipeline](./rendering-pipeline.md) - Shape inheritance chain
-- [Game Lifecycle](./lifecycle.md) - Update/render cycle
-
-## See Also
-
-- [Shapes Module](../modules/shapes/README.md)
-- [Game Module](../modules/game/README.md)
-- [Painter Module](../modules/painter/README.md)