@guinetik/gcanvas 1.0.0

package/.github/workflows/release.yaml

@@ -0,0 +1,70 @@
+name: Release on Master Merge
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  release:
+    name: Build and Release GCanvas
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+      - name: Install dependencies
+        run: npm ci
+      - name: Build library
+        run: npm run build
+      - name: Read version from package.json
+        id: pkg
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "VERSION=v$VERSION" >> $GITHUB_OUTPUT
+      - name: Show version used
+        run: |
+          echo "Publishing version: ${{ steps.pkg.outputs.VERSION }}"
+      - name: Generate Changelog
+        id: changelog
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0)
+          echo "Last tag was: $LAST_TAG"
+          LOG=$(git log $LAST_TAG..HEAD --pretty=format:"- %s")
+          echo "LOG<<EOF" >> $GITHUB_OUTPUT
+          echo "$LOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+      - name: Create GitHub Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.pkg.outputs.VERSION }}
+          body: ${{ steps.changelog.outputs.LOG }}
+          release_name: GCanvas ${{ steps.pkg.outputs.VERSION }}
+          draft: false
+          prerelease: false
+      - name: Upload UMD build
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: dist/gcanvas.umd.min.js
+          asset_name: gcanvas.umd.min.js
+          asset_content_type: application/javascript
+      - name: Upload ESM build
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: dist/gcanvas.es.min.js
+          asset_name: gcanvas.es.min.js
+          asset_content_type: application/javascript

package/.jshintrc

@@ -0,0 +1,4 @@
+{
+  "esversion": 11,
+  "node": false
+} 

package/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#2f7c47",
+        "activityBar.background": "#2f7c47",
+        "activityBar.foreground": "#e7e7e7",
+        "activityBar.inactiveForeground": "#e7e7e799",
+        "activityBarBadge.background": "#422c74",
+        "activityBarBadge.foreground": "#e7e7e7",
+        "commandCenter.border": "#e7e7e799",
+        "sash.hoverBorder": "#2f7c47",
+        "statusBar.background": "#215732",
+        "statusBar.foreground": "#e7e7e7",
+        "statusBarItem.hoverBackground": "#2f7c47",
+        "statusBarItem.remoteBackground": "#215732",
+        "statusBarItem.remoteForeground": "#e7e7e7",
+        "titleBar.activeBackground": "#215732",
+        "titleBar.activeForeground": "#e7e7e7",
+        "titleBar.inactiveBackground": "#21573299",
+        "titleBar.inactiveForeground": "#e7e7e799"
+    },
+    "peacock.color": "#215732"
+}

package/CLAUDE.md

@@ -0,0 +1,310 @@
+# AGENTS.md - GCanvas Development Guidelines
+
+## Project Overview
+
+GCanvas is a zero-dependency HTML5 Canvas library for 2D graphics, games, and generative art. It provides a declarative API built on shapes, game objects, and a rendering pipeline.
+
+**Repository:** https://github.com/guinetik/gcanvas
+
+## Project Structure
+
+```
+gcanvas/
+├── src/                    # Library source code
+│   ├── index.js           # Main exports
+│   ├── shapes/            # Shape primitives (Circle, Rect, Text, etc.)
+│   ├── game/              # Game loop, pipeline, GameObjects
+│   │   ├── objects/       # GameObject wrappers (Text, Scene, ImageGo)
+│   │   ├── ui/            # UI components (Button, FPS counter)
+│   │   └── pipeline.js    # Rendering pipeline
+│   ├── painter/           # Low-level canvas drawing utilities
+│   ├── motion/            # Animation & tweening (Tween, easing functions)
+│   ├── math/              # Math utilities (Complex, noise, fractals)
+│   ├── mixins/            # Composable behaviors (anchor, draggable)
+│   ├── util/              # Utilities (layout, position, Camera3D)
+│   ├── io/                # Input handling (keyboard, mouse, touch)
+│   ├── collision/         # Collision detection
+│   ├── state/             # State management
+│   └── sound/             # Audio utilities
+├── demos/                 # Demo applications
+│   ├── js/               # Demo JavaScript files
+│   ├── *.html            # Demo HTML entry points
+│   └── demos.css         # Shared demo styles
+├── tests/                 # Vitest test files
+└── dist/                  # Built library (UMD & ES modules)
+```
+
+## Coding Guidelines
+
+### 1. No Magic Numbers
+
+**Always use a CONFIG object** at the top of files for configurable values.
+
+```javascript
+// BAD - magic numbers scattered in code
+this.camera = new Camera3D({ perspective: 800 });
+for (let i = 0; i < 300; i++) { ... }
+const radius = 80;
+
+// GOOD - centralized configuration
+const CONFIG = {
+  perspective: 800,
+  numPoints: 300,
+  helixRadius: 80,
+
+  // Group related values
+  physics: {
+    gravity: 0.0001,
+    damping: 0.99,
+  },
+
+  // Document units where helpful
+  timeScale: 1.0,          // seconds
+  gridSpacing: 30,         // pixels
+};
+```
+
+### 2. Prefer Shapes and GameObjects Over Direct Canvas
+
+The library provides abstractions - use them instead of raw canvas operations.
+
+```javascript
+// BAD - direct canvas drawing
+ctx.beginPath();
+ctx.arc(x, y, 50, 0, Math.PI * 2);
+ctx.fillStyle = "red";
+ctx.fill();
+
+// GOOD - use Shape classes
+import { Circle } from "../../src/index.js";
+const circle = new Circle(x, y, 50, { fill: "red" });
+circle.render(ctx);
+
+// GOOD - use GameObjects for managed entities
+import { Game, Scene, Text } from "../../src/index.js";
+const label = new Text(this, "Hello", { color: "#fff", font: "16px monospace" });
+this.pipeline.add(label);
+```
+
+### 3. Use Painter.useCtx for Low-Level Operations
+
+When you must access the canvas context directly, wrap it with `Painter.useCtx`:
+
+```javascript
+import { Painter } from "../../src/index.js";
+
+// BAD - direct ctx manipulation
+ctx.save();
+ctx.strokeStyle = "rgba(255,255,255,0.5)";
+ctx.lineWidth = 2;
+ctx.moveTo(x1, y1);
+ctx.lineTo(x2, y2);
+ctx.stroke();
+ctx.restore();
+
+// GOOD - Painter.useCtx handles save/restore automatically
+Painter.useCtx((ctx) => {
+  ctx.strokeStyle = "rgba(255,255,255,0.5)";
+  ctx.lineWidth = 2;
+  ctx.moveTo(x1, y1);
+  ctx.lineTo(x2, y2);
+  ctx.stroke();
+});
+```
+
+### 4. Use Layout Utilities for Positioning
+
+Don't manually calculate positions for multiple items:
+
+```javascript
+import { verticalLayout, applyLayout, applyAnchor, Position, Scene, Text } from "../../src/index.js";
+
+// BAD - manual offset calculations
+this.title = new Text(this, "Title", { y: 20 });
+this.subtitle = new Text(this, "Subtitle", { y: 45 });
+this.info = new Text(this, "Info", { y: 70 });
+
+// GOOD - use layout utilities
+const panel = new Scene(this, { x: 0, y: 0 });
+applyAnchor(panel, { anchor: Position.TOP_CENTER, anchorOffsetY: 100 });
+
+const items = [
+  new Text(this, "Title", { font: "bold 16px monospace" }),
+  new Text(this, "Subtitle", { font: "14px monospace" }),
+  new Text(this, "Info", { font: "12px monospace" }),
+];
+
+const layout = verticalLayout(items, { spacing: 20, align: "center" });
+applyLayout(items, layout.positions);
+items.forEach(item => panel.add(item));
+```
+
+### 5. Extend Game Class for Demos
+
+All demos should extend the `Game` class:
+
+```javascript
+import { Game, Painter } from "../../src/index.js";
+
+const CONFIG = {
+  // Configuration values
+};
+
+class MyDemo extends Game {
+  constructor(canvas) {
+    super(canvas);
+    this.backgroundColor = "#000";
+    this.enableFluidSize();  // Responsive canvas
+  }
+
+  init() {
+    super.init();
+    // Initialize shapes, game objects, state
+    this.pipeline.add(myGameObject);
+  }
+
+  update(dt) {
+    super.update(dt);
+    // Update logic (dt is delta time in seconds)
+  }
+
+  render() {
+    super.render();  // Clears canvas, renders pipeline
+    // Additional rendering if needed
+  }
+}
+
+window.addEventListener("load", () => {
+  const canvas = document.getElementById("game");
+  const demo = new MyDemo(canvas);
+  demo.start();
+});
+```
+
+## Key APIs Reference
+
+### Shapes
+- `Circle`, `Rect`, `Square`, `Triangle`, `Hexagon`, `Star`
+- `Line`, `Arc`, `BezierShape`, `SVGShape`
+- `Text` (shape), `ImageShape`, `Pattern`
+- 3D shapes: `Cube`, `Sphere`, `Cylinder`, `Cone`, `Prism`
+
+### GameObjects (in `src/game/objects/`)
+- `Text` - Managed text with automatic updates
+- `Scene` - Container for grouping objects
+- `ImageGo` - Managed image display
+- `LayoutScene` - Scene with layout helpers
+
+### Motion & Animation
+- `Tween` - Animate properties over time
+- `TweenEnetik` - Advanced tweening
+- Motion behaviors: `Orbit`, `Oscillate`, `Bounce`, `Spring`, etc.
+
+### Utilities
+- `Camera3D` - Pseudo-3D projection with mouse controls
+- `verticalLayout`, `horizontalLayout`, `gridLayout` - Layout helpers
+- `applyAnchor` - Position anchoring mixin
+- `Position` - Position constants (TOP_CENTER, BOTTOM_LEFT, etc.)
+
+### Math
+- `Complex` - Complex number operations
+- `Noise` - Perlin/simplex noise
+- `Random` - Seeded random utilities
+- Fractal generators
+
+### Input
+- `Keys` - Keyboard input
+- `Input` - Mouse/pointer input
+- `Touch` - Touch input handling
+
+## Demo File Structure
+
+```
+demos/
+├── mydemo.html           # HTML entry point
+└── js/
+    └── mydemo.js         # Demo implementation
+```
+
+### HTML Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Demo Name</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+<body>
+  <div id="info">
+    <strong>Demo Title</strong> — Brief description.<br/>
+    <span style="color:#CCC">
+      <li>Feature 1</li>
+      <li>Feature 2</li>
+      <li>Controls info</li>
+    </span>
+  </div>
+  <canvas id="game"></canvas>
+  <script type="module" src="./js/mydemo.js"></script>
+</body>
+</html>
+```
+
+### Adding to Navigation
+
+Update `demos/index.html` to add your demo to the appropriate section:
+
+```html
+<h2>Section Name</h2>
+<a href="mydemo.html" target="demo-frame">My Demo</a>
+```
+
+## Development Commands
+
+```bash
+npm run dev          # Start Vite dev server
+npm run build        # Build library to dist/
+npm run test         # Run tests
+npm run test:watch   # Run tests in watch mode
+npm run docs         # Generate JSDoc documentation
+```
+
+## Testing
+
+Tests use Vitest and are located in `tests/`. Run with:
+
+```bash
+npm test
+```
+
+## Common Patterns
+
+### Responsive Canvas
+```javascript
+this.enableFluidSize();  // Auto-resize to window
+```
+
+### Mouse/Touch Interaction
+```javascript
+this.canvas.addEventListener("click", () => this.handleClick());
+this.canvas.addEventListener("touchstart", (e) => this.handleTouch(e));
+```
+
+### Color Utilities
+```javascript
+import { Painter } from "../../src/index.js";
+const rgb = Painter.colors.hslToRgb(hue, saturation, lightness);
+const hex = Painter.colors.rgbToHex(r, g, b);
+```
+
+### Animation Loop Access
+```javascript
+update(dt) {
+  super.update(dt);
+  this.time += dt;  // dt is in seconds
+  // Animation logic
+}
+```

package/demos/CNAME

@@ -0,0 +1 @@
+gcanvas.guinetik.com

package/demos/animations.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Tween</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+  <div id="info">
+    <strong>Motion Demo</strong> - Showcases reusable animations. Each animation is implemented through a tween system that handles interpolation between values over time. The demo uses a tile-based layout to organize the animations in a grid, with each animation contained in its own box. Under the hood, the system manages animation timing through a central update loop, applying mathematical transformations to the shapes' positions based on normalized time values (0-1) that loop continuously.
+  </div>
+  <canvas id="game"></canvas>
+  <script type="module">
+    import { MyGame } from './js/animations.js';
+
+    window.addEventListener("load", () => {
+      const canvas = document.getElementById("game");
+      const game = new MyGame(canvas);
+  //    game.setFPS(1);
+      //  game.enableLogging(true);
+      game.start();
+//      setTimeout(game.stop.bind(game), 2000);
+    });
+  </script>
+</body>
+
+</html>

package/demos/basic.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Basic Game Template</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+  <div id="info">
+    <strong>Basic Template</strong> — A minimal demo to kickstart new games. <br>
+    A <strong>Game</strong> manages the canvas, lifecycle, input, and rendering loop. <br>
+    A <strong>GameObject</strong> is any interactive or drawable entity (e.g. shape, text, button, particle). <br>
+    A <strong>Scene</strong> is a container that groups GameObjects and controls update & render order. <br>
+    The <strong>Pipeline</strong> is the main ordered list of GameObjects (or Scenes) that the game runs every frame.
+    <br>
+    This template sets up one game scene and one UI scene, with a "Hello World" box in the center and an FPS counter in
+    the corner.
+  </div>
+  <canvas id="game"></canvas>
+
+  <script type="module">
+    import { DemoGame } from "./js/basic.js";
+    window.addEventListener("load", () => {
+      const canvas = document.getElementById("game");
+      const game = new DemoGame(canvas);
+      //game.enableLogging();
+      game.enablePauseOnBlur(true);
+      game.setFPS(60);
+      game.start();
+    });
+  </script>
+</body>
+
+</html>

package/demos/baskara.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Root Dance - Bhaskara Formula</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+  <div id="info">
+    <strong>Bhaskara Dance</strong> - Visualizing the quadratic formula (Bhaskara).
+    Particles represent the roots of ax² + bx + c = 0. Watch them dance
+    as coefficients animate, merge when the discriminant hits zero, and spiral
+    into the complex plane when roots become imaginary.
+  </div>
+  <canvas id="game"></canvas>
+  <script type="module">
+    import { MyGame } from './js/baskara.js';
+
+    window.addEventListener("load", () => {
+      const canvas = document.getElementById("game");
+      const game = MyGame(canvas);
+      game.start();
+    });
+  </script>
+</body>
+
+</html>

package/demos/bezier.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Basic Game Template</title>
+    <link rel="stylesheet" href="demos.css" />
+    <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+    <div id="info">
+        <strong>Bezier Curve Editor</strong> — Create and modify Bezier curves with interactive control points. <br>
+        The demo shows the separation between <strong>Shapes</strong> (visual definitions) and
+        <strong>GameObjects</strong> (interactive entities). <br>
+        <strong>BezierShape</strong> defines curve paths using commands like "M" (move), "L" (line), "Q" (quadratic),
+        and "C" (cubic). <br>
+        <strong>Control Points</strong> are wrapped with ShapeGOFactory to make them interactive, while guide lines show
+        relationships between points. <br>
+        Switch between <strong>Add Points</strong> mode to place new control points and <strong>Edit Points</strong>
+        mode to drag and adjust the curve shape.
+    </div>
+    <canvas id="game"></canvas>
+    <script type="module" src="./js/bezier.js"></script>
+    <script type="module">
+        window.addEventListener("load", () => {
+            const canvas = document.getElementById("game");
+            const game = new BezierDemoGame(canvas);
+            game.start();
+        });
+    </script>
+</body>
+
+</html>

package/demos/beziersignature.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Bezier Signature</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+  <div id="info">
+    <strong>Bezier Signature</strong> — A <code>BezierShape</code> receives an array of path commands and draws them as a
+    bezier curve. This can be done all frames at once or they can be iterated over time, like a signature animation.
+  </div>
+  <canvas id="game"></canvas>
+  <script type="module">
+    import { MyGame } from './js/beziersignature.js';
+
+    window.addEventListener("load", () => {
+      const canvas = document.getElementById("game");
+      const game = new MyGame(canvas);
+      game.start();
+    });
+  </script>
+</body>
+
+</html>

package/demos/blackhole.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Black Hole - Cinematic Visualization</title>
+  <link rel="stylesheet" href="demos.css" />
+  <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+  <div id="info">
+    <strong>Black Hole</strong> — Cinematic accretion disk visualization.<br/>
+    <span style="color:#CCC">
+      <li><code>Gravitational Lensing</code> — Light bends around the hole.</li>
+      <li><code>Accretion Disk</code> — 2500 particles with heat gradient.</li>
+      <li><code>Doppler Beaming</code> — Approaching side brighter.</li>
+      <li><code>Hawking Radiation</code> — Rare cyan quantum escapes.</li>
+      <li><code>Drag</code> — Orbit the camera around.</li>
+      <li><code>Auto-rotate</code> — Slow orbit when idle.</li>
+    </span>
+  </div>
+  <canvas id="game"></canvas>
+  <script type="module" src="./js/blackhole/index.js"></script>
+</body>
+
+</html>

package/demos/blob.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Blob Feeder</title>
+    <link rel="stylesheet" href="demos.css" />
+    <script src="./js/info-toggle.js"></script>
+</head>
+
+<body>
+    <div id="info">
+        <strong>Blob Feeder</strong> — A Tamagotchi-style micro-game where you keep your blob alive by collecting food!<br>
+        <span style="color:#CCC">
+            <li>Guide the blob with your mouse/touch to collect shapes</li>
+            <li>Each level = one musical scale (do-re-mi), longer scales as you progress</li>
+            <li>Pick up items quickly for speed bonuses (up to 2x points)</li>
+            <li>Don't let your blob go hungry - it will shrink and lose points!</li>
+            <li>Watch the blob's face - it shows mood based on hunger and energy</li>
+        </span>
+    </div>
+    <canvas id="game"></canvas>
+    <script type="module">
+        import { BezierBlobGame } from './js/blob.js';
+
+        window.addEventListener("load", () => {
+            const canvas = document.getElementById("game");
+            const game = new BezierBlobGame(canvas);
+            game.start();
+        });
+    </script>
+</body>
+
+</html>