@tscircuit/rectdiff 0.0.1

package/lib/solvers/rectdiff/engine.ts

@@ -0,0 +1,355 @@
+// lib/solvers/rectdiff/engine.ts
+import type { GridFill3DOptions, Placed3D, Rect3d, RectDiffState, XYRect } from "./types"
+import type { SimpleRouteJson } from "../../types/srj-types"
+import {
+  computeCandidates3D,
+  computeDefaultGridSizes,
+  computeEdgeCandidates3D,
+  longestFreeSpanAroundZ,
+} from "./candidates"
+import { EPS, containsPoint, expandRectFromSeed, overlaps, subtractRect2D } from "./geometry"
+import { buildZIndexMap, obstacleToXYRect, obstacleZs } from "./layers"
+
+export function initState(srj: SimpleRouteJson, opts: Partial<GridFill3DOptions>): RectDiffState {
+  const { layerNames, zIndexByName } = buildZIndexMap(srj)
+  const layerCount = Math.max(1, layerNames.length, srj.layerCount || 1)
+
+  const bounds: XYRect = {
+    x: srj.bounds.minX,
+    y: srj.bounds.minY,
+    width: srj.bounds.maxX - srj.bounds.minX,
+    height: srj.bounds.maxY - srj.bounds.minY,
+  }
+
+  // Obstacles per layer
+  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 trace = Math.max(0.01, srj.minTraceWidth || 0.15)
+  const defaults: Required<Omit<GridFill3DOptions, "gridSizes" | "maxMultiLayerSpan">> & {
+    gridSizes: number[]
+    maxMultiLayerSpan: number | undefined
+  } = {
+    gridSizes: computeDefaultGridSizes(bounds),
+    initialCellRatio: 0.2,
+    maxAspectRatio: 3,
+    minSingle: { width: 2 * trace, height: 2 * trace },
+    minMulti: {
+      width: 4 * trace,
+      height: 4 * trace,
+      minLayers: Math.min(2, Math.max(1, srj.layerCount || 1)),
+    },
+    preferMultiLayer: true,
+    maxMultiLayerSpan: undefined,
+  }
+
+  const options = { ...defaults, ...opts, gridSizes: opts.gridSizes ?? defaults.gridSizes }
+
+  const placedByLayer: XYRect[][] = Array.from({ length: layerCount }, () => [])
+
+  // Begin at the **first** grid level; candidates computed lazily on first step
+  return {
+    srj,
+    layerNames,
+    layerCount,
+    bounds,
+    options,
+    obstaclesByLayer,
+    phase: "GRID",
+    gridIndex: 0,
+    candidates: [],
+    placed: [],
+    placedByLayer,
+    expansionIndex: 0,
+    edgeAnalysisDone: false,
+    totalSeedsThisGrid: 0,
+    consumedSeedsThisGrid: 0,
+  }
+}
+
+// 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) {
+    if (p.zLayers.length >= state.layerCount) {
+      for (const z of p.zLayers) out[z]!.push(p.rect)
+    }
+  }
+  return out
+}
+
+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] ?? []
+    const occ =
+      obs.some((b) => containsPoint(b, x, y)) ||
+      placed.some((b) => containsPoint(b, x, y))
+    if (!occ) return false
+  }
+  return true
+}
+
+/** Shrink/split any *soft* (non-full-stack) nodes overlapped by `newIndex` */
+function resizeSoftOverlaps(state: RectDiffState, newIndex: number) {
+  const newcomer = state.placed[newIndex]!
+  const { rect: newR, zLayers: newZs } = newcomer
+  const layerCount = state.layerCount
+
+  const removeIdx: number[] = []
+  const toAdd: typeof state.placed = []
+
+  for (let i = 0; i < state.placed.length; i++) {
+    if (i === newIndex) continue
+    const old = state.placed[i]!
+    // Protect full-stack nodes
+    if (old.zLayers.length >= layerCount) continue
+
+    const sharedZ = old.zLayers.filter((z) => newZs.includes(z))
+    if (sharedZ.length === 0) continue
+    if (!overlaps(old.rect, newR)) continue
+
+    // Carve the overlap on the shared layers
+    const parts = subtractRect2D(old.rect, newR)
+
+    // We will replace `old` entirely; re-add unaffected layers (same rect object).
+    removeIdx.push(i)
+
+    const unaffectedZ = old.zLayers.filter((z) => !newZs.includes(z))
+    if (unaffectedZ.length > 0) {
+      toAdd.push({ rect: old.rect, zLayers: unaffectedZ })
+    }
+
+    // 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)
+    for (const p of parts) {
+      if (p.width + EPS >= minW && p.height + EPS >= minH) {
+        toAdd.push({ rect: p, zLayers: sharedZ.slice() })
+      }
+    }
+  }
+
+  // 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)
+    }
+  })
+
+  // Add replacements
+  for (const p of toAdd) {
+    state.placed.push(p)
+    for (const z of p.zLayers) state.placedByLayer[z]!.push(p.rect)
+  }
+}
+
+/** One micro-step during the GRID phase: handle (or fetch) exactly one candidate */
+export function stepGrid(state: RectDiffState): void {
+  const {
+    gridSizes,
+    initialCellRatio,
+    maxAspectRatio,
+    minSingle,
+    minMulti,
+    preferMultiLayer,
+    maxMultiLayerSpan,
+  } = state.options
+  const grid = gridSizes[state.gridIndex]!
+
+  // Build hard-placed map once per micro-step (cheap)
+  const hardPlacedByLayer = buildHardPlacedByLayer(state)
+
+  // 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.totalSeedsThisGrid = state.candidates.length
+    state.consumedSeedsThisGrid = 0
+  }
+
+  // If no candidates remain, advance grid or run edge pass or switch phase
+  if (state.candidates.length === 0) {
+    if (state.gridIndex + 1 < gridSizes.length) {
+      state.gridIndex += 1
+      state.totalSeedsThisGrid = 0
+      state.consumedSeedsThisGrid = 0
+      return
+    } else {
+      if (!state.edgeAnalysisDone) {
+        const minSize = Math.min(minSingle.width, minSingle.height)
+        state.candidates = computeEdgeCandidates3D(
+          state.bounds,
+          minSize,
+          state.layerCount,
+          state.obstaclesByLayer,
+          state.placedByLayer,   // for fully-occupied test
+          hardPlacedByLayer,
+        )
+        state.edgeAnalysisDone = true
+        state.totalSeedsThisGrid = state.candidates.length
+        state.consumedSeedsThisGrid = 0
+        return
+      }
+      state.phase = "EXPANSION"
+      state.expansionIndex = 0
+      return
+    }
+  }
+
+  // Consume exactly one candidate
+  const cand = state.candidates.shift()!
+  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 attempts: Array<{
+    kind: "multi" | "single"
+    layers: number[]
+    minReq: { width: number; height: number }
+  }> = []
+
+  if (span.length >= minMulti.minLayers) {
+    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 } })
+
+  const ordered = preferMultiLayer ? attempts : attempts.reverse()
+
+  for (const attempt of ordered) {
+    // 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 (hardPlacedByLayer[z]) hardBlockers.push(...hardPlacedByLayer[z]!)
+    }
+
+    const rect = expandRectFromSeed(
+      cand.x,
+      cand.y,
+      grid,
+      state.bounds,
+      hardBlockers,      // soft nodes DO NOT block expansion
+      initialCellRatio,
+      maxAspectRatio,
+      attempt.minReq,
+    )
+    if (!rect) continue
+
+    // Place the new node
+    const placed: Placed3D = { rect, zLayers: [...attempt.layers] }
+    const newIndex = state.placed.push(placed) - 1
+    for (const z of attempt.layers) state.placedByLayer[z]!.push(rect)
+
+    // New: carve overlapped soft nodes
+    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))
+
+    return // processed one candidate
+  }
+
+  // Neither attempt worked; drop this candidate for now.
+}
+
+/** 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"
+    return
+  }
+
+  const idx = state.expansionIndex
+  const p = state.placed[idx]!
+  const lastGrid = state.options.gridSizes[state.options.gridSizes.length - 1]!
+
+  const hardPlacedByLayer = buildHardPlacedByLayer(state)
+
+  // HARD blockers only: obstacles on p.zLayers + full-stack nodes
+  const hardBlockers: XYRect[] = []
+  for (const z of p.zLayers) {
+    hardBlockers.push(...(state.obstaclesByLayer[z] ?? []))
+    hardBlockers.push(...(hardPlacedByLayer[z] ?? []))
+  }
+
+  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 },
+  )
+
+  if (expanded) {
+    // Update placement + per-layer index (replace old rect object)
+    state.placed[idx] = { rect: expanded, zLayers: p.zLayers }
+    for (const z of p.zLayers) {
+      const arr = state.placedByLayer[z]!
+      const j = arr.findIndex((r) => r === oldRect)
+      if (j >= 0) arr[j] = expanded
+    }
+
+    // Carve overlapped soft neighbors (respect full-stack nodes)
+    resizeSoftOverlaps(state, idx)
+  }
+
+  state.expansionIndex += 1
+}
+
+export function finalizeRects(state: RectDiffState): Rect3d[] {
+  return 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),
+  }))
+}
+
+/** Optional: rough progress number for BaseSolver.progress */
+export function computeProgress(state: RectDiffState): number {
+  const grids = state.options.gridSizes.length
+  if (state.phase === "GRID") {
+    const g = state.gridIndex
+    const base = g / (grids + 1) // reserve final slice for expansion
+    const denom = Math.max(1, state.totalSeedsThisGrid)
+    const frac = denom ? state.consumedSeedsThisGrid / denom : 1
+    return Math.min(0.999, base + frac * (1 / (grids + 1)))
+  }
+  if (state.phase === "EXPANSION") {
+    const base = grids / (grids + 1)
+    const denom = Math.max(1, state.placed.length)
+    const frac = denom ? state.expansionIndex / denom : 1
+    return Math.min(0.999, base + frac * (1 / (grids + 1)))
+  }
+  return 1
+}

package/lib/solvers/rectdiff/geometry.ts

@@ -0,0 +1,284 @@
+// lib/solvers/rectdiff/geometry.ts
+import type { XYRect } from "./types"
+
+export const EPS = 1e-9
+export const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v))
+export const gt = (a: number, b: number) => a > b + EPS
+export const gte = (a: number, b: number) => a > b - EPS
+export const lt = (a: number, b: number) => a < b - EPS
+export const lte = (a: number, b: number) => a < b + EPS
+
+export function overlaps(a: XYRect, b: XYRect) {
+  return !(
+    a.x + a.width <= b.x + EPS ||
+    b.x + b.width <= a.x + EPS ||
+    a.y + a.height <= b.y + EPS ||
+    b.y + b.height <= a.y + EPS
+  )
+}
+
+export function containsPoint(r: XYRect, x: number, y: number) {
+  return (
+    x >= r.x - EPS && x <= r.x + r.width + EPS &&
+    y >= r.y - EPS && y <= r.y + r.height + EPS
+  )
+}
+
+export function distancePointToRectEdges(px: number, py: number, r: XYRect) {
+  const edges: [number, number, number, number][] = [
+    [r.x, r.y, r.x + r.width, r.y],
+    [r.x + r.width, r.y, r.x + r.width, r.y + r.height],
+    [r.x + r.width, r.y + r.height, r.x, r.y + r.height],
+    [r.x, r.y + r.height, r.x, r.y],
+  ]
+  let best = Infinity
+  for (const [x1, y1, x2, y2] of edges) {
+    const A = px - x1, B = py - y1, C = x2 - x1, D = y2 - y1
+    const dot = A * C + B * D
+    const lenSq = C * C + D * D
+    let t = lenSq !== 0 ? dot / lenSq : 0
+    t = clamp(t, 0, 1)
+    const xx = x1 + t * C
+    const yy = y1 + t * D
+    best = Math.min(best, Math.hypot(px - xx, py - yy))
+  }
+  return best
+}
+
+// --- directional expansion caps (respect board + blockers + aspect) ---
+
+function maxExpandRight(
+  r: XYRect, bounds: XYRect, blockers: XYRect[], maxAspect: number | null | undefined
+) {
+  // Start with board boundary
+  let maxWidth = bounds.x + bounds.width - r.x
+
+  // Check all blockers that could limit rightward expansion
+  for (const b of blockers) {
+    // Only consider blockers that vertically overlap with current rect
+    const verticallyOverlaps = r.y + r.height > b.y + EPS && b.y + b.height > r.y + EPS
+    if (verticallyOverlaps) {
+      // Blocker is to the right - limits how far we can expand
+      if (gte(b.x, r.x + r.width)) {
+        maxWidth = Math.min(maxWidth, b.x - r.x)
+      }
+      // Blocker overlaps current position - can't expand at all
+      else if (b.x + b.width > r.x + r.width - EPS && b.x < r.x + r.width + EPS) {
+        return 0
+      }
+    }
+  }
+
+  let e = Math.max(0, maxWidth - r.width)
+  if (e <= 0) return 0
+
+  // Apply aspect ratio constraint
+  if (maxAspect != null) {
+    const w = r.width, h = r.height
+    if (w >= h) e = Math.min(e, maxAspect * h - w)
+  }
+  return Math.max(0, e)
+}
+
+function maxExpandDown(
+  r: XYRect, bounds: XYRect, blockers: XYRect[], maxAspect: number | null | undefined
+) {
+  // Start with board boundary
+  let maxHeight = bounds.y + bounds.height - r.y
+
+  // Check all blockers that could limit downward expansion
+  for (const b of blockers) {
+    // Only consider blockers that horizontally overlap with current rect
+    const horizOverlaps = r.x + r.width > b.x + EPS && b.x + b.width > r.x + EPS
+    if (horizOverlaps) {
+      // Blocker is below - limits how far we can expand
+      if (gte(b.y, r.y + r.height)) {
+        maxHeight = Math.min(maxHeight, b.y - r.y)
+      }
+      // Blocker overlaps current position - can't expand at all
+      else if (b.y + b.height > r.y + r.height - EPS && b.y < r.y + r.height + EPS) {
+        return 0
+      }
+    }
+  }
+
+  let e = Math.max(0, maxHeight - r.height)
+  if (e <= 0) return 0
+
+  // Apply aspect ratio constraint
+  if (maxAspect != null) {
+    const w = r.width, h = r.height
+    if (h >= w) e = Math.min(e, maxAspect * w - h)
+  }
+  return Math.max(0, e)
+}
+
+function maxExpandLeft(
+  r: XYRect, bounds: XYRect, blockers: XYRect[], maxAspect: number | null | undefined
+) {
+  // Start with board boundary
+  let minX = bounds.x
+
+  // Check all blockers that could limit leftward expansion
+  for (const b of blockers) {
+    // Only consider blockers that vertically overlap with current rect
+    const verticallyOverlaps = r.y + r.height > b.y + EPS && b.y + b.height > r.y + EPS
+    if (verticallyOverlaps) {
+      // Blocker is to the left - limits how far we can expand
+      if (lte(b.x + b.width, r.x)) {
+        minX = Math.max(minX, b.x + b.width)
+      }
+      // Blocker overlaps current position - can't expand at all
+      else if (b.x < r.x + EPS && b.x + b.width > r.x - EPS) {
+        return 0
+      }
+    }
+  }
+
+  let e = Math.max(0, r.x - minX)
+  if (e <= 0) return 0
+
+  // Apply aspect ratio constraint
+  if (maxAspect != null) {
+    const w = r.width, h = r.height
+    if (w >= h) e = Math.min(e, maxAspect * h - w)
+  }
+  return Math.max(0, e)
+}
+
+function maxExpandUp(
+  r: XYRect, bounds: XYRect, blockers: XYRect[], maxAspect: number | null | undefined
+) {
+  // Start with board boundary
+  let minY = bounds.y
+
+  // Check all blockers that could limit upward expansion
+  for (const b of blockers) {
+    // Only consider blockers that horizontally overlap with current rect
+    const horizOverlaps = r.x + r.width > b.x + EPS && b.x + b.width > r.x + EPS
+    if (horizOverlaps) {
+      // Blocker is above - limits how far we can expand
+      if (lte(b.y + b.height, r.y)) {
+        minY = Math.max(minY, b.y + b.height)
+      }
+      // Blocker overlaps current position - can't expand at all
+      else if (b.y < r.y + EPS && b.y + b.height > r.y - EPS) {
+        return 0
+      }
+    }
+  }
+
+  let e = Math.max(0, r.y - minY)
+  if (e <= 0) return 0
+
+  // Apply aspect ratio constraint
+  if (maxAspect != null) {
+    const w = r.width, h = r.height
+    if (h >= w) e = Math.min(e, maxAspect * w - h)
+  }
+  return Math.max(0, e)
+}
+
+/** Grow a rect around (startX,startY), honoring bounds/blockers/aspect/min sizes */
+export function expandRectFromSeed(
+  startX: number,
+  startY: number,
+  gridSize: number,
+  bounds: XYRect,
+  blockers: XYRect[],
+  initialCellRatio: number,
+  maxAspectRatio: number | null | undefined,
+  minReq: { width: number; height: number },
+): XYRect | null {
+  const minSide = Math.max(1e-9, gridSize * initialCellRatio)
+  const initialW = Math.max(minSide, minReq.width)
+  const initialH = Math.max(minSide, minReq.height)
+
+  const strategies = [
+    { ox: 0, oy: 0 },
+    { ox: -initialW, oy: 0 },
+    { ox: 0, oy: -initialH },
+    { ox: -initialW, oy: -initialH },
+    { ox: -initialW / 2, oy: -initialH / 2 },
+  ]
+
+  let best: XYRect | null = null
+  let bestArea = 0
+
+  STRATS: for (const s of strategies) {
+    let r: XYRect = { x: startX + s.ox, y: startY + s.oy, width: initialW, height: initialH }
+
+    // keep initial inside board
+    if (lt(r.x, bounds.x) || lt(r.y, bounds.y) ||
+        gt(r.x + r.width, bounds.x + bounds.width) ||
+        gt(r.y + r.height, bounds.y + bounds.height)) {
+      continue
+    }
+
+    // no initial overlap
+    for (const b of blockers) if (overlaps(r, b)) continue STRATS
+
+    // greedy expansions in 4 directions
+    let improved = true
+    while (improved) {
+      improved = false
+      const eR = maxExpandRight(r, bounds, blockers, maxAspectRatio)
+      if (eR > 0) { r = { ...r, width: r.width + eR }; improved = true }
+
+      const eD = maxExpandDown(r, bounds, blockers, maxAspectRatio)
+      if (eD > 0) { r = { ...r, height: r.height + eD }; improved = true }
+
+      const eL = maxExpandLeft(r, bounds, blockers, maxAspectRatio)
+      if (eL > 0) { r = { x: r.x - eL, y: r.y, width: r.width + eL, height: r.height }; improved = true }
+
+      const eU = maxExpandUp(r, bounds, blockers, maxAspectRatio)
+      if (eU > 0) { r = { x: r.x, y: r.y - eU, width: r.width, height: r.height + eU }; improved = true }
+    }
+
+    if (r.width + EPS >= minReq.width && r.height + EPS >= minReq.height) {
+      const area = r.width * r.height
+      if (area > bestArea) { best = r; bestArea = area }
+    }
+  }
+
+  return best
+}
+
+export function intersect1D(a0: number, a1: number, b0: number, b1: number) {
+  const lo = Math.max(a0, b0)
+  const hi = Math.min(a1, b1)
+  return hi > lo + EPS ? [lo, hi] as const : null
+}
+
+/** Return A \ B as up to 4 non-overlapping rectangles (or [A] if no overlap). */
+export function subtractRect2D(A: XYRect, B: XYRect): XYRect[] {
+  if (!overlaps(A, B)) return [A]
+
+  const Xi = intersect1D(A.x, A.x + A.width, B.x, B.x + B.width)
+  const Yi = intersect1D(A.y, A.y + A.height, B.y, B.y + B.height)
+  if (!Xi || !Yi) return [A]
+
+  const [X0, X1] = Xi
+  const [Y0, Y1] = Yi
+  const out: XYRect[] = []
+
+  // Left strip
+  if (X0 > A.x + EPS) {
+    out.push({ x: A.x, y: A.y, width: X0 - A.x, height: A.height })
+  }
+  // Right strip
+  if (A.x + A.width > X1 + EPS) {
+    out.push({ x: X1, y: A.y, width: (A.x + A.width) - X1, height: A.height })
+  }
+  // Top wedge in the middle band
+  const midW = Math.max(0, X1 - X0)
+  if (midW > EPS && Y0 > A.y + EPS) {
+    out.push({ x: X0, y: A.y, width: midW, height: Y0 - A.y })
+  }
+  // Bottom wedge in the middle band
+  if (midW > EPS && A.y + A.height > Y1 + EPS) {
+    out.push({ x: X0, y: Y1, width: midW, height: (A.y + A.height) - Y1 })
+  }
+
+  return out.filter((r) => r.width > EPS && r.height > EPS)
+}

package/lib/solvers/rectdiff/layers.ts

@@ -0,0 +1,48 @@
+// lib/solvers/rectdiff/layers.ts
+import type { SimpleRouteJson, Obstacle } from "../../types/srj-types"
+import type { XYRect } from "./types"
+
+function layerSortKey(n: string) {
+  const L = n.toLowerCase()
+  if (L === "top") return -1_000_000
+  if (L === "bottom") return 1_000_000
+  const m = /^inner(\d+)$/i.exec(L)
+  if (m) return parseInt(m[1]!, 10) || 0
+  return 100 + L.charCodeAt(0)
+}
+
+export function canonicalizeLayerOrder(names: string[]) {
+  return Array.from(new Set(names)).sort((a, b) => {
+    const ka = layerSortKey(a)
+    const kb = layerSortKey(b)
+    if (ka !== kb) return ka - kb
+    return a.localeCompare(b)
+  })
+}
+
+export function buildZIndexMap(srj: SimpleRouteJson) {
+  const names = canonicalizeLayerOrder((srj.obstacles ?? []).flatMap((o) => o.layers ?? []))
+  const fallback = Array.from(
+    { length: Math.max(1, srj.layerCount || 1) },
+    (_, i) => (i === 0 ? "top" : i === (srj.layerCount || 1) - 1 ? "bottom" : `inner${i}`),
+  )
+  const layerNames = names.length ? names : fallback
+  const map = new Map<string, number>()
+  layerNames.forEach((n, i) => map.set(n, i))
+  return { layerNames, zIndexByName: map }
+}
+
+export function obstacleZs(ob: Obstacle, zIndexByName: Map<string, number>) {
+  if (ob.zLayers?.length) return Array.from(new Set(ob.zLayers)).sort((a, b) => a - b)
+  const fromNames = (ob.layers ?? [])
+    .map((n) => zIndexByName.get(n))
+    .filter((v): v is number => typeof v === "number")
+  return Array.from(new Set(fromNames)).sort((a, b) => a - b)
+}
+
+export function obstacleToXYRect(ob: Obstacle): XYRect | null {
+  const w = ob.width as any
+  const h = ob.height as any
+  if (typeof w !== "number" || typeof h !== "number") return null
+  return { x: ob.center.x - w / 2, y: ob.center.y - h / 2, width: w, height: h }
+}

package/lib/solvers/rectdiff/rectsToMeshNodes.ts

@@ -0,0 +1,22 @@
+// lib/solvers/rectdiff/rectsToMeshNodes.ts
+import type { Rect3d } from "./types"
+import type { CapacityMeshNode } from "../../types/capacity-mesh-types"
+
+export function rectsToMeshNodes(rects: Rect3d[]): CapacityMeshNode[] {
+  let id = 0
+  const out: CapacityMeshNode[] = []
+  for (const r of rects) {
+    const w = Math.max(0, r.maxX - r.minX)
+    const h = Math.max(0, r.maxY - r.minY)
+    if (w <= 0 || h <= 0 || r.zLayers.length === 0) continue
+    out.push({
+      capacityMeshNodeId: `cmn_${id++}`,
+      center: { x: (r.minX + r.maxX) / 2, y: (r.minY + r.maxY) / 2 },
+      width: w,
+      height: h,
+      layer: "top",
+      availableZ: r.zLayers.slice(),
+    })
+  }
+  return out
+}