@guinetik/gcanvas 1.0.2 → 1.0.4

package/docs/concepts/rendering-pipeline.md

@@ -1,279 +0,0 @@
-# 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 '@guinetik/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/shapes-vs-gameobjects.md

@@ -1,187 +0,0 @@
-# Shapes vs GameObjects
-
-GCanvas serves two distinct use cases with different abstractions. Understanding when to use each is key to working effectively with the library.
-
-## Overview
-
-| Aspect | Shapes | GameObjects |
-|--------|--------|-------------|
-| Purpose | Direct canvas rendering | Managed game pipeline |
-| Game loop | Not required | Required |
-| Rendering | Call `render()` manually | Automatic via pipeline |
-| State | Stateless between frames | Maintains state |
-| Lifecycle | None | `update(dt)` / `draw()` |
-| Best for | Generative art, static visuals | Games, animations, interactive apps |
-
-## The Two Hierarchies
-
-### Shape Hierarchy (Drawing)
-
-```
-Euclidian → Geometry2d → Renderable → Transformable → Shape
-```
-
-- **Euclidian**: Basic positioning (x, y, width, height)
-- **Geometry2d**: Bounds constraints, bounding box calculations
-- **Renderable**: Visibility, opacity, shadows
-- **Transformable**: Rotation, scaling
-- **Shape**: Styling (fill, stroke, lineWidth)
-
-### GameObject Hierarchy (Pipeline)
-
-```
-GameObject → Scene / Sprite / Text
-```
-
-- **GameObject**: Base class with `update(dt)` and `draw()` lifecycle
-- **Scene**: Container for other GameObjects
-- **Sprite**: Animated GameObject with frame-by-frame timeline
-- **Text**: Text rendering with automatic updates
-
-### Containers
-
-| Container | Holds | Has update()? |
-|-----------|-------|---------------|
-| `Group` | Shapes | No |
-| `Scene` | GameObjects | Yes |
-
-## When to Use What
-
-| Use Case | Use This | Why |
-|----------|----------|-----|
-| Static visualization | `Shape` + `render()` | No update loop needed |
-| Generative art | `Shape`, `Group` | Direct control, no overhead |
-| Game character | `Sprite` (GameObject) | Needs update cycle for animation |
-| UI elements | `Text`, `Scene` | Pipeline handles positioning |
-| Complex scene | `Scene` with children | Hierarchical transforms, lifecycle |
-| Composite shape | `Group` | Transform multiple shapes together |
-
-## Example: Shapes Only (No Game Loop)
-
-You can use GCanvas purely for drawing without any game infrastructure:
-
-```javascript
-import { Circle, Rectangle, Group, Painter } from "gcanvas";
-
-// Get canvas context
-const canvas = document.getElementById("canvas");
-const ctx = canvas.getContext("2d");
-Painter.ctx = ctx;
-
-// Create shapes
-const circle = new Circle(50, { x: 100, y: 100, color: "#0f0" });
-const rect = new Rectangle({ x: 200, y: 100, width: 80, height: 60, color: "#0ff" });
-
-// Render directly - no game loop needed
-circle.render();
-rect.render();
-
-// Group multiple shapes
-const group = new Group({ x: 300, y: 100, rotation: Math.PI / 4 });
-group.add(new Circle(20, { color: "#f0f" }));
-group.add(new Rectangle({ y: 30, width: 40, height: 20, color: "#ff0" }));
-group.render();
-```
-
-> **Note:** This is perfect for one-off drawings, generative art, or when you want full control over the render loop.
-
-## Example: GameObjects with Pipeline
-
-When you need animation, input handling, and managed lifecycles:
-
-```javascript
-import { Game, Scene, Sprite, Text, Circle, Keys } from "gcanvas";
-
-class MyGame extends Game {
-  init() {
-    super.init();
-
-    // Create a scene (GameObject container)
-    this.scene = new Scene(this, { anchor: "center" });
-
-    // Create a sprite with animation (GameObject)
-    this.player = new Sprite(this, { x: 0, y: 0, frameRate: 10 });
-    this.player.addFrame(new Circle(20, { color: "#0f0" }));
-    this.player.addFrame(new Circle(25, { color: "#0ff" }));
-    this.player.play();
-
-    // Add to scene
-    this.scene.add(this.player);
-
-    // Add scene to pipeline - now it's managed
-    this.pipeline.add(this.scene);
-
-    // Input handling
-    this.events.on(Keys.SPACE, () => this.player.pause());
-  }
-
-  update(dt) {
-    super.update(dt);
-    // Player sprite automatically updates via pipeline
-  }
-}
-```
-
-> **Note:** GameObjects get their `update(dt)` called automatically by the pipeline each frame.
-
-## Bridging: Shape to GameObject
-
-Sometimes you have a Shape (or Group of shapes) that you want to add to the pipeline. Use `ShapeGOFactory`:
-
-```javascript
-import { Game, Group, Circle, Rectangle, ShapeGOFactory } from "gcanvas";
-
-class MyGame extends Game {
-  init() {
-    super.init();
-
-    // Create a Group of shapes
-    const avatar = new Group();
-    avatar.add(new Circle(30, { color: "#0f0" }));           // head
-    avatar.add(new Rectangle({ y: 50, width: 40, height: 60, color: "#0f0" })); // body
-
-    // Wrap it as a GameObject so it can join the pipeline
-    const avatarGO = ShapeGOFactory.create(this, avatar, {
-      x: 100,
-      y: 100,
-      interactive: true  // enables click/hover events
-    });
-
-    // Now it's a proper GameObject
-    this.pipeline.add(avatarGO);
-  }
-}
-```
-
-> **Important:** Never put GameObjects inside Groups. Group is a Shape container - it won't call `update()` on its children. Always use Scene for GameObjects.
-
-## Quick Reference
-
-| Class | Type | Container | Has update()? |
-|-------|------|-----------|---------------|
-| `Circle`, `Rectangle`, etc. | Shape | Group | No |
-| `Group` | Shape container | Group | No |
-| `TextShape` | Shape | Group | No |
-| `GameObject` | Base GO | Scene / Pipeline | Yes |
-| `Scene` | GO container | Scene / Pipeline | Yes |
-| `Sprite` | Animated GO | Scene / Pipeline | Yes |
-| `Text` | Text GO | Scene / Pipeline | Yes |
-
-## TL;DR
-
-**Just Drawing?**
-- Use `Shape`, `Group`
-- Call `.render()` yourself
-- No Game class needed
-
-**Building a Game?**
-- Use `GameObject`, `Scene`, `Sprite`
-- Add to `pipeline`
-- Extend `Game` class
-
-## See Also
-
-- [Coordinate System](./coordinate-system.md) - How positioning works (center-based, parent-child, Camera3D)
-- [Rendering Pipeline](./rendering-pipeline.md) - Deep dive into the Shape hierarchy
-- [Architecture Overview](./architecture-overview.md) - High-level system design
-- [Lifecycle](./lifecycle.md) - GameObject lifecycle details

package/docs/concepts/tde-zorder.md

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