git-hash-art 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-hash-art",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "author": "gfargo <ghfargo@gmail.com>",
   "scripts": {
     "watch": "parcel watch",

package/src/__tests__/custom-shapes.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createCanvas } from "@napi-rs/canvas";
+import * as render from "../lib/render";
+import * as affinity from "../lib/canvas/shapes/affinity";
+import type { CustomDrawFunction } from "../types";
+
+describe("Custom shapes", () => {
+  let ctx: CanvasRenderingContext2D;
+
+  beforeEach(() => {
+    const canvas = createCanvas(256, 256);
+    ctx = canvas.getContext("2d") as unknown as CanvasRenderingContext2D;
+  });
+
+  it("should render with custom shapes without crashing", () => {
+    const drawSpy = vi.fn<CustomDrawFunction>((ctx, size, rng) => {
+      const r = size / 2;
+      ctx.beginPath();
+      ctx.arc(0, 0, r, 0, Math.PI * 2);
+      ctx.closePath();
+    });
+
+    expect(() => {
+      render.renderHashArt(ctx, "abcdef1234567890", {
+        width: 256,
+        height: 256,
+        customShapes: {
+          myCircle: { draw: drawSpy },
+        },
+      });
+    }).not.toThrow();
+  });
+
+  it("should pass deterministic RNG to custom draw function", () => {
+    const rngValues: number[] = [];
+    const makeDraw = (collector: number[]): CustomDrawFunction => (ctx, size, rng) => {
+      collector.push(rng());
+      ctx.beginPath();
+      ctx.arc(0, 0, size / 2, 0, Math.PI * 2);
+      ctx.closePath();
+    };
+
+    render.renderHashArt(ctx, "deadbeefdeadbeef", {
+      width: 256,
+      height: 256,
+      customShapes: {
+        onlyShape: {
+          draw: makeDraw(rngValues),
+          profile: { tier: 1, heroCandidate: true, affinities: ["onlyShape"] },
+        },
+      },
+    });
+
+    if (rngValues.length > 0) {
+      const rngValues2: number[] = [];
+      const canvas2 = createCanvas(256, 256);
+      const ctx2 = canvas2.getContext("2d") as unknown as CanvasRenderingContext2D;
+
+      render.renderHashArt(ctx2, "deadbeefdeadbeef", {
+        width: 256,
+        height: 256,
+        customShapes: {
+          onlyShape: {
+            draw: makeDraw(rngValues2),
+            profile: { tier: 1, heroCandidate: true, affinities: ["onlyShape"] },
+          },
+        },
+      });
+
+      expect(rngValues).toEqual(rngValues2);
+    }
+  });
+
+  it("should not crash with empty customShapes", () => {
+    expect(() => {
+      render.renderHashArt(ctx, "1111111111111111", {
+        width: 256,
+        height: 256,
+        customShapes: {},
+      });
+    }).not.toThrow();
+  });
+
+  it("should not crash with undefined customShapes", () => {
+    expect(() => {
+      render.renderHashArt(ctx, "2222222222222222", {
+        width: 256,
+        height: 256,
+      });
+    }).not.toThrow();
+  });
+
+  it("should clean up custom profiles after render", () => {
+    render.renderHashArt(ctx, "3333333333333333", {
+      width: 256,
+      height: 256,
+      customShapes: {
+        tempShape: {
+          draw: (ctx, size) => {
+            ctx.beginPath();
+            ctx.rect(-size / 2, -size / 2, size, size);
+            ctx.closePath();
+          },
+        },
+      },
+    });
+
+    expect(affinity.SHAPE_PROFILES["tempShape"]).toBeUndefined();
+  });
+
+  it("should apply custom profile overrides", () => {
+    affinity.registerCustomProfile("testShape", {
+      tier: 1,
+      minSizeFraction: 0.1,
+      maxSizeFraction: 0.5,
+      affinities: ["circle", "triangle"],
+      heroCandidate: true,
+      bestStyles: ["stroke-only"],
+    });
+
+    const profile = affinity.SHAPE_PROFILES["testShape"];
+    expect(profile).toBeDefined();
+    expect(profile.tier).toBe(1);
+    expect(profile.minSizeFraction).toBe(0.1);
+    expect(profile.maxSizeFraction).toBe(0.5);
+    expect(profile.heroCandidate).toBe(true);
+    expect(profile.bestStyles).toEqual(["stroke-only"]);
+    expect(profile.category).toBe("procedural");
+
+    affinity.unregisterCustomProfile("testShape");
+    expect(affinity.SHAPE_PROFILES["testShape"]).toBeUndefined();
+  });
+
+  it("should use sensible defaults for missing profile fields", () => {
+    affinity.registerCustomProfile("defaultsShape", {});
+
+    const profile = affinity.SHAPE_PROFILES["defaultsShape"];
+    expect(profile.tier).toBe(2);
+    expect(profile.minSizeFraction).toBe(0.05);
+    expect(profile.maxSizeFraction).toBe(1.0);
+    expect(profile.affinities).toEqual(["circle", "square"]);
+    expect(profile.heroCandidate).toBe(false);
+    expect(profile.bestStyles).toEqual(["fill-and-stroke", "watercolor"]);
+
+    affinity.unregisterCustomProfile("defaultsShape");
+  });
+
+  it("should render with multiple custom shapes", () => {
+    const diamond: CustomDrawFunction = (ctx, size, rng) => {
+      const half = size / 2;
+      ctx.beginPath();
+      ctx.moveTo(0, -half);
+      ctx.lineTo(half * rng(), 0);
+      ctx.lineTo(0, half);
+      ctx.lineTo(-half * rng(), 0);
+      ctx.closePath();
+    };
+
+    const cross: CustomDrawFunction = (ctx, size, rng) => {
+      const arm = size * 0.15;
+      const half = size / 2 * (0.8 + rng() * 0.2);
+      ctx.beginPath();
+      ctx.rect(-arm, -half, arm * 2, size);
+      ctx.rect(-half, -arm, size, arm * 2);
+      ctx.closePath();
+    };
+
+    expect(() => {
+      render.renderHashArt(ctx, "cafebabe12345678", {
+        width: 256,
+        height: 256,
+        customShapes: {
+          customDiamond: { draw: diamond },
+          customCross: {
+            draw: cross,
+            profile: { tier: 1, heroCandidate: true },
+          },
+        },
+      });
+    }).not.toThrow();
+  });
+});

package/src/browser.ts

@@ -96,5 +96,5 @@ function generateDataURL(
 
 export { renderToCanvas, generateImageBlob, generateDataURL, renderHashArt };
 export { PRESETS } from "./lib/constants";
-export type { GenerationConfig } from "./types";
+export type { GenerationConfig, CustomShapeDefinition, CustomDrawFunction } from "./types";
 export { DEFAULT_CONFIG } from "./types";

package/src/index.ts

@@ -66,5 +66,5 @@ function saveImageToFile(
 
 export { generateImageFromHash, saveImageToFile, renderHashArt };
 export { PRESETS } from "./lib/constants";
-export type { GenerationConfig } from "./types";
+export type { GenerationConfig, CustomShapeDefinition, CustomDrawFunction } from "./types";
 export { DEFAULT_CONFIG } from "./types";

package/src/lib/canvas/draw.ts

@@ -134,6 +134,8 @@ interface EnhanceShapeConfig extends DrawShapeConfig {
   lightAngle?: number;
   /** Scale factor for resolution-independent sizing. */
   scaleFactor?: number;
+  /** Optional combined shapes registry (includes custom shapes). Falls back to built-in shapes. */
+  activeShapes?: Record<string, (ctx: CanvasRenderingContext2D, size: number, config?: any) => void>;
 }
 
 export function drawShape(
@@ -141,9 +143,9 @@ export function drawShape(
   shape: string,
   x: number,
   y: number,
-  config: DrawShapeConfig,
+  config: DrawShapeConfig & { activeShapes?: Record<string, (ctx: CanvasRenderingContext2D, size: number, config?: any) => void> },
 ) {
-  const { fillColor, strokeColor, strokeWidth, size, rotation } = config;
+  const { fillColor, strokeColor, strokeWidth, size, rotation, activeShapes } = config;
   ctx.save();
   ctx.translate(x, y);
   ctx.rotate((rotation * Math.PI) / 180);
@@ -151,7 +153,8 @@ export function drawShape(
   ctx.strokeStyle = strokeColor;
   ctx.lineWidth = strokeWidth;
 
-  const drawFunction = shapes[shape];
+  const registry = activeShapes ?? shapes;
+  const drawFunction = registry[shape];
   if (drawFunction) {
     drawFunction(ctx, size);
     ctx.fill();
@@ -746,7 +749,8 @@ export function enhanceShapeGeneration(
   ctx.strokeStyle = strokeColor;
   ctx.lineWidth = strokeWidth;
 
-  const drawFunction = shapes[shape];
+  const registry = config.activeShapes ?? shapes;
+  const drawFunction = registry[shape];
   if (drawFunction) {
     drawFunction(ctx, size, { rng });
     applyRenderStyle(ctx, renderStyle, fillColor, strokeColor, strokeWidth, size, rng);

package/src/lib/canvas/shapes/affinity.ts

@@ -420,6 +420,39 @@ export const SHAPE_PROFILES: Record<string, ShapeProfile> = {
   },
 };
 
+/**
+ * Register a custom shape profile into SHAPE_PROFILES.
+ * Merges user-provided partial profile with sensible defaults.
+ */
+export function registerCustomProfile(
+  name: string,
+  partial?: {
+    tier?: 1 | 2 | 3;
+    minSizeFraction?: number;
+    maxSizeFraction?: number;
+    affinities?: string[];
+    heroCandidate?: boolean;
+    bestStyles?: string[];
+  },
+): void {
+  SHAPE_PROFILES[name] = {
+    tier: partial?.tier ?? 2,
+    minSizeFraction: partial?.minSizeFraction ?? 0.05,
+    maxSizeFraction: partial?.maxSizeFraction ?? 1.0,
+    affinities: partial?.affinities ?? ["circle", "square"],
+    category: "procedural",
+    heroCandidate: partial?.heroCandidate ?? false,
+    bestStyles: partial?.bestStyles ?? ["fill-and-stroke", "watercolor"],
+  };
+}
+
+/**
+ * Remove a custom shape profile from SHAPE_PROFILES.
+ */
+export function unregisterCustomProfile(name: string): void {
+  delete SHAPE_PROFILES[name];
+}
+
 // ── Shape palette: curated sets of shapes that work well together ────
 
 export interface ShapePalette {

package/src/lib/render.ts

@@ -520,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 ───────
@@ -873,6 +898,7 @@ export function renderHashArt(
       rng,
       lightAngle,
       scaleFactor,
+      activeShapes,
     });
 
     heroCenter = { x: heroFocal.x, y: heroFocal.y, size: heroSize };
@@ -1118,6 +1144,7 @@ export function renderHashArt(
         rng,
         lightAngle,
         scaleFactor,
+        activeShapes,
       };
 
       if (shouldMirror) {
@@ -1152,6 +1179,7 @@ export function renderHashArt(
               proportionType: "GOLDEN_RATIO",
               renderStyle: "fill-only",
               rng,
+              activeShapes,
             });
           }
           extrasSpent += glazePasses;
@@ -1186,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 });
@@ -1237,6 +1266,7 @@ export function renderHashArt(
                 proportionType: "GOLDEN_RATIO",
                 renderStyle: innerStyle,
                 rng,
+                activeShapes,
               },
             );
             extrasSpent += RENDER_STYLE_COST[innerStyle] ?? 1;
@@ -1297,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 });
@@ -1348,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 });
@@ -1368,72 +1400,7 @@ export function renderHashArt(
   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");
 
@@ -2044,4 +2011,8 @@ 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,13 @@ 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 };
 }