@tscircuit/rectdiff 0.0.4 → 0.0.5

package/dist/index.js

@@ -1,5 +1,5 @@
 // lib/solvers/RectDiffSolver.ts
-import { BaseSolver } from "@tscircuit/solver-utils";
+import { BaseSolver as BaseSolver2 } from "@tscircuit/solver-utils";
 
 // lib/solvers/rectdiff/geometry.ts
 var EPS = 1e-9;
@@ -114,7 +114,17 @@ function maxExpandUp(r, bounds, blockers, maxAspect) {
   }
   return Math.max(0, e);
 }
-function expandRectFromSeed(startX, startY, gridSize, bounds, blockers, initialCellRatio, maxAspectRatio, minReq) {
+function expandRectFromSeed(params) {
+  const {
+    startX,
+    startY,
+    gridSize,
+    bounds,
+    blockers,
+    initialCellRatio,
+    maxAspectRatio,
+    minReq
+  } = params;
   const minSide = Math.max(1e-9, gridSize * initialCellRatio);
   const initialW = Math.max(minSide, minReq.width);
   const initialH = Math.max(minSide, minReq.height);
@@ -202,7 +212,8 @@ function subtractRect2D(A, B) {
 }
 
 // lib/solvers/rectdiff/candidates.ts
-function isFullyOccupiedAllLayers(x, y, layerCount, obstaclesByLayer, placedByLayer) {
+function isFullyOccupiedAllLayers(params) {
+  const { x, y, layerCount, obstaclesByLayer, placedByLayer } = params;
   for (let z = 0; z < layerCount; z++) {
     const obs = obstaclesByLayer[z] ?? [];
     const placed = placedByLayer[z] ?? [];
@@ -211,36 +222,42 @@ function isFullyOccupiedAllLayers(x, y, layerCount, obstaclesByLayer, placedByLa
   }
   return true;
 }
-function computeCandidates3D(bounds, gridSize, layerCount, obstaclesByLayer, placedByLayer, hardPlacedByLayer) {
+function computeCandidates3D(params) {
+  const {
+    bounds,
+    gridSize,
+    layerCount,
+    obstaclesByLayer,
+    placedByLayer,
+    hardPlacedByLayer
+  } = params;
   const out = /* @__PURE__ */ new Map();
   for (let x = bounds.x; x < bounds.x + bounds.width; x += gridSize) {
     for (let y = bounds.y; y < bounds.y + bounds.height; y += gridSize) {
       if (Math.abs(x - bounds.x) < EPS || Math.abs(y - bounds.y) < EPS || x > bounds.x + bounds.width - gridSize - EPS || y > bounds.y + bounds.height - gridSize - EPS) {
         continue;
       }
-      if (isFullyOccupiedAllLayers(
+      if (isFullyOccupiedAllLayers({
         x,
         y,
         layerCount,
         obstaclesByLayer,
         placedByLayer
-      ))
+      }))
         continue;
       let bestSpan = [];
       let bestZ = 0;
       for (let z = 0; z < layerCount; z++) {
-        const s = longestFreeSpanAroundZ(
+        const s = longestFreeSpanAroundZ({
           x,
           y,
           z,
           layerCount,
-          1,
-          void 0,
-          // no cap here
+          minSpan: 1,
+          maxSpan: void 0,
           obstaclesByLayer,
-          hardPlacedByLayer
-          // IMPORTANT: ignore soft nodes
-        );
+          placedByLayer: hardPlacedByLayer
+        });
         if (s.length > bestSpan.length) {
           bestSpan = s;
           bestZ = z;
@@ -273,7 +290,17 @@ function computeCandidates3D(bounds, gridSize, layerCount, obstaclesByLayer, pla
   arr.sort((a, b) => b.zSpanLen - a.zSpanLen || b.distance - a.distance);
   return arr;
 }
-function longestFreeSpanAroundZ(x, y, z, layerCount, minSpan, maxSpan, obstaclesByLayer, placedByLayer) {
+function longestFreeSpanAroundZ(params) {
+  const {
+    x,
+    y,
+    z,
+    layerCount,
+    minSpan,
+    maxSpan,
+    obstaclesByLayer,
+    placedByLayer
+  } = params;
   const isFreeAt = (layer) => {
     const blockers = [
       ...obstaclesByLayer[layer] ?? [],
@@ -300,7 +327,8 @@ function computeDefaultGridSizes(bounds) {
   const ref = Math.max(bounds.width, bounds.height);
   return [ref / 8, ref / 16, ref / 32];
 }
-function computeUncoveredSegments(lineStart, lineEnd, coveringIntervals, minSegmentLength) {
+function computeUncoveredSegments(params) {
+  const { lineStart, lineEnd, coveringIntervals, minSegmentLength } = params;
   if (coveringIntervals.length === 0) {
     const center = (lineStart + lineEnd) / 2;
     return [{ start: lineStart, end: lineEnd, center }];
@@ -342,19 +370,27 @@ function computeUncoveredSegments(lineStart, lineEnd, coveringIntervals, minSegm
   }
   return uncovered;
 }
-function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer, placedByLayer, hardPlacedByLayer) {
+function computeEdgeCandidates3D(params) {
+  const {
+    bounds,
+    minSize,
+    layerCount,
+    obstaclesByLayer,
+    placedByLayer,
+    hardPlacedByLayer
+  } = params;
   const out = [];
   const \u03B4 = Math.max(minSize * 0.15, EPS * 3);
   const dedup = /* @__PURE__ */ new Set();
   const key = (x, y, z) => `${z}|${x.toFixed(6)}|${y.toFixed(6)}`;
   function fullyOcc(x, y) {
-    return isFullyOccupiedAllLayers(
+    return isFullyOccupiedAllLayers({
       x,
       y,
       layerCount,
       obstaclesByLayer,
       placedByLayer
-    );
+    });
   }
   function pushIfFree(x, y, z) {
     if (x < bounds.x + EPS || y < bounds.y + EPS || x > bounds.x + bounds.width - EPS || y > bounds.y + bounds.height - EPS)
@@ -371,16 +407,16 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
     const k = key(x, y, z);
     if (dedup.has(k)) return;
     dedup.add(k);
-    const span = longestFreeSpanAroundZ(
+    const span = longestFreeSpanAroundZ({
       x,
       y,
       z,
       layerCount,
-      1,
-      void 0,
+      minSpan: 1,
+      maxSpan: void 0,
       obstaclesByLayer,
-      hardPlacedByLayer
-    );
+      placedByLayer: hardPlacedByLayer
+    });
     out.push({ x, y, z, distance: d, zSpanLen: span.length, isEdgeSeed: true });
   }
   for (let z = 0; z < layerCount; z++) {
@@ -406,12 +442,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
       start: Math.max(bounds.x, b.x),
       end: Math.min(bounds.x + bounds.width, b.x + b.width)
     }));
-    const topUncovered = computeUncoveredSegments(
-      bounds.x + \u03B4,
-      bounds.x + bounds.width - \u03B4,
-      topCovering,
-      minSize * 0.5
-    );
+    const topUncovered = computeUncoveredSegments({
+      lineStart: bounds.x + \u03B4,
+      lineEnd: bounds.x + bounds.width - \u03B4,
+      coveringIntervals: topCovering,
+      minSegmentLength: minSize * 0.5
+    });
     for (const seg of topUncovered) {
       const segLen = seg.end - seg.start;
       if (segLen >= minSize) {
@@ -427,12 +463,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
       start: Math.max(bounds.x, b.x),
       end: Math.min(bounds.x + bounds.width, b.x + b.width)
     }));
-    const bottomUncovered = computeUncoveredSegments(
-      bounds.x + \u03B4,
-      bounds.x + bounds.width - \u03B4,
-      bottomCovering,
-      minSize * 0.5
-    );
+    const bottomUncovered = computeUncoveredSegments({
+      lineStart: bounds.x + \u03B4,
+      lineEnd: bounds.x + bounds.width - \u03B4,
+      coveringIntervals: bottomCovering,
+      minSegmentLength: minSize * 0.5
+    });
     for (const seg of bottomUncovered) {
       const segLen = seg.end - seg.start;
       if (segLen >= minSize) {
@@ -448,12 +484,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
       start: Math.max(bounds.y, b.y),
       end: Math.min(bounds.y + bounds.height, b.y + b.height)
     }));
-    const leftUncovered = computeUncoveredSegments(
-      bounds.y + \u03B4,
-      bounds.y + bounds.height - \u03B4,
-      leftCovering,
-      minSize * 0.5
-    );
+    const leftUncovered = computeUncoveredSegments({
+      lineStart: bounds.y + \u03B4,
+      lineEnd: bounds.y + bounds.height - \u03B4,
+      coveringIntervals: leftCovering,
+      minSegmentLength: minSize * 0.5
+    });
     for (const seg of leftUncovered) {
       const segLen = seg.end - seg.start;
       if (segLen >= minSize) {
@@ -469,12 +505,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
       start: Math.max(bounds.y, b.y),
       end: Math.min(bounds.y + bounds.height, b.y + b.height)
     }));
-    const rightUncovered = computeUncoveredSegments(
-      bounds.y + \u03B4,
-      bounds.y + bounds.height - \u03B4,
-      rightCovering,
-      minSize * 0.5
-    );
+    const rightUncovered = computeUncoveredSegments({
+      lineStart: bounds.y + \u03B4,
+      lineEnd: bounds.y + bounds.height - \u03B4,
+      coveringIntervals: rightCovering,
+      minSegmentLength: minSize * 0.5
+    });
     for (const seg of rightUncovered) {
       const segLen = seg.end - seg.start;
       if (segLen >= minSize) {
@@ -494,12 +530,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
           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
-        );
+        const obLeftUncovered = computeUncoveredSegments({
+          lineStart: b.y,
+          lineEnd: b.y + b.height,
+          coveringIntervals: obLeftCovering,
+          minSegmentLength: minSize * 0.5
+        });
         for (const seg of obLeftUncovered) {
           pushIfFree(obLeftX, seg.center, z);
         }
@@ -512,12 +548,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
           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
-        );
+        const obRightUncovered = computeUncoveredSegments({
+          lineStart: b.y,
+          lineEnd: b.y + b.height,
+          coveringIntervals: obRightCovering,
+          minSegmentLength: minSize * 0.5
+        });
         for (const seg of obRightUncovered) {
           pushIfFree(obRightX, seg.center, z);
         }
@@ -530,12 +566,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
           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
-        );
+        const obTopUncovered = computeUncoveredSegments({
+          lineStart: b.x,
+          lineEnd: b.x + b.width,
+          coveringIntervals: obTopCovering,
+          minSegmentLength: minSize * 0.5
+        });
         for (const seg of obTopUncovered) {
           pushIfFree(seg.center, obTopY, z);
         }
@@ -548,12 +584,12 @@ function computeEdgeCandidates3D(bounds, minSize, layerCount, obstaclesByLayer,
           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
-        );
+        const obBottomUncovered = computeUncoveredSegments({
+          lineStart: b.x,
+          lineEnd: b.x + b.width,
+          coveringIntervals: obBottomCovering,
+          minSegmentLength: minSize * 0.5
+        });
         for (const seg of obBottomUncovered) {
           pushIfFree(seg.center, obBottomY, z);
         }
@@ -715,11 +751,11 @@ function buildHardPlacedByLayer(state) {
   }
   return out;
 }
-function isFullyOccupiedAtPoint(state, x, y) {
+function isFullyOccupiedAtPoint(state, point) {
   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));
+    const occ = obs.some((b) => containsPoint(b, point.x, point.y)) || placed.some((b) => containsPoint(b, point.x, point.y));
     if (!occ) return false;
   }
   return true;
@@ -783,16 +819,14 @@ function stepGrid(state) {
   const grid = gridSizes[state.gridIndex];
   const hardPlacedByLayer = buildHardPlacedByLayer(state);
   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
+    state.candidates = computeCandidates3D({
+      bounds: state.bounds,
+      gridSize: grid,
+      layerCount: state.layerCount,
+      obstaclesByLayer: state.obstaclesByLayer,
+      placedByLayer: state.placedByLayer,
       hardPlacedByLayer
-      // hard blockers for ranking/span
-    );
+    });
     state.totalSeedsThisGrid = state.candidates.length;
     state.consumedSeedsThisGrid = 0;
   }
@@ -805,15 +839,14 @@ function stepGrid(state) {
     } 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;
@@ -826,17 +859,16 @@ function stepGrid(state) {
   }
   const cand = state.candidates.shift();
   state.consumedSeedsThisGrid += 1;
-  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 = [];
   if (span.length >= minMulti.minLayers) {
     attempts.push({
@@ -858,31 +890,30 @@ function stepGrid(state) {
         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
+    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;
     const placed = { rect, zLayers: [...attempt.layers] };
     const newIndex = state.placed.push(placed) - 1;
     for (const z of attempt.layers) state.placedByLayer[z].push(rect);
     resizeSoftOverlaps(state, newIndex);
     state.candidates = state.candidates.filter(
-      (c) => !isFullyOccupiedAtPoint(state, c.x, c.y)
+      (c) => !isFullyOccupiedAtPoint(state, { x: c.x, y: c.y })
     );
     return;
   }
 }
 function stepExpansion(state) {
   if (state.expansionIndex >= state.placed.length) {
-    state.phase = "DONE";
+    state.phase = "GAP_FILL";
     return;
   }
   const idx = state.expansionIndex;
@@ -895,18 +926,16 @@ function stepExpansion(state) {
     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 }
-  );
+  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) {
     state.placed[idx] = { rect: expanded, zLayers: p.zLayers };
     for (const z of p.zLayers) {
@@ -986,18 +1015,647 @@ function rectsToMeshNodes(rects) {
   return out;
 }
 
+// lib/solvers/rectdiff/gapfill/engine/calculateCoverage.ts
+function calculateCoverage({ sampleResolution = 0.1 }, ctx) {
+  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;
+}
+
+// lib/solvers/rectdiff/gapfill/engine/findUncoveredPoints.ts
+function findUncoveredPoints({ sampleResolution = 0.05 }, ctx) {
+  const { bounds, layerCount, obstaclesByLayer, placedByLayer } = ctx;
+  const uncovered = [];
+  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;
+}
+
+// lib/solvers/rectdiff/gapfill/engine/getGapFillProgress.ts
+function getGapFillProgress(state) {
+  if (state.done) return 1;
+  const iterationProgress = state.iteration / state.options.maxIterations;
+  const gapProgress = state.gapsFound.length > 0 ? state.gapIndex / state.gapsFound.length : 0;
+  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) : 0;
+  return Math.min(
+    0.999,
+    iterationProgress + (gapProgress + gapStageProgress) / state.options.maxIterations
+  );
+}
+
+// lib/solvers/rectdiff/gapfill/engine/initGapFillState.ts
+var DEFAULT_OPTIONS = {
+  minWidth: 0.1,
+  minHeight: 0.1,
+  maxIterations: 10,
+  targetCoverage: 0.999,
+  scanResolution: 0.5
+};
+function initGapFillState({
+  placed,
+  options
+}, ctx) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const placedCopy = placed.map((p) => ({
+    rect: { ...p.rect },
+    zLayers: [...p.zLayers]
+  }));
+  const placedByLayerCopy = ctx.placedByLayer.map(
+    (layer) => layer.map((r) => ({ ...r }))
+  );
+  return {
+    bounds: { ...ctx.bounds },
+    layerCount: ctx.layerCount,
+    obstaclesByLayer: ctx.obstaclesByLayer,
+    placed: placedCopy,
+    placedByLayer: placedByLayerCopy,
+    options: opts,
+    iteration: 0,
+    gapsFound: [],
+    gapIndex: 0,
+    done: false,
+    initialGapCount: 0,
+    filledCount: 0,
+    // Four-stage visualization state
+    stage: "scan",
+    currentGap: null,
+    currentSeed: null,
+    expandedRect: null
+  };
+}
+
+// lib/solvers/rectdiff/gapfill/detection/mergeUncoveredCells.ts
+function mergeUncoveredCells(cells) {
+  if (cells.length === 0) return [];
+  const byXW = /* @__PURE__ */ new Map();
+  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);
+  }
+  const verticalStrips = [];
+  for (const stripCells of byXW.values()) {
+    stripCells.sort((a, b) => a.y - b.y);
+    let current = 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) {
+        current.height += c.h;
+      } else {
+        verticalStrips.push(current);
+        current = { x: c.x, y: c.y, width: c.w, height: c.h };
+      }
+    }
+    if (current) verticalStrips.push(current);
+  }
+  const byYH = /* @__PURE__ */ new Map();
+  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 = [];
+  for (const rowRects of byYH.values()) {
+    rowRects.sort((a, b) => a.x - b.x);
+    let current = null;
+    for (const r of rowRects) {
+      if (!current) {
+        current = { ...r };
+      } else if (Math.abs(current.x + current.width - r.x) < EPS) {
+        current.width += r.width;
+      } else {
+        merged.push(current);
+        current = { ...r };
+      }
+    }
+    if (current) merged.push(current);
+  }
+  return merged;
+}
+
+// lib/solvers/rectdiff/gapfill/detection/findGapsOnLayer.ts
+function findGapsOnLayer({
+  bounds,
+  obstacles,
+  placed,
+  scanResolution
+}) {
+  const blockers = [...obstacles, ...placed];
+  const xCoords = /* @__PURE__ */ new Set();
+  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);
+    }
+  }
+  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);
+  const yCoords = /* @__PURE__ */ new Set();
+  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);
+  const uncoveredCells = [];
+  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;
+      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 });
+      }
+    }
+  }
+  return mergeUncoveredCells(uncoveredCells);
+}
+
+// utils/rectsOverlap.ts
+function rectsOverlap(a, b) {
+  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);
+}
+
+// utils/rectsEqual.ts
+function rectsEqual(a, b) {
+  return Math.abs(a.x - b.x) < EPS && Math.abs(a.y - b.y) < EPS && Math.abs(a.width - b.width) < EPS && Math.abs(a.height - b.height) < EPS;
+}
+
+// lib/solvers/rectdiff/gapfill/detection/deduplicateGaps.ts
+function deduplicateGaps(gaps) {
+  const result = [];
+  for (const gap of gaps) {
+    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) {
+      const idx = result.indexOf(existing);
+      result[idx] = gap;
+    }
+  }
+  return result;
+}
+
+// lib/solvers/rectdiff/gapfill/detection/findAllGaps.ts
+function findAllGaps({
+  scanResolution,
+  minWidth,
+  minHeight
+}, ctx) {
+  const { bounds, layerCount, obstaclesByLayer, placedByLayer } = ctx;
+  const gapsByLayer = [];
+  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);
+  }
+  const allGaps = [];
+  for (let z = 0; z < layerCount; z++) {
+    for (const gap of gapsByLayer[z]) {
+      if (gap.width < minWidth - EPS || gap.height < minHeight - EPS) continue;
+      const zLayers = [z];
+      for (let zu = z + 1; zu < layerCount; zu++) {
+        const hasOverlap = gapsByLayer[zu].some((g) => rectsOverlap(g, gap));
+        if (hasOverlap) zLayers.push(zu);
+        else break;
+      }
+      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
+      });
+    }
+  }
+  const deduped = deduplicateGaps(allGaps);
+  deduped.sort((a, b) => {
+    const layerDiff = b.zLayers.length - a.zLayers.length;
+    if (layerDiff !== 0) return layerDiff;
+    return b.area - a.area;
+  });
+  return deduped;
+}
+
+// lib/solvers/rectdiff/gapfill/engine/tryExpandGap.ts
+function tryExpandGap(state, {
+  gap,
+  seed
+}) {
+  const blockers = [];
+  for (const z of gap.zLayers) {
+    blockers.push(...state.obstaclesByLayer[z] ?? []);
+    blockers.push(...state.placedByLayer[z] ?? []);
+  }
+  const rect = expandRectFromSeed({
+    startX: seed.x,
+    startY: seed.y,
+    gridSize: Math.min(gap.rect.width, gap.rect.height),
+    bounds: state.bounds,
+    blockers,
+    initialCellRatio: 0,
+    maxAspectRatio: null,
+    minReq: { width: state.options.minWidth, height: state.options.minHeight }
+  });
+  if (!rect) {
+    const seeds = [
+      { x: gap.rect.x + state.options.minWidth / 2, y: gap.centerY },
+      {
+        x: gap.rect.x + gap.rect.width - state.options.minWidth / 2,
+        y: gap.centerY
+      },
+      { x: gap.centerX, y: gap.rect.y + state.options.minHeight / 2 },
+      {
+        x: gap.centerX,
+        y: gap.rect.y + gap.rect.height - state.options.minHeight / 2
+      }
+    ];
+    for (const altSeed of seeds) {
+      const altRect = expandRectFromSeed({
+        startX: altSeed.x,
+        startY: altSeed.y,
+        gridSize: Math.min(gap.rect.width, gap.rect.height),
+        bounds: state.bounds,
+        blockers,
+        initialCellRatio: 0,
+        maxAspectRatio: null,
+        minReq: {
+          width: state.options.minWidth,
+          height: state.options.minHeight
+        }
+      });
+      if (altRect) {
+        return altRect;
+      }
+    }
+    return null;
+  }
+  return rect;
+}
+
+// lib/solvers/rectdiff/gapfill/engine/addPlacement.ts
+function addPlacement(state, {
+  rect,
+  zLayers
+}) {
+  const placed = { rect, zLayers: [...zLayers] };
+  state.placed.push(placed);
+  for (const z of zLayers) {
+    if (!state.placedByLayer[z]) {
+      state.placedByLayer[z] = [];
+    }
+    state.placedByLayer[z].push(rect);
+  }
+}
+
+// lib/solvers/rectdiff/gapfill/engine/stepGapFill.ts
+function stepGapFill(state) {
+  if (state.done) return false;
+  switch (state.stage) {
+    case "scan": {
+      if (state.gapsFound.length === 0 || state.gapIndex >= state.gapsFound.length) {
+        if (state.iteration >= state.options.maxIterations) {
+          state.done = true;
+          return false;
+        }
+        state.gapsFound = findAllGaps(
+          {
+            scanResolution: state.options.scanResolution,
+            minWidth: state.options.minWidth,
+            minHeight: state.options.minHeight
+          },
+          {
+            bounds: state.bounds,
+            layerCount: state.layerCount,
+            obstaclesByLayer: state.obstaclesByLayer,
+            placedByLayer: state.placedByLayer
+          }
+        );
+        if (state.iteration === 0) {
+          state.initialGapCount = state.gapsFound.length;
+        }
+        state.gapIndex = 0;
+        state.iteration++;
+        if (state.gapsFound.length === 0) {
+          state.done = true;
+          return false;
+        }
+      }
+      state.stage = "select";
+      return true;
+    }
+    case "select": {
+      if (state.gapIndex >= state.gapsFound.length) {
+        state.stage = "scan";
+        return true;
+      }
+      state.currentGap = state.gapsFound[state.gapIndex];
+      state.currentSeed = {
+        x: state.currentGap.centerX,
+        y: state.currentGap.centerY
+      };
+      state.expandedRect = null;
+      state.stage = "expand";
+      return true;
+    }
+    case "expand": {
+      if (!state.currentGap) {
+        state.stage = "select";
+        return true;
+      }
+      const expandedRect = tryExpandGap(state, {
+        gap: state.currentGap,
+        seed: state.currentSeed
+      });
+      state.expandedRect = expandedRect;
+      state.stage = "place";
+      return true;
+    }
+    case "place": {
+      if (state.expandedRect && state.currentGap) {
+        addPlacement(state, {
+          rect: state.expandedRect,
+          zLayers: state.currentGap.zLayers
+        });
+        state.filledCount++;
+      }
+      state.gapIndex++;
+      state.currentGap = null;
+      state.currentSeed = null;
+      state.expandedRect = null;
+      state.stage = "select";
+      return true;
+    }
+    default:
+      state.stage = "scan";
+      return true;
+  }
+}
+
+// lib/solvers/rectdiff/subsolvers/GapFillSubSolver.ts
+import { BaseSolver } from "@tscircuit/solver-utils";
+var GapFillSubSolver = class extends BaseSolver {
+  state;
+  layerCtx;
+  constructor(params) {
+    super();
+    this.layerCtx = params.layerCtx;
+    this.state = initGapFillState(
+      {
+        placed: params.placed,
+        options: params.options
+      },
+      params.layerCtx
+    );
+  }
+  /**
+   * Execute one step of the gap fill algorithm.
+   * Each gap goes through four stages: scan for gaps, select a target gap,
+   * expand a rectangle from seed point, then place the final result.
+   */
+  _step() {
+    const stillWorking = stepGapFill(this.state);
+    if (!stillWorking) {
+      this.solved = true;
+    }
+  }
+  /**
+   * Calculate progress as a value between 0 and 1.
+   * Accounts for iterations, gaps processed, and current stage within each gap.
+   */
+  computeProgress() {
+    return getGapFillProgress(this.state);
+  }
+  /**
+   * Get all placed rectangles including original ones plus newly created gap-fill rectangles.
+   */
+  getPlaced() {
+    return this.state.placed;
+  }
+  /**
+   * Get placed rectangles organized by Z-layer for efficient layer-based operations.
+   */
+  getPlacedByLayer() {
+    return this.state.placedByLayer;
+  }
+  getOutput() {
+    return {
+      placed: this.state.placed,
+      placedByLayer: this.state.placedByLayer,
+      filledCount: this.state.filledCount
+    };
+  }
+  /** Zen visualization: show four-stage gap filling process. */
+  visualize() {
+    const rects = [];
+    const points = [];
+    rects.push({
+      center: {
+        x: this.layerCtx.bounds.x + this.layerCtx.bounds.width / 2,
+        y: this.layerCtx.bounds.y + this.layerCtx.bounds.height / 2
+      },
+      width: this.layerCtx.bounds.width,
+      height: this.layerCtx.bounds.height,
+      fill: "none",
+      stroke: "#e5e7eb",
+      label: ""
+    });
+    switch (this.state.stage) {
+      case "scan": {
+        rects.push({
+          center: {
+            x: this.layerCtx.bounds.x + this.layerCtx.bounds.width / 2,
+            y: this.layerCtx.bounds.y + this.layerCtx.bounds.height / 2
+          },
+          width: this.layerCtx.bounds.width,
+          height: this.layerCtx.bounds.height,
+          fill: "#dbeafe",
+          stroke: "#3b82f6",
+          label: "scanning"
+        });
+        break;
+      }
+      case "select": {
+        if (this.state.currentGap) {
+          rects.push({
+            center: {
+              x: this.state.currentGap.rect.x + this.state.currentGap.rect.width / 2,
+              y: this.state.currentGap.rect.y + this.state.currentGap.rect.height / 2
+            },
+            width: this.state.currentGap.rect.width,
+            height: this.state.currentGap.rect.height,
+            fill: "#fecaca",
+            stroke: "#ef4444",
+            label: "target gap"
+          });
+          if (this.state.currentSeed) {
+            points.push({
+              x: this.state.currentSeed.x,
+              y: this.state.currentSeed.y,
+              color: "#dc2626",
+              label: "seed"
+            });
+          }
+        }
+        break;
+      }
+      case "expand": {
+        if (this.state.currentGap) {
+          rects.push({
+            center: {
+              x: this.state.currentGap.rect.x + this.state.currentGap.rect.width / 2,
+              y: this.state.currentGap.rect.y + this.state.currentGap.rect.height / 2
+            },
+            width: this.state.currentGap.rect.width,
+            height: this.state.currentGap.rect.height,
+            fill: "none",
+            stroke: "#f87171",
+            label: ""
+          });
+        }
+        if (this.state.currentSeed) {
+          points.push({
+            x: this.state.currentSeed.x,
+            y: this.state.currentSeed.y,
+            color: "#f59e0b",
+            label: "expanding"
+          });
+        }
+        if (this.state.expandedRect) {
+          rects.push({
+            center: {
+              x: this.state.expandedRect.x + this.state.expandedRect.width / 2,
+              y: this.state.expandedRect.y + this.state.expandedRect.height / 2
+            },
+            width: this.state.expandedRect.width,
+            height: this.state.expandedRect.height,
+            fill: "#fef3c7",
+            stroke: "#f59e0b",
+            label: "expanding"
+          });
+        }
+        break;
+      }
+      case "place": {
+        if (this.state.expandedRect) {
+          rects.push({
+            center: {
+              x: this.state.expandedRect.x + this.state.expandedRect.width / 2,
+              y: this.state.expandedRect.y + this.state.expandedRect.height / 2
+            },
+            width: this.state.expandedRect.width,
+            height: this.state.expandedRect.height,
+            fill: "#bbf7d0",
+            stroke: "#22c55e",
+            label: "placed"
+          });
+        }
+        break;
+      }
+    }
+    const stageNames = {
+      scan: "scanning",
+      select: "selecting",
+      expand: "expanding",
+      place: "placing"
+    };
+    return {
+      title: `GapFill (${stageNames[this.state.stage]}): ${this.state.filledCount} filled`,
+      coordinateSystem: "cartesian",
+      rects,
+      points
+    };
+  }
+};
+
 // lib/solvers/RectDiffSolver.ts
-var RectDiffSolver = class extends BaseSolver {
+var RectDiffSolver = class extends BaseSolver2 {
   srj;
-  mode;
   gridOptions;
+  gapFillOptions;
   state;
   _meshNodes = [];
   constructor(opts) {
     super();
     this.srj = opts.simpleRouteJson;
-    this.mode = opts.mode ?? "grid";
     this.gridOptions = opts.gridOptions ?? {};
+    this.gapFillOptions = opts.gapFillOptions ?? {};
+    this.activeSubSolver = null;
   }
   _setup() {
     this.state = initState(this.srj, this.gridOptions);
@@ -1006,12 +1664,44 @@ var RectDiffSolver = class extends BaseSolver {
       gridIndex: this.state.gridIndex
     };
   }
-  /** IMPORTANT: exactly ONE small step per call */
+  /** Exactly ONE small step per call. */
   _step() {
     if (this.state.phase === "GRID") {
       stepGrid(this.state);
     } else if (this.state.phase === "EXPANSION") {
       stepExpansion(this.state);
+    } else if (this.state.phase === "GAP_FILL") {
+      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) {
+        const output = this.activeSubSolver.getOutput();
+        this.state.placed = output.placed;
+        this.state.placedByLayer = output.placedByLayer;
+        this.activeSubSolver = null;
+        this.state.phase = "DONE";
+      }
     } else if (this.state.phase === "DONE") {
       if (!this.solved) {
         const rects = finalizeRects(this.state);
@@ -1023,44 +1713,81 @@ var RectDiffSolver = class 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;
+    }
   }
-  // Let BaseSolver update this.progress automatically if present.
+  /** Compute solver progress (0 to 1). */
   computeProgress() {
-    return computeProgress(this.state);
+    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;
   }
   getOutput() {
     return { meshNodes: this._meshNodes };
   }
-  // Helper to get color based on z layer
+  /** Get coverage percentage (0-1). */
+  getCoverage(sampleResolution = 0.05) {
+    return calculateCoverage(
+      { sampleResolution },
+      {
+        bounds: this.state.bounds,
+        layerCount: this.state.layerCount,
+        obstaclesByLayer: this.state.obstaclesByLayer,
+        placedByLayer: this.state.placedByLayer
+      }
+    );
+  }
+  /** Find uncovered points for debugging gaps. */
+  getUncoveredPoints(sampleResolution = 0.05) {
+    return findUncoveredPoints(
+      { sampleResolution },
+      {
+        bounds: this.state.bounds,
+        layerCount: this.state.layerCount,
+        obstaclesByLayer: this.state.obstaclesByLayer,
+        placedByLayer: this.state.placedByLayer
+      }
+    );
+  }
+  /** Get color based on z layer for visualization. */
   getColorForZLayer(zLayers) {
     const minZ = Math.min(...zLayers);
     const colors = [
       { fill: "#dbeafe", stroke: "#3b82f6" },
-      // blue (z=0)
       { fill: "#fef3c7", stroke: "#f59e0b" },
-      // amber (z=1)
       { fill: "#d1fae5", stroke: "#10b981" },
-      // green (z=2)
       { fill: "#e9d5ff", stroke: "#a855f7" },
-      // purple (z=3)
       { fill: "#fed7aa", stroke: "#f97316" },
-      // orange (z=4)
       { fill: "#fecaca", stroke: "#ef4444" }
-      // red (z=5)
     ];
     return colors[minZ % colors.length];
   }
-  // Streaming visualization: board + obstacles + current placements.
+  /** Streaming visualization: board + obstacles + current placements. */
   visualize() {
+    if (this.activeSubSolver) {
+      return this.activeSubSolver.visualize();
+    }
     const rects = [];
     const points = [];
+    const boardBounds = {
+      minX: this.srj.bounds.minX,
+      maxX: this.srj.bounds.maxX,
+      minY: this.srj.bounds.minY,
+      maxY: this.srj.bounds.maxY
+    };
     rects.push({
       center: {
-        x: (this.srj.bounds.minX + this.srj.bounds.maxX) / 2,
-        y: (this.srj.bounds.minY + this.srj.bounds.maxY) / 2
+        x: (boardBounds.minX + boardBounds.maxX) / 2,
+        y: (boardBounds.minY + boardBounds.maxY) / 2
       },
-      width: this.srj.bounds.maxX - this.srj.bounds.minX,
-      height: this.srj.bounds.maxY - this.srj.bounds.minY,
+      width: boardBounds.maxX - boardBounds.minX,
+      height: boardBounds.maxY - boardBounds.minY,
       fill: "none",
       stroke: "#111827",
       label: "board"
@@ -1107,7 +1834,7 @@ z:${p.zLayers.join(",")}`
       }
     }
     return {
-      title: "RectDiff (incremental)",
+      title: `RectDiff (${this.state?.phase ?? "init"})`,
       coordinateSystem: "cartesian",
       rects,
       points