Keepout exits and rule areas

A route may not leave a cell inside a wire keepout as a wire, nor reach
a pin there by one: it changes layer instead, and the via goes in the
pad. A pin whose every stub enters a keepout is reached by a via only.

A structure keepout named rule_area... (mckicad names KiCad rule areas
so) is checked for overlap only, as KiCad's DRC does, with the free ends
of each wire tested for their round caps.

bench/bench.py

@@ -24,9 +24,11 @@ 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
@@ -34,8 +36,6 @@ import sys
 import tempfile
 import threading
 import time
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from pathlib import Path
 
 NOT_ROUTED = re.compile(r"freeroute: (\d+) connection\(s\) not routed")
 TO_ZONE = re.compile(r"freeroute: (\d+) more connection\(s\) left to a zone fill")

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/build.py

@@ -333,10 +333,20 @@ def _insert_keepouts(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTran
                     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.
 

src/freeroute/board/items.py

@@ -76,6 +76,11 @@ class ObstacleArea(Item):
     #: 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

src/freeroute/board/search_tree.py

@@ -50,6 +50,8 @@ class TreeShape:
     #: 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
@@ -129,6 +131,8 @@ class ShapeSearchTree:
 
         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):
@@ -136,6 +140,10 @@ class ShapeSearchTree:
                 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
@@ -143,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:
@@ -178,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

@@ -30,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", "seed", "orders", "promote"}),
-    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote"}),
+    "grid": frozenset({"rip_up", "max_passes", "seed", "orders", "promote", "access"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote", "access"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -45,6 +45,7 @@ _FLAG_NAMES = {
     "seed": "--seed",
     "orders": "--orders",
     "promote": "--promote-failures",
+    "access": "--access-cost",
 }
 
 
@@ -158,6 +159,13 @@ def build_parser() -> argparse.ArgumentParser:
         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(
         "--jobs",
         type=int,
@@ -186,6 +194,7 @@ def main(argv: list[str] | None = None) -> int:
             ("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),
         )
         if asked
     ]
@@ -219,6 +228,7 @@ def main(argv: list[str] | None = None) -> int:
             "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,
         }
     elif args.engine == "grid":
         options = {
@@ -227,6 +237,7 @@ def main(argv: list[str] | None = None) -> int:
             "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,
         }
     if args.engine == "room":
         result = build_rooms_routing_result(

src/freeroute/dsn/reader.py

@@ -9,6 +9,8 @@ tolerant ``skip_scope`` behaviour.
 
 from __future__ import annotations
 
+import re
+
 from .model import (
     ClearanceRule,
     ComponentPlace,
@@ -481,12 +483,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} ...)'"

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
 
@@ -96,6 +97,7 @@ def route_board_exact(
     heuristic_weight: float = 1.0,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> ExactRouteResult:
     """Route ``board`` orthogonally and verify the result with exact geometry.
 
@@ -126,6 +128,7 @@ def route_board_exact(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     edge = 0 if edge_clearance is None else edge_clearance
     outline = board.outline
@@ -155,7 +158,10 @@ def route_board_exact(
             box = tile.bounding_box()
             if not box.is_empty():
                 tree.insert(
-                    TreeShape(next(owner), -1, frozenset({obstacle.layer}), box, blocks=blocks)
+                    TreeShape(
+                        next(owner), -1, frozenset({obstacle.layer}), box,
+                        blocks=blocks, clearance=obstacle.clearance,
+                    )
                 )
 
     via_layers = frozenset(signal_layers)
@@ -176,7 +182,9 @@ def route_board_exact(
             )
             for i, (box, box_layers) in enumerate(boxes)
             for layer in box_layers
-        ) or (outline is not None and not all(outline.box_clear(b, edge) for b, _ in boxes)):
+        ) 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.get(net_no)
@@ -590,6 +598,17 @@ def _net_boxes(result, net_no, half_width, via_layers, via_half=None):
     )
 
 
+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]]] = []

src/freeroute/route/grid_router.py

@@ -33,6 +33,7 @@ import random
 from freeroute.board.board import BasicBoard
 from freeroute.board.items import ConductionArea, ObstacleArea, Pin
 from freeroute.geometry import IntBox, IntPoint
+from freeroute.geometry.polyline import corner_box
 
 __all__ = ["GridRouter", "RouteResult", "route_board"]
 
@@ -157,8 +158,16 @@ class GridRouter:
         heuristic_weight: float = 1.0,
         seed: int | None = None,
         route_first: frozenset | None = None,
+        access_cost: float = 0.0,
     ) -> None:
         self.board = board
+        # Pin access: while a pin still has connections to route, the cells
+        # its route would leave by (its end cells, the via it may need there,
+        # and the clearance around both) cost other nets this much extra, so
+        # they route round a fine-pitch pin's way out instead of sealing it.
+        self.access_cost = max(float(access_cost), 0.0)
+        self._doorways: dict[Node, list[tuple[int, int]]] = {}
+        self._pending: dict[int, int] = {}
         # None keeps the deterministic order; a seed shuffles which connection
         # routes first, to measure how much a result owes to the order
         self.seed = seed
@@ -289,6 +298,10 @@ class GridRouter:
         margin = self.clearance + self.half_width
         outline = self.board.outline
         self._via_edge_block: set[Cell] = set()
+        # wire keepouts as boxes, to check a pin stub the way the exact engine will
+        self._keepout_boxes: dict[int, list[tuple[IntBox, bool]]] = {}
+        # pin end nodes no wire can reach without entering a keepout
+        self._via_only: set[Node] = set()
         if outline is not None:
             # cells too close to the real outline (rounded corners included):
             # for a trace on every layer, and separately for a via's wider copper
@@ -325,7 +338,13 @@ class GridRouter:
                     if box.is_empty():
                         continue
                     # the same distance the exact engine verifies against
-                    for cell in self._cells_in_box(box, margin):
+                    if item.blocks_wires:
+                        self._keepout_boxes.setdefault(item.layer, []).append(
+                            (box, item.clearance)
+                        )
+                    # a rule area takes no clearance: a trace may touch it
+                    reach = margin if item.clearance else self.half_width
+                    for cell in self._cells_in_box(box, reach):
                         if item.blocks_wires:
                             self._keepout.add((*cell, item.layer))
                         if item.blocks_vias:
@@ -463,23 +482,34 @@ class GridRouter:
                     return path
             cx, cy, cl = current
             base = g_score[current]
-            for dx, dy in self._neighbours:
+            # A cell inside a wire keepout (a pin there, or where a via
+            # landed) may only be left by another via: a wire from it would
+            # start inside the keepout.
+            blocked = current in self._keepout or current in self._via_only
+            neighbours = () if blocked else self._neighbours
+            for dx, dy in neighbours:
                 cell = (cx + dx, cy + dy)
                 if not (0 <= cell[0] < self.cols and 0 <= cell[1] < self.rows):
                     continue
                 nxt = (*cell, cl)
                 if nxt in goal_stub:  # a pin end; a zone end is entered normally
+                    if nxt in self._keepout or nxt in self._via_only:
+                        continue  # a pin inside a keepout is reached by a via only
                     enter = goal_stub[nxt]
                 else:
                     enter = self._enter_cost(cell, cl, net_no, allow_ripup, conns)
                     if enter is None:
                         continue
+                    if self._doorways:
+                        enter += self._access(nxt, net_no)
                 step = 1.0 if dx == 0 or dy == 0 else math.sqrt(2)
                 self._relax(
                     current, nxt, base + step + enter, goal_cell, g_score, came_from, open_heap
                 )
             if len(self.layers) > 1:
                 g_via = base + self.via_cost
+                if self._doorways:
+                    g_via += self._access(current, net_no)
                 for layer in self.layers:
                     if layer == cl:
                         continue
@@ -512,7 +542,27 @@ class GridRouter:
             if _point_segment(self._cell_center(c), pin_location, end) < reach
         ]
 
-    def _stub_clear(self, pin: Pin, cell: Cell, layer: int, net_no: int, conns) -> bool:
+    def _stub_clear(
+        self, pin: Pin, cell: Cell, layer: int, net_no: int, conns, keepouts_only: bool = False
+    ) -> bool:
+        keepouts = self._keepout_boxes.get(layer)
+        if keepouts:
+            # the stub is off the grid, so check it exactly, as the exact
+            # engine will: its copper grown by clearance must miss every keepout
+            from freeroute.geometry.polyline import Polyline, PolylineShape
+
+            end = self._cell_center(cell)
+            if end != pin.location:
+                for tile in PolylineShape(Polyline([pin.location, end]), self.half_width).tiles():
+                    grown = tile.offset(self.clearance)
+                    if any(k.overlaps(grown if needs else tile) for k, needs in keepouts):
+                        return False
+                # the track's round end at the pin, for a rule area
+                cap = corner_box(pin.location, self.half_width)
+                if any(not needs and k.overlaps(cap) for k, needs in keepouts):
+                    return False
+        if keepouts_only:
+            return True
         for c in self._stub_cells(pin.location, cell):
             owner = self._cell_owner.get((*c, layer))
             if owner is not None and conns[owner].net_no != net_no:
@@ -618,6 +668,13 @@ class GridRouter:
             nodes |= self._escape_nodes(pin, net_no, conns, layers, (cx, cy))
         if not nodes:  # nothing clear: fall back to the nearest cell, as before
             nodes = {(cx, cy, layer) for layer in layers}
+            if self._keepout_boxes and not any(
+                self._stub_clear(pin, (cx, cy), layer, net_no, conns, keepouts_only=True)
+                for layer in layers
+            ):
+                # no wire can reach the pin without entering a keepout: the
+                # route has to arrive by a via, which goes in the pad
+                self._via_only.update(nodes)
         return nodes
 
     def _crowded(self, pin: Pin, net_no: int) -> bool:
@@ -765,8 +822,21 @@ class GridRouter:
                 if node not in self._cell_owner:
                     self._cell_owner[node] = conn.index
                     conn.trace_cells.append((c, layer))
+        # A pin inside a wire keepout can only leave by a via. Its stub to the
+        # cell centre would be track inside the keepout, so the via goes on
+        # the pin itself (a via in its own pad) and the stub is left out.
+        in_pad: dict[int, IntPoint] = {}
+        if len(wire_segs) > 1:
+            for idx, pin in ((0, conn.a_end), (len(wire_segs) - 1, conn.b_end)):
+                layer, cells = wire_segs[idx]
+                node = (*cells[0], layer)
+                walled = node in self._keepout or node in self._via_only
+                if isinstance(pin, Pin) and len(cells) == 1 and walled:
+                    in_pad[idx] = pin.location
         conn.wires = []
         for idx, (layer, cells) in enumerate(wire_segs):
+            if idx in in_pad:
+                continue
             points = [self._cell_center(c) for c in cells]
             if idx == 0 and isinstance(conn.a_end, Pin):
                 points.insert(0, conn.a_end.location)
@@ -776,7 +846,11 @@ class GridRouter:
             if len(points) >= 2:
                 conn.wires.append((layer, points))
         conn.vias = [self._cell_center(c) for c in conn.via_cells]
+        for idx, location in in_pad.items():
+            # via k joins wire segments k and k + 1
+            conn.vias[0 if idx == 0 else idx - 1] = location
         conn.routed = True
+        self._settle(conn, -1)
 
     def _rip(self, conn: _Connection) -> None:
         for cell, layer in conn.trace_cells:
@@ -799,6 +873,7 @@ class GridRouter:
         conn.vias = []
         conn.routed = False
         conn.rip_count += 1
+        self._settle(conn, +1)
 
     def _crossed_owners(self, path: list[Node], net_no: int, conns: list[_Connection]) -> set[int]:
         owners: set[int] = set()
@@ -814,6 +889,50 @@ class GridRouter:
                     owners.add(i)
         return owners
 
+    # --- pin access ---------------------------------------------------------
+
+    @staticmethod
+    def _group_pins(conn: _Connection):
+        return [*conn.a_group[0], *conn.b_group[0]]
+
+    def _build_doorways(self, conns: list[_Connection]) -> None:
+        """Map every cell that would close a pin's way out to that pin."""
+        spread = [(0, 0), *self._halo_offsets]
+        done: set[int] = set()
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                self._pending[id(pin)] = self._pending.get(id(pin), 0) + 1
+                if id(pin) in done:
+                    continue
+                done.add(id(pin))
+                claim = (id(pin), conn.net_no)
+                exits: set[Node] = set()
+                for x, y, layer in self._end_nodes(pin, conn.net_no, conns):
+                    exits.add((x, y, layer))
+                    for c in self._via_cells((x, y)):
+                        exits.update((*c, other) for other in self.layers)
+                cells: set[Node] = set()
+                for x, y, layer in exits:
+                    for dx, dy in spread:
+                        if 0 <= x + dx < self.cols and 0 <= y + dy < self.rows:
+                            cells.add((x + dx, y + dy, layer))
+                for node in cells:
+                    self._doorways.setdefault(node, []).append(claim)
+
+    def _settle(self, conn: _Connection, delta: int) -> None:
+        if not self._pending:
+            return
+        for pin in self._group_pins(conn):
+            if id(pin) in self._pending:
+                self._pending[id(pin)] += delta
+
+    def _access(self, node: Node, net_no: int) -> float:
+        """Extra cost for ``net_no`` to use a cell another pin still needs."""
+        for pin_id, owner_net in self._doorways.get(node, ()):
+            if owner_net != net_no and self._pending.get(pin_id, 0) > 0:
+                return self.access_cost
+        return 0.0
+
     # --- passes -------------------------------------------------------------
 
     def route(self) -> RouteResult:
@@ -822,6 +941,8 @@ class GridRouter:
         self._conns = conns
         if not conns:
             return RouteResult(self.half_width)
+        if self.access_cost:
+            self._build_doorways(conns)
 
         passes = self.max_passes if self.rip_up else 1
         best_count = -1
@@ -1067,6 +1188,7 @@ def route_board(
     heuristic_weight: float = 1.0,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> RouteResult:
     """Convenience wrapper: build a :class:`GridRouter` and route the board."""
     router = GridRouter(
@@ -1084,5 +1206,6 @@ def route_board(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     return router.route()

src/freeroute/route/pipeline.py

@@ -82,6 +82,7 @@ def route_dsn_board(
     max_passes: int = 10,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> 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
@@ -104,6 +105,7 @@ def route_dsn_board(
         max_passes=max_passes,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     return result, scale, [layer.name for layer in dsn.layers]
 
@@ -146,12 +148,14 @@ def build_routing_result(
     edge_clearance_mm: float | None = None,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> 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,
         edge_clearance_mm=edge_clearance_mm, resolution=resolution, seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     return _to_routing_result(route, dsn, scale, layer_names)
 
@@ -169,6 +173,7 @@ def route_dsn_board_exact(
     diagonal: bool = False,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> 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.
@@ -195,6 +200,7 @@ def route_dsn_board_exact(
         diagonal=diagonal,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     return exact, scale, [layer.name for layer in dsn.layers]
 
@@ -212,6 +218,7 @@ def build_exact_routing_result(
     edge_clearance_mm: float | None = None,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
 ) -> RoutingResult:
     """Route ``dsn`` (exact track) and convert to a DSN-unit RoutingResult."""
     exact, scale, layer_names = route_dsn_board_exact(
@@ -226,6 +233,7 @@ def build_exact_routing_result(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
     )
     return _to_routing_result(exact.result, dsn, scale, layer_names)
 

tests/board/test_build.py

@@ -254,3 +254,37 @@ 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/test_cli.py

@@ -157,6 +157,7 @@ def test_cli_supported_combinations_are_accepted(tmp_path):
         "seed": ["--seed", "3"],
         "orders": ["--orders", "2"],
         "promote": ["--promote-failures", "2"],
+        "access": ["--access-cost", "5"],
     }
     for engine, options in ENGINE_OPTIONS.items():
         for option in options: