feat: Add board outline support (#20)

* feat: Remove GapFillSubSolver from RectDiffSolver

Disables and removes the GapFillSubSolver from RectDiffSolver.
The GAP_FILL phase is now skipped, directly transitioning to DONE.
This change involves:
- Removing GapFillSubSolver import.
- Removing activeSubSolver property and its initialization.
- Modifying _step() to skip the GAP_FILL phase.
- Removing GapFillSubSolver usage from computeProgress() and visualize().

* feat: Implement board outline support with inverse obstacles

- Introduced  to  to track areas outside the board outline.
- Implemented  and  geometry helpers to calculate void areas.
- Updated  initialization to add these void areas as obstacles on all layers, preventing expansion outside the board.
- Enhanced visualization to render void areas as dark, semi-transparent overlays.
- Refactored geometry helpers into separate files for better organization.

* fix(viz): Hide outer void padding in visualization and update snapshots

* fix(engine): Exclude void rects from final output mesh

The void rectangles (generated from board outline) act as internal obstacles during solving but should not be part of the final obstacle output.

* refactor: Apply code review feedback (variable naming, EPS import)

Applies feedback from the code review, focusing on variable transparency and proper constant importing.

- Renamed short/non-descriptive variables (e.g., 'ob', 'r', 'zs') to more transparent names ('obstacle', 'rect', 'zLayers') in 'engine.ts' and 'RectDiffSolver.ts'.
- Replaced local 'EPS' definition in 'computeInverseRects.ts' with an import from 'geometry.ts' for consistency.

Author: 0hmX

lib/solvers/RectDiffSolver.ts

@@ -13,36 +13,29 @@ import {
   computeProgress,
 } from "./rectdiff/engine"
 import { rectsToMeshNodes } from "./rectdiff/rectsToMeshNodes"
+import { overlaps } from "./rectdiff/geometry"
 import type { GapFillOptions } from "./rectdiff/gapfill/types"
 import {
   findUncoveredPoints,
   calculateCoverage,
 } from "./rectdiff/gapfill/engine"
-import { GapFillSubSolver } from "./rectdiff/subsolvers/GapFillSubSolver"
 
 /**
  * A streaming, one-step-per-iteration solver for capacity mesh generation.
  */
 export class RectDiffSolver extends BaseSolver {
   private srj: SimpleRouteJson
   private gridOptions: Partial<GridFill3DOptions>
-  private gapFillOptions: Partial<GapFillOptions>
   private state!: RectDiffState
   private _meshNodes: CapacityMeshNode[] = []
 
-  /** Active subsolver for GAP_FILL phases. */
-  declare activeSubSolver: GapFillSubSolver | null
-
   constructor(opts: {
     simpleRouteJson: SimpleRouteJson
     gridOptions?: Partial<GridFill3DOptions>
-    gapFillOptions?: Partial<GapFillOptions>
   }) {
     super()
     this.srj = opts.simpleRouteJson
     this.gridOptions = opts.gridOptions ?? {}
-    this.gapFillOptions = opts.gapFillOptions ?? {}
-    this.activeSubSolver = null
   }
 
   override _setup() {
@@ -60,44 +53,7 @@ export class RectDiffSolver extends BaseSolver {
     } else if (this.state.phase === "EXPANSION") {
       stepExpansion(this.state)
     } else if (this.state.phase === "GAP_FILL") {
-      // Initialize gap fill subsolver if needed
-      if (
-        !this.activeSubSolver ||
-        !(this.activeSubSolver instanceof GapFillSubSolver)
-      ) {
-        const minTrace = this.srj.minTraceWidth || 0.15
-        const minGapSize = Math.max(0.01, minTrace / 10)
-        const boundsSize = Math.min(
-          this.state.bounds.width,
-          this.state.bounds.height,
-        )
-        this.activeSubSolver = new GapFillSubSolver({
-          placed: this.state.placed,
-          options: {
-            minWidth: minGapSize,
-            minHeight: minGapSize,
-            scanResolution: Math.max(0.05, boundsSize / 100),
-            ...this.gapFillOptions,
-          },
-          layerCtx: {
-            bounds: this.state.bounds,
-            layerCount: this.state.layerCount,
-            obstaclesByLayer: this.state.obstaclesByLayer,
-            placedByLayer: this.state.placedByLayer,
-          },
-        })
-      }
-
-      this.activeSubSolver.step()
-
-      if (this.activeSubSolver.solved) {
-        // Transfer results back to main state
-        const output = this.activeSubSolver.getOutput()
-        this.state.placed = output.placed
-        this.state.placedByLayer = output.placedByLayer
-        this.activeSubSolver = null
-        this.state.phase = "DONE"
-      }
+      this.state.phase = "DONE"
     } else if (this.state.phase === "DONE") {
       // Finalize once
       if (!this.solved) {
@@ -112,24 +68,14 @@ export class RectDiffSolver extends BaseSolver {
     this.stats.phase = this.state.phase
     this.stats.gridIndex = this.state.gridIndex
     this.stats.placed = this.state.placed.length
-    if (this.activeSubSolver instanceof GapFillSubSolver) {
-      const output = this.activeSubSolver.getOutput()
-      this.stats.gapsFilled = output.filledCount
-    }
   }
 
   /** Compute solver progress (0 to 1). */
   computeProgress(): number {
     if (this.solved || this.state.phase === "DONE") {
       return 1
     }
-    if (
-      this.state.phase === "GAP_FILL" &&
-      this.activeSubSolver instanceof GapFillSubSolver
-    ) {
-      return 0.85 + 0.1 * this.activeSubSolver.computeProgress()
-    }
-    return computeProgress(this.state) * 0.85
+    return computeProgress(this.state)
   }
 
   override getOutput(): { meshNodes: CapacityMeshNode[] } {
@@ -183,11 +129,6 @@ export class RectDiffSolver extends BaseSolver {
 
   /** Streaming visualization: board + obstacles + current placements. */
   override visualize(): GraphicsObject {
-    // If a subsolver is active, delegate to its visualization
-    if (this.activeSubSolver) {
-      return this.activeSubSolver.visualize()
-    }
-
     const rects: NonNullable<GraphicsObject["rects"]> = []
     const points: NonNullable<GraphicsObject["points"]> = []
     const lines: NonNullable<GraphicsObject["lines"]> = [] // Initialize lines array
@@ -223,12 +164,12 @@ export class RectDiffSolver extends BaseSolver {
     }
 
     // obstacles (rect & oval as bounding boxes)
-    for (const ob of this.srj.obstacles ?? []) {
-      if (ob.type === "rect" || ob.type === "oval") {
+    for (const obstacle of this.srj.obstacles ?? []) {
+      if (obstacle.type === "rect" || obstacle.type === "oval") {
         rects.push({
-          center: { x: ob.center.x, y: ob.center.y },
-          width: ob.width,
-          height: ob.height,
+          center: { x: obstacle.center.x, y: obstacle.center.y },
+          width: obstacle.width,
+          height: obstacle.height,
           fill: "#fee2e2",
           stroke: "#ef4444",
           layer: "obstacle",
@@ -237,6 +178,46 @@ export class RectDiffSolver extends BaseSolver {
       }
     }
 
+    // board void rects
+    if (this.state?.boardVoidRects) {
+      // If outline exists, compute its bbox to hide outer padding voids
+      let outlineBBox: {
+        x: number
+        y: number
+        width: number
+        height: number
+      } | null = null
+
+      if (this.srj.outline && this.srj.outline.length > 0) {
+        const xs = this.srj.outline.map((p) => p.x)
+        const ys = this.srj.outline.map((p) => p.y)
+        const minX = Math.min(...xs)
+        const minY = Math.min(...ys)
+        outlineBBox = {
+          x: minX,
+          y: minY,
+          width: Math.max(...xs) - minX,
+          height: Math.max(...ys) - minY,
+        }
+      }
+
+      for (const r of this.state.boardVoidRects) {
+        // If we have an outline, only show voids that overlap its bbox (hides outer padding)
+        if (outlineBBox && !overlaps(r, outlineBBox)) {
+          continue
+        }
+
+        rects.push({
+          center: { x: r.x + r.width / 2, y: r.y + r.height / 2 },
+          width: r.width,
+          height: r.height,
+          fill: "rgba(0, 0, 0, 0.5)",
+          stroke: "none",
+          label: "void",
+        })
+      }
+    }
+
     // candidate positions (where expansion started from)
     if (this.state?.candidates?.length) {
       for (const cand of this.state.candidates) {

lib/solvers/rectdiff/engine.ts

@@ -20,6 +20,7 @@ import {
   overlaps,
   subtractRect2D,
 } from "./geometry"
+import { computeInverseRects } from "./geometry/computeInverseRects"
 import { buildZIndexMap, obstacleToXYRect, obstacleZs } from "./layers"
 
 /**
@@ -44,11 +45,24 @@ export function initState(
     { length: layerCount },
     () => [],
   )
-  for (const ob of srj.obstacles ?? []) {
-    const r = obstacleToXYRect(ob)
-    if (!r) continue
-    const zs = obstacleZs(ob, zIndexByName)
-    const invalidZs = zs.filter((z) => z < 0 || z >= layerCount)
+
+  // Compute void rects from outline if present
+  let boardVoidRects: XYRect[] = []
+  if (srj.outline && srj.outline.length > 2) {
+    boardVoidRects = computeInverseRects(bounds, srj.outline)
+    // Add void rects as obstacles to ALL layers
+    for (const voidR of boardVoidRects) {
+      for (let z = 0; z < layerCount; z++) {
+        obstaclesByLayer[z]!.push(voidR)
+      }
+    }
+  }
+
+  for (const obstacle of srj.obstacles ?? []) {
+    const rect = obstacleToXYRect(obstacle)
+    if (!rect) continue
+    const zLayers = obstacleZs(obstacle, zIndexByName)
+    const invalidZs = zLayers.filter((z) => z < 0 || z >= layerCount)
     if (invalidZs.length) {
       throw new Error(
         `RectDiffSolver: obstacle uses z-layer indices ${invalidZs.join(
@@ -57,8 +71,9 @@ export function initState(
       )
     }
     // Persist normalized zLayers back onto the shared SRJ so downstream solvers see them.
-    if ((!ob.zLayers || ob.zLayers.length === 0) && zs.length) ob.zLayers = zs
-    for (const z of zs) obstaclesByLayer[z]!.push(r)
+    if ((!obstacle.zLayers || obstacle.zLayers.length === 0) && zLayers.length)
+      obstacle.zLayers = zLayers
+    for (const z of zLayers) obstaclesByLayer[z]!.push(rect)
   }
 
   const trace = Math.max(0.01, srj.minTraceWidth || 0.15)
@@ -97,6 +112,7 @@ export function initState(
     bounds,
     options,
     obstaclesByLayer,
+    boardVoidRects,
     phase: "GRID",
     gridIndex: 0,
     candidates: [],
@@ -426,7 +442,10 @@ export function finalizeRects(state: RectDiffState): Rect3d[] {
   })
 
   // Append obstacle nodes to the output
+  const voidSet = new Set(state.boardVoidRects || [])
   for (const [rect, layerIndices] of layersByObstacleRect.entries()) {
+    if (voidSet.has(rect)) continue // Skip void rects
+
     out.push({
       minX: rect.x,
       minY: rect.y,

lib/solvers/rectdiff/geometry/computeInverseRects.ts

@@ -0,0 +1,108 @@
+import type { XYRect } from "../types"
+import { isPointInPolygon } from "./isPointInPolygon"
+import { EPS } from "../geometry" // Import EPS from common geometry file
+
+/**
+ * Decompose the empty space inside 'bounds' but outside 'polygon' into rectangles.
+ * This uses a coordinate grid approach, ideal for rectilinear polygons.
+ */
+export function computeInverseRects(
+  bounds: XYRect,
+  polygon: Array<{ x: number; y: number }>,
+): XYRect[] {
+  if (!polygon || polygon.length < 3) return []
+
+  // 1. Collect unique sorted X and Y coordinates
+  const xs = new Set<number>([bounds.x, bounds.x + bounds.width])
+  const ys = new Set<number>([bounds.y, bounds.y + bounds.height])
+  for (const p of polygon) {
+    xs.add(p.x)
+    ys.add(p.y)
+  }
+  const xSorted = Array.from(xs).sort((a, b) => a - b)
+  const ySorted = Array.from(ys).sort((a, b) => a - b)
+
+  // 2. Generate grid cells and classify them
+  const rawRects: XYRect[] = []
+  for (let i = 0; i < xSorted.length - 1; i++) {
+    for (let j = 0; j < ySorted.length - 1; j++) {
+      const x0 = xSorted[i]!
+      const x1 = xSorted[i + 1]!
+      const y0 = ySorted[j]!
+      const y1 = ySorted[j + 1]!
+
+      // Check center point
+      const cx = (x0 + x1) / 2
+      const cy = (y0 + y1) / 2
+
+      // If NOT in polygon, it's a void rect
+      if (
+        cx >= bounds.x &&
+        cx <= bounds.x + bounds.width &&
+        cy >= bounds.y &&
+        cy <= bounds.y + bounds.height
+      ) {
+        if (!isPointInPolygon({ x: cx, y: cy }, polygon)) {
+          rawRects.push({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 })
+        }
+      }
+    }
+  }
+
+  // 3. Simple merge pass (horizontal)
+  const finalRects: XYRect[] = []
+
+  // Sort by y then x
+  rawRects.sort((a, b) => {
+    if (Math.abs(a.y - b.y) > EPS) return a.y - b.y
+    return a.x - b.x
+  })
+
+  let current: XYRect | null = null
+  for (const r of rawRects) {
+    if (!current) {
+      current = r
+      continue
+    }
+
+    const sameY = Math.abs(current.y - r.y) < EPS
+    const sameHeight = Math.abs(current.height - r.height) < EPS
+    const touchesX = Math.abs(current.x + current.width - r.x) < EPS
+
+    if (sameY && sameHeight && touchesX) {
+      current.width += r.width
+    } else {
+      finalRects.push(current)
+      current = r
+    }
+  }
+  if (current) finalRects.push(current)
+
+  // 4. Vertical merge pass
+  finalRects.sort((a, b) => {
+    if (Math.abs(a.x - b.x) > EPS) return a.x - b.x
+    return a.y - b.y
+  })
+
+  const mergedVertical: XYRect[] = []
+  current = null
+  for (const r of finalRects) {
+    if (!current) {
+      current = r
+      continue
+    }
+    const sameX = Math.abs(current.x - r.x) < EPS
+    const sameWidth = Math.abs(current.width - r.width) < EPS
+    const touchesY = Math.abs(current.y + current.height - r.y) < EPS
+
+    if (sameX && sameWidth && touchesY) {
+      current.height += r.height
+    } else {
+      mergedVertical.push(current)
+      current = r
+    }
+  }
+  if (current) mergedVertical.push(current)
+
+  return mergedVertical
+}

lib/solvers/rectdiff/geometry/isPointInPolygon.ts

@@ -0,0 +1,20 @@
+/**
+ * Check if a point is inside a polygon using ray casting.
+ */
+export function isPointInPolygon(
+  p: { x: number; y: number },
+  polygon: Array<{ x: number; y: number }>,
+): boolean {
+  let inside = false
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const xi = polygon[i]!.x,
+      yi = polygon[i]!.y
+    const xj = polygon[j]!.x,
+      yj = polygon[j]!.y
+
+    const intersect =
+      yi > p.y !== yj > p.y && p.x < ((xj - xi) * (p.y - yi)) / (yj - yi) + xi
+    if (intersect) inside = !inside
+  }
+  return inside
+}

lib/solvers/rectdiff/types.ts

@@ -49,6 +49,7 @@ export type RectDiffState = {
     maxMultiLayerSpan: number | undefined
   }
   obstaclesByLayer: XYRect[][]
+  boardVoidRects: XYRect[] // newly added for viz
 
   // evolving
   phase: Phase