@guinetik/gcanvas 1.0.0

package/docs/modules/shapes/README.md

@@ -0,0 +1,221 @@
+# Shapes Module
+
+> 40+ drawable primitives and the shape inheritance hierarchy.
+
+## Overview
+
+The shapes module provides all visual primitives in GCanvas. Every shape inherits from a chain of base classes that add progressively more functionality.
+
+## Quick Start
+
+```js
+import { Circle, Rectangle, Star, Group } from 'gcanvas';
+
+// Create shapes
+const circle = new Circle(50, { x: 100, y: 100, color: 'red' });
+const rect = new Rectangle({ width: 80, height: 40, color: 'blue' });
+
+// Draw
+circle.draw();
+rect.draw();
+
+// Group shapes together
+const group = new Group({ x: 400, y: 300 });
+group.add(circle);
+group.add(rect);
+group.draw();
+```
+
+## Class Hierarchy
+
+```
+Euclidian ─────────── Position & size
+    │
+Geometry2d ────────── Bounding boxes & constraints
+    │
+Traceable ─────────── Debug visualization
+    │
+Renderable ────────── Visibility, opacity, shadows
+    │
+Transformable ─────── Rotation & scaling
+    │
+Shape ─────────────── Fill & stroke styling
+    │
+├── Circle
+├── Rectangle
+├── Star
+├── Triangle
+├── Polygon
+├── ... (40+ shapes)
+└── Group (container)
+```
+
+[View detailed hierarchy](./hierarchy.md)
+
+## Base Classes
+
+| Class | Purpose | Documentation |
+|-------|---------|---------------|
+| [Euclidian](./base/euclidian.md) | Position (x, y) and size (width, height) | [Link](./base/euclidian.md) |
+| [Geometry2d](./base/geometry2d.md) | Bounding boxes and constraints | [Link](./base/geometry2d.md) |
+| [Renderable](./base/renderable.md) | Visibility, opacity, shadows | [Link](./base/renderable.md) |
+| [Transformable](./base/transformable.md) | Rotation and scaling | [Link](./base/transformable.md) |
+| [Shape](./base/shape.md) | Fill, stroke, line styling | [Link](./base/shape.md) |
+
+## Available Shapes
+
+### 2D Primitives
+
+| Shape | Description |
+|-------|-------------|
+| Circle | Basic circle with radius |
+| Rectangle | Centered rectangle |
+| RoundedRectangle | Rectangle with rounded corners |
+| Square | Square (convenience) |
+| Triangle | Three-sided polygon |
+| Line | Line segment |
+| Arc | Curved arc segment |
+| Polygon | N-sided polygon |
+| Hexagon | Six-sided shape |
+
+### Complex Shapes
+
+| Shape | Description |
+|-------|-------------|
+| Star | Star with configurable points |
+| Heart | Heart shape |
+| Diamond | Diamond/rhombus |
+| Cross | Plus/cross shape |
+| Arrow | Arrow shape |
+| Pin | Map pin/marker |
+| Ring | Hollow ring/donut |
+| Cloud | Cloud-like shape |
+| PieSlice | Pie chart slice |
+
+### 3D-Looking Shapes
+
+| Shape | Description |
+|-------|-------------|
+| Cube | Isometric cube with face colors |
+| Sphere | Sphere with shading |
+| Cylinder | Cylindrical shape |
+| Cone | Cone/pyramid |
+| Prism | Triangular prism |
+
+### Special Shapes
+
+| Shape | Description |
+|-------|-------------|
+| TextShape | Rotatable, scalable text |
+| Image | Image rendering |
+| SVGShape | SVG path-based shapes |
+| BezierShape | Bezier curve shapes |
+| PatternRectangle | Pattern-filled rectangle |
+| StickFigure | Simple stick figure |
+
+### Containers
+
+| Class | Description |
+|-------|-------------|
+| Group | Container for composing multiple shapes |
+
+## Common Properties
+
+All shapes inherit these properties:
+
+```js
+// From Euclidian
+shape.x          // Center X position
+shape.y          // Center Y position
+shape.width      // Width
+shape.height     // Height
+
+// From Geometry2d
+shape.minX       // Minimum X constraint
+shape.maxX       // Maximum X constraint
+shape.minY       // Minimum Y constraint
+shape.maxY       // Maximum Y constraint
+shape.crisp      // Pixel-perfect alignment
+
+// From Renderable
+shape.visible    // Show/hide
+shape.opacity    // Transparency (0-1)
+shape.active     // Receive updates
+shape.zIndex     // Stacking order
+shape.shadowColor
+shape.shadowBlur
+shape.shadowOffsetX
+shape.shadowOffsetY
+
+// From Transformable
+shape.rotation   // Rotation in degrees
+shape.scaleX     // Horizontal scale
+shape.scaleY     // Vertical scale
+
+// From Shape
+shape.color      // Fill color
+shape.stroke     // Stroke color
+shape.lineWidth  // Stroke width
+shape.lineJoin   // "miter", "round", "bevel"
+shape.lineCap    // "butt", "round", "square"
+```
+
+## Usage Patterns
+
+### Basic Drawing
+
+```js
+const circle = new Circle(50, { x: 100, y: 100, color: 'red' });
+circle.draw();
+```
+
+### With Transforms
+
+```js
+const rect = new Rectangle({
+  width: 100,
+  height: 50,
+  color: '#4ecdc4',
+  rotation: 45,      // 45 degrees
+  scaleX: 1.5,
+  opacity: 0.8
+});
+rect.draw();
+```
+
+### Grouping Shapes
+
+```js
+const group = new Group({ x: 400, y: 300 });
+group.add(new Circle(30, { color: 'red' }));
+group.add(new Rectangle({ y: 50, width: 60, height: 30, color: 'blue' }));
+
+// Transform entire group
+group.rotation = 15;
+group.draw();
+```
+
+### Animation
+
+```js
+function animate() {
+  Painter.clear();
+
+  shape.rotation += 1;
+  shape.x = 400 + Math.sin(Date.now() * 0.001) * 100;
+
+  shape.draw();
+  requestAnimationFrame(animate);
+}
+```
+
+## Related
+
+- [Rendering Pipeline](../../concepts/rendering-pipeline.md) - How shapes render
+- [Two-Layer Architecture](../../concepts/two-layer-architecture.md) - Shape vs Game layer
+- [Painter Module](../painter/README.md) - Low-level drawing API
+
+## See Also
+
+- [Hello World](../../getting-started/hello-world.md)
+- [Shape Hierarchy](./hierarchy.md)

package/docs/modules/shapes/base/euclidian.md

@@ -0,0 +1,123 @@
+# Euclidian
+
+> The root class defining spatial properties for all visual objects.
+
+**Module:** [shapes](../README.md) | **Extends:** `Loggable` | **Source:** `src/shapes/euclidian.js`
+
+## Overview
+
+Euclidian is the foundation of all drawable objects in GCanvas. It defines the fundamental spatial contract: a 2D position and size. Before something becomes a shape, a renderable, or a transformable object, it first **exists in space**.
+
+This class is abstract and intended to be subclassed.
+
+## Constructor
+
+```js
+new Euclidian(options)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options` | `Object` | `{}` | Configuration options |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `x` | `number` | `0` | X position (center-based) |
+| `y` | `number` | `0` | Y position (center-based) |
+| `width` | `number` | `0` | Width in pixels |
+| `height` | `number` | `0` | Height in pixels |
+| `debug` | `boolean` | `false` | Enable debug visualization |
+| `debugColor` | `string` | `"#0f0"` | Debug outline color |
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `x` | `number` | X center position in canvas space |
+| `y` | `number` | Y center position in canvas space |
+| `width` | `number` | Width of the object (always ≥ 0) |
+| `height` | `number` | Height of the object (always ≥ 0) |
+| `debug` | `boolean` | Whether debug overlay is enabled |
+| `debugColor` | `string` | Color of the debug box outline |
+
+## Coordinate System
+
+GCanvas uses a **center-based** coordinate system:
+
+```
+    ┌────────────────────────────────┐
+    │                                │
+    │         (x, y)                 │
+    │            ●───────────────┐   │
+    │            │               │   │
+    │            │    width      │   │
+    │            │               │   │
+    │            └───────────────┘   │
+    │                   height       │
+    │                                │
+    └────────────────────────────────┘
+```
+
+The `(x, y)` point is the **center** of the object, not the top-left corner.
+
+## Example
+
+```js
+import { Euclidian } from 'gcanvas';
+
+// Euclidian is abstract, but shows the basic spatial contract
+const spatial = {
+  x: 100,       // Center at x=100
+  y: 100,       // Center at y=100
+  width: 50,    // 50 pixels wide
+  height: 30    // 30 pixels tall
+};
+
+// Top-left corner would be at (75, 85)
+// x - width/2 = 100 - 25 = 75
+// y - height/2 = 100 - 15 = 85
+```
+
+## Property Validation
+
+All properties are validated on set:
+
+```js
+shape.x = 100;        // Valid
+shape.x = null;       // Throws Error: "Invalid property value: x null"
+shape.x = undefined;  // Throws Error: "Invalid property value: x undefined"
+```
+
+Width and height are clamped to be non-negative:
+
+```js
+shape.width = -10;    // Sets width to 0
+shape.height = -5;    // Sets height to 0
+```
+
+## Inheritance
+
+```
+Loggable
+    └── Euclidian  <── You are here
+            └── Geometry2d
+                    └── Traceable
+                            └── Renderable
+                                    └── Transformable
+                                            └── Shape
+```
+
+## Related
+
+- [Geometry2d](./geometry2d.md) - Adds bounding boxes and constraints
+- [Shape Hierarchy](../hierarchy.md) - Full inheritance diagram
+- [Rendering Pipeline](../../../concepts/rendering-pipeline.md) - How shapes render
+
+## See Also
+
+- [Shapes Module](../README.md)
+- [Renderable](./renderable.md)

package/docs/modules/shapes/base/geometry2d.md

@@ -0,0 +1,204 @@
+# Geometry2d
+
+> Bounding box calculations and positional constraints.
+
+**Module:** [shapes](../README.md) | **Extends:** [Euclidian](./euclidian.md) | **Source:** `src/shapes/geometry.js`
+
+## Overview
+
+Geometry2d builds upon Euclidian by adding:
+
+- **Bounding logic** with memoization
+- **Constraint enforcement** (minX, maxX, minY, maxY)
+- **Property change tracking** for efficient recalculations
+
+This class is not concerned with transforms, rendering, or visibility. It's the core layer where **position + size = spatial identity**.
+
+## Constructor
+
+```js
+new Geometry2d(options)
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `minX` | `number` | `undefined` | Minimum X constraint |
+| `maxX` | `number` | `undefined` | Maximum X constraint |
+| `minY` | `number` | `undefined` | Minimum Y constraint |
+| `maxY` | `number` | `undefined` | Maximum Y constraint |
+| `crisp` | `boolean` | `true` | Round to whole pixels |
+
+Plus all options from [Euclidian](./euclidian.md).
+
+## Properties
+
+### Inherited from Euclidian
+
+`x`, `y`, `width`, `height`, `debug`, `debugColor`
+
+### Own Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `minX` | `number \| undefined` | Minimum allowed X value |
+| `maxX` | `number \| undefined` | Maximum allowed X value |
+| `minY` | `number \| undefined` | Minimum allowed Y value |
+| `maxY` | `number \| undefined` | Maximum allowed Y value |
+| `crisp` | `boolean` | Whether to round to whole pixels |
+| `boundsDirty` | `boolean` | Whether bounds need recalculation (readonly) |
+
+## Methods
+
+### getBounds()
+
+Returns the object's bounding box. Uses memoization to avoid unnecessary recomputation.
+
+```js
+const bounds = shape.getBounds();
+// { x: 100, y: 100, width: 50, height: 30 }
+```
+
+**Returns:** `{ x: number, y: number, width: number, height: number }`
+
+### calculateBounds()
+
+Called by `getBounds()` when bounds are dirty. Override in subclasses for custom bounds (e.g., rotated shapes).
+
+```js
+// Default implementation
+calculateBounds() {
+  return {
+    x: this.x,
+    y: this.y,
+    width: this.width,
+    height: this.height
+  };
+}
+```
+
+**Returns:** `{ x: number, y: number, width: number, height: number }`
+
+### getLocalPosition()
+
+Returns the object's top-left corner position. Useful for layout systems.
+
+```js
+const local = shape.getLocalPosition();
+// { x: 75, y: 85 } for a shape at (100,100) with width 50, height 30
+```
+
+**Returns:** `{ x: number, y: number }`
+
+### applyConstraints()
+
+Applies positional constraints and optionally rounds to whole pixels.
+
+```js
+shape.minX = 0;
+shape.maxX = 800;
+shape.x = -50;      // Out of bounds
+shape.applyConstraints();
+console.log(shape.x); // 0 (constrained to minX)
+```
+
+### markBoundsDirty()
+
+Marks bounds for recalculation. Called automatically when spatial properties change.
+
+```js
+shape.markBoundsDirty();
+// Next getBounds() call will recalculate
+```
+
+### setTopLeft(x, y)
+
+Sets position using top-left coordinates instead of center.
+
+```js
+shape.setTopLeft(0, 0); // Top-left at (0,0)
+// Center is now at (width/2, height/2)
+```
+
+**Returns:** `this` (for chaining)
+
+### setCenter(x, y)
+
+Sets the center position (same as setting x and y directly).
+
+```js
+shape.setCenter(400, 300);
+```
+
+**Returns:** `this` (for chaining)
+
+## Constraints Example
+
+```js
+const shape = new Circle(30, {
+  x: 400,
+  y: 300,
+  minX: 50,
+  maxX: 750,
+  minY: 50,
+  maxY: 550
+});
+
+// Shape can't go outside the constrained area
+shape.x = 900;
+shape.applyConstraints();
+console.log(shape.x); // 750 (clamped to maxX)
+```
+
+## Crisp Rendering
+
+When `crisp` is true, positions and dimensions are rounded to whole pixels:
+
+```js
+const shape = new Rectangle({
+  x: 100.7,
+  y: 50.3,
+  width: 80.5,
+  height: 40.2,
+  crisp: true
+});
+
+shape.applyConstraints();
+// x: 101, y: 50, width: 81, height: 40
+```
+
+This prevents blurry rendering from sub-pixel positioning.
+
+## Dirty Tracking
+
+Bounds are automatically marked dirty when spatial properties change:
+
+```js
+shape.x = 200;           // Marks bounds dirty
+shape.getBounds();       // Recalculates and caches
+shape.getBounds();       // Returns cached value (fast)
+shape.width = 100;       // Marks bounds dirty again
+```
+
+## Inheritance
+
+```
+Euclidian
+    └── Geometry2d  <── You are here
+            └── Traceable
+                    └── Renderable
+                            └── Transformable
+                                    └── Shape
+```
+
+## Related
+
+- [Euclidian](./euclidian.md) - Parent class
+- [Renderable](./renderable.md) - Next in hierarchy
+- [Shape Hierarchy](../hierarchy.md) - Full inheritance diagram
+
+## See Also
+
+- [Shapes Module](../README.md)
+- [Transformable](./transformable.md) - Adds rotation/scale-aware bounds