@tscircuit/rectdiff 0.0.1 → 0.0.3

package/lib/solvers/RectDiffSolver.ts

@@ -5,7 +5,13 @@ import type { GraphicsObject } from "graphics-debug"
 import type { CapacityMeshNode } from "../types/capacity-mesh-types"
 
 import type { GridFill3DOptions, RectDiffState } from "./rectdiff/types"
-import { initState, stepGrid, stepExpansion, finalizeRects, computeProgress } from "./rectdiff/engine"
+import {
+  initState,
+  stepGrid,
+  stepExpansion,
+  finalizeRects,
+  computeProgress,
+} from "./rectdiff/engine"
 import { rectsToMeshNodes } from "./rectdiff/rectsToMeshNodes"
 
 // A streaming, one-step-per-iteration solver.
@@ -71,7 +77,10 @@ export class RectDiffSolver extends BaseSolver {
   }
 
   // Helper to get color based on z layer
-  private getColorForZLayer(zLayers: number[]): { fill: string; stroke: string } {
+  private getColorForZLayer(zLayers: number[]): {
+    fill: string
+    stroke: string
+  } {
     const minZ = Math.min(...zLayers)
     const colors = [
       { fill: "#dbeafe", stroke: "#3b82f6" }, // blue (z=0)
@@ -135,7 +144,10 @@ export class RectDiffSolver extends BaseSolver {
       for (const p of this.state.placed) {
         const colors = this.getColorForZLayer(p.zLayers)
         rects.push({
-          center: { x: p.rect.x + p.rect.width / 2, y: p.rect.y + p.rect.height / 2 },
+          center: {
+            x: p.rect.x + p.rect.width / 2,
+            y: p.rect.y + p.rect.height / 2,
+          },
           width: p.rect.width,
           height: p.rect.height,
           fill: colors.fill,

package/lib/solvers/rectdiff/candidates.ts

@@ -25,8 +25,8 @@ export function computeCandidates3D(
   gridSize: number,
   layerCount: number,
   obstaclesByLayer: XYRect[][],
-  placedByLayer: XYRect[][],         // all current nodes (soft + hard)
-  hardPlacedByLayer: XYRect[][],     // only full-stack nodes, treated as hard
+  placedByLayer: XYRect[][], // all current nodes (soft + hard)
+  hardPlacedByLayer: XYRect[][], // only full-stack nodes, treated as hard
 ): Candidate3D[] {
   const out = new Map<string, Candidate3D>() // key by (x,y)
 
@@ -43,7 +43,16 @@ export function computeCandidates3D(
       }
 
       // New rule: Only drop if EVERY layer is occupied (by obstacle or node)
-      if (isFullyOccupiedAllLayers(x, y, layerCount, obstaclesByLayer, placedByLayer)) continue
+      if (
+        isFullyOccupiedAllLayers(
+          x,
+          y,
+          layerCount,
+          obstaclesByLayer,
+          placedByLayer,
+        )
+      )
+        continue
 
       // Find the best (longest) free contiguous Z span at (x,y) ignoring soft nodes.
       let bestSpan: number[] = []
@@ -55,9 +64,9 @@ export function computeCandidates3D(
           z,
           layerCount,
           1,
-          undefined,            // no cap here
+          undefined, // no cap here
           obstaclesByLayer,
-          hardPlacedByLayer,    // IMPORTANT: ignore soft nodes
+          hardPlacedByLayer, // IMPORTANT: ignore soft nodes
         )
         if (s.length > bestSpan.length) {
           bestSpan = s
@@ -100,7 +109,7 @@ export function computeCandidates3D(
   }
 
   const arr = Array.from(out.values())
-  arr.sort((a, b) => (b.zSpanLen! - a.zSpanLen!) || (b.distance - a.distance))
+  arr.sort((a, b) => b.zSpanLen! - a.zSpanLen! || b.distance - a.distance)
   return arr
 }
 
@@ -116,7 +125,10 @@ export function longestFreeSpanAroundZ(
   placedByLayer: XYRect[][],
 ): number[] {
   const isFreeAt = (layer: number) => {
-    const blockers = [...(obstaclesByLayer[layer] ?? []), ...(placedByLayer[layer] ?? [])]
+    const blockers = [
+      ...(obstaclesByLayer[layer] ?? []),
+      ...(placedByLayer[layer] ?? []),
+    ]
     return !blockers.some((b) => containsPoint(b, x, y))
   }
   let lo = z
@@ -214,24 +226,34 @@ export function computeEdgeCandidates3D(
   minSize: number,
   layerCount: number,
   obstaclesByLayer: XYRect[][],
-  placedByLayer: XYRect[][],     // all nodes
+  placedByLayer: XYRect[][], // all nodes
   hardPlacedByLayer: XYRect[][], // full-stack nodes
 ): Candidate3D[] {
   const out: Candidate3D[] = []
   // Use small inset from edges for placement
   const δ = Math.max(minSize * 0.15, EPS * 3)
   const dedup = new Set<string>()
-  const key = (x: number, y: number, z: number) => `${z}|${x.toFixed(6)}|${y.toFixed(6)}`
+  const key = (x: number, y: number, z: number) =>
+    `${z}|${x.toFixed(6)}|${y.toFixed(6)}`
 
   function fullyOcc(x: number, y: number) {
-    return isFullyOccupiedAllLayers(x, y, layerCount, obstaclesByLayer, placedByLayer)
+    return isFullyOccupiedAllLayers(
+      x,
+      y,
+      layerCount,
+      obstaclesByLayer,
+      placedByLayer,
+    )
   }
 
   function pushIfFree(x: number, y: number, z: number) {
     if (
-      x < bounds.x + EPS || y < bounds.y + EPS ||
-      x > bounds.x + bounds.width - EPS || y > bounds.y + bounds.height - EPS
-    ) return
+      x < bounds.x + EPS ||
+      y < bounds.y + EPS ||
+      x > bounds.x + bounds.width - EPS ||
+      y > bounds.y + bounds.height - EPS
+    )
+      return
     if (fullyOcc(x, y)) return // new rule: only drop if truly impossible
 
     // Distance uses obstacles + hard nodes (soft nodes ignored for ranking)
@@ -241,7 +263,9 @@ export function computeEdgeCandidates3D(
     ]
     const d = Math.min(
       distancePointToRectEdges(x, y, bounds),
-      ...(hard.length ? hard.map((b) => distancePointToRectEdges(x, y, b)) : [Infinity]),
+      ...(hard.length
+        ? hard.map((b) => distancePointToRectEdges(x, y, b))
+        : [Infinity]),
     )
 
     const k = key(x, y, z)
@@ -249,12 +273,24 @@ export function computeEdgeCandidates3D(
     dedup.add(k)
 
     // Approximate z-span strength at this z (ignoring soft nodes)
-    const span = longestFreeSpanAroundZ(x, y, z, layerCount, 1, undefined, obstaclesByLayer, hardPlacedByLayer)
+    const span = longestFreeSpanAroundZ(
+      x,
+      y,
+      z,
+      layerCount,
+      1,
+      undefined,
+      obstaclesByLayer,
+      hardPlacedByLayer,
+    )
     out.push({ x, y, z, distance: d, zSpanLen: span.length, isEdgeSeed: true })
   }
 
   for (let z = 0; z < layerCount; z++) {
-    const blockers = [...(obstaclesByLayer[z] ?? []), ...(hardPlacedByLayer[z] ?? [])]
+    const blockers = [
+      ...(obstaclesByLayer[z] ?? []),
+      ...(hardPlacedByLayer[z] ?? []),
+    ]
 
     // 1) Board edges — find exact uncovered segments along each edge
 
@@ -272,10 +308,18 @@ export function computeEdgeCandidates3D(
     // Top edge (y = bounds.y + δ)
     const topY = bounds.y + δ
     const topCovering = blockers
-      .filter(b => b.y <= topY && b.y + b.height >= topY)
-      .map(b => ({ start: Math.max(bounds.x, b.x), end: Math.min(bounds.x + bounds.width, b.x + b.width) }))
+      .filter((b) => b.y <= topY && b.y + b.height >= topY)
+      .map((b) => ({
+        start: Math.max(bounds.x, b.x),
+        end: Math.min(bounds.x + bounds.width, b.x + b.width),
+      }))
     // Find uncovered segments that are large enough to potentially fill
-    const topUncovered = computeUncoveredSegments(bounds.x + δ, bounds.x + bounds.width - δ, topCovering, minSize * 0.5)
+    const topUncovered = computeUncoveredSegments(
+      bounds.x + δ,
+      bounds.x + bounds.width - δ,
+      topCovering,
+      minSize * 0.5,
+    )
     for (const seg of topUncovered) {
       const segLen = seg.end - seg.start
       if (segLen >= minSize) {
@@ -291,9 +335,17 @@ export function computeEdgeCandidates3D(
     // Bottom edge (y = bounds.y + bounds.height - δ)
     const bottomY = bounds.y + bounds.height - δ
     const bottomCovering = blockers
-      .filter(b => b.y <= bottomY && b.y + b.height >= bottomY)
-      .map(b => ({ start: Math.max(bounds.x, b.x), end: Math.min(bounds.x + bounds.width, b.x + b.width) }))
-    const bottomUncovered = computeUncoveredSegments(bounds.x + δ, bounds.x + bounds.width - δ, bottomCovering, minSize * 0.5)
+      .filter((b) => b.y <= bottomY && b.y + b.height >= bottomY)
+      .map((b) => ({
+        start: Math.max(bounds.x, b.x),
+        end: Math.min(bounds.x + bounds.width, b.x + b.width),
+      }))
+    const bottomUncovered = computeUncoveredSegments(
+      bounds.x + δ,
+      bounds.x + bounds.width - δ,
+      bottomCovering,
+      minSize * 0.5,
+    )
     for (const seg of bottomUncovered) {
       const segLen = seg.end - seg.start
       if (segLen >= minSize) {
@@ -308,9 +360,17 @@ export function computeEdgeCandidates3D(
     // Left edge (x = bounds.x + δ)
     const leftX = bounds.x + δ
     const leftCovering = blockers
-      .filter(b => b.x <= leftX && b.x + b.width >= leftX)
-      .map(b => ({ start: Math.max(bounds.y, b.y), end: Math.min(bounds.y + bounds.height, b.y + b.height) }))
-    const leftUncovered = computeUncoveredSegments(bounds.y + δ, bounds.y + bounds.height - δ, leftCovering, minSize * 0.5)
+      .filter((b) => b.x <= leftX && b.x + b.width >= leftX)
+      .map((b) => ({
+        start: Math.max(bounds.y, b.y),
+        end: Math.min(bounds.y + bounds.height, b.y + b.height),
+      }))
+    const leftUncovered = computeUncoveredSegments(
+      bounds.y + δ,
+      bounds.y + bounds.height - δ,
+      leftCovering,
+      minSize * 0.5,
+    )
     for (const seg of leftUncovered) {
       const segLen = seg.end - seg.start
       if (segLen >= minSize) {
@@ -325,9 +385,17 @@ export function computeEdgeCandidates3D(
     // Right edge (x = bounds.x + bounds.width - δ)
     const rightX = bounds.x + bounds.width - δ
     const rightCovering = blockers
-      .filter(b => b.x <= rightX && b.x + b.width >= rightX)
-      .map(b => ({ start: Math.max(bounds.y, b.y), end: Math.min(bounds.y + bounds.height, b.y + b.height) }))
-    const rightUncovered = computeUncoveredSegments(bounds.y + δ, bounds.y + bounds.height - δ, rightCovering, minSize * 0.5)
+      .filter((b) => b.x <= rightX && b.x + b.width >= rightX)
+      .map((b) => ({
+        start: Math.max(bounds.y, b.y),
+        end: Math.min(bounds.y + bounds.height, b.y + b.height),
+      }))
+    const rightUncovered = computeUncoveredSegments(
+      bounds.y + δ,
+      bounds.y + bounds.height - δ,
+      rightCovering,
+      minSize * 0.5,
+    )
     for (const seg of rightUncovered) {
       const segLen = seg.end - seg.start
       if (segLen >= minSize) {
@@ -345,9 +413,19 @@ export function computeEdgeCandidates3D(
       const obLeftX = b.x - δ
       if (obLeftX > bounds.x + EPS && obLeftX < bounds.x + bounds.width - EPS) {
         const obLeftCovering = blockers
-          .filter(bl => bl !== b && bl.x <= obLeftX && bl.x + bl.width >= obLeftX)
-          .map(bl => ({ start: Math.max(b.y, bl.y), end: Math.min(b.y + b.height, bl.y + bl.height) }))
-        const obLeftUncovered = computeUncoveredSegments(b.y, b.y + b.height, obLeftCovering, minSize * 0.5)
+          .filter(
+            (bl) => bl !== b && bl.x <= obLeftX && bl.x + bl.width >= obLeftX,
+          )
+          .map((bl) => ({
+            start: Math.max(b.y, bl.y),
+            end: Math.min(b.y + b.height, bl.y + bl.height),
+          }))
+        const obLeftUncovered = computeUncoveredSegments(
+          b.y,
+          b.y + b.height,
+          obLeftCovering,
+          minSize * 0.5,
+        )
         for (const seg of obLeftUncovered) {
           pushIfFree(obLeftX, seg.center, z)
         }
@@ -355,11 +433,24 @@ export function computeEdgeCandidates3D(
 
       // Right edge of blocker (x = b.x + b.width + δ)
       const obRightX = b.x + b.width + δ
-      if (obRightX > bounds.x + EPS && obRightX < bounds.x + bounds.width - EPS) {
+      if (
+        obRightX > bounds.x + EPS &&
+        obRightX < bounds.x + bounds.width - EPS
+      ) {
         const obRightCovering = blockers
-          .filter(bl => bl !== b && bl.x <= obRightX && bl.x + bl.width >= obRightX)
-          .map(bl => ({ start: Math.max(b.y, bl.y), end: Math.min(b.y + b.height, bl.y + bl.height) }))
-        const obRightUncovered = computeUncoveredSegments(b.y, b.y + b.height, obRightCovering, minSize * 0.5)
+          .filter(
+            (bl) => bl !== b && bl.x <= obRightX && bl.x + bl.width >= obRightX,
+          )
+          .map((bl) => ({
+            start: Math.max(b.y, bl.y),
+            end: Math.min(b.y + b.height, bl.y + bl.height),
+          }))
+        const obRightUncovered = computeUncoveredSegments(
+          b.y,
+          b.y + b.height,
+          obRightCovering,
+          minSize * 0.5,
+        )
         for (const seg of obRightUncovered) {
           pushIfFree(obRightX, seg.center, z)
         }
@@ -369,9 +460,19 @@ export function computeEdgeCandidates3D(
       const obTopY = b.y - δ
       if (obTopY > bounds.y + EPS && obTopY < bounds.y + bounds.height - EPS) {
         const obTopCovering = blockers
-          .filter(bl => bl !== b && bl.y <= obTopY && bl.y + bl.height >= obTopY)
-          .map(bl => ({ start: Math.max(b.x, bl.x), end: Math.min(b.x + b.width, bl.x + bl.width) }))
-        const obTopUncovered = computeUncoveredSegments(b.x, b.x + b.width, obTopCovering, minSize * 0.5)
+          .filter(
+            (bl) => bl !== b && bl.y <= obTopY && bl.y + bl.height >= obTopY,
+          )
+          .map((bl) => ({
+            start: Math.max(b.x, bl.x),
+            end: Math.min(b.x + b.width, bl.x + bl.width),
+          }))
+        const obTopUncovered = computeUncoveredSegments(
+          b.x,
+          b.x + b.width,
+          obTopCovering,
+          minSize * 0.5,
+        )
         for (const seg of obTopUncovered) {
           pushIfFree(seg.center, obTopY, z)
         }
@@ -379,11 +480,25 @@ export function computeEdgeCandidates3D(
 
       // Bottom edge of blocker (y = b.y + b.height + δ)
       const obBottomY = b.y + b.height + δ
-      if (obBottomY > bounds.y + EPS && obBottomY < bounds.y + bounds.height - EPS) {
+      if (
+        obBottomY > bounds.y + EPS &&
+        obBottomY < bounds.y + bounds.height - EPS
+      ) {
         const obBottomCovering = blockers
-          .filter(bl => bl !== b && bl.y <= obBottomY && bl.y + bl.height >= obBottomY)
-          .map(bl => ({ start: Math.max(b.x, bl.x), end: Math.min(b.x + b.width, bl.x + bl.width) }))
-        const obBottomUncovered = computeUncoveredSegments(b.x, b.x + b.width, obBottomCovering, minSize * 0.5)
+          .filter(
+            (bl) =>
+              bl !== b && bl.y <= obBottomY && bl.y + bl.height >= obBottomY,
+          )
+          .map((bl) => ({
+            start: Math.max(b.x, bl.x),
+            end: Math.min(b.x + b.width, bl.x + bl.width),
+          }))
+        const obBottomUncovered = computeUncoveredSegments(
+          b.x,
+          b.x + b.width,
+          obBottomCovering,
+          minSize * 0.5,
+        )
         for (const seg of obBottomUncovered) {
           pushIfFree(seg.center, obBottomY, z)
         }
@@ -392,6 +507,6 @@ export function computeEdgeCandidates3D(
   }
 
   // Strong multi-layer preference then distance.
-  out.sort((a, b) => (b.zSpanLen! - a.zSpanLen!) || (b.distance - a.distance))
+  out.sort((a, b) => b.zSpanLen! - a.zSpanLen! || b.distance - a.distance)
   return out
 }

package/lib/solvers/rectdiff/engine.ts

@@ -1,5 +1,11 @@
 // lib/solvers/rectdiff/engine.ts
-import type { GridFill3DOptions, Placed3D, Rect3d, RectDiffState, XYRect } from "./types"
+import type {
+  GridFill3DOptions,
+  Placed3D,
+  Rect3d,
+  RectDiffState,
+  XYRect,
+} from "./types"
 import type { SimpleRouteJson } from "../../types/srj-types"
 import {
   computeCandidates3D,
@@ -7,10 +13,19 @@ import {
   computeEdgeCandidates3D,
   longestFreeSpanAroundZ,
 } from "./candidates"
-import { EPS, containsPoint, expandRectFromSeed, overlaps, subtractRect2D } from "./geometry"
+import {
+  EPS,
+  containsPoint,
+  expandRectFromSeed,
+  overlaps,
+  subtractRect2D,
+} from "./geometry"
 import { buildZIndexMap, obstacleToXYRect, obstacleZs } from "./layers"
 
-export function initState(srj: SimpleRouteJson, opts: Partial<GridFill3DOptions>): RectDiffState {
+export function initState(
+  srj: SimpleRouteJson,
+  opts: Partial<GridFill3DOptions>,
+): RectDiffState {
   const { layerNames, zIndexByName } = buildZIndexMap(srj)
   const layerCount = Math.max(1, layerNames.length, srj.layerCount || 1)
 
@@ -22,16 +37,31 @@ export function initState(srj: SimpleRouteJson, opts: Partial<GridFill3DOptions>
   }
 
   // Obstacles per layer
-  const obstaclesByLayer: XYRect[][] = Array.from({ length: layerCount }, () => [])
+  const obstaclesByLayer: XYRect[][] = Array.from(
+    { length: layerCount },
+    () => [],
+  )
   for (const ob of srj.obstacles ?? []) {
     const r = obstacleToXYRect(ob)
     if (!r) continue
     const zs = obstacleZs(ob, zIndexByName)
-    for (const z of zs) if (z >= 0 && z < layerCount) obstaclesByLayer[z]!.push(r)
+    const invalidZs = zs.filter((z) => z < 0 || z >= layerCount)
+    if (invalidZs.length) {
+      throw new Error(
+        `RectDiffSolver: obstacle uses z-layer indices ${invalidZs.join(
+          ",",
+        )} outside 0-${layerCount - 1}`,
+      )
+    }
+    // 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)
   }
 
   const trace = Math.max(0.01, srj.minTraceWidth || 0.15)
-  const defaults: Required<Omit<GridFill3DOptions, "gridSizes" | "maxMultiLayerSpan">> & {
+  const defaults: Required<
+    Omit<GridFill3DOptions, "gridSizes" | "maxMultiLayerSpan">
+  > & {
     gridSizes: number[]
     maxMultiLayerSpan: number | undefined
   } = {
@@ -48,7 +78,11 @@ export function initState(srj: SimpleRouteJson, opts: Partial<GridFill3DOptions>
     maxMultiLayerSpan: undefined,
   }
 
-  const options = { ...defaults, ...opts, gridSizes: opts.gridSizes ?? defaults.gridSizes }
+  const options = {
+    ...defaults,
+    ...opts,
+    gridSizes: opts.gridSizes ?? defaults.gridSizes,
+  }
 
   const placedByLayer: XYRect[][] = Array.from({ length: layerCount }, () => [])
 
@@ -83,7 +117,11 @@ function buildHardPlacedByLayer(state: RectDiffState): XYRect[][] {
   return out
 }
 
-function isFullyOccupiedAtPoint(state: RectDiffState, x: number, y: number): boolean {
+function isFullyOccupiedAtPoint(
+  state: RectDiffState,
+  x: number,
+  y: number,
+): boolean {
   for (let z = 0; z < state.layerCount; z++) {
     const obs = state.obstaclesByLayer[z] ?? []
     const placed = state.placedByLayer[z] ?? []
@@ -126,8 +164,14 @@ function resizeSoftOverlaps(state: RectDiffState, newIndex: number) {
     }
 
     // Re-add carved pieces for affected layers, dropping tiny slivers
-    const minW = Math.min(state.options.minSingle.width, state.options.minMulti.width)
-    const minH = Math.min(state.options.minSingle.height, state.options.minMulti.height)
+    const minW = Math.min(
+      state.options.minSingle.width,
+      state.options.minMulti.width,
+    )
+    const minH = Math.min(
+      state.options.minSingle.height,
+      state.options.minMulti.height,
+    )
     for (const p of parts) {
       if (p.width + EPS >= minW && p.height + EPS >= minH) {
         toAdd.push({ rect: p, zLayers: sharedZ.slice() })
@@ -136,14 +180,16 @@ function resizeSoftOverlaps(state: RectDiffState, newIndex: number) {
   }
 
   // Remove (and clear placedByLayer)
-  removeIdx.sort((a, b) => b - a).forEach((idx) => {
-    const rem = state.placed.splice(idx, 1)[0]!
-    for (const z of rem.zLayers) {
-      const arr = state.placedByLayer[z]!
-      const j = arr.findIndex((r) => r === rem.rect)
-      if (j >= 0) arr.splice(j, 1)
-    }
-  })
+  removeIdx
+    .sort((a, b) => b - a)
+    .forEach((idx) => {
+      const rem = state.placed.splice(idx, 1)[0]!
+      for (const z of rem.zLayers) {
+        const arr = state.placedByLayer[z]!
+        const j = arr.findIndex((r) => r === rem.rect)
+        if (j >= 0) arr.splice(j, 1)
+      }
+    })
 
   // Add replacements
   for (const p of toAdd) {
@@ -175,8 +221,8 @@ export function stepGrid(state: RectDiffState): void {
       grid,
       state.layerCount,
       state.obstaclesByLayer,
-      state.placedByLayer,     // all nodes (soft + hard) for fully-occupied test
-      hardPlacedByLayer,       // hard blockers for ranking/span
+      state.placedByLayer, // all nodes (soft + hard) for fully-occupied test
+      hardPlacedByLayer, // hard blockers for ranking/span
     )
     state.totalSeedsThisGrid = state.candidates.length
     state.consumedSeedsThisGrid = 0
@@ -197,7 +243,7 @@ export function stepGrid(state: RectDiffState): void {
           minSize,
           state.layerCount,
           state.obstaclesByLayer,
-          state.placedByLayer,   // for fully-occupied test
+          state.placedByLayer, // for fully-occupied test
           hardPlacedByLayer,
         )
         state.edgeAnalysisDone = true
@@ -234,9 +280,17 @@ export function stepGrid(state: RectDiffState): void {
   }> = []
 
   if (span.length >= minMulti.minLayers) {
-    attempts.push({ kind: "multi", layers: span, minReq: { width: minMulti.width, height: minMulti.height } })
+    attempts.push({
+      kind: "multi",
+      layers: span,
+      minReq: { width: minMulti.width, height: minMulti.height },
+    })
   }
-  attempts.push({ kind: "single", layers: [cand.z], minReq: { width: minSingle.width, height: minSingle.height } })
+  attempts.push({
+    kind: "single",
+    layers: [cand.z],
+    minReq: { width: minSingle.width, height: minSingle.height },
+  })
 
   const ordered = preferMultiLayer ? attempts : attempts.reverse()
 
@@ -244,7 +298,8 @@ export function stepGrid(state: RectDiffState): void {
     // HARD blockers only: obstacles on those layers + full-stack nodes
     const hardBlockers: XYRect[] = []
     for (const z of attempt.layers) {
-      if (state.obstaclesByLayer[z]) hardBlockers.push(...state.obstaclesByLayer[z]!)
+      if (state.obstaclesByLayer[z])
+        hardBlockers.push(...state.obstaclesByLayer[z]!)
       if (hardPlacedByLayer[z]) hardBlockers.push(...hardPlacedByLayer[z]!)
     }
 
@@ -253,7 +308,7 @@ export function stepGrid(state: RectDiffState): void {
       cand.y,
       grid,
       state.bounds,
-      hardBlockers,      // soft nodes DO NOT block expansion
+      hardBlockers, // soft nodes DO NOT block expansion
       initialCellRatio,
       maxAspectRatio,
       attempt.minReq,
@@ -269,7 +324,9 @@ export function stepGrid(state: RectDiffState): void {
     resizeSoftOverlaps(state, newIndex)
 
     // New: relax candidate culling — only drop seeds that became fully occupied
-    state.candidates = state.candidates.filter((c) => !isFullyOccupiedAtPoint(state, c.x, c.y))
+    state.candidates = state.candidates.filter(
+      (c) => !isFullyOccupiedAtPoint(state, c.x, c.y),
+    )
 
     return // processed one candidate
   }
@@ -304,8 +361,8 @@ export function stepExpansion(state: RectDiffState): void {
     lastGrid,
     state.bounds,
     hardBlockers,
-    0,       // seed bias off
-    null,    // no aspect cap in expansion pass
+    0, // seed bias off
+    null, // no aspect cap in expansion pass
     { width: p.rect.width, height: p.rect.height },
   )
 
@@ -326,13 +383,44 @@ export function stepExpansion(state: RectDiffState): void {
 }
 
 export function finalizeRects(state: RectDiffState): Rect3d[] {
-  return state.placed.map((p) => ({
+  // Convert all placed (free space) nodes to output format
+  const out: Rect3d[] = state.placed.map((p) => ({
     minX: p.rect.x,
     minY: p.rect.y,
     maxX: p.rect.x + p.rect.width,
     maxY: p.rect.y + p.rect.height,
     zLayers: [...p.zLayers].sort((a, b) => a - b),
   }))
+
+  /**
+   * Recover obstacles as mesh nodes.
+   * Obstacles are stored per-layer in `obstaclesByLayer`, but we want to emit
+   * single 3D nodes for multi-layer obstacles if they share the same rect.
+   * We use the `XYRect` object reference identity to group layers.
+   */
+  const layersByObstacleRect = new Map<XYRect, number[]>()
+
+  state.obstaclesByLayer.forEach((layerObs, z) => {
+    for (const rect of layerObs) {
+      const layerIndices = layersByObstacleRect.get(rect) ?? []
+      layerIndices.push(z)
+      layersByObstacleRect.set(rect, layerIndices)
+    }
+  })
+
+  // Append obstacle nodes to the output
+  for (const [rect, layerIndices] of layersByObstacleRect.entries()) {
+    out.push({
+      minX: rect.x,
+      minY: rect.y,
+      maxX: rect.x + rect.width,
+      maxY: rect.y + rect.height,
+      zLayers: layerIndices.sort((a, b) => a - b),
+      isObstacle: true,
+    })
+  }
+
+  return out
 }
 
 /** Optional: rough progress number for BaseSolver.progress */