@buncanvas/core 0.1.2 → 0.1.4

package/README.md

@@ -1,23 +1,149 @@
-# buncanvas
+# BunCanvas 🎨
 
-To install dependencies:
+A fast, lightweight 2D graphics canvas binding for the **Bun** JavaScript runtime, powered by native Google Skia rendering. 
+
+BunCanvas brings hardware-accelerated 2D drawing capabilities directly to desktop applications—without needing a browser, DOM environment, or heavy webview dependencies.
+
+---
+
+## ⚙️ Installation
+
+Add `BunCanvas` to your project via Bun:
 
 ```bash
-bun install
+bun add @buncanvas/core
+Note: BunCanvas automatically resolves and installs the matching native binary (.so, .dll, or .dylib) for your platform via optionalDependencies.
 ```
 
-To run:
+## 🚀 Quick Start
+Here is a minimal example that opens a window and renders a simple rectangle.
 
-```bash
-bun run index.js
+```JavaScript
+import { Window, Canvas } from "@buncanvas/core";
+
+// 1. Create a native window
+const win = new Window(800, 600, {
+  title: "BunCanvas Quickstart",
+});
+
+// 2. Create a 2D drawing canvas matching the window size
+const canvas = new Canvas(800, 600);
+const ctx = canvas.getContext("2d");
+
+// 3. Draw onto the canvas context
+ctx.fillStyle = "#3498db";
+ctx.fillRect(50, 50, 200, 150);
+
+// 4. Attach the canvas to the window frame
+win.append(canvas);
 ```
 
-To type check:
+## 🎨 Code Examples
+1. Animated Bouncing Ball (Render Loop)
+Use requestAnimationFrame to manage a smooth render loop for real-time graphics and physics.
 
-```bash
-bun check
+```JavaScript
+import { Window, Canvas } from "@buncanvas/core";
+
+const WIDTH = 800;
+const HEIGHT = 600;
+
+const win = new Window(WIDTH, HEIGHT, { title: "Animation Example" });
+const canvas = new Canvas(WIDTH, HEIGHT);
+const ctx = canvas.getContext("2d");
+
+win.append(canvas);
+
+// Ball state
+let x = 100;
+let y = 100;
+let vx = 4;
+let vy = 3;
+const radius = 25;
+
+function render(timestamp) {
+  // Clear screen
+  ctx.fillStyle = "#1e1e2e";
+  ctx.fillRect(0, 0, WIDTH, HEIGHT);
+
+  // Update position
+  x += vx;
+  y += vy;
+
+  // Bounce off edges
+  if (x - radius < 0 || x + radius > WIDTH) vx *= -1;
+  if (y - radius < 0 || y + radius > HEIGHT) vy *= -1;
+
+  // Draw circle
+  ctx.beginPath();
+  ctx.arc(x, y, radius, 0, Math.PI * 2);
+  ctx.fillStyle = "#ff5555";
+  ctx.fill();
+  ctx.lineWidth = 3;
+  ctx.strokeStyle = "#ffffff";
+  ctx.stroke();
+
+  // Schedule next frame
+  requestAnimationFrame(render);
+}
+
+// Start loop
+requestAnimationFrame(render);
 ```
 
-Run `bun fmt` to format the code.
+## 2. Gradient & Path Drawing
+BunCanvas supports complex paths, transformations, and gradient shaders.
+
+```JavaScript
+import { Window, Canvas } from "@buncanvas/core";
+
+const win = new Window(600, 600, { title: "Gradient & Paths" });
+const canvas = new Canvas(600, 600);
+const ctx = canvas.getContext("2d");
+
+// Create linear gradient
+const gradient = ctx.createLinearGradient(0, 0, 600, 600);
+gradient.addColorStop(0, "#8e44ad");
+gradient.addColorStop(1, "#f39c12");
+
+ctx.fillStyle = gradient;
+ctx.fillRect(0, 0, 600, 600);
+
+// Draw a star shape
+ctx.save();
+ctx.translate(300, 300);
+ctx.fillStyle = "#ffffff";
+ctx.beginPath();
+
+for (let i = 0; i < 5; i++) {
+  ctx.lineTo(Math.cos(((18 + i * 72) * Math.PI) / 180) * 120, -Math.sin(((18 + i * 72) * Math.PI) / 180) * 120);
+  ctx.lineTo(Math.cos(((54 + i * 72) * Math.PI) / 180) * 50, -Math.sin(((54 + i * 72) * Math.PI) / 180) * 50);
+}
+
+ctx.closePath();
+ctx.fill();
+ctx.restore();
+
+win.append(canvas);
+```
+
+## 🛠️ API Reference Summary
+`new Window(width, height, options)` Creates a desktop window frame.
+
+`width`: number - Initial window width in pixels.
+
+`height`: number - Initial window height in pixels.
+
+`options`: object (Optional)
+
+`title`: string - Title bar text.
+
+`window.append(canvas)`: Binds a Canvas instance to render inside the window viewport.
+
+`new Canvas(width, height)` Creates an off-screen 2D drawing surface.
+
+`canvas.getContext('2d')`: Returns the 2D rendering context supporting standard canvas operations (fillRect, arc, save, restore, etc.).
+
+`requestAnimationFrame(callback)` Schedules a frame update for continuous rendering.
 
-This project was created using `bun init` in bun v1.4.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+Refer to <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D">CanvasRenderingContext2D</a> for other drawing methods.