@guinetik/gcanvas 1.0.2 → 1.0.4

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

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

@@ -1,262 +0,0 @@
-# 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 '@guinetik/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 '@guinetik/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

@@ -1,243 +0,0 @@
-# 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 '@guinetik/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)