feat: implement pixel-draw-renderer v1.0 (#237)

Author: fraxken

README.md

@@ -38,6 +38,7 @@ Click on one of the links to access the documentation of the package:
 | engine | [@jolly-pixel/engine](./packages/engine) | ECS framework on top of Three.js |
 | runtime | [@jolly-pixel/runtime](./packages/runtime) | Runtime for the engine / ECS |
 | voxel-renderer | [@jolly-pixel/voxel.renderer](./packages/voxel-renderer) | Voxel Engine and Renderer |
+| pixel-draw-renderer | [@jolly-pixel/pixel-draw.renderer](./packages/pixel-draw-renderer) | Pixel Art draw renderer |
 | fs-tree | [@jolly-pixel/fs-tree](./packages/fs-tree) | Robust, stylable tree view widget for HTML5 apps with drag'n'drop support |
 
 These packages are available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).

package.json

@@ -23,7 +23,8 @@
     "packages/fs-tree-backend",
     "packages/editors/voxel-map",
     "packages/editors/texture",
-    "packages/voxel-renderer"
+    "packages/voxel-renderer",
+    "packages/pixel-draw-renderer"
   ],
   "repository": {
     "type": "git",

packages/pixel-draw-renderer/README.md

@@ -0,0 +1,150 @@
+<h1 align="center">
+  pixel-draw.renderer
+</h1>
+
+<p align="center">
+  JollyPixel Pixel Art canvas renderer
+</p>
+
+## About
+
+`@jolly-pixel/pixel-draw.renderer` is a browser-based library for editing pixel-art textures. It provides zoom, pan, brush painting, right-click color picking, and an SVG cursor overlay, built around a SOLID-structured class architecture.
+
+## Features
+
+- **Zoom & pan** — smooth mouse-wheel zoom with configurable sensitivity and range; middle-click pan in any mode
+- **Brush painting** — configurable square brush with adjustable size, color, and opacity
+- **Color picking** — right-click eyedropper that reads the master canvas pixel
+- **Transparency support** — configurable checkerboard background renders beneath transparent pixels
+- **SVG brush highlight** — grid-aligned SVG overlay tracks the cursor in real time
+- **Dual-canvas architecture** — a master canvas (full resolution, off-screen) and a working canvas (viewport-cropped, on-screen) maintain pixel-perfect fidelity at any zoom level
+- **Mode switching** — `"paint"` and `"move"` modes control how mouse events are interpreted
+
+## Getting Started
+
+This package is available in the Node Package Repository and can be easily installed with [npm][npm] or [yarn][yarn].
+
+```bash
+$ npm i @jolly-pixel/pixel-draw.renderer
+# or
+$ yarn add @jolly-pixel/pixel-draw.renderer
+```
+
+## Usage Examples
+
+### Minimal setup
+
+```ts
+import { CanvasManager } from "@jolly-pixel/pixel-draw.renderer";
+
+const manager = new CanvasManager({
+  texture: { size: 64 },
+  zoom: {
+    range: [0.5, 40],
+    sensitivity: 0.002
+  },
+});
+
+const container = document.getElementById("editor-container")!;
+manager.reparentCanvasTo(container);
+manager.resize();
+manager.centerTexture();
+```
+
+### Drawing pixels programmatically
+
+```ts
+import { CanvasManager } from "@jolly-pixel/pixel-draw.renderer";
+
+const manager = new CanvasManager({
+  texture: { size: 32 }
+});
+manager.reparentCanvasTo(document.body);
+
+// Draw a red pixel at texture position (10, 10)
+manager.textureBuffer.drawPixels(
+  [{ x: 10, y: 10 }],
+  { r: 255, g: 0, b: 0, a: 255 }
+);
+manager.render();
+```
+
+### Loading an existing texture
+
+```ts
+const img = new Image();
+img.src = "/assets/sprite.png";
+await img.decode();
+
+manager.setTexture(img);
+```
+
+### Configuring the brush
+
+```ts
+manager.brush.setColor("#FF6600");
+manager.brush.setOpacity(0.8);
+manager.brush.setSize(3);
+```
+
+### Switching modes
+
+```ts
+manager.setMode("move");  // left-click pans
+manager.setMode("paint"); // left-click draws
+```
+
+## Running the Examples
+
+```bash
+npm run dev -w @jolly-pixel/pixel-draw.renderer
+```
+
+Open `http://localhost:5173` to see the interactive demo.
+
+## API
+
+| Class | Description |
+|---|---|
+| [`CanvasManager`](./docs/CanvasManager.md) | Top-level coordinator — the primary public API |
+| [`Viewport`](./docs/Viewport.md) | Camera position, zoom level, and coordinate transforms |
+| [`BrushManager`](./docs/BrushManager.md) | Brush size, color, opacity, and affected-pixel computation |
+| `TextureBuffer` | Dual-canvas pixel storage and image-data access |
+| `CanvasRenderer` | Visible canvas drawing and checkerboard background |
+| `InputController` | Mouse event routing to drawing and pan actions |
+| `SvgManager` | SVG brush-highlight overlay |
+
+## Troubleshooting
+
+**Canvas is blank after mounting**
+Call `manager.resize()` after `reparentCanvasTo()` to let the renderer read the parent element's dimensions, then call `manager.centerTexture()`.
+
+**Pixels appear at the wrong position**
+Pass `{ bounds: canvas.getBoundingClientRect() }` when calling `viewport.getMouseTexturePosition()`. Stale bounding rects cause offset errors.
+
+**Master canvas is slow to initialize**
+`TextureBuffer` pre-allocates a canvas at `maxSize` (default `2048`). In test environments or when large textures are unnecessary, set `texture.maxSize` to a smaller value such as `64`.
+
+## Contributors Guide
+
+If you are a developer **looking to contribute** to the project, you must first read the [CONTRIBUTING][contributing] guide.
+
+Once you have finished your development, check that the tests (and linter) are still good by running the following script:
+
+```bash
+$ npm run test
+$ npm run lint
+```
+
+> [!CAUTION]
+> In case you introduce a new feature or fix a bug, make sure to include tests for it as well.
+
+## License
+
+MIT
+
+<!-- Reference-style links for DRYness -->
+
+[npm]: https://docs.npmjs.com/getting-started/what-is-npm
+[yarn]: https://yarnpkg.com
+[contributing]: ../../CONTRIBUTING.md

packages/pixel-draw-renderer/docs/BrushManager.md

@@ -0,0 +1,108 @@
+# BrushManager
+
+`BrushManager` manages the current brush color, opacity, size, and highlight colors, and computes the list of texture-space pixels a brush stroke covers.
+
+## Import
+
+```ts
+import { BrushManager } from "@jolly-pixel/pixel-draw.renderer";
+```
+
+## Constructor
+
+```ts
+new BrushManager(options: BrushManagerOptions)
+```
+
+### `BrushManagerOptions`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `color` | `string` | `"#000000"` | Initial brush color (CSS hex) |
+| `size` | `number` | `1` | Initial brush size in pixels |
+| `maxSize` | `number` | `32` | Upper bound for brush size |
+| `highlightColorInline` | `string` | `"#FFFFFF"` | SVG overlay inner stroke color |
+| `highlightColorOutline` | `string` | `"#000000"` | SVG overlay outer stroke color |
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `color` | `string` | Current brush color as a CSS hex string |
+| `opacity` | `number` | Current opacity in the range `[0, 1]` |
+| `size` | `number` | Current brush size in pixels |
+| `maxSize` | `number` | Maximum allowed brush size |
+| `r` / `g` / `b` | `number` | Current color channels in the range `[0, 255]` |
+
+## Methods
+
+### `setColor`
+
+```ts
+setColor(color: string): void
+```
+
+Sets the brush color from a CSS hex string (e.g. `"#FF0000"`). Updates the internal `r`, `g`, `b` components accordingly.
+
+---
+
+### `setOpacity`
+
+```ts
+setOpacity(opacity: number): void
+```
+
+Sets the brush opacity. Values are clamped to `[0, 1]`.
+
+---
+
+### `setSize`
+
+```ts
+setSize(size: number): void
+```
+
+Sets the brush size in pixels. Values are clamped to `[1, maxSize]`.
+
+---
+
+### `getHighlightColorInline` / `setHighlightColorInline`
+
+```ts
+getHighlightColorInline(): string
+setHighlightColorInline(color: string): void
+```
+
+Gets or sets the inner stroke color of the SVG brush cursor overlay.
+
+---
+
+### `getHighlightColorOutline` / `setHighlightColorOutline`
+
+```ts
+getHighlightColorOutline(): string
+setHighlightColorOutline(color: string): void
+```
+
+Gets or sets the outer stroke color of the SVG brush cursor overlay.
+
+---
+
+### `getAffectedPixels`
+
+```ts
+getAffectedPixels(cx: number, cy: number): Vec2[]
+```
+
+Returns an array of texture-space `{ x, y }` coordinates for every pixel within the current brush square centered at `(cx, cy)`.
+
+- For **odd** brush sizes the center pixel is exactly `(cx, cy)`.
+- For **even** brush sizes the brush is offset by `−0.5` to remain grid-aligned.
+
+**Example**
+
+```ts
+// size = 3 → 9 pixels around (10, 10)
+const pixels = brush.getAffectedPixels(10, 10);
+textureBuffer.drawPixels(pixels, { r: 255, g: 0, b: 0, a: 255 });
+```