holey-shapes 2.0.0 → 2.1.0

package/README.md

@@ -1,195 +1,34 @@
 # holey-shapes
 
-Solid, perforated shapes for the web, SwiftUI, and Jetpack Compose, with a connected extrusion and built-in hole animation. Hovering closes and reopens the holes in a seeded random order while the body stays still.
+Avatars with holes. Turn any name into a colorful, one-of-a-kind SVG shape. The same name always gives the same shape. It runs in Node and browsers with no dependencies.
 
-[live playground](https://holey-shapes.aakashreddy.com) · [npm package](https://www.npmjs.com/package/holey-shapes) · [source](https://github.com/skyaara/holey-shapes)
-
-## Install
-
-### JavaScript
+<img src="https://raw.githubusercontent.com/skyaara/holey-shapes/main/.github/media/names.gif" width="720" alt="Ten names, each turned into its own holey shape">
 
 ```sh
 npm install holey-shapes
 ```
 
-### Swift Package Manager
-
-In Xcode, add `https://github.com/skyaara/holey-shapes` as a package dependency, or add it to `Package.swift`:
-
-```swift
-dependencies: [
-    .package(url: "https://github.com/skyaara/holey-shapes.git", from: "2.0.0")
-]
-```
-
-Then render any catalog shape directly in SwiftUI:
-
-```swift
-import HoleyShapes
-import SwiftUI
-
-struct Logo: View {
-    var body: some View {
-        HoleyShapeView(
-            .prism,
-            faceColor: HoleyColor(hex: "#FF4FA3"),
-            shadowColor: HoleyColor(hex: "#7A1748"),
-            holes: 6,
-            seed: 2
-        )
-        .frame(width: 240, height: 240)
-    }
-}
-```
-
-The Swift SDK supports iOS 16+, macOS 13+, tvOS 16+, and visionOS 1+. It uses asynchronous SwiftUI `Canvas` rendering and caches the immutable shape paths, packing candidates, and finished hole layouts. Pointer hover closes and reopens individual holes, and Reduce Motion disables the effect.
-
-### Android
-
-Add JitPack to dependency resolution in `settings.gradle.kts`:
-
-```kotlin
-dependencyResolutionManagement {
-    repositories {
-        google()
-        mavenCentral()
-        maven("https://jitpack.io")
-    }
-}
-```
-
-Then add the Compose SDK:
-
-```kotlin
-dependencies {
-    implementation("com.github.skyaara:holey-shapes:v2.0.0")
-}
-```
-
-Use the composable directly or derive a stable shape from an ID:
-
-```kotlin
-import com.aakashreddy.holeyshapes.HoleyShapeConfig
-import com.aakashreddy.holeyshapes.HoleyShapeView
-
-HoleyShapeView(
-    config = HoleyShapeConfig.seeded(user.id),
-    modifier = Modifier.size(64.dp),
-    contentDescription = null,
-)
-```
-
-The Android SDK requires API 26 or newer and a consuming project compiled with API 35 or newer. It renders through the native Android canvas and caches geometry and packed layouts. Mouse and stylus hover close and reopen individual holes; touch-only avatars remain still. Android's animation scale applies automatically.
-
-## Generate layouts in Swift and JVM processes
-
-Swift packing uses Foundation and plain geometry. It needs no SwiftUI view or CoreGraphics context. The package conditionally includes its SwiftUI renderer on supported Apple platforms.
-
-```swift
-import HoleyShapes
-
-let holes = HoleyShapes.layout(shape: .prism, count: 6, seed: 2)
-// Each hole exposes cx, cy, rx, ry, and rotation.
-```
-
-The Kotlin `core` module is a standalone JVM library with no Android or Compose dependencies. The Android SDK uses this same core. For a local JVM consumer, run `./gradlew :core:publishToMavenLocal`, enable `mavenLocal()`, and add `com.github.skyaara:holey-shapes-core:2.0.0`. For JitPack, the standalone module coordinate is `com.github.skyaara.holey-shapes:holey-shapes-core:v2.0.0`.
-
-```kotlin
-import com.aakashreddy.holeyshapes.core.HoleyPacking
-import com.aakashreddy.holeyshapes.core.HoleyShape
-
-val holes = HoleyPacking.layout(HoleyShape.Prism, count = 6, seed = 2)
-```
-
-Both APIs use full equal-area packing, clamp counts to 0–8 and seeds to ±1,000,000, and cache layouts. They never substitute preset layouts. Floating-point differences between language runtimes can produce different positions; byte-identical layouts across Swift, Kotlin, and JavaScript are not guaranteed.
-
-Run the process checks locally:
-
-```sh
-swift run --package-path tests/native/swift -c release Verify /tmp/swift-layouts.json
-./gradlew :core:verifyPacking
-# Independent Canvas checks require Playwright and installed Google Chrome.
-node scripts/verify-native-layouts.mjs /tmp/swift-layouts.json core/build/packing-layouts.json
-```
-
-## Render an SVG string
-
-```js
-import { createHoleySvg } from 'holey-shapes';
-
-const svg = createHoleySvg({
-  shape: 'prism',
-  color: '#FF4FA3',
-  shadowColor: '#7A1748',
-  holes: 6,
-  seed: 2
-});
-
-document.querySelector('#shape').innerHTML = svg;
-```
-
-`createHoleySvg()` returns a complete, self-contained SVG string. The animation and extrusion are embedded in the SVG, so downloaded or copied shapes keep their hover behavior.
-
-## Mount and update a shape
-
 ```js
-import { mountHoleyShape } from 'holey-shapes';
+import { createHoleySvg, mountHoleyShape } from 'holey-shapes';
 
-const shape = mountHoleyShape('#shape', {
-  shape: 'disc',
-  color: '#6337FF',
-  holes: 5
-});
+const svg = createHoleySvg({ shape: 'prism', color: '#FF4FA3', holes: 6, seed: 2 });
+document.querySelector('#preview').innerHTML = svg;
 
-shape.update({ color: '#00D7B9', holes: 8 });
-shape.shuffle();
+const mounted = mountHoleyShape('#avatar', { shape: 'disc', holes: 5 });
+mounted.update({ color: '#00D7B9' });
 ```
 
-`mountHoleyShape()` returns `update()`, `shuffle()`, and `destroy()` methods. Updates replace only the mounted SVG.
-
-The generated SVG scales to its container:
-
-```css
-#shape {
-  width: 320px;
-}
-
-#shape svg {
-  display: block;
-  width: 100%;
-  height: auto;
-}
-```
-
-## Options
-
-| Option | Default | Description |
-| --- | --- | --- |
-| `shape` | `disc` | One of the keys in `shapeNames` |
-| `color` | Shape color | Six-digit hex face color |
-| `shadowColor` | Darker face color | Six-digit hex extrusion color |
-| `holes` | Shape default | Hole count from 0 to 8 |
-| `seed` | `0` | Changes the hole layout |
-| `animated` | `true` | Includes the hover hole animation |
-| `duration` | `900` | Total hole-animation duration in milliseconds |
-| `shadowX` | `18` | Horizontal extrusion offset |
-| `shadowY` | `21` | Vertical extrusion offset |
-| `shadowSteps` | `12` | Number of solid extrusion slices |
-
-Available shape keys: `disc`, `round-block`, `hex`, `capsule`, `prism`, `cross`, `triangle`, `diamond`, `sunburst`, `octagon`, `chevron`, `long-bar`, `flower-star`, and `bowtie`.
-
-You can also build a picker from the exported metadata:
+Give every user a stable avatar from their ID. `identityHash(id)` returns the 16-digit hex hash that `seededHoleyOptions(id)` derives the shape and seed from:
 
 ```js
-import { shapeNames } from 'holey-shapes';
+import { createHoleySvg, identityHash, seededHoleyOptions } from 'holey-shapes';
 
-for (const { key, name, color } of shapeNames) {
-  console.log(key, name, color);
-}
+identityHash('relay-agent'); // '0cc0c8aa3dbd893e'
+avatar.innerHTML = createHoleySvg({ ...seededHoleyOptions('relay-agent'), idPrefix: 'relay-agent' });
 ```
 
-## Browser support
+Pass a unique `idPrefix` to `createHoleySvg()` when adding multiple SVG strings to one document. `mountHoleyShape()` creates isolated IDs automatically.
 
-The package has no runtime dependencies. Node processes, server-side rendering, and browsers use the same JavaScript geometry and full hole-packing algorithm. SVG generation needs no DOM, Canvas, or `Path2D`; identical options produce identical SVG markup. Only `mountHoleyShape` and interactive animation require a browser.
+For the option reference, shape catalog, native packages, and contribution guide, see the [reference](https://github.com/skyaara/holey-shapes/blob/main/docs/REFERENCE.md) and the [project README](https://github.com/skyaara/holey-shapes#readme). Source for this package is in [`packages/js`](https://github.com/skyaara/holey-shapes/tree/main/packages/js).
 
-The hover animation respects `prefers-reduced-motion`.
+MIT licensed.

package/color.js

@@ -0,0 +1,54 @@
+// Colors are chosen in OKLCH, where equal lightness looks equally bright. Every
+// seeded hue then reads as one family, and every extrusion darkens by the same
+// perceived amount. Swift and Kotlin repeat these steps exactly; results are
+// rounded to sRGB hex.
+
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+const toGamma = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055);
+
+function oklabToLinear(L, a, b) {
+  const l = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s = L - 0.0894841775 * a - 1.291485548 * b;
+  const l3 = l * l * l, m3 = m * m * m, s3 = s * s * s;
+  return [
+    4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+    -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+    -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3,
+  ];
+}
+
+const inGamut = (rgb) => rgb.every((v) => v >= -0.0001 && v <= 1.0001);
+const hex = (rgb) => `#${rgb.map((v) => Math.round(toGamma(Math.min(1, Math.max(0, v))) * 255).toString(16).padStart(2, '0')).join('').toUpperCase()}`;
+
+// Keeps lightness and hue, and reduces chroma until the color fits in sRGB.
+function oklabHex(L, a, b) {
+  if (inGamut(oklabToLinear(L, a, b))) return hex(oklabToLinear(L, a, b));
+  let low = 0, high = 1;
+  for (let pass = 0; pass < 24; pass++) {
+    const mid = (low + high) / 2;
+    if (inGamut(oklabToLinear(L, a * mid, b * mid))) low = mid;
+    else high = mid;
+  }
+  return hex(oklabToLinear(L, a * low, b * low));
+}
+
+/** Face color for a hue in degrees. Yellows only look clean when lighter, so lightness rises around 100°. */
+export function hueColor(hue) {
+  const distance = Math.abs(((hue - 100) % 360 + 540) % 360 - 180);
+  const lift = distance < 60 ? Math.pow(Math.cos((distance / 60) * (Math.PI / 2)), 2) : 0;
+  const angle = (hue * Math.PI) / 180;
+  return oklabHex(0.74 + 0.12 * lift, 0.19 * Math.cos(angle), 0.19 * Math.sin(angle));
+}
+
+/** Extrusion color for a face: the same hue at 56% of its lightness and 70% of its chroma. */
+export function extrusionColor(face) {
+  const [r, g, b] = [1, 3, 5].map((i) => toLinear(parseInt(face.slice(i, i + 2), 16) / 255));
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return oklabHex(L * 0.56, A * 0.7, B * 0.7);
+}

package/doodle.js

@@ -0,0 +1,79 @@
+import { compileShapePath } from "./geometry.js";
+
+const ink = "#25262A";
+const n = (value) => String(Math.round(value * 100) / 100);
+const point = ([x, y]) => `${n(x)} ${n(y)}`;
+const contours = new Map();
+
+// A wobbly polyline around the outline. Straight segments keep corners crisp.
+function outline(shape, seed) {
+  let vertices = contours.get(shape.key);
+  if (!vertices) {
+    vertices = compileShapePath(shape.path).contour;
+    contours.set(shape.key, vertices);
+  }
+  const phase = seed * 0.017;
+  const wobble = ([x, y]) => [
+    x + 2.6 * Math.sin(y / 23 + phase) + 1.3 * Math.sin(x / 13 + y / 37),
+    y + 2.6 * Math.sin(x / 27 - phase) + 1.3 * Math.cos(y / 17 + x / 31),
+  ];
+  const points = [vertices[0]];
+  // Retain polygon corners; decimate the densely flattened curves.
+  for (let i = 1; i < vertices.length; i++) {
+    const current = vertices[i], previous = vertices[i - 1];
+    const next = vertices[(i + 1) % vertices.length];
+    const a = Math.atan2(current[1] - previous[1], current[0] - previous[0]);
+    const b = Math.atan2(next[1] - current[1], next[0] - current[0]);
+    const last = points[points.length - 1];
+    const distance = Math.hypot(current[0] - last[0], current[1] - last[1]);
+    if (distance < 9 && Math.abs(Math.atan2(Math.sin(b - a), Math.cos(b - a))) < 0.3 && i < vertices.length - 1) continue;
+    const steps = Math.max(1, Math.ceil(distance / 10));
+    for (let step = 1; step <= steps; step++) {
+      points.push([last[0] + ((current[0] - last[0]) * step) / steps, last[1] + ((current[1] - last[1]) * step) / steps]);
+    }
+  }
+  return points.map((p, i) => `${i ? "L" : "M"}${point(wobble(p))}`).join("") + "Z";
+}
+
+// A slightly irregular closed curve inside each packed hole.
+function cutout(hole, seed, index) {
+  const phase = seed * 0.013 + index * 2.4;
+  const rotation = (hole.rotate * Math.PI) / 180;
+  const points = Array.from({ length: 12 }, (_, i) => {
+    const angle = (i * Math.PI) / 6;
+    // Shrink before wobbling to stay inside the original packing clearance.
+    const radius = 0.92 + 0.045 * Math.sin(angle * 3 + phase) + 0.03 * Math.cos(angle * 2 - phase);
+    const x = Math.cos(angle) * hole.rx * radius;
+    const y = Math.sin(angle) * hole.ry * radius;
+    return [hole.cx + x * Math.cos(rotation) - y * Math.sin(rotation), hole.cy + x * Math.sin(rotation) + y * Math.cos(rotation)];
+  });
+  let path = `M${point(points[0])}`;
+  for (let i = 0; i < points.length; i++) {
+    const prev = points[(i + 11) % 12], start = points[i];
+    const end = points[(i + 1) % 12], next = points[(i + 2) % 12];
+    path += `C${point(start.map((v, j) => v + (end[j] - prev[j]) / 6))} ${point(end.map((v, j) => v - (next[j] - start[j]) / 6))} ${point(end)}`;
+  }
+  return path + "Z";
+}
+
+export function createDoodleSvg(shape, holes, options) {
+  const seed = options.seed || 0;
+  const path = outline(shape, seed);
+  const paths = holes.map((hole, index) => cutout(hole, seed, index));
+  const duration = Math.max(100, Math.min(10000, Number(options.duration) || 900));
+  // The offset shadow is ink by default, or a solid silhouette in the shadow
+  // color when one is given, so it reads on dark backgrounds too.
+  const shadow = options.doodleShadow ?? ink;
+  // Turn and mirror the drawing, not its offset, so the ink shadow keeps its direction.
+  const turned = options.transform ? ` transform="${options.transform}"` : "";
+  const hole = (d, index, stroke = false) => {
+    const mark = `<path d="${d}" fill="${stroke ? "none" : "black"}"${stroke ? ` stroke="${ink}" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"` : ""}/>`;
+    return options.animated === false
+      ? mark
+      : `<g class="doodle-cutout" style="transform-origin:${n(holes[index].cx)}px ${n(holes[index].cy)}px;--doodle-delay:${index * 27}ms;--doodle-duration:${duration}ms">${mark}</g>`;
+  };
+  const animation = options.animated === false
+    ? ""
+    : "<style>svg:hover .doodle-cutout{animation:doodle-cutout-pulse var(--doodle-duration) ease-in-out var(--doodle-delay) both}@keyframes doodle-cutout-pulse{0%,100%{transform:scale(1)}50%{transform:scale(.75)}}@media(prefers-reduced-motion:reduce){svg:hover .doodle-cutout{animation:none}}</style>";
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 420" role="img" aria-label="${shape.name} with ${holes.length} holes">${animation}<defs><mask id="h"><rect width="420" height="420" fill="white"/>${paths.map((d, i) => hole(d, i)).join("")}</mask></defs><g stroke="${ink}" stroke-width="7" stroke-linejoin="round" stroke-linecap="round"><g class="doodle-shadow-offset" transform="translate(9 11)"><g class="doodle-shadow"${turned}><path d="${path}" fill="${shadow}" stroke="${shadow}" mask="url(#h)"/></g></g><g class="doodle-face"${turned}><path d="${path}" fill="${shape.color}" mask="url(#h)"/><path d="${path}" fill="none"/>${paths.map((d, i) => hole(d, i, true)).join("")}</g></g></svg>`;
+}

package/geometry.js

@@ -4,6 +4,7 @@
 export function compileShapePath(source) {
   const tokens = source.match(/[a-zA-Z]|[-+]?(?:\d*\.\d+|\d+\.?\d*)(?:e[-+]?\d+)?/g) || [];
   const edges = [];
+  const contour = [];
   let i = 0, command, x = 0, y = 0, startX = 0, startY = 0;
   const number = () => {
     const value = Number(tokens[i++]);
@@ -13,6 +14,7 @@ export function compileShapePath(source) {
   const line = (nx, ny) => {
     if (y !== ny) edges.push({ x, y, nx, ny });
     x = nx; y = ny;
+    contour.push([x, y]);
   };
   function quadratic(x0, y0, cx, cy, x1, y1) {
     // The curve's deviation from its chord is at most half this distance.
@@ -31,6 +33,7 @@ export function compileShapePath(source) {
     switch (command) {
       case 'M':
         x = number(); y = number(); startX = x; startY = y; command = 'L';
+        contour.push([x, y]);
         break;
       case 'L': line(number(), number()); break;
       case 'H': line(number(), y); break;
@@ -74,20 +77,38 @@ export function compileShapePath(source) {
       default: throw new Error(`Unsupported shape path command: ${command}`);
     }
   }
-  // Index edges by vertical band to keep the optimizer's many point queries cheap.
-  const bands = new Map();
+  // Index edges by 1-unit vertical band in flat arrays: the optimizer makes
+  // millions of point queries, and each one only scans the few edges that can
+  // cross its row. The crossing arithmetic is unchanged, so results are exact.
+  let top = Infinity, bottom = -Infinity;
   for (const edge of edges) {
-    for (let band = Math.floor(Math.min(edge.y, edge.ny) / 8); band <= Math.floor(Math.max(edge.y, edge.ny) / 8); band++) {
-      if (!bands.has(band)) bands.set(band, []);
-      bands.get(band).push(edge);
-    }
+    top = Math.min(top, edge.y, edge.ny);
+    bottom = Math.max(bottom, edge.y, edge.ny);
   }
+  const first = Math.floor(top), bandCount = edges.length ? Math.floor(bottom) - first + 1 : 0;
+  const bandEdges = Array.from({ length: bandCount }, () => []);
+  edges.forEach((edge, index) => {
+    for (let band = Math.floor(Math.min(edge.y, edge.ny)); band <= Math.floor(Math.max(edge.y, edge.ny)); band++) {
+      bandEdges[band - first].push(index);
+    }
+  });
+  const offsets = new Uint32Array(bandCount + 1);
+  bandEdges.forEach((list, band) => { offsets[band + 1] = offsets[band] + list.length; });
+  const data = new Float64Array(offsets[bandCount] * 4);
+  bandEdges.flat().forEach((index, slot) => {
+    const e = edges[index];
+    data.set([e.x, e.y, e.nx, e.ny], slot * 4);
+  });
   return {
+    contour,
     contains(px, py) {
+      const band = Math.floor(py) - first;
+      if (!(band >= 0 && band < bandCount)) return false;
       let winding = 0;
-      for (const e of bands.get(Math.floor(py / 8)) || []) {
-        if ((e.y > py) === (e.ny > py)) continue;
-        if (px < e.x + (py - e.y) * (e.nx - e.x) / (e.ny - e.y)) winding += e.ny > e.y ? 1 : -1;
+      for (let k = offsets[band] * 4, end = offsets[band + 1] * 4; k < end; k += 4) {
+        const x = data[k], y = data[k + 1], nx = data[k + 2], ny = data[k + 3];
+        if ((y > py) === (ny > py)) continue;
+        if (px < x + (py - y) * (nx - x) / (ny - y)) winding += ny > y ? 1 : -1;
       }
       return winding !== 0;
     }

package/index.d.ts

@@ -15,11 +15,20 @@ export type HoleyShapeKey =
   | 'bowtie';
 
 export interface HoleyOptions {
+  /** Hand-drawn outline and fixed ink shadow. */
+  doodle?: boolean;
+  /** Unique, stable prefix when inserting multiple SVG strings in one document. */
+  idPrefix?: string;
   shape?: HoleyShapeKey;
   color?: `#${string}`;
+  /** Extrusion color. For doodles, the offset shadow's color; ink when omitted. */
   shadowColor?: `#${string}`;
   holes?: number;
   seed?: number;
+  /** Quarter turns of the face: 0, 90, 180 or 270. Other values snap to the nearest. The extrusion keeps its direction. */
+  turn?: number;
+  /** Flip the face left to right. The extrusion keeps its direction. */
+  mirror?: boolean;
   animated?: boolean;
   duration?: number;
   shadowX?: number;
@@ -41,7 +50,26 @@ export interface HoleyMount {
 }
 
 export const shapeNames: readonly HoleyShapeInfo[];
-export const shapes: readonly Record<string, unknown>[];
-export function seededHoleyOptions(identity: string, animated?: boolean): HoleyOptions;
+export interface HoleyShape extends HoleyShapeInfo {
+  readonly bg: string;
+  readonly initial: number;
+  readonly path: string;
+  readonly holes: readonly { cx: number; cy: number; rx: number; ry: number; rotate: number }[];
+}
+export const shapes: readonly HoleyShape[];
+/** FNV-1a 64 hash of the UTF-8 ID as 16 lowercase hex digits. `seededHoleyOptions` starts from it. */
+export function identityHash(identity: string): string;
+/** Options derived from an identity. Swift and Kotlin derive the same values. */
+export interface SeededHoleyOptions {
+  shape: HoleyShapeKey;
+  holes: number;
+  seed: number;
+  turn: 0 | 90 | 180 | 270;
+  mirror: boolean;
+  color: `#${string}`;
+  shadowColor: `#${string}`;
+  animated: boolean;
+}
+export function seededHoleyOptions(identity: string, animated?: boolean): SeededHoleyOptions;
 export function createHoleySvg(options?: HoleyOptions): string;
 export function mountHoleyShape(target: string | Element, options?: HoleyOptions): HoleyMount;

package/index.js

@@ -1 +1 @@
-export { createHoleySvg, mountHoleyShape, seededHoleyOptions, shapeNames, shapes } from './script.js';
+export { createHoleySvg, identityHash, mountHoleyShape, seededHoleyOptions, shapeNames, shapes } from './script.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holey-shapes",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Colorful perforated SVG shapes with solid extrusion and animated holes.",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/skyaara/holey-shapes.git"
+    "url": "git+https://github.com/skyaara/holey-shapes.git",
+    "directory": "packages/js"
   },
   "homepage": "https://github.com/skyaara/holey-shapes#readme",
   "bugs": {
@@ -32,6 +33,8 @@
     "index.js",
     "script.js",
     "geometry.js",
+    "doodle.js",
+    "color.js",
     "index.d.ts",
     "README.md",
     "LICENSE"
@@ -55,13 +58,7 @@
     "access": "public"
   },
   "scripts": {
-    "dev": "vite --host 127.0.0.1",
-    "build": "vite build",
-    "preview": "vite preview --host 127.0.0.1",
-    "test": "node tests/package.test.mjs && node tests/packing.test.mjs && node tests/site.test.mjs",
-    "prepublishOnly": "npm test && npm run build"
-  },
-  "devDependencies": {
-    "vite": "^7.1.3"
+    "test": "node tests/package.test.mjs && node tests/packing.test.mjs",
+    "prepublishOnly": "npm test"
   }
 }

package/script.js

@@ -1,51 +1,10 @@
 import { compileShapePath } from './geometry.js';
+import { extrusionColor, hueColor } from './color.js';
+import { createDoodleSvg } from './doodle.js';
 
 const h = (cx, cy, rx, ry, rotate = 0) => ({ cx, cy, rx, ry, rotate });
 
 const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
-const root = isBrowser ? document.documentElement : null;
-const isHoleyApp = root?.hasAttribute('data-holey-app');
-const themeToggle = isHoleyApp ? document.querySelector('.theme-toggle') : null;
-const themeLabel = themeToggle?.querySelector('.theme-label');
-
-function applyTheme(theme) {
-  if (!themeToggle || !themeLabel) return;
-  const isDark = theme === 'dark';
-  root.dataset.theme = theme;
-  themeToggle.setAttribute('aria-pressed', String(isDark));
-  themeToggle.setAttribute('aria-label', `Switch to ${isDark ? 'light' : 'dark'} mode`);
-  themeLabel.textContent = isDark ? 'LIGHT' : 'DARK';
-}
-
-if (themeToggle) {
-  const savedTheme = localStorage.getItem('holey-theme');
-  const initialTheme = savedTheme || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
-  applyTheme(initialTheme);
-  themeToggle.addEventListener('click', () => {
-    const nextTheme = root.dataset.theme === 'dark' ? 'light' : 'dark';
-    applyTheme(nextTheme);
-    localStorage.setItem('holey-theme', nextTheme);
-  });
-}
-
-const installButton = isHoleyApp ? document.querySelector('.install-command') : null;
-
-if (installButton) {
-  installButton.addEventListener('click', async () => {
-    const label = installButton.querySelector('.install-copy-label');
-    try {
-      await navigator.clipboard.writeText('npm install holey-shapes');
-      if (label) label.textContent = 'COPIED';
-      window.setTimeout(() => {
-        if (label) label.textContent = 'COPY';
-      }, 1400);
-    } catch {
-      if (label) label.textContent = 'SELECT';
-      window.getSelection()?.selectAllChildren(installButton.querySelector('code'));
-    }
-  });
-}
-
 export const shapes = [
   {
     key: 'disc', name: 'Perforated disc', color: '#6337FF', bg: '#D7CEFF', initial: 5,
@@ -119,12 +78,10 @@ export const shapes = [
   }
 ];
 
-const collection = isHoleyApp ? document.querySelector('#collection') : null;
 const MAX_HOLES = 8;
 const SHADOW_X = 18;
 const SHADOW_Y = 21;
 const SHADOW_STEPS = 12;
-const states = new Map();
 const packingCache = new Map();
 
 const holeMarkup = ({ cx, cy, rx, ry, rotate }) =>
@@ -138,11 +95,6 @@ function hoverHoleMarkup(hole, index, seed = 0, duration = 900) {
   return `<g class="hole-hover" style="--hole-duration:${pulseDuration}ms;--hole-delay:${delay}ms">${holeMarkup(hole)}</g>`;
 }
 
-function darkShadow(color, factor = 0.52) {
-  const value = color.replace('#', '');
-  const channels = [0, 2, 4].map((offset) => parseInt(value.slice(offset, offset + 2), 16));
-  return `#${channels.map((channel) => Math.round(channel * factor).toString(16).padStart(2, '0')).join('')}`;
-}
 
 function circleFits(path, cx, cy, radius) {
   for (let step = 0; step < 32; step += 1) {
@@ -263,6 +215,10 @@ function maximizeHoleAreas(shape, holes) {
     }
     return low;
   }
+  function fitsAt(point, profile, radius) {
+    return radius < 180 && path.contains(point.x, point.y) && profile.edge.every(e => path.contains(
+      point.x + radius * e.x + (gap + 1) * e.nx, point.y + radius * e.y + (gap + 1) * e.ny));
+  }
   const boundaries = points.map((p, i) => boundaryLimit(p, profiles[i]));
   function capacity(point, index, boundary) {
     let limit = boundary;
@@ -286,8 +242,12 @@ function maximizeHoleAreas(shape, holes) {
         let bestLimit = capacity(point, i, bestBoundary);
         for (const [dx, dy] of [[1,0],[-1,0],[0,1],[0,-1],[1,1],[-1,1],[1,-1],[-1,-1]]) {
           const candidate = { x: point.x + dx * step, y: point.y + dy * step };
+          // A move wins only if both limits beat the threshold, so reject on
+          // the cheap separation test and a single rim test before the search.
+          const separation = capacity(candidate, i, Infinity);
+          if (separation <= bestLimit + 0.02 || !fitsAt(candidate, profiles[i], bestLimit + 0.02)) continue;
           const boundary = boundaryLimit(candidate, profiles[i]);
-          const limit = capacity(candidate, i, boundary);
+          const limit = Math.min(separation, boundary);
           if (limit > bestLimit + 0.02) {
             best = candidate; bestBoundary = boundary; bestLimit = limit;
           }
@@ -380,12 +340,6 @@ function initialHoleLayout(shape, count, seed) {
   }));
 }
 
-function svgMarkup(shape, holes, className, maskSuffix, accessible = false) {
-  const maskId = `mask-${shape.key}-${maskSuffix}`;
-  const fill = className === 'shape-shadow' ? darkShadow(shape.color) : shape.color;
-  return `<svg class="shape-layer ${className}" viewBox="0 0 420 420" ${accessible ? `role="img" aria-label="${shape.name} with ${holes.length} holes"` : 'aria-hidden="true"'}><defs><mask id="${maskId}"><rect width="420" height="420" fill="white"/>${holes.map(holeMarkup).join('')}</mask></defs><path d="${shape.path}" fill="${fill}" mask="url(#${maskId})"/></svg>`;
-}
-
 function compactNumber(value) {
   const rounded = Math.round(value * 100) / 100;
   return String(Object.is(rounded, -0) ? 0 : rounded);
@@ -395,7 +349,7 @@ function extrusionFilterMarkup(shape, filterId, options = {}) {
   const shadowX = options.shadowX ?? SHADOW_X;
   const shadowY = options.shadowY ?? SHADOW_Y;
   const shadowSteps = options.shadowSteps ?? SHADOW_STEPS;
-  const shadowColor = options.shadowColor ?? darkShadow(shape.color);
+  const shadowColor = options.shadowColor ?? extrusionColor(shape.color);
   const offsets = Array.from({ length: shadowSteps }, (_, index) => {
     const step = index + 1;
     const ratio = step / shadowSteps;
@@ -407,23 +361,14 @@ function extrusionFilterMarkup(shape, filterId, options = {}) {
   return `<filter id="${filterId}" x="-20%" y="-20%" width="160%" height="160%" color-interpolation-filters="sRGB"><feFlood flood-color="${shadowColor}" result="p"/><feComposite in="p" in2="SourceGraphic" operator="in" result="s"/>${offsets}<feMerge>${merge}<feMergeNode in="SourceGraphic"/></feMerge></filter>`;
 }
 
-function objectMarkup(shape, holes, suffix, accessible = false, options = {}) {
-  const maskId = `mask-${shape.key}-${suffix}`;
-  const filterId = `extrusion-${shape.key}-${suffix}`;
-  const seed = options.seed ?? 0;
-  const duration = options.duration ?? 900;
-  const maskHoles = holes.map((hole, index) => hoverHoleMarkup(hole, index, seed, duration)).join('');
-  return `<svg class="shape-layer shape-object" viewBox="0 0 420 420" ${accessible ? `role="img" aria-label="${shape.name} with ${holes.length} holes"` : 'aria-hidden="true"'}><defs><mask id="${maskId}"><rect width="420" height="420" fill="white"/>${maskHoles}</mask>${extrusionFilterMarkup(shape, filterId)}</defs><g filter="url(#${filterId})"><path d="${shape.path}" fill="${shape.color}" mask="url(#${maskId})"/></g></svg>`;
-}
-
-function renderShape(card, shape, state) {
-  const holes = packedHoleLayout(shape, state.count, state.seed);
-  card.querySelector('.shape-art').innerHTML = objectMarkup(shape, holes, 'card', true, { seed: state.seed });
-  card.querySelector('.hole-count').textContent = `${String(state.count).padStart(2, '0')} / ${String(state.limit).padStart(2, '0')}`;
-  card.querySelector('.hole-range').value = state.count;
+// Quarter turns and mirroring apply to the face only. The extrusion is drawn
+// around it in unturned space, so every holey's depth points the same way.
+function orientation(turn = 0, mirror = false) {
+  return [turn ? `rotate(${turn} 210 210)` : '', mirror ? 'translate(420 0) scale(-1 1)' : ''].filter(Boolean).join(' ');
 }
 
 function exportSvg(shape, holes, options = {}) {
+  if (options.doodle) return createDoodleSvg(shape, holes, options);
   const filter = extrusionFilterMarkup(shape, 'e', options);
   const duration = Math.max(100, Math.min(10000, Number(options.duration) || 900));
   const seed = Math.trunc(Number(options.seed) || 0);
@@ -433,7 +378,7 @@ function exportSvg(shape, holes, options = {}) {
   const animation = options.animated === false
     ? ''
     : `<style>.hole-hover{transform-box:fill-box;transform-origin:center;will-change:transform}svg:hover .hole-hover{animation:hole-open-close var(--hole-duration) cubic-bezier(.33,0,.2,1) var(--hole-delay) both}@keyframes hole-open-close{0%,100%{transform:scale(1)}50%{transform:scale(.06)}}@media(prefers-reduced-motion:reduce){svg:hover .hole-hover{animation:none}}</style>`;
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 420" role="img" aria-label="${shape.name} with ${holes.length} holes">${animation}<defs><mask id="h"><rect width="420" height="420" fill="white"/>${maskHoles}</mask>${filter}</defs><g filter="url(#e)"><path d="${shape.path}" fill="${shape.color}" mask="url(#h)"/></g></svg>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 420" role="img" aria-label="${shape.name} with ${holes.length} holes">${animation}<defs><mask id="h"><rect width="420" height="420" fill="white"/>${maskHoles}</mask>${filter}</defs><g filter="url(#e)"><path${options.transform ? ` transform="${options.transform}"` : ''} d="${shape.path}" fill="${shape.color}" mask="url(#h)"/></g></svg>`;
 }
 
 function normalizeColor(color, fallback) {
@@ -441,29 +386,58 @@ function normalizeColor(color, fallback) {
 }
 
 function numberInRange(value, fallback, min, max) {
+  if (value === null || value === undefined || value === '') return fallback;
   const number = Number(value);
   return Number.isFinite(number) ? Math.min(max, Math.max(min, number)) : fallback;
 }
 
-export const shapeNames = Object.freeze(shapes.map(({ key, name, color }) => ({ key, name, color })));
+export const shapeNames = Object.freeze(shapes.map(({ key, name, color }) => Object.freeze({ key, name, color })));
 
-export function seededHoleyOptions(identity, animated = true) {
-  const bytes = new TextEncoder().encode(String(identity));
+// Callers inserting several SVG strings can supply a stable, unique prefix.
+// Encoding each code point avoids collisions between punctuation and underscores.
+function scopeSvg(source, prefix) {
+  if (prefix === undefined) return source;
+  const id = `holey-${Array.from(String(prefix), c => c.codePointAt(0).toString(16)).join('-') || 'empty'}`;
+  return source.replaceAll('id="h"', `id="${id}-h"`).replaceAll('url(#h)', `url(#${id}-h)`)
+    .replaceAll('id="e"', `id="${id}-e"`).replaceAll('url(#e)', `url(#${id}-e)`);
+}
+
+function fnv1a64(identity) {
   let hash = 14695981039346656037n;
-  for (const byte of bytes) {
+  for (const byte of new TextEncoder().encode(String(identity))) {
     hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * 1099511628211n);
   }
-  let state = hash;
-  const next = () => {
-    state = BigInt.asUintN(64, state + 0x9E3779B97F4A7C15n);
-    let value = state;
-    value = BigInt.asUintN(64, (value ^ (value >> 30n)) * 0xBF58476D1CE4E5B9n);
-    value = BigInt.asUintN(64, (value ^ (value >> 27n)) * 0x94D049BB133111EBn);
-    return BigInt.asUintN(64, value ^ (value >> 31n));
+  return hash;
+}
+
+export function identityHash(identity) {
+  return fnv1a64(identity).toString(16).padStart(16, '0');
+}
+
+// Seeding: the identity hash is mixed once, with a bijection so no bits are
+// lost, then read as mixed-radix digits, so every field gets its own bits.
+function mix64(value) {
+  value = BigInt.asUintN(64, (value ^ (value >> 30n)) * 0xBF58476D1CE4E5B9n);
+  value = BigInt.asUintN(64, (value ^ (value >> 27n)) * 0x94D049BB133111EBn);
+  return value ^ (value >> 31n);
+}
+
+export function seededHoleyOptions(identity, animated = true) {
+  let rest = mix64(fnv1a64(identity));
+  const take = (count) => {
+    const digit = Number(rest % BigInt(count));
+    rest /= BigInt(count);
+    return digit;
   };
-  const shape = shapes[Number(next() % BigInt(shapes.length))];
-  const seed = Number(next() % 1000001n);
-  return { shape: shape.key, seed, animated };
+  const shape = shapes[take(shapes.length)];
+  const fewest = Math.max(2, shape.initial - 1);
+  const most = Math.min(MAX_HOLES, shape.holes.length, shape.initial + 1);
+  const holes = fewest + take(most - fewest + 1);
+  const turn = take(4) * 90;
+  const mirror = take(2) === 1;
+  const color = hueColor(take(3600) / 10);
+  const seed = take(1000001);
+  return { shape: shape.key, holes, seed, turn, mirror, color, shadowColor: extrusionColor(color), animated };
 }
 
 export function createHoleySvg(options = {}) {
@@ -475,19 +449,25 @@ export function createHoleySvg(options = {}) {
   const shadowX = numberInRange(options.shadowX, SHADOW_X, -80, 80);
   const shadowY = numberInRange(options.shadowY, SHADOW_Y, -80, 80);
   const shadowSteps = Math.round(numberInRange(options.shadowSteps, SHADOW_STEPS, 1, 32));
-  const shadowColor = normalizeColor(options.shadowColor, darkShadow(color));
+  const shadowColor = normalizeColor(options.shadowColor, extrusionColor(color));
+  const turn = ((Math.round(numberInRange(options.turn, 0, -36000, 36000) / 90) % 4) + 4) % 4 * 90;
   const holes = packedHoleLayout(shape, holeCount, seed);
-  return exportSvg(shape, holes, {
+  return scopeSvg(exportSvg(shape, holes, {
+    doodle: options.doodle === true,
+    transform: orientation(turn, options.mirror === true),
     animated: options.animated,
     duration: options.duration,
     seed,
     shadowColor,
+    // Doodles keep their ink shadow unless a shadow color is asked for.
+    doodleShadow: options.shadowColor === undefined ? undefined : shadowColor,
     shadowX,
     shadowY,
     shadowSteps
-  });
+  }), options.idPrefix);
 }
 
+let mountSequence = 0;
 export function mountHoleyShape(target, options = {}) {
   const element = typeof target === 'string' && isBrowser ? document.querySelector(target) : target;
   if (!element || typeof element.replaceChildren !== 'function') {
@@ -495,10 +475,18 @@ export function mountHoleyShape(target, options = {}) {
   }
 
   let currentOptions = { ...options };
+  const idPrefix = `mount-${++mountSequence}`;
+  const ownerDocument = element.ownerDocument;
+  let mounted;
+  let destroyed = false;
   const render = () => {
-    const template = document.createElement('template');
-    template.innerHTML = createHoleySvg(currentOptions).trim();
-    element.replaceChildren(template.content.firstElementChild);
+    if (destroyed) return;
+    const template = ownerDocument.createElement('template');
+    template.innerHTML = createHoleySvg({ ...currentOptions, idPrefix }).trim();
+    const next = template.content.firstElementChild;
+    if (mounted?.parentNode === element) mounted.replaceWith(next);
+    else element.append(next);
+    mounted = next;
   };
   render();
 
@@ -509,149 +497,13 @@ export function mountHoleyShape(target, options = {}) {
       render();
     },
     shuffle() {
-      currentOptions.seed = (Number(currentOptions.seed) || 0) + 1;
+      const seed = Math.trunc(numberInRange(currentOptions.seed, 0, -1000000, 1000000));
+      currentOptions.seed = seed >= 1000000 ? -1000000 : seed + 1;
       render();
     },
     destroy() {
-      element.replaceChildren();
+      destroyed = true;
+      mounted?.remove();
     }
   };
 }
-
-function downloadSvg(shape, holes) {
-  const source = exportSvg(shape, holes);
-  const url = URL.createObjectURL(new Blob([source], { type: 'image/svg+xml' }));
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = `${shape.key}-${holes.length}-holes.svg`;
-  link.click();
-  URL.revokeObjectURL(url);
-}
-
-if (collection) shapes.forEach((shape, index) => {
-  const number = String(index + 1).padStart(2, '0');
-  const holeLimit = Math.min(MAX_HOLES, shape.holes.length);
-  const wide = index === 0 || index === shapes.length - 1;
-  const card = document.createElement('article');
-  card.className = `form-card${wide ? ' form-card--wide' : ''}`;
-  card.dataset.index = number;
-  card.innerHTML = `
-    <div class="card-meta"><span>${number}</span><h2>${shape.name}</h2><span>MAX ${String(holeLimit).padStart(2, '0')}</span></div>
-    <div class="stage" style="background:${shape.bg}">
-      <div class="shape-art${wide ? ' shape-art--large' : ''}"></div>
-      ${index === 0 ? '<span class="orbit-line" aria-hidden="true"></span>' : ''}
-      ${index === shapes.length - 1 ? '<span class="crosshair" aria-hidden="true"></span>' : ''}
-    </div>
-    <div class="card-actions">
-      <label class="hole-control"><span>HOLES</span><input class="hole-range" type="range" min="0" max="${holeLimit}" value="${Math.min(shape.initial, holeLimit)}"/><output class="hole-count"></output></label>
-      <button class="shuffle" type="button">SHUFFLE ↻</button>
-      <button class="download" type="button">GET SVG <span>↓</span></button>
-    </div>`;
-  collection.append(card);
-  const state = { count: Math.min(shape.initial, holeLimit), seed: 0, limit: holeLimit };
-  states.set(shape.key, state);
-  renderShape(card, shape, state);
-
-  card.querySelector('.hole-range').addEventListener('input', (event) => {
-    state.count = Number(event.target.value);
-    renderShape(card, shape, state);
-  });
-  card.querySelector('.shuffle').addEventListener('click', () => {
-    state.seed += 1;
-    renderShape(card, shape, state);
-  });
-  card.querySelector('.download').addEventListener('click', () => {
-    downloadSvg(shape, packedHoleLayout(shape, state.count, state.seed));
-  });
-});
-
-const presentApp = isHoleyApp ? document.querySelector('#present-app') : null;
-
-if (presentApp) {
-  const art = document.querySelector('#present-art');
-  const shapePicker = document.querySelector('#shape-picker');
-  const colorPicker = document.querySelector('#color-picker');
-  const range = document.querySelector('#present-holes');
-  const count = document.querySelector('#present-count');
-  const selectedName = document.querySelector('#selected-name');
-  const shuffle = document.querySelector('#present-shuffle');
-  const download = document.querySelector('#present-download');
-  const canvas = document.querySelector('.present-canvas');
-  const palette = ['#6337FF', '#9BED00', '#FF0878', '#2878FF', '#FF6A00', '#00DBFF', '#FFD000', '#C94DFF', '#00D7B9'];
-  const presentState = { index: 0, count: shapes[0].initial, seed: 0, color: shapes[0].color };
-
-  const activeShape = () => ({ ...shapes[presentState.index], color: presentState.color });
-
-  function syncPresentControls() {
-    const shape = shapes[presentState.index];
-    const limit = Math.min(MAX_HOLES, shape.holes.length);
-    selectedName.textContent = shape.name;
-    range.max = limit;
-    range.value = presentState.count;
-    count.textContent = `${String(presentState.count).padStart(2, '0')} / ${String(limit).padStart(2, '0')}`;
-    shapePicker.querySelectorAll('.shape-option').forEach((button, index) => {
-      button.classList.toggle('is-active', index === presentState.index);
-      button.setAttribute('aria-pressed', String(index === presentState.index));
-    });
-    colorPicker.querySelectorAll('.color-option').forEach((button) => {
-      const active = button.dataset.color === presentState.color;
-      button.classList.toggle('is-active', active);
-      button.setAttribute('aria-pressed', String(active));
-    });
-  }
-
-  function renderPresent() {
-    const shape = activeShape();
-    const holes = packedHoleLayout(shape, presentState.count, presentState.seed);
-    art.innerHTML = objectMarkup(shape, holes, 'present', true, { seed: presentState.seed });
-    syncPresentControls();
-  }
-
-  shapes.forEach((shape, index) => {
-    const button = document.createElement('button');
-    const previewHoles = packedHoleLayout(shape, Math.min(3, shape.holes.length), 0);
-    button.className = 'shape-option';
-    button.type = 'button';
-    button.setAttribute('aria-label', shape.name);
-    button.innerHTML = `<span class="shape-thumb">${svgMarkup(shape, previewHoles, 'picker-shape', `picker-${index}`)}</span><span>${String(index + 1).padStart(2, '0')}</span>`;
-    button.addEventListener('click', () => {
-      presentState.index = index;
-      presentState.count = Math.min(shape.initial, MAX_HOLES, shape.holes.length);
-      presentState.seed = 0;
-      presentState.color = shape.color;
-      renderPresent();
-    });
-    shapePicker.append(button);
-  });
-
-  palette.forEach((color) => {
-    const button = document.createElement('button');
-    button.className = 'color-option';
-    button.type = 'button';
-    button.dataset.color = color;
-    button.style.setProperty('--swatch', color);
-    button.setAttribute('aria-label', `Use color ${color}`);
-    button.addEventListener('click', () => {
-      presentState.color = color;
-      renderPresent();
-    });
-    colorPicker.append(button);
-  });
-
-  range.addEventListener('input', () => {
-    presentState.count = Number(range.value);
-    renderPresent();
-  });
-
-  shuffle.addEventListener('click', () => {
-    presentState.seed += 1;
-    renderPresent();
-  });
-
-  download.addEventListener('click', () => {
-    const shape = activeShape();
-    downloadSvg(shape, packedHoleLayout(shape, presentState.count, presentState.seed));
-  });
-
-  renderPresent();
-}