holey-shapes 1.0.0 → 2.0.0

package/README.md

@@ -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.4")
+    .package(url: "https://github.com/skyaara/holey-shapes.git", from: "2.0.0")
 ]
 ```
 
@@ -62,7 +62,7 @@ Then add the Compose SDK:
 
 ```kotlin
 dependencies {
-    implementation("com.github.skyaara:holey-shapes:v0.1.4")
+    implementation("com.github.skyaara:holey-shapes:v2.0.0")
 }
 ```
 
@@ -81,6 +81,37 @@ HoleyShapeView(
 
 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
@@ -159,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holey-shapes",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Colorful perforated SVG shapes with solid extrusion and animated holes.",
   "type": "module",
   "license": "MIT",
@@ -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';
@@ -123,17 +125,7 @@ const SHADOW_X = 18;
 const SHADOW_Y = 21;
 const SHADOW_STEPS = 12;
 const states = new Map();
-let packingContext = null;
 const packingCache = new Map();
-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})"` : ''}/>`;
@@ -153,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) {
@@ -179,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 });
     }
@@ -245,9 +232,7 @@ const optimizedLayoutCache = new Map();
 
 function maximizeHoleAreas(shape, holes) {
   if (!holes.length) return holes;
-  const context = getPackingContext();
   const { path } = packingCandidates(shape);
-  if (!context || !path) return holes;
   const gap = 12;
   const profiles = holes.map(hole => {
     const a = Math.sqrt(hole.rx / hole.ry);
@@ -267,12 +252,12 @@ function maximizeHoleAreas(shape, holes) {
   });
   const points = holes.map(h => ({ x: h.cx, y: h.cy }));
   function boundaryLimit(point, profile) {
-    if (!context.isPointInPath(path, point.x, point.y)) return 0;
+    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 => context.isPointInPath(path,
+      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;
     }
@@ -330,10 +315,7 @@ function packedHoleLayout(shape, count, seed) {
 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 equalizeHoleAreas(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
@@ -381,7 +363,7 @@ function initialHoleLayout(shape, count, seed) {
       ? 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;