git-hash-art 0.5.0 → 0.7.0

package/ALGORITHM.md

@@ -9,28 +9,33 @@ Hash String
   │
   ├─► Seed (mulberry32 PRNG)
   │
-  ├─► Color Scheme (hash-driven variation + scheme type + temperature mode)
+  ├─► Archetype Selection (1 of 10 visual personalities)
   │
-  └─► Rendering Pipeline
+  ├─► Color Scheme (palette mode from archetype + temperature mode + contrast enforcement)
+  │
+  └─► Rendering Pipeline (parameters overridden by archetype)
        │
-       1.  Background Layer (radial gradient, temperature-shifted)
+       0.  Archetype Override (gridSize, layers, opacity, sizes, styles)
+       1.  Background Layer (7 styles: radial, linear, solid, multi-stop)
+       1a. Background Luminance → contrast enforcement threshold
        1b. Layered Background (faint shapes + concentric rings)
        2.  Composition Mode Selection
        2b. Symmetry Mode Selection (none / bilateral / quad)
        3.  Focal Points (rule-of-thirds biased) + Void Zones
        4.  Flow Field Initialization
-       4b. Hero Shape (large focal anchor, ~60% of images)
-       5.  Shape Layers (× N layers)
+       4b. Hero Shape (large focal anchor, archetype-controlled)
+       5.  Shape Layers (× N layers, archetype-tuned)
        │   ├─ Blend Mode (per-layer compositing)
-       │   ├─ Render Style (fill+stroke, wireframe, dashed, watercolor, hatched, incomplete, etc.)
+       │   ├─ Render Style (archetype-preferred + random mix)
        │   ├─ Position (composition mode + focal bias + density check)
-       │   ├─ Shape Selection (layer-weighted)
+       │   ├─ Shape Selection (4 categories: basic, complex, sacred, procedural)
+       │   ├─ Contrast Enforcement (ensure readability vs background)
        │   ├─ Atmospheric Depth (desaturation on later layers)
        │   ├─ Temperature Contrast (foreground opposite to background)
        │   ├─ Styling (transparency, glow, gradients, color jitter)
        │   ├─ Organic Edges (~15% watercolor bleed)
        │   └─ Recursive Nesting (~15% of large shapes)
-       6.  Flow-Line Pass (tapered brush strokes)
+       6.  Flow-Line Pass (tapered brush strokes, archetype-scaled)
        6b. Symmetry Mirroring (bilateral-x, bilateral-y, or quad)
        7.  Noise Texture Overlay
        8.  Vignette (radial edge darkening)
@@ -48,7 +53,44 @@ rng() → float in [0, 1)
 
 The old approach extracted 2-char hex pairs from the hash (only ~20 unique values in a 40-char hash). Mulberry32 produces a full 32-bit uniform stream from any seed, eliminating correlation artifacts.
 
-## 2. Color Scheme
+## 2. Archetype System
+
+Before any rendering begins, the hash deterministically selects one of 10 **visual archetypes** — fundamentally different rendering personalities that override key parameters. This is the primary mechanism for visual diversity: two hashes that select different archetypes will look like they came from entirely different generators.
+
+Each archetype controls:
+
+| Parameter | Effect |
+|-----------|--------|
+| `gridSize` | Shape density (2 = sparse, 9 = packed) |
+| `layers` | Rendering depth (2 = flat, 5 = deep) |
+| `baseOpacity` / `opacityReduction` | Transparency character |
+| `minShapeSize` / `maxShapeSize` | Scale range |
+| `backgroundStyle` | One of 7 background rendering modes |
+| `paletteMode` | One of 7 color palette strategies |
+| `preferredStyles` | Weighted render style selection |
+| `flowLineMultiplier` | Flow line density (0 = none, 4 = heavy) |
+| `heroShape` | Whether to draw a dominant focal shape |
+| `glowMultiplier` | Glow probability scaling (0 = none, 3 = heavy) |
+| `sizePower` | Size distribution curve (0.5 = uniform, 2.5 = many tiny) |
+
+### The 10 Archetypes
+
+| Archetype | Character | Background | Palette | Key Traits |
+|-----------|-----------|------------|---------|------------|
+| **dense-chaotic** | Packed, energetic | radial-dark | harmonious | 9×9 grid, 5 layers, heavy flow lines, low glow |
+| **minimal-spacious** | Clean, deliberate | solid-light | duotone | 2×2 grid, 2 layers, large shapes, no glow |
+| **organic-flow** | Natural, flowing | radial-dark | earth | Heavy flow lines (4×), watercolor style, no hero |
+| **geometric-precision** | Technical, structured | solid-dark | high-contrast | Stroke-only/dashed/hatched styles, no flow lines |
+| **ethereal** | Dreamy, luminous | radial-light | pastel-light | High glow (2×), watercolor, hero shape |
+| **bold-graphic** | Poster-like, impactful | linear-diagonal | duotone | 2 layers, very large shapes, no flow lines |
+| **neon-glow** | Electric, vibrant | solid-dark | neon | Heavy glow (3×), stroke-heavy styles, hero shape |
+| **monochrome-ink** | Pen-and-ink, textural | solid-light | monochrome | Hatched/incomplete styles, no glow |
+| **cosmic** | Deep space, vast | radial-dark | neon | 8×8 grid, 5 layers, heavy glow, many tiny shapes |
+| **classic** | Balanced, familiar | radial-dark | harmonious | Preserves the original rendering look |
+
+Archetype values serve as defaults — explicit user config always wins. The `classic` archetype preserves backward compatibility with the original rendering style.
+
+## 3. Color Scheme
 
 The `SacredColorScheme` class derives three harmonious palettes from the hash:
 
@@ -60,6 +102,22 @@ The `SacredColorScheme` class derives three harmonious palettes from the hash:
 
 These are merged and deduplicated into a single 6-8 color palette. Background colors are darkened variants (65% and 55% brightness) of the base scheme, with optional temperature shifting.
 
+### Palette Modes
+
+The archetype's `paletteMode` reshapes the color palette to match the visual personality:
+
+| Mode | Colors | Character |
+|------|--------|-----------|
+| **harmonious** | Full base + complementary + triadic | Rich, balanced (default) |
+| **monochrome** | Single hue, 5 lightness steps | Elegant, focused |
+| **duotone** | Two contrasting hues + tints | Bold, graphic |
+| **neon** | 4 hues at full saturation | Electric, vivid |
+| **pastel-light** | 4 hues at low saturation, high lightness | Soft, dreamy |
+| **earth** | Warm muted naturals (browns, olives, sage) | Organic, grounded |
+| **high-contrast** | Black + white + one accent | Technical, stark |
+
+Each mode also provides matching background colors (e.g., neon gets near-black backgrounds, pastel-light gets warm off-whites).
+
 ### Temperature Contrast
 
 The hash deterministically selects a **temperature mode** that creates warm/cool tension across the image:
@@ -95,9 +153,21 @@ Scheme types also vary: `analogic`, `mono`, `contrast`, `triade`, `tetrade`. The
 - **`shiftTemperature(hex, target, amount)`** — shifts hue toward warm (orange) or cool (blue)
 - **Positional blending** — shape fill color is biased by canvas position, creating smooth color flow across the image
 
-## 3. Background
+## 4. Background
+
+The archetype's `backgroundStyle` selects one of 7 rendering modes:
+
+| Style | Description |
+|-------|-------------|
+| **radial-dark** | Radial gradient from dark center to darker edges (original default) |
+| **radial-light** | Light off-white center fading to the base palette |
+| **linear-horizontal** | Left-to-right gradient between two palette colors |
+| **linear-diagonal** | Corner-to-corner gradient with color reversal |
+| **solid-dark** | Flat dark color fill |
+| **solid-light** | Flat warm off-white fill |
+| **multi-stop** | 3-4 color gradient with a darkened mid-palette accent |
 
-A radial gradient fills the canvas from center to corners using two darkened base-scheme colors. This creates depth before any shapes are drawn.
+This single change has an outsized impact on visual diversity — a solid-light background with monochrome shapes looks nothing like a radial-dark background with neon glow.
 
 ### Layered Background
 
@@ -108,7 +178,7 @@ After the gradient, a second pass adds visual texture to the background:
 
 This prevents the background from feeling flat and gives the image depth before the main shape layers begin.
 
-## 4. Composition Modes
+## 5. Composition Modes
 
 The hash deterministically selects one of five composition strategies that control how shapes are positioned on the canvas:
 
@@ -135,7 +205,7 @@ Each mode produces fundamentally different visual character from the same shape
 
 Symmetry is applied after shape layers and flow lines but before post-processing (noise, vignette, connecting curves). This means the mirrored content gets the same noise texture and vignette as the original, maintaining visual consistency. Symmetrical generative art is disproportionately appealing to humans due to our innate preference for bilateral symmetry.
 
-## 5. Focal Points & Negative Space
+## 6. Focal Points & Negative Space
 
 1-2 focal points are placed on the canvas. **70% of the time**, focal points snap to **rule-of-thirds intersection points** (with slight jitter to avoid a mechanical look), creating compositions that feel intentionally designed. The remaining 30% use free placement within the central 60% of the canvas. Every shape position is pulled toward the nearest focal point by a strength factor (30-70%).
 
@@ -156,7 +226,7 @@ Symmetry is applied after shape layers and flow lines but before post-processing
 
 Before placing each shape, the renderer checks how many shapes already exist nearby. If local density exceeds ~15% of the per-layer shape count, there's a 60% chance the shape is skipped. This prevents areas from becoming an opaque blob and creates natural visual rhythm.
 
-## 6. Shape Layers
+## 7. Shape Layers
 
 The image is built in N layers (default: 4). Each layer has its own characteristics:
 
@@ -169,7 +239,7 @@ The image is built in N layers (default: 4). Each layer has its own characterist
 | Shape weights | Early layers favor basic shapes; later layers favor complex/sacred |
 | Per-shape opacity | Additional random jitter (50-100% of layer opacity) |
 | Blend mode | Each layer gets a hash-derived `globalCompositeOperation` (see below) |
-| Render style | Each layer has a dominant render style; 30% of shapes pick their own |
+| Render style | Each layer has a dominant render style (60% from archetype preferences, 40% random); 30% of shapes pick their own |
 | Atmospheric depth | Later layers desaturate colors by up to 30%, simulating distance |
 
 ### Blend Modes (Per-Layer Compositing)
@@ -199,13 +269,25 @@ Later layers progressively desaturate their colors (0% on layer 0, up to 30% on
 
 ### Shape Selection (Layer-Weighted)
 
-Shapes are divided into three categories with weights that shift across layers:
+Shapes are divided into four categories with weights that shift across layers:
 
 | Category | Shapes | Early layers | Late layers |
 |----------|--------|-------------|-------------|
 | **Basic** | circle, square, triangle, hexagon, diamond, cube | High weight | Low weight |
 | **Complex** | star, platonic solid, fibonacci spiral, islamic pattern, celtic knot, merkaba, fractal | Medium | Medium-high |
 | **Sacred** | mandala, flower of life, tree of life, Metatron's cube, Sri Yantra, seed of life, vesica piscis, torus, egg of life | Low | High |
+| **Procedural** | blob, ngon, lissajous, superellipse, spirograph, waveRing, rose | Medium (always present) | Medium-high |
+
+Procedural shapes are hash-derived — their geometry is generated from the RNG, so every hash produces unique shapes that don't exist in any other generation. See the Procedural Shapes section below for details.
+
+### Contrast Enforcement
+
+After color selection, every foreground color (fills, strokes, flow lines, connecting curves) is checked against the average background luminance. If the luminance difference is below the minimum threshold (0.15), the color is adjusted:
+
+- **Light backgrounds** — foreground colors are darkened and saturated
+- **Dark backgrounds** — foreground colors are lightened and saturated
+
+This prevents the white-on-white and dark-on-dark readability problems that occur when light palette modes (pastel-light, high-contrast) combine with light background styles (solid-light, radial-light).
 
 ### Size Distribution
 
@@ -230,7 +312,7 @@ Each shape receives:
 - Sized at 15-40% of the parent
 - More transparent than the parent layer
 
-## 7. Flow-Line Pass (Tapered Brush Strokes)
+## 8. Flow-Line Pass (Tapered Brush Strokes)
 
 6-16 flowing curves are drawn across the canvas, following the hash-derived vector field:
 
@@ -246,7 +328,7 @@ The flow field is defined by:
 angle(x, y) = baseAngle + sin(x/w × freq × 2π) × π/2 + cos(y/h × freq × 2π) × π/2
 ```
 
-## 8. Noise Texture Overlay
+## 9. Noise Texture Overlay
 
 A dedicated noise RNG (seeded separately from the main RNG to avoid affecting shape generation) renders thousands of 1px dots across the canvas:
 
@@ -255,7 +337,7 @@ A dedicated noise RNG (seeded separately from the main RNG to avoid affecting sh
 - Very low opacity (1-4%)
 - Creates subtle film-grain texture that adds organic depth
 
-## 8b. Vignette
+## 9b. Vignette
 
 A radial gradient overlay darkens the edges of the canvas, drawing the viewer's eye toward the center:
 
@@ -264,7 +346,7 @@ A radial gradient overlay darkens the edges of the canvas, drawing the viewer's
 - Applied after noise but before connecting curves, so the curves remain visible at edges
 - Creates a natural "spotlight" effect that makes compositions feel more focused and photographic
 
-## 9. Organic Connecting Curves
+## 10. Organic Connecting Curves
 
 Quadratic bezier curves connect nearby shapes:
 
@@ -298,6 +380,19 @@ Mathematically precise sacred geometry patterns:
 - **Torus** — 2D projection of a torus via line segments
 - **Egg of Life** — 7 circles in tight hexagonal packing
 
+### Procedural Shapes
+Hash-derived shapes whose geometry is generated from the RNG. Every hash produces unique shapes that don't exist in any other generation:
+
+| Shape | Algorithm | Hash Controls |
+|-------|-----------|---------------|
+| **Blob** | Smooth closed curve via quadratic bezier through 5-9 control points arranged around a circle | Number of lobes (5-9), radius jitter per lobe (50-100%) |
+| **Ngon** | Irregular polygon with independent vertex displacement | Side count (3-12), vertex jitter amount (10-50%) |
+| **Lissajous** | Parametric curve `x = sin(a*t + φ), y = sin(b*t)` | Frequency ratios a,b (1-5 each), phase offset φ |
+| **Superellipse** | `|x|^n + |y|^n = 1` rendered parametrically | Exponent n: 0.3 (spiky astroid) → 2 (circle) → 5 (rounded rectangle) |
+| **Spirograph** | Hypotrochoid curve `(R-r)cos(t) + d*cos((R-r)t/r)` | Inner radius ratio r (0.2-0.8), pen distance d (0.3-1.0) |
+| **Wave Ring** | Concentric rings with sinusoidal radial displacement | Ring count (2-5), wave frequency (3-14), amplitude (5-20%) |
+| **Rose** | Polar rose curve `r = cos(k*θ)` | Petal parameter k (2-7), producing k or 2k petals |
+
 ## Configuration
 
 All parameters are exposed via `GenerationConfig`:

package/CHANGELOG.md

@@ -4,8 +4,25 @@ 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.7.0](https://github.com/gfargo/git-hash-art/compare/0.6.0...0.7.0)
+
+- feat: procedural shape generators and contrast enforcement [`#13`](https://github.com/gfargo/git-hash-art/pull/13)
+- feat: procedural shapes and contrast enforcement [`4f018ab`](https://github.com/gfargo/git-hash-art/commit/4f018abb4c89849954ccc941ee7e9ab468231f78)
+- docs: update ALGORITHM.md with procedural shapes and contrast enforcement [`3e044fd`](https://github.com/gfargo/git-hash-art/commit/3e044fd940fbc0f62e3a9696fa815145cf315f67)
+
+#### [0.6.0](https://github.com/gfargo/git-hash-art/compare/0.5.0...0.6.0)
+
+> 19 March 2026
+
+- feat: archetype system, palette modes, background variety, and CLI [`#12`](https://github.com/gfargo/git-hash-art/pull/12)
+- feat: archetype system for dramatically different visual personalities [`2a1b919`](https://github.com/gfargo/git-hash-art/commit/2a1b919c51d3bfbd9d5c7a381ea5e104f81df2f6)
+- feat: add CLI for generating art from terminal [`184372a`](https://github.com/gfargo/git-hash-art/commit/184372a584f68031bf44379f385f2e78691f98aa)
+- docs: update ALGORITHM.md with archetype system, palette modes, and background styles [`4eccd07`](https://github.com/gfargo/git-hash-art/commit/4eccd077be9469c27caf60a0d8c463124ad7f9fa)
+
 #### [0.5.0](https://github.com/gfargo/git-hash-art/compare/0.4.1...0.5.0)
 
+> 19 March 2026
+
 - feat: visual improvements — composition, color, and rendering upgrades [`#11`](https://github.com/gfargo/git-hash-art/pull/11)
 - feat: warm/cool temperature contrast in color system [`550bc6a`](https://github.com/gfargo/git-hash-art/commit/550bc6a87929d7ebafa973079845e688a00de929)
 - docs: update ALGORITHM.md with all new visual features [`a05de15`](https://github.com/gfargo/git-hash-art/commit/a05de1586684b91266f5a26ea7279fc601dd2202)

package/bin/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const { generateImageFromHash, saveImageToFile } = require("../dist/main.js");
+const { PRESETS } = require("../dist/main.js");
+
+const HELP = `
+git-hash-art — Generate deterministic abstract art from git hashes.
+
+Usage:
+  git-hash-art current [options]          Generate art from HEAD commit
+  git-hash-art generate <hash> [options]  Generate art from a specific hash
+
+Options:
+  --width <n>       Canvas width in pixels (default: 2048)
+  --height <n>      Canvas height in pixels (default: 2048)
+  --output <dir>    Output directory (default: ./output)
+  --preset <name>   Use a built-in preset (overrides width/height)
+  --layers <n>      Number of layers (default: 4)
+  --grid <n>        Grid density (default: 5)
+  --list-presets    List available presets
+
+Examples:
+  npx git-hash-art current
+  npx git-hash-art current --preset instagram-square
+  npx git-hash-art generate abc123ff --width 1920 --height 1080
+`;
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const parsed = { command, hash: null, options: {} };
+
+  let i = 1;
+  if (command === "generate") {
+    parsed.hash = args[1];
+    i = 2;
+  }
+
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--width" && args[i + 1]) {
+      parsed.options.width = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--height" && args[i + 1]) {
+      parsed.options.height = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--output" && args[i + 1]) {
+      parsed.options.output = args[i + 1];
+      i += 2;
+    } else if (arg === "--preset" && args[i + 1]) {
+      parsed.options.preset = args[i + 1];
+      i += 2;
+    } else if (arg === "--layers" && args[i + 1]) {
+      parsed.options.layers = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--grid" && args[i + 1]) {
+      parsed.options.gridSize = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--list-presets") {
+      parsed.command = "list-presets";
+      i += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.command = "help";
+      i += 1;
+    } else {
+      i += 1;
+    }
+  }
+
+  return parsed;
+}
+
+function getHeadHash() {
+  try {
+    return execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+  } catch {
+    console.error("Error: Not a git repository or git is not installed.");
+    process.exit(1);
+  }
+}
+
+function listPresets() {
+  console.log("\nAvailable presets:\n");
+  for (const [name, config] of Object.entries(PRESETS)) {
+    console.log(`  ${name.padEnd(20)} ${config.width}x${config.height}`);
+  }
+  console.log("");
+}
+
+function run() {
+  const { command, hash, options } = parseArgs(process.argv);
+
+  if (!command || command === "help") {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (command === "list-presets") {
+    listPresets();
+    process.exit(0);
+  }
+
+  if (command !== "current" && command !== "generate") {
+    console.error(`Unknown command: ${command}\n`);
+    console.log(HELP);
+    process.exit(1);
+  }
+
+  let gitHash;
+  if (command === "current") {
+    gitHash = getHeadHash();
+    console.log(`Using HEAD: ${gitHash}`);
+  } else {
+    if (!hash) {
+      console.error("Error: Please provide a hash.\n");
+      console.log("Usage: git-hash-art generate <hash> [options]");
+      process.exit(1);
+    }
+    gitHash = hash;
+  }
+
+  // Build config from preset + overrides
+  let config = {};
+  if (options.preset) {
+    const preset = PRESETS[options.preset];
+    if (!preset) {
+      console.error(`Unknown preset: ${options.preset}`);
+      console.log("Use --list-presets to see available presets.");
+      process.exit(1);
+    }
+    config = { ...preset };
+    delete config.hash;
+  }
+
+  if (options.width) config.width = options.width;
+  if (options.height) config.height = options.height;
+  if (options.layers) config.layers = options.layers;
+  if (options.gridSize) config.gridSize = options.gridSize;
+
+  const outputDir = options.output || "./output";
+
+  try {
+    const buffer = generateImageFromHash(gitHash, config);
+    const w = config.width || 2048;
+    const h = config.height || 2048;
+    const outputPath = saveImageToFile(buffer, outputDir, gitHash, "", w, h);
+    console.log(`Done! Image saved to ${outputPath}`);
+  } catch (error) {
+    console.error("Generation failed:", error.message);
+    process.exit(1);
+  }
+}
+
+run();