Fix core geometry snapping, A* target lookahead, and test configurations

docs/plans/package_structure.md

@@ -0,0 +1,57 @@
+# Python Package Structure
+
+This document outlines the directory structure and module organization for the `inire` auto-router package.
+
+## 1. Directory Layout
+
+```
+inire/
+├── __init__.py             # Exposes the main `Router` class and key types
+├── geometry/               # Core geometric primitives and operations
+│   ├── __init__.py
+│   ├── primitives.py       # Point, Port, Polygon, Arc classes
+│   ├── collision.py        # R-Tree wrapper and intersection logic
+│   └── components.py       # Move generators (Straight, Bend90, SBend)
+├── router/                 # Search algorithms and pathfinding
+│   ├── __init__.py
+│   ├── astar.py            # Hybrid State-Lattice A* implementation
+│   ├── graph.py            # Node, Edge, and Graph data structures
+│   ├── cost.py             # Cost functions (length, bend, proximity)
+│   ├── danger_map.py       # Pre-computed grid for heuristic proximity costs
+│   └── pathfinder.py       # Multi-net "Negotiated Congestion" manager
+├── utils/                  # Utility functions
+│   ├── __init__.py
+│   └── visualization.py    # Plotting tools for debug/heatmaps (matplotlib/klayout)
+└── tests/                  # Unit and integration tests
+    ├── __init__.py
+    ├── conftest.py         # Pytest fixtures (common shapes, PDK cells)
+    ├── test_primitives.py  # Tests for Port and coordinate transforms
+    ├── test_components.py  # Tests for Straight, Bend90, SBend generation
+    ├── test_collision.py   # Tests for R-Tree and dilation logic
+    ├── test_cost.py        # Tests for Danger Map and cost evaluation
+    ├── test_astar.py       # Tests for single-net routing (mazes, snapping)
+    └── test_pathfinder.py  # Multi-net "Negotiated Congestion" benchmarks
+```
+
+## 2. Module Responsibilities
+
+### `inire.geometry`
+*   **`primitives.py`**: Defines the `Port` named tuple `(x, y, theta)` and helper functions for coordinate transforms.
+*   **`collision.py`**: Wraps the `rtree` or `shapely` library. Handles the "Analytic Correctness" checks (exact polygon distance).
+*   **`components.py`**: Logic to generate "Moves" from a start port. E.g., `SBend.generate(start_port, offset, radius)` returns a list of polygons and the end port. Handles $O > 2R$ logic.
+
+### `inire.router`
+*   **`astar.py`**: The heavy lifter. Maintains the `OpenSet` (priority queue) and `ClosedSet`. Implements the "Snap-to-Target" logic.
+*   **`cost.py`**: compute $f(n) = g(n) + h(n)$. encapsulates the "Danger Map" and Path R-Tree lookups.
+*   **`danger_map.py`**: Manages the pre-computed proximity grid used for $O(1)$ heuristic calculations.
+*   **`pathfinder.py`**: Orchestrates the multi-net loop. Tracks the Path R-Tree for negotiated congestion and triggers reroutes.
+
+### `inire.tests`
+*   **Structure:** Tests are co-located within the package for ease of access.
+*   **Fixtures:** `conftest.py` will provide standard PDK cells (e.g., a $10\mu m$ radius bend) to avoid repetition in test cases.
+
+## 3. Dependencies
+*   `numpy`: Vector math.
+*   `shapely`: Polygon geometry and intersection.
+*   `rtree`: Spatial indexing.
+*   `networkx` (Optional): Not used for core search to ensure performance.