@tscircuit/rectdiff 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -69,6 +69,12 @@ interface CapacityMeshNode {
     _parent?: CapacityMeshNode;
 }
 
+type XYRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 type GridFill3DOptions = {
     gridSizes?: number[];
     initialCellRatio?: number;
@@ -85,26 +91,129 @@ type GridFill3DOptions = {
     preferMultiLayer?: boolean;
     maxMultiLayerSpan?: number;
 };
+type Placed3D = {
+    rect: XYRect;
+    zLayers: number[];
+};
+
+interface GapFillOptions {
+    /** Minimum width for gap-fill rectangles (can be smaller than main solver) */
+    minWidth: number;
+    /** Minimum height for gap-fill rectangles */
+    minHeight: number;
+    /** Maximum iterations to prevent infinite loops */
+    maxIterations: number;
+    /** Target coverage percentage (0-1) to stop early */
+    targetCoverage: number;
+    /** Grid resolution for gap detection */
+    scanResolution: number;
+}
+/** Context for layer-based operations shared across gap fill functions */
+interface LayerContext {
+    bounds: XYRect;
+    layerCount: number;
+    obstaclesByLayer: XYRect[][];
+    placedByLayer: XYRect[][];
+}
+
+/**
+ * A sub-solver that fills empty spaces (gaps) left by the main grid-based
+ * placement algorithm.
+ *
+ * The preceding grid-based placement is fast but can leave irregular un-placed
+ * areas. This solver maximizes board coverage by finding and filling these
+ * gaps, which is critical for producing a high-quality capacity mesh.
+ *
+ * The core of the algorithm is its gap-detection phase. It works by first
+ * collecting all unique x and y-coordinates from the edges of existing
+ * obstacles and placed rectangles. This set of coordinates is supplemented by a
+ * uniform grid based on the `scanResolution` parameter. Together, these form a
+ * non-uniform grid of cells. The solver then tests the center of each cell for
+ * coverage. Contiguous uncovered cells are merged into larger, maximal
+ * rectangles, which become the candidate gaps to be filled.
+ *
+ * Once a prioritized list of gaps is generated (favoring larger, multi-layer
+ * gaps), the solver iteratively attempts to fill each one by expanding a new
+ * rectangle from a seed point until it collides with an existing boundary.
+ *
+ * The time complexity is dominated by the gap detection, which is approximately
+ * O((N+1/R)^2 * B), where N is the number of objects, R is the scan
+ * resolution, and B is the number of blockers. The algorithm's performance is
+ * therefore highly dependent on the `scanResolution`. It is a heuristic
+ * designed to be "fast enough" by avoiding a brute-force search, instead
+ * relying on this grid-based cell checking to find significant gaps.
+ */
+declare class GapFillSubSolver extends BaseSolver {
+    private state;
+    private layerCtx;
+    constructor(params: {
+        placed: Placed3D[];
+        options?: Partial<GapFillOptions>;
+        layerCtx: LayerContext;
+    });
+    /**
+     * 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(): void;
+    /**
+     * Calculate progress as a value between 0 and 1.
+     * Accounts for iterations, gaps processed, and current stage within each gap.
+     */
+    computeProgress(): number;
+    /**
+     * Get all placed rectangles including original ones plus newly created gap-fill rectangles.
+     */
+    getPlaced(): Placed3D[];
+    /**
+     * Get placed rectangles organized by Z-layer for efficient layer-based operations.
+     */
+    getPlacedByLayer(): XYRect[][];
+    getOutput(): {
+        placed: Placed3D[];
+        placedByLayer: XYRect[][];
+        filledCount: number;
+    };
+    /** Zen visualization: show four-stage gap filling process. */
+    visualize(): GraphicsObject;
+}
 
+/**
+ * A streaming, one-step-per-iteration solver for capacity mesh generation.
+ */
 declare class RectDiffSolver extends BaseSolver {
     private srj;
-    private mode;
     private gridOptions;
+    private gapFillOptions;
     private state;
     private _meshNodes;
+    /** Active subsolver for GAP_FILL phases. */
+    activeSubSolver: GapFillSubSolver | null;
     constructor(opts: {
         simpleRouteJson: SimpleRouteJson;
-        mode?: "grid" | "exact";
         gridOptions?: Partial<GridFill3DOptions>;
+        gapFillOptions?: Partial<GapFillOptions>;
     });
     _setup(): void;
-    /** IMPORTANT: exactly ONE small step per call */
+    /** Exactly ONE small step per call. */
     _step(): void;
+    /** Compute solver progress (0 to 1). */
     computeProgress(): number;
     getOutput(): {
         meshNodes: CapacityMeshNode[];
     };
+    /** Get coverage percentage (0-1). */
+    getCoverage(sampleResolution?: number): number;
+    /** Find uncovered points for debugging gaps. */
+    getUncoveredPoints(sampleResolution?: number): Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /** Get color based on z layer for visualization. */
     private getColorForZLayer;
+    /** Streaming visualization: board + obstacles + current placements. */
     visualize(): GraphicsObject;
 }