@tscircuit/rectdiff 0.0.3 → 0.0.5

package/lib/solvers/rectdiff/engine.ts

@@ -22,6 +22,9 @@ import {
 } from "./geometry"
 import { buildZIndexMap, obstacleToXYRect, obstacleZs } from "./layers"
 
+/**
+ * Initialize the RectDiff solver state from SimpleRouteJson.
+ */
 export function initState(
   srj: SimpleRouteJson,
   opts: Partial<GridFill3DOptions>,
@@ -106,7 +109,9 @@ export function initState(
   }
 }
 
-// Build per-layer list of "hard" placed rects = nodes spanning all layers
+/**
+ * Build per-layer list of "hard" placed rects (nodes spanning all layers).
+ */
 function buildHardPlacedByLayer(state: RectDiffState): XYRect[][] {
   const out: XYRect[][] = Array.from({ length: state.layerCount }, () => [])
   for (const p of state.placed) {
@@ -117,23 +122,27 @@ function buildHardPlacedByLayer(state: RectDiffState): XYRect[][] {
   return out
 }
 
+/**
+ * Check if a point is occupied on ALL layers.
+ */
 function isFullyOccupiedAtPoint(
   state: RectDiffState,
-  x: number,
-  y: number,
+  point: { x: number; y: number },
 ): boolean {
   for (let z = 0; z < state.layerCount; z++) {
     const obs = state.obstaclesByLayer[z] ?? []
     const placed = state.placedByLayer[z] ?? []
     const occ =
-      obs.some((b) => containsPoint(b, x, y)) ||
-      placed.some((b) => containsPoint(b, x, y))
+      obs.some((b) => containsPoint(b, point.x, point.y)) ||
+      placed.some((b) => containsPoint(b, point.x, point.y))
     if (!occ) return false
   }
   return true
 }
 
-/** Shrink/split any *soft* (non-full-stack) nodes overlapped by `newIndex` */
+/**
+ * Shrink/split any soft (non-full-stack) nodes overlapped by the newcomer.
+ */
 function resizeSoftOverlaps(state: RectDiffState, newIndex: number) {
   const newcomer = state.placed[newIndex]!
   const { rect: newR, zLayers: newZs } = newcomer
@@ -198,7 +207,9 @@ function resizeSoftOverlaps(state: RectDiffState, newIndex: number) {
   }
 }
 
-/** One micro-step during the GRID phase: handle (or fetch) exactly one candidate */
+/**
+ * One micro-step during the GRID phase: handle exactly one candidate.
+ */
 export function stepGrid(state: RectDiffState): void {
   const {
     gridSizes,
@@ -216,14 +227,14 @@ export function stepGrid(state: RectDiffState): void {
 
   // Ensure candidates exist for this grid
   if (state.candidates.length === 0 && state.consumedSeedsThisGrid === 0) {
-    state.candidates = computeCandidates3D(
-      state.bounds,
-      grid,
-      state.layerCount,
-      state.obstaclesByLayer,
-      state.placedByLayer, // all nodes (soft + hard) for fully-occupied test
-      hardPlacedByLayer, // hard blockers for ranking/span
-    )
+    state.candidates = computeCandidates3D({
+      bounds: state.bounds,
+      gridSize: grid,
+      layerCount: state.layerCount,
+      obstaclesByLayer: state.obstaclesByLayer,
+      placedByLayer: state.placedByLayer,
+      hardPlacedByLayer,
+    })
     state.totalSeedsThisGrid = state.candidates.length
     state.consumedSeedsThisGrid = 0
   }
@@ -238,14 +249,14 @@ export function stepGrid(state: RectDiffState): void {
     } else {
       if (!state.edgeAnalysisDone) {
         const minSize = Math.min(minSingle.width, minSingle.height)
-        state.candidates = computeEdgeCandidates3D(
-          state.bounds,
+        state.candidates = computeEdgeCandidates3D({
+          bounds: state.bounds,
           minSize,
-          state.layerCount,
-          state.obstaclesByLayer,
-          state.placedByLayer, // for fully-occupied test
+          layerCount: state.layerCount,
+          obstaclesByLayer: state.obstaclesByLayer,
+          placedByLayer: state.placedByLayer,
           hardPlacedByLayer,
-        )
+        })
         state.edgeAnalysisDone = true
         state.totalSeedsThisGrid = state.candidates.length
         state.consumedSeedsThisGrid = 0
@@ -262,16 +273,16 @@ export function stepGrid(state: RectDiffState): void {
   state.consumedSeedsThisGrid += 1
 
   // Evaluate attempts — multi-layer span first (computed ignoring soft nodes)
-  const span = longestFreeSpanAroundZ(
-    cand.x,
-    cand.y,
-    cand.z,
-    state.layerCount,
-    minMulti.minLayers,
-    maxMultiLayerSpan,
-    state.obstaclesByLayer,
-    hardPlacedByLayer, // ignore soft nodes for span
-  )
+  const span = longestFreeSpanAroundZ({
+    x: cand.x,
+    y: cand.y,
+    z: cand.z,
+    layerCount: state.layerCount,
+    minSpan: minMulti.minLayers,
+    maxSpan: maxMultiLayerSpan,
+    obstaclesByLayer: state.obstaclesByLayer,
+    placedByLayer: hardPlacedByLayer,
+  })
 
   const attempts: Array<{
     kind: "multi" | "single"
@@ -303,16 +314,16 @@ export function stepGrid(state: RectDiffState): void {
       if (hardPlacedByLayer[z]) hardBlockers.push(...hardPlacedByLayer[z]!)
     }
 
-    const rect = expandRectFromSeed(
-      cand.x,
-      cand.y,
-      grid,
-      state.bounds,
-      hardBlockers, // soft nodes DO NOT block expansion
+    const rect = expandRectFromSeed({
+      startX: cand.x,
+      startY: cand.y,
+      gridSize: grid,
+      bounds: state.bounds,
+      blockers: hardBlockers,
       initialCellRatio,
       maxAspectRatio,
-      attempt.minReq,
-    )
+      minReq: attempt.minReq,
+    })
     if (!rect) continue
 
     // Place the new node
@@ -325,7 +336,7 @@ export function stepGrid(state: RectDiffState): void {
 
     // New: relax candidate culling — only drop seeds that became fully occupied
     state.candidates = state.candidates.filter(
-      (c) => !isFullyOccupiedAtPoint(state, c.x, c.y),
+      (c) => !isFullyOccupiedAtPoint(state, { x: c.x, y: c.y }),
     )
 
     return // processed one candidate
@@ -334,10 +345,13 @@ export function stepGrid(state: RectDiffState): void {
   // Neither attempt worked; drop this candidate for now.
 }
 
-/** One micro-step during the EXPANSION phase: expand exactly one placed rect */
+/**
+ * One micro-step during the EXPANSION phase: expand exactly one placed rect.
+ */
 export function stepExpansion(state: RectDiffState): void {
   if (state.expansionIndex >= state.placed.length) {
-    state.phase = "DONE"
+    // Transition to gap fill phase instead of done
+    state.phase = "GAP_FILL"
     return
   }
 
@@ -355,16 +369,16 @@ export function stepExpansion(state: RectDiffState): void {
   }
 
   const oldRect = p.rect
-  const expanded = expandRectFromSeed(
-    p.rect.x + p.rect.width / 2,
-    p.rect.y + p.rect.height / 2,
-    lastGrid,
-    state.bounds,
-    hardBlockers,
-    0, // seed bias off
-    null, // no aspect cap in expansion pass
-    { width: p.rect.width, height: p.rect.height },
-  )
+  const expanded = expandRectFromSeed({
+    startX: p.rect.x + p.rect.width / 2,
+    startY: p.rect.y + p.rect.height / 2,
+    gridSize: lastGrid,
+    bounds: state.bounds,
+    blockers: hardBlockers,
+    initialCellRatio: 0,
+    maxAspectRatio: null,
+    minReq: { width: p.rect.width, height: p.rect.height },
+  })
 
   if (expanded) {
     // Update placement + per-layer index (replace old rect object)
@@ -382,6 +396,9 @@ export function stepExpansion(state: RectDiffState): void {
   state.expansionIndex += 1
 }
 
+/**
+ * Finalize placed rectangles into output format.
+ */
 export function finalizeRects(state: RectDiffState): Rect3d[] {
   // Convert all placed (free space) nodes to output format
   const out: Rect3d[] = state.placed.map((p) => ({
@@ -423,7 +440,9 @@ export function finalizeRects(state: RectDiffState): Rect3d[] {
   return out
 }
 
-/** Optional: rough progress number for BaseSolver.progress */
+/**
+ * Calculate rough progress number for BaseSolver.progress.
+ */
 export function computeProgress(state: RectDiffState): number {
   const grids = state.options.gridSizes.length
   if (state.phase === "GRID") {

package/lib/solvers/rectdiff/gapfill/detection/deduplicateGaps.ts

@@ -0,0 +1,28 @@
+// lib/solvers/rectdiff/gapfill/detection/deduplicateGaps.ts
+import { rectsEqual } from "../../../../../utils/rectsEqual"
+import { rectsOverlap } from "../../../../../utils/rectsOverlap"
+import type { GapRegion } from "../types"
+
+export function deduplicateGaps(gaps: GapRegion[]): GapRegion[] {
+  const result: GapRegion[] = []
+
+  for (const gap of gaps) {
+    // Check if we already have a gap at the same location with overlapping layers
+    const existing = result.find(
+      (g) =>
+        rectsEqual(g.rect, gap.rect) ||
+        (rectsOverlap(g.rect, gap.rect) &&
+          gap.zLayers.some((z) => g.zLayers.includes(z))),
+    )
+
+    if (!existing) {
+      result.push(gap)
+    } else if (gap.zLayers.length > existing.zLayers.length) {
+      // Replace with the one that has more layers
+      const idx = result.indexOf(existing)
+      result[idx] = gap
+    }
+  }
+
+  return result
+}

package/lib/solvers/rectdiff/gapfill/detection/findAllGaps.ts

@@ -0,0 +1,83 @@
+// lib/solvers/rectdiff/gapfill/detection/findAllGaps.ts
+import type { XYRect } from "../../types"
+import type { GapRegion, LayerContext } from "../types"
+import { EPS } from "../../geometry"
+import { findGapsOnLayer } from "./findGapsOnLayer"
+import { rectsOverlap } from "../../../../../utils/rectsOverlap"
+import { deduplicateGaps } from "./deduplicateGaps"
+
+/**
+ * Find gaps across all layers and return GapRegions with z-layer info.
+ */
+export function findAllGaps(
+  {
+    scanResolution,
+    minWidth,
+    minHeight,
+  }: {
+    scanResolution: number
+    minWidth: number
+    minHeight: number
+  },
+  ctx: LayerContext,
+): GapRegion[] {
+  const { bounds, layerCount, obstaclesByLayer, placedByLayer } = ctx
+
+  // Find gaps on each layer
+  const gapsByLayer: XYRect[][] = []
+  for (let z = 0; z < layerCount; z++) {
+    const obstacles = obstaclesByLayer[z] ?? []
+    const placed = placedByLayer[z] ?? []
+    const gaps = findGapsOnLayer({ bounds, obstacles, placed, scanResolution })
+    gapsByLayer.push(gaps)
+  }
+
+  // Convert to GapRegions with z-layer info
+  const allGaps: GapRegion[] = []
+
+  for (let z = 0; z < layerCount; z++) {
+    for (const gap of gapsByLayer[z]!) {
+      // Filter out gaps that are too small
+      if (gap.width < minWidth - EPS || gap.height < minHeight - EPS) continue
+
+      // Check if this gap exists on adjacent layers too
+      const zLayers = [z]
+
+      // Look up
+      for (let zu = z + 1; zu < layerCount; zu++) {
+        const hasOverlap = gapsByLayer[zu]!.some((g) => rectsOverlap(g, gap))
+        if (hasOverlap) zLayers.push(zu)
+        else break
+      }
+
+      // Look down (if z > 0 and not already counted)
+      for (let zd = z - 1; zd >= 0; zd--) {
+        const hasOverlap = gapsByLayer[zd]!.some((g) => rectsOverlap(g, gap))
+        if (hasOverlap && !zLayers.includes(zd)) zLayers.unshift(zd)
+        else break
+      }
+
+      allGaps.push({
+        rect: gap,
+        zLayers: zLayers.sort((a, b) => a - b),
+        centerX: gap.x + gap.width / 2,
+        centerY: gap.y + gap.height / 2,
+        area: gap.width * gap.height,
+      })
+    }
+  }
+
+  // Deduplicate gaps that are essentially the same across layers
+  const deduped = deduplicateGaps(allGaps)
+
+  // Sort by priority: prefer larger gaps and multi-layer gaps
+  deduped.sort((a, b) => {
+    // Prefer multi-layer gaps
+    const layerDiff = b.zLayers.length - a.zLayers.length
+    if (layerDiff !== 0) return layerDiff
+    // Then prefer larger area
+    return b.area - a.area
+  })
+
+  return deduped
+}

package/lib/solvers/rectdiff/gapfill/detection/findGapsOnLayer.ts

@@ -0,0 +1,100 @@
+// lib/solvers/rectdiff/gapfill/detection/findGapsOnLayer.ts
+import type { XYRect } from "../../types"
+import { EPS } from "../../geometry"
+
+import { mergeUncoveredCells } from "./mergeUncoveredCells"
+
+/**
+ * Sweep-line algorithm to find maximal uncovered rectangles on a single layer.
+ */
+export function findGapsOnLayer({
+  bounds,
+  obstacles,
+  placed,
+  scanResolution,
+}: {
+  bounds: XYRect
+  obstacles: XYRect[]
+  placed: XYRect[]
+  scanResolution: number
+}): XYRect[] {
+  const blockers = [...obstacles, ...placed]
+
+  // Collect all unique x-coordinates
+  const xCoords = new Set<number>()
+  xCoords.add(bounds.x)
+  xCoords.add(bounds.x + bounds.width)
+
+  for (const b of blockers) {
+    if (b.x > bounds.x && b.x < bounds.x + bounds.width) {
+      xCoords.add(b.x)
+    }
+    if (b.x + b.width > bounds.x && b.x + b.width < bounds.x + bounds.width) {
+      xCoords.add(b.x + b.width)
+    }
+  }
+
+  // Also add intermediate points based on scan resolution
+  for (let x = bounds.x; x <= bounds.x + bounds.width; x += scanResolution) {
+    xCoords.add(x)
+  }
+
+  const sortedX = Array.from(xCoords).sort((a, b) => a - b)
+
+  // Similarly for y-coordinates
+  const yCoords = new Set<number>()
+  yCoords.add(bounds.y)
+  yCoords.add(bounds.y + bounds.height)
+
+  for (const b of blockers) {
+    if (b.y > bounds.y && b.y < bounds.y + bounds.height) {
+      yCoords.add(b.y)
+    }
+    if (
+      b.y + b.height > bounds.y &&
+      b.y + b.height < bounds.y + bounds.height
+    ) {
+      yCoords.add(b.y + b.height)
+    }
+  }
+
+  for (let y = bounds.y; y <= bounds.y + bounds.height; y += scanResolution) {
+    yCoords.add(y)
+  }
+
+  const sortedY = Array.from(yCoords).sort((a, b) => a - b)
+
+  // Build a grid of cells and mark which are uncovered
+  const uncoveredCells: Array<{ x: number; y: number; w: number; h: number }> =
+    []
+
+  for (let i = 0; i < sortedX.length - 1; i++) {
+    for (let j = 0; j < sortedY.length - 1; j++) {
+      const cellX = sortedX[i]!
+      const cellY = sortedY[j]!
+      const cellW = sortedX[i + 1]! - cellX
+      const cellH = sortedY[j + 1]! - cellY
+
+      if (cellW <= EPS || cellH <= EPS) continue
+
+      // Check if this cell is covered by any blocker
+      const cellCenterX = cellX + cellW / 2
+      const cellCenterY = cellY + cellH / 2
+
+      const isCovered = blockers.some(
+        (b) =>
+          cellCenterX >= b.x - EPS &&
+          cellCenterX <= b.x + b.width + EPS &&
+          cellCenterY >= b.y - EPS &&
+          cellCenterY <= b.y + b.height + EPS,
+      )
+
+      if (!isCovered) {
+        uncoveredCells.push({ x: cellX, y: cellY, w: cellW, h: cellH })
+      }
+    }
+  }
+
+  // Merge adjacent uncovered cells into maximal rectangles
+  return mergeUncoveredCells(uncoveredCells)
+}

package/lib/solvers/rectdiff/gapfill/detection/mergeUncoveredCells.ts

@@ -0,0 +1,75 @@
+// lib/solvers/rectdiff/gapfill/detection/mergeUncoveredCells.ts
+import type { XYRect } from "../../types"
+import { EPS } from "../../geometry"
+
+/**
+ * Merge adjacent uncovered cells into larger rectangles using a greedy approach.
+ */
+export function mergeUncoveredCells(
+  cells: Array<{ x: number; y: number; w: number; h: number }>,
+): XYRect[] {
+  if (cells.length === 0) return []
+
+  // Group cells by their left edge and width
+  const byXW = new Map<string, typeof cells>()
+  for (const c of cells) {
+    const key = `${c.x.toFixed(9)}|${c.w.toFixed(9)}`
+    const arr = byXW.get(key) ?? []
+    arr.push(c)
+    byXW.set(key, arr)
+  }
+
+  // Within each vertical strip, merge adjacent cells
+  const verticalStrips: XYRect[] = []
+  for (const stripCells of byXW.values()) {
+    // Sort by y
+    stripCells.sort((a, b) => a.y - b.y)
+
+    let current: XYRect | null = null
+    for (const c of stripCells) {
+      if (!current) {
+        current = { x: c.x, y: c.y, width: c.w, height: c.h }
+      } else if (Math.abs(current.y + current.height - c.y) < EPS) {
+        // Adjacent vertically, merge
+        current.height += c.h
+      } else {
+        // Gap, save current and start new
+        verticalStrips.push(current)
+        current = { x: c.x, y: c.y, width: c.w, height: c.h }
+      }
+    }
+    if (current) verticalStrips.push(current)
+  }
+
+  // Now try to merge horizontal strips with same y and height
+  const byYH = new Map<string, XYRect[]>()
+  for (const r of verticalStrips) {
+    const key = `${r.y.toFixed(9)}|${r.height.toFixed(9)}`
+    const arr = byYH.get(key) ?? []
+    arr.push(r)
+    byYH.set(key, arr)
+  }
+
+  const merged: XYRect[] = []
+  for (const rowRects of byYH.values()) {
+    // Sort by x
+    rowRects.sort((a, b) => a.x - b.x)
+
+    let current: XYRect | null = null
+    for (const r of rowRects) {
+      if (!current) {
+        current = { ...r }
+      } else if (Math.abs(current.x + current.width - r.x) < EPS) {
+        // Adjacent horizontally, merge
+        current.width += r.width
+      } else {
+        // Gap, save current and start new
+        merged.push(current)
+        current = { ...r }
+      }
+    }
+    if (current) merged.push(current)
+  }
+
+  return merged
+}

package/lib/solvers/rectdiff/gapfill/detection.ts

@@ -0,0 +1,3 @@
+// lib/solvers/rectdiff/gapfill/detection.ts
+export * from "./detection/findAllGaps"
+// findGapsOnLayer is not exported as it's only used by findAllGaps

package/lib/solvers/rectdiff/gapfill/engine/addPlacement.ts

@@ -0,0 +1,27 @@
+// lib/solvers/rectdiff/gapfill/engine/addPlacement.ts
+import type { Placed3D, XYRect } from "../../types"
+import type { GapFillState } from "../types"
+
+/**
+ * Add a new placement to the state.
+ */
+export function addPlacement(
+  state: GapFillState,
+  {
+    rect,
+    zLayers,
+  }: {
+    rect: XYRect
+    zLayers: number[]
+  },
+): void {
+  const placed: Placed3D = { rect, zLayers: [...zLayers] }
+  state.placed.push(placed)
+
+  for (const z of zLayers) {
+    if (!state.placedByLayer[z]) {
+      state.placedByLayer[z] = []
+    }
+    state.placedByLayer[z]!.push(rect)
+  }
+}

package/lib/solvers/rectdiff/gapfill/engine/calculateCoverage.ts

@@ -0,0 +1,44 @@
+// lib/solvers/rectdiff/gapfill/engine/calculateCoverage.ts
+import type { LayerContext } from "../types"
+
+/**
+ * Calculate coverage percentage (0-1).
+ */
+export function calculateCoverage(
+  { sampleResolution = 0.1 }: { sampleResolution?: number },
+  ctx: LayerContext,
+): number {
+  const { bounds, layerCount, obstaclesByLayer, placedByLayer } = ctx
+
+  let totalPoints = 0
+  let coveredPoints = 0
+
+  for (let z = 0; z < layerCount; z++) {
+    const obstacles = obstaclesByLayer[z] ?? []
+    const placed = placedByLayer[z] ?? []
+    const allRects = [...obstacles, ...placed]
+
+    for (
+      let x = bounds.x;
+      x <= bounds.x + bounds.width;
+      x += sampleResolution
+    ) {
+      for (
+        let y = bounds.y;
+        y <= bounds.y + bounds.height;
+        y += sampleResolution
+      ) {
+        totalPoints++
+
+        const isCovered = allRects.some(
+          (r) =>
+            x >= r.x && x <= r.x + r.width && y >= r.y && y <= r.y + r.height,
+        )
+
+        if (isCovered) coveredPoints++
+      }
+    }
+  }
+
+  return totalPoints > 0 ? coveredPoints / totalPoints : 1
+}

package/lib/solvers/rectdiff/gapfill/engine/findUncoveredPoints.ts

@@ -0,0 +1,43 @@
+// lib/solvers/rectdiff/gapfill/engine/findUncoveredPoints.ts
+import type { LayerContext } from "../types"
+
+/**
+ * Find uncovered points for debugging gaps.
+ */
+export function findUncoveredPoints(
+  { sampleResolution = 0.05 }: { sampleResolution?: number },
+  ctx: LayerContext,
+): Array<{ x: number; y: number; z: number }> {
+  const { bounds, layerCount, obstaclesByLayer, placedByLayer } = ctx
+
+  const uncovered: Array<{ x: number; y: number; z: number }> = []
+
+  for (let z = 0; z < layerCount; z++) {
+    const obstacles = obstaclesByLayer[z] ?? []
+    const placed = placedByLayer[z] ?? []
+    const allRects = [...obstacles, ...placed]
+
+    for (
+      let x = bounds.x;
+      x <= bounds.x + bounds.width;
+      x += sampleResolution
+    ) {
+      for (
+        let y = bounds.y;
+        y <= bounds.y + bounds.height;
+        y += sampleResolution
+      ) {
+        const isCovered = allRects.some(
+          (r) =>
+            x >= r.x && x <= r.x + r.width && y >= r.y && y <= r.y + r.height,
+        )
+
+        if (!isCovered) {
+          uncovered.push({ x, y, z })
+        }
+      }
+    }
+  }
+
+  return uncovered
+}

package/lib/solvers/rectdiff/gapfill/engine/getGapFillProgress.ts

@@ -0,0 +1,42 @@
+// lib/solvers/rectdiff/gapfill/engine/getGapFillProgress.ts
+import type { GapFillState } from "../types"
+
+/**
+ * Get progress as a number between 0 and 1.
+ * Accounts for four-stage processing (scan → select → expand → place for each gap).
+ */
+export function getGapFillProgress(state: GapFillState): number {
+  if (state.done) return 1
+
+  const iterationProgress = state.iteration / state.options.maxIterations
+  const gapProgress =
+    state.gapsFound.length > 0 ? state.gapIndex / state.gapsFound.length : 0
+
+  // Add sub-progress within current gap based on stage
+  let stageProgress = 0
+  switch (state.stage) {
+    case "scan":
+      stageProgress = 0
+      break
+    case "select":
+      stageProgress = 0.25
+      break
+    case "expand":
+      stageProgress = 0.5
+      break
+    case "place":
+      stageProgress = 0.75
+      break
+  }
+
+  const gapStageProgress =
+    state.gapsFound.length > 0
+      ? stageProgress / (state.gapsFound.length * 4) // 4 stages per gap
+      : 0
+
+  return Math.min(
+    0.999,
+    iterationProgress +
+      (gapProgress + gapStageProgress) / state.options.maxIterations,
+  )
+}