git-hash-art 0.4.1 → 0.6.0

package/ALGORITHM.md

@@ -9,27 +9,35 @@ Hash String
   │
   ├─► Seed (mulberry32 PRNG)
   │
-  ├─► Color Scheme (hash-driven variation + scheme type selection)
+  ├─► Archetype Selection (1 of 10 visual personalities)
   │
-  └─► Rendering Pipeline
+  ├─► Color Scheme (palette mode from archetype + temperature mode)
+  │
+  └─► Rendering Pipeline (parameters overridden by archetype)
        │
-       1.  Background Layer (radial gradient)
+       0.  Archetype Override (gridSize, layers, opacity, sizes, styles)
+       1.  Background Layer (7 styles: radial, linear, solid, multi-stop)
        1b. Layered Background (faint shapes + concentric rings)
        2.  Composition Mode Selection
-       3.  Focal Points + Void Zones (negative space)
+       2b. Symmetry Mode Selection (none / bilateral / quad)
+       3.  Focal Points (rule-of-thirds biased) + Void Zones
        4.  Flow Field Initialization
-       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, etc.)
+       │   ├─ Render Style (archetype-preferred + random mix)
        │   ├─ Position (composition mode + focal bias + density check)
        │   ├─ Shape Selection (layer-weighted)
        │   ├─ 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.  Organic Connecting Curves
+       8.  Vignette (radial edge darkening)
+       9.  Organic Connecting Curves
 ```
 
 ## 1. Deterministic RNG
@@ -43,7 +51,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:
 
@@ -53,7 +98,35 @@ The `SacredColorScheme` class derives three harmonious palettes from the hash:
 | Complementary | hue = seed + 180°, contrasting variation | Contrast accents |
 | Triadic | hue = seed + 120° | Additional variety |
 
-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.
+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:
+
+| Mode | Probability | Background | Foreground |
+|------|-------------|------------|------------|
+| `warm-bg` | ~40% | Hues shifted toward orange (30°) | Hues shifted toward blue (210°) |
+| `cool-bg` | ~40% | Hues shifted toward blue (210°) | Hues shifted toward orange (30°) |
+| `neutral` | ~20% | No temperature shift | No temperature shift |
+
+The shift amount is subtle (15-25%) and increases on later layers, creating progressive temperature separation between foreground and background elements. This produces the kind of warm/cool interplay seen in classical painting.
 
 ### Hash-Driven Color Variation
 
@@ -75,11 +148,24 @@ Scheme types also vary: `analogic`, `mono`, `contrast`, `triade`, `tetrade`. The
 - **`hexWithAlpha(hex, alpha)`** — converts hex to `rgba()` for transparency
 - **`jitterColor(hex, rng, amount)`** — applies ±amount RGB jitter per channel for organic variation
 - **`desaturate(hex, amount)`** — blends toward luminance gray for atmospheric depth
+- **`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:
 
-A radial gradient fills the canvas from center to corners using two darkened base-scheme colors. This creates depth before any shapes are drawn.
+| 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 |
+
+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
 
@@ -90,7 +176,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:
 
@@ -104,9 +190,31 @@ The hash deterministically selects one of five composition strategies that contr
 
 Each mode produces fundamentally different visual character from the same shape set.
 
-## 5. Focal Points & Negative Space
+### Symmetry Modes
+
+~25% of hashes trigger a symmetry mode that mirrors the rendered content:
+
+| Mode | Probability | Effect |
+|------|-------------|--------|
+| `bilateral-x` | 10% | Left half mirrored onto right half |
+| `bilateral-y` | 10% | Top half mirrored onto bottom half |
+| `quad` | 5% | Both axes mirrored (4-fold symmetry) |
+| `none` | 75% | No mirroring |
+
+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.
+
+## 6. Focal Points & Negative Space
 
-1-2 focal points are placed on the canvas (kept away from edges). Every shape position is pulled toward the nearest focal point by a strength factor (30-70%), creating areas of visual density and intentional-looking composition rather than uniform scatter.
+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%).
+
+### Hero Shape
+
+~60% of images receive a **hero shape** — a large sacred or complex geometry piece anchored at the primary focal point. The hero shape:
+- Uses sacred/complex shape types (flower of life, fibonacci spiral, merkaba, fractal, etc.)
+- Is sized at 80-130% of the maximum shape size for visual dominance
+- Gets glow effects, gradient fills, and often watercolor rendering
+- Is drawn before the main shape layers so other shapes layer on top of it
+- Creates a clear center of gravity that anchors the entire composition
 
 ### Void Zones (Negative Space)
 
@@ -116,7 +224,7 @@ Each mode produces fundamentally different visual character from the same shape
 
 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:
 
@@ -129,7 +237,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)
@@ -142,12 +250,14 @@ Instead of always `fill()` + `stroke()`, each shape gets a rendering treatment:
 
 | Style | Description | Probability |
 |-------|-------------|-------------|
-| `fill-and-stroke` | Classic solid fill with outline | ~29% (weighted) |
-| `fill-only` | Soft shapes with no outline | ~14% |
-| `stroke-only` | Wireframe with ghost fill at 30% alpha | ~14% |
-| `double-stroke` | Outer stroke at 2× width + inner stroke in fill color | ~14% |
-| `dashed` | Dashed outline (5% size dash, 3% gap) | ~14% |
-| `watercolor` | 3-4 slightly offset passes at low opacity for bleed effect | ~14% |
+| `fill-and-stroke` | Classic solid fill with outline | ~22% (weighted) |
+| `fill-only` | Soft shapes with no outline | ~11% |
+| `stroke-only` | Wireframe with ghost fill at 30% alpha | ~11% |
+| `double-stroke` | Outer stroke at 2× width + inner stroke in fill color | ~11% |
+| `dashed` | Dashed outline (5% size dash, 3% gap) | ~11% |
+| `watercolor` | 3-4 slightly offset passes at low opacity for bleed effect | ~11% |
+| `hatched` | Cross-hatch texture fill clipped to shape boundary | ~11% |
+| `incomplete` | Only 60-85% of outline drawn via dash patterns | ~11% |
 
 70% of shapes in a layer use the layer's dominant style; 30% pick independently. Additionally, ~15% of `fill-and-stroke` shapes are upgraded to `watercolor` for organic edge effects.
 
@@ -188,7 +298,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:
 
@@ -204,7 +314,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:
 
@@ -213,7 +323,16 @@ 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
 
-## 9. Organic Connecting Curves
+## 9b. Vignette
+
+A radial gradient overlay darkens the edges of the canvas, drawing the viewer's eye toward the center:
+
+- Strength varies by hash: 25-45% maximum edge darkening
+- The vignette begins fading at 60% of the canvas radius from center
+- 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
+
+## 10. Organic Connecting Curves
 
 Quadratic bezier curves connect nearby shapes:
 

package/CHANGELOG.md

@@ -4,8 +4,27 @@ 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.6.0](https://github.com/gfargo/git-hash-art/compare/0.5.0...0.6.0)
+
+- 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)
+- feat: hatched and incomplete render styles for shape variety [`4f42f7e`](https://github.com/gfargo/git-hash-art/commit/4f42f7e30bac60239b69468e36ef5481dca5d007)
+
 #### [0.4.1](https://github.com/gfargo/git-hash-art/compare/0.4.0...0.4.1)
 
+> 19 March 2026
+
+- chore: release v0.4.1 [`c453061`](https://github.com/gfargo/git-hash-art/commit/c4530616bc40a540ce4d87a8124a1d2665f77376)
 - update README with new feature details [`1e3fcd7`](https://github.com/gfargo/git-hash-art/commit/1e3fcd771ea602b21c9c90cd3809d0d08ace5d3f)
 - update color variations and complementary logic [`9c8f4ba`](https://github.com/gfargo/git-hash-art/commit/9c8f4ba51e1a5730e4c4ddd59218db23d4719129)
 

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();