@guinetik/gcanvas 1.0.0

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

@@ -0,0 +1,215 @@
+# Renderable
+
+> Visibility, opacity, shadows, and the render lifecycle.
+
+**Module:** [shapes](../README.md) | **Extends:** `Traceable` | **Source:** `src/shapes/renderable.js`
+
+## Overview
+
+Renderable introduces the core rendering lifecycle. It knows when to draw, how to draw, and when **not** to draw (invisible, opacity = 0).
+
+This class adds:
+- **Rendering lifecycle control** (`render()`)
+- **Canvas state management** (save/restore)
+- **Visual properties** (opacity, visibility)
+- **Shadow styling** support
+
+## Constructor
+
+```js
+new Renderable(options)
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `visible` | `boolean` | `true` | Whether to draw this object |
+| `opacity` | `number` | `1` | Alpha transparency (0–1) |
+| `active` | `boolean` | `true` | Whether to receive updates |
+| `zIndex` | `number` | `0` | Stacking order |
+| `blendMode` | `string` | `"source-over"` | Canvas composite operation |
+| `shadowColor` | `string` | `undefined` | Shadow color |
+| `shadowBlur` | `number` | `0` | Shadow blur radius |
+| `shadowOffsetX` | `number` | `0` | Shadow X offset |
+| `shadowOffsetY` | `number` | `0` | Shadow Y offset |
+
+Plus all options from [Geometry2d](./geometry2d.md).
+
+## Properties
+
+### Inherited
+
+From Euclidian: `x`, `y`, `width`, `height`, `debug`, `debugColor`
+
+From Geometry2d: `minX`, `maxX`, `minY`, `maxY`, `crisp`, `boundsDirty`
+
+### Own Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `visible` | `boolean` | Show/hide the object |
+| `opacity` | `number` | Transparency (0 = invisible, 1 = opaque) |
+| `active` | `boolean` | Whether to call `update()` |
+| `zIndex` | `number` | Stacking order (higher = on top) |
+| `shadowColor` | `string \| undefined` | CSS color for shadow |
+| `shadowBlur` | `number` | Shadow blur radius in pixels |
+| `shadowOffsetX` | `number` | Horizontal shadow offset |
+| `shadowOffsetY` | `number` | Vertical shadow offset |
+| `tick` | `number` | Total time object has been alive (readonly) |
+
+## Methods
+
+### render()
+
+Main rendering lifecycle method. Handles canvas state, applies effects, and calls `draw()`.
+
+```js
+shape.render();
+```
+
+**Render flow:**
+
+```
+render()
+├── Check visible && opacity > 0
+├── Painter.save()
+├── Set blend mode
+├── Push opacity
+├── Translate to (x, y)
+├── Apply shadows
+├── draw()  ← subclass implements this
+├── Pop opacity
+└── Painter.restore()
+```
+
+### draw()
+
+Called by `render()` to do actual drawing. Override in subclasses.
+
+```js
+class MyShape extends Renderable {
+  draw() {
+    // Custom drawing logic
+    Painter.shapes.fillCircle(0, 0, 50, 'red');
+  }
+}
+```
+
+### update(dt)
+
+Called once per frame if the object is active.
+
+```js
+shape.update(0.016); // dt in seconds
+
+// Override in subclasses
+update(dt) {
+  this.x += 100 * dt;  // Move 100 pixels per second
+  super.update(dt);
+}
+```
+
+**Parameters:**
+- `dt` (`number`): Time since last frame in seconds
+
+### applyShadow(ctx)
+
+Applies shadow styles to the canvas context.
+
+```js
+shape.applyShadow(Painter.ctx);
+```
+
+## Visibility Control
+
+```js
+// Hide the shape (won't render)
+shape.visible = false;
+
+// Show the shape
+shape.visible = true;
+
+// Make semi-transparent
+shape.opacity = 0.5;
+
+// Fully transparent (same as invisible)
+shape.opacity = 0;
+```
+
+## Shadow Effects
+
+```js
+const shape = new Circle(50, {
+  x: 200,
+  y: 200,
+  color: '#4ecdc4',
+  shadowColor: 'rgba(0,0,0,0.5)',
+  shadowBlur: 15,
+  shadowOffsetX: 5,
+  shadowOffsetY: 5
+});
+```
+
+## Z-Index Ordering
+
+Objects are rendered in z-index order (low to high):
+
+```js
+const background = new Rectangle({ zIndex: 0 });
+const player = new Circle({ zIndex: 10 });
+const ui = new Rectangle({ zIndex: 100 });
+
+// Render order: background → player → ui
+```
+
+## Active vs Visible
+
+| Property | Effect |
+|----------|--------|
+| `visible = false` | Skips `render()`, still calls `update()` |
+| `active = false` | Skips `update()`, still calls `render()` |
+| Both `false` | Object is completely dormant |
+
+```js
+// Pause updates but keep drawing
+shape.active = false;
+
+// Pause everything
+shape.active = false;
+shape.visible = false;
+```
+
+## Blend Modes
+
+GCanvas supports standard canvas composite operations:
+
+```js
+shape.blendMode = 'multiply';
+shape.blendMode = 'screen';
+shape.blendMode = 'overlay';
+// etc.
+```
+
+Common values: `source-over` (default), `multiply`, `screen`, `overlay`, `darken`, `lighten`
+
+## Inheritance
+
+```
+Geometry2d
+    └── Traceable
+            └── Renderable  <── You are here
+                    └── Transformable
+                            └── Shape
+```
+
+## Related
+
+- [Geometry2d](./geometry2d.md) - Parent class
+- [Transformable](./transformable.md) - Adds rotation/scale
+- [Shape Hierarchy](../hierarchy.md) - Full inheritance diagram
+
+## See Also
+
+- [Shapes Module](../README.md)
+- [Game Lifecycle](../../../concepts/lifecycle.md) - Update/render cycle

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

@@ -0,0 +1,262 @@
+# Shape
+
+> Fill color, stroke, and line styling for drawable primitives.
+
+**Module:** [shapes](../README.md) | **Extends:** [Transformable](./transformable.md) | **Source:** `src/shapes/shape.js`
+
+## Overview
+
+Shape is the base class for all drawable geometric primitives. It's the first class in the hierarchy to express **canvas styling intent**:
+
+- Fill & stroke colors
+- Line width & join styles
+- Line cap styles
+
+Shape does not define geometry — that's up to subclasses like Circle, Rectangle, etc.
+
+## Constructor
+
+```js
+new Shape(options)
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `color` | `string \| null` | `null` | Fill color (CSS color) |
+| `stroke` | `string \| null` | `null` | Stroke color (CSS color) |
+| `lineWidth` | `number` | `1` | Stroke width in pixels |
+| `lineJoin` | `string` | `"miter"` | Line join style |
+| `lineCap` | `string` | `"butt"` | Line cap style |
+| `miterLimit` | `number` | `10` | Maximum miter length |
+
+Plus all options from [Transformable](./transformable.md).
+
+## Properties
+
+### Inherited
+
+From Euclidian: `x`, `y`, `width`, `height`, `debug`, `debugColor`
+
+From Geometry2d: `minX`, `maxX`, `minY`, `maxY`, `crisp`
+
+From Renderable: `visible`, `opacity`, `active`, `zIndex`, `shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY`
+
+From Transformable: `rotation`, `scaleX`, `scaleY`
+
+### Own Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string \| null` | Fill color (CSS color string) |
+| `stroke` | `string \| null` | Stroke color (CSS color string) |
+| `lineWidth` | `number` | Width of stroke in pixels |
+| `lineJoin` | `"miter" \| "round" \| "bevel"` | Line join style |
+| `lineCap` | `"butt" \| "round" \| "square"` | Line cap style |
+| `miterLimit` | `number` | Maximum miter length before bevel |
+
+## Fill and Stroke
+
+```js
+// Fill only
+const filled = new Circle(50, {
+  color: 'red'
+});
+
+// Stroke only
+const outlined = new Circle(50, {
+  stroke: 'blue',
+  lineWidth: 2
+});
+
+// Both fill and stroke
+const both = new Circle(50, {
+  color: 'red',
+  stroke: 'black',
+  lineWidth: 2
+});
+```
+
+## Color Formats
+
+Any valid CSS color string:
+
+```js
+shape.color = 'red';                    // Named color
+shape.color = '#ff0000';                // Hex
+shape.color = '#f00';                   // Short hex
+shape.color = 'rgb(255, 0, 0)';        // RGB
+shape.color = 'rgba(255, 0, 0, 0.5)';  // RGBA
+shape.color = 'hsl(0, 100%, 50%)';     // HSL
+```
+
+## Line Join Styles
+
+Controls how lines meet at corners:
+
+```js
+shape.lineJoin = 'miter';  // Sharp corners (default)
+shape.lineJoin = 'round';  // Rounded corners
+shape.lineJoin = 'bevel';  // Beveled corners
+```
+
+```
+  miter          round          bevel
+    ╱              ╱              ╱
+   ╱              ╱              ╱
+──┼──          ──╲──          ──┘──
+   ╲              ╲              ╲
+    ╲              ╲              ╲
+```
+
+## Line Cap Styles
+
+Controls how line endpoints look:
+
+```js
+shape.lineCap = 'butt';    // Flat end at endpoint (default)
+shape.lineCap = 'round';   // Rounded end
+shape.lineCap = 'square';  // Square end extending past endpoint
+```
+
+```
+  butt           round          square
+   │              │               │
+───┤            ───●            ───┤
+   │              │               │
+```
+
+## Miter Limit
+
+When `lineJoin` is `"miter"`, very sharp angles can create very long miter points. `miterLimit` caps this:
+
+```js
+shape.lineJoin = 'miter';
+shape.miterLimit = 10;  // Default, reasonable for most cases
+shape.miterLimit = 2;   // Shorter miters, more beveling
+```
+
+## Subclassing
+
+Shape is abstract. Subclasses implement `draw()`:
+
+```js
+import { Shape, Painter } from 'gcanvas';
+
+class CustomShape extends Shape {
+  constructor(options = {}) {
+    super(options);
+    // Custom initialization
+  }
+
+  draw() {
+    super.draw();  // Apply transforms
+
+    // Use this.color, this.stroke, this.lineWidth, etc.
+    if (this.color) {
+      Painter.colors.fill(this.color);
+      // Custom fill drawing
+    }
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+      // Custom stroke drawing
+    }
+  }
+}
+```
+
+## Concrete Shape Classes
+
+These classes extend Shape:
+
+| Class | Description |
+|-------|-------------|
+| `Circle` | Circle with radius |
+| `Rectangle` | Centered rectangle |
+| `Triangle` | Three-sided polygon |
+| `Star` | Star with n points |
+| `Polygon` | N-sided polygon |
+| `Line` | Line segment |
+| `Arc` | Curved arc |
+| `Heart` | Heart shape |
+| `Diamond` | Diamond/rhombus |
+| ... | And many more |
+
+## Example
+
+```js
+import { Rectangle, Painter } from 'gcanvas';
+
+const rect = new Rectangle({
+  x: 200,
+  y: 150,
+  width: 100,
+  height: 60,
+  color: '#4ecdc4',
+  stroke: '#2a9d8f',
+  lineWidth: 3,
+  lineJoin: 'round'
+});
+
+rect.draw();
+```
+
+## Complete Property Example
+
+```js
+const shape = new Circle(50, {
+  // Position (Euclidian)
+  x: 400,
+  y: 300,
+
+  // Constraints (Geometry2d)
+  minX: 50,
+  maxX: 750,
+
+  // Visibility (Renderable)
+  visible: true,
+  opacity: 0.9,
+  shadowColor: 'rgba(0,0,0,0.3)',
+  shadowBlur: 10,
+  shadowOffsetX: 5,
+  shadowOffsetY: 5,
+
+  // Transforms (Transformable)
+  rotation: 0,
+  scaleX: 1,
+  scaleY: 1,
+
+  // Styling (Shape)
+  color: '#ff6b6b',
+  stroke: '#c92a2a',
+  lineWidth: 2,
+  lineJoin: 'round',
+  lineCap: 'round'
+});
+```
+
+## Inheritance
+
+```
+Transformable
+    └── Shape  <── You are here
+            ├── Circle
+            ├── Rectangle
+            ├── Triangle
+            ├── Star
+            ├── Polygon
+            └── ... (40+ shapes)
+```
+
+## Related
+
+- [Transformable](./transformable.md) - Parent class
+- [Shape Hierarchy](../hierarchy.md) - Full inheritance diagram
+- [Shapes Module](../README.md) - All available shapes
+
+## See Also
+
+- [Rendering Pipeline](../../../concepts/rendering-pipeline.md)
+- [Hello World](../../../getting-started/hello-world.md)

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

@@ -0,0 +1,243 @@
+# Transformable
+
+> Rotation and scaling with transformed bounding boxes.
+
+**Module:** [shapes](../README.md) | **Extends:** [Renderable](./renderable.md) | **Source:** `src/shapes/transformable.js`
+
+## Overview
+
+Transformable adds canvas transformation support:
+- **Rotation** in degrees
+- **Scaling** (horizontal and vertical)
+- **Transformed bounds** calculation
+
+This is the final base layer before custom shape styling is introduced.
+
+## Constructor
+
+```js
+new Transformable(options)
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rotation` | `number` | `0` | Rotation in degrees (clockwise) |
+| `scaleX` | `number` | `1` | Horizontal scale factor |
+| `scaleY` | `number` | `1` | Vertical scale factor |
+
+Plus all options from [Renderable](./renderable.md).
+
+## Properties
+
+### Inherited
+
+From Euclidian: `x`, `y`, `width`, `height`, `debug`, `debugColor`
+
+From Geometry2d: `minX`, `maxX`, `minY`, `maxY`, `crisp`, `boundsDirty`
+
+From Renderable: `visible`, `opacity`, `active`, `zIndex`, `shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY`, `tick`
+
+### Own Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rotation` | `number` | Rotation angle in degrees |
+| `scaleX` | `number` | Horizontal scale (1 = normal) |
+| `scaleY` | `number` | Vertical scale (1 = normal) |
+
+## Methods
+
+### draw()
+
+Applies transforms before subclass drawing. Always call `super.draw()` in subclasses.
+
+```js
+class MyShape extends Transformable {
+  draw() {
+    super.draw();  // Apply transforms
+    // Custom drawing (in transformed space)
+  }
+}
+```
+
+### applyTransforms()
+
+Applies rotation and scale to the canvas context. Called by `draw()`.
+
+```js
+applyTransforms() {
+  Painter.rotate(this._rotation);
+  Painter.scale(this._scaleX, this._scaleY);
+}
+```
+
+Transform order: **rotate → scale**
+
+### calculateBounds()
+
+Returns the bounding box after applying rotation and scale.
+
+```js
+const bounds = shape.getBounds();
+// Returns axis-aligned bounding box of the rotated/scaled shape
+```
+
+## Rotation
+
+Rotation is specified in **degrees** (converted to radians internally):
+
+```js
+const shape = new Rectangle({
+  width: 100,
+  height: 50,
+  rotation: 45  // 45 degrees clockwise
+});
+
+// Update rotation
+shape.rotation = 90;   // 90 degrees
+shape.rotation = -30;  // 30 degrees counter-clockwise
+```
+
+## Scaling
+
+Scale factors multiply the shape's dimensions:
+
+```js
+const shape = new Circle(50, {
+  scaleX: 2,   // Twice as wide
+  scaleY: 0.5  // Half as tall
+});
+
+// Result: ellipse 200 wide, 50 tall
+```
+
+Common patterns:
+
+```js
+// Uniform scale
+shape.scaleX = 2;
+shape.scaleY = 2;  // 2x size in both dimensions
+
+// Flip horizontally
+shape.scaleX = -1;
+
+// Flip vertically
+shape.scaleY = -1;
+```
+
+## Transform Order
+
+Transforms are applied in this order:
+
+1. **Translate** to (x, y) — from Renderable
+2. **Rotate** by rotation angle
+3. **Scale** by scaleX, scaleY
+
+```js
+// Canvas transform stack:
+ctx.translate(x, y);      // Move to position
+ctx.rotate(rotation);     // Rotate around position
+ctx.scale(scaleX, scaleY); // Scale from position
+```
+
+## Transformed Bounds
+
+`getBounds()` returns the axis-aligned bounding box that contains the rotated/scaled shape:
+
+```js
+const rect = new Rectangle({
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 50,
+  rotation: 45
+});
+
+const bounds = rect.getBounds();
+// Returns AABB that contains the rotated rectangle
+// bounds.width and bounds.height will be larger than original
+```
+
+```
+Original:           Rotated 45°:
+┌──────────┐            ◇
+│          │           ╱ ╲
+│    ●     │          ╱   ╲
+│          │         ◇  ●  ◇
+└──────────┘          ╲   ╱
+                       ╲ ╱
+                        ◇
+                    ┌───────┐
+                    │ AABB  │
+                    └───────┘
+```
+
+## Example: Spinning Shape
+
+```js
+import { Rectangle, Painter } from 'gcanvas';
+
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+const rect = new Rectangle({
+  x: 400,
+  y: 300,
+  width: 100,
+  height: 60,
+  color: '#4ecdc4'
+});
+
+function animate() {
+  Painter.clear();
+
+  // Rotate 1 degree per frame
+  rect.rotation += 1;
+
+  rect.draw();
+  requestAnimationFrame(animate);
+}
+
+animate();
+```
+
+## Example: Pulsing Scale
+
+```js
+let time = 0;
+
+function animate() {
+  Painter.clear();
+  time += 0.05;
+
+  // Pulse between 0.8x and 1.2x
+  const scale = 1 + Math.sin(time) * 0.2;
+  shape.scaleX = scale;
+  shape.scaleY = scale;
+
+  shape.draw();
+  requestAnimationFrame(animate);
+}
+```
+
+## Inheritance
+
+```
+Renderable
+    └── Transformable  <── You are here
+            └── Shape
+                    └── Circle, Rectangle, Star, ...
+```
+
+## Related
+
+- [Renderable](./renderable.md) - Parent class
+- [Shape](./shape.md) - Adds fill/stroke styling
+- [Shape Hierarchy](../hierarchy.md) - Full inheritance diagram
+
+## See Also
+
+- [Shapes Module](../README.md)
+- [Rendering Pipeline](../../../concepts/rendering-pipeline.md)