--reserve-escapes: keep a way out open for every fine-pitch pin

Before routing, each crowded pin gets the shortest way from its pad to
open board, found against pads, keepouts and earlier escapes. While the
pin still has connections to route, no other net may put a trace or a
via there, nor within clearance of it; the reservation lifts once the
pin is routed.

bench/diagnose.py

@@ -26,6 +26,7 @@ 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
@@ -80,13 +81,24 @@ def _capture_conflicts() -> list:
     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)
-            other = next(
-                (s for s in self.overlapping(expanded)
-                 if s.net_no != net_no and s.on_layer(layer)
-                 and (s.blocks == "all" or s.blocks == kind + "s")),
-                None,
-            )
+            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
 
@@ -177,10 +189,11 @@ def diagnose(
         if other is None:
             what = "?"
         elif other.net_no == -1:
-            what = "keepout"
+            what = "keepout" if other.clearance else "rule area"
         else:
             what = ("trace/via of " if other.routed else "pad of ") + names.get(other.net_no, "?")
-        short = (clearance - _gap(box, other.tile)) / scale / 1000 if other is not None else 0
+        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)}
         )

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", "access"}),
-    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote", "access"}),
+    "grid": frozenset({"rip_up", "max_passes", "seed", "orders", "promote", "access", "escapes"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote", "access", "escapes"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -46,6 +46,7 @@ _FLAG_NAMES = {
     "orders": "--orders",
     "promote": "--promote-failures",
     "access": "--access-cost",
+    "escapes": "--reserve-escapes",
 }
 
 
@@ -166,6 +167,12 @@ def build_parser() -> argparse.ArgumentParser:
         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(
+        "--reserve-escapes",
+        action="store_true",
+        help="grid and exact engines: before routing, reserve a way out for every fine-pitch "
+        "pin that no other net may use until that pin's connections are routed",
+    )
     parser.add_argument(
         "--jobs",
         type=int,
@@ -195,6 +202,7 @@ def main(argv: list[str] | None = None) -> int:
             ("orders", args.orders is not None),
             ("promote", args.promote_failures is not None),
             ("access", args.access_cost is not None),
+            ("escapes", args.reserve_escapes),
         )
         if asked
     ]
@@ -229,6 +237,7 @@ def main(argv: list[str] | None = None) -> int:
             "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,
+            "reserve_escapes": args.reserve_escapes,
         }
     elif args.engine == "grid":
         options = {
@@ -238,6 +247,7 @@ def main(argv: list[str] | None = None) -> int:
             "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,
+            "reserve_escapes": args.reserve_escapes,
         }
     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
 
@@ -97,6 +98,7 @@ def route_board_exact(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> ExactRouteResult:
     """Route ``board`` orthogonally and verify the result with exact geometry.
 
@@ -128,6 +130,7 @@ def route_board_exact(
         seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     edge = 0 if edge_clearance is None else edge_clearance
     outline = board.outline
@@ -157,7 +160,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)
@@ -178,7 +184,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)
@@ -592,6 +600,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"]
 
@@ -158,6 +159,7 @@ class GridRouter:
         seed: int | None = None,
         route_first: frozenset | None = None,
         access_cost: float = 0.0,
+        reserve_escapes: bool = False,
     ) -> None:
         self.board = board
         # Pin access: while a pin still has connections to route, the cells
@@ -167,6 +169,12 @@ class GridRouter:
         self.access_cost = max(float(access_cost), 0.0)
         self._doorways: dict[Node, list[tuple[int, int]]] = {}
         self._pending: dict[int, int] = {}
+        # Escape reservations: before routing, every crowded (fine-pitch) pin
+        # gets a short way out to open board, and while it still has
+        # connections to route no other net may use those cells (nor come
+        # within clearance of them).
+        self.reserve_escapes = bool(reserve_escapes)
+        self._reserved: dict[Node, list[tuple[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
@@ -298,7 +306,9 @@ class GridRouter:
         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[IntBox]] = {}
+        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
@@ -336,8 +346,12 @@ class GridRouter:
                         continue
                     # the same distance the exact engine verifies against
                     if item.blocks_wires:
-                        self._keepout_boxes.setdefault(item.layer, []).append(box)
-                    for cell in self._cells_in_box(box, margin):
+                        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:
@@ -364,6 +378,10 @@ class GridRouter:
         node = (*cell, layer)
         if wire_keepout and node in self._keepout:
             return None
+        if self._reserved:
+            for pin_id, owner_net in self._reserved.get(node, ()):
+                if owner_net != net_no and self._pending.get(pin_id, 0) > 0:
+                    return None  # another pin's reserved way out
         pads = self._pad_block.get(node)
         if pads and any(n != net_no for n in pads) and net_no not in self._pad_own.get(node, ()):
             return None
@@ -475,12 +493,19 @@ 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)
@@ -528,7 +553,9 @@ 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
@@ -539,8 +566,14 @@ class GridRouter:
             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) for k in keepouts):
+                    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:
@@ -646,6 +679,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:
@@ -800,7 +840,9 @@ class GridRouter:
         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]
-                if isinstance(pin, Pin) and len(cells) == 1 and (*cells[0], layer) in self._keepout:
+                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):
@@ -870,7 +912,6 @@ class GridRouter:
         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))
@@ -888,6 +929,76 @@ class GridRouter:
                 for node in cells:
                     self._doorways.setdefault(node, []).append(claim)
 
+    def _count_pending(self, conns: list[_Connection]) -> None:
+        """How many unrouted connections each pin is an end of."""
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                self._pending[id(pin)] = self._pending.get(id(pin), 0) + 1
+
+    def _reserve_escapes(self, conns: list[_Connection]) -> None:
+        """Give every crowded pin a way out before anything is routed."""
+        blocked: set[Node] = set()  # earlier escapes and their clearance
+        spread = [(0, 0), *self._halo_offsets]
+        seen: set[int] = set()
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                if id(pin) in seen or not self._crowded(pin, conn.net_no):
+                    continue
+                seen.add(id(pin))
+                path = self._escape_path(pin, conn.net_no, conns, blocked)
+                if not path:
+                    continue
+                claim = (id(pin), conn.net_no)
+                for x, y, layer in path:
+                    for dx, dy in spread:
+                        node = (x + dx, y + dy, layer)
+                        if 0 <= node[0] < self.cols and 0 <= node[1] < self.rows:
+                            self._reserved.setdefault(node, []).append(claim)
+                            blocked.add(node)
+
+    def _escape_path(self, pin: Pin, net_no: int, conns, blocked: set[Node]) -> list[Node]:
+        """The shortest way from a pin to a cell clear of other nets' pads,
+        against pads, keepouts and earlier escapes only (breadth first, on
+        the pin's own layers, at most ``2 * _escape_cells`` long)."""
+        starts = [n for n in self._end_nodes(pin, net_no, conns) if n not in blocked]
+        came: dict[Node, Node | None] = dict.fromkeys(starts)
+        frontier = list(starts)
+        limit = 2 * self._escape_cells
+        for _depth in range(limit):
+            nxt: list[Node] = []
+            for node in frontier:
+                if node not in starts and self._open_ground(node, net_no):
+                    path = [node]
+                    while came[path[-1]] is not None:
+                        path.append(came[path[-1]])
+                    return path[::-1]
+                x, y, layer = node
+                for dx, dy in self._neighbours:
+                    n = (x + dx, y + dy, layer)
+                    if n in came or n in blocked:
+                        continue
+                    if not (0 <= n[0] < self.cols and 0 <= n[1] < self.rows):
+                        continue
+                    if not self._static_open(n, net_no):
+                        continue
+                    came[n] = node
+                    nxt.append(n)
+            frontier = nxt
+            if not frontier:
+                break
+        return []
+
+    def _open_ground(self, node: Node, net_no: int) -> bool:
+        """Clear of every other net's pad by a full trace spacing all round."""
+        x, y, layer = node
+        for dx, dy in self._halo_offsets:
+            n = (x + dx, y + dy, layer)
+            if not (0 <= n[0] < self.cols and 0 <= n[1] < self.rows):
+                return False
+            if not self._static_open(n, net_no):
+                return False
+        return True
+
     def _settle(self, conn: _Connection, delta: int) -> None:
         if not self._pending:
             return
@@ -910,8 +1021,12 @@ class GridRouter:
         self._conns = conns
         if not conns:
             return RouteResult(self.half_width)
+        if self.access_cost or self.reserve_escapes:
+            self._count_pending(conns)
         if self.access_cost:
             self._build_doorways(conns)
+        if self.reserve_escapes:
+            self._reserve_escapes(conns)
 
         passes = self.max_passes if self.rip_up else 1
         best_count = -1
@@ -1158,6 +1273,7 @@ def route_board(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RouteResult:
     """Convenience wrapper: build a :class:`GridRouter` and route the board."""
     router = GridRouter(
@@ -1176,5 +1292,6 @@ def route_board(
         seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return router.route()

src/freeroute/route/pipeline.py

@@ -83,6 +83,7 @@ def route_dsn_board(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> 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
@@ -106,6 +107,7 @@ def route_dsn_board(
         seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return result, scale, [layer.name for layer in dsn.layers]
 
@@ -149,6 +151,7 @@ def build_routing_result(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RoutingResult:
     """Route ``dsn`` (grid track) and convert to a DSN-unit RoutingResult."""
     route, scale, layer_names = route_dsn_board(
@@ -156,6 +159,7 @@ def build_routing_result(
         edge_clearance_mm=edge_clearance_mm, resolution=resolution, seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return _to_routing_result(route, dsn, scale, layer_names)
 
@@ -174,6 +178,7 @@ def route_dsn_board_exact(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> 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.
@@ -201,6 +206,7 @@ def route_dsn_board_exact(
         seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return exact, scale, [layer.name for layer in dsn.layers]
 
@@ -219,6 +225,7 @@ def build_exact_routing_result(
     seed: int | None = None,
     route_first: frozenset | None = None,
     access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RoutingResult:
     """Route ``dsn`` (exact track) and convert to a DSN-unit RoutingResult."""
     exact, scale, layer_names = route_dsn_board_exact(
@@ -234,6 +241,7 @@ def build_exact_routing_result(
         seed=seed,
         route_first=route_first,
         access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     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/route/test_escapes.py

@@ -0,0 +1,65 @@
+"""--reserve-escapes: a crowded pin keeps a way out until it is routed."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+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,
+    build_exact_routing_result,
+)
+
+SMD = (Path(__file__).resolve().parent.parent / "dsn" / "fixtures" / "smd_demo.dsn").read_text()
+
+
+def _router():
+    dsn = parse_dsn(SMD)
+    s = dsn.resolution.value
+    router = GridRouter(
+        build_board(dsn),
+        trace_width=round(_rule_width_dsn(dsn) * s),
+        clearance=round(_rule_clearance_dsn(dsn) * s),
+        orthogonal=True,
+        resolution=2,
+        reserve_escapes=True,
+    )
+    conns = router._build_connections()
+    router._conns = conns
+    router._count_pending(conns)
+    router._reserve_escapes(conns)
+    return router, conns
+
+
+def test_a_reserved_escape_is_closed_to_other_nets_and_open_to_its_own():
+    router, conns = _router()
+    assert router._reserved
+    node, claims = next(iter(router._reserved.items()))
+    pin_id, owner = claims[0]
+    other = next(c.net_no for c in conns if c.net_no != owner)
+    cell, layer = node[:2], node[2]
+    assert router._enter_cost(cell, layer, other, True, conns) is None  # even for rip-up
+    assert router._enter_cost(cell, layer, owner, False, conns) is not None or node in router._keepout
+
+
+def test_the_escape_is_released_once_its_pin_is_routed():
+    router, conns = _router()
+    node, claims = next(iter(router._reserved.items()))
+    other = next(c.net_no for c in conns if c.net_no != claims[0][1])
+    cell, layer = node[:2], node[2]
+    assert router._enter_cost(cell, layer, other, False, conns) is None
+    for c in conns:  # every connection routed: no pin is pending any more
+        router._settle(c, -1)
+    released = router._enter_cost(cell, layer, other, False, conns)
+    reserved, router._reserved = router._reserved, {}
+    assert released == router._enter_cost(cell, layer, other, False, conns)
+    router._reserved = reserved
+
+
+def test_reserving_escapes_loses_nothing_on_the_demo_board():
+    plain = build_exact_routing_result(parse_dsn(SMD), resolution=2)
+    reserved = build_exact_routing_result(parse_dsn(SMD), resolution=2, reserve_escapes=True)
+    assert len(reserved.unrouted) <= len(plain.unrouted)

tests/test_cli.py

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