traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/kicad/escape.py

@@ -0,0 +1,1410 @@
+"""Dense-package escape: fan-out vias and stubs for fine-pitch parts, placed before routing.
+
+A grid router cannot find the way out of a 0.4 or 0.5 mm QFN/QFP ring, or out of a 0.8 mm
+BGA, by itself: a via needs about twice the pad pitch, so neighbouring pins have to leave in
+a staggered pattern. This module plans that pattern with exact geometry (no grid) and writes
+it to the board as ordinary tracks and vias; the router then starts from the via of each
+pin (``attach_fanout``) instead of from the pad.
+
+Packages handled (found from the pad geometry, not from names):
+
+* **Perimeter parts** (QFN, QFP, fine-pitch board-to-board connectors on two or four sides):
+  pads in rows with a long axis pointing away from the part. Every ``m``-th pin (``m`` is the
+  fewest rows whose lanes fit, 3 at 0.5 mm pitch) shares a *row* of vias at one distance from
+  the part; the stubs of the pins behind them run out through the lanes between the vias of the
+  inner rows, in 45 degree jogs, and end in a via of their own row. The lane arithmetic is in
+  ``_rows_needed``; every stub and via is then checked exactly. Pins the pattern does not
+  serve get the nearest legal dogbone; with ``via_in_pad`` a pin whose pad can hold a via gets
+  the via in the pad. A part whose pitch is too fine for the rules is left alone (single vias
+  would only block the router) and the report says what clearance it would need.
+* **BGAs** (square pads on a grid): the outer two rings break out on the surface through the
+  channels between balls to lanes outside the part, where the same row pattern places their
+  vias; balls further in get a dogbone on the lattice point between four balls, or a via in the
+  pad. Through vias block every layer, so a fully populated 0.8 mm BGA escapes about three
+  rings at the fab's rules; pins that do not fit are reported.
+
+Sizes come from the board: the project's design rules (the fab profile written by the
+generator), the net classes and the router options. Every stub and via is checked against all
+copper with the clearance rules of the nets involved, the hole clearance and the board edge.
+
+Escape layers: each pin's via spans all layers; ``Fanout.layer_hint`` assigns the inner signal
+layers to rings in turn, which the router uses as a soft preference when it leaves the via.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge.fab import FabProfile, get_fab
+from traceforge.kicad import edit
+from traceforge.kicad.pcb import Board, Footprint, Pad, read_board
+from traceforge.kicad.routegeom import Shape, SpatialIndex
+
+_EPS = 1e-6
+_MARGIN = 0.005  # KiCad measures round copper as polygons; keep this much beyond the rule
+
+
+# ---------------------------------------------------------------------------- data
+@dataclass
+class Fanout:
+    """One pin's escape: a stub on the pad's layer and (usually) a via at its end."""
+
+    reference: str
+    pad: str
+    net: str
+    layer: str
+    points: list[tuple[float, float]]  # stub centreline from the pad centre; empty: via in pad
+    width: float
+    via: tuple[float, float, float, float] | None  # x, y, size, drill
+    style: str  # dogbone | via-in-pad | surface
+    ring: int = 0
+    layer_hint: str | None = None
+
+
+@dataclass
+class EscapeReport:
+    packages: list[dict] = field(default_factory=list)
+    fanouts: list[Fanout] = field(default_factory=list)
+    unplaced: list[tuple[str, str, str]] = field(default_factory=list)  # ref, pad, reason
+    seconds: float = 0.0
+
+    @property
+    def layer_hints(self) -> dict[tuple[str, str], str]:
+        return {
+            ("~FANOUT", f"{f.reference}.{f.pad}"): f.layer_hint
+            for f in self.fanouts
+            if f.layer_hint
+        }
+
+    def to_dict(self) -> dict:
+        groups: dict[tuple[str, str], list[str]] = {}
+        for ref, pad, why in self.unplaced:
+            groups.setdefault((ref, why), []).append(pad)
+        return {
+            "packages": self.packages,
+            "vias": sum(1 for f in self.fanouts if f.via),
+            "pins_fanned_out": len(self.fanouts),
+            "pins_not_placed": [
+                {"part": ref, "pins": pads, "why": why} for (ref, why), pads in groups.items()
+            ],
+            "seconds": round(self.seconds, 2),
+        }
+
+
+@dataclass
+class EscapeOptions:
+    clearance: float = 0.2
+    track_width: float = 0.25
+    min_track_width: float = 0.15
+    via_size: float = 0.6
+    via_drill: float = 0.3
+    edge_clearance: float = 0.5
+    hole_clearance: float = 0.25
+    via_in_pad: bool = False
+    fab: FabProfile = field(default_factory=lambda: get_fab("jlcpcb"))
+    net_clearance: dict[str, float] = field(default_factory=dict)
+    net_width: dict[str, float] = field(default_factory=dict)
+    plane_nets: frozenset[str] = frozenset()
+    signal_layers: tuple[str, ...] = ()
+    nets: tuple[str, ...] | None = None  # fan out only these nets
+    skip_nets: tuple[str, ...] = ()
+    max_pitch_perimeter: float = 0.55  # 0.5 mm parts and finer
+    max_pitch_grid: float = 1.0
+    min_perimeter_pins: int = 20  # a USB-C receptacle is not a candidate
+
+    def via_tiers(self) -> list[tuple[float, float]]:
+        """Via sizes to try, largest first: the board's own, then the fab's smallest."""
+        fab = self.fab
+        small_drill = max(fab.min_drill, 0.0)
+        small = max(fab.min_via_diameter, small_drill + 2 * fab.min_annular_ring + 0.01)
+        tiers = [(self.via_size, self.via_drill)]
+        if small < self.via_size - 0.01:
+            tiers.append((round(small, 3), small_drill))
+        return tiers
+
+    def stub_widths(self, net: str) -> list[float]:
+        want = max(self.net_width.get(net, 0.0), self.track_width)
+        widths = [want, self.track_width, self.min_track_width, self.fab.min_track]
+        out: list[float] = []
+        for w in widths:
+            w = max(w, self.fab.min_track)
+            if not any(abs(w - o) < 1e-9 for o in out):
+                out.append(w)
+        return sorted(out, reverse=True)
+
+
+# ------------------------------------------------------------------- project rules
+def _project(pcb: Path) -> dict:
+    try:
+        return json.loads(pcb.with_suffix(".kicad_pro").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def options_for(pcb: Path, route_options, copper_layers: list[str]) -> EscapeOptions:
+    """Escape options from the router options and the project's design rules."""
+    data = _project(pcb)
+    rules = ((data.get("board") or {}).get("design_settings") or {}).get("rules") or {}
+    base = get_fab(getattr(route_options, "fab", None))
+    fab = FabProfile(
+        **{
+            **base.to_dict(),
+            "min_track": float(rules.get("min_track_width") or base.min_track),
+            "min_clearance": float(rules.get("min_clearance") or base.min_clearance),
+            "min_via_diameter": float(rules.get("min_via_diameter") or base.min_via_diameter),
+            "min_drill": float(rules.get("min_through_hole_diameter") or base.min_drill),
+            "min_annular_ring": float(rules.get("min_via_annular_width") or base.min_annular_ring),
+        }
+    )
+    settings = data.get("net_settings") or {}
+    classes = {c.get("name"): c for c in settings.get("classes", [])}
+    clearance: dict[str, float] = {}
+    width: dict[str, float] = {}
+    for net, cls in (settings.get("netclass_assignments") or {}).items():
+        info = classes.get(cls) or {}
+        if info.get("clearance"):
+            clearance[net] = float(info["clearance"])
+        if info.get("track_width"):
+            width[net] = float(info["track_width"])
+    roles = ((data.get("traceforge") or {}).get("stackup") or {}).get("roles") or {}
+    planes = ((data.get("traceforge") or {}).get("stackup") or {}).get("planes") or {}
+    plane_layers = {n for n, r in roles.items() if r == "plane"} | set(planes)
+    signal = tuple(n for n in copper_layers if n not in plane_layers)
+    layers = getattr(route_options, "layers", None)
+    if layers:
+        signal = tuple(n for n in layers if n in copper_layers)
+    plane_nets = set(getattr(route_options, "plane_nets", []) or []) | {
+        str(n) for n in planes.values()
+    }
+    assigned = getattr(route_options, "plane_assign", None)
+    if assigned:
+        plane_nets |= set(assigned)
+    return EscapeOptions(
+        clearance=route_options.clearance,
+        track_width=route_options.track_width,
+        min_track_width=min(route_options.min_track_width, route_options.track_width),
+        via_size=route_options.via_size,
+        via_drill=route_options.via_drill,
+        edge_clearance=route_options.edge_clearance,
+        hole_clearance=route_options.hole_clearance,
+        via_in_pad=route_options.via_in_pad,
+        fab=fab,
+        net_clearance=clearance,
+        net_width=width,
+        plane_nets=frozenset(plane_nets),
+        signal_layers=signal,
+        nets=tuple(route_options.nets) if route_options.nets is not None else None,
+        skip_nets=tuple(route_options.skip_nets),
+    )
+
+
+# --------------------------------------------------------------------------- world
+def _pad_shape(pad: Pad, net: int, layers: int) -> Shape:
+    hw, hh = pad.width / 2, pad.height / 2
+    if pad.shape == "circle":
+        r = min(hw, hh)
+        return Shape.capsule(pad.x, pad.y, pad.x, pad.y, r, net, layers, None)
+    if pad.shape == "oval":
+        if hw >= hh:
+            return Shape.capsule(pad.x - hw + hh, pad.y, pad.x + hw - hh, pad.y, hh, net, layers)
+        return Shape.capsule(pad.x, pad.y - hh + hw, pad.x, pad.y + hh - hw, hw, net, layers)
+    return Shape.rect(pad.x - hw, pad.y - hh, pad.x + hw, pad.y + hh, net, layers)
+
+
+class _World:
+    """All copper on the board as exact shapes, plus what the plan adds."""
+
+    def __init__(self, board: Board, opt: EscapeOptions):
+        self.opt = opt
+        self.board = board
+        self.layers = list(board.copper_layers)
+        self.bit = {name: 1 << i for i, name in enumerate(self.layers)}
+        self.all = (1 << len(self.layers)) - 1
+        self.ids: dict[str, int] = {}
+        self.index = SpatialIndex()
+        self.names: dict[int, str] = {}
+        self.holes: dict[tuple[int, int], list[tuple[float, float, float]]] = {}
+        self.hole_r: dict[int, float] = {}  # shape id -> drill radius, for vias
+        self.log: list[tuple] = []  # what the plan added, to roll back a trial
+        self.outline = board.outline
+        self.geom = board.edge_geometry
+        self.max_clear = max([opt.clearance, *opt.net_clearance.values()])
+        hole_extra = max(0.0, opt.hole_clearance - opt.clearance)
+        for fp in board.footprints:
+            for pad in fp.pads:
+                nid = self.nid(pad.net)
+                if pad.kind == "np_thru_hole":
+                    r = max(max(pad.width, pad.height) / 2, pad.drill / 2 + hole_extra)
+                    self.index.add(Shape.capsule(pad.x, pad.y, pad.x, pad.y, r, 0, self.all))
+                else:
+                    mask = 0
+                    for name, bit in self.bit.items():
+                        if pad.on_layer(name):
+                            mask |= bit
+                    if mask:
+                        self.index.add(_pad_shape(pad, nid, mask))
+                if pad.drill:
+                    self._add_hole(pad.x, pad.y, pad.drill)
+        for track in board.tracks:
+            bit = self.bit.get(track.layer)
+            if bit:
+                self.index.add(
+                    Shape.capsule(
+                        track.x1,
+                        track.y1,
+                        track.x2,
+                        track.y2,
+                        track.width / 2,
+                        self.nid(track.net),
+                        bit,
+                    )
+                )
+        for via in board.vias:
+            self._add_via(via.x, via.y, via.size, via.drill, self.nid(via.net))
+
+    def nid(self, net: str) -> int:
+        if not net:
+            return 0
+        if net not in self.ids:
+            self.ids[net] = len(self.ids) + 1
+            self.names[self.ids[net]] = net
+        return self.ids[net]
+
+    def _add_hole(self, x: float, y: float, drill: float) -> None:
+        key = (int(x // 2), int(y // 2))
+        self.holes.setdefault(key, []).append((x, y, drill))
+        self.log.append(("hole", (key, (x, y, drill))))
+
+    def _add_shape(self, shape: Shape) -> None:
+        self.index.add(shape)
+        self.log.append(("shape", shape))
+
+    def checkpoint(self) -> int:
+        return len(self.log)
+
+    def rollback(self, mark: int) -> None:
+        while len(self.log) > mark:
+            kind, item = self.log.pop()
+            if kind == "shape":
+                self.index.remove(item)
+                self.hole_r.pop(id(item), None)
+            else:
+                key, tup = item
+                self.holes[key].remove(tup)
+
+    def unlog(self, entries: list) -> None:
+        """Take specific earlier additions back out (not just the latest ones)."""
+        for entry in entries:
+            for i in range(len(self.log) - 1, -1, -1):
+                if self.log[i] is entry:
+                    del self.log[i]
+                    break
+            kind, item = entry
+            if kind == "shape":
+                self.index.remove(item)
+                self.hole_r.pop(id(item), None)
+            else:
+                key, tup = item
+                self.holes[key].remove(tup)
+
+    def clear(self, a: str, b: str) -> float:
+        nc = self.opt.net_clearance
+        return max(self.opt.clearance, nc.get(a, 0.0), nc.get(b, 0.0)) + _MARGIN
+
+    # -- adding
+    def _add_via(self, x, y, size, drill, nid) -> None:
+        shape = Shape.capsule(x, y, x, y, size / 2, nid, self.all)
+        self.hole_r[id(shape)] = drill / 2
+        self._add_shape(shape)
+        self._add_hole(x, y, drill)
+
+    def add_via(self, x: float, y: float, size: float, drill: float, net: str) -> None:
+        self._add_via(x, y, size, drill, self.nid(net))
+
+    def add_poly(self, points, width: float, layer: str, net: str) -> None:
+        for (ax, ay), (bx, by) in zip(points, points[1:]):
+            self._add_shape(
+                Shape.capsule(ax, ay, bx, by, width / 2, self.nid(net), self.bit[layer])
+            )
+
+    # -- queries
+    def edge_ok(self, x: float, y: float, margin: float) -> bool:
+        return self.geom.room(x, y) >= margin - _EPS
+
+    def via_ok(self, x: float, y: float, size: float, drill: float, net: str) -> bool:
+        opt = self.opt
+        if not self.edge_ok(x, y, opt.edge_clearance + size / 2):
+            return False
+        nid = self.ids.get(net, 0)
+        names = self.names
+        reach = size / 2 + self.max_clear + opt.hole_clearance + 0.2
+        for shape in self.index.near((x, y, x, y), reach):
+            if nid and shape.net == nid:
+                continue
+            other = names.get(shape.net, "")
+            d = shape.dist_point(x, y)
+            need = max(self.clear(net, other) + size / 2, drill / 2 + opt.hole_clearance)
+            if d < need - _EPS:
+                return False
+            drill_r = self.hole_r.get(id(shape))
+            if (
+                drill_r is not None
+                and d + shape.c[4] - drill_r - size / 2 < opt.hole_clearance - _EPS
+            ):
+                return False
+        cx, cy = int(x // 2), int(y // 2)
+        for gx in (cx - 1, cx, cx + 1):
+            for gy in (cy - 1, cy, cy + 1):
+                for hx, hy, hd in self.holes.get((gx, gy), ()):
+                    if math.hypot(hx - x, hy - y) < (hd + drill) / 2 + opt.hole_clearance - _EPS:
+                        return False
+        return True
+
+    def seg_ok(self, ax, ay, bx, by, width: float, layer: str, net: str) -> bool:
+        opt = self.opt
+        half = width / 2
+        margin = opt.edge_clearance + half
+        if not (self.edge_ok(ax, ay, margin) and self.edge_ok(bx, by, margin)):
+            return False
+        bit = self.bit[layer]
+        nid = self.ids.get(net, 0)
+        names = self.names
+        reach = half + self.max_clear + opt.hole_clearance + 0.2
+        bbox = (min(ax, bx), min(ay, by), max(ax, bx), max(ay, by))
+        for shape in self.index.near(bbox, reach):
+            if nid and shape.net == nid:
+                continue
+            other = names.get(shape.net, "")
+            need = 0.0
+            if shape.layers & bit:
+                need = self.clear(net, other) + half
+            dist = shape.dist_seg(ax, ay, bx, by)
+            drill_r = self.hole_r.get(id(shape))
+            if drill_r is not None:  # a via's hole: edge of the hole to the track's edge
+                if dist + shape.c[4] - drill_r - half < opt.hole_clearance - _EPS:
+                    return False
+            if need and dist < need - _EPS:
+                return False
+        return True
+
+    def poly_ok(self, points, width: float, layer: str, net: str) -> bool:
+        return all(
+            self.seg_ok(a[0], a[1], b[0], b[1], width, layer, net)
+            for a, b in zip(points, points[1:])
+        )
+
+
+# ------------------------------------------------------------------- detection
+@dataclass
+class _Package:
+    footprint: Footprint
+    kind: str  # perimeter | grid
+    pitch: float
+    pads: list[Pad]  # netted ring/grid pads, candidates for fan-out
+    layer: str
+    sides: dict[int, tuple[float, float]] = field(default_factory=dict)  # id(pad) -> outward
+    ring: dict[int, int] = field(default_factory=dict)
+    lattice: tuple[list[float], list[float]] | None = None
+
+
+def _pitch(pads: list[Pad]) -> float:
+    """Most common nearest-neighbour distance between pad centres."""
+    if len(pads) < 2:
+        return 0.0
+    counts: dict[float, int] = {}
+    for a in pads:
+        best = min(math.hypot(a.x - b.x, a.y - b.y) for b in pads if b is not a)
+        if best > 1e-3:
+            key = round(best / 0.01) * 0.01
+            counts[key] = counts.get(key, 0) + 1
+    if not counts:
+        return 0.0
+    return max(counts.items(), key=lambda kv: (kv[1], -kv[0]))[0]
+
+
+def _cluster(values: list[float], tol: float = 0.05) -> list[float]:
+    out: list[float] = []
+    for v in sorted(values):
+        if not out or v - out[-1] > tol:
+            out.append(v)
+    return out
+
+
+def detect_packages(board: Board, opt: EscapeOptions) -> list[_Package]:
+    found: list[_Package] = []
+    for fp in board.footprints:
+        smd = [
+            p
+            for p in fp.pads
+            if p.kind == "smd"
+            and p.width > 0
+            and p.height > 0
+            and any(name.endswith(".Cu") for name in p.layers)  # not a paste-only aperture
+        ]
+        if len(smd) < 12:
+            continue
+        layer = "B.Cu" if fp.layer.startswith("B") else "F.Cu"
+        pitch = _pitch(smd)
+        if pitch <= 0:
+            continue
+        ring = [
+            p
+            for p in smd
+            if max(p.width, p.height) >= 1.6 * min(p.width, p.height)
+            and min(p.width, p.height) <= pitch * 0.9
+        ]
+        grid = [
+            p
+            for p in smd
+            if max(p.width, p.height) <= 1.3 * min(p.width, p.height)
+            and max(p.width, p.height) < pitch
+        ]
+        if len(ring) >= opt.min_perimeter_pins and pitch <= opt.max_pitch_perimeter:
+            pkg = _perimeter(fp, ring, pitch, layer)
+            if pkg is not None:
+                found.append(pkg)
+        elif len(grid) >= 16 and pitch <= opt.max_pitch_grid:
+            pkg = _grid(fp, grid, pitch, layer)
+            if pkg is not None:
+                found.append(pkg)
+    return found
+
+
+def _perimeter(fp: Footprint, ring: list[Pad], pitch: float, layer: str) -> _Package | None:
+    cx = sum(p.x for p in ring) / len(ring)
+    cy = sum(p.y for p in ring) / len(ring)
+    sides: dict[int, tuple[float, float]] = {}
+    for p in ring:
+        if p.width >= p.height:
+            sides[id(p)] = (1.0 if p.x >= cx else -1.0, 0.0)
+        else:
+            sides[id(p)] = (0.0, 1.0 if p.y >= cy else -1.0)
+    if len(set(sides.values())) < 2:
+        return None
+    pads = [p for p in ring if p.net]
+    return _Package(fp, "perimeter", pitch, pads, layer, sides)
+
+
+def _grid(fp: Footprint, grid: list[Pad], pitch: float, layer: str) -> _Package | None:
+    xs = _cluster([p.x for p in grid])
+    ys = _cluster([p.y for p in grid])
+    if len(xs) < 4 or len(ys) < 4:
+        return None
+    pkg = _Package(fp, "grid", pitch, [p for p in grid if p.net], layer, lattice=(xs, ys))
+
+    def index(values: list[float], v: float) -> int:
+        return min(range(len(values)), key=lambda i: abs(values[i] - v))
+
+    nx, ny = len(xs), len(ys)
+    for p in grid:
+        ix, iy = index(xs, p.x), index(ys, p.y)
+        pkg.ring[id(p)] = min(ix, iy, nx - 1 - ix, ny - 1 - iy)
+    return pkg
+
+
+# ------------------------------------------------------------------- planning
+def _pad_connected(board: Board, fp: Footprint, pad: Pad) -> bool:
+    for t in board.tracks:
+        if t.net == pad.net and pad.on_layer(t.layer):
+            if pad.contains(t.x1, t.y1, 0.005) or pad.contains(t.x2, t.y2, 0.005):
+                return True
+    for v in board.vias:
+        if v.net == pad.net and pad.contains(v.x, v.y, 0.005):
+            return True
+    return False
+
+
+def _wanted_pads(board: Board, pkg: _Package, opt: EscapeOptions) -> list[Pad]:
+    net_pads: dict[str, int] = {}
+    for fp in board.footprints:
+        for pad in fp.pads:
+            if pad.net:
+                net_pads[pad.net] = net_pads.get(pad.net, 0) + 1
+    out = []
+    for pad in pkg.pads:
+        if opt.nets is not None and pad.net not in opt.nets:
+            continue
+        if pad.net in opt.skip_nets:
+            continue
+        if net_pads.get(pad.net, 0) < 2:
+            continue
+        if _pad_connected(board, pkg.footprint, pad):
+            continue
+        out.append(pad)
+    return out
+
+
+def _hint(opt: EscapeOptions, pad_layer: str, ring: int) -> str | None:
+    """Layer a ring should leave on: the inner signal layers in turn, the far outer layer last."""
+    others = [n for n in opt.signal_layers if n != pad_layer]
+    order = [n for n in others if n not in ("F.Cu", "B.Cu")] + [
+        n for n in others if n in ("F.Cu", "B.Cu")
+    ]
+    return order[ring % len(order)] if order else None
+
+
+@dataclass
+class _Term:
+    """Where a pin's pattern stub starts: the pad itself, or the end of a breakout lane."""
+
+    pad: Pad
+    x: float
+    y: float
+    e: float  # half-length of the copper at (x, y) along the outward axis
+    lat: float  # coordinate across the outward axis
+    lead: list[tuple[float, float]]  # points from the pad centre to (x, y), both included
+
+
+class _Planner:
+    def __init__(self, board: Board, opt: EscapeOptions):
+        self.logs: dict[int, list] = {}
+        self.board = board
+        self.opt = opt
+        self.note = ""  # why pins were left out, for the report
+
+    def _why_not(self, pitch: float) -> str:
+        """What the rules would have to be for the row pattern to fit at this pitch."""
+        opt = self.opt
+        fab = opt.fab
+        via = max(fab.min_via_diameter, fab.min_drill + 2 * fab.min_annular_ring + 0.01)
+        if _rows_needed(pitch, via, opt.clearance + _MARGIN, fab.min_track) is not None:
+            return "other copper near the part leaves no room for the via rows"
+        c = opt.clearance
+        while c > fab.min_clearance - 1e-9:
+            if _rows_needed(pitch, via, c + _MARGIN, fab.min_track) is not None:
+                return (
+                    f"pitch {pitch:g} mm needs about {c:.3f} mm clearance and {via:g} mm vias "
+                    f"(rules here: {opt.clearance:g} mm); set that clearance on the part's nets"
+                )
+            c -= 0.005
+        return (
+            f"pitch {pitch:g} mm is too fine for through vias at the fab's minimum rules; "
+            "it needs via in pad or microvias"
+        )
+
+    # -------------------------------------------------------------- perimeter
+    def perimeter(self, pkg: _Package, pads: list[Pad]) -> tuple[list[Fanout], list[Pad]]:
+        """Fan-out of one perimeter part: (fanouts, pads that did not fit)."""
+        world = _World(self.board, self.opt)
+        sides: dict[tuple[float, float], list[Pad]] = {}
+        for pad in pads:
+            sides.setdefault(pkg.sides[id(pad)], []).append(pad)
+        placed: list[Fanout] = []
+        left: list[Pad] = []
+        for u, items in sides.items():
+            w_axis = (-u[1], u[0])
+            terms = [
+                _Term(
+                    p,
+                    p.x,
+                    p.y,
+                    (p.width if u[0] else p.height) / 2,
+                    p.x * w_axis[0] + p.y * w_axis[1],
+                    [(round(p.x, 4), round(p.y, 4))],
+                )
+                for p in items
+            ]
+            terms.sort(key=lambda t: t.lat)
+            pool: list[dict[str, Fanout]] = []
+            got = self._staggered(world, pkg, u, terms, pkg.pitch, pool)
+            if got and len(got) < len(terms):
+                got = self._best_with_gaps(world, pkg, u, terms, pkg.pitch, pool)
+            for fan in got.values():
+                self._commit(world, fan)
+            if got:
+                self._fill_gaps(world, pkg, u, terms, pkg.pitch, got)
+            if not got and not self.opt.via_in_pad:
+                # No row pattern fits at these rules; single vias would only block the router.
+                left.extend(items)
+                self.note = self._why_not(pkg.pitch)
+                continue
+            missed: list[Pad] = []
+            for pad in items:
+                if pad.number in got:
+                    continue
+                fan = self._dogbone(world, pkg, pad)
+                if fan is None:
+                    missed.append(pad)
+                else:
+                    self._commit(world, fan)
+                    got[pad.number] = fan
+            for pad in missed:
+                if not self._replan(world, pkg, u, terms, got, pad):
+                    left.append(pad)
+            placed.extend(got.values())
+        return placed, left
+
+    def _staggered(
+        self, world, pkg, u, terms, pitch: float, collect: list | None = None
+    ) -> dict[str, Fanout]:
+        """The row pattern: every ``m``-th pin shares a row of vias; the stubs of the outer rows
+        run through the lanes between the vias of the inner ones (see ``_lane_polyline``)."""
+        opt = self.opt
+        best: dict[str, Fanout] = {}
+        for size, drill in opt.via_tiers():
+            for width in opt.stub_widths(""):
+                m = _rows_needed(pitch, size, opt.clearance + _MARGIN, width)
+                if m is None:
+                    continue
+                for offset in range(m):
+                    for d0 in _D0:
+                        for h in _ROW_GAP:
+                            for bf in _ENTRY:
+                                params = (m, offset, d0, h, bf, size, drill, width)
+                                got = self._try_pattern(world, pkg, u, terms, pitch, params)
+                                if collect is not None and got:
+                                    collect.append(got)
+                                if len(got) > len(best):
+                                    best = got
+                                if len(best) == len(terms):
+                                    return best
+            if len(best) >= 0.9 * len(terms):
+                break
+        return best
+
+    def _replan(self, world, pkg, u, terms, got: dict[str, Fanout], pad: Pad) -> bool:
+        """A pin the pattern and the single-pin search both missed: take out the fan-outs of
+        the pins around it, place it first, then place those pins again one by one. Kept only
+        if all of them fit; otherwise the board of copper goes back as it was."""
+        pitch = pkg.pitch
+        by_number = {t.pad.number: t for t in terms}
+        me = by_number.get(pad.number)
+        if me is None:
+            return False
+        near = [
+            n
+            for n, f in got.items()
+            if n in by_number and abs(by_number[n].lat - me.lat) <= 5.01 * pitch
+        ]
+        near.sort(key=lambda n: abs(by_number[n].lat - me.lat))
+        old = {n: got[n] for n in near}
+        for n in near:
+            self._uncommit(world, old[n])
+        pads = {n: by_number[n].pad for n in near}
+        orders = [
+            [pad, *[pads[n] for n in near]],
+            [pad, *[pads[n] for n in reversed(near)]],
+            [*sorted([pad, *pads.values()], key=lambda q: by_number[q.number].lat)],
+            [*sorted([pad, *pads.values()], key=lambda q: -by_number[q.number].lat)],
+            [*[pads[n] for n in near], pad],
+        ]
+        window = [by_number[n] for n in near]
+        window.sort(key=lambda t: t.lat)
+        first = self._dogbone(world, pkg, pad)
+        if first is not None:
+            # The stuck pin first, then the row pattern again for the pins around it.
+            self._commit(world, first)
+            fresh = {pad.number: first}
+            pool = self._staggered(world, pkg, u, window, pitch)
+            for fan in pool.values():
+                self._commit(world, fan)
+            fresh.update(pool)
+            ok = True
+            for t in window:
+                if t.pad.number in fresh:
+                    continue
+                fan = self._dogbone(world, pkg, t.pad)
+                if fan is None:
+                    ok = False
+                    break
+                self._commit(world, fan)
+                fresh[t.pad.number] = fan
+            if ok:
+                got.update(fresh)
+                return True
+            for fan in fresh.values():
+                self._uncommit(world, fan)
+        for order in orders:
+            fresh = {}
+            ok = True
+            for target in order:
+                fan = self._dogbone(world, pkg, target)
+                if fan is None:
+                    ok = False
+                    break
+                self._commit(world, fan)
+                fresh[target.number] = fan
+            if ok:
+                got.update(fresh)
+                return True
+            for fan in fresh.values():
+                self._uncommit(world, fan)
+        for n in near:
+            self._commit(world, old[n])
+        return False
+
+    def _best_with_gaps(self, world, pkg, u, terms, pitch: float, pool) -> dict[str, Fanout]:
+        """Of the row patterns that placed the most pins, the one that places the most once
+        the missed pins have been filled in (a different pattern can leave room for them)."""
+        seen: set[tuple] = set()
+        ranked = []
+        for cand in sorted(pool, key=len, reverse=True):
+            key = tuple(sorted((n, tuple(f.via[:2])) for n, f in cand.items()))
+            if key in seen:
+                continue
+            seen.add(key)
+            ranked.append(cand)
+            if len(ranked) >= 8:
+                break
+        best, best_n = ranked[0], -1
+        for cand in ranked:
+            mark = world.checkpoint()
+            for fan in cand.values():
+                self._commit(world, fan)
+            trial = dict(cand)
+            self._fill_gaps(world, pkg, u, terms, pitch, trial)
+            world.rollback(mark)
+            if len(trial) > best_n:
+                best, best_n = cand, len(trial)
+            if best_n == len(terms):
+                break
+        return dict(best)
+
+    def _fill_gaps(self, world, pkg, u, terms, pitch: float, got: dict[str, Fanout]) -> None:
+        """Pins the best row pattern missed: try every pattern again for just those pins,
+        against the copper already placed (a pin that is boxed in by its neighbours' stubs
+        often fits under a different row offset or entry)."""
+        opt = self.opt
+        for _ in range(len(terms)):
+            missing = {t.pad.number for t in terms if t.pad.number not in got}
+            if not missing:
+                return
+            gained: dict[str, Fanout] = {}
+            for size, drill in opt.via_tiers():
+                for width in opt.stub_widths(""):
+                    m = _rows_needed(pitch, size, opt.clearance + _MARGIN, width)
+                    if m is None:
+                        continue
+                    for offset in range(m):
+                        for d0 in (*_D0, *_D0_FAR):
+                            for h in (*_ROW_GAP, *_ROW_GAP_FAR):
+                                for bf in _ENTRY:
+                                    params = (m, offset, d0, h, bf, size, drill, width)
+                                    gained = self._try_pattern(
+                                        world, pkg, u, terms, pitch, params, only=missing
+                                    )
+                                    if gained:
+                                        break
+                                if gained:
+                                    break
+                            if gained:
+                                break
+                        if gained:
+                            break
+                    if gained:
+                        break
+                if gained:
+                    break
+            if not gained:
+                return
+            for fan in gained.values():
+                self._commit(world, fan)
+            got.update(gained)
+
+    def _try_pattern(
+        self, world, pkg, u, terms, pitch: float, params, only: set[str] | None = None
+    ) -> dict[str, Fanout]:
+        opt = self.opt
+        m, offset, d0, h, bf, size, drill, width = params
+        w_axis = (-u[1], u[0])
+        origin = terms[0].lat
+        mark = world.checkpoint()
+        got: dict[str, Fanout] = {}
+
+        def phase(t: _Term) -> int:
+            return (round((t.lat - origin) / pitch) + offset) % m
+
+        order = sorted(terms, key=lambda t: (0 if t.pad.net in opt.plane_nets else 1, phase(t)))
+        for term in order:
+            pad = term.pad
+            if only is not None and pad.number not in only:
+                continue
+            k = phase(term)
+            clear = world.clear(pad.net, "")
+            half = size / 2 + clear + width / 2
+            lanes = []
+            for j in range(k):
+                row_lat = -(k - j) * pitch  # lateral of the row-j via before this pin
+                lo, hi = row_lat + half, row_lat + m * pitch - half
+                n = m - 1 - j
+                idx = k - j - 1
+                lanes.append((lo + hi) / 2 if n == 1 else lo + idx * (hi - lo) / (n - 1))
+            rows = [term.e + d0 + j * h for j in range(k + 1)]
+            local = _lane_polyline(term.e, rows, lanes, bf)
+            poly = [
+                (
+                    round(term.x + u[0] * r + w_axis[0] * lat, 4),
+                    round(term.y + u[1] * r + w_axis[1] * lat, 4),
+                )
+                for r, lat in local
+            ]
+            vx, vy = poly[-1]
+            if not world.via_ok(vx, vy, size, drill, pad.net):
+                continue
+            points = _clean(term.lead + poly[1:])
+            if not world.poly_ok(points, width, pkg.layer, pad.net):
+                continue
+            fan = Fanout(
+                pkg.footprint.reference,
+                pad.number,
+                pad.net,
+                pkg.layer,
+                points,
+                width,
+                (vx, vy, size, drill),
+                "dogbone",
+            )
+            self._commit(world, fan)
+            got[pad.number] = fan
+        world.rollback(mark)
+        return got
+
+    def _commit(self, world: _World, fan: Fanout) -> None:
+        start = len(world.log)
+        self._commit_raw(world, fan)
+        self.logs[id(fan)] = world.log[start:]
+
+    def _uncommit(self, world: _World, fan: Fanout) -> None:
+        world.unlog(self.logs.pop(id(fan), []))
+
+    def _commit_raw(self, world: _World, fan: Fanout) -> None:
+        if fan.points:
+            world.add_poly(fan.points, fan.width, fan.layer, fan.net)
+        if fan.via:
+            x, y, size, drill = fan.via
+            world.add_via(x, y, size, drill, fan.net)
+
+    def _dogbone(self, world: _World, pkg: _Package, pad: Pad) -> Fanout | None:
+        """One pin on its own: the nearest legal via, straight out or after one 45 degree jog."""
+        opt = self.opt
+        u = pkg.sides[id(pad)]
+        w = (-u[1], u[0])
+        e = (pad.width if u[0] else pad.height) / 2
+        cx, cy = pad.x, pad.y
+        layer = pkg.layer
+
+        def at(r: float, lat: float) -> tuple[float, float]:
+            return (round(cx + u[0] * r + w[0] * lat, 4), round(cy + u[1] * r + w[1] * lat, 4))
+
+        for size, drill in opt.via_tiers():
+            if opt.via_in_pad:
+                fan = self._via_in_pad(world, pkg, pad, size, drill)
+                if fan is not None:
+                    return fan
+            cands = []
+            t = e + 0.15
+            while t <= e + 7.0:
+                for o in _OFFSETS:
+                    cands.append((t + 0.414 * abs(o) + (0.15 if o else 0.0), t, o))
+                t += 0.05
+            cands.sort()
+            widths = opt.stub_widths(pad.net)
+            seg_memo: dict[tuple, bool] = {}
+
+            def seg_ok(a, b, width, seg_memo=seg_memo):
+                key = (a, b, width)
+                if key not in seg_memo:
+                    seg_memo[key] = world.seg_ok(a[0], a[1], b[0], b[1], width, layer, pad.net)
+                return seg_memo[key]
+
+            dbg = {"cands": len(cands), "via_bad": 0, "stub_bad": 0}
+            for _cost, t, o in cands:
+                vx, vy = at(t, o)
+                if not world.via_ok(vx, vy, size, drill, pad.net):
+                    dbg["via_bad"] += 1
+                    continue
+                for poly in _stubs(at, e, t, o):
+                    segs = list(zip(poly, poly[1:]))
+                    if not all(seg_ok(a, b, widths[-1]) for a, b in segs):
+                        dbg["stub_bad"] += 1
+                        continue  # not even the narrowest stub fits
+                    for width in widths:
+                        if all(seg_ok(a, b, width) for a, b in segs):
+                            return Fanout(
+                                pkg.footprint.reference,
+                                pad.number,
+                                pad.net,
+                                layer,
+                                poly,
+                                width,
+                                (vx, vy, size, drill),
+                                "dogbone",
+                            )
+            if os.environ.get("TF_ROUTE_DEBUG"):
+                print("  dogbone fail", pad.number, pad.net, size, widths, dbg, flush=True)
+                run = 0.0
+                tt = e
+                while tt <= e + 7.0:
+                    x2, y2 = at(tt, 0.0)
+                    if not world.seg_ok(cx, cy, x2, y2, widths[-1], layer, pad.net):
+                        break
+                    run = tt - e
+                    tt += 0.05
+                vias_ok = [
+                    round(t2, 2)
+                    for t2 in [e + 0.15 + 0.1 * k for k in range(70)]
+                    if world.via_ok(*at(t2, 0.0), size, drill, pad.net)
+                ]
+                print(
+                    "   straight stub clear for",
+                    round(run, 2),
+                    "mm; via ok at t:",
+                    vias_ok[:20],
+                    flush=True,
+                )
+                px, py = at(e + run + 0.1, 0.0)
+                near = world.index.near((px - 0.3, py - 0.3, px + 0.3, py + 0.3), 0.4)
+                print(
+                    "   blocked near",
+                    (round(px, 2), round(py, 2)),
+                    [(world.names.get(sh.net, sh.net), [round(v, 2) for v in sh.c]) for sh in near][
+                        :8
+                    ],
+                    flush=True,
+                )
+        return None
+
+    def _via_in_pad(self, world, pkg, pad: Pad, size: float, drill: float) -> Fanout | None:
+        """A via inside the pad when the pad can hold it with the drill clear of the edge."""
+        if min(pad.width, pad.height) < size + 0.05:
+            return None
+        if not world.via_ok(pad.x, pad.y, size, drill, pad.net):
+            return None
+        return Fanout(
+            pkg.footprint.reference,
+            pad.number,
+            pad.net,
+            pkg.layer,
+            [],
+            0.0,
+            (round(pad.x, 4), round(pad.y, 4), size, drill),
+            "via-in-pad",
+        )
+
+    # ------------------------------------------------------------------- grid
+    def grid(self, pkg: _Package, pads: list[Pad]) -> tuple[list[Fanout], list[Pad]]:
+        """BGA: outer rings break out on the surface between balls to lanes outside the part,
+        where the row pattern puts their vias; the other balls get a via in the pad or a
+        dogbone on the lattice point between four balls."""
+        world = _World(self.board, self.opt)
+        assert pkg.lattice is not None
+        xs, ys = pkg.lattice
+        pitch = pkg.pitch
+        radius = max(max(p.width, p.height) for p in pkg.pads) / 2
+        nx, ny = len(xs), len(ys)
+        out_gap = radius + 0.3
+        bound = {
+            (-1.0, 0.0): xs[0] - out_gap,
+            (1.0, 0.0): xs[-1] + out_gap,
+            (0.0, -1.0): ys[0] - out_gap,
+            (0.0, 1.0): ys[-1] + out_gap,
+        }
+        widths = self.opt.stub_widths("")
+        leads: dict[tuple[float, float], list[_Term]] = {}
+        placed: dict[str, Fanout] = {}
+        ring_pads = sorted(
+            (pad for pad in pads if pkg.ring[id(pad)] <= 1),
+            key=lambda p: (pkg.ring[id(p)], p.number),
+        )
+        for pad in ring_pads:
+            ix = min(range(nx), key=lambda i: abs(xs[i] - pad.x))
+            iy = min(range(ny), key=lambda i: abs(ys[i] - pad.y))
+            ring = pkg.ring[id(pad)]
+            dirs = []
+            if ix == ring:
+                dirs.append((-1.0, 0.0))
+            if nx - 1 - ix == ring:
+                dirs.append((1.0, 0.0))
+            if iy == ring:
+                dirs.append((0.0, -1.0))
+            if ny - 1 - iy == ring:
+                dirs.append((0.0, 1.0))
+            options = []
+            for d in dirs:
+                if ring == 0:
+                    options.append((d, 0.0))
+                else:
+                    options.append((d, -0.5 * pitch))
+                    options.append((d, 0.5 * pitch))
+            for d, shift in options:
+                lat_axis = (-d[1], d[0])
+                if shift == 0.0:
+                    first = None
+                    lane = (pad.x, pad.y)
+                else:
+                    first = (
+                        pad.x + d[0] * 0.5 * pitch + lat_axis[0] * shift,
+                        pad.y + d[1] * 0.5 * pitch + lat_axis[1] * shift,
+                    )
+                    lane = first
+                if d[0]:
+                    end = (bound[d], lane[1])
+                else:
+                    end = (lane[0], bound[d])
+                pts = [(round(pad.x, 4), round(pad.y, 4))]
+                if first is not None:
+                    pts.append((round(first[0], 4), round(first[1], 4)))
+                pts.append((round(end[0], 4), round(end[1], 4)))
+                width = next(
+                    (w for w in widths if world.poly_ok(pts, w, pkg.layer, pad.net)),
+                    None,
+                )
+                if width is None:
+                    continue
+                lat = end[0] * lat_axis[0] + end[1] * lat_axis[1]
+                term = _Term(pad, end[0], end[1], 0.0, lat, pts)
+                world.add_poly(pts, width, pkg.layer, pad.net)
+                leads.setdefault(d, []).append(term)
+                placed[pad.number] = Fanout(
+                    pkg.footprint.reference,
+                    pad.number,
+                    pad.net,
+                    pkg.layer,
+                    pts,
+                    width,
+                    None,
+                    "surface",
+                )
+                break
+        # Vias for the lane ends: the row pattern on every side.
+        final: dict[str, Fanout] = {}
+        for d, terms in leads.items():
+            terms.sort(key=lambda t: t.lat)
+            got = self._staggered(world, pkg, d, terms, pitch / 2)
+            for number, fan in got.items():
+                fan.style = "surface+dogbone"
+                self._commit(world, fan)
+                final[number] = fan
+        # A breakout lane that got no via leads nowhere: take it out again.
+        world = _World(self.board, self.opt)
+        for fan in final.values():
+            self._commit(world, fan)
+        # Everything else: via in pad, then a dogbone on a lattice point.
+        left: list[Pad] = []
+        for pad in pads:
+            if pad.number in final:
+                continue
+            fan = self._grid_dogbone(world, pkg, pad, pitch)
+            if fan is None:
+                left.append(pad)
+            else:
+                self._commit(world, fan)
+                final[pad.number] = fan
+        if left:
+            self.note = (
+                f"no dogbone via fits between {pitch:g} mm balls at {self.opt.clearance:g} mm "
+                "clearance and the fab's via sizes: needs via in pad (via_in_pad) or finer rules"
+            )
+        return list(final.values()), left
+
+    def _grid_dogbone(self, world, pkg, pad: Pad, pitch: float) -> Fanout | None:
+        opt = self.opt
+        for size, drill in opt.via_tiers():
+            fan = self._via_in_pad(world, pkg, pad, size, drill) if opt.via_in_pad else None
+            if fan is not None:
+                return fan
+            xs, ys = pkg.lattice  # type: ignore[misc]
+            cx = (xs[0] + xs[-1]) / 2
+            cy = (ys[0] + ys[-1]) / 2
+            options = []
+            for sx in (-1, 1):
+                for sy in (-1, 1):
+                    outward = (pad.x - cx) * sx + (pad.y - cy) * sy
+                    options.append((-outward, sx, sy))
+            options.sort()
+            for _o, sx, sy in options:
+                vx, vy = round(pad.x + sx * pitch / 2, 4), round(pad.y + sy * pitch / 2, 4)
+                if not world.via_ok(vx, vy, size, drill, pad.net):
+                    continue
+                poly = [(round(pad.x, 4), round(pad.y, 4)), (vx, vy)]
+                for width in opt.stub_widths(pad.net):
+                    if world.poly_ok(poly, width, pkg.layer, pad.net):
+                        return Fanout(
+                            pkg.footprint.reference,
+                            pad.number,
+                            pad.net,
+                            pkg.layer,
+                            poly,
+                            width,
+                            (vx, vy, size, drill),
+                            "dogbone",
+                        )
+        return None
+
+
+_D0 = (0.55, 0.75, 1.0)  # first via row: distance beyond the pad end
+_ROW_GAP = (0.9, 1.2, 1.6)  # between via rows
+_D0_FAR = (1.4, 1.9, 2.5, 3.2)  # farther rows, only to place pins the usual rows could not
+_ROW_GAP_FAR = (1.6, 2.2, 3.0)
+_ENTRY = (0.5, 0.35)  # where along a via the stub must be in its lane
+_OFFSETS = [0.0] + [s * k * 0.1 for k in range(1, 11) for s in (1, -1)]
+
+
+def _stubs(at, e: float, t: float, o: float) -> list[list[tuple[float, float]]]:
+    """Stub centrelines from the pad centre to the via at (t, o): straight or one 45 degree jog."""
+    if abs(o) < 1e-9:
+        return [[at(0, 0), at(t, 0)]]
+    polys = []
+    for s in (e + 0.1, e + 0.3, e + 0.6, e + 1.0):
+        if s + abs(o) <= t + 1e-9:
+            polys.append([at(0, 0), at(s, 0), at(s + abs(o), o), at(t, o)])
+    return polys
+
+
+def _clean(points: list[tuple[float, float]], tol: float = 0.02) -> list[tuple[float, float]]:
+    """Drop points that leave a segment shorter than ``tol`` (the last point always stays)."""
+    out = [points[0]]
+    for i, q in enumerate(points[1:], start=1):
+        last = i == len(points) - 1
+        if math.hypot(q[0] - out[-1][0], q[1] - out[-1][1]) < tol:
+            if last and len(out) > 1:
+                out[-1] = q
+            continue
+        out.append(q)
+    return out
+
+
+def _rows_needed(pitch: float, via: float, clearance: float, width: float) -> int | None:
+    """Fewest via rows (3 to 6) whose lanes carry the tracks of the others, or None.
+
+    Between two vias of the same row (``m`` pitches apart) the ``m - 1`` stubs of the other
+    rows must fit: ``m * pitch - via - 2 * clearance >= (m - 1) * width + (m - 2) * clearance``.
+    """
+    for m in range(3, 7):
+        if m * pitch - via - 2 * clearance >= (m - 1) * width + (m - 2) * clearance - 1e-9:
+            return m
+    return None
+
+
+def _lane_polyline(
+    e: float, rows: list[float], lanes: list[float], entry: float
+) -> list[tuple[float, float]]:
+    """A stub in (radial, lateral) coordinates from the pad centre to the via of its row.
+
+    ``rows[j]`` is the radial position of via row ``j``; the stub is in lane ``lanes[j]`` while it
+    passes row ``j`` (``entry`` before and after the row's vias) and ends at the pad's own
+    lateral position (0) on row ``len(lanes)``.
+    """
+    pts = [(0.0, 0.0)]
+    r, lat = 0.0, 0.0
+    if lanes:
+        pts.append((e + 0.1, 0.0))
+        r = e + 0.1
+    for j, lane in enumerate(lanes):
+        d = abs(lane - lat)
+        r_fin = rows[j] - entry
+        r0 = max(r, r_fin - d)
+        if r0 > r:
+            pts.append((r0, lat))
+        pts.append((r0 + d, lane))
+        r, lat = r0 + d, lane
+        r_out = max(r, rows[j] + entry)
+        pts.append((r_out, lane))
+        r = r_out
+    d = abs(lat)
+    target = rows[len(lanes)]
+    r0 = max(r, target - d)
+    if r0 > r:
+        pts.append((r0, lat))
+    pts.append((r0 + d, 0.0))
+    out = [pts[0]]
+    for q in pts[1:]:
+        if math.hypot(q[0] - out[-1][0], q[1] - out[-1][1]) > 1e-9:
+            out.append(q)
+    return out
+
+
+# ----------------------------------------------------------------------- driver
+def plan(board: Board, opt: EscapeOptions) -> EscapeReport:
+    """Plan the fan-out of every dense package on ``board`` (nothing is written)."""
+    import time
+
+    started = time.monotonic()
+    report = EscapeReport()
+    planner = _Planner(board, opt)
+    for pkg in detect_packages(board, opt):
+        pads = _wanted_pads(board, pkg, opt)
+        info = {
+            "reference": pkg.footprint.reference,
+            "kind": "grid (BGA)" if pkg.kind == "grid" else "perimeter (QFN/QFP/connector)",
+            "pitch_mm": round(pkg.pitch, 3),
+            "pins": len(pads),
+        }
+        if not pads:
+            continue
+        if pkg.kind == "perimeter":
+            placed, left = planner.perimeter(pkg, pads)
+        else:
+            placed, left = planner.grid(pkg, pads)
+        for fan in placed:
+            fan.ring = _ring_of(pkg, fan)
+            fan.layer_hint = _hint(opt, fan.layer, fan.ring) if fan.via else None
+        report.fanouts.extend(placed)
+        for pad in left:
+            why = planner.note or "no legal stub and via at these rules"
+            report.unplaced.append((pkg.footprint.reference, pad.number, why))
+        planner.note = ""
+        info["placed"] = len(placed)
+        info["vias"] = sum(1 for f in placed if f.via)
+        report.packages.append(info)
+    report.seconds = time.monotonic() - started
+    return report
+
+
+def _ring_of(pkg: _Package, fan: Fanout) -> int:
+    if pkg.kind == "grid":
+        pad = next((p for p in pkg.footprint.pads if p.number == fan.pad), None)
+        return pkg.ring.get(id(pad), 0) if pad is not None else 0
+    if not fan.via or not fan.points:
+        return 0
+    x0, y0 = fan.points[0]
+    dist = math.hypot(fan.via[0] - x0, fan.via[1] - y0)
+    return int(max(0.0, dist - 0.5) // 0.6)
+
+
+def apply(pcb: Path, report: EscapeReport) -> int:
+    """Write the planned stubs and vias into the board file."""
+    tracks = [(f.net, f.layer, f.width, f.points) for f in report.fanouts if len(f.points) > 1]
+    if tracks:
+        edit.pcb_add_routing(pcb, tracks, [], 0.6, 0.3)
+    by_size: dict[tuple[float, float], list[tuple[str, float, float]]] = {}
+    for f in report.fanouts:
+        if f.via:
+            by_size.setdefault((f.via[2], f.via[3]), []).append((f.net, f.via[0], f.via[1]))
+    for (size, drill), vias in by_size.items():
+        edit.pcb_add_routing(pcb, [], vias, size, drill)
+    return len(tracks) + sum(len(v) for v in by_size.values())
+
+
+def fan_out(pcb: str | Path, route_options, enabled: bool | None = None) -> EscapeReport:
+    """Plan and write the fan-out of dense packages. ``enabled``: None switches it on from
+    four copper layers up (two-layer boards keep their pads as they are)."""
+    pcb = Path(pcb)
+    board = read_board(pcb)
+    if enabled is None:
+        enabled = len(board.copper_layers) >= 4
+    if not enabled or board.outline is None:
+        return EscapeReport()
+    opt = options_for(pcb, route_options, board.copper_layers)
+    report = plan(board, opt)
+    if report.fanouts:
+        apply(pcb, report)
+    return report
+
+
+# ------------------------------------------------------------- router handover
+_TOL = 0.002
+
+
+def attach_fanout(board: Board) -> set[int]:
+    """Make each fanned-out pin start at the end of its stub.
+
+    A pad whose only copper is a short chain of tracks ending in a via (or free end) gets a
+    stand-in pad at that end, appended to the board in memory as a footprint ``~FANOUT``.
+    Returns the ids of the pads that stand-ins replace; the router treats those as connected.
+    """
+    by_net_tracks: dict[str, list] = {}
+    for t in board.tracks:
+        by_net_tracks.setdefault(t.net, []).append(t)
+    vias_by_net: dict[str, list] = {}
+    for v in board.vias:
+        vias_by_net.setdefault(v.net, []).append(v)
+    replaced: set[int] = set()
+    stand_ins: list[Pad] = []
+    pad_list = [(fp, p) for fp in board.footprints for p in fp.pads if p.net and p.kind == "smd"]
+    all_smd = [p for _fp, p in pad_list]
+    for fp, pad in pad_list:
+        tracks = by_net_tracks.get(pad.net)
+        if not tracks:
+            continue
+        first = [
+            t
+            for t in tracks
+            if pad.on_layer(t.layer)
+            and (pad.contains(t.x1, t.y1, _TOL) or pad.contains(t.x2, t.y2, _TOL))
+        ]
+        if len(first) != 1:
+            continue
+        chain = [first[0]]
+        a = first[0]
+        end = (a.x2, a.y2) if not pad.contains(a.x2, a.y2, _TOL) else (a.x1, a.y1)
+        if pad.contains(a.x1, a.y1, _TOL) and pad.contains(a.x2, a.y2, _TOL):
+            continue
+        ok = True
+        for _ in range(40):
+            if any(
+                math.hypot(v.x - end[0], v.y - end[1]) < _TOL for v in vias_by_net.get(pad.net, [])
+            ):
+                break  # a via ends the stub, or joins it to other copper
+            nxt = [
+                t
+                for t in tracks
+                if t not in chain
+                and t.layer == a.layer
+                and (
+                    math.hypot(t.x1 - end[0], t.y1 - end[1]) < _TOL
+                    or math.hypot(t.x2 - end[0], t.y2 - end[1]) < _TOL
+                )
+            ]
+            if not nxt:
+                break
+            if len(nxt) > 1:
+                ok = False
+                break
+            t = nxt[0]
+            chain.append(t)
+            end = (t.x2, t.y2) if math.hypot(t.x1 - end[0], t.y1 - end[1]) < _TOL else (t.x1, t.y1)
+        if not ok:
+            continue
+        end = (round(end[0], 4), round(end[1], 4))
+        others = [
+            t
+            for t in tracks
+            if t not in chain
+            and (
+                math.hypot(t.x1 - end[0], t.y1 - end[1]) < _TOL
+                or math.hypot(t.x2 - end[0], t.y2 - end[1]) < _TOL
+            )
+        ]
+        via = next(
+            (
+                v
+                for v in vias_by_net.get(pad.net, [])
+                if math.hypot(v.x - end[0], v.y - end[1]) < _TOL
+            ),
+            None,
+        )
+        if others:
+            continue
+        name = f"{fp.reference}.{pad.number}"
+        stub = sum(t.length for t in chain)
+        if via is not None:
+            stand = Pad(
+                name, "thru_hole", "circle", via.x, via.y, via.size, via.size, ["*.Cu"], pad.net
+            )
+            stand.stub_mm = stub  # type: ignore[attr-defined]
+            stand.stub_of = (fp.reference, pad.number)  # type: ignore[attr-defined]
+            stand_ins.append(stand)
+        else:
+            if any(
+                q is not pad and q.on_layer(a.layer) and q.contains(end[0], end[1], _TOL)
+                for q in all_smd
+            ):
+                continue  # runs on to another pad: ordinary routing
+            width = chain[-1].width
+            stand = Pad(
+                name, "thru_hole", "circle", end[0], end[1], width, width, [a.layer], pad.net
+            )
+            stand.stub_mm = stub  # type: ignore[attr-defined]
+            stand.stub_of = (fp.reference, pad.number)  # type: ignore[attr-defined]
+            stand_ins.append(stand)
+        replaced.add(id(pad))
+    if stand_ins:
+        board.footprints.append(
+            Footprint("traceforge:fanout", "~FANOUT", "", 0.0, 0.0, 0.0, "F.Cu", stand_ins)
+        )
+    return replaced