--orders: route several connection orders in parallel, keep the best

The default order is always one of the candidates, so the result is
never worse than a plain run; ties go to the earlier candidate.

.gitignore

@@ -20,3 +20,7 @@ htmlcov/
 # Editor / OS
 .DS_Store
 *.swp
+
+# Benchmark inputs and results: board lists name local, often private, designs
+/bench/boards*.txt
+/bench/results/

README.md

@@ -1,6 +1,6 @@
 # freeroute
 
-A native Python PCB autorouter — a Java-free reimplementation of the
+A native Python PCB autorouter: a Java-free reimplementation of the
 [FreeRouting](https://github.com/freerouting/freerouting) engine. Specctra DSN
 in, Specctra SES out, no JVM anywhere in the pipeline.
 
@@ -8,8 +8,8 @@ in, Specctra SES out, no JVM anywhere in the pipeline.
 
 Toolchains that autoroute (`kicad-mcp` among them) do it by shelling out to
 `freerouting.jar`, which drags a JVM into every install and container image.
-`freeroute` reimplements the routing engine in pure Python — no dependencies at
-all, standard library only — so the JAR step becomes a `pip install`.
+`freeroute` reimplements the routing engine in pure Python, with no dependencies
+beyond the standard library, so the JAR step becomes a `pip install`.
 
 ## The contract
 
@@ -21,7 +21,7 @@ board.dsn  ──▶  freeroute  ──▶  board.ses
 ```
 
 `kicad-cli` already exports `.dsn` and imports `.ses`, so `freeroute` drops in
-wherever `java -jar freerouting.jar` was invoked — nothing else in the pipeline
+wherever `java -jar freerouting.jar` was invoked, and nothing else in the pipeline
 changes. The `-de` / `-do` / `-mp` flags are the JAR's, on purpose.
 
 ## Install
@@ -33,27 +33,31 @@ uv tool install freeroute      # or: pipx install freeroute
 ## Usage
 
 ```bash
-freeroute board.dsn -o board.ses          # grid engine, the default
-freeroute -de board.dsn -do board.ses     # the FreeRouting JAR spelling
+# a KiCad board: the exact engine, with the board's copper-to-edge rule
+freeroute board.dsn --engine exact --shove --edge-clearance 0.5 -do board.ses
 
+freeroute -de board.dsn -do board.ses     # the FreeRouting JAR spelling (grid engine)
 freeroute board.dsn --engine room --pack --shove -do board.ses
-freeroute board.dsn --engine exact --diagonal --shove -do board.ses
 ```
 
-With no `-do` / `-o`, the SES goes to stdout.
+With no `-do` / `-o`, the SES goes to stdout. Connections freeroute could not
+make are listed on stderr; the SES is still written and the exit code stays 0,
+as with the JAR. Connections whose two ends sit in one zone of their net are
+listed separately, as left to that zone's fill.
 
 ### Engines
 
 Three routing tracks, selected with `--engine`:
 
-- **`grid`** (default) — multi-layer maze router over a uniform occupancy grid,
-  with rip-up-and-retry and via search. Highest raw connectivity of the three;
-  its geometry is grid-quantised, so it is the least precise about clearance.
-- **`exact`** — orthogonal router whose output is verified against exact integer
-  geometry (tile/octagon clearance, not bounding boxes). Cleaner, DRC-clean
-  output where it succeeds; it will drop a net rather than emit a violation.
-- **`room`** — continuous expansion-room router: an exact decomposition of free
-  space, so it routes off-grid channels that the grid quantisation cannot see.
+- **`exact`** (recommended for real boards): orthogonal grid search whose every
+  accepted connection is verified against exact integer geometry. It drops a
+  connection rather than emit a violation. Defaults to `--grid-resolution 2`.
+- **`grid`** (the default, for JAR-compatible invocation): the same multi-layer
+  maze router with rip-up and via search, without the exact check, so its
+  geometry is only as precise as the grid.
+- **`room`**: continuous expansion-room router, an exact decomposition of free
+  space. It routes off-grid channels the grid cannot see, but it is much slower
+  on real boards and does not yet use zones.
 
 ### Flags
 
@@ -62,6 +66,9 @@ Three routing tracks, selected with `--engine`:
 | `--engine {grid,exact,room}` | routing track (default: `grid`) |
 | `-de`, `--design` | input `.dsn` (FreeRouting-compatible alias) |
 | `-do`, `--output` | output `.ses` (default: stdout) |
+| `--edge-clearance MM` | copper to board-edge clearance, e.g. KiCad's `min_copper_edge_clearance`, which the DSN does not carry (default 0: copper only has to stay inside the outline) |
+| `--grid-resolution K` | grid cells K times finer than trace + clearance (default 2 for exact, 1 for grid); finer reaches fine-pitch pins at a cost in time |
+| `--heuristic-weight W` | exact: weighted A*, routes at most W times the shortest (default 1) |
 | `-mp`, `--max-passes` | rip-up-and-retry pass bound (default 10) |
 | `--no-rip-up` | single greedy pass, no rip-up |
 | `--layers` | comma-separated signal layer indices to route on |
@@ -74,65 +81,90 @@ unsupported combination is a hard error (exit 2) rather than a silent no-op:
 
 | | `--pack` | `--shove` | `--diagonal` | `--no-rip-up` | `-mp` |
 |---|---|---|---|---|---|
-| **grid** | — | — | — | yes | yes |
-| **exact** | — | yes | yes | yes | yes |
-| **room** | yes | yes | — | — | — |
+| **grid** | no | no | no | yes | yes |
+| **exact** | no | yes | yes | yes | yes |
+| **room** | yes | yes | no | no | no |
 
-`--layers` works on all three.
+`--layers` and `--edge-clearance` work on all three; `--grid-resolution` on grid
+and exact.
 
 What the opt-in passes buy you:
 
-- **`--pack`** (room) — when several 2-pin nets have to cross the same obstacle
-  gap, they are assigned consistent parallel lanes and routed together, so a
-  channel physically wide enough for all of them stops dropping nets to greedy
-  per-net gate collisions.
-- **`--shove`** (exact, room) — a net that would be dropped nudges the blocking
+- **`--pack`** (room): when several 2-pin nets have to cross the same obstacle
+  gap, they are assigned consistent parallel lanes and routed together.
+- **`--shove`** (exact, room): a net that would be dropped nudges the blocking
   committed traces aside and re-routes, rolling every moved trace back if the
-  retry fails. On the room engine it also turns on occupancy-aware gate
-  placement. It recovers *ordering* drops; it cannot manufacture space that is
-  not there.
-- **`--diagonal`** (exact) — a still-dropped 2-pin net is retried as a 45° trace
-  whose diagonal copper is covered by an exact integer octagon, so it fits
-  corridors the orthogonal L cannot, at the ideal hypotenuse length.
+  retry fails. It recovers *ordering* drops; it cannot make space that is not
+  there.
+- **`--diagonal`** (exact): a still-dropped 2-pin net is retried as a 45° trace
+  covered by an exact integer octagon.
+
+## What freeroute reads from a KiCad DSN
+
+These were each checked against KiCad itself, pad by pad or with its DRC:
+
+- **Pads** placed as KiCad places them: back-side parts on the mirrored copper
+  layer, outlines rotated with the part, oval pads at their full width, the
+  largest shape of a multi-layer padstack.
+- **Vias** at the size of the DSN's via padstack.
+- **Keepouts**: `keepout` blocks tracks and vias, `wire_keepout` (KiCad's "no
+  tracks" rule area) tracks only, `via_keepout` vias only; a rule area with a
+  hole (a no-track ring along the edge) is split into convex pieces rather than
+  filled in; footprint-level keepouts (a mounting hole's plated ring) are placed
+  with their part; `place_keepout` does not affect routing.
+- **The real board outline**, rounded corners included, with `--edge-clearance`.
+- **Copper zones** (`plane`): a pad inside a zone connects through it, and a
+  route can end on it with a via. A zone is only counted on to connect when a
+  no-tracks rule area covers it; a board-wide pour can be split into islands by
+  other nets' tracks, so its pads are routed with tracks instead.
+- **Fine-pitch pins**: a finer grid, and exact escape stubs for pins the grid
+  cannot reach.
+
+SES coordinates are written in resolution units, exactly as the JAR writes them.
 
 ## Library use
 
 ```python
 from freeroute.route import route
 
-ses_text = route(dsn_text, engine="room", shove=True, pack=True)
+ses_text = route(dsn_text, engine="exact", shove=True, edge_clearance_mm=0.5)
 ```
 
 ## Status and honest scope
 
-Alpha, version 0.1.0. It parses real `kicad-cli` DSN output, routes, and writes
-SES that KiCad imports. What is actually implemented:
+Alpha. Measured on two real KiCad 10 boards (the TerraHawk charge node's power
+stage and sense board, 2026-09-27), with every track stripped, then routed, then
+checked with `kicad-cli pcb drc --refill-zones`:
 
-- Specctra DSN parser (structure, library, placement, network, rules, keepouts)
-  and SES writer.
-- Multi-layer routing with via search and rip-up-and-retry.
-- Exact integer geometry (tiles, octagons) with a spatial index, so the `exact`
-  and `room` engines verify their own output is clearance-clean.
-- Continuous expansion-room free-space decomposition.
-- Channel packing, shove, and 45° routing as described above.
+| board | freeroute exact | FreeRouting JAR | DRC errors from freeroute |
+|---|---|---|---|
+| power stage (40 x 30 mm) | 7 unconnected, ~5 s | 12 | 0 |
+| sense board (55 x 25 mm, 0.5 mm pitch MCU) | 41 unconnected, ~2.5 min | 32 | 0 |
+
+In the board owner's production flow (hand-routed power lanes kept, pours added
+after routing), freeroute completed the power stage with no unconnected items.
 
 What it is **not**, stated plainly:
 
-- **Not at FreeRouting/JAR density parity on dense commercial boards.** The JAR
-  remains the better router when the board is hard. `freeroute` is honest about
-  drops: it leaves a net unrouted rather than emit a DRC violation, so on a
-  crowded board expect fewer completed nets than the JAR would manage.
-- **`--diagonal` is a shortening/recovery pass, not diagonal-native search.**
-  The maze search is orthogonal; 45° geometry is applied to nets the orthogonal
-  pass dropped or to shorten a staircase. A true 45°-native expansion-room maze
-  is not implemented.
-- No fanout pass, no post-route optimiser, no interactive/incremental routing,
-  no net classes with per-class widths beyond the default rules, no plane/pour
-  handling.
+- **Not yet at JAR completion on a dense board.** The legality of what it routes
+  holds up; how much it routes does not match the JAR yet. The remaining gap is
+  congestion: routes committed one at a time block later ones. The JAR's
+  negotiated rip-up loop handles that better. Negotiated congestion routing is
+  the planned next step.
+- **Slower than the JAR** on a dense board (minutes against seconds), being
+  pure Python.
+- **`--diagonal` is a recovery pass, not diagonal-native search.**
+- The `room` engine does not use zones, the outline edge rule is only enforced
+  approximately there, and it is slow on real boards.
+- No fanout pass, no post-route optimiser, no incremental routing, no per-class
+  track widths beyond the default rules.
+- Copper that KiCad draws as graphics (a net tie's polygon, a logo) is not in
+  the DSN at all, so no router sees it; mckicad adds footprint copper to the DSN
+  as keepouts.
 
-If you need maximum completion on a dense board today, use the JAR. If you need
-routing without a JVM — CI, containers, an MCP server, a library call — this is
-that.
+For maximum completion on a dense board today, the JAR is still the stronger
+router. For routing without a JVM (CI, containers, an MCP server, a library
+call), freeroute routes legally and says what it could not do.
 
 ## Development
 
@@ -144,7 +176,7 @@ uv run ruff check src/ tests/
 
 The `oracle`-marked tests run the real `freerouting.jar` as a differential
 reference and skip cleanly when Java or the JAR is absent. The JAR is never
-vendored, and neither is the upstream Java source — see
+vendored, and neither is the upstream Java source; see
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the port map and
 [`docs/PORTING_PLAN.md`](docs/PORTING_PLAN.md) for the roadmap.
 

bench/bench.py

@@ -0,0 +1,206 @@
+"""Route boards under several connection orders and compare variants fairly.
+
+One routing run says little: which connection routes first moves a result by
+ten connections either way on a crowded board. This runs every board with
+every variant under the same seeds (``--seed``), so variant A and variant B
+face the same order on seed 3, and compares them seed by seed.
+
+    uv run python bench/bench.py BOARDS -v base= -v hist1="--history-cost 1" \\
+        --seeds 6 --jobs 4 --out bench/results/hist.jsonl
+
+BOARDS is a text file, one board per line: a name, a DSN path and any flags
+that board always needs, e.g.
+
+    sense  /path/to/charge-sense.dsn  --edge-clearance 0.5
+    # comments and blank lines are ignored
+
+A variant is ``NAME=FLAGS``, or ``NAME@SRC=FLAGS`` to run the code under SRC
+(a worktree's ``src`` directory) rather than the installed package. The first
+variant is the baseline. Results are appended to --out as JSON lines, and runs
+already in it are skipped, so an interrupted benchmark picks up where it left
+off. Exits non-zero if any run crashed or timed out.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+NOT_ROUTED = re.compile(r"freeroute: (\d+) connection\(s\) not routed")
+TO_ZONE = re.compile(r"freeroute: (\d+) more connection\(s\) left to a zone fill")
+
+
+def parse_boards(path: Path) -> list[tuple[str, Path, list[str]]]:
+    boards = []
+    for line in path.read_text().splitlines():
+        words = shlex.split(line, comments=True)
+        if not words:
+            continue
+        if len(words) < 2:
+            raise SystemExit(f"{path}: want 'name path [flags]', got {line!r}")
+        dsn = Path(words[1]).expanduser()
+        if not dsn.is_file():
+            raise SystemExit(f"{path}: no such DSN {dsn}")
+        boards.append((words[0], dsn, words[2:]))
+    return boards
+
+
+def parse_variant(spec: str) -> tuple[str, str | None, list[str]]:
+    head, sep, flags = spec.partition("=")
+    if not sep or not head:
+        raise SystemExit(f"variant {spec!r}: want NAME=FLAGS or NAME@SRC=FLAGS")
+    name, _, src = head.partition("@")
+    if src and not (Path(src) / "freeroute").is_dir():
+        raise SystemExit(f"variant {name}: {src} has no freeroute package")
+    return name, src or None, shlex.split(flags)
+
+
+def run_one(board, variant, seed: int, timeout: float) -> dict:
+    name, dsn, board_flags = board
+    vname, src, flags = variant
+    env = dict(os.environ)
+    if src:
+        env["PYTHONPATH"] = src + os.pathsep + env.get("PYTHONPATH", "")
+    with tempfile.TemporaryDirectory() as tmp:
+        cmd = [
+            sys.executable, "-m", "freeroute.cli", str(dsn), "-do", f"{tmp}/out.ses",
+            *board_flags, *flags, "--seed", str(seed),
+        ]
+        start = time.monotonic()
+        proc = subprocess.Popen(
+            cmd, env=env, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True
+        )
+        expired = threading.Event()
+
+        def expire() -> None:
+            expired.set()
+            proc.kill()
+
+        timer = threading.Timer(timeout, expire)
+        timer.start()
+        err = proc.stderr.read()
+        # reap it here rather than through Popen, to keep its peak memory
+        _, wstatus, usage = os.wait4(proc.pid, 0)
+        timer.cancel()
+        proc.returncode = os.waitstatus_to_exitcode(wstatus)
+        proc.stderr.close()
+        status = "timeout" if expired.is_set() else (
+            "ok" if proc.returncode == 0 else f"exit {proc.returncode}"
+        )
+        rss_mb = round(usage.ru_maxrss / 1024)
+        secs = round(time.monotonic() - start, 1)
+    missing = NOT_ROUTED.search(err)
+    zone = TO_ZONE.search(err)
+    return {
+        "board": name, "variant": vname, "seed": seed, "status": status,
+        "unrouted": int(missing.group(1)) if missing else 0,
+        "to_zone": int(zone.group(1)) if zone else 0,
+        "secs": secs, "rss_mb": rss_mb,
+        "tail": err.strip().splitlines()[-1] if status != "ok" and err.strip() else "",
+    }
+
+
+def mean_sd(xs: list[float]) -> tuple[float, float]:
+    m = sum(xs) / len(xs)
+    sd = math.sqrt(sum((x - m) ** 2 for x in xs) / (len(xs) - 1)) if len(xs) > 1 else 0.0
+    return m, sd
+
+
+def report(rows: list[dict], boards, variants) -> None:
+    ok = {(r["board"], r["variant"], r["seed"]): r for r in rows if r["status"] == "ok"}
+    base = variants[0][0]
+    print(f"\nunrouted per board (lower is better), baseline {base!r}\n")
+    print(f"{'board':14} {'variant':14} {'n':>3} {'mean':>6} {'sd':>5} {'min':>4} {'max':>4}"
+          f" {'secs':>6}   vs baseline, seed by seed")
+    for bname, _, _ in boards:
+        for vname, _, _ in variants:
+            runs = sorted((k[2], r) for k, r in ok.items() if k[:2] == (bname, vname))
+            if not runs:
+                print(f"{bname:14} {vname:14}   no finished runs")
+                continue
+            xs = [r["unrouted"] for _, r in runs]
+            m, sd = mean_sd(xs)
+            t, _ = mean_sd([r["secs"] for _, r in runs])
+            line = (f"{bname:14} {vname:14} {len(xs):>3} {m:>6.1f} {sd:>5.1f} {min(xs):>4}"
+                    f" {max(xs):>4} {t:>6.0f}")
+            if vname != base:
+                diffs = [r["unrouted"] - ok[(bname, base, s)]["unrouted"]
+                         for s, r in runs if (bname, base, s) in ok]
+                if diffs:
+                    dm, dsd = mean_sd(diffs)
+                    se = dsd / math.sqrt(len(diffs)) if len(diffs) > 1 else float("inf")
+                    better = sum(d < 0 for d in diffs)
+                    worse = sum(d > 0 for d in diffs)
+                    # a difference inside two standard errors is not a finding
+                    verdict = ("better" if dm < 0 else "worse") if abs(dm) > 2 * se else "no clear change"
+                    line += (f"   {dm:+.1f} ± {se:.1f}  ({better} better, {worse} worse,"
+                             f" {len(diffs) - better - worse} same)  {verdict}")
+            print(line)
+    failed = [r for r in rows if r["status"] != "ok"]
+    for r in failed:
+        print(f"FAILED {r['board']} {r['variant']} seed {r['seed']}: {r['status']} {r['tail']}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("boards", type=Path, help="board list: name, DSN path, flags")
+    ap.add_argument("-v", "--variant", action="append", required=True,
+                    help="NAME=FLAGS or NAME@SRC=FLAGS; the first is the baseline")
+    ap.add_argument("--seeds", type=int, default=6, help="orders per board and variant")
+    ap.add_argument("--first-seed", type=int, default=0)
+    ap.add_argument("--jobs", type=int, default=4, help="runs at once")
+    ap.add_argument("--timeout", type=float, default=1800, help="seconds per run")
+    ap.add_argument("--out", type=Path, required=True, help="JSON lines, appended")
+    ap.add_argument("--report-only", action="store_true", help="summarise --out, run nothing")
+    args = ap.parse_args(argv)
+
+    boards = parse_boards(args.boards)
+    variants = [parse_variant(v) for v in args.variant]
+    if len({v[0] for v in variants}) != len(variants):
+        raise SystemExit("variant names must differ")
+    seeds = range(args.first_seed, args.first_seed + args.seeds)
+
+    rows: list[dict] = []
+    if args.out.exists():
+        rows = [json.loads(line) for line in args.out.read_text().splitlines() if line.strip()]
+    done = {(r["board"], r["variant"], r["seed"]) for r in rows if r["status"] == "ok"}
+    todo = [(b, v, s) for b in boards for v in variants for s in seeds
+            if (b[0], v[0], s) not in done]
+
+    if not args.report_only and todo:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        print(f"{len(todo)} runs, {args.jobs} at a time", file=sys.stderr)
+        # retried runs replace their earlier failure
+        rows = [r for r in rows if (r["board"], r["variant"], r["seed"]) in done]
+        with ThreadPoolExecutor(args.jobs) as pool, args.out.open("w") as out:
+            for r in rows:
+                out.write(json.dumps(r) + "\n")
+            futures = [pool.submit(run_one, b, v, s, args.timeout) for b, v, s in todo]
+            for n, fut in enumerate(as_completed(futures), 1):
+                r = fut.result()
+                rows.append(r)
+                out.write(json.dumps(r) + "\n")
+                out.flush()
+                print(f"[{n}/{len(todo)}] {r['board']} {r['variant']} seed {r['seed']}:"
+                      f" {r['status']} unrouted {r['unrouted']} ({r['secs']}s,"
+                      f" {r['rss_mb']} MB)", file=sys.stderr)
+
+    wanted = {(b[0], v[0], s) for b in boards for v in variants for s in seeds}
+    rows = [r for r in rows if (r["board"], r["variant"], r["seed"]) in wanted]
+    report(rows, boards, variants)
+    return 1 if any(r["status"] != "ok" for r in rows) or len(rows) < len(wanted) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/freeroute/board/board.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 from freeroute.geometry import IntBox
 
 from .clearance import ClearanceMatrix
-from .items import Item, ObstacleArea, Pin, Trace, Via
+from .items import ConductionArea, Item, ObstacleArea, Pin, Trace, Via
 from .layer import LayerStructure
 from .net import Nets
 
@@ -22,7 +22,7 @@ __all__ = ["BasicBoard"]
 class BasicBoard:
     """A board: layers, nets, clearances, a bounding box, and items."""
 
-    __slots__ = ("layer_structure", "nets", "clearance_matrix", "bounding_box", "_items")
+    __slots__ = ("layer_structure", "nets", "clearance_matrix", "bounding_box", "outline", "_items")
 
     def __init__(
         self,
@@ -35,6 +35,8 @@ class BasicBoard:
         self.nets = nets
         self.clearance_matrix = clearance_matrix
         self.bounding_box = bounding_box
+        #: the real board outline, when the DSN has a polygon boundary
+        self.outline = None
         self._items: list[Item] = []
 
     # --- layers -------------------------------------------------------------
@@ -55,7 +57,15 @@ class BasicBoard:
         return [it for it in self._items if isinstance(it, Pin)]
 
     def get_obstacle_areas(self) -> list[ObstacleArea]:
-        return [it for it in self._items if isinstance(it, ObstacleArea)]
+        """Keepouts. Copper zones are not obstacles; see get_conduction_areas."""
+        return [
+            it
+            for it in self._items
+            if isinstance(it, ObstacleArea) and not isinstance(it, ConductionArea)
+        ]
+
+    def get_conduction_areas(self) -> list[ConductionArea]:
+        return [it for it in self._items if isinstance(it, ConductionArea)]
 
     def get_traces(self) -> list[Trace]:
         return [it for it in self._items if isinstance(it, Trace)]

src/freeroute/board/build.py

@@ -27,10 +27,11 @@ import math
 from freeroute.dsn.model import DsnBoard
 from freeroute.dsn.shapes import Circle, Path, Polygon, Rectangle, Shape
 from freeroute.geometry import FloatPoint, IntBox, IntPoint, IntVector, Simplex
+from freeroute.geometry.polygon_shape import PolygonShape
 
 from .board import BasicBoard
 from .clearance import ClearanceMatrix
-from .items import ObstacleArea, Pin
+from .items import ConductionArea, ObstacleArea, Pin
 from .layer import Layer, LayerStructure
 from .net import Nets
 from .transform import CoordinateTransform
@@ -49,9 +50,12 @@ def build_board(dsn: DsnBoard) -> BasicBoard:
     bounding_box = _build_bounding_box(dsn, transform)
 
     board = BasicBoard(layer_structure, nets, clearance, bounding_box)
+    board.outline = _build_outline(dsn, transform)
 
     _insert_pins(dsn, board, transform, terminal_to_net)
     _insert_keepouts(dsn, board, transform)
+    _insert_image_keepouts(dsn, board, transform)
+    _insert_zones(dsn, board, transform, nets)
     return board
 
 
@@ -97,6 +101,18 @@ def _build_bounding_box(dsn: DsnBoard, transform: CoordinateTransform) -> IntBox
     return IntBox(llx, lly, urx, ury)
 
 
+def _build_outline(dsn: DsnBoard, transform: CoordinateTransform):
+    """The DSN boundary as a polygon, or None when it is not a polygon."""
+    from .outline import BoardOutline
+
+    shape = dsn.boundary
+    if not isinstance(shape, (Polygon, Path)):
+        return None
+    c = shape.coords
+    pts = [transform.dsn_to_board_point(c[i], c[i + 1]) for i in range(0, len(c) - 1, 2)]
+    return BoardOutline(pts) if len(pts) >= 3 else None
+
+
 def _shape_coords(shape: Shape) -> list[float]:
     if isinstance(shape, Rectangle):
         return list(shape.coords)
@@ -132,7 +148,7 @@ def _insert_pins(
                 location = _pin_location(place, dsn_pin, transform)
                 padstack = dsn.padstack(dsn_pin.padstack_name)
                 shape, layers = _pad_shape_and_layers(
-                    padstack, location, transform, layer_no, signal_layers
+                    padstack, place, dsn_pin, location, transform, layer_no, signal_layers
                 )
                 net_no = terminal_to_net.get((place.name, dsn_pin.name))
                 pin = Pin(
@@ -140,6 +156,7 @@ def _insert_pins(
                     component_no=id(place) & 0xFFFFFF,
                     fixed=True,
                     name=dsn_pin.name,
+                    component_ref=place.name,
                     padstack_name=dsn_pin.padstack_name,
                     location=location,
                     layers=layers,
@@ -148,22 +165,44 @@ def _insert_pins(
                 board.insert(pin)
 
 
+def _to_board_offset(place, x: float, y: float, pin_rotation: float = 0.0) -> FloatPoint:
+    """Image-relative DSN offset -> board-oriented DSN offset for a placed part.
+
+    The chain is: the pin's own rotation (pad shapes only), then the mirror of
+    a back-side part (x -> -x), then the part's rotation. Pin positions use the
+    same chain without the pin rotation, so pads and positions always agree.
+    """
+    p = FloatPoint(x, y)
+    if pin_rotation:
+        p = p.rotate(math.radians(pin_rotation), FloatPoint(0.0, 0.0))
+    if not place.is_front:
+        p = FloatPoint(-p.x, p.y)
+    if place.rotation:
+        p = p.rotate(math.radians(place.rotation), FloatPoint(0.0, 0.0))
+    return p
+
+
 def _pin_location(place, dsn_pin, transform: CoordinateTransform) -> IntPoint:
-    """Absolute board location of a pin: component origin + rotated pin offset."""
-    rel_x = -dsn_pin.x if not place.is_front else dsn_pin.x  # back side mirrors in x
-    rel = FloatPoint(rel_x, dsn_pin.y)
-    rotated = rel.rotate(math.radians(place.rotation), FloatPoint(0.0, 0.0))
-    return transform.dsn_to_board_point(place.x + rotated.x, place.y + rotated.y)
+    """Absolute board location of a pin: component origin + placed pin offset."""
+    rel = _to_board_offset(place, dsn_pin.x, dsn_pin.y)
+    return transform.dsn_to_board_point(place.x + rel.x, place.y + rel.y)
 
 
 def _pad_shape_and_layers(
     padstack,
+    place,
+    dsn_pin,
     location: IntPoint,
     transform: CoordinateTransform,
     layer_no: dict[str, int],
     signal_layers: list[int],
 ) -> tuple[object, list[int]]:
-    """A pad tile centred on ``location`` plus the layer indices it occupies."""
+    """A pad tile around ``location`` plus the layer indices it occupies.
+
+    A back-side part's pads move to the mirrored copper layer (F.Cu -> B.Cu on
+    a two-layer board), and the pad outline is placed through the same
+    rotation and mirror as the pin itself.
+    """
     if padstack is None or not padstack.shapes:
         # degenerate: a zero-size box at the location (still contains it)
         return IntBox(location.x, location.y, location.x, location.y), list(signal_layers)
@@ -176,12 +215,63 @@ def _pad_shape_and_layers(
             layers.add(layer_no[shape.layer])
     if not layers:
         layers = set(signal_layers)
+    if not place.is_front and signal_layers:
+        top, bottom = min(signal_layers), max(signal_layers)
+        layers = {top + bottom - layer if layer in signal_layers else layer for layer in layers}
 
-    tile = _pad_tile(padstack.shapes[0], transform)
+    # The largest of the padstack's shapes: per-layer shapes of a through-hole
+    # pad usually match, and when they do not the bigger one is the safe side.
+    shape = max(padstack.shapes, key=_shape_extent)
+    tile = _placed_pad_tile(shape, place, dsn_pin, transform)
     tile = tile.translate_by(IntVector(location.x, location.y))
     return tile, sorted(layers)
 
 
+def _shape_extent(shape: Shape) -> float:
+    coords = _shape_coords(shape)
+    if isinstance(shape, Circle):
+        return shape.diameter ** 2
+    if len(coords) < 4:
+        return 0.0
+    xs, ys = coords[0::2], coords[1::2]
+    return (max(xs) - min(xs)) * (max(ys) - min(ys))
+
+
+def _placed_pad_tile(shape: Shape, place, dsn_pin, transform: CoordinateTransform):
+    """The pad outline, rotated and mirrored with its part, relative to the pin."""
+    if isinstance(shape, Circle):
+        centre = _to_board_offset(place, shape.center_x, shape.center_y, dsn_pin.rotation)
+        r = round(transform.dsn_to_board(shape.diameter / 2))
+        cx = round(transform.dsn_to_board(centre.x))
+        cy = round(transform.dsn_to_board(centre.y))
+        return IntBox(cx - r, cy - r, cx + r, cy + r)
+    if isinstance(shape, Rectangle):
+        x0, y0, x1, y1 = shape.coords[:4]
+        corners = [(x0, y0), (x1, y0), (x1, y1), (x0, y1)]
+    elif isinstance(shape, (Polygon, Path)):
+        c = shape.coords
+        corners = [(c[i], c[i + 1]) for i in range(0, len(c) - 1, 2)]
+    else:
+        return _pad_tile(shape, transform)
+    # An oval pad is a path with a width (the aperture). Pad the centreline
+    # out by half the width in every direction; the square ends cover more
+    # than the round ones do, which is the safe side.
+    half = getattr(shape, "width", 0.0) / 2 if isinstance(shape, Path) else 0.0
+    if half:
+        corners = [(x + dx, y + dy) for x, y in corners for dx in (-half, half) for dy in (-half, half)]
+    pts = []
+    for x, y in corners:
+        p = _to_board_offset(place, x, y, dsn_pin.rotation)
+        pts.append(IntPoint(round(transform.dsn_to_board(p.x)), round(transform.dsn_to_board(p.y))))
+    if len(pts) >= 3:
+        simplex = Simplex.from_corners(pts)
+        if not simplex.is_empty():
+            return simplex
+    xs = [p.x for p in pts] or [0]
+    ys = [p.y for p in pts] or [0]
+    return IntBox(min(xs), min(ys), max(xs), max(ys))
+
+
 def _pad_tile(shape: Shape, transform: CoordinateTransform):
     """A board-relative pad tile from a DSN padstack shape (centred near origin)."""
     if isinstance(shape, Rectangle):
@@ -219,11 +309,14 @@ def _insert_keepouts(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTran
     signal_layers = [i for i, layer in enumerate(dsn.layers) if layer.is_signal]
 
     for keepout in dsn.keepouts:
+        # A place_keepout only restricts where parts go, not copper.
+        if keepout.kind == "place_keepout":
+            continue
         area = keepout.area
         if area is None or area.border is None:
             continue
-        tile = _area_border_tile(area.border, transform)
-        if tile is None:
+        tiles = _area_border_tiles(area.border, transform)
+        if not tiles:
             continue
         border_layer = area.border.layer
         if border_layer in ("signal", "pcb"):
@@ -237,11 +330,38 @@ def _insert_keepouts(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTran
                 ObstacleArea(
                     name=keepout.area.name,
                     layer=layer_index,
-                    tiles=[tile],
+                    tiles=tiles,
+                    blocks_wires=keepout.kind != "via_keepout",
+                    blocks_vias=keepout.kind != "wire_keepout",
                 )
             )
 
 
+def _area_border_tiles(shape: Shape, transform: CoordinateTransform) -> list:
+    """Convex board tiles covering a keepout border shape.
+
+    Polygons are split into convex pieces rather than wrapped in one convex
+    tile: KiCad exports a rule area with a hole (a no-track ring along the
+    board edge, say) as a single keyhole polygon, and its convex hull is the
+    whole board.
+    """
+    if isinstance(shape, (Polygon, Path)):
+        coords = shape.coords
+        pts = [
+            IntPoint(
+                round(transform.dsn_to_board(coords[i])),
+                round(transform.dsn_to_board(coords[i + 1])),
+            )
+            for i in range(0, len(coords) - 1, 2)
+        ]
+        if len(pts) >= 3:
+            pieces = [t for t in PolygonShape(pts).split_to_convex() if not t.is_empty()]
+            if pieces:
+                return pieces
+    tile = _area_border_tile(shape, transform)
+    return [tile] if tile is not None else []
+
+
 def _area_border_tile(shape: Shape, transform: CoordinateTransform):
     """Convert an absolute-coordinate keepout border shape to one board tile."""
     if isinstance(shape, Rectangle):
@@ -269,3 +389,99 @@ def _area_border_tile(shape: Shape, transform: CoordinateTransform):
         ys = [p.y for p in pts] or [0]
         return IntBox(min(xs), min(ys), max(xs), max(ys))
     return None
+
+
+def _insert_image_keepouts(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTransform) -> None:
+    """Keepouts declared inside a footprint, placed with each instance.
+
+    KiCad exports copper that has no pin number this way, for instance the
+    plated ring of a mounting hole, so skipping them leaves copper the router
+    cannot see.
+    """
+    images = {img.name: img for img in dsn.images}
+    layer_no = {layer.name: i for i, layer in enumerate(dsn.layers)}
+    signal_layers = [i for i, layer in enumerate(dsn.layers) if layer.is_signal]
+    for placement in dsn.placements:
+        image = images.get(placement.lib_name)
+        if image is None:
+            continue
+        areas = [
+            *((a, True, True) for a in image.keepouts),
+            *((a, False, True) for a in image.via_keepouts),
+            *((a, True, False) for a in image.wire_keepouts),
+        ]
+        if not areas:
+            continue
+        for place in placement.places:
+            if place.x is None or place.y is None:
+                continue
+            for area, blocks_wires, blocks_vias in areas:
+                border = area.border
+                if border is None:
+                    continue
+                tiles = _placed_area_tiles(border, place, transform)
+                if not tiles:
+                    continue
+                if border.layer in ("signal", "pcb") or border.layer not in layer_no:
+                    layers = list(signal_layers)
+                else:
+                    layers = [layer_no[border.layer]]
+                if not place.is_front and signal_layers:
+                    top, bottom = min(signal_layers), max(signal_layers)
+                    layers = [top + bottom - layer for layer in layers]
+                for layer_index in layers:
+                    board.insert(
+                        ObstacleArea(
+                            name=area.name, layer=layer_index, tiles=tiles,
+                            blocks_wires=blocks_wires, blocks_vias=blocks_vias,
+                        )
+                    )
+
+
+def _placed_area_tiles(shape: Shape, place, transform: CoordinateTransform) -> list:
+    """An image-relative area border placed with its part, as convex board tiles."""
+    def to_board(x: float, y: float) -> IntPoint:
+        p = _to_board_offset(place, x, y)
+        return transform.dsn_to_board_point(place.x + p.x, place.y + p.y)
+
+    if isinstance(shape, Circle):
+        c = to_board(shape.center_x, shape.center_y)
+        r = round(transform.dsn_to_board(shape.diameter / 2))
+        return [IntBox(c.x - r, c.y - r, c.x + r, c.y + r)]
+    if isinstance(shape, Rectangle):
+        x0, y0, x1, y1 = shape.coords[:4]
+        pts = [to_board(x, y) for x, y in ((x0, y0), (x1, y0), (x1, y1), (x0, y1))]
+    elif isinstance(shape, (Polygon, Path)):
+        c = shape.coords
+        pts = [to_board(c[i], c[i + 1]) for i in range(0, len(c) - 1, 2)]
+    else:
+        return []
+    if len(pts) < 3:
+        return []
+    return [tile for tile in PolygonShape(pts).split_to_convex() if not tile.is_empty()]
+
+
+def _insert_zones(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTransform, nets) -> None:
+    """Each DSN plane as a ConductionArea of its net on its layer."""
+    layer_no = {layer.name: i for i, layer in enumerate(dsn.layers)}
+    numbers = {net.name: net.net_number for net in nets}
+    for plane in dsn.planes:
+        shape = plane.shape
+        if plane.net not in numbers or shape.layer not in layer_no:
+            continue
+        if not isinstance(shape, (Polygon, Path)):
+            continue
+        c = shape.coords
+        pts = [transform.dsn_to_board_point(c[i], c[i + 1]) for i in range(0, len(c) - 1, 2)]
+        if len(pts) < 3:
+            continue
+        polygon = PolygonShape(pts)
+        tiles = [t for t in polygon.split_to_convex() if not t.is_empty()]
+        if not tiles:
+            continue
+        board.insert(
+            ConductionArea(
+                net_nos=[numbers[plane.net]], name=plane.net, layer=layer_no[shape.layer],
+                tiles=tiles, polygon=polygon, blocks_wires=False, blocks_vias=False,
+            )
+        )

src/freeroute/board/items.py

@@ -48,6 +48,8 @@ class Pin(Item):
     """A component pin: a pad shape on one or more layers at a fixed location."""
 
     name: str = ""
+    #: reference designator of the owning component, for diagnostics
+    component_ref: str = ""
     padstack_name: str = ""
     location: IntPoint = field(default_factory=lambda: IntPoint(0, 0))
     #: layer indices the pad occupies (all signal layers when spanning)
@@ -70,6 +72,10 @@ class ObstacleArea(Item):
     name: str | None = None
     layer: int = 0
     tiles: list = field(default_factory=list)
+    #: a DSN keepout blocks both; wire_keepout only traces (KiCad's "no
+    #: tracks" rule area, where vias are allowed), via_keepout only vias
+    blocks_wires: bool = True
+    blocks_vias: bool = True
 
     def is_obstacle(self) -> bool:
         return True
@@ -85,7 +91,16 @@ class ObstacleArea(Item):
 
 @dataclass
 class ConductionArea(ObstacleArea):
-    """A power-plane conduction area (an obstacle carrying a net)."""
+    """A copper zone of one net (a DSN plane): not an obstacle to routing,
+    since KiCad refills it around other nets' copper, but copper of its net:
+    pads it touches are connected through it, and a route of its net ends on
+    it by placing a via inside it."""
+
+    #: the zone outline, for point containment
+    polygon: object = None
+
+    def is_obstacle(self) -> bool:
+        return False
 
 
 @dataclass

src/freeroute/board/outline.py

@@ -0,0 +1,122 @@
+"""The board outline as a polygon, and clearance tests against its edge.
+
+The DSN boundary is the real Edge.Cuts outline, rounded corners and all
+(arcs come as short segments). Routing inside its bounding box instead lets
+copper cut across a rounded corner closer to the edge than the board allows.
+"""
+
+from __future__ import annotations
+
+import math
+
+from freeroute.geometry import IntBox, IntPoint
+
+
+class BoardOutline:
+    """A simple polygon in board units, with point and box clearance tests."""
+
+    def __init__(self, points: list[IntPoint]) -> None:
+        pts = list(points)
+        if len(pts) > 1 and pts[0] == pts[-1]:
+            pts.pop()
+        self.points = pts
+        self._edges = [(pts[i], pts[(i + 1) % len(pts)]) for i in range(len(pts))]
+
+    def contains(self, p: IntPoint) -> bool:
+        """Even-odd point in polygon; points on the edge count as outside."""
+        inside = False
+        x, y = p.x, p.y
+        for a, b in self._edges:
+            if (a.y > y) != (b.y > y):
+                t = (y - a.y) / (b.y - a.y)
+                if x < a.x + t * (b.x - a.x):
+                    inside = not inside
+        return inside
+
+    def row_inside_spans(self, y: float) -> list[tuple[float, float]]:
+        """The x intervals inside the polygon along the horizontal line at ``y``."""
+        xs = sorted(
+            a.x + (y - a.y) * (b.x - a.x) / (b.y - a.y)
+            for a, b in self._edges
+            if (a.y > y) != (b.y > y)
+        )
+        # an odd count (a line grazing a vertex) drops the unpaired crossing
+        return list(zip(xs[0::2], xs[1::2], strict=False))
+
+    def edges(self):
+        return self._edges
+
+    def edge_distance(self, p: IntPoint) -> float:
+        return min(_point_segment(p, a, b) for a, b in self._edges)
+
+    def point_clear(self, p: IntPoint, reach: float) -> bool:
+        """Copper reaching ``reach`` around ``p`` stays inside, clear of the edge."""
+        return self.contains(p) and self.edge_distance(p) >= reach
+
+    def box_clear(self, box: IntBox, clearance: float) -> bool:
+        """``box`` lies inside the outline at least ``clearance`` from its edge."""
+        corners = [
+            IntPoint(box.ll.x, box.ll.y),
+            IntPoint(box.ur.x, box.ll.y),
+            IntPoint(box.ur.x, box.ur.y),
+            IntPoint(box.ll.x, box.ur.y),
+        ]
+        if not all(self.contains(c) for c in corners):
+            return False
+        return all(_segment_box(a, b, box) >= clearance for a, b in self._edges)
+
+
+def _point_segment(p: IntPoint, a: IntPoint, b: IntPoint) -> float:
+    dx, dy = b.x - a.x, b.y - a.y
+    length2 = dx * dx + dy * dy
+    if length2 == 0:
+        return math.hypot(p.x - a.x, p.y - a.y)
+    t = max(0.0, min(1.0, ((p.x - a.x) * dx + (p.y - a.y) * dy) / length2))
+    return math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy))
+
+
+def _point_box(p: IntPoint, box: IntBox) -> float:
+    dx = max(box.ll.x - p.x, 0, p.x - box.ur.x)
+    dy = max(box.ll.y - p.y, 0, p.y - box.ur.y)
+    return math.hypot(dx, dy)
+
+
+def _segment_box(a: IntPoint, b: IntPoint, box: IntBox) -> float:
+    """Distance between segment ``ab`` and an axis-aligned box (0 if they touch)."""
+    if _segments_cross_box(a, b, box):
+        return 0.0
+    corners = [
+        IntPoint(box.ll.x, box.ll.y),
+        IntPoint(box.ur.x, box.ll.y),
+        IntPoint(box.ur.x, box.ur.y),
+        IntPoint(box.ll.x, box.ur.y),
+    ]
+    return min(
+        _point_box(a, box),
+        _point_box(b, box),
+        *(_point_segment(c, a, b) for c in corners),
+    )
+
+
+def _segments_cross_box(a: IntPoint, b: IntPoint, box: IntBox) -> bool:
+    """Liang-Barsky clip: does segment ``ab`` enter the box?"""
+    t0, t1 = 0.0, 1.0
+    dx, dy = b.x - a.x, b.y - a.y
+    for p, q in (
+        (-dx, a.x - box.ll.x),
+        (dx, box.ur.x - a.x),
+        (-dy, a.y - box.ll.y),
+        (dy, box.ur.y - a.y),
+    ):
+        if p == 0:
+            if q < 0:
+                return False
+        else:
+            r = q / p
+            if p < 0:
+                t0 = max(t0, r)
+            else:
+                t1 = min(t1, r)
+            if t0 > t1:
+                return False
+    return True

src/freeroute/board/search_tree.py

@@ -47,6 +47,9 @@ class TreeShape:
     routed: bool = False
     exact: Simplex | None = None
     seg: tuple | None = None  # (a: IntPoint, b: IntPoint, half_width: int)
+    #: which copper a keepout tile stops: "all", "wires" (a wire_keepout,
+    #: vias allowed) or "vias" (a via_keepout)
+    blocks: str = "all"
 
     def on_layer(self, layer: int) -> bool:
         return layer in self.layers
@@ -118,7 +121,9 @@ class ShapeSearchTree:
                     result.append(shape)
         return result
 
-    def clearance_conflict(self, box: IntBox, net_no: int, layer: int, clearance: int) -> bool:
+    def clearance_conflict(
+        self, box: IntBox, net_no: int, layer: int, clearance: int, kind: str = "wire"
+    ) -> bool:
         """True if placing ``box`` (of ``net_no`` on ``layer``) would come *closer
         than* ``clearance`` to a different net's tile on that layer (exact).
 
@@ -129,6 +134,8 @@ class ShapeSearchTree:
         for shape in self.overlapping(expanded):
             if shape.net_no == net_no or not shape.on_layer(layer):
                 continue
+            if shape.blocks != "all" and shape.blocks != kind + "s":
+                continue  # a wire-only keepout does not stop a via, and so on
             if shape.exact is not None:
                 if overlaps_2d(shape.exact, expanded):
                     return True

src/freeroute/cli.py

@@ -19,6 +19,7 @@ import argparse
 import sys
 
 from freeroute.dsn.reader import parse_dsn
+from freeroute.route.orders import best_of_orders
 from freeroute.route.pipeline import (
     build_exact_routing_result,
     build_rooms_routing_result,
@@ -29,8 +30,8 @@ from freeroute.ses import write_ses
 #: which optional flags each engine actually implements. Anything not listed for
 #: an engine is rejected by :func:`_validate` rather than quietly ignored.
 ENGINE_OPTIONS: dict[str, frozenset[str]] = {
-    "grid": frozenset({"rip_up", "max_passes"}),
-    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes"}),
+    "grid": frozenset({"rip_up", "max_passes", "seed", "orders"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -41,6 +42,8 @@ _FLAG_NAMES = {
     "diagonal": "--diagonal",
     "rip_up": "--no-rip-up",
     "max_passes": "-mp/--max-passes",
+    "seed": "--seed",
+    "orders": "--orders",
 }
 
 
@@ -110,6 +113,49 @@ def build_parser() -> argparse.ArgumentParser:
         help="disable rip-up-and-retry (grid and exact engines)",
     )
     parser.add_argument("--layers", help="comma-separated signal layer indices to route on")
+    parser.add_argument(
+        "--grid-resolution",
+        type=int,
+        default=None,
+        metavar="K",
+        help="grid and exact engines: cells K times finer than trace + clearance; "
+        "default 2 for exact (reaches 0.5 mm pitch pins), 1 for grid",
+    )
+    parser.add_argument(
+        "--heuristic-weight",
+        type=float,
+        default=1.0,
+        metavar="W",
+        help="exact engine: weighted A* (W >= 1); larger is faster, routes at most "
+        "W times the shortest length (default 1)",
+    )
+    parser.add_argument(
+        "--edge-clearance",
+        type=float,
+        metavar="MM",
+        help="copper to board-edge clearance in mm, e.g. KiCad's min_copper_edge_clearance "
+        "(the DSN does not carry it); default 0: copper only has to stay inside the outline",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        metavar="N",
+        help="grid and exact engines: shuffle the order connections are routed in; "
+        "the same seed gives the same result (default: fewer-pin nets first)",
+    )
+    parser.add_argument(
+        "--orders",
+        type=int,
+        metavar="N",
+        help="grid and exact engines: route N connection orders in parallel and keep the "
+        "one leaving the fewest connections unrouted (the default order is one of them)",
+    )
+    parser.add_argument(
+        "--jobs",
+        type=int,
+        metavar="J",
+        help="processes for --orders (default: one per order, up to the CPU count)",
+    )
     return parser
 
 
@@ -129,6 +175,8 @@ def main(argv: list[str] | None = None) -> int:
             ("diagonal", args.diagonal),
             ("rip_up", args.no_rip_up),
             ("max_passes", args.max_passes is not None),
+            ("seed", args.seed is not None),
+            ("orders", args.orders is not None),
         )
         if asked
     ]
@@ -150,21 +198,62 @@ def main(argv: list[str] | None = None) -> int:
     rip_up = not args.no_rip_up
     max_passes = args.max_passes if args.max_passes is not None else 10
 
+    if args.orders is not None and args.orders < 1:
+        parser.error("--orders must be at least 1")
     if args.engine == "exact":
-        result = build_exact_routing_result(
-            dsn,
-            layers=layers,
-            shove=args.shove,
-            diagonal=args.diagonal,
-            rip_up=rip_up,
-            max_passes=max_passes,
+        options = {
+            "layers": layers,
+            "shove": args.shove,
+            "diagonal": args.diagonal,
+            "rip_up": rip_up,
+            "max_passes": max_passes,
+            "edge_clearance_mm": args.edge_clearance,
+            "resolution": 2 if args.grid_resolution is None else args.grid_resolution,
+            "heuristic_weight": args.heuristic_weight,
+        }
+    elif args.engine == "grid":
+        options = {
+            "layers": layers,
+            "rip_up": rip_up,
+            "max_passes": max_passes,
+            "edge_clearance_mm": args.edge_clearance,
+            "resolution": 1 if args.grid_resolution is None else args.grid_resolution,
+        }
+    if args.engine == "room":
+        result = build_rooms_routing_result(
+            dsn, layers=layers, shove=args.shove, pack=args.pack,
+            edge_clearance_mm=args.edge_clearance,
         )
-    elif args.engine == "room":
-        result = build_rooms_routing_result(dsn, layers=layers, shove=args.shove, pack=args.pack)
+    elif args.orders and args.orders > 1:
+        result, kept, tried = best_of_orders(
+            dsn_text, args.engine, options, orders=args.orders, seed=args.seed, jobs=args.jobs
+        )
+        counts = ", ".join(f"{'default' if s is None else s}: {m}" for s, (m, _z) in tried)
+        print(
+            f"freeroute: tried {len(tried)} orders, kept "
+            f"{'the default order' if kept is None else f'--seed {kept}'} (unrouted {counts})",
+            file=sys.stderr,
+        )
+    elif args.engine == "exact":
+        result = build_exact_routing_result(dsn, seed=args.seed, **options)
     else:
-        result = build_routing_result(dsn, layers=layers, rip_up=rip_up, max_passes=max_passes)
+        result = build_routing_result(dsn, seed=args.seed, **options)
 
     ses_text = write_ses(dsn, result)
+    missing = [u for u in result.unrouted if not u[3]]
+    in_zone = [u for u in result.unrouted if u[3]]
+    if missing:
+        # the SES is still written; say plainly what it is missing
+        print(f"freeroute: {len(missing)} connection(s) not routed:", file=sys.stderr)
+        for net, a, b, _zone in missing:
+            print(f"  {net}: {a} to {b}", file=sys.stderr)
+    if in_zone:
+        print(
+            f"freeroute: {len(in_zone)} more connection(s) left to a zone fill that may join them:",
+            file=sys.stderr,
+        )
+        for net, a, b, zone in in_zone:
+            print(f"  {net}: {a} to {b} (both in zone {zone})", file=sys.stderr)
 
     if args.output:
         with open(args.output, "w", encoding="utf-8") as f:

src/freeroute/dsn/model.py

@@ -112,6 +112,7 @@ class Image:
     outlines: list[Shape] = field(default_factory=list)
     keepouts: list[Area] = field(default_factory=list)
     via_keepouts: list[Area] = field(default_factory=list)
+    wire_keepouts: list[Area] = field(default_factory=list)
     place_keepouts: list[Area] = field(default_factory=list)
 
 
@@ -169,12 +170,20 @@ class NetClass:
     via_rule: str | None = None
 
 
+@dataclass
+class Plane:
+    """A ``(plane <net> <shape>)``: a copper zone of that net (KiCad's zones)."""
+
+    net: str
+    shape: Shape
+
+
 @dataclass
 class Keepout:
     """A structure-level keepout area with its kind."""
 
     area: Area
-    kind: str = "keepout"  # keepout | via_keepout | place_keepout
+    kind: str = "keepout"  # keepout | via_keepout | wire_keepout | place_keepout
 
 
 @dataclass
@@ -186,6 +195,8 @@ class DsnBoard:
     resolution: Resolution = field(default_factory=Resolution)
     unit: str = "mil"
     layers: list[Layer] = field(default_factory=list)
+    #: copper zones, as planes of a net
+    planes: list[Plane] = field(default_factory=list)
     #: bounding-box boundary shape (layer ``pcb``), if present
     boundary: Shape | None = None
     #: outline shapes (layer ``signal``)

src/freeroute/dsn/reader.py

@@ -178,6 +178,16 @@ def _read_structure(node: SExp, board: DsnBoard) -> None:
             area = read_area(it)
             if area is not None:
                 board.keepouts.append(Keepout(area=area, kind="via_keepout"))
+        elif head == "wire_keepout":
+            # KiCad writes a "no tracks" rule area this way (vias allowed).
+            area = read_area(it)
+            if area is not None:
+                board.keepouts.append(Keepout(area=area, kind="wire_keepout"))
+        elif head == "plane":
+            # (plane <net> <shape>): KiCad exports each zone this way
+            plane = _read_plane(it)
+            if plane is not None:
+                board.planes.append(plane)
         elif head == "place_keepout":
             area = read_area(it)
             if area is not None:
@@ -285,6 +295,10 @@ def _read_image(node: SExp) -> Image | None:
             area = read_area(it)
             if area is not None:
                 image.via_keepouts.append(area)
+        elif head == "wire_keepout":
+            area = read_area(it)
+            if area is not None:
+                image.wire_keepouts.append(area)
         elif head == "place_keepout":
             area = read_area(it)
             if area is not None:
@@ -504,3 +518,19 @@ def parse_dsn(text: str) -> DsnBoard:
         # `wiring` and unknown scopes are intentionally ignored for now.
 
     return board
+
+
+def _read_plane(node: SExp):
+    """``(plane <net> (polygon <layer> <width> x y ...))`` -> :class:`Plane`."""
+    from .model import Plane
+
+    items = node.items
+    if not items or not isinstance(items[0], Token):
+        return None
+    net = items[0].text
+    for sub in items[1:]:
+        if isinstance(sub, SExp):
+            shape = read_shape(sub)
+            if shape is not None:
+                return Plane(net=net, shape=shape)
+    return None

src/freeroute/route/exact_router.py

@@ -90,6 +90,11 @@ def route_board_exact(
     diagonal: bool = False,
     max_shove_depth: int = 5,
     shove_cap: int = 3,
+    via_half: int | None = None,
+    edge_clearance: int | None = None,
+    resolution: int = 1,
+    heuristic_weight: float = 1.0,
+    seed: int | None = None,
 ) -> ExactRouteResult:
     """Route ``board`` orthogonally and verify the result with exact geometry.
 
@@ -102,6 +107,7 @@ def route_board_exact(
         i for i, layer in enumerate(board.layer_structure.arr) if layer.is_signal
     ]
     half_width = max(trace_width // 2, 1)
+    via_half = via_half or half_width
     step = trace_width + clearance
 
     result = route_board(
@@ -113,7 +119,14 @@ def route_board_exact(
         max_passes=max_passes,
         rip_up=rip_up,
         orthogonal=True,
+        via_half=via_half,
+        edge_clearance=edge_clearance,
+        resolution=resolution,
+        heuristic_weight=heuristic_weight,
+        seed=seed,
     )
+    edge = 0 if edge_clearance is None else edge_clearance
+    outline = board.outline
 
     tree = ShapeSearchTree()
     owner = _counter()
@@ -132,29 +145,49 @@ def route_board_exact(
     for obstacle in board.get_obstacle_areas():
         if obstacle.layer not in signal_layers:
             continue
+        blocks = (
+            "all" if obstacle.blocks_wires and obstacle.blocks_vias
+            else "wires" if obstacle.blocks_wires else "vias"
+        )
         for tile in obstacle.tiles:
             box = tile.bounding_box()
             if not box.is_empty():
-                tree.insert(TreeShape(next(owner), -1, frozenset({obstacle.layer}), box))
+                tree.insert(
+                    TreeShape(next(owner), -1, frozenset({obstacle.layer}), box, blocks=blocks)
+                )
 
     via_layers = frozenset(signal_layers)
     accepted: dict[int, _Accepted] = {}
 
-    for net_no in sorted(set(result.wires) | set(result.vias)):
-        boxes = _net_boxes(result, net_no, half_width, via_layers)
+    # Verify connection by connection, so one conflicting segment of a
+    # 25-pin supply net costs that one connection, not the whole net.
+    rejected: list[tuple[int, str, str]] = []
+    ends_list = result.connection_ends or [("?", "?", "")] * len(result.connections)
+    for (net_no, wires, vias), ends in sorted(
+        zip(result.connections, ends_list, strict=False), key=lambda c: c[0][0]
+    ):
+        boxes = _copper_boxes(wires, vias, half_width, via_layers, via_half)
+        wire_count = len(_copper_boxes(wires, [], half_width, via_layers, via_half))
         if any(
-            tree.clearance_conflict(box, net_no, layer, clearance)
-            for box, box_layers in boxes
+            tree.clearance_conflict(
+                box, net_no, layer, clearance, "wire" if i < wire_count else "via"
+            )
+            for i, (box, box_layers) in enumerate(boxes)
             for layer in box_layers
-        ):
+        ) or (outline is not None and not all(outline.box_clear(b, edge) for b, _ in boxes)):
+            rejected.append((net_no, *ends))
             continue  # exact-clearance conflict -> drop (may be recovered by shove)
-        acc = _Accepted(wires=result.wires.get(net_no, []), vias=result.vias.get(net_no, []))
+        acc = accepted.get(net_no)
+        if acc is None:
+            acc = accepted[net_no] = _Accepted(wires=[], vias=[])
+        acc.wires.extend(wires)
+        acc.vias.extend(vias)
         for box, box_layers in boxes:
             oid = next(owner)
             tree.insert(TreeShape(oid, net_no, box_layers, box, routed=True))
             acc.owners.append(oid)
-        accepted[net_no] = acc
 
+    accepted_before_recovery = set(accepted)
     # a net is dropped if it has a real ratsnest (>= 2 pins on a signal layer)
     # but was not accepted — whether the grid failed to route it or its exact
     # copper conflicted.
@@ -189,6 +222,12 @@ def route_board_exact(
             )
 
     clean = RouteResult(half_width)
+    # what is still missing: what the grid could not route, plus what the
+    # exact check rejected, less any net shove or the diagonal pass recovered
+    clean.failed = [
+        *result.failed,
+        *(r for r in rejected if not (r[0] in accepted and r[0] not in accepted_before_recovery)),
+    ]
     for net_no, acc in accepted.items():
         clean.wires[net_no] = acc.wires
         clean.vias[net_no] = acc.vias
@@ -543,15 +582,20 @@ def _rollback(shoved, accepted, tree, owner) -> int:  # noqa: ARG001
 # --- helpers -----------------------------------------------------------------
 
 
-def _net_boxes(result, net_no, half_width, via_layers):
+def _net_boxes(result, net_no, half_width, via_layers, via_half=None):
+    return _copper_boxes(
+        result.wires.get(net_no, []), result.vias.get(net_no, []), half_width, via_layers, via_half
+    )
+
+
+def _copper_boxes(wires, vias, half_width, via_layers, via_half=None):
+    via_half = via_half or half_width
     boxes: list[tuple[IntBox, frozenset[int]]] = []
-    for layer, points in result.wires.get(net_no, []):
+    for layer, points in wires:
         for box in PolylineShape(Polyline(points), half_width).tiles():
             boxes.append((box, frozenset({layer})))
-    for loc in result.vias.get(net_no, []):
-        vbox = IntBox(
-            loc.x - half_width, loc.y - half_width, loc.x + half_width, loc.y + half_width
-        )
+    for loc in vias:
+        vbox = IntBox(loc.x - via_half, loc.y - via_half, loc.x + via_half, loc.y + via_half)
         boxes.append((vbox, via_layers))
     return boxes
 

src/freeroute/route/grid_router.py

@@ -28,10 +28,11 @@ from __future__ import annotations
 
 import heapq
 import math
+import random
 
 from freeroute.board.board import BasicBoard
-from freeroute.board.items import ObstacleArea, Pin
-from freeroute.geometry import IntPoint
+from freeroute.board.items import ConductionArea, ObstacleArea, Pin
+from freeroute.geometry import IntBox, IntPoint
 
 __all__ = ["GridRouter", "RouteResult", "route_board"]
 
@@ -59,7 +60,7 @@ class RouteResult:
     ``routed_net_numbers`` are the nets that got any wire or via.
     """
 
-    __slots__ = ("wires", "vias", "half_width", "unrouted")
+    __slots__ = ("wires", "vias", "half_width", "unrouted", "connections", "connection_ends", "failed")
 
     def __init__(self, half_width: int) -> None:
         self.wires: dict[int, list[tuple[int, list[IntPoint]]]] = {}
@@ -67,6 +68,13 @@ class RouteResult:
         self.half_width = half_width
         #: number of ratsnest connections left unrouted
         self.unrouted = 0
+        #: the same copper per routed connection: (net_no, wires, vias)
+        self.connections: list[tuple[int, list[tuple[int, list[IntPoint]]], list[IntPoint]]] = []
+        #: what each routed connection joins, and the zone both ends sit in
+        #: (or ""), parallel to ``connections``
+        self.connection_ends: list[tuple[str, str, str]] = []
+        #: connections left unrouted: (net_no, one end, the other end)
+        self.failed: list[tuple[int, str, str]] = []
 
     def add_wire(self, net_no: int, layer: int, path: list[IntPoint]) -> None:
         self.wires.setdefault(net_no, []).append((layer, path))
@@ -98,6 +106,12 @@ class _Connection:
         "vias",
         "trace_cells",
         "via_cells",
+        "via_halo",
+        "halo_nodes",
+        "a_group",
+        "b_group",
+        "a_end",
+        "b_end",
     )
 
     def __init__(self, index: int, net_no: int, a: Pin, b: Pin) -> None:
@@ -111,6 +125,14 @@ class _Connection:
         self.vias: list[IntPoint] = []
         self.trace_cells: list[tuple[Cell, int]] = []
         self.via_cells: list[Cell] = []
+        self.via_halo: list[Cell] = []
+        self.halo_nodes: list[Node] = []
+        # the pins and zones each end may use, and which pin the route ended
+        # on (None when it ended on a zone)
+        self.a_group: tuple[list[Pin], list] = ([a], [])
+        self.b_group: tuple[list[Pin], list] = ([b], [])
+        self.a_end: Pin | None = a
+        self.b_end: Pin | None = b
 
 
 class GridRouter:
@@ -129,8 +151,21 @@ class GridRouter:
         rip_cap: int = 4,
         rip_penalty: float = 30.0,
         orthogonal: bool = False,
+        via_half: int | None = None,
+        edge_clearance: int | None = None,
+        resolution: int = 1,
+        heuristic_weight: float = 1.0,
+        seed: int | None = None,
     ) -> None:
         self.board = board
+        # None keeps the deterministic order; a seed shuffles which connection
+        # routes first, to measure how much a result owes to the order
+        self.seed = seed
+        # how far (in cells) an escape stub may run to leave a walled-in pin
+        self._escape_cells = 12
+        self._crowded_cache: dict = {}
+        self._trapped_cache: dict = {}
+        self.heuristic_weight = max(float(heuristic_weight), 1.0)
         self.trace_width = max(trace_width, 1)
         self.clearance = max(clearance, 0)
         self.half_width = self.trace_width // 2
@@ -142,8 +177,30 @@ class GridRouter:
         # orthogonal routing (axis-aligned segments only) yields exact IntBox
         # trace copper; 8-connected also produces 45-degree segments.
         self._neighbours = _NEIGHBOURS[:4] if orthogonal else _NEIGHBOURS
-        # cell size must fit a trace plus its clearance to a neighbouring trace
-        self.step = max(self.trace_width + self.clearance, 1)
+        self._orthogonal = orthogonal
+        # At resolution 1 a cell is exactly one trace plus its clearance, so a
+        # trace owning its cell is the whole clearance model. At resolution k
+        # cells are k times finer, fine enough to give every pin of a 0.5 mm
+        # pitch row its own column, and a trace also claims a halo: the cells
+        # whose centre is nearer than trace + clearance to one of its own.
+        self.resolution = max(int(resolution), 1)
+        self.step = max((self.trace_width + self.clearance) // self.resolution, 1)
+        need = self.trace_width + self.clearance
+        reach = math.ceil(need / self.step)
+        self._halo_offsets = [
+            (dx, dy)
+            for dx in range(-reach, reach + 1)
+            for dy in range(-reach, reach + 1)
+            if (dx or dy) and math.hypot(dx, dy) * self.step < need
+        ]
+        # A via's copper is wider than a trace. Another net's trace needs its
+        # centre via_half + clearance + half_width from the via's centre, so a
+        # via also claims every cell within via_reach of its own.
+        self.via_half = via_half or self.half_width
+        # copper to board edge; KiCad's rule is usually wider than clearance
+        self.edge_clearance = 0 if edge_clearance is None else edge_clearance
+        need = self.via_half + self.clearance + self.half_width
+        self.via_reach = max(0, math.ceil(need / self.step) - 1)
 
         if layers is None:
             layers = [i for i, layer in enumerate(board.layer_structure.arr) if layer.is_signal]
@@ -157,10 +214,19 @@ class GridRouter:
 
         # static obstacles
         self._pad_block: dict[Node, set[int]] = {}
+        self._pad_own: dict[Node, set[int]] = {}
         self._keepout: set[Node] = set()
+        self._via_keepout: set[Node] = set()
+        # inner power (plane) layers: not routed on, reached by vias
+        self._power_layers = {
+            i for i, layer in enumerate(board.layer_structure.arr) if not layer.is_signal
+        }
+        self._zone_cells: dict[int, list[Node]] = {}
         # per-connection occupancy (owner = connection index)
         self._cell_owner: dict[Node, int] = {}
         self._via_owner: dict[Cell, int] = {}
+        # trace halos: node -> indices of the connections claiming it
+        self._halo: dict[Node, list[int]] = {}
         self._rasterize_obstacles()
 
     # --- grid helpers -------------------------------------------------------
@@ -176,16 +242,57 @@ class GridRouter:
         return IntPoint(self.origin_x + cell[0] * self.step, self.origin_y + cell[1] * self.step)
 
     def _cells_in_box(self, box, margin: int):
-        lo_x = round((box.ll.x - margin - self.origin_x) / self.step)
-        hi_x = round((box.ur.x + margin - self.origin_x) / self.step)
-        lo_y = round((box.ll.y - margin - self.origin_y) / self.step)
-        hi_y = round((box.ur.y + margin - self.origin_y) / self.step)
+        """Cells whose centre lies strictly inside ``box`` grown by ``margin``.
+
+        A trace centred there would come closer than ``margin`` to the box.
+        Rounding the bounds outward instead blocked cells up to half a step
+        clear of it, which walled in every pin of a 0.5 mm pitch package.
+        """
+        lo_x = math.floor((box.ll.x - margin - self.origin_x) / self.step) + 1
+        hi_x = math.ceil((box.ur.x + margin - self.origin_x) / self.step) - 1
+        lo_y = math.floor((box.ll.y - margin - self.origin_y) / self.step) + 1
+        hi_y = math.ceil((box.ur.y + margin - self.origin_y) / self.step) - 1
         for gx in range(max(lo_x, 0), min(hi_x, self.cols - 1) + 1):
             for gy in range(max(lo_y, 0), min(hi_y, self.rows - 1) + 1):
                 yield gx, gy
 
+    def _outline_blocked(self, reach: int) -> set[Cell]:
+        """Cells whose centre is outside the outline or within ``reach`` of its edge."""
+        outline = self.board.outline
+        blocked: set[Cell] = set()
+        for gy in range(self.rows):  # outside: one scanline per row
+            y = self.origin_y + gy * self.step
+            spans = outline.row_inside_spans(y)
+            for gx in range(self.cols):
+                x = self.origin_x + gx * self.step
+                if not any(lo < x < hi for lo, hi in spans):
+                    blocked.add((gx, gy))
+        for a, b in outline.edges():  # too close: only cells near each edge
+            edge_box = IntBox(min(a.x, b.x), min(a.y, b.y), max(a.x, b.x), max(a.y, b.y))
+            for cell in self._cells_in_box(edge_box, reach):
+                if cell not in blocked and outline.edge_distance(self._cell_center(cell)) < reach:
+                    blocked.add(cell)
+        return blocked
+
+    def _inside_own_pad(self, cell: Cell, shape) -> bool:
+        """A trace centred on ``cell`` lies entirely on the pad's own copper."""
+        c = self._cell_center(cell)
+        h = self.half_width
+        return all(
+            shape.contains(IntPoint(c.x + dx, c.y + dy)) for dx in (-h, h) for dy in (-h, h)
+        )
+
     def _rasterize_obstacles(self) -> None:
         margin = self.clearance + self.half_width
+        outline = self.board.outline
+        self._via_edge_block: set[Cell] = set()
+        if outline is not None:
+            # cells too close to the real outline (rounded corners included):
+            # for a trace on every layer, and separately for a via's wider copper
+            for cell in self._outline_blocked(self.half_width + self.edge_clearance):
+                for layer in self.layers:
+                    self._keepout.add((*cell, layer))
+            self._via_edge_block = self._outline_blocked(self.via_half + self.edge_clearance)
         for item in self.board.get_items():
             if isinstance(item, Pin):
                 box = item.shape.bounding_box() if item.shape is not None else None
@@ -196,19 +303,41 @@ class GridRouter:
                 for cell in self._cells_in_box(box, margin):
                     for layer in pin_layers:
                         self._pad_block.setdefault((*cell, layer), set()).add(net)
+                # Copper of the pin's own net: a trace inside it adds nothing,
+                # so it is open to that net however close the neighbours are.
+                # That is how a route leaves a fine-pitch pin.
+                for cell in self._cells_in_box(box, 0):
+                    if self._inside_own_pad(cell, item.shape):
+                        for layer in pin_layers:
+                            self._pad_own.setdefault((*cell, layer), set()).add(net)
+            elif isinstance(item, ConductionArea):
+                continue  # a zone is copper of its net, not an obstacle
             elif isinstance(item, ObstacleArea):
                 if item.layer not in self.layers:
                     continue
-                box = item.bounding_box()
-                if box.is_empty():
-                    continue
-                for cell in self._cells_in_box(box, self.clearance):
-                    self._keepout.add((*cell, item.layer))
+                # Tile by tile: the area's own bounding box of a ring (a
+                # no-track border along the board edge) is the whole board.
+                for tile in item.tiles:
+                    box = tile.bounding_box()
+                    if box.is_empty():
+                        continue
+                    # the same distance the exact engine verifies against
+                    for cell in self._cells_in_box(box, margin):
+                        if item.blocks_wires:
+                            self._keepout.add((*cell, item.layer))
+                        if item.blocks_vias:
+                            self._via_keepout.add((*cell, item.layer))
 
     # --- occupancy cost -----------------------------------------------------
 
     def _enter_cost(
-        self, cell: Cell, layer: int, net_no: int, allow_ripup: bool, conns: list[_Connection]
+        self,
+        cell: Cell,
+        layer: int,
+        net_no: int,
+        allow_ripup: bool,
+        conns: list[_Connection],
+        wire_keepout: bool = True,
     ) -> float | None:
         """Cost to enter ``(cell, layer)`` for ``net_no``; ``None`` if blocked.
 
@@ -218,10 +347,10 @@ class GridRouter:
         already hit ``rip_cap`` (then it hardens into a wall).
         """
         node = (*cell, layer)
-        if node in self._keepout:
+        if wire_keepout and node in self._keepout:
             return None
         pads = self._pad_block.get(node)
-        if pads and any(n != net_no for n in pads):
+        if pads and any(n != net_no for n in pads) and net_no not in self._pad_own.get(node, ()):
             return None
         blocking = None
         owner = self._cell_owner.get(node)
@@ -231,6 +360,11 @@ class GridRouter:
             via_owner = self._via_owner.get(cell)
             if via_owner is not None and conns[via_owner].net_no != net_no:
                 blocking = via_owner
+        if blocking is None:
+            for i in self._halo.get(node, ()):
+                if conns[i].net_no != net_no:
+                    blocking = i
+                    break
         if blocking is None:
             return 0.0
         if not allow_ripup:
@@ -240,40 +374,90 @@ class GridRouter:
             return None
         return self.rip_penalty * (1 + rip_count)
 
+    def _via_cells(self, cell: Cell) -> list[Cell]:
+        """The cell a via sits in plus the neighbours its copper reaches."""
+        r = self.via_reach
+        cx, cy = cell
+        return [
+            (x, y)
+            for x in range(max(cx - r, 0), min(cx + r, self.cols - 1) + 1)
+            for y in range(max(cy - r, 0), min(cy + r, self.rows - 1) + 1)
+        ]
+
     def _via_placeable(self, cell: Cell, net_no: int, conns: list[_Connection]) -> bool:
-        """A through via needs every signal layer strictly free of other nets."""
-        return all(
-            self._enter_cost(cell, layer, net_no, False, conns) == 0.0 for layer in self.layers
-        )
+        """A through via needs its whole footprint free of other nets on every layer."""
+        if cell in self._via_edge_block:
+            return False
+        for c in self._via_cells(cell):
+            for layer in self.layers:
+                if (*c, layer) in self._via_keepout:
+                    return False
+                if self._enter_cost(c, layer, net_no, False, conns, wire_keepout=False) != 0.0:
+                    return False
+        return True
 
     # --- A* search ----------------------------------------------------------
 
     def _search(
         self, conn: _Connection, allow_ripup: bool, conns: list[_Connection]
     ) -> list[Node] | None:
-        start_cell = self._cell_of(conn.a.location)
-        goal_cell = self._cell_of(conn.b.location)
-        a_layers = [layer for layer in conn.a.layers if layer in self.layers]
-        b_layers = [layer for layer in conn.b.layers if layer in self.layers]
-        if not a_layers or not b_layers:
+        goal_cell = self._group_target(conn.b_group)
+        if not conn.b_group[0] and any(z.layer in self._power_layers for z in conn.b_group[1]):
+            # the plane is everywhere: aim at where the route starts instead
+            goal_cell = self._group_target(conn.a_group)
+        starts = self._group_ends(conn.a_group, conn.net_no, conns)
+        goals = self._group_ends(conn.b_group, conn.net_no, conns)
+        if not starts or not goals:
             return None
-        starts = {(*start_cell, layer) for layer in a_layers}
-        goals = {(*goal_cell, layer) for layer in b_layers}
-        if starts & goals:
-            return [min(starts & goals)]
+        common = sorted(set(starts) & set(goals))
+        if common:
+            conn.a_end, conn.b_end = starts[common[0]], goals[common[0]]
+            return [common[0]]
         net_no = conn.net_no
 
         open_heap: list[tuple[float, Node]] = []
         g_score: dict[Node, float] = {}
         came_from: dict[Node, Node] = {}
+        # a stub costs its length, so the nearest cell wins unless it is blocked
+        goal_stub = {n: self._stub_cost(p, n) for n, p in goals.items() if p is not None}
         for s in sorted(starts):
-            g_score[s] = 0.0
-            heapq.heappush(open_heap, (self._h(s, goal_cell), s))
+            pin = starts[s]
+            g_score[s] = self._stub_cost(pin, s) if pin is not None else 0.0
+            heapq.heappush(open_heap, (g_score[s] + self._h(s, goal_cell), s))
 
+        # Via footprints are checked lazily: a layer change goes on the heap as
+        # a candidate and is checked only if it is popped. Most never are (a
+        # via costs a lot), and the check is the single most expensive thing
+        # the search does. A check can only rule a via out, never make it
+        # cheaper, so deferring it cannot change which route is found.
+        via_ok: dict[Cell, bool] = {}
         while open_heap:
-            _, current = heapq.heappop(open_heap)
+            entry = heapq.heappop(open_heap)
+            if len(entry) == 4:  # a deferred via: (f, target, g, source)
+                _, target, g_via, source = entry
+                if g_via >= g_score.get(target, math.inf):
+                    continue
+                cell = (target[0], target[1])
+                ok = via_ok.get(cell)
+                if ok is None:
+                    ok = via_ok[cell] = self._via_placeable(cell, net_no, conns)
+                if ok:
+                    self._relax(source, target, g_via, goal_cell, g_score, came_from, open_heap)
+                continue
+            current = entry[1]
             if current in goals:
-                return _reconstruct(came_from, current)
+                end = goals[current]
+                cell = (current[0], current[1])
+                if isinstance(end, ConductionArea):  # a plane end needs its via to fit
+                    ok = via_ok.get(cell)
+                    if ok is None:
+                        ok = via_ok[cell] = self._via_placeable(cell, net_no, conns)
+                else:
+                    ok = True
+                if ok:
+                    path = _reconstruct(came_from, current)
+                    conn.a_end, conn.b_end = starts.get(path[0]), end
+                    return path
             cx, cy, cl = current
             base = g_score[current]
             for dx, dy in self._neighbours:
@@ -281,8 +465,8 @@ class GridRouter:
                 if not (0 <= cell[0] < self.cols and 0 <= cell[1] < self.rows):
                     continue
                 nxt = (*cell, cl)
-                if nxt in goals:
-                    enter = 0.0
+                if nxt in goal_stub:  # a pin end; a zone end is entered normally
+                    enter = goal_stub[nxt]
                 else:
                     enter = self._enter_cost(cell, cl, net_no, allow_ripup, conns)
                     if enter is None:
@@ -291,16 +475,241 @@ class GridRouter:
                 self._relax(
                     current, nxt, base + step + enter, goal_cell, g_score, came_from, open_heap
                 )
-            if len(self.layers) > 1 and self._via_placeable((cx, cy), net_no, conns):
+            if len(self.layers) > 1:
+                g_via = base + self.via_cost
                 for layer in self.layers:
                     if layer == cl:
                         continue
                     nxt = (cx, cy, layer)
-                    self._relax(
-                        current, nxt, base + self.via_cost, goal_cell, g_score, came_from, open_heap
-                    )
+                    if g_via < g_score.get(nxt, math.inf):
+                        heapq.heappush(
+                            open_heap, (g_via + self._h(nxt, goal_cell), nxt, g_via, current)
+                        )
         return None
 
+    # --- pin stubs ----------------------------------------------------------
+    # A pin rarely sits on a cell centre, so every route starts and ends with a
+    # short stub from the pin to its first cell. The grid has to see that
+    # copper too, or a stub ends up closer than clearance to a trace in the
+    # cell beside it.
+
+    def _stub_cells(self, pin_location: IntPoint, cell: Cell) -> list[Cell]:
+        """Cells where another net's trace would come too close to the stub."""
+        from freeroute.board.outline import _point_segment
+
+        end = self._cell_center(cell)
+        reach = 2 * self.half_width + self.clearance
+        box = IntBox(
+            min(pin_location.x, end.x), min(pin_location.y, end.y),
+            max(pin_location.x, end.x), max(pin_location.y, end.y),
+        )
+        return [
+            c
+            for c in self._cells_in_box(box, reach)
+            if _point_segment(self._cell_center(c), pin_location, end) < reach
+        ]
+
+    def _stub_clear(self, pin: Pin, cell: Cell, layer: int, net_no: int, conns) -> bool:
+        for c in self._stub_cells(pin.location, cell):
+            owner = self._cell_owner.get((*c, layer))
+            if owner is not None and conns[owner].net_no != net_no:
+                return False
+            via_owner = self._via_owner.get(c)
+            if via_owner is not None and conns[via_owner].net_no != net_no:
+                return False
+        return True
+
+    def _zone_nodes(self, zone) -> list[Node]:
+        """Cells of a zone where a via of this net fits inside its copper; for a
+        plane on a power layer, on every routing layer (a via reaches it)."""
+        key = id(zone)
+        if key not in self._zone_cells:
+            h = self.via_half
+            layers = [zone.layer] if zone.layer in self.layers else list(self.layers)
+            nodes = []
+            for tile in zone.tiles:
+                for cell in self._cells_in_box(tile.bounding_box(), 0):
+                    c = self._cell_center(cell)
+                    if all(
+                        zone.polygon.contains(IntPoint(c.x + dx, c.y + dy))
+                        for dx in (-h, h) for dy in (-h, h)
+                    ):
+                        nodes.extend((*cell, layer) for layer in layers)
+            self._zone_cells[key] = sorted(set(nodes))
+        return self._zone_cells[key]
+
+    def _zone_is_solid(self, zone, coverage: float = 0.95) -> bool:
+        """Whether a zone's fill can be trusted to be one piece of copper.
+
+        A zone outline is where copper may go, not where it will be: other
+        nets' tracks through a board-wide pour break its fill into islands,
+        and a pad inside the outline need not reach the rest of the net. It
+        is safe to count on only when no track can cross it, which is what a
+        no-tracks rule area over the zone guarantees (the rc4 power pours).
+        Otherwise the zone is left out and its pads are routed with tracks.
+        """
+        cells = [cell for tile in zone.tiles for cell in self._cells_in_box(tile.bounding_box(), 0)
+                 if zone.polygon.contains(self._cell_center(cell))]
+        if not cells:
+            return False
+        covered = sum((*cell, zone.layer) in self._keepout for cell in cells)
+        return covered >= coverage * len(cells)
+
+    def _left_to_zone(self, conn) -> str:
+        """The zone both ends of an unrouted connection sit in, if any: its
+        fill may well join them, even when it is not trusted for routing."""
+        for zone in self._every_zone_by_net.get(conn.net_no, []):
+            if any(_pin_touches_zone(p, zone) for p in conn.a_group[0]) and any(
+                _pin_touches_zone(p, zone) for p in conn.b_group[0]
+            ):
+                return zone.name or "zone"
+        return ""
+
+    def _group_ends(self, group, net_no: int, conns) -> dict[Node, Pin | None]:
+        """End nodes of a group, each mapped to its pin (None for a zone cell)."""
+        ends: dict[Node, Pin | None] = {}
+        for pin in group[0]:
+            for node in sorted(self._end_nodes(pin, net_no, conns)):
+                ends.setdefault(node, pin)
+        for zone in group[1]:
+            plane = zone.layer in self._power_layers
+            for node in self._zone_nodes(zone):
+                # a plane end is marked with the plane: the route ends in a via
+                ends.setdefault(node, zone if plane else None)
+        return ends
+
+    def _group_target(self, group) -> Cell:
+        if group[0]:
+            return self._cell_of(group[0][0].location)
+        box = group[1][0].bounding_box()
+        return self._cell_of(IntPoint((box.ll.x + box.ur.x) // 2, (box.ll.y + box.ur.y) // 2))
+
+    def _stub_cost(self, pin: Pin, node: Node) -> float:
+        c = self._cell_center(node[:2])
+        dx, dy = abs(c.x - pin.location.x), abs(c.y - pin.location.y)
+        if self._orthogonal:  # measured the way the route itself is allowed to move
+            return (dx + dy) / self.step
+        return math.hypot(dx, dy) / self.step
+
+    def _end_nodes(self, pin: Pin, net_no: int, conns) -> set[Node]:
+        """Nodes a route may start or end on for ``pin``: the nearest cell and
+        its neighbours, where the cell is enterable and the stub to it is clear.
+        A crowded fine-pitch pin gets more than one way out."""
+        layers = [layer for layer in pin.layers if layer in self.layers]
+        cx, cy = self._cell_of(pin.location)
+        nodes: set[Node] = set()
+        for dx, dy in ((0, 0), *self._neighbours):
+            cell = (cx + dx, cy + dy)
+            if not (0 <= cell[0] < self.cols and 0 <= cell[1] < self.rows):
+                continue
+            for layer in layers:
+                if (dx or dy) and self._enter_cost(cell, layer, net_no, False, conns) is None:
+                    continue
+                if self._stub_clear(pin, cell, layer, net_no, conns):
+                    nodes.add((*cell, layer))
+        # Also offer exact escape stubs: a fine-pitch pin's nearby cells can be
+        # a pocket inside its own pad that leads nowhere (the grid columns miss
+        # the narrow legal band past the pad tip). The stub's length is its
+        # cost, so it is only taken where a short step would not do.
+        if self._orthogonal and self._crowded(pin, net_no) and self._trapped(pin, net_no, nodes):
+            nodes |= self._escape_nodes(pin, net_no, conns, layers, (cx, cy))
+        if not nodes:  # nothing clear: fall back to the nearest cell, as before
+            nodes = {(cx, cy, layer) for layer in layers}
+        return nodes
+
+    def _crowded(self, pin: Pin, net_no: int) -> bool:
+        """A pin whose neighbour pad of another net is too close for a trace
+        to pass between them: a fine-pitch pin, the case escapes are for."""
+        key = (id(pin), net_no)
+        cached = self._crowded_cache.get(key)
+        if cached is not None:
+            return cached
+        box = pin.shape.bounding_box() if pin.shape is not None else None
+        gap = self.trace_width + 2 * self.clearance
+        crowded = False
+        if box is not None:
+            for other in self.board.get_pins():
+                if other is pin or net_no in other.net_nos or other.shape is None:
+                    continue
+                if not set(other.layers) & set(pin.layers):
+                    continue
+                ob = other.shape.bounding_box()
+                dx = max(ob.ll.x - box.ur.x, box.ll.x - ob.ur.x, 0)
+                dy = max(ob.ll.y - box.ur.y, box.ll.y - ob.ur.y, 0)
+                if max(dx, dy) < gap and min(dx, dy) == 0:
+                    crowded = True
+                    break
+        self._crowded_cache[key] = crowded
+        return crowded
+
+    def _static_open(self, node: Node, net_no: int) -> bool:
+        """Open to ``net_no`` as far as pads and keepouts go (routes ignored)."""
+        if node in self._keepout:
+            return False
+        pads = self._pad_block.get(node)
+        return not (pads and any(n != net_no for n in pads) and net_no not in self._pad_own.get(node, ()))
+
+    def _trapped(self, pin: Pin, net_no: int, nodes: set[Node], limit: int = 60) -> bool:
+        """Whether a pin's nearby cells are a dead-end pocket, judged against
+        pads and keepouts only (not other routes), so it is fixed per pin."""
+        key = (id(pin), net_no)
+        cached = self._trapped_cache.get(key)
+        if cached is not None:
+            return cached
+        seen = set(nodes)
+        frontier = list(nodes)
+        while frontier and len(seen) < limit:
+            x, y, layer = frontier.pop()
+            for dx, dy in self._neighbours:
+                n = (x + dx, y + dy, layer)
+                if n in seen or not (0 <= n[0] < self.cols and 0 <= n[1] < self.rows):
+                    continue
+                if self._static_open(n, net_no):
+                    seen.add(n)
+                    frontier.append(n)
+        trapped = len(seen) < limit
+        self._trapped_cache[key] = trapped
+        return trapped
+
+    def _escape_nodes(self, pin: Pin, net_no: int, conns, layers, origin: Cell) -> set[Node]:
+        """For a pin walled in on the grid (a fine-pitch pin whose legal band
+        the grid columns miss): look along each axis for the first open cell
+        whose straight stub from the pin clears every other net's pad by the
+        full margin, measured exactly rather than on the grid."""
+        from freeroute.board.outline import _segment_box
+
+        margin = self.half_width + self.clearance
+        reach = self._escape_cells
+        near = [
+            (p.shape.bounding_box(), set(p.layers))
+            for p in self.board.get_pins()
+            if p.shape is not None
+            and net_no not in p.net_nos
+            and abs(p.location.x - pin.location.x) < (reach + 2) * self.step * 2
+            and abs(p.location.y - pin.location.y) < (reach + 2) * self.step * 2
+        ]
+        cx, cy = origin
+        nodes: set[Node] = set()
+        for dx, dy in _NEIGHBOURS[:4]:
+            for k in range(2, reach + 1):
+                cell = (cx + dx * k, cy + dy * k)
+                if not (0 <= cell[0] < self.cols and 0 <= cell[1] < self.rows):
+                    break
+                end = self._cell_center(cell)
+                for layer in layers:
+                    if self._enter_cost(cell, layer, net_no, False, conns) is None:
+                        continue
+                    if any(
+                        layer in box_layers and _segment_box(pin.location, end, box) < margin
+                        for box, box_layers in near
+                    ):
+                        continue
+                    if self._stub_clear(pin, cell, layer, net_no, conns):
+                        nodes.add((*cell, layer))
+                if any(n[:2] == cell for n in nodes):
+                    break  # the first open cell along this axis is enough
+        return nodes
+
     def _relax(self, current, nxt, tentative, goal_cell, g_score, came_from, open_heap):
         if tentative < g_score.get(nxt, math.inf):
             came_from[nxt] = current
@@ -308,25 +717,58 @@ class GridRouter:
             heapq.heappush(open_heap, (tentative + self._h(nxt, goal_cell), nxt))
 
     def _h(self, node: Node, goal_cell: Cell) -> float:
-        return math.hypot(node[0] - goal_cell[0], node[1] - goal_cell[1])
+        dx, dy = abs(node[0] - goal_cell[0]), abs(node[1] - goal_cell[1])
+        # the tightest estimate the allowed moves admit (Manhattan when only
+        # orthogonal steps exist), scaled by heuristic_weight: above 1 the
+        # search heads for the goal instead of flooding open board, for a
+        # route at most that factor longer than the shortest
+        base = dx + dy if self._orthogonal else math.hypot(dx, dy)
+        return self.heuristic_weight * base
 
     # --- commit / rip -------------------------------------------------------
 
     def _commit(self, conn: _Connection, path: list[Node]) -> None:
         wire_segs, via_cells = _split_path(path)
+        via_cells = list(via_cells)
+        if isinstance(conn.a_end, ConductionArea):
+            via_cells.append((path[0][0], path[0][1]))
+        if isinstance(conn.b_end, ConductionArea):
+            via_cells.append((path[-1][0], path[-1][1]))
         conn.trace_cells = [(cell, layer) for layer, cells in wire_segs for cell in cells]
         conn.via_cells = list(via_cells)
         for cell, layer in conn.trace_cells:
             self._cell_owner[(*cell, layer)] = conn.index
+        conn.halo_nodes = []
+        for (cx, cy), layer in conn.trace_cells:
+            for dx, dy in self._halo_offsets:
+                x, y = cx + dx, cy + dy
+                if 0 <= x < self.cols and 0 <= y < self.rows:
+                    node = (x, y, layer)
+                    self._halo.setdefault(node, []).append(conn.index)
+                    conn.halo_nodes.append(node)
+        conn.via_halo = []
         for cell in conn.via_cells:
-            self._via_owner[cell] = conn.index
+            for c in self._via_cells(cell):
+                if c not in self._via_owner:
+                    self._via_owner[c] = conn.index
+                    conn.via_halo.append(c)
+        ends = ((conn.a_end, wire_segs[0], 0), (conn.b_end, wire_segs[-1], -1)) if wire_segs else ()
+        for pin, (layer, cells), at in ends:
+            if not isinstance(pin, Pin):
+                continue  # ended on a zone or a plane: no stub
+            cell = cells[at]
+            for c in self._stub_cells(pin.location, cell):
+                node = (*c, layer)
+                if node not in self._cell_owner:
+                    self._cell_owner[node] = conn.index
+                    conn.trace_cells.append((c, layer))
         conn.wires = []
         for idx, (layer, cells) in enumerate(wire_segs):
             points = [self._cell_center(c) for c in cells]
-            if idx == 0:
-                points.insert(0, conn.a.location)
-            if idx == len(wire_segs) - 1:
-                points.append(conn.b.location)
+            if idx == 0 and isinstance(conn.a_end, Pin):
+                points.insert(0, conn.a_end.location)
+            if idx == len(wire_segs) - 1 and isinstance(conn.b_end, Pin):
+                points.append(conn.b_end.location)
             points = _simplify(points)
             if len(points) >= 2:
                 conn.wires.append((layer, points))
@@ -337,9 +779,17 @@ class GridRouter:
         for cell, layer in conn.trace_cells:
             if self._cell_owner.get((*cell, layer)) == conn.index:
                 del self._cell_owner[(*cell, layer)]
-        for cell in conn.via_cells:
+        for cell in conn.via_halo:
             if self._via_owner.get(cell) == conn.index:
                 del self._via_owner[cell]
+        conn.via_halo = []
+        for node in conn.halo_nodes:
+            claims = self._halo.get(node)
+            if claims is not None:
+                claims.remove(conn.index)
+                if not claims:
+                    del self._halo[node]
+        conn.halo_nodes = []
         conn.trace_cells = []
         conn.via_cells = []
         conn.wires = []
@@ -356,6 +806,9 @@ class GridRouter:
             via_owner = self._via_owner.get((cx, cy))
             if via_owner is not None and conns[via_owner].net_no != net_no:
                 owners.add(via_owner)
+            for i in self._halo.get((cx, cy, cl), ()):
+                if conns[i].net_no != net_no:
+                    owners.add(i)
         return owners
 
     # --- passes -------------------------------------------------------------
@@ -363,6 +816,7 @@ class GridRouter:
     def route(self) -> RouteResult:
         """Route all ratsnest connections, using rip-up-and-retry across passes."""
         conns = self._build_connections()
+        self._conns = conns
         if not conns:
             return RouteResult(self.half_width)
 
@@ -370,9 +824,13 @@ class GridRouter:
         best_count = -1
         best_snapshot: list[tuple[int, list, list]] | None = None
         best_unrouted = len(conns)
+        # conns[i].index == i is what rip-up relies on, so shuffle a view
+        order = list(conns)
+        if self.seed is not None:
+            random.Random(self.seed).shuffle(order)
         for _ in range(passes):
             changed = False
-            for conn in conns:  # deterministic: connection creation order
+            for conn in order:
                 if conn.routed:
                     continue
                 if self._try_route(conn, conns):
@@ -403,12 +861,37 @@ class GridRouter:
 
     def _build_connections(self) -> list[_Connection]:
         pins_by_net = self._pins_by_net()
+        zones_by_net: dict[int, list] = {}
+        self._every_zone_by_net: dict[int, list] = {}
+        for zone in self.board.get_conduction_areas():
+            if zone.layer in self.layers and zone.net_nos:
+                self._every_zone_by_net.setdefault(zone.net_nos[0], []).append(zone)
+        for zone in self.board.get_conduction_areas():
+            if zone.layer in self.layers and zone.net_nos and self._zone_is_solid(zone):
+                zones_by_net.setdefault(zone.net_nos[0], []).append(zone)
+        # planes: zones of a net on an inner power layer, solid by construction
+        planes_by_net: dict[int, list] = {}
+        for zone in self.board.get_conduction_areas():
+            if zone.net_nos and zone.layer in self._power_layers:
+                planes_by_net.setdefault(zone.net_nos[0], []).append(zone)
+        plane_ids = frozenset(id(z) for zs in planes_by_net.values() for z in zs)
         conns: list[_Connection] = []
+        nets = set(pins_by_net) | set(zones_by_net) | set(planes_by_net)
         # deterministic: fewer-pin nets first, then by net number
-        for net_no in sorted(pins_by_net, key=lambda n: (len(pins_by_net[n]), n)):
-            pins = pins_by_net[net_no]
-            for a, b in zip(pins, pins[1:], strict=False):
-                conns.append(_Connection(len(conns), net_no, a, b))
+        for net_no in sorted(nets, key=lambda n: (len(pins_by_net.get(n, [])), n)):
+            zones = zones_by_net.get(net_no, []) + planes_by_net.get(net_no, [])
+            groups = _connected_groups(pins_by_net.get(net_no, []), zones, plane_ids)
+            hubs = [g for g in groups if any(id(z) in plane_ids for z in g[1])]
+            if hubs:
+                # a plane net: every other group goes straight to the plane
+                # (usually a stub and a via), not pad to pad across the board
+                pairs = [(g, hubs[0]) for g in groups if g is not hubs[0]]
+            else:
+                pairs = list(zip(groups, groups[1:], strict=False))
+            for ga, gb in pairs:
+                conn = _Connection(len(conns), net_no, _first(ga[0]), _first(gb[0]))
+                conn.a_group, conn.b_group = ga, gb
+                conns.append(conn)
         return conns
 
     def _pins_by_net(self) -> dict[int, list[Pin]]:
@@ -420,9 +903,10 @@ class GridRouter:
                 by_net.setdefault(net_no, []).append(pin)
         return by_net
 
-    def _snapshot(self, conns: list[_Connection]) -> list[tuple[int, list, list]]:
+    def _snapshot(self, conns: list[_Connection]) -> list[tuple]:
         return [
-            (c.net_no, [(layer, list(pts)) for layer, pts in c.wires], list(c.vias))
+            (c.net_no, [(layer, list(pts)) for layer, pts in c.wires], list(c.vias),
+             (*_ends_of(c), self._left_to_zone(c)))
             for c in conns
             if c.routed
         ]
@@ -430,14 +914,95 @@ class GridRouter:
     def _result_from(self, snapshot, unrouted: int) -> RouteResult:
         result = RouteResult(self.half_width)
         result.unrouted = unrouted
-        for net_no, wires, vias in snapshot:
+        for net_no, wires, vias, ends in snapshot:
             for layer, points in wires:
                 result.add_wire(net_no, layer, points)
             for location in vias:
                 result.add_via(net_no, location)
+            result.connections.append((net_no, wires, vias))
+            result.connection_ends.append(ends)
+        routed = {ends[:2] + (net_no,) for net_no, _w, _v, ends in snapshot}
+        result.failed = [
+            (c.net_no, *_ends_of(c), self._left_to_zone(c))
+            for c in self._conns
+            if _ends_of(c) + (c.net_no,) not in routed
+        ]
         return result
 
 
+def _first(items):
+    return items[0] if items else None
+
+
+def _group_label(group) -> str:
+    pins, zones = group
+    parts = [f"{p.component_ref}-{p.name}" for p in pins[:3]]
+    if len(pins) > 3:
+        parts.append(f"+{len(pins) - 3} pins")
+    parts += [f"zone {z.name}" for z in zones[:1]]
+    return "/".join(parts) or "?"
+
+
+def _ends_of(conn) -> tuple[str, str]:
+    """A readable description of what a connection joins."""
+    return _group_label(conn.a_group), _group_label(conn.b_group)
+
+
+def _pin_touches_zone(pin: Pin, zone, plane: bool = False) -> bool:
+    """A pad on the zone's layer whose centre or a corner lies in the zone.
+
+    For a plane on an inner power layer: a through-hole pad (on more than one
+    copper layer) inside it passes through the plane and is joined to it; an
+    SMD pad is not, and needs a via.
+    """
+    if plane:
+        return len(pin.layers) > 1 and zone.polygon is not None and zone.polygon.contains(pin.location)
+    if zone.layer not in pin.layers or zone.polygon is None:
+        return False
+    if zone.polygon.contains(pin.location):
+        return True
+    box = pin.shape.bounding_box() if pin.shape is not None else None
+    if box is None:
+        return False
+    corners = (box.ll, IntPoint(box.ur.x, box.ll.y), box.ur, IntPoint(box.ll.x, box.ur.y))
+    return any(zone.polygon.contains(c) for c in corners)
+
+
+def _connected_groups(
+    pins: list[Pin], zones: list, planes: frozenset = frozenset()
+) -> list[tuple[list[Pin], list]]:
+    """Pins and zones of one net that copper already joins: a pad in a zone
+    is connected to it, and two zones sharing a pad are one. Only the groups
+    need routing between them. Pin groups come first, in pin order."""
+    parent = list(range(len(pins) + len(zones)))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    for j, zone in enumerate(zones):
+        for i, pin in enumerate(pins):
+            if _pin_touches_zone(pin, zone, id(zone) in planes):
+                parent[find(i)] = find(len(pins) + j)
+    groups: dict[int, tuple[list[Pin], list]] = {}
+    order: list[int] = []
+    for i, pin in enumerate(pins):
+        root = find(i)
+        if root not in groups:
+            groups[root] = ([], [])
+            order.append(root)
+        groups[root][0].append(pin)
+    for j, zone in enumerate(zones):
+        root = find(len(pins) + j)
+        if root not in groups:
+            groups[root] = ([], [])
+            order.append(root)
+        groups[root][1].append(zone)
+    return [groups[r] for r in order]
+
+
 def _split_path(path: list[Node]) -> tuple[list[tuple[int, list[Cell]]], list[Cell]]:
     """Split a node path into per-layer wire segments and via cells."""
     wires: list[tuple[int, list[Cell]]] = []
@@ -490,6 +1055,11 @@ def route_board(
     rip_up: bool = True,
     max_passes: int = 10,
     orthogonal: bool = False,
+    via_half: int | None = None,
+    edge_clearance: int | None = None,
+    resolution: int = 1,
+    heuristic_weight: float = 1.0,
+    seed: int | None = None,
 ) -> RouteResult:
     """Convenience wrapper: build a :class:`GridRouter` and route the board."""
     router = GridRouter(
@@ -501,5 +1071,10 @@ def route_board(
         rip_up=rip_up,
         max_passes=max_passes,
         orthogonal=orthogonal,
+        via_half=via_half,
+        edge_clearance=edge_clearance,
+        resolution=resolution,
+        heuristic_weight=heuristic_weight,
+        seed=seed,
     )
     return router.route()

src/freeroute/route/orders.py

@@ -0,0 +1,67 @@
+"""Route one board in several connection orders at once and keep the best.
+
+Which connection routes first moves the result on a crowded board by several
+connections either way, and no single order wins everywhere. Routing a few
+orders in parallel processes and keeping the one that leaves the fewest
+connections unrouted costs cores, not wall time.
+
+Without a seed the candidates are the default order and seeds 0 to N-2, so the
+result is never worse than a plain run. With seed S they are seeds S to S+N-1.
+Ties go to the earlier candidate, so the choice is deterministic.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ProcessPoolExecutor
+import os
+
+from freeroute.dsn import parse_dsn
+from freeroute.ses import RoutingResult
+
+from .pipeline import build_exact_routing_result, build_routing_result
+
+
+def candidate_seeds(orders: int, seed: int | None = None) -> list[int | None]:
+    orders = max(int(orders), 1)
+    if seed is None:
+        return [None, *range(orders - 1)]
+    return list(range(seed, seed + orders))
+
+
+def score(result: RoutingResult) -> tuple[int, int]:
+    """Connections left open, then those left to a zone fill: lower is better."""
+    missing = sum(1 for u in result.unrouted if not u[3])
+    return missing, len(result.unrouted) - missing
+
+
+def route_once(dsn_text: str, engine: str, options: dict, seed: int | None) -> RoutingResult:
+    dsn = parse_dsn(dsn_text)
+    if engine == "exact":
+        return build_exact_routing_result(dsn, seed=seed, **options)
+    if engine == "grid":
+        return build_routing_result(dsn, seed=seed, **options)
+    raise ValueError(f"routing orders are not supported by the {engine} engine")
+
+
+def best_of_orders(
+    dsn_text: str,
+    engine: str,
+    options: dict,
+    *,
+    orders: int,
+    seed: int | None = None,
+    jobs: int | None = None,
+) -> tuple[RoutingResult, int | None, list[tuple[int | None, tuple[int, int]]]]:
+    """Route ``orders`` orders and return the best result, the seed that made
+    it (None for the default order), and every candidate's seed and score."""
+    seeds = candidate_seeds(orders, seed)
+    if len(seeds) == 1:
+        result = route_once(dsn_text, engine, options, seeds[0])
+        return result, seeds[0], [(seeds[0], score(result))]
+    jobs = max(1, min(jobs or os.cpu_count() or 1, len(seeds)))
+    with ProcessPoolExecutor(jobs) as pool:
+        futures = [pool.submit(route_once, dsn_text, engine, options, s) for s in seeds]
+        results = [f.result() for f in futures]
+    scores = [score(r) for r in results]
+    best = min(range(len(seeds)), key=lambda i: (scores[i], i))
+    return results[best], seeds[best], list(zip(seeds, scores, strict=True))

src/freeroute/route/pipeline.py

@@ -45,12 +45,42 @@ def _via_padstack(dsn: DsnBoard) -> str:
     return dsn.via_padstack_names[0] if dsn.via_padstack_names else _DEFAULT_VIA
 
 
+def _mm_to_board(dsn: DsnBoard, scale: int, value_mm: float | None) -> int | None:
+    """A length in millimetres as board units, or None."""
+    if value_mm is None:
+        return None
+    unit_mm = {"inch": 25.4, "mil": 0.0254, "mm": 1.0, "cm": 10.0, "um": 0.001}[dsn.unit]
+    return round(value_mm / unit_mm * scale)
+
+
+def _via_half_board(dsn: DsnBoard, scale: int) -> int | None:
+    """Half the via pad's size in board units, from the DSN's via padstack.
+
+    None when the DSN names no via padstack with a shape, so the engines fall
+    back to their old estimate.
+    """
+    padstack = dsn.padstack(_via_padstack(dsn))
+    if padstack is None or not padstack.shapes:
+        return None
+    half = 0.0
+    for shape in padstack.shapes:
+        if hasattr(shape, "diameter"):
+            half = max(half, shape.diameter / 2)
+        elif len(getattr(shape, "coords", [])) >= 4:
+            xs, ys = shape.coords[0::2], shape.coords[1::2]
+            half = max(half, (max(xs) - min(xs)) / 2, (max(ys) - min(ys)) / 2)
+    return round(half * scale) or None
+
+
 def route_dsn_board(
     dsn: DsnBoard,
     *,
+    resolution: int = 1,
+    edge_clearance_mm: float | None = None,
     layers: list[int] | None = None,
     rip_up: bool = True,
     max_passes: int = 10,
+    seed: int | None = None,
 ) -> tuple[RouteResult, int, list[str]]:
     """Route a parsed :class:`DsnBoard`; return the board-unit result, the scale,
     and the layer names. ``layers`` restricts routing to those signal-layer
@@ -58,15 +88,20 @@ def route_dsn_board(
     toggles rip-up-and-retry (``False`` = greedy single pass)."""
     board = build_board(dsn)
     scale = max(dsn.resolution.value, 1)
+    edge_clearance_board = _mm_to_board(dsn, scale, edge_clearance_mm)
     width_board = round(_rule_width_dsn(dsn) * scale)
     clearance_board = round(_rule_clearance_dsn(dsn) * scale)
     result = route_board(
         board,
+        resolution=resolution,
+        via_half=_via_half_board(dsn, scale),
+        edge_clearance=edge_clearance_board,
         trace_width=width_board,
         clearance=clearance_board,
         layers=layers,
         rip_up=rip_up,
         max_passes=max_passes,
+        seed=seed,
     )
     return result, scale, [layer.name for layer in dsn.layers]
 
@@ -93,19 +128,26 @@ def _to_routing_result(route, dsn: DsnBoard, scale: int, layer_names: list[str])
         name = numbers_to_names.get(net_no, str(net_no))
         for loc in locations:
             result.add_via(name, RoutedVia(padstack=via_name, x=loc.x / scale, y=loc.y / scale))
+    result.unrouted = [
+        (numbers_to_names.get(n, str(n)), a, b, zone) for n, a, b, zone in getattr(route, "failed", [])
+    ]
     return result
 
 
 def build_routing_result(
     dsn: DsnBoard,
     *,
+    resolution: int = 1,
     layers: list[int] | None = None,
     rip_up: bool = True,
     max_passes: int = 10,
+    edge_clearance_mm: float | None = None,
+    seed: int | None = None,
 ) -> RoutingResult:
     """Route ``dsn`` (grid track) and convert to a DSN-unit RoutingResult."""
     route, scale, layer_names = route_dsn_board(
-        dsn, layers=layers, rip_up=rip_up, max_passes=max_passes
+        dsn, layers=layers, rip_up=rip_up, max_passes=max_passes,
+        edge_clearance_mm=edge_clearance_mm, resolution=resolution, seed=seed,
     )
     return _to_routing_result(route, dsn, scale, layer_names)
 
@@ -113,11 +155,15 @@ def build_routing_result(
 def route_dsn_board_exact(
     dsn: DsnBoard,
     *,
+    resolution: int = 1,
+    heuristic_weight: float = 1.0,
+    edge_clearance_mm: float | None = None,
     layers: list[int] | None = None,
     max_passes: int = 10,
     rip_up: bool = True,
     shove: bool = False,
     diagonal: bool = False,
+    seed: int | None = None,
 ) -> tuple[ExactRouteResult, int, list[str]]:
     """Route a parsed :class:`DsnBoard` with the exact-geometry (orthogonal,
     DRC-verified) track; return the exact result, the scale, and layer names.
@@ -126,10 +172,15 @@ def route_dsn_board_exact(
     the 45-degree recovery pass for still-dropped 2-pin nets."""
     board = build_board(dsn)
     scale = max(dsn.resolution.value, 1)
+    edge_clearance_board = _mm_to_board(dsn, scale, edge_clearance_mm)
     width_board = round(_rule_width_dsn(dsn) * scale)
     clearance_board = round(_rule_clearance_dsn(dsn) * scale)
     exact = route_board_exact(
         board,
+        resolution=resolution,
+        heuristic_weight=heuristic_weight,
+        via_half=_via_half_board(dsn, scale),
+        edge_clearance=edge_clearance_board,
         trace_width=width_board,
         clearance=clearance_board,
         layers=layers,
@@ -137,6 +188,7 @@ def route_dsn_board_exact(
         rip_up=rip_up,
         shove=shove,
         diagonal=diagonal,
+        seed=seed,
     )
     return exact, scale, [layer.name for layer in dsn.layers]
 
@@ -144,11 +196,15 @@ def route_dsn_board_exact(
 def build_exact_routing_result(
     dsn: DsnBoard,
     *,
+    resolution: int = 1,
+    heuristic_weight: float = 1.0,
     layers: list[int] | None = None,
     shove: bool = False,
     diagonal: bool = False,
     rip_up: bool = True,
     max_passes: int = 10,
+    edge_clearance_mm: float | None = None,
+    seed: int | None = None,
 ) -> RoutingResult:
     """Route ``dsn`` (exact track) and convert to a DSN-unit RoutingResult."""
     exact, scale, layer_names = route_dsn_board_exact(
@@ -158,12 +214,21 @@ def build_exact_routing_result(
         diagonal=diagonal,
         rip_up=rip_up,
         max_passes=max_passes,
+        edge_clearance_mm=edge_clearance_mm,
+        resolution=resolution,
+        heuristic_weight=heuristic_weight,
+        seed=seed,
     )
     return _to_routing_result(exact.result, dsn, scale, layer_names)
 
 
 def route_dsn_board_rooms(
-    dsn: DsnBoard, *, layers: list[int] | None = None, shove: bool = False, pack: bool = False
+    dsn: DsnBoard,
+    *,
+    layers: list[int] | None = None,
+    shove: bool = False,
+    pack: bool = False,
+    edge_clearance_mm: float | None = None,
 ) -> tuple[ExactRouteResult, int, list[str]]:
     """Route a parsed :class:`DsnBoard` with the continuous expansion-room track;
     return the result, the scale, and layer names. ``shove`` enables occupancy-
@@ -171,10 +236,13 @@ def route_dsn_board_rooms(
     ``pack`` enables the coordinated multi-trace channel packer."""
     board = build_board(dsn)
     scale = max(dsn.resolution.value, 1)
+    edge_clearance_board = _mm_to_board(dsn, scale, edge_clearance_mm)
     width_board = round(_rule_width_dsn(dsn) * scale)
     clearance_board = round(_rule_clearance_dsn(dsn) * scale)
     rooms = route_board_rooms(
         board,
+        via_half=_via_half_board(dsn, scale),
+        edge_clearance=edge_clearance_board,
         trace_width=width_board,
         clearance=clearance_board,
         layers=layers,
@@ -185,10 +253,17 @@ def route_dsn_board_rooms(
 
 
 def build_rooms_routing_result(
-    dsn: DsnBoard, *, layers: list[int] | None = None, shove: bool = False, pack: bool = False
+    dsn: DsnBoard,
+    *,
+    layers: list[int] | None = None,
+    shove: bool = False,
+    pack: bool = False,
+    edge_clearance_mm: float | None = None,
 ) -> RoutingResult:
     """Route ``dsn`` (room track) and convert to a DSN-unit RoutingResult."""
-    rooms, scale, layer_names = route_dsn_board_rooms(dsn, layers=layers, shove=shove, pack=pack)
+    rooms, scale, layer_names = route_dsn_board_rooms(
+        dsn, layers=layers, shove=shove, pack=pack, edge_clearance_mm=edge_clearance_mm
+    )
     return _to_routing_result(rooms.result, dsn, scale, layer_names)
 
 
@@ -200,6 +275,8 @@ def route(
     shove: bool = False,
     pack: bool = False,
     diagonal: bool = False,
+    edge_clearance_mm: float | None = None,
+    resolution: int = 1,
 ) -> str:
     """Route a Specctra DSN string and return the routed SES string.
 
@@ -213,9 +290,16 @@ def route(
     """
     dsn = parse_dsn(dsn_text)
     if engine == "exact":
-        result = build_exact_routing_result(dsn, layers=layers, shove=shove, diagonal=diagonal)
+        result = build_exact_routing_result(
+            dsn, layers=layers, shove=shove, diagonal=diagonal,
+            edge_clearance_mm=edge_clearance_mm, resolution=resolution,
+        )
     elif engine == "room":
-        result = build_rooms_routing_result(dsn, layers=layers, shove=shove, pack=pack)
+        result = build_rooms_routing_result(
+            dsn, layers=layers, shove=shove, pack=pack, edge_clearance_mm=edge_clearance_mm
+        )
     else:
-        result = build_routing_result(dsn, layers=layers)
+        result = build_routing_result(
+            dsn, layers=layers, edge_clearance_mm=edge_clearance_mm, resolution=resolution
+        )
     return write_ses(dsn, result)

src/freeroute/route/room_router.py

@@ -471,6 +471,8 @@ def route_board_rooms(
     pack: bool = False,
     max_shove_depth: int = 5,
     shove_cap: int = 3,
+    via_half: int | None = None,
+    edge_clearance: int | None = None,
 ) -> ExactRouteResult:
     """Route ``board`` with the continuous expansion-room track.
 
@@ -494,6 +496,10 @@ def route_board_rooms(
         i for i, layer in enumerate(board.layer_structure.arr) if layer.is_signal
     ]
     half_width = max(trace_width // 2, 1)
+    # half the via pad's size: a via is not a trace, and sizing it like one
+    # let routes pass within a via's real copper
+    via_half = via_half or half_width
+    edge = (board.outline, 0 if edge_clearance is None else edge_clearance)
     margin = clearance + half_width
     outline = board.bounding_box
 
@@ -537,7 +543,7 @@ def route_board_rooms(
             via_layers,
             accepted,
             shove,
-        )
+        via_half=via_half, edge=edge)
     for net_no in sorted(_routable_nets(board, signal_layers)):
         if net_no in packed:
             continue
@@ -562,7 +568,7 @@ def route_board_rooms(
                 accepted,
                 max_shove_depth,
                 shove_cap,
-            )
+            via_half=via_half, edge=edge)
 
     drc_clean = tree.has_violation(clearance) is None
     return ExactRouteResult(result=result, tree=tree, drc_clean=drc_clean, shoves=shoves)
@@ -587,6 +593,8 @@ def _route_connection(
     accepted=None,
     max_shove_depth=5,
     shove_cap=3,
+    via_half=None,
+    edge=None,
 ):
     rooms_by_layer = {
         layer: _free_rooms(tree, outline, layer, net_no, margin, half_width)
@@ -607,7 +615,7 @@ def _route_connection(
 
     if realized is not None:
         wires, vias = realized
-        boxes = _collect_boxes(wires, vias, half_width, via_layers, outline)
+        boxes = _collect_boxes(wires, vias, half_width, via_layers, outline, via_half=via_half, edge=edge)
         if boxes is not None and not any(
             tree.clearance_conflict(box, net_no, layer, clearance)
             for box, box_layers in boxes
@@ -615,7 +623,7 @@ def _route_connection(
         ):
             _commit(
                 net_no, wires, vias, tree, result, owner, half_width, via_layers, shove, accepted
-            )
+            , via_half=via_half)
             return 0
 
     # the net would be dropped: try a transactional shove-in-rooms recovery
@@ -634,11 +642,12 @@ def _route_connection(
             clearance,
             max_shove_depth,
             shove_cap,
-        )
+        via_half=via_half, edge=edge)
     return 0
 
 
-def _collect_boxes(wires, vias, half_width, via_layers, outline):
+def _collect_boxes(wires, vias, half_width, via_layers, outline, via_half=None, edge=None):
+    via_half = via_half or half_width
     """The ``(box, layers)`` copper tiles of a realized route, or ``None`` if any
     tile leaves the board outline (the same early-out as the old inline check)."""
     boxes: list[tuple[IntBox, frozenset[int]]] = []
@@ -646,16 +655,21 @@ def _collect_boxes(wires, vias, half_width, via_layers, outline):
         for box in PolylineShape(Polyline(corners), half_width).tiles():
             if not outline.contains_box(box):
                 return None
+            if edge is not None and edge[0] is not None and not edge[0].box_clear(box, edge[1]):
+                return None
             boxes.append((box, frozenset({layer})))
     for loc in vias:
         vbox = IntBox(
-            loc.x - half_width, loc.y - half_width, loc.x + half_width, loc.y + half_width
+            loc.x - via_half, loc.y - via_half, loc.x + via_half, loc.y + via_half
         )
         boxes.append((vbox, via_layers))
     return boxes
 
 
-def _commit(net_no, wires, vias, tree, result, owner, half_width, via_layers, shove, accepted):
+def _commit(
+    net_no, wires, vias, tree, result, owner, half_width, via_layers, shove, accepted, via_half=None
+):
+    via_half = via_half or half_width
     """Insert a verified route's copper and record it in the routed output.
 
     With ``shove=False`` this is the foundation router's exact commit sequence.
@@ -668,7 +682,7 @@ def _commit(net_no, wires, vias, tree, result, owner, half_width, via_layers, sh
                 tree.insert(TreeShape(next(owner), net_no, frozenset({layer}), box, routed=True))
         for loc in vias:
             vbox = IntBox(
-                loc.x - half_width, loc.y - half_width, loc.x + half_width, loc.y + half_width
+                loc.x - via_half, loc.y - via_half, loc.x + via_half, loc.y + via_half
             )
             tree.insert(TreeShape(next(owner), net_no, via_layers, vbox, routed=True))
         for layer, corners in wires:
@@ -693,7 +707,7 @@ def _commit(net_no, wires, vias, tree, result, owner, half_width, via_layers, sh
         acc.wire_owners.append(w_owners)
     for loc in vias:
         vbox = IntBox(
-            loc.x - half_width, loc.y - half_width, loc.x + half_width, loc.y + half_width
+            loc.x - via_half, loc.y - via_half, loc.x + via_half, loc.y + via_half
         )
         oid = next(owner)
         tree.insert(TreeShape(oid, net_no, via_layers, vbox, routed=True))
@@ -854,6 +868,8 @@ def _pack_channels(
     via_layers,
     accepted,
     shove,
+    via_half=None,
+    edge=None,
 ) -> set[int]:
     """Coordinated multi-trace channel packing (opt-in pre-pass).
 
@@ -922,7 +938,7 @@ def _pack_channels(
                     spacing_min,
                     via_layers,
                     outline,
-                )
+                via_half=via_half, edge=edge)
                 if placed is None:
                     continue  # could not pack every member cleanly -> leave to greedy
                 for net_no, wires in placed:
@@ -937,7 +953,7 @@ def _pack_channels(
                         via_layers,
                         shove,
                         accepted,
-                    )
+                    via_half=via_half)
                     routed.add(net_no)
     return routed
 
@@ -958,6 +974,8 @@ def _pack_group(
     spacing_min,
     via_layers,
     outline,
+    via_half=None,
+    edge=None,
 ):
     """Assign parallel lanes + staggered fan-in trunks to every net crossing one
     gap, and return ``[(net_no, wires), ...]`` if ALL of them realize exactly
@@ -1014,7 +1032,7 @@ def _pack_group(
         if len(corners) < 2:
             return None
         wires = [(layer, corners)]
-        boxes = _collect_boxes(wires, [], half_width, via_layers, outline)
+        boxes = _collect_boxes(wires, [], half_width, via_layers, outline, via_half=via_half, edge=edge)
         if boxes is None:
             return None
         if any(
@@ -1049,6 +1067,8 @@ def _shove_recover_room(
     clearance,
     max_shove_depth,
     shove_cap,
+    via_half=None,
+    edge=None,
 ) -> int:
     """Recover a dropped net by nudging the committed trace(s) that block it.
 

src/freeroute/ses/model.py

@@ -57,6 +57,9 @@ class RoutingResult:
     """The complete routing output for a board, grouped by net."""
 
     nets: list[RoutedNet] = field(default_factory=list)
+    #: connections the router could not make: (net name, one end, other end,
+    #: the zone both ends sit in or "") -- a zone's fill may join the latter
+    unrouted: list[tuple[str, str, str, str]] = field(default_factory=list)
 
     def net(self, name: str, *, create: bool = False) -> RoutedNet | None:
         """Return the :class:`RoutedNet` with ``name`` (creating it if asked)."""

tests/board/test_build.py

@@ -17,6 +17,7 @@ import pytest
 
 from freeroute.board import BasicBoard, ObstacleArea, Pin, build_board
 from freeroute.dsn import parse_dsn
+from freeroute.geometry import IntPoint
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
@@ -62,11 +63,20 @@ def test_pin_count_matches_placement(dsn, board):
 
 
 def test_obstacle_count_matches_keepouts(dsn, board):
-    # each keepout expands to one obstacle per applicable layer; with no keepouts
-    # in this fixture the count is zero
-    assert len(board.get_obstacle_areas()) >= len(dsn.keepouts)
+    # Board-level keepouts plus every placed instance of a footprint-level one.
+    # This fixture has none of the first and six plated mounting holes, whose
+    # copper KiCad exports as a keepout on each layer.
+    images = {img.name: img for img in dsn.images}
+    placed = 0
+    for placement in dsn.placements:
+        image = images.get(placement.lib_name)
+        if image is None:
+            continue
+        per_part = len(image.keepouts) + len(image.via_keepouts) + len(image.wire_keepouts)
+        placed += per_part * sum(p.x is not None for p in placement.places)
     assert len(dsn.keepouts) == 0
-    assert board.get_obstacle_areas() == []
+    assert placed == 12
+    assert len(board.get_obstacle_areas()) == placed
 
 
 # --- per-item invariants ----------------------------------------------------
@@ -129,3 +139,118 @@ def test_board_net_set_covers_oracle_routed_nets(board):
     assert routed, "oracle produced no routed nets"
     # every net the reference router routed exists on our constructed board
     assert routed <= board.nets.names()
+
+
+# --- keepouts as KiCad exports them ------------------------------------------
+# Found on the TerraHawk charge-node boards (2026-09-27): a no-track ring along
+# the board edge arrives as one keyhole polygon, "keep router off" rule areas
+# arrive as wire_keepout, and neither may block the board's interior.
+
+_RING_DSN = """(pcb ring (parser) (resolution um 10) (unit um)
+  (structure
+    (layer F.Cu (type signal)) (layer B.Cu (type signal))
+    (boundary (path pcb 0  0 0  40000 0  40000 -30000  0 -30000  0 0))
+    (keepout "" (polygon F.Cu 0  0 0  40000 0  40000 -30000  0 -30000  0 0
+      500 -500  500 -29500  39500 -29500  39500 -500  500 -500  0 0))
+    (wire_keepout "pour" (polygon F.Cu 0  10000 -10000  20000 -10000  20000 -20000  10000 -20000))
+    (place_keepout "courtyard" (polygon F.Cu 0  30000 -10000  35000 -10000  35000 -20000  30000 -20000))
+    (rule (width 250) (clearance 150)))
+  (placement) (library) (network))"""
+
+
+def _areas(dsn_text):
+    return build_board(parse_dsn(dsn_text)).get_obstacle_areas()
+
+
+def _blocked(areas, x_um, y_um):
+    p = IntPoint(x_um * 10, y_um * 10)
+    return any(t.contains(p) for a in areas for t in a.tiles)
+
+
+def test_keyhole_ring_keepout_blocks_only_the_border():
+    areas = _areas(_RING_DSN)
+    assert _blocked(areas, 200, -15000)          # inside the 0.5 mm edge strip
+    assert not _blocked(areas, 5000, -5000)      # open board interior
+
+
+def test_wire_keepout_is_read_and_blocks_its_area():
+    dsn = parse_dsn(_RING_DSN)
+    assert [k.kind for k in dsn.keepouts].count("wire_keepout") == 1
+    assert _blocked(_areas(_RING_DSN), 15000, -15000)
+
+
+def test_place_keepout_does_not_block_routing():
+    assert not _blocked(_areas(_RING_DSN), 32500, -15000)
+
+
+def test_grid_router_leaves_the_interior_of_a_ring_keepout_open():
+    from freeroute.route.pipeline import route_dsn_board
+
+    ring_only = "\n".join(
+        line for line in _RING_DSN.splitlines() if "wire_keepout" not in line
+    ).replace(
+        "(placement) (library) (network)",
+        "(placement (component P (place P1 5000 -15000 front 0) (place P2 35000 -15000 front 0)))\n"
+        "  (library (image P (pin pad 1 0 0)) (padstack pad (shape (circle F.Cu 600)) (attach off)))\n"
+        "  (network (net N (pins P1-1 P2-1)))",
+    )
+    result, _, _ = route_dsn_board(parse_dsn(ring_only), max_passes=2)
+    assert result.routed_net_numbers
+
+
+# --- pads placed as KiCad places them (2026-09-27, TerraHawk rc4) ------------
+
+_PAD_DSN = """(pcb pads (parser) (resolution um 10) (unit um)
+  (structure
+    (layer F.Cu (type signal)) (layer B.Cu (type signal))
+    (boundary (path pcb 0  0 0  40000 0  40000 -30000  0 -30000  0 0))
+    (via "Via[0-1]_600:300_um")
+    (rule (width 250) (clearance 150)))
+  (placement
+    (component R (place TOP 10000 -10000 front 0) (place BOT 20000 -10000 back 0)
+                 (place ROT 30000 -10000 front 90)))
+  (library
+    (image R (pin rect 1 -1000 0))
+    (padstack rect (shape (rect F.Cu -400 -250 400 250)) (attach off))
+    (padstack "Via[0-1]_600:300_um" (shape (circle F.Cu 600)) (shape (circle B.Cu 600)) (attach off)))
+  (network))"""
+
+
+def _pins_by_ref(text):
+    board = build_board(parse_dsn(text))
+    return {p.component_ref: p for p in board.get_pins()}, board
+
+
+def test_back_side_pad_moves_to_the_bottom_layer():
+    pins, board = _pins_by_ref(_PAD_DSN)
+    names = [layer.name for layer in board.layer_structure.arr]
+    assert [names[i] for i in pins["TOP"].layers] == ["F.Cu"]
+    assert [names[i] for i in pins["BOT"].layers] == ["B.Cu"]
+
+
+def test_back_side_pin_offset_is_mirrored():
+    pins, _ = _pins_by_ref(_PAD_DSN)
+    assert pins["TOP"].location.x == (10000 - 1000) * 10
+    assert pins["BOT"].location.x == (20000 + 1000) * 10
+
+
+def test_rotated_part_rotates_its_pad_outline():
+    pins, _ = _pins_by_ref(_PAD_DSN)
+    flat = pins["TOP"].shape.bounding_box()
+    turned = pins["ROT"].shape.bounding_box()
+    assert (flat.ur.x - flat.ll.x, flat.ur.y - flat.ll.y) == (8000, 5000)
+    assert (turned.ur.x - turned.ll.x, turned.ur.y - turned.ll.y) == (5000, 8000)
+
+
+def test_oval_pad_keeps_its_width():
+    oval = _PAD_DSN.replace("(shape (rect F.Cu -400 -250 400 250))", "(shape (path F.Cu 500  -300 0  300 0))")
+    pins, _ = _pins_by_ref(oval)
+    box = pins["TOP"].shape.bounding_box()
+    assert box.ur.y - box.ll.y == 5000       # the aperture, not a zero-height line
+    assert box.ur.x - box.ll.x == 11000      # centreline 600 um plus the aperture
+
+
+def test_via_size_comes_from_the_via_padstack():
+    from freeroute.route.pipeline import _via_half_board
+
+    assert _via_half_board(parse_dsn(_PAD_DSN), 10) == 3000   # 0.6 mm via, board units

tests/oracle.py

@@ -111,12 +111,17 @@ def route_dsn(dsn_path: str | Path, *, max_passes: int = 6, timeout: int = 180)
     with tempfile.NamedTemporaryFile(suffix=".ses", delete=False) as tmp:
         out_path = tmp.name
     try:
+        # Headless: without these the JAR opens its GUI on the developer's
+        # desktop for every oracle run.
+        env = {k: v for k, v in os.environ.items() if k not in ("DISPLAY", "WAYLAND_DISPLAY")}
         subprocess.run(
-            [JAVA, "-jar", JAR, "-de", str(dsn_path), "-do", out_path, "-mp", str(max_passes)],
+            [JAVA, "-Djava.awt.headless=true", "-jar", JAR, "-de", str(dsn_path),
+             "-do", out_path, "-mp", str(max_passes), "--gui.enabled=false"],
             capture_output=True,
             text=True,
             timeout=timeout,
             check=False,
+            env=env,
         )
         text = Path(out_path).read_text()
     finally:

tests/route/test_orders.py

@@ -0,0 +1,44 @@
+"""--orders: route several connection orders and keep the best."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from freeroute.cli import main
+from freeroute.route.orders import best_of_orders, candidate_seeds, route_once, score
+
+FIXTURES = Path(__file__).resolve().parent.parent / "dsn" / "fixtures"
+# Greedy (no rip-up), the default order strands a net here and seeds 1 to 3 do not.
+RIPUP = (FIXTURES / "ripup_needed.dsn").read_text()
+GREEDY = {"rip_up": False}
+
+
+def test_the_default_order_is_always_a_candidate_without_a_seed():
+    assert candidate_seeds(1) == [None]
+    assert candidate_seeds(4) == [None, 0, 1, 2]
+    assert candidate_seeds(3, seed=7) == [7, 8, 9]
+
+
+def test_keeps_the_order_that_leaves_the_fewest_unrouted():
+    assert score(route_once(RIPUP, "grid", GREEDY, None)) == (1, 0)
+    result, kept, tried = best_of_orders(RIPUP, "grid", GREEDY, orders=3, jobs=2)
+    assert kept == 1
+    assert score(result) == (0, 0)
+    assert tried == [(None, (1, 0)), (0, (1, 0)), (1, (0, 0))]
+
+
+def test_ties_go_to_the_earlier_candidate():
+    # every order routes this board fully, so the default order is kept
+    _, kept, tried = best_of_orders(RIPUP, "grid", {}, orders=3, jobs=3)
+    assert kept is None
+    assert all(s == (0, 0) for _, s in tried)
+
+
+def test_cli_orders_writes_the_best_session(tmp_path, capsys):
+    out = tmp_path / "best.ses"
+    rc = main([str(FIXTURES / "ripup_needed.dsn"), "--no-rip-up", "--orders", "3", "-do", str(out)])
+    assert rc == 0
+    err = capsys.readouterr().err
+    assert "tried 3 orders, kept --seed 1" in err
+    assert "not routed" not in err
+    assert out.read_text().startswith("(session")

tests/route/test_real_board_geometry.py

@@ -0,0 +1,213 @@
+"""Routing behaviours found on the TerraHawk rc4 boards (2026-09-27)."""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+
+from freeroute.board import build_board
+from freeroute.dsn import parse_dsn
+from freeroute.route.pipeline import route_dsn_board_exact
+
+# 20 x 20 mm board whose corners are rounded with a 3 mm radius, as polylines
+_R = 3000.0
+_arc = [(_R - _R * math.cos(math.radians(a)), _R - _R * math.sin(math.radians(a))) for a in range(0, 91, 15)]
+
+
+def _outline_coords():
+    pts = []
+    for cx, cy, sx, sy in ((0, 0, 1, 1), (20000, 0, -1, 1), (20000, -20000, -1, -1), (0, -20000, 1, -1)):
+        corner = [(cx + sx * x, cy - sy * y) for x, y in _arc]
+        pts.extend(corner if sx * sy > 0 else corner[::-1])
+    return " ".join(f"{x:.1f} {y:.1f}" for x, y in pts)
+
+
+def _dsn(placement, network, extra=""):
+    return f"""(pcb t (parser) (resolution um 10) (unit um)
+  (structure (layer F.Cu (type signal)) (layer B.Cu (type signal))
+    (boundary (path pcb 0 {_outline_coords()}))
+    (via "Via[0-1]_600:300_um") (rule (width 250) (clearance 150)) {extra})
+  (placement {placement})
+  (library (image P (pin pad 1 0 0))
+    (padstack pad (shape (rect F.Cu -150 -500 150 500)) (attach off))
+    (padstack "Via[0-1]_600:300_um" (shape (circle F.Cu 600)) (shape (circle B.Cu 600)) (attach off)))
+  (network {network}))"""
+
+
+def test_routes_keep_edge_clearance_at_a_rounded_corner():
+    # two pads near the top-left corner: the direct path cuts the corner arc
+    text = _dsn("(component P (place A 1800 -6000 front 0) (place B 6000 -1800 front 90))",
+                "(net N (pins A-1 B-1))")
+    dsn = parse_dsn(text)
+    result, scale, _ = route_dsn_board_exact(dsn, edge_clearance_mm=0.5)
+    assert result.routed_net_numbers
+    outline = build_board(dsn).outline
+    half = 125 * scale
+    for segs in result.result.wires.values():
+        for _layer, pts in segs:
+            for p in pts:
+                # every trace point, plus half the trace, keeps 0.5 mm to the edge
+                assert outline.edge_distance(p) >= half + 500 * scale - 1
+
+
+@pytest.mark.parametrize(("resolution", "escape"), [(1, 2), (4, 5)])
+def test_every_pin_of_a_half_millimetre_pitch_row_escapes(resolution, escape):
+    # Five 0.3 mm pads at 0.5 mm pitch, each wired to its own pad 8 mm away.
+    # Between two neighbours a trace's centre has a legal band only 0.15 mm
+    # wide. At resolution 1 the 0.4 mm grid misses most bands; at 4 its
+    # 0.1 mm columns cannot, and every pin gets out, as the JAR manages.
+    places = " ".join(f"(place R{i} {6000 + 500 * i} -6000 front 0)" for i in range(5))
+    places += " " + " ".join(f"(place F{i} {6000 + 500 * i} -14000 front 0)" for i in range(5))
+    nets = " ".join(f"(net N{i} (pins R{i}-1 F{i}-1))" for i in range(5))
+    result, _, _ = route_dsn_board_exact(
+        parse_dsn(_dsn(f"(component P {places})", nets)), resolution=resolution
+    )
+    assert len(result.routed_net_numbers) == escape
+
+
+def test_resolution_one_has_no_halo_so_the_grid_is_unchanged():
+    from freeroute.route.grid_router import GridRouter
+
+    board = build_board(parse_dsn(_dsn("", "")))
+    assert GridRouter(board, trace_width=2500, clearance=1500)._halo_offsets == []
+    fine = GridRouter(board, trace_width=2500, clearance=1500, resolution=2)
+    assert fine.step == 2000 and (1, 0) in fine._halo_offsets and (2, 0) not in fine._halo_offsets
+
+
+def test_heuristic_weight_bounds_route_length():
+    # weighted A* may take a longer route, but never more than W times the shortest
+    places = "(place A 3000 -3000 front 0) (place B 17000 -17000 front 0)"
+
+    def length(weight):
+        result, _, _ = route_dsn_board_exact(
+            parse_dsn(_dsn(f"(component P {places})", "(net N (pins A-1 B-1))")),
+            heuristic_weight=weight,
+        )
+        return sum(
+            math.hypot(q.x - p.x, q.y - p.y)
+            for segs in result.result.wires.values()
+            for _layer, pts in segs
+            for p, q in zip(pts, pts[1:], strict=False)
+        )
+
+    shortest = length(1.0)
+    assert shortest > 0
+    assert length(2.0) <= 2.0 * shortest
+
+
+# --- copper zones (DSN planes) -----------------------------------------------
+# rc4 power stage: pads inside "keep router off" pours connect through the pour,
+# and freeroute, not knowing zones, dropped every such connection.
+
+_ZONE = "(plane N (polygon F.Cu 0  4000 -4000  10000 -4000  10000 -10000  4000 -10000  4000 -4000))"
+_NO_TRACKS = "(wire_keepout \"pour\" (polygon F.Cu 0  4000 -4000  10000 -4000  10000 -10000  4000 -10000))"
+
+
+def _zone_board():
+    places = "(place P1 5500 -7000 front 0) (place P2 8500 -7000 front 0) (place P3 16000 -16000 front 0)"
+    return parse_dsn(_dsn(f"(component P {places})", "(net N (pins P1-1 P2-1 P3-1))", _ZONE + " " + _NO_TRACKS))
+
+
+def test_planes_are_read_and_are_not_obstacles():
+    dsn = _zone_board()
+    assert [(p.net, p.shape.layer) for p in dsn.planes] == [("N", "F.Cu")]
+    board = build_board(dsn)
+    assert len(board.get_conduction_areas()) == 1
+    assert all(not a.is_obstacle() or a.name == "pour" for a in board.get_obstacle_areas())
+
+
+def test_pads_in_one_zone_need_no_route_between_them():
+    from freeroute.route.grid_router import _connected_groups
+
+    board = build_board(_zone_board())
+    pins = sorted(board.get_pins(), key=lambda p: p.component_ref)
+    groups = _connected_groups(pins, board.get_conduction_areas())
+    assert [sorted(p.component_ref for p in g[0]) for g in groups] == [["P1", "P2"], ["P3"]]
+
+
+def test_a_pad_reaches_a_zone_under_a_no_tracks_area_by_a_via():
+    dsn = _zone_board()
+    result, scale, names = route_dsn_board_exact(dsn)
+    net = next(iter(result.routed_net_numbers))
+    assert result.result.vias.get(net)  # it had to drop into the zone
+    board = build_board(dsn)
+    pour = next(a for a in board.get_obstacle_areas() if a.name == "pour")
+    f_cu = names.index("F.Cu")
+    for layer, pts in result.result.wires[net]:
+        if layer == f_cu:  # no track runs inside the no-tracks area
+            assert not any(t.contains(p) and not t.bounding_box().is_empty()
+                           for t in pour.tiles for p in pts[1:-1])
+
+
+def test_a_pour_other_nets_can_cross_is_not_trusted_to_connect():
+    # the same zone with no no-tracks area over it: its fill could be split by
+    # other nets' tracks, so its pads are joined by routing, not assumed
+    places = "(place P1 5500 -7000 front 0) (place P2 8500 -7000 front 0)"
+    dsn = parse_dsn(_dsn(f"(component P {places})", "(net N (pins P1-1 P2-1))", _ZONE))
+    result, _, _ = route_dsn_board_exact(dsn)
+    net = next(iter(result.routed_net_numbers))
+    assert result.result.wires.get(net)  # P1 and P2 got a track between them
+
+
+def test_cli_names_the_connections_it_could_not_route(tmp_path, capsys):
+    # a keepout wall across the board on both layers: A and B cannot be joined
+    from freeroute.cli import main
+
+    wall = " ".join(
+        f"(keepout \"wall\" (polygon {layer} 0  9000 1000  11000 1000  11000 -21000  9000 -21000))"
+        for layer in ("F.Cu", "B.Cu")
+    )
+    dsn = tmp_path / "wall.dsn"
+    dsn.write_text(_dsn("(component P (place A 4000 -10000 front 0) (place B 16000 -10000 front 0))",
+                        "(net N (pins A-1 B-1))", wall))
+    assert main([str(dsn), "--engine", "exact", "-do", str(tmp_path / "out.ses")]) == 0
+    err = capsys.readouterr().err
+    assert "1 connection(s) not routed" in err and "N: A-1 to B-1" in err
+
+
+# --- inner plane layers (a 4-layer board with a GND plane on In1.Cu) --------
+
+def _four_layer_dsn():
+    return """(pcb four (parser) (resolution um 10) (unit um)
+  (structure
+    (layer F.Cu (type signal)) (layer In1.Cu (type power))
+    (layer In2.Cu (type power)) (layer B.Cu (type signal))
+    (boundary (path pcb 0  0 0  30000 0  30000 -30000  0 -30000  0 0))
+    (plane GND (polygon In1.Cu 0  500 -500  29500 -500  29500 -29500  500 -29500  500 -500))
+    (via "Via[0-3]_600:300_um") (rule (width 250) (clearance 150)))
+  (placement
+    (component S (place G1 5000 -5000 front 0) (place G2 25000 -5000 front 0)
+                 (place G3 15000 -25000 front 0) (place A 5000 -15000 front 0) (place B 25000 -15000 front 0))
+    (component T (place GT 15000 -15000 front 0)))
+  (library
+    (image S (pin smd 1 0 0))
+    (image T (pin tht 1 0 0))
+    (padstack smd (shape (rect F.Cu -300 -300 300 300)) (attach off))
+    (padstack tht (shape (circle F.Cu 1000)) (shape (circle B.Cu 1000)) (attach off))
+    (padstack "Via[0-3]_600:300_um" (shape (circle F.Cu 600)) (shape (circle B.Cu 600)) (attach off)))
+  (network (net GND (pins G1-1 G2-1 G3-1 GT-1)) (net SIG (pins A-1 B-1))))"""
+
+
+def test_smd_pads_reach_an_inner_plane_by_their_own_via():
+    dsn = parse_dsn(_four_layer_dsn())
+    result, scale, names = route_dsn_board_exact(dsn)
+    gnd = next(i + 1 for i, n in enumerate(dsn.nets) if n.name == "GND")
+    sig = next(i + 1 for i, n in enumerate(dsn.nets) if n.name == "SIG")
+    assert len(result.result.vias.get(gnd, [])) == 3  # one per SMD pad, none for the THT pad
+    for _layer, pts in result.result.wires.get(gnd, []):  # stubs, not tracks across the board
+        length = sum(abs(q.x - p.x) + abs(q.y - p.y) for p, q in zip(pts, pts[1:], strict=False))
+        assert length < 3000 * scale  # under 3 mm: a stub to its via
+    assert sig in result.result.routed_net_numbers  # signals still route on the outer layers
+    assert all(names[layer] in ("F.Cu", "B.Cu") for segs in result.result.wires.values() for layer, _ in segs)
+
+
+def test_a_through_hole_pad_inside_a_plane_needs_no_route():
+    from freeroute.route.grid_router import _connected_groups
+
+    board = build_board(parse_dsn(_four_layer_dsn()))
+    plane = [z for z in board.get_conduction_areas() if z.name == "GND"]
+    gnd_pins = [p for p in board.get_pins() if p.component_ref in ("G1", "G2", "G3", "GT")]
+    groups = _connected_groups(gnd_pins, plane, frozenset(id(z) for z in plane))
+    hub = next(g for g in groups if g[1])
+    assert [p.component_ref for p in hub[0]] == ["GT"]

tests/route/test_router.py

@@ -264,6 +264,19 @@ def test_larger_board_still_connects_its_multipin_nets():
     assert len(result.routed_net_numbers) == multi_pin == 4
 
 
+def test_a_seed_is_repeatable_and_does_change_the_order():
+    # The benchmark samples seeds to measure how much a result owes to the
+    # routing order. A seed that changed nothing would make every sample the
+    # same run and report no spread at all.
+    text = (FIXTURES / "kicad_routable.dsn").read_text()
+    default = _wire_key(route_dsn_board(parse_dsn(text))[0])
+    runs = {s: route_dsn_board(parse_dsn(text), seed=s)[0] for s in range(4)}
+    again = route_dsn_board(parse_dsn(text), seed=1)[0]
+    assert _wire_key(again) == _wire_key(runs[1])
+    assert any(_wire_key(r) != default for r in runs.values())
+    assert all(r.unrouted == 0 for r in runs.values())
+
+
 # --- oracle parity ----------------------------------------------------------
 
 

tests/test_cli.py

@@ -154,6 +154,8 @@ def test_cli_supported_combinations_are_accepted(tmp_path):
         "diagonal": ["--diagonal"],
         "rip_up": ["--no-rip-up"],
         "max_passes": ["-mp", "4"],
+        "seed": ["--seed", "3"],
+        "orders": ["--orders", "2"],
     }
     for engine, options in ENGINE_OPTIONS.items():
         for option in options:

uv.lock

@@ -128,7 +128,7 @@ wheels = [
 
 [[package]]
 name = "freeroute"
-version = "0.1.0"
+version = "2026.7.14"
 source = { editable = "." }
 
 [package.dev-dependencies]