git-hash-art 0.1.0 → 0.2.0

package/.kiro/steering/product.md

@@ -0,0 +1,16 @@
+# Product: git-hash-art
+
+A cross-platform library that generates deterministic abstract art from git commit hashes. Given a hex hash string, it produces a unique image using layered geometric shapes, sacred geometry patterns, and harmonious color schemes. Works in both Node.js and browser environments.
+
+Key capabilities:
+- Deterministic output: same hash always produces the same image
+- Configurable canvas size, grid density, layers, shape sizes, and opacity
+- Built-in presets for social media (Instagram, Twitter, LinkedIn), device wallpapers, and print sizes
+- CLI for generating art from the current commit or a specific hash
+- Cross-platform: Node.js (via `@napi-rs/canvas`) and browsers (native Canvas 2D API)
+
+## Public API
+
+- Node entry (`git-hash-art`): `generateImageFromHash` (returns PNG Buffer), `saveImageToFile`, `renderHashArt`
+- Browser entry (`git-hash-art/browser`): `renderToCanvas`, `generateImageBlob`, `generateDataURL`, `renderHashArt`
+- Both re-export `PRESETS`, `DEFAULT_CONFIG`, and the `GenerationConfig` type

package/.kiro/steering/structure.md

@@ -0,0 +1,40 @@
+# Project Structure
+
+```
+src/
+  index.ts              # Node.js entry: generateImageFromHash, saveImageToFile, re-exports renderHashArt
+  browser.ts            # Browser entry: renderToCanvas, generateImageBlob, generateDataURL, re-exports renderHashArt
+  types.ts              # Shared GenerationConfig interface and DEFAULT_CONFIG
+  __tests__/            # Vitest test files (*.test.ts)
+  lib/
+    render.ts           # Pure rendering logic (environment-agnostic) — renderHashArt()
+    utils.ts            # Hash-to-seed conversion, deterministic RNG, PatternCombiner
+    constants.ts        # PRESETS, default shape config, proportions, pattern presets
+    canvas/
+      colors.ts         # Color scheme generation (generateColorScheme, SacredColorScheme class)
+      draw.ts           # Shape drawing and enhancement (drawShape, enhanceShapeGeneration)
+      shapes/
+        index.ts        # Aggregates and re-exports all shape draw functions
+        basic.ts        # Circle, square, triangle, hexagon, star
+        complex.ts      # Platonic solids, fibonacci, golden ratio shapes
+        sacred.ts       # Flower of life, tree of life, Metatron's cube, Sri Yantra
+        utils.ts        # Geometry helpers (transforms, degree conversion)
+bin/
+  generateExamples.js   # Script to generate example images from PRESETS
+examples/               # Generated example PNGs (gitignored)
+```
+
+## Architecture
+
+- `src/lib/render.ts` contains the pure rendering core (`renderHashArt`) that only uses the standard `CanvasRenderingContext2D` API — no Node or browser dependencies
+- `src/index.ts` is the Node entry point — wraps `renderHashArt` with `@napi-rs/canvas` for PNG buffer output and `fs` for file saving
+- `src/browser.ts` is the browser entry point — wraps `renderHashArt` with `HTMLCanvasElement`/`OffscreenCanvas` helpers
+- `@napi-rs/canvas` is an optional peer dependency, only required for Node.js usage
+
+## Conventions
+
+- Shape draw functions follow the `DrawFunction` signature: `(ctx: CanvasRenderingContext2D, size: number, config?: any) => void`
+- Shapes are grouped by category (basic, complex, sacred) and merged via the barrel `shapes/index.ts`
+- All randomness is derived deterministically from the git hash via `getRandomFromHash` — never use `Math.random()`
+- Tests live in `src/__tests__/` and use Vitest (`describe`/`it`/`expect`)
+- The `examples/` directory is gitignored; regenerate with `yarn build:examples`

package/.kiro/steering/tech.md

@@ -0,0 +1,24 @@
+# Tech Stack
+
+- Language: TypeScript (strict mode, ES2020 target)
+- Runtime: Node.js and browsers
+- Canvas (Node): `@napi-rs/canvas` (optional peer dependency)
+- Canvas (Browser): native Canvas 2D API / OffscreenCanvas
+- Color generation: `color-scheme` (declared in `global.d.ts` since it lacks types)
+- Bundler: Parcel (outputs CJS `dist/main.js`, ESM `dist/module.js`, browser `dist/browser.js`, types `dist/types.d.ts`)
+- Test framework: Vitest
+- Formatter: Prettier
+- Release: release-it
+- Package manager: Yarn
+
+## Common Commands
+
+| Command | Purpose |
+|---|---|
+| `yarn build` | Production build (clears `.parcel-cache` first via `prebuild`) |
+| `yarn watch` | Dev build with file watching |
+| `npx vitest --run` | Run tests once |
+| `yarn format` | Format source files with Prettier |
+| `yarn format:check` | Check formatting without writing |
+| `yarn build:examples` | Generate example images via `bin/generateExamples.js` |
+| `yarn test:publish` | Dry-run npm publish |

package/CHANGELOG.md

@@ -4,9 +4,20 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [0.2.0](https://github.com/gfargo/git-hash-art/compare/0.1.0...0.2.0)
+
+- feat: add cross-platform browser support [`#8`](https://github.com/gfargo/git-hash-art/pull/8)
+- feat: add visual effects for richer art generation [`#6`](https://github.com/gfargo/git-hash-art/pull/6)
+- fix: improve art generation quality [`#5`](https://github.com/gfargo/git-hash-art/pull/5)
+- docs: update README to reflect current algorithm and features [`15879c6`](https://github.com/gfargo/git-hash-art/commit/15879c62480a2d418c4ef8dcb479d912a7160345)
+- fix(shapes): handle missing shape type default [`860bfd3`](https://github.com/gfargo/git-hash-art/commit/860bfd36caab97d6ed44dd441ea1a995863b6068)
+
 #### [0.1.0](https://github.com/gfargo/git-hash-art/compare/0.0.4...0.1.0)
 
+> 18 March 2026
+
 - update shape drawing for platonic solids [`c26decd`](https://github.com/gfargo/git-hash-art/commit/c26decd8df9d7d47615efce37da8fdf554cdfcc4)
+- chore: release v0.1.0 [`f83dce5`](https://github.com/gfargo/git-hash-art/commit/f83dce5de7a03da5432b1bb538643b7fcb9cd29f)
 
 #### [0.0.4](https://github.com/gfargo/git-hash-art/compare/0.0.3...0.0.4)
 

package/README.md

@@ -2,15 +2,22 @@
 
 Generate beautiful, deterministic abstract art from git commit hashes. Perfect for creating unique visual representations of your project's commits, generating placeholder images, or creating artistic wallpapers.
 
+Works in both Node.js and browser environments.
+
 ## Features
 
-- Generate consistent, deterministic abstract art from any git hash
-- Configurable canvas sizes and output formats
-- Built-in presets for common social media and device sizes
-- Harmonious color schemes based on hash values
-- Grid-based composition system for balanced layouts
-- Multiple shape types and layering effects
-- Customizable output settings
+- Deterministic output — same hash always produces the same image
+- Hash-derived harmonious color schemes (analogic, complementary, and triadic palettes)
+- 20+ shape types across three categories: basic, complex, and sacred geometry
+- Layered composition with depth — early layers use simple shapes, later layers use intricate ones
+- Watercolor-style transparency with semi-transparent fills and color blending
+- Glow effects on sacred geometry shapes for an ethereal quality
+- Radial gradient fills and organic color jitter for a hand-painted feel
+- Organic bezier curves connecting nearby shapes
+- Configurable canvas size, layers, shape sizes, and opacity
+- Built-in presets for social media, device wallpapers, and print sizes
+- CLI for generating art from the current commit or a specific hash
+- Cross-platform: runs in Node.js (via `@napi-rs/canvas`) and browsers (native Canvas API)
 
 ## Installation
 
@@ -18,87 +25,170 @@ Generate beautiful, deterministic abstract art from git commit hashes. Perfect f
 npm install git-hash-art
 ```
 
-## Basic Usage
+For Node.js usage you also need the canvas backend:
+
+```bash
+npm install @napi-rs/canvas
+```
+
+Browser usage requires no additional dependencies — the library uses the native Canvas 2D API.
+
+## Node.js Usage
 
 ```javascript
-import { generateImageFromHash } from 'git-hash-art';
+import { generateImageFromHash, saveImageToFile } from 'git-hash-art';
 
-// Generate art from a git hash with default settings
+// Generate a PNG buffer from a git hash
 const gitHash = '46192e59d42f741c761cbea79462a8b3815dd905';
-generateImageFromHash(gitHash);
+const imageBuffer = generateImageFromHash(gitHash);
+
+// Save to disk
+saveImageToFile(imageBuffer, './output', gitHash, 'my-art', 2048, 2048);
 ```
 
-## Advanced Usage
+### Advanced Node.js Usage
 
 ```javascript
-// Custom configuration
+import { generateImageFromHash } from 'git-hash-art';
+
 const config = {
   width: 1920,
   height: 1080,
   gridSize: 6,
-  layers: 7,
-  shapesPerLayer: 30,
+  layers: 5,
+  shapesPerLayer: 40,
   minShapeSize: 20,
-  maxShapeSize: 180,
-  baseOpacity: 0.6,
-  opacityReduction: 0.1
+  maxShapeSize: 300,
+  baseOpacity: 0.7,
+  opacityReduction: 0.12
 };
 
-generateImageFromHash(gitHash, config);
+const imageBuffer = generateImageFromHash(gitHash, config);
 ```
 
-## Configuration Options
+## Browser Usage
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `width` | number | 1024 | Canvas width in pixels |
-| `height` | number | 1024 | Canvas height in pixels |
-| `gridSize` | number | 4 | Number of grid cells (gridSize x gridSize) |
-| `layers` | number | 5 | Number of layers to generate |
-| `shapesPerLayer` | number | - | Base number of shapes per layer (defaults to grid cells * 1.5) |
-| `minShapeSize` | number | 20 | Minimum shape size |
-| `maxShapeSize` | number | 180 | Maximum shape size |
-| `baseOpacity` | number | 0.6 | Starting opacity for first layer |
-| `opacityReduction` | number | 0.1 | How much to reduce opacity per layer |
+```javascript
+import { renderToCanvas, generateDataURL, generateImageBlob } from 'git-hash-art/browser';
+```
 
-## Preset Sizes
+### Render onto an existing canvas element
 
-The package includes several preset configurations for common use cases:
+```javascript
+import { renderToCanvas } from 'git-hash-art/browser';
+
+const canvas = document.getElementById('art-canvas');
+canvas.width = 1024;
+canvas.height = 1024;
+
+renderToCanvas(canvas, '46192e59d42f741c761cbea79462a8b3815dd905');
+```
+
+### Generate a data URL (for `<img>` tags)
 
 ```javascript
-import { PRESETS } from 'git-hash-art-generator';
+import { generateDataURL } from 'git-hash-art/browser';
 
-// Generate an Instagram-sized image
-generateImageFromHash(gitHash, PRESETS['instagram'].config);
+const dataUrl = generateDataURL('46192e59d42f741c761cbea79462a8b3815dd905', {
+  width: 512,
+  height: 512,
+});
 
-// Generate a mobile wallpaper
-generateImageFromHash(gitHash, PRESETS['phone-wallpaper'].config);
+document.getElementById('preview').src = dataUrl;
 ```
 
-Available presets include:
-- Standard (1024x1024)
-- Banner (1920x480)
-- Ultrawide (3440x1440)
-- Instagram (1080x1080)
-- Instagram Story (1080x1920)
-- Twitter Header (1500x500)
-- LinkedIn Banner (1584x396)
-- Phone Wallpaper (1170x2532)
-- Tablet Wallpaper (2048x2732)
-- Print sizes (A4/A3 at 300 DPI)
+### Generate a Blob (for downloads or uploads)
 
-## CLI Usage
+```javascript
+import { generateImageBlob } from 'git-hash-art/browser';
+
+const blob = await generateImageBlob('46192e59d42f741c761cbea79462a8b3815dd905', {
+  width: 1080,
+  height: 1080,
+});
+
+// Trigger a download
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'hash-art.png';
+a.click();
+```
+
+## Core Renderer (Environment-Agnostic)
+
+If you need full control, both entry points re-export `renderHashArt` which
+accepts any standard `CanvasRenderingContext2D` — useful for custom canvas
+setups, Web Workers with `OffscreenCanvas`, or server-side rendering
+frameworks.
+
+```javascript
+import { renderHashArt } from 'git-hash-art'; // or 'git-hash-art/browser'
+
+const ctx = myCanvas.getContext('2d');
+renderHashArt(ctx, '46192e59d42f741c761cbea79462a8b3815dd905', {
+  width: myCanvas.width,
+  height: myCanvas.height,
+});
+```
+
+## Configuration Options
+
+| Option            | Type   | Default | Description                                          |
+| ----------------- | ------ | ------- | ---------------------------------------------------- |
+| `width`           | number | 2048    | Canvas width in pixels                               |
+| `height`          | number | 2048    | Canvas height in pixels                              |
+| `gridSize`        | number | 5       | Controls base shape count per layer (gridSize² × 1.5)|
+| `layers`          | number | 4       | Number of layers to generate                         |
+| `shapesPerLayer`  | number | auto    | Base shapes per layer (defaults to gridSize² × 1.5)  |
+| `minShapeSize`    | number | 30      | Minimum shape size in pixels (scaled to canvas)      |
+| `maxShapeSize`    | number | 400     | Maximum shape size in pixels (scaled to canvas)      |
+| `baseOpacity`     | number | 0.7     | Starting opacity for the first layer                 |
+| `opacityReduction`| number | 0.12    | Opacity reduction per layer                          |
+
+## Shape Categories
 
-The package includes a command-line interface:
+Shapes are selected with layer-aware weighting — early layers favor simple shapes for background texture, later layers favor intricate ones for foreground detail.
+
+**Basic** — circle, square, triangle, hexagon, star, diamond, cube, heart
+
+**Complex** — platonic solids, fibonacci spiral, islamic pattern, celtic knot, merkaba, mandala, fractal
+
+**Sacred Geometry** — flower of life, tree of life, Metatron's cube, Sri Yantra, seed of life, vesica piscis, torus, egg of life
+
+## Preset Sizes
+
+```javascript
+import { PRESETS } from 'git-hash-art';
+
+// Use a preset's hash and config
+const preset = PRESETS['instagram-square'];
+const imageBuffer = generateImageFromHash(preset.hash, preset);
+```
+
+Available presets:
+
+- Standard (1024×1024)
+- Banner (1920×480)
+- Ultrawide (3440×1440)
+- Instagram Square (1080×1080)
+- Instagram Story (1080×1920)
+- Twitter Header (1500×500)
+- LinkedIn Banner (1584×396)
+- Phone Wallpaper (1170×2532)
+- Tablet Wallpaper (2048×2732)
+- Minimal, Complex (special configurations)
+
+## CLI Usage
 
 ```bash
-# Generate with default settings
+# Generate from the current commit
 npx git-hash-art current
 
-# Generate from specific hash
+# Generate from a specific hash
 npx git-hash-art generate <hash>
 
-# Generate with custom size
+# Custom size
 npx git-hash-art generate <hash> --width 1920 --height 1080
 ```
 
@@ -115,7 +205,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
-      - run: npm install git-hash-art-generator
+      - run: npm install git-hash-art @napi-rs/canvas
       - run: npx git-hash-art current --output artwork/
 ```
 
@@ -124,15 +214,33 @@ jobs:
 ```bash
 #!/bin/sh
 # .git/hooks/post-commit
-
 hash=$(git rev-parse HEAD)
 npx git-hash-art generate $hash --output .git/artwork/
 ```
 
+### React Component
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { renderToCanvas } from 'git-hash-art/browser';
+
+function CommitArt({ hash, width = 256, height = 256 }) {
+  const canvasRef = useRef(null);
+
+  useEffect(() => {
+    if (canvasRef.current) {
+      renderToCanvas(canvasRef.current, hash, { width, height });
+    }
+  }, [hash, width, height]);
+
+  return <canvas ref={canvasRef} width={width} height={height} />;
+}
+```
+
 ## Contributing
 
 Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more details.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see [LICENSE](LICENSE) for details.