Test: a pad inside a via keepout reaches the plane past it

A start that was already a plane end joined the plane at once, with no
check that its via fits: under a sensor's via keepout the via went in
the pad and the exact check refused it. A via leaving or reaching a
walled-in pin goes in that pin's pad, but was only checked at the grid
cell's centre; it is now checked exactly at the pin against via
keepouts and other nets' pads and fixed copper.

.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
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import json
+import math
+import os
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+
+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())

bench/diagnose.py

@@ -0,0 +1,266 @@
+"""Why did each connection fail? Sort the failures of one exact-engine run.
+
+    uv run python bench/diagnose.py board.dsn --edge-clearance 0.5 [--json out.json]
+
+Every connection the exact engine leaves unrouted lands in one bucket:
+
+rejected    the grid routed it, the exact geometry check refused its copper
+alone       it cannot be routed even on a board with no other routes: the
+            pads, keepouts or the grid itself are the limit, not congestion
+walled-in   in the routed board one of its pins has no way out: a flood from
+            the pin's end cells through free cells stops short (pin access)
+congestion  both pins can get out, but no free path joins them
+
+The board state is the one the result came from (the best pass), rebuilt by
+replaying that pass's paths. Diagnostic only: it reaches into the router.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+import json
+from pathlib import Path
+import sys
+
+from freeroute.board import build_board
+from freeroute.board.search_tree import ShapeSearchTree
+from freeroute.dsn import parse_dsn
+from freeroute.geometry.octagon import overlaps_2d
+from freeroute.route import grid_router
+from freeroute.route.exact_router import route_board_exact
+from freeroute.route.grid_router import GridRouter, _ends_of
+from freeroute.route.pipeline import (
+    _mm_to_board,
+    _rule_clearance_dsn,
+    _rule_width_dsn,
+    _via_half_board,
+)
+
+# a pin whose free neighbourhood holds fewer nodes than this is walled in
+FLOOD_LIMIT = 200
+
+
+def _capture_router():
+    """Patch GridRouter so the instance route_board_exact builds, and the paths
+    of its best pass, can be read back afterwards."""
+    seen: dict = {}
+    original_commit = GridRouter._commit
+    original_snapshot = GridRouter._snapshot
+
+    def commit(self, conn, path):
+        original_commit(self, conn, path)
+        self._diag_paths[conn.index] = (list(path), conn.a_end, conn.b_end)
+
+    def snapshot(self, conns):
+        self._diag_best = {c.index: self._diag_paths[c.index] for c in conns if c.routed}
+        seen["router"] = self
+        return original_snapshot(self, conns)
+
+    def init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        self._diag_paths = {}
+        self._diag_best = {}
+        seen["kwargs"] = kwargs
+        seen["args"] = args
+
+    original_init = GridRouter.__init__
+    GridRouter.__init__ = init
+    GridRouter._commit = commit
+    GridRouter._snapshot = snapshot
+    return seen
+
+
+def _capture_conflicts() -> list:
+    """Record each exact-check refusal: the copper box, its kind, and the
+    shape it came too close to. The check stops at a connection's first
+    conflict, so refusals and rejected connections line up in order."""
+    log: list = []
+    original = ShapeSearchTree.clearance_conflict
+
+    def conflict(self, box, net_no, layer, clearance, kind="wire"):
+        hit = original(self, box, net_no, layer, clearance, kind)
+        if hit:
+            # the shape that tripped the check, found the way the check does
+            other = None
+            expanded = box.offset(clearance)
+            for s in self.overlapping(expanded):
+                if s.net_no == net_no or not s.on_layer(layer):
+                    continue
+                if s.blocks != "all" and s.blocks != kind + "s":
+                    continue
+                if not s.clearance:
+                    if s.tile.overlaps(box):
+                        other = s
+                        break
+                    continue
+                if (s.exact is not None and overlaps_2d(s.exact, expanded)) or (
+                    s.exact is None and s.tile.overlaps(expanded)
+                ):
+                    other = s
+                    break
+            log.append((net_no, kind, layer, box, clearance, other))
+        return hit
+
+    ShapeSearchTree.clearance_conflict = conflict
+    return log
+
+
+def _gap(a, b) -> int:
+    dx = max(b.ll.x - a.ur.x, a.ll.x - b.ur.x, 0)
+    dy = max(b.ll.y - a.ur.y, a.ll.y - b.ur.y, 0)
+    return max(dx, dy)
+
+
+def _fresh(seen) -> GridRouter:
+    router = grid_router.GridRouter(*seen["args"], **seen["kwargs"])
+    router._conns = router._build_connections()
+    return router
+
+
+def _flood(router: GridRouter, pin, net_no: int, conns) -> tuple[int, Counter]:
+    """How many nodes a pin can reach through free cells (up to FLOOD_LIMIT),
+    and which other nets' copper bounds the region."""
+    walls: Counter = Counter()
+    # the search starts on every end node unconditionally (it may leave one
+    # inside a wire keepout by a via), so the flood does too
+    start = list(router._end_nodes(pin, net_no, conns))
+    seen = set(start)
+    frontier = list(start)
+    while frontier and len(seen) < FLOOD_LIMIT:
+        x, y, layer = frontier.pop()
+        steps = [(x + dx, y + dy, layer) for dx, dy in router._neighbours]
+        if router._via_placeable((x, y), net_no, conns):
+            steps += [(x, y, other) for other in router.layers if other != layer]
+        elif len(seen) == 1:
+            # the pin's own exit is a via that other copper leaves no room for
+            via_nodes = [(*c, lay) for c in router._via_cells((x, y)) for lay in router.layers]
+            for owner in router._crossed_owners(via_nodes, net_no, conns):
+                walls[conns[owner].net_no] += 1
+        for n in steps:
+            if n in seen or not (0 <= n[0] < router.cols and 0 <= n[1] < router.rows):
+                continue
+            if router._enter_cost(n[:2], n[2], net_no, False, conns) is None:
+                # trace, via footprint or clearance halo, as rip-up sees them
+                owners = router._crossed_owners([n], net_no, conns)
+                for owner in owners:
+                    walls[conns[owner].net_no] += 1
+                if not owners:
+                    walls[0] += 1  # a pad or keepout
+                continue
+            seen.add(n)
+            frontier.append(n)
+    return len(seen), walls
+
+
+def diagnose(
+    dsn_text: str, edge_clearance_mm: float | None, resolution: int = 2, shove: bool = False,
+    access_cost: float = 0.0,
+) -> dict:
+    dsn = parse_dsn(dsn_text)
+    names = {i + 1: n.name for i, n in enumerate(dsn.nets)}
+    scale = max(dsn.resolution.value, 1)
+    seen = _capture_router()
+    conflicts = _capture_conflicts()
+    exact = route_board_exact(
+        build_board(dsn),
+        trace_width=round(_rule_width_dsn(dsn) * scale),
+        clearance=round(_rule_clearance_dsn(dsn) * scale),
+        via_half=_via_half_board(dsn, scale),
+        edge_clearance=_mm_to_board(dsn, scale, edge_clearance_mm),
+        resolution=resolution,
+        shove=shove,
+        access_cost=access_cost,
+    )
+    routed = seen["router"]
+    best = routed._diag_best
+    grid_failed = {(c.net_no, *_ends_of(c)) for c in routed._conns if c.index not in best}
+
+    # the board as the best pass left it
+    state = _fresh(seen)
+    conns = state._conns
+    for idx, (path, a_end, b_end) in best.items():
+        conns[idx].a_end, conns[idx].b_end = a_end, b_end
+        state._commit(conns[idx], path)
+    empty = _fresh(seen)
+    # refusals in the order the check made them, one per rejected connection
+    per_net: dict[int, list] = {}
+    for net_no, kind, layer, box, clearance, other in conflicts:
+        if other is None:
+            what = "?"
+        elif other.net_no == -1:
+            what = "keepout" if other.clearance else "rule area"
+        else:
+            what = ("trace/via of " if other.routed else "pad of ") + names.get(other.net_no, "?")
+        need = clearance if other is None or other.clearance else 0
+        short = (need - _gap(box, other.tile)) / scale / 1000 if other is not None else 0
+        per_net.setdefault(net_no, []).append(
+            {"copper": kind, "layer": layer, "against": what, "short_mm": round(short, 4)}
+        )
+    by_key = {(c.net_no, *_ends_of(c)): c for c in conns}
+
+    rows = []
+    for failure in exact.result.failed:
+        net_no, a, b = failure[0], failure[1], failure[2]
+        zone = failure[3] if len(failure) > 3 else ""
+        if zone:
+            continue  # left to a zone fill, not a failure
+        key = (net_no, a, b)
+        row = {"net": names.get(net_no, str(net_no)), "a": a, "b": b}
+        conn = by_key.get(key)
+        if key not in grid_failed:
+            row["kind"] = "rejected"
+            if per_net.get(net_no):
+                row["conflict"] = per_net[net_no].pop(0)
+        elif conn is None:
+            row["kind"] = "unknown"
+        elif empty._search(empty._conns[conn.index], allow_ripup=False, conns=empty._conns) is None:
+            row["kind"] = "alone"
+        else:
+            walled = []
+            for end, group in ((a, conn.a_group), (b, conn.b_group)):
+                for pin in group[0][:1]:  # a group's first pin is its route end
+                    reach, walls = _flood(state, pin, net_no, conns)
+                    if reach < FLOOD_LIMIT:
+                        walled.append({
+                            "pin": end, "reach": reach,
+                            "walls": [names.get(n, "pads/keepouts") for n, _ in walls.most_common(4)],
+                        })
+            row["kind"] = "walled-in" if walled else "congestion"
+            if walled:
+                row["walled"] = walled
+        rows.append(row)
+    return {"failures": rows, "counts": dict(Counter(r["kind"] for r in rows))}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("dsn", type=Path)
+    ap.add_argument("--edge-clearance", type=float, metavar="MM")
+    ap.add_argument("--grid-resolution", type=int, default=2, metavar="K")
+    ap.add_argument("--shove", action="store_true", help="as mckicad routes")
+    ap.add_argument("--access-cost", type=float, default=0.0)
+    ap.add_argument("--json", type=Path, help="also write the full table here")
+    args = ap.parse_args(argv)
+
+    report = diagnose(args.dsn.read_text(), args.edge_clearance, args.grid_resolution, args.shove,
+                      args.access_cost)
+    for row in report["failures"]:
+        extra = ""
+        for w in row.get("walled", []):
+            extra += f"  [{w['pin']} reaches {w['reach']} cells, walled by {', '.join(w['walls'])}]"
+        if "conflict" in row:
+            c = row["conflict"]
+            extra += (f"  [{c['copper']} on layer {c['layer']} {c['short_mm']} mm too close"
+                      f" to {c['against']}]")
+        print(f"{row['kind']:11} {row['net']}: {row['a']} to {row['b']}{extra}")
+    total = sum(report["counts"].values())
+    print(f"\n{total} failed: " + ", ".join(f"{k} {v}" for k, v in sorted(report["counts"].items())),
+          file=sys.stderr)
+    if args.json:
+        args.json.write_text(json.dumps(report, indent=1))
+    return 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,11 +57,40 @@ 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)]
 
+    def get_fixed_copper(self) -> list[tuple[int, frozenset[int], IntBox]]:
+        """Copper already routed on the board (the DSN's ``wiring``), as
+        ``(net, layers, box)``. A track is its segments, its corners and the
+        round caps at its ends (as squares); a via is its largest pad."""
+        from freeroute.geometry.polyline import Polyline, PolylineShape, corner_box
+
+        out: list[tuple[int, frozenset[int], IntBox]] = []
+        for item in self._items:
+            if not item.fixed or not item.net_nos:
+                continue
+            net = item.net_nos[0]
+            if isinstance(item, Trace) and not item.is_empty():
+                layers = frozenset({item.layer})
+                for box in PolylineShape(Polyline(item.corners), item.half_width).tiles():
+                    out.append((net, layers, box))
+                for end in (item.corners[0], item.corners[-1]):
+                    out.append((net, layers, corner_box(end, item.half_width)))
+            elif isinstance(item, Via) and item.shape is not None:
+                out.append((net, frozenset(item.layers), item.shape.bounding_box()))
+        return out
+
     def get_vias(self) -> list[Via]:
         return [it for it in self._items if isinstance(it, Via)]
 

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, Trace, Via
 from .layer import Layer, LayerStructure
 from .net import Nets
 from .transform import CoordinateTransform
@@ -49,9 +50,13 @@ 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)
+    _insert_wiring(dsn, board, transform, nets)
     return board
 
 
@@ -97,6 +102,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 +149,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 +157,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 +166,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 +216,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 +310,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 +331,48 @@ 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",
+                    clearance=not is_rule_area(keepout.area.name),
                 )
             )
 
 
+#: a structure keepout named with this prefix is a KiCad rule area (mckicad
+#: names them on export); it is checked for overlap only
+RULE_AREA_PREFIX = "rule_area"
+
+
+def is_rule_area(name: str | None) -> bool:
+    return bool(name) and name.startswith(RULE_AREA_PREFIX)
+
+
+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 +400,140 @@ 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_wiring(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTransform, nets) -> None:
+    """Tracks and vias already on the board, as fixed copper of their nets."""
+    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]
+    numbers = {net.name: net.net_number for net in nets}
+    for wire in dsn.wires:
+        if wire.net not in numbers or wire.layer not in layer_no:
+            continue
+        c = wire.coords
+        corners = [transform.dsn_to_board_point(c[i], c[i + 1]) for i in range(0, len(c) - 1, 2)]
+        if len(corners) < 2:
+            continue
+        board.insert(
+            Trace(
+                net_nos=[numbers[wire.net]], fixed=True, layer=layer_no[wire.layer],
+                half_width=max(round(transform.dsn_to_board(wire.width / 2)), 1), corners=corners,
+            )
+        )
+    for via in dsn.vias:
+        padstack = dsn.padstack(via.padstack)
+        if via.net not in numbers or padstack is None or not padstack.shapes:
+            continue
+        layers: set[int] = set()
+        for shape in padstack.shapes:
+            if shape.layer in ("signal", "pcb"):
+                layers.update(signal_layers)
+            elif shape.layer in layer_no:
+                layers.add(layer_no[shape.layer])
+        location = transform.dsn_to_board_point(via.x, via.y)
+        pad = _pad_tile(max(padstack.shapes, key=_shape_extent), transform)
+        box = pad.bounding_box()
+        board.insert(
+            Via(
+                net_nos=[numbers[via.net]], fixed=True, padstack_name=via.padstack,
+                location=location, layers=sorted(layers or signal_layers),
+                shape=IntBox(box.ll.x + location.x, box.ll.y + location.y,
+                             box.ur.x + location.x, box.ur.y + location.y),
+            )
+        )
+
+
+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,15 @@ 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
+    #: False for a KiCad rule area: copper may not overlap it but may touch
+    #: it, since KiCad's DRC applies no clearance to a rule area. Every other
+    #: keepout may stand for copper (a net tie, a track kept as it is), so it
+    #: keeps the clearance unless named as a rule area.
+    clearance: bool = True
 
     def is_obstacle(self) -> bool:
         return True
@@ -85,7 +96,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
@@ -94,6 +114,9 @@ class Via(Item):
 
     padstack_name: str = ""
     location: IntPoint = field(default_factory=lambda: IntPoint(0, 0))
+    #: layer indices the via's pads occupy, and the largest pad as a box
+    layers: list[int] = field(default_factory=list)
+    shape: object = None
 
 
 @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,11 @@ 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"
+    #: False for a rule area: copper may touch it, only overlap counts
+    clearance: bool = True
 
     def on_layer(self, layer: int) -> bool:
         return layer in self.layers
@@ -118,17 +123,27 @@ 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).
 
         Uses a strict 2-D overlap of the ``clearance``-expanded box, so tiles
         exactly ``clearance`` apart (touching after expansion) are allowed.
+        A rule area (``clearance=False``) only has to be clear of the copper
+        itself.
         """
         expanded = box.offset(clearance)
         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 not shape.clearance:
+                if shape.tile.overlaps(box):
+                    return True
+                continue
             if shape.exact is not None:
                 if overlaps_2d(shape.exact, expanded):
                     return True
@@ -136,6 +151,17 @@ class ShapeSearchTree:
                 return True
         return False
 
+    def rule_area_overlap(self, box: IntBox, layer: int, kind: str = "wire") -> bool:
+        """True if ``box`` overlaps a rule area on ``layer`` that stops ``kind``."""
+        for shape in self.overlapping(box):
+            if shape.clearance or not shape.on_layer(layer):
+                continue
+            if shape.blocks != "all" and shape.blocks != kind + "s":
+                continue
+            if shape.tile.overlaps(box):
+                return True
+        return False
+
     def clearance_conflict_shape(
         self, region, net_no: int, layer: int
     ) -> bool:
@@ -171,6 +197,13 @@ class ShapeSearchTree:
                     continue  # static input pair (e.g. pad vs pad) — not a routing DRC
                 if not (shape.layers & other.layers):
                     continue
+                if not (shape.clearance and other.clearance):
+                    # a rule area: only an overlap is a violation
+                    mine = shape.exact if shape.exact is not None else shape.tile
+                    theirs = other.exact if other.exact is not None else other.tile
+                    if overlaps_2d(mine, theirs):
+                        return shape
+                    continue
                 if shape.exact is None and other.exact is None:
                     if other.tile.overlaps(expanded):  # byte-identical box path
                         return shape

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, promote_failures
 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", "promote", "access", "rollback"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote", "access", "rollback"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -41,6 +42,11 @@ _FLAG_NAMES = {
     "diagonal": "--diagonal",
     "rip_up": "--no-rip-up",
     "max_passes": "-mp/--max-passes",
+    "seed": "--seed",
+    "orders": "--orders",
+    "promote": "--promote-failures",
+    "access": "--access-cost",
+    "rollback": "--no-rollback",
 }
 
 
@@ -110,6 +116,71 @@ 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(
+        "--promote-failures",
+        type=int,
+        metavar="R",
+        help="grid and exact engines: up to R rounds, each routing the connections that "
+        "failed so far first; keeps the best round",
+    )
+    parser.add_argument(
+        "--access-cost",
+        type=float,
+        metavar="C",
+        help="grid and exact engines: extra cost for a route to pass where it would close "
+        "another pin's way out while that pin still has connections to route (default 0: off)",
+    )
+    parser.add_argument(
+        "--no-rollback",
+        dest="rollback",
+        action="store_false",
+        help="grid and exact engines: keep every rip-up, as before. By default the "
+        "connections a rip-up displaces are rerouted at once and the rip-up is undone "
+        "if fewer connections end up routed",
+    )
+    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 +200,11 @@ 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),
+            ("promote", args.promote_failures is not None),
+            ("access", args.access_cost is not None),
+            ("rollback", not args.rollback),
         )
         if asked
     ]
@@ -150,21 +226,74 @@ 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,
+            "access_cost": args.access_cost or 0.0,
+            "rollback": args.rollback,
+        }
+    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,
+            "access_cost": args.access_cost or 0.0,
+            "rollback": args.rollback,
+        }
+    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.promote_failures and args.promote_failures > 1:
+        if args.orders:
+            parser.error("--orders and --promote-failures cannot be combined")
+        result, rounds = promote_failures(
+            dsn_text, args.engine, options, rounds=args.promote_failures, seed=args.seed
+        )
+        counts = ", ".join(str(m) for m, _z in rounds)
+        print(f"freeroute: {len(rounds)} rounds, unrouted {counts}; kept the best", file=sys.stderr)
+    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

@@ -27,6 +27,8 @@ __all__ = [
     "NetPin",
     "Net",
     "NetClass",
+    "WiringVia",
+    "WiringWire",
     "Keepout",
     "DsnBoard",
 ]
@@ -112,6 +114,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 +172,40 @@ 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
+class WiringWire:
+    """A track already on the board: ``(wire (path LAYER WIDTH x y ...) (net N))``."""
+
+    net: str
+    layer: str
+    width: float
+    coords: list[float] = field(default_factory=list)
+
+
+@dataclass
+class WiringVia:
+    """A via already on the board: ``(via PADSTACK x y (net N))``."""
+
+    net: str
+    padstack: str
+    x: float
+    y: float
 
 
 @dataclass
@@ -186,6 +217,11 @@ 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)
+    #: copper already routed (the ``wiring`` scope), kept fixed
+    wires: list[WiringWire] = field(default_factory=list)
+    vias: list[WiringVia] = 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

@@ -9,6 +9,8 @@ tolerant ``skip_scope`` behaviour.
 
 from __future__ import annotations
 
+import re
+
 from .model import (
     ClearanceRule,
     ComponentPlace,
@@ -25,6 +27,8 @@ from .model import (
     Pin,
     Resolution,
     WidthRule,
+    WiringVia,
+    WiringWire,
 )
 from .sexp import SExp, parse
 from .shapes import Shape, read_area, read_shape
@@ -178,6 +182,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 +299,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:
@@ -467,12 +485,26 @@ def _read_network(node: SExp, board: DsnBoard) -> None:
 # --- top level ---------------------------------------------------------------
 
 
+_STRING_QUOTE = re.compile(r"\(\s*string_quote\s+(\S)\s*\)")
+
+
+def _declared_quote(text: str) -> str:
+    """The quote character the file declares in ``(string_quote X)``.
+
+    Only that character opens a string. Without a declaration both kinds are
+    accepted, as before: KiCad declares ``"`` and then writes a bare ``'``
+    where a value is a single quote mark, e.g. a keycap part number.
+    """
+    found = _STRING_QUOTE.search(text[:4096])
+    return found.group(1) if found else "\"'"
+
+
 def parse_dsn(text: str) -> DsnBoard:
     """Parse DSN ``text`` into a :class:`DsnBoard`.
 
     Raises :class:`DsnParseError` if the top-level scope is not ``(pcb ...)``.
     """
-    top = parse(text)
+    top = parse(text, _declared_quote(text))
     if top.head != "pcb":
         raise DsnParseError(
             f"not a Specctra DSN file: expected top-level '(pcb ...)', got '({top.head} ...)'"
@@ -501,6 +533,56 @@ def parse_dsn(text: str) -> DsnBoard:
             _read_placement(it, board)
         elif head == "network":
             _read_network(it, board)
-        # `wiring` and unknown scopes are intentionally ignored for now.
+        elif head == "wiring":
+            _read_wiring(it, board)
+        # unknown scopes are ignored
 
     return board
+
+
+def _read_wiring(node: SExp, board: DsnBoard) -> None:
+    """Tracks and vias already on the board. They stay where they are: the
+    router treats them as copper of their net that other nets keep clear of."""
+    for it in node.items:
+        if not isinstance(it, SExp):
+            continue
+        net_scope = it.child("net")
+        net = _first_value(net_scope) if net_scope is not None else None
+        if not net:
+            continue  # netless copper would need a keepout, not a wire
+        if it.head == "wire":
+            path = it.child("path") or it.child("polyline_path")
+            vals = [v.text for v in path.values()] if path is not None else []
+            if len(vals) < 6:
+                continue
+            try:
+                width = float(vals[1])
+                coords = [float(v) for v in vals[2:]]
+            except ValueError:
+                continue
+            board.wires.append(WiringWire(net=net, layer=vals[0], width=width, coords=coords))
+        elif it.head == "via":
+            vals = [v.text for v in it.values()]
+            if len(vals) < 3:
+                continue
+            try:
+                x, y = float(vals[1]), float(vals[2])
+            except ValueError:
+                continue
+            board.vias.append(WiringVia(net=net, padstack=vals[0], x=x, y=y))
+
+
+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

@@ -42,6 +42,7 @@ from freeroute.geometry import (
     segment_octagon,
     shove_segment,
 )
+from freeroute.geometry.polyline import corner_box
 
 from .grid_router import RouteResult, route_board
 
@@ -90,6 +91,14 @@ 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,
+    route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    rollback: bool = True,
 ) -> ExactRouteResult:
     """Route ``board`` orthogonally and verify the result with exact geometry.
 
@@ -102,6 +111,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 +123,17 @@ 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,
+        route_first=route_first,
+        access_cost=access_cost,
+        rollback=rollback,
     )
+    edge = 0 if edge_clearance is None else edge_clearance
+    outline = board.outline
 
     tree = ShapeSearchTree()
     owner = _counter()
@@ -129,32 +149,61 @@ def route_board_exact(
         pin_layers = frozenset(layer for layer in pin.layers if layer in signal_layers)
         if pin_layers:
             tree.insert(TreeShape(next(owner), net, pin_layers, box))
+    for net, copper_layers, box in board.get_fixed_copper():
+        on = frozenset(layer for layer in copper_layers if layer in signal_layers)
+        if on and not box.is_empty():
+            tree.insert(TreeShape(next(owner), net, on, box))
     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, clearance=obstacle.clearance,
+                    )
+                )
 
     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 _end_in_rule_area(tree, wires, half_width) 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 +238,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 +598,31 @@ 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 _end_in_rule_area(tree, wires, half_width) -> bool:
+    """A wire's tiles stop at its end points, but a track ends in a round cap
+    half its width beyond them. Against other copper the pad or via there
+    covers it; a rule area has no clearance to absorb it, so check it."""
+    for layer, points in wires:
+        for end in (points[0], points[-1]):
+            if tree.rule_area_overlap(corner_box(end, half_width), layer):
+                return True
+    return False
+
+
+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/orders.py

@@ -0,0 +1,98 @@
+"""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))
+
+
+def promote_failures(
+    dsn_text: str,
+    engine: str,
+    options: dict,
+    *,
+    rounds: int,
+    seed: int | None = None,
+) -> tuple[RoutingResult, list[tuple[int, int]]]:
+    """Route, then route again with every connection that has failed so far
+    moved to the front, keeping the rest in their order. Returns the best
+    round's result and every round's score.
+
+    The promoted set only grows, so a connection that failed once keeps its
+    early place and two groups cannot take turns failing. Stops early when a
+    round routes everything or fails nothing new."""
+    numbers = {n.name: i + 1 for i, n in enumerate(parse_dsn(dsn_text).nets)}
+    first: frozenset = frozenset()
+    best: RoutingResult | None = None
+    scores: list[tuple[int, int]] = []
+    for _ in range(max(int(rounds), 1)):
+        result = route_once(dsn_text, engine, {**options, "route_first": first}, seed)
+        scores.append(score(result))
+        if best is None or scores[-1] < score(best):
+            best = result
+        failed = {(numbers.get(name), a, b) for name, a, b, zone in result.unrouted if not zone}
+        if not failed or failed <= first:
+            break
+        first = first | failed
+    return best, scores

src/freeroute/route/pipeline.py

@@ -45,12 +45,45 @@ 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,
+    route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    rollback: bool = True,
 ) -> 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 +91,23 @@ 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,
+        route_first=route_first,
+        access_cost=access_cost,
+        rollback=rollback,
     )
     return result, scale, [layer.name for layer in dsn.layers]
 
@@ -93,19 +134,32 @@ 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,
+    route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    rollback: bool = True,
 ) -> 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,
+        route_first=route_first,
+        access_cost=access_cost,
+        rollback=rollback,
     )
     return _to_routing_result(route, dsn, scale, layer_names)
 
@@ -113,11 +167,18 @@ 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,
+    route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    rollback: bool = True,
 ) -> 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 +187,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 +203,10 @@ def route_dsn_board_exact(
         rip_up=rip_up,
         shove=shove,
         diagonal=diagonal,
+        seed=seed,
+        route_first=route_first,
+        access_cost=access_cost,
+        rollback=rollback,
     )
     return exact, scale, [layer.name for layer in dsn.layers]
 
@@ -144,11 +214,18 @@ 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,
+    route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    rollback: bool = True,
 ) -> RoutingResult:
     """Route ``dsn`` (exact track) and convert to a DSN-unit RoutingResult."""
     exact, scale, layer_names = route_dsn_board_exact(
@@ -158,12 +235,24 @@ 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,
+        route_first=route_first,
+        access_cost=access_cost,
+        rollback=rollback,
     )
     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 +260,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 +277,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 +299,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 +314,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
 
@@ -509,6 +515,10 @@ def route_board_rooms(
         pin_layers = frozenset(layer for layer in pin.layers if layer in signal_layers)
         if pin_layers:
             tree.insert(TreeShape(next(owner), net, pin_layers, box))
+    for net, copper_layers, box in board.get_fixed_copper():
+        on = frozenset(layer for layer in copper_layers if layer in signal_layers)
+        if on and not box.is_empty():
+            tree.insert(TreeShape(next(owner), net, on, box))
     for obstacle in board.get_obstacle_areas():
         if obstacle.layer not in signal_layers:
             continue
@@ -537,7 +547,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 +572,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 +597,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 +619,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 +627,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 +646,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 +659,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 +686,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 +711,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 +872,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 +942,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 +957,7 @@ def _pack_channels(
                         via_layers,
                         shove,
                         accepted,
-                    )
+                    via_half=via_half)
                     routed.add(net_no)
     return routed
 
@@ -958,6 +978,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 +1036,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 +1071,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,152 @@ 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
+
+
+# --- rule areas: overlap only ------------------------------------------------
+
+_CHANNEL_DSN = """(pcb channel.dsn
+  (parser (string_quote ")) (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 "{name}top" (polygon signal 0  18000 0  22000 0  22000 -14750  18000 -14750))
+    (keepout "{name}bottom" (polygon signal 0  18000 -15250  22000 -15250  22000 -30000  18000 -30000))
+    (rule (width 250) (clearance 150)))
+  (placement (component P (place P1 5000 -15000 front 0) (place P2 35000 -15000 front 0)))
+  (library (image P (pin pad 1 0 0)) (padstack pad (shape (circle F.Cu 600)) (attach off)))
+  (network (net N (pins P1-1 P2-1))))"""
+
+
+def test_a_keepout_named_rule_area_takes_no_clearance():
+    named = _areas(_CHANNEL_DSN.format(name="rule_area_"))
+    plain = _areas(_CHANNEL_DSN.format(name=""))
+    assert named and not any(a.clearance for a in named)
+    assert plain and all(a.clearance for a in plain)
+
+
+def _route_channel(name):
+    from freeroute.route.pipeline import build_exact_routing_result
+
+    return build_exact_routing_result(parse_dsn(_CHANNEL_DSN.format(name=name)), resolution=2)
+
+
+def test_a_trace_may_run_beside_a_rule_area_closer_than_clearance():
+    # the 0.5 mm channel fits a 0.25 mm trace, but not with 0.15 mm each side
+    assert _route_channel("rule_area_").unrouted == []
+    assert _route_channel("").unrouted != []

tests/board/test_search_tree.py

@@ -62,3 +62,37 @@ def test_has_violation_ignores_static_pad_pairs():
     # a routed trace of net 3 within clearance of pad net 1 -> violation
     tree.insert(shape(2, 3, 0, IntBox(11, 0, 20, 10), routed=True))
     assert tree.has_violation(clearance=20) is not None
+
+
+def test_a_rule_area_conflicts_only_on_overlap():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    near = IntBox(0, 0, 95, 100)  # 5 short of the area, well inside clearance 50
+    over = IntBox(0, 0, 105, 100)
+    assert not tree.clearance_conflict(near, 7, 0, 50)
+    assert tree.clearance_conflict(over, 7, 0, 50)
+
+
+def test_an_ordinary_keepout_still_needs_clearance():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100)))
+    assert tree.clearance_conflict(IntBox(0, 0, 95, 100), 7, 0, 50)
+
+
+def test_the_routed_board_check_treats_a_rule_area_the_same_way():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    tree.insert(TreeShape(2, 7, frozenset({0}), IntBox(0, 0, 95, 100), routed=True))
+    assert tree.has_violation(50) is None
+    tree.insert(TreeShape(3, 7, frozenset({0}), IntBox(150, 0, 160, 100), routed=True))
+    assert tree.has_violation(50) is not None
+
+
+
+def test_rule_area_overlap_sees_only_rule_areas():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    tree.insert(TreeShape(2, -1, frozenset({0}), IntBox(300, 0, 400, 100)))
+    assert tree.rule_area_overlap(IntBox(90, 40, 110, 60), 0)
+    assert not tree.rule_area_overlap(IntBox(290, 40, 310, 60), 0)
+    assert not tree.rule_area_overlap(IntBox(90, 40, 110, 60), 1)

tests/dsn/test_reader.py

@@ -156,3 +156,26 @@ def test_unplaced_component_has_no_coords():
     place = board.placements[0].places[0]
     assert place.name == "U9"
     assert place.x is None and place.y is None
+
+
+# --- string_quote ----------------------------------------------------------
+
+_QUOTED = """(pcb q.dsn
+  (parser (string_quote {q}) (space_in_quoted_tokens on))
+  (resolution um 10) (unit um)
+  (structure (layer F.Cu (type signal)) (boundary (path pcb 0 0 0 1000 0 1000 1000 0 1000 0 0)))
+  (placement (component "SW1" (place SW1 100 100 front 0 (PN {pn}))))
+  (library)
+  (network)
+)"""
+
+
+def test_a_bare_apostrophe_is_an_atom_when_the_file_quotes_with_double_quotes():
+    # KiCad declares " and writes a keycap's part number as a bare '
+    board = parse_dsn(_QUOTED.format(q='"', pn="'"))
+    assert board.parser.string_quote == '"'
+
+
+def test_the_declared_quote_character_is_the_one_that_opens_strings():
+    board = parse_dsn(_QUOTED.format(q="'", pn="'10k 1%'").replace('"SW1"', "'SW1'"))
+    assert board.parser.string_quote == "'"

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_fixed_wiring.py

@@ -0,0 +1,50 @@
+"""Tracks and vias already on the board (the DSN's wiring) are fixed copper."""
+
+from __future__ import annotations
+
+from freeroute.board import build_board
+from freeroute.dsn import parse_dsn
+from freeroute.route.pipeline import route_dsn_board_exact
+
+_DSN = """(pcb wired (parser) (resolution um 10) (unit um)
+  (structure
+    (layer F.Cu (type signal)) (layer B.Cu (type signal))
+    (boundary (path pcb 0  0 0  30000 0  30000 -20000  0 -20000  0 0))
+    (via "Via[0-1]_600:300_um") (rule (width 250) (clearance 200)))
+  (placement (component S (place A1 5000 -10000 front 0) (place A2 25000 -10000 front 0)))
+  (library
+    (image S (pin smd 1 0 0))
+    (padstack smd (shape (rect F.Cu -400 -400 400 400)) (attach off))
+    (padstack "Via[0-1]_600:300_um" (shape (circle F.Cu 600)) (shape (circle B.Cu 600)) (attach off)))
+  (network (net SIG (pins A1-1 A2-1)) (net GND))
+  (wiring
+    (wire (path F.Cu 400  15000 0  15000 -20000) (net GND) (type route))
+    (via "Via[0-1]_600:300_um"  8000 -14000 (net GND) (type route))))"""
+
+
+def test_wiring_is_read_with_its_nets():
+    dsn = parse_dsn(_DSN)
+    assert [(w.net, w.layer, w.width) for w in dsn.wires] == [("GND", "F.Cu", 400.0)]
+    assert [(v.net, v.x, v.y) for v in dsn.vias] == [("GND", 8000.0, -14000.0)]
+
+
+def test_wiring_is_fixed_copper_and_not_a_connection_to_route():
+    board = build_board(parse_dsn(_DSN))
+    copper = board.get_fixed_copper()
+    gnd = next(n.net_number for n in board.nets if n.name == "GND")
+    assert copper and all(net == gnd for net, _, _ in copper)
+    assert not any(gnd in p.net_nos for p in board.get_pins())
+
+
+def test_other_nets_route_around_a_fixed_track():
+    dsn = parse_dsn(_DSN)
+    exact, scale, names = route_dsn_board_exact(dsn, resolution=2)
+    sig = next(i + 1 for i, n in enumerate(dsn.nets) if n.name == "SIG")
+    assert sig in exact.result.routed_net_numbers
+    assert exact.drc_clean
+    wall = 15000 * scale
+    for layer, pts in exact.result.wires.get(sig, []):
+        if names[layer] != "F.Cu":
+            continue
+        for p, q in zip(pts, pts[1:], strict=False):
+            assert not (min(p.x, q.x) < wall < max(p.x, q.x)), "crossed the GND track on F.Cu"

tests/route/test_orders.py

@@ -0,0 +1,78 @@
+"""--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,
+    promote_failures,
+    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")
+
+
+def test_promoting_the_failed_connection_routes_it():
+    best, rounds = promote_failures(RIPUP, "grid", GREEDY, rounds=3)
+    assert rounds == [(1, 0), (0, 0)]  # stops once nothing fails
+    assert score(best) == (0, 0)
+
+
+def test_nothing_promoted_is_the_plain_order():
+    plain = route_once(RIPUP, "grid", {}, None)
+    empty = route_once(RIPUP, "grid", {"route_first": frozenset()}, None)
+    assert plain == empty
+
+
+def test_cli_promote_failures(tmp_path, capsys):
+    out = tmp_path / "p.ses"
+    rc = main(
+        [
+            str(FIXTURES / "ripup_needed.dsn"),
+            "--no-rip-up",
+            "--promote-failures",
+            "3",
+            "-do",
+            str(out),
+        ]
+    )
+    assert rc == 0
+    assert "2 rounds, unrouted 1, 0" in capsys.readouterr().err

tests/route/test_real_board_geometry.py

@@ -0,0 +1,251 @@
+"""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_pad_outside_the_plane_routes_to_it():
+    # G1 sits left of a plane that covers only the right half, so its route
+    # has to reach the plane's cells: those ends are the plane, not a pin
+    dsn_text = _four_layer_dsn().replace(
+        "(plane GND (polygon In1.Cu 0  500 -500  29500 -500  29500 -29500  500 -29500  500 -500))",
+        "(plane GND (polygon In1.Cu 0  15000 -500  29500 -500  29500 -29500  15000 -29500  15000 -500))",
+    )
+    result, _scale, _names = route_dsn_board_exact(parse_dsn(dsn_text))
+    gnd = next(i + 1 for i, n in enumerate(parse_dsn(dsn_text).nets) if n.name == "GND")
+    assert gnd in result.result.routed_net_numbers
+
+
+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"]
+
+
+def test_a_pad_inside_a_via_keepout_reaches_the_plane_by_a_via_outside_it():
+    # a sensor's GND pad: vias are forbidden under the body, so the route
+    # has to leave on the top layer and drop to the plane past the keepout
+    dsn = parse_dsn("""(pcb repro (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  20000 0  20000 -20000  0 -20000  0 0))
+    (plane GND (polygon In1.Cu 0  500 -500  19500 -500  19500 -19500  500 -19500  500 -500))
+    (via_keepout "" (polygon signal 0  8500 -8500  11500 -8500  11500 -11500  8500 -11500  8500 -8500))
+    (via "Via[0-3]_600:300_um") (rule (width 150) (clearance 150)))
+  (placement (component S (place G1 10000 -10000 front 0)))
+  (library
+    (image S (pin smd 1 0 0))
+    (padstack smd (shape (rect F.Cu -175 -300 175 300)) (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))))""")
+    exact, scale, _names = route_dsn_board_exact(dsn, resolution=2)
+    assert exact.result.failed == []
+    (via,) = exact.result.vias[1]
+    half = 300 * scale  # the via's radius
+    outside = (via.x + half <= 8500 * scale or via.x - half >= 11500 * scale
+               or via.y - half >= -8500 * scale or via.y + half <= -11500 * scale)
+    assert outside, f"via at {via} is inside the via keepout"

tests/route/test_rollback.py

@@ -0,0 +1,43 @@
+"""--rollback: a rip-up that loses connections is undone, leaving no trace."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from freeroute.board import build_board
+from freeroute.dsn import parse_dsn
+from freeroute.route.grid_router import GridRouter
+from freeroute.route.pipeline import _rule_clearance_dsn, _rule_width_dsn, route_dsn_board
+
+FIXTURES = Path(__file__).resolve().parent.parent / "dsn" / "fixtures"
+
+
+def _routed_router(name):
+    dsn = parse_dsn((FIXTURES / name).read_text())
+    s = dsn.resolution.value
+    router = GridRouter(
+        build_board(dsn),
+        trace_width=round(_rule_width_dsn(dsn) * s),
+        clearance=round(_rule_clearance_dsn(dsn) * s),
+        rollback=True,
+    )
+    return router, router.route()
+
+
+@pytest.mark.parametrize("name", ["ripup_needed.dsn", "true_density.dsn", "kicad_routable.dsn"])
+def test_occupancy_only_holds_routed_connections(name):
+    router, _ = _routed_router(name)
+    conns = router._conns
+    assert all(conns[i].routed for i in router._cell_owner.values())
+    assert all(conns[i].routed for i in router._via_owner.values())
+    assert all(conns[i].routed for claims in router._halo.values() for i in claims)
+
+
+@pytest.mark.parametrize("name", ["ripup_needed.dsn", "true_density.dsn", "kicad_routable.dsn"])
+def test_rollback_never_routes_fewer_than_plain_rip_up(name):
+    text = (FIXTURES / name).read_text()
+    plain, _, _ = route_dsn_board(parse_dsn(text), rollback=False)
+    undo, _, _ = route_dsn_board(parse_dsn(text))
+    assert undo.unrouted <= plain.unrouted

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,11 @@ 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"],
+        "promote": ["--promote-failures", "2"],
+        "access": ["--access-cost", "5"],
+        "rollback": ["--no-rollback"],
     }
     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]