git-hash-art 0.7.0 → 0.9.0

package/ALGORITHM.md

@@ -4,49 +4,70 @@ This document describes the deterministic art generation pipeline used by `git-h
 
 ## Pipeline Overview
 
-```
+```text
 Hash String
   │
   ├─► Seed (mulberry32 PRNG)
   │
-  ├─► Archetype Selection (1 of 10 visual personalities)
+  ├─► Archetype Selection (1 of 17 visual personalities)
+  │
+  ├─► Color Scheme (palette mode + temperature mode + contrast enforcement)
+  │   └─► Color Hierarchy (dominant 60% / secondary 25% / accent 15%)
   │
-  ├─► Color Scheme (palette mode from archetype + temperature mode + contrast enforcement)
+  ├─► Shape Palette (affinity-curated primary / supporting / accent shapes)
+  │
+  ├─► Color Grade Selection (unified tone for post-processing)
   │
   └─► Rendering Pipeline (parameters overridden by archetype)
        │
        0.  Archetype Override (gridSize, layers, opacity, sizes, styles)
+       0b. Color Hierarchy (dominant/secondary/accent weighting)
+       0c. Shape Palette (curated via affinity graph)
+       0d. Color Grade (hue + intensity for final tone)
+       0e. Light Direction (consistent shadow angle)
        1.  Background Layer (7 styles: radial, linear, solid, multi-stop)
+           └─ Gradient Mesh Overlay (3-4 radial color control points)
        1a. Background Luminance → contrast enforcement threshold
-       1b. Layered Background (faint shapes + concentric rings)
+       1b. Layered Background (archetype-coherent shapes + concentric rings)
+       1c. Background Pattern Layer (dot grid / diagonal lines / tessellation)
        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, archetype-controlled)
+       4b. Hero Shape (palette-aware, affinity-styled)
        5.  Shape Layers (× N layers, archetype-tuned)
        │   ├─ Blend Mode (per-layer compositing)
-       │   ├─ Render Style (archetype-preferred + random mix)
+       │   ├─ Render Style (affinity-aware per shape)
+       │   ├─ Depth-of-Field (stroke thinning + contrast reduction on far layers)
        │   ├─ Position (composition mode + focal bias + density check)
-       │   ├─ Shape Selection (4 categories: basic, complex, sacred, procedural)
+       │   ├─ Shape Selection (palette-driven with size constraints)
+       │   ├─ Hero Avoidance Field (nearby shapes orient toward hero)
        │   ├─ Contrast Enforcement (ensure readability vs background)
        │   ├─ Atmospheric Depth (desaturation on later layers)
        │   ├─ Temperature Contrast (foreground opposite to background)
-       │   ├─ Styling (transparency, glow, gradients, color jitter)
+       │   ├─ Styling (transparency, glow, gradients, HSL jitter)
        │   ├─ Organic Edges (~15% watercolor bleed)
-       │   └─ Recursive Nesting (~15% of large shapes)
-       6.  Flow-Line Pass (tapered brush strokes, archetype-scaled)
+       │   ├─ 5a. Tangent Placement (~25% nudge toward nearest shape edge)
+       │   ├─ 5b. Shape Mirroring (~40% of basic shapes get reflected copies)
+       │   ├─ 5c. Size Echo (~20% of large shapes spawn trailing copies)
+       │   ├─ 5d. Recursive Nesting (~15% of large shapes, palette-aware)
+       │   └─ 5e. Shape Constellations (~12% of large shapes, pre-composed groups)
+       6.  Flow-Line Pass (variable color, pressure, branching)
        6b. Symmetry Mirroring (bilateral-x, bilateral-y, or quad)
        7.  Noise Texture Overlay
        8.  Vignette (radial edge darkening)
        9.  Organic Connecting Curves
+       10. Post-Processing
+           ├─ Color Grading (unified tone overlay)
+           ├─ Chromatic Aberration (neon/cosmic/ethereal only)
+           └─ Bloom (neon/cosmic only)
 ```
 
 ## 1. Deterministic RNG
 
 All randomness flows from a single **mulberry32** PRNG seeded by hashing the full input string:
 
-```
+```text
 seed = hash(gitHash) → mulberry32 state
 rng() → float in [0, 1)
 ```
@@ -55,12 +76,12 @@ The old approach extracted 2-char hex pairs from the hash (only ~20 unique value
 
 ## 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.
+Before any rendering begins, the hash deterministically selects one of 17 **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 |
@@ -71,340 +92,372 @@ Each archetype controls:
 | `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) |
+| `sizePower` | Size distribution curve (0.5 = uniform, 2.8 = many tiny) |
 
-### The 10 Archetypes
+### The 17 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 | Grid | Layers | Background | Palette | Key Styles | Flow | Hero | Character |
+| --------- | ---- | ------ | ---------- | ------- | ---------- | ---- | ---- | --------- |
+| dense-chaotic | 9 | 5 | radial-dark | harmonious | fill-and-stroke, watercolor | 2.5× | no | Packed, layered, energetic |
+| minimal-spacious | 2 | 2 | solid-light | duotone | fill-and-stroke, stroke-only, incomplete | 0.3× | yes | Clean, airy, few large shapes |
+| organic-flow | 4 | 3 | radial-dark | earth | watercolor, fill-only, incomplete | 4× | no | Natural, flowing, muted tones |
+| geometric-precision | 6 | 3 | solid-dark | high-contrast | stroke-only, dashed, double-stroke, hatched | 0× | no | Sharp, structured, no flow lines |
+| ethereal | 7 | 5 | radial-light | pastel-light | watercolor, incomplete | 1.5× | yes | Soft, glowing, dreamlike |
+| bold-graphic | 2 | 2 | linear-diagonal | duotone | fill-and-stroke, double-stroke | 0× | yes | Poster-like, large shapes |
+| neon-glow | 5 | 4 | solid-dark | neon | stroke-only, double-stroke, dashed | 2× | yes | Bright outlines on black, heavy glow |
+| monochrome-ink | 6 | 3 | solid-light | monochrome | hatched, incomplete, stroke-only | 1.5× | no | Pen-and-ink, single hue |
+| cosmic | 8 | 5 | radial-dark | neon | fill-only, watercolor | 3× | yes | Deep space, many tiny shapes, glow |
+| watercolor-wash | 3 | 3 | radial-light | harmonious | watercolor, fill-only, incomplete | 0.5× | no | Soft washes, large shapes, low opacity |
+| op-art | 8 | 2 | solid-light | high-contrast | fill-and-stroke, stroke-only, dashed | 0× | no | Dense, high-contrast, uniform sizes |
+| collage | 4 | 3 | solid-light | duotone | fill-and-stroke, fill-only, double-stroke | 0× | yes | Overlapping, medium-large shapes |
+| classic | 5 | 4 | radial-dark | harmonious | fill-and-stroke, watercolor | 1× | yes | Balanced, the original look |
+| shattered-glass | 8 | 3 | solid-dark | high-contrast | fill-and-stroke, stroke-only, fill-only | 0× | no | Angular fragments, sharp edges, mosaic-like |
+| botanical | 4 | 4 | radial-light | earth | watercolor, fill-only, incomplete | 3× | yes | Organic tendrils, flowing forms, natural tones |
+| stipple-portrait | 9 | 2 | solid-light | monochrome | stipple, fill-only, hatched | 0× | no | Dense dot textures, pointillist, single hue |
+| celestial | 7 | 5 | radial-dark | neon | fill-only, watercolor, stroke-only, incomplete | 2× | yes | Cosmic crescents, sacred geometry, heavy glow |
 
-Archetype values serve as defaults — explicit user config always wins. The `classic` archetype preserves backward compatibility with the original rendering style.
+#### New Archetype Details
 
-## 3. Color Scheme
+**shattered-glass** — Favors angular, fragmented shapes (shardField, voronoiCell, penroseTile, diamond, triangle, ngon). Organic shapes like blobs and clouds are filtered from the palette. High contrast on a dark background with no flow lines creates a mosaic of sharp-edged fragments.
+
+**botanical** — Boosts organic shapes (tendril, cloudForm, blob, crescent, rose, inkSplat) for a natural, garden-like feel. Earth palette on a light radial background with heavy flow lines (3×) creates flowing, vine-like compositions.
 
-The `SacredColorScheme` class derives three harmonious palettes from the hash:
+**stipple-portrait** — Extremely dense (grid 9) with very small shapes (5–120px) and a steep size power curve (2.8) producing many tiny dots. Monochrome palette with stipple and hatched styles creates a pointillist texture. No flow lines or hero shape.
 
-| Palette | Method | Purpose |
-|---------|--------|---------|
-| Base | `color-scheme` lib, hue = seed % 360, hash-driven scheme type | Primary shape colors |
-| Complementary | hue = seed + 180°, contrasting variation | Contrast accents |
-| Triadic | hue = seed + 120° | Additional variety |
+**celestial** — Boosts sacred geometry and cosmic shapes (crescent, geodesicDome, mandala, flowerOfLife, spirograph, fibonacciSpiral). Neon palette on dark background with heavy glow (2.5×) and deep layering (5 layers) creates a starfield-like composition with luminous geometric forms.
 
-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.
+## 3. Color Scheme
+
+Color generation uses the `color-scheme` library seeded from the hash, then applies archetype-specific palette modes.
 
 ### Palette Modes
 
-The archetype's `paletteMode` reshapes the color palette to match the visual personality:
+| Mode | Description |
+| ---- | ----------- |
+| harmonious | Full palette from the scheme — the default |
+| monochrome | Single hue, varying lightness |
+| duotone | Two colors only |
+| neon | High saturation on dark backgrounds |
+| pastel-light | Soft pastels on light backgrounds |
+| earth | Muted warm naturals |
+| high-contrast | Black + white + one accent color |
+
+### Color Hierarchy
+
+After generating the raw palette, colors are organized into a **hierarchy** with weighted selection:
+
+- **Dominant (60%)** — the most-used color, selected as the palette entry closest to the average hue
+- **Secondary (25%)** — the color most distant from the dominant
+- **Accent (15%)** — a remaining color for visual punctuation
+
+`pickHierarchyColor(hierarchy, rng)` rolls against these weights so compositions naturally converge on a dominant tone without being monotonous.
 
-| 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 |
+### HSL Jitter
 
-Each mode also provides matching background colors (e.g., neon gets near-black backgrounds, pastel-light gets warm off-whites).
+Color variation uses **HSL-space jitter** (`jitterColorHSL`) instead of the old RGB approach. This produces perceptually uniform shifts — a ±10° hue rotation and ±8% saturation/lightness shift feels natural, whereas the equivalent RGB jitter could accidentally desaturate or muddy colors.
+
+### Positional Color
+
+Shapes receive color based on their position relative to the canvas center:
+- **Center (< 35% radius):** biased toward the dominant color
+- **Middle (35–70%):** weighted random from the full hierarchy
+- **Edges (> 70%):** biased toward secondary and accent colors
+
+This creates a natural color gradient across the composition without explicit gradient code.
 
 ### Temperature Contrast
 
-The hash deterministically selects a **temperature mode** that creates warm/cool tension across the image:
+The scheme detects whether the background leans warm or cool, then shifts foreground shapes toward the opposite temperature. This ensures shapes always "pop" against their background.
+
+### Contrast Enforcement
+
+Every shape color is checked against the background luminance. If the contrast ratio is too low, the color is lightened or darkened to ensure visibility.
+
+## 4. Shape Affinity System
+
+Not all shapes look equally good at all sizes or in all combinations. The affinity system replaces naive random shape selection with intentional curation.
+
+### Shape Inventory
+
+The system includes 40+ shapes across 4 categories:
+
+| Category | Shapes |
+| -------- | ------ |
+| Basic (9) | circle, square, triangle, hexagon, star, jacked-star, heart, diamond, cube |
+| Complex (7) | platonicSolid, fibonacciSpiral, islamicPattern, celticKnot, merkaba, mandala, fractal |
+| Sacred (8) | flowerOfLife, treeOfLife, metatronsCube, sriYantra, seedOfLife, vesicaPiscis, torus, eggOfLife |
+| Procedural (18) | blob, ngon, lissajous, superellipse, spirograph, waveRing, rose, shardField, voronoiCell, crescent, tendril, cloudForm, inkSplat, geodesicDome, penroseTile, reuleauxTriangle, dotCluster, crosshatchPatch |
+
+### Quality Tiers
+
+Each shape has a profile with:
 
-| 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 |
+| Field | Purpose |
+| ----- | ------- |
+| `tier` (1–3) | Visual quality rating. Tier 1 shapes look good at any size; Tier 3 shapes need specific conditions |
+| `minSizeFraction` / `maxSizeFraction` | Size bounds as fraction of `maxShapeSize` — prevents shapes from being drawn at sizes where they look bad |
+| `affinities` | List of shapes this one composes well with |
+| `category` | basic, complex, sacred, or procedural |
+| `heroCandidate` | Whether the shape works as a dominant focal element |
+| `bestStyles` | Render styles that suit this shape (e.g., sacred geometry looks best as stroke-only) |
 
-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.
+### Shape Palette Construction
 
-### Hash-Driven Color Variation
+`buildShapePalette(rng, shapeNames, archetypeName)` builds a curated set:
 
-The hash deterministically selects both a **scheme type** and a **color variation**, producing dramatically different palettes from the same hue:
+1. **Seed selection:** Pick a Tier 1 hero-candidate shape as the seed
+2. **Primary (5 shapes):** The seed + its direct affinities (Tier 1–2 only)
+3. **Supporting (6 shapes):** Affinities-of-affinities + same-category Tier 1–2 shapes
+4. **Accents (3 shapes):** Tier 1–2 shapes from *other* categories for contrast
 
-| Variation | Character |
-|-----------|-----------|
-| `soft` | Muted, gentle tones |
-| `hard` | High saturation, vivid |
-| `pastel` | Light, airy |
-| `light` | Bright, open |
-| `pale` | Washed out, ethereal |
-| `default` | Balanced, neutral |
+Archetype-specific overrides apply:
+- `geometric-precision` removes organic/procedural shapes from primary
+- `organic-flow` boosts blobs and wave rings
+- `shattered-glass` boosts angular shapes (shardField, voronoiCell, penroseTile), removes blobs/clouds
+- `botanical` boosts organic shapes (tendril, cloudForm, crescent, rose, inkSplat)
+- `stipple-portrait` boosts dot-friendly shapes (dotCluster, circle, crosshatchPatch)
+- `celestial` boosts sacred/cosmic shapes (crescent, geodesicDome, mandala, flowerOfLife)
 
-Scheme types also vary: `analogic`, `mono`, `contrast`, `triade`, `tetrade`. The complementary palette uses a contrasting variation (e.g., if base is `soft`, complementary uses `hard`) to create intentional color tension.
+### Palette-Driven Selection
 
-### Color Utilities
+During rendering, `pickShapeFromPalette(palette, rng, sizeFraction)` selects shapes with weighted probability:
+- **Primary: ~60%**, Supporting: ~30%, Accent: ~10%
+- Shapes whose size constraints don't match the current `sizeFraction` are filtered out before selection
 
-- **`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
+### Affinity-Aware Styling
 
-## 4. Background
+`pickStyleForShape(shapeName, layerStyle, rng)` gives each shape a 70% chance of using one of its `bestStyles` instead of the layer's default style. This means sacred geometry naturally renders as stroke-only while blobs naturally render as watercolor.
 
-The archetype's `backgroundStyle` selects one of 7 rendering modes:
+## 5. Background Rendering
+
+### Base Background
+
+The archetype's `backgroundStyle` selects one of 7 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 |
+| ----- | ----------- |
+| radial-dark | Dark radial gradient from center outward (default) |
+| radial-light | Light center (#f0ece4) fading to the palette background |
+| linear-horizontal | Left-to-right gradient |
+| linear-diagonal | Corner-to-corner gradient with midpoint return |
+| solid-dark | Flat dark fill |
+| solid-light | Flat off-white (#f5f2eb) |
+| multi-stop | 3–4 color gradient using palette colors |
 
-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.
+### Gradient Mesh Overlay
 
-### Layered Background
+After the base background, 3–4 radial color control points are placed at random positions using `soft-light` compositing. Each point uses a hierarchy color at very low opacity (8–14%). This adds subtle color variation and depth to what would otherwise be a flat or simple gradient background.
 
-After the gradient, a second pass adds visual texture to the background:
+### Layered Background Shapes
 
-- **Faint shapes** — 3-7 large, very low-opacity circles (3-8% alpha) drawn with `soft-light` blending, creating subtle color pools
-- **Concentric rings** — 2-4 rings emanating from center at ~2-5% opacity, adding structure without competing with foreground shapes
+Large, nearly-transparent shapes (3–7) are drawn in `soft-light` mode at 3–8% opacity. The shape type is archetype-coherent: geometric archetypes (`geometric-precision`, `op-art`) use rectangles; all others use circles. Subtle concentric rings radiate from the center at ~2–5% opacity to add structure.
 
-This prevents the background from feeling flat and gives the image depth before the main shape layers begin.
+### Background Pattern Layer
 
-## 5. Composition Modes
+~60% of images receive a subtle background pattern drawn in `soft-light` at 2–6% opacity, simulating textured paper:
 
-The hash deterministically selects one of five composition strategies that control how shapes are positioned on the canvas:
+| Pattern | Description |
+| ------- | ----------- |
+| Dot grid (⅓ chance) | Evenly spaced tiny dots across the canvas |
+| Diagonal lines (⅓ chance) | Parallel diagonal lines at 0.5px width |
+| Hexagonal tessellation (⅓ chance) | Honeycomb grid of tiny hexagons, stroke-only |
 
-| Mode | Description |
-|------|-------------|
-| **Radial** | Shapes emanate from the center with distance following a power curve (denser near center) |
-| **Flow-field** | Random positions; shapes are rotated to align with a hash-derived vector field |
-| **Spiral** | Shapes follow a multi-turn spiral path outward from center with slight scatter |
-| **Grid-subdivision** | Canvas is divided into cells; shapes are placed randomly within cells |
-| **Clustered** | 3-5 cluster centers are generated; shapes scatter around the nearest cluster |
+The pattern spacing scales with canvas size (1.5–3% of the shorter dimension). This adds tactile depth without competing with foreground shapes.
 
-Each mode produces fundamentally different visual character from the same shape set.
+### Background Luminance
 
-### Symmetry Modes
+The average luminance of the two background colors is computed and stored. This value drives contrast enforcement for all foreground shapes — ensuring they remain visible regardless of background brightness.
 
-~25% of hashes trigger a symmetry mode that mirrors the rendered content:
+## 6. Composition & Symmetry
 
-| 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 |
+### Composition Modes
 
-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.
+Each image uses one of 5 composition strategies for shape placement:
 
-## 6. Focal Points & Negative Space
+| Mode | Behavior |
+| ---- | -------- |
+| radial | Shapes cluster around center with power-curve falloff |
+| spiral | Shapes follow a multi-turn spiral from center outward |
+| grid-subdivision | Canvas divided into 3–5 cells; shapes placed within random cells |
+| clustered | 3–5 cluster centers; shapes scatter around the nearest cluster |
+| flow-field | Uniform random placement (rotation driven by flow field) |
 
-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%).
+### Symmetry
 
-### Hero Shape
+~25% of hashes trigger symmetry mirroring, applied after all shapes and flow lines are drawn:
+- **bilateral-x (10%):** Left half mirrored to right
+- **bilateral-y (10%):** Top half mirrored to bottom
+- **quad (5%):** Both axes mirrored
 
-~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
+Symmetry is applied by drawing the canvas image onto itself with `scale(-1, 1)` or `scale(1, -1)` transforms.
 
-### Void Zones (Negative Space)
+## 7. Focal Points & Void Zones
 
-1-2 void zones are generated at random positions. Shapes that land inside a void zone have an 85% chance of being skipped, creating deliberate areas of breathing room. A few shapes bleed through (15%) to keep the edges organic rather than hard-cut.
+1–2 **focal points** are placed with 70% bias toward rule-of-thirds intersections (the remaining 30% are placed randomly within the central 60% of the canvas). Each focal point has a `strength` (0.3–0.7) that pulls nearby shapes toward it via `applyFocalBias`.
 
-### Density Awareness
+1–2 **void zones** are placed randomly. Shapes landing inside a void zone have an 85% chance of being skipped, creating breathing room in the composition.
 
-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.
+## 8. Hero Shape
 
-## 7. Shape Layers
+When the archetype enables `heroShape` and the RNG roll passes (60% chance), a dominant focal element is drawn at the first focal point:
 
-The image is built in N layers (default: 4). Each layer has its own characteristics:
+- Shape is selected from palette hero candidates (Tier 1, `heroCandidate: true`)
+- Size is 80–130% of `adjustedMaxSize`
+- Style is chosen from the shape's `bestStyles` via its affinity profile
+- Fill uses the dominant hierarchy color; stroke uses the accent
+- Glow radius is 12–32px (scaled)
+- The hero's position and size are stored for the **hero avoidance field**
 
-### Layer Properties
+## 9. Shape Layers
 
-| Property | Behavior |
-|----------|----------|
-| Opacity | Decays gently per layer (0.7 → 0.58 → 0.46 → 0.34), minimum 0.15 |
-| Size scale | Later layers use progressively smaller shapes (×0.85, ×0.70, ×0.55) |
-| 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 (60% from archetype preferences, 40% random); 30% of shapes pick their own |
-| Atmospheric depth | Later layers desaturate colors by up to 30%, simulating distance |
+The core of the image: `layers` passes (archetype-controlled, typically 2–5), each drawing `gridSize² × 1.5` shapes plus up to 30% random extra.
 
-### Blend Modes (Per-Layer Compositing)
+### Per-Layer Setup
 
-Each layer deterministically selects a `globalCompositeOperation` from: `source-over`, `screen`, `multiply`, `overlay`, `soft-light`, `color-dodge`, `color-burn`, `lighter`. There's a 40% chance of `source-over` (default) to keep some images clean, while the other modes create rich color interactions where shapes overlap — the kind of depth that makes output feel painterly rather than stacked.
+- **Blend mode:** Random compositing mode (`source-over`, `multiply`, `screen`, `overlay`, `soft-light`, etc.)
+- **Render style bias:** 60% chance of using an archetype-preferred style; 40% random
+- **Opacity:** Decreases per layer (`baseOpacity - layer × opacityReduction`, floor 0.15)
+- **Size scale:** Decreases 15% per layer (later layers = smaller shapes)
+- **Atmospheric desaturation:** Later layers are progressively desaturated (up to 30%) to simulate depth
+- **Depth-of-field:** Later layers get thinner strokes (down to 40% of base width) and reduced contrast (up to 20% opacity reduction), simulating camera focus falloff
 
-### Render Styles (Per-Shape Treatment)
+### Per-Shape Pipeline
 
-Instead of always `fill()` + `stroke()`, each shape gets a rendering treatment:
+For each shape in a layer:
 
-| Style | Description | Probability |
-|-------|-------------|-------------|
-| `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% |
+1. **Position:** Composition mode generates a candidate position, then `applyFocalBias` pulls it toward the nearest focal point
+2. **Void check:** 85% skip chance if inside a void zone
+3. **Density check:** If local density exceeds 15% of `shapesPerLayer`, 60% skip chance
+4. **Size:** Power-curve distribution controlled by `archetype.sizePower` — higher values produce more small shapes
+5. **Shape selection:** `pickShapeFromPalette` with size-constraint filtering
+6. **Rotation:** Flow-field angle in flow-field mode (±15° jitter); random otherwise
+7. **Hero avoidance:** Shapes within 1.5× the hero's size orient toward it (rotation blended 40% toward the angle-to-hero)
+8. **Color:** Positional color from hierarchy + HSL jitter, with atmospheric desaturation and temperature contrast applied
+9. **Contrast enforcement:** Fill and stroke colors checked against background luminance
+10. **Styling:** Affinity-aware render style, optional glow (sacred shapes 45% base chance × archetype multiplier), optional radial gradient fill (30% chance)
+11. **Organic edges:** 15% of `fill-and-stroke` shapes are promoted to `watercolor` style
+12. **Light direction:** Non-glowing shapes get a subtle shadow offset along the consistent light angle
 
-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.
+### 5a. Tangent Placement
 
-### Atmospheric Depth (Per-Layer Desaturation)
+~25% of shapes are nudged toward the nearest previously-placed shape so their edges "kiss." The algorithm finds the nearest shape, computes the target distance (sum of half-sizes), and repositions the current shape along the angle between them. This creates organic clustering where shapes feel intentionally arranged rather than randomly scattered.
 
-Later layers progressively desaturate their colors (0% on layer 0, up to 30% on the final layer). This simulates atmospheric perspective — distant shapes appear more muted, creating a sense of foreground/background depth.
+### 5b. Shape Mirroring
 
-### Shape Selection (Layer-Weighted)
+Basic shapes (circle, triangle, square, hexagon, star, diamond, crescent, penroseTile, reuleauxTriangle) that are larger than 20% of max size have a ~40% chance of receiving a mirrored reflection. Four mirror axes are available:
 
-Shapes are divided into four categories with weights that shift across layers:
+| Axis | Probability | Effect |
+| ---- | ----------- | ------ |
+| horizontal | 15% | Reflected below with inverted rotation |
+| vertical | 12% | Reflected to the right with 180° rotation offset |
+| diagonal | 8% | Reflected along 45° axis with 90° rotation offset |
+| radial-4 | 5% | Four copies at 90° intervals around the center |
 
-| 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 |
+The mirror copy is drawn at 70% opacity and 95% size (decreasing for radial-4), creating a subtle symmetry effect without perfect duplication.
 
-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.
+### 5c. Size Echo
 
-### Contrast Enforcement
+~20% of shapes larger than half `adjustedMaxSize` spawn 2–3 trailing copies along a random direction. Each echo is progressively smaller (30% → 22% → 14% of parent size) and more transparent, creating a motion-trail effect.
 
-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:
+### 5d. Recursive Nesting
 
-- **Light backgrounds** — foreground colors are darkened and saturated
-- **Dark backgrounds** — foreground colors are lightened and saturated
+~15% of shapes larger than 40% of `adjustedMaxSize` receive 1–3 inner shapes. Inner shapes are selected from the palette via `pickShapeFromPalette` at the nested size fraction, and styled with their own affinity-aware render style.
 
-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).
+### 5e. Shape Constellations
 
-### Size Distribution
+~12% of shapes larger than 35% of `adjustedMaxSize` trigger a **constellation** — a pre-composed group of shapes placed as a unit. The entire group is rotated by a random angle for variety. Five constellation types are available:
 
-Shape sizes follow a **power distribution** (`Math.pow(rng(), 1.8)`) — producing many small shapes and few large ones, which creates natural visual hierarchy.
+| Constellation | Description |
+| ------------- | ----------- |
+| flanked-triangle | Central triangle with two smaller circles on either side |
+| hexagon-ring | 5–6 hexagons arranged in a ring |
+| spiral-dots | 7–11 circles spiraling outward with decreasing size |
+| diamond-cluster | 4 diamonds in a cardinal arrangement with progressive rotation |
+| crescent-pair | Two crescents facing each other |
 
-### Styling Per Shape
+Each member shape uses hierarchy colors with HSL jitter and affinity-aware render styles. Members that fall outside the canvas bounds are skipped.
 
-Each shape receives:
+## 10. Render Styles
 
-- **Semi-transparent fill** — alpha between 0.2-0.7, creating watercolor-style blending where shapes overlap
-- **Color jitter** — ±8% RGB variation on fills, ±5% on strokes, so no two shapes using the "same" palette color are pixel-identical
-- **Positional color** — fill color is biased by the shape's canvas position, creating smooth color flow
-- **Glow effect** — 45% of sacred shapes and 20% of others get a `shadowBlur` glow (8-28px scaled), with glow color at 60% opacity
-- **Gradient fill** — ~30% of shapes get a radial gradient between two jittered palette colors instead of a flat fill
-- **Variable stroke width** — 0.5-2.5px scaled to canvas size
+Each shape is drawn using one of 14 render styles:
 
-### Recursive Nesting
+| Style | Description |
+| ----- | ----------- |
+| fill-and-stroke | Standard fill + outline (default) |
+| fill-only | Solid fill, no outline |
+| stroke-only | Ghost fill at 30% opacity + full outline |
+| double-stroke | Fill + thick outer stroke at 50% opacity + thin inner stroke in fill color |
+| dashed | Fill + dashed outline (dash = 5% of size, gap = 3%) |
+| watercolor | Multi-pass: base wash (scaled up 8%), radial-bleed offset washes, edge darkening via inner lighter fill, delicate thin stroke |
+| hatched | 30% opacity fill + clipped cross-hatch lines (parallel + optional perpendicular) + 50% opacity outline |
+| incomplete | 25% opacity fill + long-dash stroke simulating a partially drawn outline (60–85% completeness) |
+| stipple | Ghost fill at 15% + clipped dot grid with jittered positions and variable dot sizes |
+| stencil | Negative-space cutout: fills a bounding rectangle, then erases the shape via destination-out compositing |
+| noise-grain | 25% base tint + clipped procedural noise (random black/white dots at 15–50% opacity, variable sizes) |
+| wood-grain | 20% base tint + clipped parallel wavy lines at a random angle, simulating wood texture |
+| marble-vein | 35% soft base + clipped branching vein lines that drift and fork, simulating marble stone |
+| fabric-weave | 15% ghost base + clipped interlocking horizontal and vertical thread lines at alternating opacities |
 
-~15% of shapes larger than 40% of max size spawn 1-3 inner shapes:
-- Inner shapes are drawn at the parent's position with small random offsets
-- They use more complex/sacred shape types (layer ratio biased +0.3)
-- Sized at 15-40% of the parent
-- More transparent than the parent layer
+### Texture Fill Details
 
-## 8. Flow-Line Pass (Tapered Brush Strokes)
+The 4 new texture fills (noise-grain, wood-grain, marble-vein, fabric-weave) all work by:
+1. Drawing a low-opacity base fill to tint the shape
+2. Clipping to the shape boundary via `ctx.clip()`
+3. Drawing the procedural texture pattern within the clipped region
+4. Adding a subtle outline stroke on top
 
-6-16 flowing curves are drawn across the canvas, following the hash-derived vector field:
+**noise-grain** scatters random-sized dots (black or white) across the shape at variable opacity, creating a film-grain or sandpaper texture. Dot spacing scales with shape size.
 
-- Each line starts at a random position and takes 30-70 steps
-- At each step, direction is determined by the flow field angle at that position plus slight random wobble
-- Lines stop if they leave the canvas bounds
-- **Tapered width** — each line starts at 1-4px and tapers to 20% of its starting width by the end, simulating a brush stroke that lifts off the canvas
-- **Tapered opacity** — alpha also decays along the stroke, creating natural fade-out
-- Individual segments are drawn with `lineCap: "round"` for smooth joins
+**wood-grain** draws parallel wavy lines at a random angle. The wave frequency (3–8 cycles) and amplitude (1–4% of size) create organic undulation. Line spacing is ~3.5% of shape size.
 
-The flow field is defined by:
-```
-angle(x, y) = baseAngle + sin(x/w × freq × 2π) × π/2 + cos(y/h × freq × 2π) × π/2
-```
+**marble-vein** draws 2–4 main veins that drift randomly downward, with ~20% chance per step of spawning a thinner branch vein. This creates the characteristic forking pattern of natural marble.
+
+**fabric-weave** draws horizontal threads at full spacing, then vertical threads at half-spacing offsets, creating an over-under weave pattern. The two thread directions use different opacities (55% vs 45%) and colors (stroke vs fill) for visual distinction.
+
+### Watercolor Detail
+
+The watercolor style simulates wet media through 4 passes:
+1. **Base wash:** Shape drawn at 108% scale, 15% opacity — soft bleed beyond the boundary
+2. **Offset washes:** 4–5 passes with radial displacement (random angle, up to 5% of size) — organic edge irregularity
+3. **Edge darkening:** Shape drawn at 85–93% scale with lightened fill — simulates pigment pooling at boundaries where the inner area dries lighter
+4. **Delicate stroke:** Thin outline (60% of normal width) at 25% opacity
+
+## 11. Flow Lines
+
+Flow lines follow a sinusoidal vector field defined by `flowAngle(x, y)`. The archetype's `flowLineMultiplier` controls count (0× = none, up to 4× = heavy).
+
+Each flow line:
+- Starts at a random position
+- Takes 30–70 steps along the flow field (±0.3 radians jitter per step)
+- **Variable color:** Interpolates between two hierarchy colors along the stroke length
+- **Pressure simulation:** Line width oscillates sinusoidally (frequency 2–6 cycles, amplitude ±40%) to simulate pen pressure
+- **Taper:** Width and opacity decrease toward the end (80% taper over the stroke length)
+- **Branching:** ~12% chance per step (between steps 5 and N-10) to spawn a child stroke at ±0.3–0.8 radians, 40% width, 5–15 steps, 60% parent opacity
+
+## 12. Post-Processing
+
+After all shapes, flow lines, and symmetry mirroring:
+
+### Noise Texture
+
+Deterministic noise (separate RNG seeded from hash + salt 777) scatters single-pixel dots across the canvas. Density scales with canvas area (~1 dot per 800px²). Each dot is black or white at 1–4% opacity, adding subtle film grain.
+
+### Vignette
+
+A radial gradient darkens the edges: transparent at center, ramping to 25–45% black at the corners. This draws the eye inward toward the focal points.
+
+### Organic Connecting Curves
+
+Quadratic Bézier curves connect random pairs of placed shapes. The control point is offset perpendicular to the line between shapes by up to 40% of their distance, creating organic arcs. Count scales with canvas area (~8 per megapixel). Drawn at 6–16% opacity using hierarchy colors.
+
+### Color Grading
+
+A `soft-light` overlay in a single hue (random, 40% saturation, 50% lightness) at low intensity (grade intensity × 25% opacity). This unifies the image's color temperature — like applying a photo filter.
+
+### Chromatic Aberration
+
+Only for `neon-glow`, `cosmic`, and `ethereal` archetypes. The canvas is drawn onto itself with a small horizontal offset (±2px scaled) using `screen` compositing at 3% opacity. This creates a subtle RGB fringing effect at high-contrast edges.
+
+### Bloom
 
-## 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:
-
-- Density: ~1 dot per 800 square pixels
-- Each dot is either black or white (50/50)
-- Very low opacity (1-4%)
-- Creates subtle film-grain texture that adds organic depth
-
-## 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:
-
-- Number of curves scales with canvas area (~8 per megapixel)
-- Each curve connects two shapes that were drawn near each other in sequence
-- Control points are offset perpendicular to the connecting line with random bulge
-- Drawn at low opacity (6-16%) with palette colors at 30% alpha
-
-## Shape Implementations
-
-### Basic Shapes
-Standard geometric primitives drawn as canvas paths (beginPath → moveTo/lineTo/arc → closePath). The draw pipeline calls `fill()` and `stroke()` after the path is defined.
-
-### Complex Shapes
-More intricate geometry including:
-- **Platonic solids** — 2D projections with all edges drawn between vertices
-- **Fibonacci spiral** — iterative arc segments following the golden ratio
-- **Islamic pattern** — 8-pointed star grid at intersections
-- **Celtic knot** — bezier over/under weaving pattern
-- **Mandala** — concentric circles with radial lines
-- **Fractal tree** — recursive branching at ±30° with 0.7× length decay
-
-### Sacred Geometry
-Mathematically precise sacred geometry patterns:
-- **Flower of Life** — 7 overlapping circles in hexagonal arrangement
-- **Tree of Life** — 10 Sephirot nodes with connecting paths
-- **Metatron's Cube** — 13 vertices (center + inner/outer hexagons) fully connected
-- **Sri Yantra** — 9 interlocking triangles at two radii
-- **Seed of Life** — 7 circles (same as Flower of Life, different scale)
-- **Vesica Piscis** — two overlapping circles
-- **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`:
-
-| Parameter | Default | Effect |
-|-----------|---------|--------|
-| `width` | 2048 | Canvas width in pixels |
-| `height` | 2048 | Canvas height in pixels |
-| `gridSize` | 5 | Base shape count = gridSize² × 1.5 |
-| `layers` | 4 | Number of rendering layers |
-| `minShapeSize` | 30 | Minimum shape size (scaled to canvas) |
-| `maxShapeSize` | 400 | Maximum shape size (scaled to canvas) |
-| `baseOpacity` | 0.7 | First layer opacity |
-| `opacityReduction` | 0.12 | Opacity decay per layer |
-| `shapesPerLayer` | auto | Override auto-calculated shape count |
+Only for `neon-glow` and `cosmic` archetypes. The canvas is redrawn with `shadowBlur` at 30px (scaled) and white shadow color, composited via `screen` at 8% opacity. This creates a soft glow around bright areas.