git-hash-art 0.12.0 → 0.14.0

package/src/lib/render.ts

@@ -479,6 +479,15 @@ export function renderHashArt(
   config: Partial<GenerationConfig> = {},
 ): void {
   const finalConfig: GenerationConfig = { ...DEFAULT_CONFIG, ...config };
+  const _dt = finalConfig._debugTiming;
+  const _t = _dt ? () => performance.now() : undefined;
+  let _p = _t ? _t() : 0;
+  function _mark(name: string) {
+    if (!_dt || !_t) return;
+    const now = _t();
+    _dt.phases[name] = (now - _p);
+    _p = now;
+  }
 
   const rng = createRng(seedFromHash(gitHash));
 
@@ -511,7 +520,32 @@ export function renderHashArt(
   const colorHierarchy = buildColorHierarchy(colors, rng);
 
   // ── 0c. Shape palette — curated shapes that work well together ──
-  const shapeNames = Object.keys(shapes);
+  // Merge custom shapes into a combined registry
+  const customShapeNames: string[] = [];
+  type DrawFunction = (ctx: CanvasRenderingContext2D, size: number, config?: any) => void;
+  let activeShapes: Record<string, DrawFunction> | undefined;
+  if (finalConfig.customShapes && Object.keys(finalConfig.customShapes).length > 0) {
+    activeShapes = { ...shapes };
+    for (const [name, def] of Object.entries(finalConfig.customShapes)) {
+      // Wrap CustomDrawFunction (ctx, size, rng) into DrawFunction (ctx, size, config?)
+      const customDraw = def.draw;
+      activeShapes[name] = (ctx, size, config?) => {
+        customDraw(ctx, size, config?.rng ?? Math.random);
+      };
+      // Register profile for affinity system (inlined to avoid ESM interop issues)
+      SHAPE_PROFILES[name] = {
+        tier: def.profile?.tier ?? 2,
+        minSizeFraction: def.profile?.minSizeFraction ?? 0.05,
+        maxSizeFraction: def.profile?.maxSizeFraction ?? 1.0,
+        affinities: def.profile?.affinities ?? ["circle", "square"],
+        category: "procedural",
+        heroCandidate: def.profile?.heroCandidate ?? false,
+        bestStyles: def.profile?.bestStyles ?? ["fill-and-stroke", "watercolor"],
+      };
+      customShapeNames.push(name);
+    }
+  }
+  const shapeNames = Object.keys(activeShapes ?? shapes);
   const shapePalette = buildShapePalette(rng, shapeNames, archetype.name);
 
   // ── 0d. Color grading — unified tone for the whole image ───────
@@ -530,13 +564,16 @@ export function renderHashArt(
   const cx = width / 2;
   const cy = height / 2;
 
+  _mark("0_setup");
+
   // ── 1. Background ──────────────────────────────────────────────
   const bgRadius = Math.hypot(cx, cy);
   drawBackground(ctx, archetype.backgroundStyle, bgStart, bgEnd, width, height, cx, cy, bgRadius, rng, colors);
 
   // Gradient mesh overlay — 3-4 color control points for richer backgrounds
+  // Use source-over instead of soft-light for cheaper compositing
   const meshPoints = 3 + Math.floor(rng() * 2);
-  ctx.globalCompositeOperation = "soft-light";
+  ctx.globalAlpha = 1;
   for (let i = 0; i < meshPoints; i++) {
     const mx = rng() * width;
     const my = rng() * height;
@@ -545,104 +582,114 @@ export function renderHashArt(
     const grad = ctx.createRadialGradient(mx, my, 0, mx, my, mRadius);
     grad.addColorStop(0, hexWithAlpha(mColor, 0.08 + rng() * 0.06));
     grad.addColorStop(1, "rgba(0,0,0,0)");
-    ctx.globalAlpha = 1;
     ctx.fillStyle = grad;
-    ctx.fillRect(0, 0, width, height);
+    // Clip to gradient bounding box — avoids blending transparent pixels
+    const gx = Math.max(0, mx - mRadius);
+    const gy = Math.max(0, my - mRadius);
+    const gw = Math.min(width, mx + mRadius) - gx;
+    const gh = Math.min(height, my + mRadius) - gy;
+    ctx.fillRect(gx, gy, gw, gh);
   }
-  ctx.globalCompositeOperation = "source-over";
 
   // Compute average background luminance for contrast enforcement
   const bgLum = (luminance(bgStart) + luminance(bgEnd)) / 2;
 
   // ── 1b. Layered background — archetype-coherent shapes ─────────
+  // Use source-over with pre-multiplied alpha instead of soft-light
+  // for much cheaper compositing (soft-light requires per-pixel blend)
   const bgShapeCount = 3 + Math.floor(rng() * 4);
-  ctx.globalCompositeOperation = "soft-light";
   for (let i = 0; i < bgShapeCount; i++) {
     const bx = rng() * width;
     const by = rng() * height;
     const bSize = (width * 0.3 + rng() * width * 0.5);
     const bColor = pickHierarchyColor(colorHierarchy, rng);
-    ctx.globalAlpha = 0.03 + rng() * 0.05;
+    ctx.globalAlpha = (0.03 + rng() * 0.05) * 0.5; // halved to compensate for source-over vs soft-light
     ctx.fillStyle = hexWithAlpha(bColor, 0.15);
     ctx.beginPath();
     // Use archetype-appropriate background shapes
     if (archetype.name === "geometric-precision" || archetype.name === "op-art") {
-      // Rectangular shapes for geometric archetypes
       ctx.rect(bx - bSize / 2, by - bSize / 2, bSize, bSize * (0.5 + rng() * 0.5));
     } else {
       ctx.arc(bx, by, bSize / 2, 0, Math.PI * 2);
     }
     ctx.fill();
   }
-  // Subtle concentric rings from center
+  // Subtle concentric rings from center — batched into single stroke
   const ringCount = 2 + Math.floor(rng() * 3);
   ctx.globalAlpha = 0.02 + rng() * 0.03;
   ctx.strokeStyle = hexWithAlpha(colorHierarchy.dominant, 0.1);
   ctx.lineWidth = 1 * scaleFactor;
+  ctx.beginPath();
   for (let i = 1; i <= ringCount; i++) {
     const r = (Math.min(width, height) * 0.15) * i;
-    ctx.beginPath();
+    ctx.moveTo(cx + r, cy);
     ctx.arc(cx, cy, r, 0, Math.PI * 2);
-    ctx.stroke();
   }
-  ctx.globalCompositeOperation = "source-over";
+  ctx.stroke();
 
   // ── 1c. Background pattern layer — subtle textured paper ───────
   const bgPatternRoll = rng();
   if (bgPatternRoll < 0.6) {
     ctx.save();
-    ctx.globalCompositeOperation = "soft-light";
     const patternOpacity = 0.02 + rng() * 0.04;
     const patternColor = hexWithAlpha(colorHierarchy.dominant, 0.15);
 
     if (bgPatternRoll < 0.2) {
-      // Dot grid — batched into a single path
-      const dotSpacing = Math.max(8, Math.min(width, height) * (0.015 + rng() * 0.015));
-      const dotR = dotSpacing * 0.08;
+      // Dot grid — use fillRect instead of arcs (much cheaper, no path building)
+      const dotSpacing = Math.max(12, Math.min(width, height) * (0.015 + rng() * 0.015));
+      const dotDiam = Math.max(1, Math.round(dotSpacing * 0.16));
       ctx.globalAlpha = patternOpacity;
       ctx.fillStyle = patternColor;
-      ctx.beginPath();
-      for (let px = 0; px < width; px += dotSpacing) {
-        for (let py = 0; py < height; py += dotSpacing) {
-          ctx.moveTo(px + dotR, py);
-          ctx.arc(px, py, dotR, 0, Math.PI * 2);
+      let dotCount = 0;
+      for (let px = 0; px < width && dotCount < 2000; px += dotSpacing) {
+        for (let py = 0; py < height && dotCount < 2000; py += dotSpacing) {
+          ctx.fillRect(px, py, dotDiam, dotDiam);
+          dotCount++;
         }
       }
-      ctx.fill();
     } else if (bgPatternRoll < 0.4) {
-      // Diagonal lines — batched into a single path
-      const lineSpacing = Math.max(6, Math.min(width, height) * (0.02 + rng() * 0.02));
+      // Diagonal lines — batched into a single path, capped at 300 lines
+      const lineSpacing = Math.max(10, Math.min(width, height) * (0.02 + rng() * 0.02));
       ctx.globalAlpha = patternOpacity;
       ctx.strokeStyle = patternColor;
       ctx.lineWidth = 0.5 * scaleFactor;
       const diag = Math.hypot(width, height);
       ctx.beginPath();
-      for (let d = -diag; d < diag; d += lineSpacing) {
+      let lineCount = 0;
+      for (let d = -diag; d < diag && lineCount < 300; d += lineSpacing) {
         ctx.moveTo(d, 0);
         ctx.lineTo(d + height, height);
+        lineCount++;
       }
       ctx.stroke();
     } else {
-      // Tessellation — hexagonal grid, batched into a single path
-      const tessSize = Math.max(10, Math.min(width, height) * (0.025 + rng() * 0.02));
+      // Tessellation — hexagonal grid, capped at 500 hexagons
+      const tessSize = Math.max(15, Math.min(width, height) * (0.025 + rng() * 0.02));
       const tessH = tessSize * Math.sqrt(3);
       ctx.globalAlpha = patternOpacity * 0.7;
       ctx.strokeStyle = patternColor;
       ctx.lineWidth = 0.4 * scaleFactor;
+      // Pre-compute hex vertex offsets (avoid trig per vertex)
+      const hexVx: number[] = [];
+      const hexVy: number[] = [];
+      for (let s = 0; s < 6; s++) {
+        const angle = (Math.PI / 3) * s - Math.PI / 6;
+        hexVx.push(Math.cos(angle) * tessSize * 0.5);
+        hexVy.push(Math.sin(angle) * tessSize * 0.5);
+      }
       ctx.beginPath();
-      for (let row = 0; row * tessH < height + tessH; row++) {
+      let hexCount = 0;
+      for (let row = 0; row * tessH < height + tessH && hexCount < 500; row++) {
         const offsetX = (row % 2) * tessSize * 0.75;
-        for (let col = 0; col * tessSize * 1.5 < width + tessSize * 1.5; col++) {
+        for (let col = 0; col * tessSize * 1.5 < width + tessSize * 1.5 && hexCount < 500; col++) {
           const hx = col * tessSize * 1.5 + offsetX;
           const hy = row * tessH;
-          for (let s = 0; s < 6; s++) {
-            const angle = (Math.PI / 3) * s - Math.PI / 6;
-            const vx = hx + Math.cos(angle) * tessSize * 0.5;
-            const vy = hy + Math.sin(angle) * tessSize * 0.5;
-            if (s === 0) ctx.moveTo(vx, vy);
-            else ctx.lineTo(vx, vy);
+          ctx.moveTo(hx + hexVx[0], hy + hexVy[0]);
+          for (let s = 1; s < 6; s++) {
+            ctx.lineTo(hx + hexVx[s], hy + hexVy[s]);
           }
           ctx.closePath();
+          hexCount++;
         }
       }
       ctx.stroke();
@@ -651,6 +698,8 @@ export function renderHashArt(
   }
   ctx.globalCompositeOperation = "source-over";
 
+  _mark("1_background");
+
   // ── 2. Composition mode — archetype-aware selection ──────────────
   const compositionMode: CompositionMode = rng() < 0.7
     ? archetype.preferredCompositions[Math.floor(rng() * archetype.preferredCompositions.length)]
@@ -776,6 +825,8 @@ export function renderHashArt(
   }
   ctx.globalAlpha = 1;
 
+  _mark("2_3_composition_focal");
+
   // ── 4. Flow field — simplex noise for organic variation ─────────
   // Create a seeded simplex noise field (unique per hash)
   const noiseFieldRng = createRng(seedFromHash(gitHash, 333));
@@ -847,6 +898,7 @@ export function renderHashArt(
       rng,
       lightAngle,
       scaleFactor,
+      activeShapes,
     });
 
     heroCenter = { x: heroFocal.x, y: heroFocal.y, size: heroSize };
@@ -855,6 +907,8 @@ export function renderHashArt(
   }
 
 
+  _mark("4_flowfield_hero");
+
   // ── 5. Shape layers ────────────────────────────────────────────
   const maxLocalDensity = Math.ceil(shapesPerLayer * 0.15);
 
@@ -1090,6 +1144,7 @@ export function renderHashArt(
         rng,
         lightAngle,
         scaleFactor,
+        activeShapes,
       };
 
       if (shouldMirror) {
@@ -1124,6 +1179,7 @@ export function renderHashArt(
               proportionType: "GOLDEN_RATIO",
               renderStyle: "fill-only",
               rng,
+              activeShapes,
             });
           }
           extrasSpent += glazePasses;
@@ -1158,6 +1214,7 @@ export function renderHashArt(
               proportionType: "GOLDEN_RATIO",
               renderStyle: finalRenderStyle,
               rng,
+              activeShapes,
             });
             shapePositions.push({ x: echoX, y: echoY, size: echoSize, shape });
             spatialGrid.insert({ x: echoX, y: echoY, size: echoSize, shape });
@@ -1209,6 +1266,7 @@ export function renderHashArt(
                 proportionType: "GOLDEN_RATIO",
                 renderStyle: innerStyle,
                 rng,
+                activeShapes,
               },
             );
             extrasSpent += RENDER_STYLE_COST[innerStyle] ?? 1;
@@ -1269,6 +1327,7 @@ export function renderHashArt(
               proportionType: "GOLDEN_RATIO",
               renderStyle: memberStyle,
               rng,
+              activeShapes,
             });
             shapePositions.push({ x: mx, y: my, size: member.size, shape: memberShape });
             spatialGrid.insert({ x: mx, y: my, size: member.size, shape: memberShape });
@@ -1320,6 +1379,7 @@ export function renderHashArt(
               proportionType: "GOLDEN_RATIO",
               renderStyle: finalRenderStyle,
               rng,
+              activeShapes,
             });
             shapePositions.push({ x: rx, y: ry, size: rhythmSize, shape: rhythmShape });
             spatialGrid.insert({ x: rx, y: ry, size: rhythmSize, shape: rhythmShape });
@@ -1337,73 +1397,12 @@ export function renderHashArt(
 
   // Reset blend mode for post-processing passes
   ctx.globalCompositeOperation = "source-over";
+  if (_dt) { _dt.shapeCount = shapePositions.length; _dt.extraCount = extrasSpent; }
+  _mark("5_shape_layers");
 
-  // ── 5g. Layered masking / cutout portals ───────────────────────
-  // ~18% of images get 1-3 portal windows that paint over foreground
-  // with a tinted background wash, creating a "peek through" effect.
-  if (rng() < 0.18 && shapePositions.length > 3) {
-    const portalCount = 1 + Math.floor(rng() * 2);
-    for (let p = 0; p < portalCount; p++) {
-      // Pick a position biased toward placed shapes
-      const sourceShape = shapePositions[Math.floor(rng() * shapePositions.length)];
-      const portalX = sourceShape.x + (rng() - 0.5) * sourceShape.size * 0.5;
-      const portalY = sourceShape.y + (rng() - 0.5) * sourceShape.size * 0.5;
-      const portalSize = adjustedMaxSize * (0.15 + rng() * 0.25);
-
-      // Pick a portal shape from the palette
-      const portalShape = pickShapeFromPalette(shapePalette, rng, portalSize / adjustedMaxSize);
-      const portalRotation = rng() * 360;
-      const portalAlpha = 0.6 + rng() * 0.35;
-
-      ctx.save();
-      ctx.translate(portalX, portalY);
-      ctx.rotate((portalRotation * Math.PI) / 180);
-
-      // Step 1: Clip to the portal shape and fill with background wash
-      ctx.beginPath();
-      shapes[portalShape]?.(ctx, portalSize);
-      ctx.clip();
-
-      // Fill the clipped region with a radial gradient from background colors
-      const portalColor = jitterColorHSL(bgStart, rng, 15, 0.1);
-      const portalGrad = ctx.createRadialGradient(0, 0, 0, 0, 0, portalSize);
-      portalGrad.addColorStop(0, portalColor);
-      portalGrad.addColorStop(1, bgEnd);
-      ctx.globalAlpha = portalAlpha;
-      ctx.fillStyle = portalGrad;
-      ctx.fillRect(-portalSize, -portalSize, portalSize * 2, portalSize * 2);
-
-      // Optional: subtle inner texture — a few tiny dots inside the portal
-      if (rng() < 0.5) {
-        const dotCount = 3 + Math.floor(rng() * 5);
-        ctx.globalAlpha = portalAlpha * 0.3;
-        ctx.fillStyle = hexWithAlpha(pickHierarchyColor(colorHierarchy, rng), 0.2);
-        for (let d = 0; d < dotCount; d++) {
-          const dx = (rng() - 0.5) * portalSize * 1.4;
-          const dy = (rng() - 0.5) * portalSize * 1.4;
-          const dr = (1 + rng() * 3) * scaleFactor;
-          ctx.beginPath();
-          ctx.arc(dx, dy, dr, 0, Math.PI * 2);
-          ctx.fill();
-        }
-      }
-
-      ctx.restore();
-
-      // Step 2: Draw a border ring around the portal (outside the clip)
-      ctx.save();
-      ctx.translate(portalX, portalY);
-      ctx.rotate((portalRotation * Math.PI) / 180);
-      ctx.globalAlpha = 0.15 + rng() * 0.2;
-      ctx.strokeStyle = hexWithAlpha(pickHierarchyColor(colorHierarchy, rng), 0.5);
-      ctx.lineWidth = (1.5 + rng() * 2.5) * scaleFactor;
-      ctx.beginPath();
-      shapes[portalShape]?.(ctx, portalSize * 1.06);
-      ctx.stroke();
-      ctx.restore();
-    }
-  }
+  // ── 5g. (Portal/cutout feature removed — replaced by custom shapes API) ──
 
+  _mark("5g_portals");
 
   // ── 6. Flow-line pass — variable color, branching, pressure ────
   // Optimized: collect all segments into width-quantized buckets, then
@@ -1546,6 +1545,8 @@ export function renderHashArt(
     }
   }
 
+  _mark("6_flow_lines");
+
   // ── 6b. Motion/energy lines — short directional bursts ─────────
   // Optimized: collect all burst segments, then batch by quantized alpha
   const energyArchetypes = ["dense-chaotic", "cosmic", "neon-glow", "bold-graphic"];
@@ -1605,6 +1606,8 @@ export function renderHashArt(
     }
   }
 
+  _mark("6b_energy_lines");
+
   // ── 6c. Apply symmetry mirroring ─────────────────────────────────
   if (symmetryMode !== "none") {
     const canvas = ctx.canvas;
@@ -1627,66 +1630,28 @@ export function renderHashArt(
   }
 
 
-  // ── 7. Noise texture overlay — batched via ImageData ─────────────
-  // Optimized: cap density at large sizes (diminishing returns above ~2K dots),
-  // skip inner pixelScale loop when scale=1, use Uint32Array for faster writes.
+  _mark("6c_symmetry");
+
+  // ── 7. Noise texture overlay ─────────────────────────────────────
+  // With density capped at 2500 dots, direct fillRect calls are far cheaper
+  // than the getImageData/putImageData round-trip which copies the entire
+  // pixel buffer (4 × width × height bytes) twice.
   const noiseRng = createRng(seedFromHash(gitHash, 777));
   const rawNoiseDensity = Math.floor((width * height) / 800);
-  // Cap at 2500 dots — beyond this the visual effect is indistinguishable
-  // but getImageData/putImageData cost scales with canvas size
   const noiseDensity = Math.min(rawNoiseDensity, 2500);
-  try {
-    const imageData = ctx.getImageData(0, 0, width, height);
-    const data = imageData.data;
-    const pixelScale = Math.max(1, Math.round(scaleFactor));
-    if (pixelScale === 1) {
-      // Fast path — no inner loop, direct pixel write
-      // Pre-compute alpha blend as integer math (avoid float multiply per channel)
-      for (let i = 0; i < noiseDensity; i++) {
-        const nx = Math.floor(noiseRng() * width);
-        const ny = Math.floor(noiseRng() * height);
-        const brightness = noiseRng() > 0.5 ? 255 : 0;
-        // srcA in range [0.01, 0.04] — multiply by 256 for fixed-point
-        const srcA256 = Math.round((0.01 + noiseRng() * 0.03) * 256);
-        const invA256 = 256 - srcA256;
-        const bSrc = brightness * srcA256; // pre-multiply brightness × alpha
-        const idx = (ny * width + nx) << 2;
-        data[idx]     = (data[idx]     * invA256 + bSrc) >> 8;
-        data[idx + 1] = (data[idx + 1] * invA256 + bSrc) >> 8;
-        data[idx + 2] = (data[idx + 2] * invA256 + bSrc) >> 8;
-      }
-    } else {
-      for (let i = 0; i < noiseDensity; i++) {
-        const nx = Math.floor(noiseRng() * width);
-        const ny = Math.floor(noiseRng() * height);
-        const brightness = noiseRng() > 0.5 ? 255 : 0;
-        const srcA256 = Math.round((0.01 + noiseRng() * 0.03) * 256);
-        const invA256 = 256 - srcA256;
-        const bSrc = brightness * srcA256;
-        for (let dy = 0; dy < pixelScale && ny + dy < height; dy++) {
-          for (let dx = 0; dx < pixelScale && nx + dx < width; dx++) {
-            const idx = ((ny + dy) * width + (nx + dx)) << 2;
-            data[idx]     = (data[idx]     * invA256 + bSrc) >> 8;
-            data[idx + 1] = (data[idx + 1] * invA256 + bSrc) >> 8;
-            data[idx + 2] = (data[idx + 2] * invA256 + bSrc) >> 8;
-          }
-        }
-      }
-    }
-    ctx.putImageData(imageData, 0, 0);
-  } catch {
-    // Fallback for environments where getImageData isn't available (e.g. some OffscreenCanvas)
-    for (let i = 0; i < noiseDensity; i++) {
-      const nx = noiseRng() * width;
-      const ny = noiseRng() * height;
-      const brightness = noiseRng() > 0.5 ? 255 : 0;
-      const alpha = 0.01 + noiseRng() * 0.03;
-      ctx.globalAlpha = alpha;
-      ctx.fillStyle = `rgba(${brightness},${brightness},${brightness},1)`;
-      ctx.fillRect(nx, ny, 1 * scaleFactor, 1 * scaleFactor);
-    }
+  const pixelScale = Math.max(1, Math.round(scaleFactor));
+  for (let i = 0; i < noiseDensity; i++) {
+    const nx = noiseRng() * width;
+    const ny = noiseRng() * height;
+    const brightness = noiseRng() > 0.5 ? 255 : 0;
+    const alpha = 0.01 + noiseRng() * 0.03;
+    ctx.globalAlpha = alpha;
+    ctx.fillStyle = `rgb(${brightness},${brightness},${brightness})`;
+    ctx.fillRect(nx, ny, pixelScale, pixelScale);
   }
 
+  _mark("7_noise_texture");
+
   // ── 8. Vignette — darken edges to draw the eye inward ───────────
   ctx.globalAlpha = 1;
   const vignetteStrength = 0.25 + rng() * 0.2;
@@ -1702,6 +1667,8 @@ export function renderHashArt(
   ctx.fillStyle = vigGrad;
   ctx.fillRect(0, 0, width, height);
 
+  _mark("8_vignette");
+
   // ── 9. Organic connecting curves — proximity-aware ───────────────
   // Optimized: batch all curves into alpha-quantized groups to reduce
   // beginPath/stroke calls from O(numCurves) to O(alphaBuckets).
@@ -1770,6 +1737,8 @@ export function renderHashArt(
     }
   }
 
+  _mark("9_connecting_curves");
+
   // ── 10. Post-processing ────────────────────────────────────────
 
   // 10a. Color grading — unified tone across the whole image
@@ -1827,6 +1796,8 @@ export function renderHashArt(
     ctx.globalCompositeOperation = "source-over";
   }
 
+  _mark("10_post_processing");
+
   // ── 10e. Generative borders — archetype-driven decorative frames ──
   {
     ctx.save();
@@ -1973,6 +1944,8 @@ export function renderHashArt(
     ctx.restore();
   }
 
+  _mark("10e_borders");
+
   // ── 11. Signature mark — placed in the least-dense corner ──────
   {
     const sigRng = createRng(seedFromHash(gitHash, 42));
@@ -2036,5 +2009,10 @@ export function renderHashArt(
   }
 
   ctx.globalAlpha = 1;
+  _mark("11_signature");
 
+  // Clean up custom shape profiles to avoid leaking into subsequent renders
+  for (const name of customShapeNames) {
+    delete SHAPE_PROFILES[name];
+  }
 }

package/src/types.ts

@@ -1,3 +1,46 @@
+/**
+ * Draw function signature for custom shapes.
+ * The function should build a canvas path (moveTo/lineTo/arc/etc.)
+ * centered at the origin. The pipeline handles translate, rotate,
+ * fill, and stroke — your function just defines the geometry.
+ *
+ * @param ctx  - Canvas 2D rendering context (already translated to shape center)
+ * @param size - Bounding size in pixels
+ * @param rng  - Deterministic RNG seeded from the git hash — use this instead of Math.random()
+ */
+export type CustomDrawFunction = (
+  ctx: CanvasRenderingContext2D,
+  size: number,
+  rng: () => number,
+) => void;
+
+/**
+ * Definition for a user-provided custom shape.
+ */
+export interface CustomShapeDefinition {
+  /** The draw function that builds the shape path */
+  draw: CustomDrawFunction;
+  /**
+   * Optional shape profile for the affinity system.
+   * Controls how the shape is selected and composed with others.
+   * Sensible defaults are applied for any omitted fields.
+   */
+  profile?: {
+    /** Visual quality tier: 1 = always good, 2 = usually good, 3 = situational (default: 2) */
+    tier?: 1 | 2 | 3;
+    /** Minimum size as fraction of maxShapeSize (default: 0.05) */
+    minSizeFraction?: number;
+    /** Maximum size as fraction of maxShapeSize (default: 1.0) */
+    maxSizeFraction?: number;
+    /** Names of shapes this composes well with (default: ["circle", "square"]) */
+    affinities?: string[];
+    /** Whether this shape works as a hero/focal element (default: false) */
+    heroCandidate?: boolean;
+    /** Best render styles (default: ["fill-and-stroke", "watercolor"]) */
+    bestStyles?: string[];
+  };
+}
+
 /**
  * Configuration options for image generation.
  */
@@ -20,6 +63,15 @@ export interface GenerationConfig {
   opacityReduction: number;
   /** Base shapes per layer — defaults to gridSize² × 1.5 when 0 */
   shapesPerLayer: number;
+  /**
+   * Custom shapes to include in the generation.
+   * Keys are shape names, values are CustomShapeDefinition objects.
+   * Custom shapes are merged with built-in shapes and participate
+   * in palette selection, affinity matching, and all render styles.
+   */
+  customShapes?: Record<string, CustomShapeDefinition>;
+  /** Internal: collect per-phase timing data when set (not part of public API) */
+  _debugTiming?: { phases: Record<string, number>; shapeCount: number; extraCount: number };
 }
 
 export const DEFAULT_CONFIG: GenerationConfig = {