holey-shapes 0.1.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # holey-shapes
 
-Solid, perforated shapes for the web and SwiftUI, with a connected extrusion and a built-in hover spin. Pick from 15 shapes, set the face and shadow colors, and control the hole layout.
+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.
 
 [live playground](https://holey-shapes.aakashreddy.com) · [npm package](https://www.npmjs.com/package/holey-shapes) · [source](https://github.com/skyaara/holey-shapes)
 
@@ -18,7 +18,7 @@ In Xcode, add `https://github.com/skyaara/holey-shapes` as a package dependency,
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/skyaara/holey-shapes.git", from: "0.1.2")
+    .package(url: "https://github.com/skyaara/holey-shapes.git", from: "2.0.0")
 ]
 ```
 
@@ -31,7 +31,7 @@ import SwiftUI
 struct Logo: View {
     var body: some View {
         HoleyShapeView(
-            .flower,
+            .prism,
             faceColor: HoleyColor(hex: "#FF4FA3"),
             shadowColor: HoleyColor(hex: "#7A1748"),
             holes: 6,
@@ -42,7 +42,75 @@ struct Logo: View {
 }
 ```
 
-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. The pointer hover animation follows Reduce Motion automatically.
+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
 
@@ -50,7 +118,7 @@ The Swift SDK supports iOS 16+, macOS 13+, tvOS 16+, and visionOS 1+. It uses as
 import { createHoleySvg } from 'holey-shapes';
 
 const svg = createHoleySvg({
-  shape: 'flower',
+  shape: 'prism',
   color: '#FF4FA3',
   shadowColor: '#7A1748',
   holes: 6,
@@ -102,13 +170,13 @@ The generated SVG scales to its container:
 | `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 spin |
-| `duration` | `900` | Spin duration in milliseconds |
+| `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`, `flower`, and `bowtie`.
+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:
 
@@ -122,6 +190,6 @@ for (const { key, name, color } of shapeNames) {
 
 ## Browser support
 
-The package has no runtime dependencies. Browsers with Canvas `Path2D` get the full packed-hole layout. Server-side rendering uses the built-in deterministic fallback layout.
+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.
 
 The hover animation respects `prefers-reduced-motion`.

package/geometry.js

@@ -0,0 +1,95 @@
+// Geometry for the absolute SVG commands used by the built-in shapes.
+// Curves are flattened within 0.01 viewBox units, well below the packing rim.
+// Both Node and browsers use this code so layout never depends on Canvas.
+export function compileShapePath(source) {
+  const tokens = source.match(/[a-zA-Z]|[-+]?(?:\d*\.\d+|\d+\.?\d*)(?:e[-+]?\d+)?/g) || [];
+  const edges = [];
+  let i = 0, command, x = 0, y = 0, startX = 0, startY = 0;
+  const number = () => {
+    const value = Number(tokens[i++]);
+    if (!Number.isFinite(value)) throw new Error('Invalid shape path');
+    return value;
+  };
+  const line = (nx, ny) => {
+    if (y !== ny) edges.push({ x, y, nx, ny });
+    x = nx; y = ny;
+  };
+  function quadratic(x0, y0, cx, cy, x1, y1) {
+    // The curve's deviation from its chord is at most half this distance.
+    if (Math.hypot(cx - (x0 + x1) / 2, cy - (y0 + y1) / 2) <= 0.02) {
+      line(x1, y1);
+      return;
+    }
+    const ax = (x0 + cx) / 2, ay = (y0 + cy) / 2;
+    const bx = (cx + x1) / 2, by = (cy + y1) / 2;
+    const mx = (ax + bx) / 2, my = (ay + by) / 2;
+    quadratic(x0, y0, ax, ay, mx, my);
+    quadratic(mx, my, bx, by, x1, y1);
+  }
+  while (i < tokens.length) {
+    if (/^[a-zA-Z]$/.test(tokens[i])) command = tokens[i++];
+    switch (command) {
+      case 'M':
+        x = number(); y = number(); startX = x; startY = y; command = 'L';
+        break;
+      case 'L': line(number(), number()); break;
+      case 'H': line(number(), y); break;
+      case 'V': line(x, number()); break;
+      case 'Q': {
+        const cx = number(), cy = number(), nx = number(), ny = number();
+        quadratic(x, y, cx, cy, nx, ny);
+        break;
+      }
+      case 'A': {
+        let rx = Math.abs(number()), ry = Math.abs(number());
+        const rotation = number() * Math.PI / 180;
+        const large = number(), sweep = number(), nx = number(), ny = number();
+        if (!rx || !ry) { line(nx, ny); break; }
+        if (x === nx && y === ny) break;
+        const c = Math.cos(rotation), s = Math.sin(rotation);
+        const dx = (x - nx) / 2, dy = (y - ny) / 2;
+        const px = c * dx + s * dy, py = -s * dx + c * dy;
+        const scale = Math.hypot(px / rx, py / ry);
+        if (scale > 1) { rx *= scale; ry *= scale; }
+        const factor = (large === sweep ? -1 : 1) * Math.sqrt(Math.max(0,
+          (rx * rx * ry * ry - rx * rx * py * py - ry * ry * px * px) /
+          (rx * rx * py * py + ry * ry * px * px)));
+        const cx = factor * rx * py / ry, cy = -factor * ry * px / rx;
+        const centerX = c * cx - s * cy + (x + nx) / 2;
+        const centerY = s * cx + c * cy + (y + ny) / 2;
+        const angle = Math.atan2((py - cy) / ry, (px - cx) / rx);
+        let delta = Math.atan2((-py - cy) / ry, (-px - cx) / rx) - angle;
+        if (sweep && delta < 0) delta += Math.PI * 2;
+        if (!sweep && delta > 0) delta -= Math.PI * 2;
+        const steps = Math.ceil(Math.abs(delta) / (2 * Math.acos(1 - Math.min(1, 0.01 / Math.max(rx, ry)))));
+        for (let step = 1; step < steps; step++) {
+          const a = angle + delta * step / steps;
+          line(centerX + c * rx * Math.cos(a) - s * ry * Math.sin(a),
+            centerY + s * rx * Math.cos(a) + c * ry * Math.sin(a));
+        }
+        line(nx, ny);
+        break;
+      }
+      case 'Z': line(startX, startY); command = null; break;
+      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();
+  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);
+    }
+  }
+  return {
+    contains(px, py) {
+      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;
+      }
+      return winding !== 0;
+    }
+  };
+}

package/index.d.ts

@@ -12,7 +12,6 @@ export type HoleyShapeKey =
   | 'chevron'
   | 'long-bar'
   | 'flower-star'
-  | 'flower'
   | 'bowtie';
 
 export interface HoleyOptions {
@@ -43,5 +42,6 @@ export interface HoleyMount {
 
 export const shapeNames: readonly HoleyShapeInfo[];
 export const shapes: readonly Record<string, unknown>[];
+export function seededHoleyOptions(identity: string, animated?: boolean): HoleyOptions;
 export function createHoleySvg(options?: HoleyOptions): string;
 export function mountHoleyShape(target: string | Element, options?: HoleyOptions): HoleyMount;

package/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "holey-shapes",
-  "version": "0.1.2",
-  "description": "Colorful perforated SVG shapes with solid extrusion and hover animation.",
+  "version": "2.0.0",
+  "description": "Colorful perforated SVG shapes with solid extrusion and animated holes.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -31,6 +31,7 @@
   "files": [
     "index.js",
     "script.js",
+    "geometry.js",
     "index.d.ts",
     "README.md",
     "LICENSE"
@@ -57,7 +58,7 @@
     "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/site.test.mjs",
+    "test": "node tests/package.test.mjs && node tests/packing.test.mjs && node tests/site.test.mjs",
     "prepublishOnly": "npm test && npm run build"
   },
   "devDependencies": {

package/script.js

@@ -1,3 +1,5 @@
+import { compileShapePath } from './geometry.js';
+
 const h = (cx, cy, rx, ry, rotate = 0) => ({ cx, cy, rx, ry, rotate });
 
 const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
@@ -110,11 +112,6 @@ export const shapes = [
     path: 'M274.7 121Q467.8 126.3 314.6 244Q369.3 429.2 210 320Q50.7 429.2 105.4 244Q-47.8 126.3 145.3 121Q210 -61 274.7 121Z',
     holes: [h(210,104,18,24),h(304,174,23,17,20),h(269,282,18,24,-22),h(151,282,22,17,18),h(116,174,17,23,-18),h(210,210,23,18),h(254,211,16,21,12),h(168,210,16,21,-12)]
   },
-  {
-    key: 'flower', name: 'Daisy flower', color: '#C94DFF', bg: '#F2D8FF', initial: 6,
-    path: 'M315 210A105 105 0 1 1 105 210A105 105 0 1 1 315 210ZM210 20A60 90 0 1 1 210 200A60 90 0 1 1 210 20ZM374.5 115A60 90 60 1 1 218.7 205A60 90 60 1 1 374.5 115ZM374.5 305A60 90 120 1 1 218.7 215A60 90 120 1 1 374.5 305ZM210 400A60 90 0 1 1 210 220A60 90 0 1 1 210 400ZM45.5 305A60 90 60 1 1 201.3 215A60 90 60 1 1 45.5 305ZM45.5 115A60 90 120 1 1 201.3 205A60 90 120 1 1 45.5 115Z',
-    holes: [h(210,104,18,24),h(304,174,23,17,20),h(269,282,18,24,-22),h(151,282,22,17,18),h(116,174,17,23,-18),h(210,210,23,18),h(254,211,16,21,12),h(168,210,16,21,-12)]
-  },
   {
     key: 'bowtie', name: 'Bowtie slab', color: '#00D7B9', bg: '#D0F7F0', initial: 6,
     path: 'M40 70H380L286 210 380 350H40L134 210Z',
@@ -128,77 +125,18 @@ const SHADOW_X = 18;
 const SHADOW_Y = 21;
 const SHADOW_STEPS = 12;
 const states = new Map();
-let packingContext = null;
 const packingCache = new Map();
-const SHOWCASE_MOTIONS = [
-  ['scatter', '4.2s', '-1.4s'],
-  ['magnet', '4.6s', '-3.2s'],
-  ['blinkwave', '3.7s', '-2.1s'],
-  ['orbit', '5.2s', '-.6s'],
-  ['hop', '3.5s', '-1.9s'],
-  ['scan', '4.3s', '-.8s'],
-  ['wobble', '4.8s', '-2.4s'],
-  ['pinch', '3.9s', '-1.1s'],
-  ['carousel', '5.6s', '-4.1s'],
-  ['heartbeat', '3.8s', '-2.2s'],
-  ['peek', '4.5s', '-3.5s'],
-  ['shuffle', '4.1s', '-1.7s'],
-  ['tumble', '4.7s', '-3.3s'],
-  ['ripple', '3.6s', '-1.2s'],
-  ['breathe', '5s', '-2.5s']
-];
-const showcaseObserver = isBrowser && typeof IntersectionObserver === 'function'
-  ? new IntersectionObserver((entries) => {
-      entries.forEach((entry) => entry.target.classList.toggle('is-showcase-visible', entry.isIntersecting));
-    }, { rootMargin: '120px 0px', threshold: 0.05 })
-  : null;
-
-function applyShowcaseMotion(element, index) {
-  const [name, duration, delay] = SHOWCASE_MOTIONS[index % SHOWCASE_MOTIONS.length];
-  element.dataset.motion = name;
-  element.style.setProperty('--motion-duration', duration);
-  element.style.setProperty('--motion-delay', delay);
-  if (showcaseObserver) showcaseObserver.observe(element);
-  else element.classList.add('is-showcase-visible');
-}
-
-function getPackingContext() {
-  if (packingContext) return packingContext;
-  if (!isBrowser || typeof Path2D === 'undefined') return null;
-  const packingCanvas = document.createElement('canvas');
-  packingCanvas.width = 420;
-  packingCanvas.height = 420;
-  packingContext = packingCanvas.getContext('2d');
-  return packingContext;
-}
 
 const holeMarkup = ({ cx, cy, rx, ry, rotate }) =>
   `<ellipse cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}"${rotate ? ` transform="rotate(${rotate} ${cx} ${cy})"` : ''}/>`;
 
-const showcaseHoleMarkup = (hole, index) => {
-  const angle = (index * 137.5 * Math.PI) / 180;
-  const scatterX = Math.round(Math.cos(angle) * 17);
-  const scatterY = Math.round(Math.sin(angle) * 17);
-  const inwardX = Math.round((210 - hole.cx) * .26);
-  const inwardY = Math.round((210 - hole.cy) * .26);
-  const outwardX = Math.round((hole.cx - 210) * .11);
-  const outwardY = Math.round((hole.cy - 210) * .11);
-  const turn = (index % 2 ? 1 : -1) * (14 + (index % 3) * 7);
-  const variables = [
-    `--hole-origin:${hole.cx}px ${hole.cy}px`,
-    `--scatter-x:${scatterX}px`,
-    `--scatter-y:${scatterY}px`,
-    `--scatter-back-x:${Math.round(scatterX * -.3)}px`,
-    `--scatter-back-y:${Math.round(scatterY * -.3)}px`,
-    `--in-x:${inwardX}px`,
-    `--in-y:${inwardY}px`,
-    `--out-x:${outwardX}px`,
-    `--out-y:${outwardY}px`,
-    `--turn:${turn}deg`,
-    `--turn-back:${turn * -1}deg`
-  ].join(';');
-  return `<g class="hole-motion" style="${variables}">${holeMarkup(hole)}</g>`;
-};
+function hoverHoleMarkup(hole, index, seed = 0, duration = 900) {
+  const durationNoise = seededNoise(index + 1, 17, seed);
+  const delayNoise = seededNoise(index + 1, 43, seed);
+  const pulseDuration = Math.round(duration * (0.42 + durationNoise * 0.16));
+  const delay = Math.round(duration * (0.04 + delayNoise * 0.34));
+  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('#', '');
@@ -207,20 +145,17 @@ function darkShadow(color, factor = 0.52) {
 }
 
 function circleFits(path, cx, cy, radius) {
-  const context = getPackingContext();
-  if (!context) return false;
   for (let step = 0; step < 32; step += 1) {
     const angle = (Math.PI * 2 * step) / 32;
     const x = cx + Math.cos(angle) * radius;
     const y = cy + Math.sin(angle) * radius;
-    if (!context.isPointInPath(path, x, y)) return false;
+    if (!path.contains(x, y)) return false;
   }
   return true;
 }
 
 function boundaryClearance(path, cx, cy) {
-  const context = getPackingContext();
-  if (!context || !context.isPointInPath(path, cx, cy)) return 0;
+  if (!path.contains(cx, cy)) return 0;
   let low = 0;
   let high = 180;
   for (let pass = 0; pass < 9; pass += 1) {
@@ -233,13 +168,11 @@ function boundaryClearance(path, cx, cy) {
 
 function packingCandidates(shape) {
   if (packingCache.has(shape.key)) return packingCache.get(shape.key);
-  const context = getPackingContext();
-  if (!context) return { path: null, candidates: [] };
-  const path = new Path2D(shape.path);
+  const path = compileShapePath(shape.path);
   const candidates = [];
   for (let y = 50; y <= 370; y += 12) {
     for (let x = 50; x <= 370; x += 12) {
-      if (!context.isPointInPath(path, x, y)) continue;
+      if (!path.contains(x, y)) continue;
       const clearance = boundaryClearance(path, x, y);
       if (clearance >= 17) candidates.push({ x, y, clearance });
     }
@@ -271,13 +204,118 @@ function assignVoronoiCells(points, candidates) {
   return cells;
 }
 
+// Shrink to the smallest fitted area so spacing and oval proportions stay intact.
+function equalizeHoleAreas(holes) {
+  if (!holes.length) return holes;
+  const targetArea = Math.min(...holes.map(({ rx, ry }) => rx * ry));
+  return holes.map((hole) => {
+    const scale = Math.sqrt(targetArea / (hole.rx * hole.ry));
+    return {
+      ...hole,
+      rx: Number((hole.rx * scale).toFixed(3)),
+      ry: Number((hole.ry * scale).toFixed(3))
+    };
+  });
+}
+
+// Equal-area ellipses use radius sqrt(rx * ry). Support projections give a
+// separating line with a 12-unit gap, including for differently rotated ovals.
+const packingDirections = Array.from({ length: 48 }, (_, i) => {
+  const angle = i * Math.PI * 2 / 48;
+  return { x: Math.cos(angle), y: Math.sin(angle) };
+});
+const perimeterDirections = Array.from({ length: 192 }, (_, i) => {
+  const angle = i * Math.PI * 2 / 192;
+  return { x: Math.cos(angle), y: Math.sin(angle) };
+});
+const optimizedLayoutCache = new Map();
+
+function maximizeHoleAreas(shape, holes) {
+  if (!holes.length) return holes;
+  const { path } = packingCandidates(shape);
+  const gap = 12;
+  const profiles = holes.map(hole => {
+    const a = Math.sqrt(hole.rx / hole.ry);
+    const b = 1 / a;
+    const angle = hole.rotate * Math.PI / 180;
+    const c = Math.cos(angle), s = Math.sin(angle);
+    return {
+      a, b,
+      support: packingDirections.map(n => Math.hypot(a * (n.x * c + n.y * s), b * (-n.x * s + n.y * c))),
+      edge: perimeterDirections.map(n => {
+        const nx = n.x / a, ny = n.y / b;
+        const length = Math.hypot(nx, ny);
+        return { x: a * n.x * c - b * n.y * s, y: a * n.x * s + b * n.y * c,
+          nx: (nx * c - ny * s) / length, ny: (nx * s + ny * c) / length };
+      })
+    };
+  });
+  const points = holes.map(h => ({ x: h.cx, y: h.cy }));
+  function boundaryLimit(point, profile) {
+    if (!path.contains(point.x, point.y)) return 0;
+    let low = 0, high = 180;
+    for (let pass = 0; pass < 11; pass++) {
+      const radius = (low + high) / 2;
+      // An extra rim unit covers the space between perimeter samples.
+      const fits = profile.edge.every(e => path.contains(
+        point.x + radius * e.x + (gap + 1) * e.nx, point.y + radius * e.y + (gap + 1) * e.ny));
+      if (fits) low = radius; else high = radius;
+    }
+    return low;
+  }
+  const boundaries = points.map((p, i) => boundaryLimit(p, profiles[i]));
+  function capacity(point, index, boundary) {
+    let limit = boundary;
+    points.forEach((other, j) => {
+      if (j === index) return;
+      let separation = 0;
+      packingDirections.forEach((n, k) => {
+        separation = Math.max(separation, (Math.abs((point.x - other.x) * n.x + (point.y - other.y) * n.y) - gap)
+          / (profiles[index].support[k] + profiles[j].support[k]));
+      });
+      limit = Math.min(limit, separation);
+    });
+    return limit;
+  }
+  // Coordinate search improves each constrained hole, then refines its position.
+  for (const step of [12, 6, 3, 1.5]) {
+    for (let pass = 0; pass < 3; pass++) {
+      let moved = false;
+      points.forEach((point, i) => {
+        let best = point, bestBoundary = boundaries[i];
+        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 };
+          const boundary = boundaryLimit(candidate, profiles[i]);
+          const limit = capacity(candidate, i, boundary);
+          if (limit > bestLimit + 0.02) {
+            best = candidate; bestBoundary = boundary; bestLimit = limit;
+          }
+        }
+        if (best !== point) moved = true;
+        points[i] = best; boundaries[i] = bestBoundary;
+      });
+      if (!moved) break;
+    }
+  }
+  const radius = Math.max(0, Math.min(...points.map((p, i) => capacity(p, i, boundaries[i]))) - 0.05);
+  return holes.map((hole, i) => ({ ...hole, cx: points[i].x, cy: points[i].y,
+    rx: Number((radius * profiles[i].a).toFixed(3)), ry: Number((radius * profiles[i].b).toFixed(3)) }));
+}
+
 function packedHoleLayout(shape, count, seed) {
+  const key = `${shape.key}:${count}:${seed}`;
+  if (optimizedLayoutCache.has(key)) return optimizedLayoutCache.get(key);
+  const holes = maximizeHoleAreas(shape, initialHoleLayout(shape, count, seed));
+  if (optimizedLayoutCache.size >= 512) optimizedLayoutCache.delete(optimizedLayoutCache.keys().next().value);
+  optimizedLayoutCache.set(key, holes);
+  return holes;
+}
+
+function initialHoleLayout(shape, count, seed) {
   if (count === 0) return [];
   const { candidates } = packingCandidates(shape);
-  if (!candidates.length) {
-    const start = ((Math.trunc(seed) % shape.holes.length) + shape.holes.length) % shape.holes.length;
-    return Array.from({ length: count }, (_, index) => ({ ...shape.holes[(start + index) % shape.holes.length] }));
-  }
+  if (candidates.length < count) throw new Error(`Insufficient packing space for ${shape.key}`);
   const maximumClearance = Math.max(...candidates.map(({ clearance }) => clearance));
   const starterPool = candidates.filter(({ clearance }) => clearance >= maximumClearance * 0.72);
   const first = seed === 0
@@ -320,12 +358,12 @@ function packedHoleLayout(shape, count, seed) {
   }
 
   const cells = assignVoronoiCells(selected, candidates);
-  return selected.map((point, index) => {
+  return equalizeHoleAreas(selected.map((point, index) => {
     const nearest = selected.length === 1
       ? Infinity
       : Math.min(...selected.filter((_, otherIndex) => otherIndex !== index).map((other) =>
           Math.hypot(point.x - other.x, point.y - other.y)));
-    const style = shape.holes[(index + seed) % shape.holes.length];
+    const style = shape.holes[((index + seed) % shape.holes.length + shape.holes.length) % shape.holes.length];
     const styleRadius = Math.max(style.rx, style.ry);
     const aspectArea = (style.rx / styleRadius) * (style.ry / styleRadius);
     const territoryArea = cells[index].length * 144;
@@ -339,7 +377,7 @@ function packedHoleLayout(shape, count, seed) {
       ry: Math.round(radius * (style.ry / styleRadius)),
       rotate: style.rotate
     };
-  });
+  }));
 }
 
 function svgMarkup(shape, holes, className, maskSuffix, accessible = false) {
@@ -369,27 +407,33 @@ 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) {
+function objectMarkup(shape, holes, suffix, accessible = false, options = {}) {
   const maskId = `mask-${shape.key}-${suffix}`;
   const filterId = `extrusion-${shape.key}-${suffix}`;
-  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"/>${holes.map(showcaseHoleMarkup).join('')}</mask>${extrusionFilterMarkup(shape, filterId)}</defs><g filter="url(#${filterId})"><g class="shape-spin"><path d="${shape.path}" fill="${shape.color}" mask="url(#${maskId})"/></g></g></svg>`;
+  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);
+  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;
 }
 
 function exportSvg(shape, holes, options = {}) {
-  const maskHoles = holes.map(holeMarkup).join('');
   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);
+  const maskHoles = options.animated === false
+    ? holes.map(holeMarkup).join('')
+    : holes.map((hole, index) => hoverHoleMarkup(hole, index, seed, duration)).join('');
   const animation = options.animated === false
     ? ''
-    : `<style>.spin-group{transform-box:fill-box;transform-origin:center;will-change:transform}svg:hover .spin-group{animation:spin ${duration}ms cubic-bezier(.33,0,.2,1) both}@keyframes spin{to{transform:rotate(360deg)}}@media(prefers-reduced-motion:reduce){svg:hover .spin-group{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)"><g class="spin-group"><path d="${shape.path}" fill="${shape.color}" mask="url(#h)"/></g></g></svg>`;
+    : `<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>`;
 }
 
 function normalizeColor(color, fallback) {
@@ -403,6 +447,25 @@ function numberInRange(value, fallback, min, max) {
 
 export const shapeNames = Object.freeze(shapes.map(({ key, name, color }) => ({ key, name, color })));
 
+export function seededHoleyOptions(identity, animated = true) {
+  const bytes = new TextEncoder().encode(String(identity));
+  let hash = 14695981039346656037n;
+  for (const byte of bytes) {
+    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));
+  };
+  const shape = shapes[Number(next() % BigInt(shapes.length))];
+  const seed = Number(next() % 1000001n);
+  return { shape: shape.key, seed, animated };
+}
+
 export function createHoleySvg(options = {}) {
   const source = shapes.find(({ key }) => key === options.shape) || shapes[0];
   const color = normalizeColor(options.color, source.color);
@@ -417,6 +480,7 @@ export function createHoleySvg(options = {}) {
   return exportSvg(shape, holes, {
     animated: options.animated,
     duration: options.duration,
+    seed,
     shadowColor,
     shadowX,
     shadowY,
@@ -484,8 +548,6 @@ if (collection) shapes.forEach((shape, index) => {
       <button class="download" type="button">GET SVG <span>↓</span></button>
     </div>`;
   collection.append(card);
-  applyShowcaseMotion(card, index);
-
   const state = { count: Math.min(shape.initial, holeLimit), seed: 0, limit: holeLimit };
   states.set(shape.key, state);
   renderShape(card, shape, state);
@@ -541,8 +603,7 @@ if (presentApp) {
   function renderPresent() {
     const shape = activeShape();
     const holes = packedHoleLayout(shape, presentState.count, presentState.seed);
-    applyShowcaseMotion(art, presentState.index);
-    art.innerHTML = objectMarkup(shape, holes, 'present', true);
+    art.innerHTML = objectMarkup(shape, holes, 'present', true, { seed: presentState.seed });
     syncPresentControls();
   }