@guinetik/gcanvas 1.0.0

package/docs/concepts/rendering-pipeline.md

@@ -0,0 +1,279 @@
+# Rendering Pipeline
+
+> The shape inheritance chain from Euclidian to concrete shapes.
+
+## Overview
+
+Every visual element in GCanvas inherits from a chain of base classes. Each layer adds specific functionality, building from simple spatial properties to full rendering capabilities.
+
+## The Inheritance Chain
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                  │
+│   Euclidian                                                      │
+│   ├── x, y (position)                                           │
+│   ├── width, height (dimensions)                                │
+│   └── debug rendering support                                   │
+│       │                                                          │
+│       ▼                                                          │
+│   Geometry2d                                                     │
+│   ├── getBounds() - bounding box calculation                    │
+│   ├── minX, maxX, minY, maxY - constraints                      │
+│   ├── crisp - pixel-perfect alignment                           │
+│   └── dirty flag tracking                                       │
+│       │                                                          │
+│       ▼                                                          │
+│   Traceable                                                      │
+│   ├── drawDebug() - debug visualization                         │
+│   └── logging capabilities                                      │
+│       │                                                          │
+│       ▼                                                          │
+│   Renderable                                                     │
+│   ├── visible - show/hide                                       │
+│   ├── opacity - transparency (0-1)                              │
+│   ├── shadowColor, shadowBlur, shadowOffset                     │
+│   ├── blendMode - canvas composite operation                    │
+│   ├── zIndex - stacking order                                   │
+│   └── render() - main render lifecycle                          │
+│       │                                                          │
+│       ▼                                                          │
+│   Transformable                                                  │
+│   ├── rotation - angle in radians                               │
+│   ├── scaleX, scaleY - scaling factors                          │
+│   ├── applyTransforms() - canvas transform                      │
+│   └── getTransformedBounds() - rotated bounds                   │
+│       │                                                          │
+│       ▼                                                          │
+│   Shape                                                          │
+│   ├── color - fill color                                        │
+│   ├── stroke - stroke color                                     │
+│   ├── lineWidth, lineJoin, lineCap                              │
+│   └── draw() - abstract (override in subclasses)                │
+│       │                                                          │
+│       ▼                                                          │
+│   ┌─────────┬─────────┬─────────┬─────────┬─────────┐           │
+│   │ Circle  │Rectangle│  Star   │  Cube   │   ...   │           │
+│   │ draw()  │ draw()  │ draw()  │ draw()  │         │           │
+│   └─────────┴─────────┴─────────┴─────────┴─────────┘           │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Layer Details
+
+### 1. Euclidian
+
+**Source:** `src/shapes/euclidian.js`
+
+The foundation class providing basic spatial properties.
+
+```js
+class Euclidian {
+  x = 0;        // Center X position
+  y = 0;        // Center Y position
+  width = 0;    // Width
+  height = 0;   // Height
+}
+```
+
+**Key Concept:** Position is center-based, not top-left. A shape at `(100, 100)` has its center at that point.
+
+### 2. Geometry2d
+
+**Source:** `src/shapes/geometry.js`
+
+Adds bounding box calculations and positional constraints.
+
+```js
+// Get the bounding box
+const bounds = shape.getBounds();
+// { x, y, width, height }
+
+// Constrain position
+shape.minX = 0;
+shape.maxX = 800;
+shape.applyConstraints();
+```
+
+### 3. Traceable
+
+**Source:** `src/shapes/traceable.js`
+
+Adds debug visualization capabilities.
+
+```js
+shape.drawDebug(ctx); // Draw bounding box and center point
+```
+
+### 4. Renderable
+
+**Source:** `src/shapes/renderable.js`
+
+Adds visual properties and the main `render()` lifecycle.
+
+```js
+shape.visible = true;
+shape.opacity = 0.8;
+shape.shadowColor = 'rgba(0,0,0,0.5)';
+shape.shadowBlur = 10;
+shape.shadowOffsetX = 5;
+shape.shadowOffsetY = 5;
+```
+
+**The `render()` method:**
+
+```js
+render() {
+  if (!this.visible || this.opacity <= 0) return;
+
+  Painter.save();
+  Painter.effects.setBlendMode(this.blendMode);
+  Painter.opacity.pushOpacity(this.opacity);
+  Painter.translateTo(this.x, this.y);
+
+  // Apply shadows
+  if (this.shadowColor) {
+    ctx.shadowColor = this.shadowColor;
+    ctx.shadowBlur = this.shadowBlur;
+    ctx.shadowOffsetX = this.shadowOffsetX;
+    ctx.shadowOffsetY = this.shadowOffsetY;
+  }
+
+  this.draw();  // Call subclass implementation
+
+  Painter.opacity.popOpacity();
+  Painter.restore();
+}
+```
+
+### 5. Transformable
+
+**Source:** `src/shapes/transformable.js`
+
+Adds rotation and scaling.
+
+```js
+shape.rotation = Math.PI / 4;  // 45 degrees
+shape.scaleX = 2.0;
+shape.scaleY = 0.5;
+```
+
+**Transform application:**
+
+```js
+applyTransforms() {
+  if (this.rotation !== 0) {
+    Painter.rotate(this.rotation);
+  }
+  if (this.scaleX !== 1 || this.scaleY !== 1) {
+    Painter.scale(this.scaleX, this.scaleY);
+  }
+}
+```
+
+### 6. Shape
+
+**Source:** `src/shapes/shape.js`
+
+Adds canvas styling (fill and stroke).
+
+```js
+const circle = new Circle(50, {
+  color: 'red',           // Fill color
+  stroke: 'black',        // Stroke color
+  lineWidth: 2,           // Stroke width
+  lineJoin: 'round',      // Line join style
+  lineCap: 'round'        // Line cap style
+});
+```
+
+## The Render Flow
+
+When `shape.render()` is called (or `shape.draw()` directly):
+
+```
+1. render() called
+   │
+   ├─► Check visible && opacity > 0
+   │
+   ├─► Painter.save()           ─── Save canvas state
+   │
+   ├─► Set blend mode
+   │
+   ├─► Push opacity
+   │
+   ├─► Translate to (x, y)      ─── Move to shape center
+   │
+   ├─► Apply shadows
+   │
+   ├─► draw() called            ─── Subclass implementation
+   │   │
+   │   ├─► applyTransforms()    ─── Rotation & scale
+   │   │
+   │   └─► Painter.shapes.*     ─── Actual drawing
+   │
+   ├─► Pop opacity
+   │
+   └─► Painter.restore()        ─── Restore canvas state
+```
+
+## Coordinate System
+
+GCanvas uses a **center-based** coordinate system:
+
+```
+       ┌────────────────────────────────────┐
+       │            Canvas                   │
+       │                                     │
+       │      (0,0) top-left                │
+       │        ┌──────────────────┐        │
+       │        │                  │        │
+       │        │    (x, y)        │        │
+       │        │       ●──────────┼─width  │
+       │        │       │          │        │
+       │        │       │          │        │
+       │        └───────┼──────────┘        │
+       │              height                 │
+       │                                     │
+       └────────────────────────────────────┘
+```
+
+The `(x, y)` point is the **center** of the shape, not the top-left corner.
+
+## Creating Custom Shapes
+
+Extend `Shape` and implement `draw()`:
+
+```js
+import { Shape, Painter } from 'gcanvas';
+
+class CustomShape extends Shape {
+  constructor(options = {}) {
+    super(options);
+    this.customProp = options.customProp ?? 'default';
+  }
+
+  draw() {
+    super.draw();  // Apply transforms
+
+    // Draw using Painter
+    Painter.shapes.fillCircle(0, 0, this.width / 2, this.color);
+    Painter.shapes.strokeCircle(0, 0, this.width / 2, this.stroke, this.lineWidth);
+  }
+}
+```
+
+## Related
+
+- [Architecture Overview](./architecture-overview.md) - Full system architecture
+- [Two-Layer Architecture](./two-layer-architecture.md) - Shape vs Game layer
+- [Shape Hierarchy](../modules/shapes/hierarchy.md) - Detailed class documentation
+
+## See Also
+
+- [Euclidian](../modules/shapes/base/euclidian.md)
+- [Geometry2d](../modules/shapes/base/geometry2d.md)
+- [Renderable](../modules/shapes/base/renderable.md)
+- [Transformable](../modules/shapes/base/transformable.md)
+- [Shape](../modules/shapes/base/shape.md)

package/docs/concepts/tde-zorder.md

@@ -0,0 +1,106 @@
+# TDE Demo Z-Order Rendering System
+
+This document describes the z-ordering (depth sorting) system used in the Tidal Disruption Event (TDE) demo.
+
+## Overview
+
+The TDE demo uses a 3D scene with multiple objects that need to be rendered in the correct order based on their depth relative to the camera. The system uses a combination of:
+
+1. **Static z-index buckets** for objects that always render in a fixed order
+2. **Dynamic z-index updates** for objects whose render order depends on camera position
+
+## Z-Index Buckets
+
+Objects are assigned to z-index buckets. Lower z-index values render first (behind), higher values render later (in front).
+
+**Only the Star has a dynamic z-index** that changes based on its position relative to the camera. The TidalStream particles always render on top for a cleaner visual effect.
+
+| Object | Z-Index | Description |
+|--------|---------|-------------|
+| Star (back) | 10 | Star when behind black hole |
+| BlackHole | 15 | Dark shadow - at the back |
+| AccretionDisk | 20 | Disk renders over the black hole |
+| Star (front) | 25 | Star when in front of black hole |
+| TidalStream | 30 | Particles - always on top |
+| RelativisticJets | 40 | Jets - always on top |
+
+### Layering by Camera View
+
+**When star is IN FRONT of black hole:**
+- Stream (30) > Star (25) > Disk (20) > BlackHole (15)
+
+**When star is BEHIND black hole:**
+- Stream (30) > Disk (20) > BlackHole (15) > Star (10)
+
+The accretion disk particles curve around the black hole visually, and the stream always stays on top.
+
+## Rendering Rules
+
+### Rule 1: TidalStream Always Behind Star
+The tidal stream particles (z-index 10) always render behind the star (z-index 25-35). This ensures the star is always visible and the stream appears to emanate from behind/around it.
+
+### Rule 2: Star in Front of Black Hole (When Closer)
+When the star is closer to the camera than the black hole, the star's z-index is set to 35 (starFront), which is higher than the black hole's z-index of 30. This causes the star to render after (on top of) the black hole.
+
+### Rule 3: Black Hole in Front of Star (When Star is Behind)
+When the star is farther from the camera than the black hole, the star's z-index is set to 25 (starBack), which is lower than the black hole's z-index of 30. This causes the black hole to render after (on top of) the star.
+
+## Dynamic Z-Order Algorithm
+
+The `BlackHoleScene.updateStarZOrder()` method handles dynamic z-ordering:
+
+```javascript
+updateStarZOrder() {
+    const camera = this.game.camera;
+    
+    // Project star position to get depth after camera rotation
+    const projStar = camera.project(star.x, star.y, star.z);
+    
+    // Black hole is always at origin
+    const projBH = camera.project(0, 0, 0);
+    
+    // Lower projected z = closer to camera
+    const starInFront = projStar.z < projBH.z;
+    
+    // Update z-index based on depth comparison
+    star.zIndex = starInFront ? Z.starFront : Z.starBack;
+}
+```
+
+### Critical: Update Order
+
+The z-order update **must be called AFTER** the star position is updated each frame. This is done in `TDEDemo.update()` at the end, after all state-based position updates:
+
+```javascript
+// In TDEDemo.update(), at the end:
+if (this.scene) {
+    this.scene.updateStarZOrder();
+}
+```
+
+If called before the position update, it uses stale position data and causes incorrect ordering.
+
+## Camera3D Projection
+
+The `Camera3D.project()` method returns:
+- `x, y`: Screen position
+- `z`: Depth after rotation (lower = closer to camera)
+- `scale`: Perspective scale factor
+
+The depth (`z`) value is used for z-order comparisons. Objects with lower depth values are closer to the camera and should render on top.
+
+## Scene3D Sorting
+
+`Scene3D` sorts children before rendering:
+
+1. **Primary sort**: By `zIndex` (lower renders first)
+2. **Secondary sort**: By projected `z` depth (back-to-front, as tie-breaker)
+
+This ensures objects with different z-indices render in the correct order, while objects with the same z-index are sorted by actual depth.
+
+## Implementation Files
+
+- `demos/js/tde/blackholescene.js` - Main scene with z-ordering logic
+- `src/game/objects/scene3d.js` - Base Scene3D with depth sorting
+- `src/util/camera3d.js` - Camera projection utilities
+

package/docs/concepts/two-layer-architecture.md

@@ -0,0 +1,229 @@
+# Two-Layer Architecture
+
+> Understanding when to use the Shape Layer vs the Game Layer.
+
+## Overview
+
+GCanvas provides two complementary approaches to building canvas applications:
+
+1. **Shape Layer** - For declarative, static graphics
+2. **Game Layer** - For interactive, dynamic applications
+
+You can use either layer independently or combine them for complex applications.
+
+## Shape Layer
+
+The Shape Layer is for drawing graphics without a game loop. Shapes are self-contained objects that know how to render themselves.
+
+### When to Use
+
+- Static visualizations
+- Data charts and graphs
+- Decorative graphics
+- Simple animations (manual redraw)
+- Learning canvas fundamentals
+
+### Key Classes
+
+- `Shape` and subclasses (`Circle`, `Rectangle`, `Star`, etc.)
+- `Group` for composing shapes
+- `Painter` for direct canvas control
+
+### Example
+
+```js
+import { Circle, Rectangle, Group, Painter } from 'gcanvas';
+
+// Initialize Painter with canvas context
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+// Create shapes
+const circle = new Circle(50, { x: 100, y: 100, color: 'red' });
+const rect = new Rectangle(80, 40, { x: 200, y: 100, color: 'blue' });
+
+// Draw immediately
+Painter.clear();
+circle.draw();
+rect.draw();
+```
+
+### Characteristics
+
+| Aspect | Shape Layer |
+|--------|-------------|
+| Loop | None (manual redraw) |
+| State | Shapes hold their own state |
+| Input | Manual event handling |
+| Animation | Call draw() on each frame manually |
+| Complexity | Simple, direct |
+
+## Game Layer
+
+The Game Layer provides a complete game loop with automatic updates, rendering, and input handling.
+
+### When to Use
+
+- Games and simulations
+- Interactive applications
+- Real-time animations
+- Complex state management
+- Multi-object coordination
+
+### Key Classes
+
+- `Game` - Main loop and canvas management
+- `Pipeline` - Object lifecycle management
+- `GameObject` - Interactive entities
+- `Scene` - Hierarchical organization
+
+### Example
+
+```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) {
+    // Called every frame
+    if (this.game.input.isKeyDown('ArrowRight')) {
+      this.shape.x += 200 * dt;
+    }
+  }
+
+  render() {
+    // Called every frame after update
+    this.shape.draw();
+  }
+
+  onPointerDown(e) {
+    // Automatic input handling
+    console.log('Clicked!');
+  }
+}
+
+class MyGame extends Game {
+  init() {
+    this.enableFluidSize();
+    const scene = new Scene(this);
+    scene.add(new Player(this));
+    this.pipeline.add(scene);
+  }
+}
+
+const game = new MyGame(document.getElementById('canvas'));
+game.start();
+```
+
+### Characteristics
+
+| Aspect | Game Layer |
+|--------|-------------|
+| Loop | Automatic (requestAnimationFrame) |
+| State | Managed by Pipeline |
+| Input | Automatic dispatching to objects |
+| Animation | Built-in with dt (delta time) |
+| Complexity | Full-featured |
+
+## Comparison
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Shape Layer                             │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
+│  │ Circle  │  │Rectangle│  │  Star   │  ... more shapes    │
+│  └────┬────┘  └────┬────┘  └────┬────┘                      │
+│       │            │            │                            │
+│       └────────────┼────────────┘                            │
+│                    ▼                                         │
+│              ┌──────────┐                                    │
+│              │  Group   │  (optional composition)            │
+│              └────┬─────┘                                    │
+│                   │                                          │
+│                   ▼                                          │
+│              ┌──────────┐                                    │
+│              │  draw()  │  (manual call)                     │
+│              └──────────┘                                    │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│                      Game Layer                              │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                       Game                           │    │
+│  │  ┌─────────────────────────────────────────────┐    │    │
+│  │  │                   Pipeline                   │    │    │
+│  │  │  ┌─────────────────────────────────────┐    │    │    │
+│  │  │  │               Scene                  │    │    │    │
+│  │  │  │  ┌───────────┐  ┌───────────┐       │    │    │    │
+│  │  │  │  │GameObject │  │GameObject │  ...  │    │    │    │
+│  │  │  │  │  + Shape  │  │  + Shape  │       │    │    │    │
+│  │  │  │  └───────────┘  └───────────┘       │    │    │    │
+│  │  │  └─────────────────────────────────────┘    │    │    │
+│  │  └─────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                            │                                 │
+│                            ▼                                 │
+│                     ┌────────────┐                           │
+│                     │ Game Loop  │  (automatic)              │
+│                     │ update(dt) │                           │
+│                     │ render()   │                           │
+│                     └────────────┘                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Mixing Layers
+
+You can use shapes without GameObjects, or combine both approaches:
+
+```js
+class HybridGame extends Game {
+  init() {
+    // Game layer for interactive elements
+    const scene = new Scene(this);
+    scene.add(new Player(this));
+    this.pipeline.add(scene);
+
+    // Shape layer for static background
+    this.background = new Group();
+    this.background.add(new Rectangle(this.width, this.height, { color: '#222' }));
+  }
+
+  render() {
+    // Draw static shapes first
+    this.background.draw();
+
+    // Then let pipeline draw interactive objects
+    super.render();
+  }
+}
+```
+
+## Decision Guide
+
+| If you need... | Use |
+|---------------|-----|
+| Static graphics | Shape Layer |
+| Simple animations | Shape Layer + manual loop |
+| Keyboard/mouse input | Game Layer |
+| Multiple interactive objects | Game Layer |
+| Collision detection | Game Layer |
+| Scene organization | Game Layer |
+| Quick prototype | Shape Layer |
+| Full game | Game Layer |
+
+## Related
+
+- [Architecture Overview](./architecture-overview.md) - Full system architecture
+- [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)
+- [Getting Started: Hello World](../getting-started/hello-world.md)