copperhead

import type { Bounds } from '../sexp.js';
import { knum, type PlacementModel, type EmitSymbol } from '../emit.js';
import { powerSymbolSource, pwrFlagSource, type ResolvedSymbol, type DraftPin } from './symsource.js';
import type { SchematicIntent, IntentNet, IntentPart, ValidatedIntent } from './ir.js';

/**
 * The rule-based deterministic drafting engine (design D1/D2). All geometry is
 * computed in integer multiples of the 1.27mm grid, so every pin lands on-grid
 * by construction. No randomness, no clock, no environment-dependent ordering:
 * identical IR yields an identical placement model on every machine.
 */

/** The grid. Every symbol origin and wire endpoint is an integer multiple. */
const U = 1.27;
/** Stub length from a pin to its label/power symbol, in grid units. */
const STUB = 2;
/** Cell margin around a symbol body (room for stubs, labels, text), in units. */
const MARGIN = 6;
/** Vertical gap between rows and horizontal channel between columns, units. */
const ROW_GAP = 4;
const CHANNEL = 8;
/** Gap between group boxes, units. */
const GROUP_GAP = 8;
/** Local nets up to this many endpoints may be wired (design D2). */
const MAX_WIRED_ENDPOINTS = 4;
/** Wire-span budget in mm beyond which a net becomes labels. */
const MAX_WIRE_SPAN = 50.8;
/** Label text metrics, matching the legibility checker's conservative box. */
const LABEL_HEIGHT = 1.27;
const LABEL_ADVANCE = 0.6;
/** How far a colliding label may ride its stub outward, in grid units.
 * Deep enough to carry a bottom-pin label past the routing channel that runs
 * under its connector (#220 phase 2); rungs stay ordered nearest-first, so a
 * label that used to clear at rung n still clears at rung n. */
const MAX_LABEL_NUDGE = 8;
/**
 * How far a power stub may be pulled in or pushed out to clear a foreign
 * connection point, in grid units. Bounded so the symbol stays visibly attached
 * to the pin it serves; past this the merged-net gate is the better answer.
 */
const MAX_POWER_STUB_SHIFT = 4;
/**
 * Fraction of labels allowed to still overlap a foreign net's label text after
 * the de-collision pass has done what it can.
 *
 * Overlapping text boxes and coincident label POINTS are different failures and
 * are treated differently. A shared point merges two nets (`findMergedNets`) and
 * is always refused — the drawn netlist would not be the IR's. Overlapping text
 * is a legibility defect: the sheet is harder to read, the netlist is correct.
 * Refusing a whole draft over the second kind is what turned a real placement
 * bug into a pipeline that could not finish, so a small budget is tolerated,
 * counted, and reported rather than gated.
 */
const LABEL_OVERLAP_BUDGET = 0.02;

const ceilU = (mm: number): number => Math.ceil(mm / U - 1e-9);
const grid = (units: number): number => Math.round(units) * U;

/**
 * Two coordinates are the same POINT iff they emit identically: comparisons and
 * map keys go through `knum`, the emitter's rounding, because KiCad's
 * connectivity sees the rounded file, not the engine's float dust —
 * 13.969999999999999 and 13.97 are one coordinate on the sheet. Raw float keys
 * here would let two distinct nets whose labels differ by dust but emit to the
 * same point evade the merged-net refusal.
 */
const sameCoord = (a: number, b: number): boolean => knum(a) === knum(b);
const pointKey = (x: number, y: number): string => `${knum(x)},${knum(y)}`;

/** Standard landscape sheets, smallest first, for content-derived paper. */
const PAPERS: { name: string; w: number; h: number }[] = [
  { name: 'A5', w: 210, h: 148 },
  { name: 'A4', w: 297, h: 210 },
  { name: 'A3', w: 420, h: 297 },
  { name: 'A2', w: 594, h: 420 },
  { name: 'A1', w: 841, h: 594 },
  { name: 'A0', w: 1189, h: 841 },
];
const FRAME = 10;
const TITLE_STRIP = 30;
/** Max pin-to-pin gap, grid units, for chaining a passive bank on one trunk
 * (#233): wide enough for two-pin parts sitting in adjacent COLUMNS (cell
 * width plus the channel, ~23 units), tight enough that a trunk never spans
 * unrelated structure — and every join is still vetoed by the body-crossing
 * and touches-foreign checks regardless of distance. */
const BANK_PITCH_MAX = 32;
/** Natural-fit utilization below which the paper pass tries smaller sheets
 * with width and height budgets (#220 phase 4). Matches the legibility
 * checker's low-utilization threshold: a sheet the checker would call mostly
 * empty is a sheet worth compacting. */
const COMPACT_UTILIZATION = 0.5;

export type NetClass = 'rail' | 'ground' | 'signal';
/**
 * What decided a net's class: an IR `kind` declaration, the library electrical
 * type of a pin it touches, or the last-resort supply-name shape. Reported per
 * net so a name-inferred class — the one inference no pin actually attests —
 * is visible and correctable through the IR.
 */
export type NetClassBasis = 'declared' | 'pin-type' | 'name';

export interface SchematicDraftReport {
  groups: { name: string; members: string[] }[];
  netClasses: { name: string; class: NetClass; overridden: boolean; basis: NetClassBasis }[];
  wireCount: number;
  labelCount: number;
  pwrFlags: string[];
  noConnects: number;
  paper: string;
  notes: string[];
  /**
   * Points where labels of two or more distinct nets landed together, merging
   * them into one net in the emitted sheet. Non-empty means the drawing does
   * not implement the IR, so the caller must refuse the draft.
   */
  mergedNets: { x: number; y: number; nets: string[]; via?: 'labels' | 'wires' }[];
  /**
   * Labels whose TEXT still overlaps a foreign net's label after de-collision.
   * The netlist is correct — these are legibility defects, tolerated up to
   * `LABEL_OVERLAP_BUDGET` and always reported. Never a reason to refuse.
   */
  labelOverlaps: { x: number; y: number; nets: string[] }[];
  /** Whether `labelOverlaps` exceeded the tolerated fraction of all labels. */
  labelOverlapBudgetExceeded: boolean;
}

/**
 * Points carrying labels for two or more distinct nets.
 *
 * Co-located labels are not a cosmetic overlap: KiCad resolves them to a single
 * net and reports `Both A and B are attached to the same items; A will be used
 * in the netlist` — as a *warning*. A live run drew ISET (charge-current
 * program) and NTC (thermistor input) onto one node of a BQ24040 that way,
 * which would have shipped a board whose charge current is not set by its
 * programming resistor and whose temperature cutoff does not work.
 *
 * The engine computes every coordinate, so this is the engine's to catch, and
 * it is strictly worse than the failures already gated: an unreadable sheet
 * stops the pipeline loudly, a merged net flows quietly into layout and
 * fabrication outputs.
 */
export function findMergedNets(
  labels: { name: string; x: number; y: number }[],
): { x: number; y: number; nets: string[] }[] {
  const byPoint = new Map<string, Set<string>>();
  for (const l of labels) {
    const key = pointKey(l.x, l.y);
    const at = byPoint.get(key) ?? new Set<string>();
    at.add(l.name);
    byPoint.set(key, at);
  }
  return [...byPoint.entries()]
    .filter(([, nets]) => nets.size > 1)
    .map(([key, nets]) => {
      const [x, y] = key.split(',').map(Number);
      return { x: x!, y: y!, nets: [...nets].sort() };
    })
    .sort((a, b) => a.nets[0]!.localeCompare(b.nets[0]!));
}

/** True when (px,py) lies on the horizontal/vertical segment, endpoints
 * included. The same dust tolerance as `sameCoord` for the fixed coordinate;
 * the along-segment range check uses a plain epsilon. */
const SEG_EPS = 0.005;
const pointOnSeg = (
  px: number,
  py: number,
  s: { x1: number; y1: number; x2: number; y2: number },
): boolean => {
  if (sameCoord(s.x1, s.x2)) {
    return sameCoord(px, s.x1) && py >= Math.min(s.y1, s.y2) - SEG_EPS && py <= Math.max(s.y1, s.y2) + SEG_EPS;
  }
  if (sameCoord(s.y1, s.y2)) {
    return sameCoord(py, s.y1) && px >= Math.min(s.x1, s.x2) - SEG_EPS && px <= Math.max(s.x1, s.x2) + SEG_EPS;
  }
  return false;
};

/**
 * Cross-net wire contact is a merged net the co-located-label check cannot
 * see: KiCad joins wires at coincident endpoints and at an endpoint on
 * another wire's interior, whatever the labels say. The lemondrop run routed
 * a local net's trunk down a column of neighbouring stub ends and shorted the
 * crystal drive onto TOUCH_IRQ exactly this way (I22, #204) — ERC demoted it
 * to a warning and it would have flowed into layout. The router now avoids
 * foreign contact; this check gates whatever geometry any pass produces, so
 * a merge can never again leave the engine silently. A label whose anchor
 * sits on a foreign net's wire attaches to that wire in KiCad and is the
 * same defect.
 */
export function findWireContactMerges(
  wires: { x1: number; y1: number; x2: number; y2: number; net: string }[],
  labels: { name: string; x: number; y: number }[],
): { x: number; y: number; nets: string[] }[] {
  const out = new Map<string, { x: number; y: number; nets: string[] }>();
  const add = (x: number, y: number, a: string, b: string): void => {
    if (a === b) return;
    const nets = [a, b].sort();
    const key = `${nets[0]}/${nets[1]}@${pointKey(x, y)}`;
    if (!out.has(key)) out.set(key, { x, y, nets });
  };
  for (let i = 0; i < wires.length; i++) {
    for (let j = i + 1; j < wires.length; j++) {
      const a = wires[i]!;
      const b = wires[j]!;
      if (a.net === b.net) continue;
      if (pointOnSeg(a.x1, a.y1, b)) add(a.x1, a.y1, a.net, b.net);
      if (pointOnSeg(a.x2, a.y2, b)) add(a.x2, a.y2, a.net, b.net);
      if (pointOnSeg(b.x1, b.y1, a)) add(b.x1, b.y1, a.net, b.net);
      if (pointOnSeg(b.x2, b.y2, a)) add(b.x2, b.y2, a.net, b.net);
    }
  }
  for (const l of labels) {
    for (const w of wires) {
      if (w.net === l.name) continue;
      if (pointOnSeg(l.x, l.y, w)) add(l.x, l.y, l.name, w.net);
    }
  }
  return [...out.values()].sort(
    (a, b) => a.nets[0]!.localeCompare(b.nets[0]!) || a.x - b.x || a.y - b.y,
  );
}

/** An orthogonal segment in schematic space, millimetres. */
export interface Seg {
  x1: number;
  y1: number;
  x2: number;
  y2: number;
}

/**
 * Every on-grid point strictly BETWEEN the ends of each segment.
 *
 * Takes segments, never a bag of points: a label anchored at a point that lies
 * on no wire of its own net is attached to nothing in KiCad, and the net
 * silently loses the name the IR gave it. Callers that keep their points in
 * some other order (anchor preference, say) must pass the segments themselves
 * so the walk cannot interpolate between two points that share no wire.
 */
export function interiorGridPoints(segs: Seg[], step: number): { x: number; y: number }[] {
  const out: { x: number; y: number }[] = [];
  for (const seg of segs) {
    const steps = Math.round((Math.abs(seg.x2 - seg.x1) + Math.abs(seg.y2 - seg.y1)) / step);
    const sx = Math.sign(seg.x2 - seg.x1);
    const sy = Math.sign(seg.y2 - seg.y1);
    for (let k = 1; k < steps; k++) out.push({ x: seg.x1 + sx * k * step, y: seg.y1 + sy * k * step });
  }
  return out;
}

/**
 * Whether `seg` crosses the LINE a foreign pin's stub could grow along.
 *
 * `touchesForeign` predicts foreign stubs at their base length only, but a
 * signal stub's clearance ladder may extend it further — jetson-agx-thor-
 * baseboard shipped twelve trunk-on-stub contacts exactly that way, each a
 * merged net the gate then refused. `reach` is that maximum growth, in mm.
 * Both are orthogonal, so bounding-box overlap IS intersection, and it also
 * catches collinear overlap, conservatively.
 */
export function segCrossesStubGrowth(
  seg: Seg,
  pin: { x: number; y: number },
  o: { dx: number; dy: number },
  reach: number,
  eps: number,
): boolean {
  const ex = pin.x + o.dx * reach;
  const ey = pin.y + o.dy * reach;
  return (
    Math.min(seg.x1, seg.x2) <= Math.max(pin.x, ex) + eps &&
    Math.max(seg.x1, seg.x2) >= Math.min(pin.x, ex) - eps &&
    Math.min(seg.y1, seg.y2) <= Math.max(pin.y, ey) + eps &&
    Math.max(seg.y1, seg.y2) >= Math.min(pin.y, ey) - eps
  );
}

/**
 * Split one line of bank candidates into the runs that may share a trunk.
 *
 * `canStub` vets a member on its own (its stub must clear foreign points) and
 * `canJoin` vets the join to the member before it. A member that fails either
 * ends the run in progress — a bank never buys density with a merged net — and
 * a run of one is no bank at all, so only runs of two or more come back.
 * Pure, so the veto semantics are testable without a sheet to place.
 */
export function splitBankRuns<T>(line: T[], canStub: (c: T) => boolean, canJoin: (prev: T, c: T) => boolean): T[][] {
  const runs: T[][] = [];
  let run: T[] = [];
  const flush = (): void => {
    if (run.length >= 2) runs.push(run);
    run = [];
  };
  for (const c of line) {
    if (!canStub(c)) {
      flush();
      continue;
    }
    if (!run.length) {
      run.push(c);
      continue;
    }
    if (canJoin(run[run.length - 1]!, c)) run.push(c);
    else {
      flush();
      run = [c];
    }
  }
  flush();
  return runs;
}

interface Placed {
  part: IntentPart;
  /** The drawn refdes (the part's ref, shared by every unit instance). */
  refDes: string;
  /** KiCad unit number for a multi-unit instance; null for single-unit parts. */
  unit: number | null;
  sym: ResolvedSymbol;
  /** Origin, mm (grid multiple). */
  x: number;
  y: number;
  body: Bounds; // schematic space, absolute
  cellW: number; // units
  cellH: number; // units
}

/**
 * One placeable thing. A single-unit part is one instance whose key IS its
 * refdes. A multi-unit part (an opamp, a gate pack) becomes one instance per
 * unit, keyed `REF#unit`, each carrying only that unit's pins and body — the
 * units share symbol-space pin coordinates, so placing the symbol once would
 * overlay unrelated pins on one point and silently merge their nets (#218).
 * Net endpoints stay `REF.PIN` strings; pin numbers are package-unique, so
 * each endpoint resolves to exactly one instance.
 */
interface Instance {
  key: string;
  ref: string;
  unit: number | null;
  part: IntentPart;
  sym: ResolvedSymbol;
}

const bodyBoundsOf = (sym: ResolvedSymbol): Bounds => {
  if (sym.body) return sym.body;
  const xs = sym.pins.map((p) => p.x);
  const ys = sym.pins.map((p) => p.y);
  if (!xs.length) return { minX: -U, minY: -U, maxX: U, maxY: U };
  return { minX: Math.min(...xs), minY: Math.min(...ys), maxX: Math.max(...xs), maxY: Math.max(...ys) };
};

/** Pin connection point in schematic space for a part placed at (x, y), rot 0. */
const pinAt = (p: Placed, pin: DraftPin): { x: number; y: number } => ({ x: p.x + pin.x, y: p.y - pin.y });

/** Outward direction of a pin (away from the body), schematic space. */
function outward(pin: DraftPin): { dx: number; dy: number } {
  // pin angle points from the connection point toward the body (symbol space,
  // Y-up); outward is the opposite, with Y flipped into schematic space.
  const a = ((pin.angle % 360) + 360) % 360;
  if (a === 0) return { dx: -1, dy: 0 };
  if (a === 180) return { dx: 1, dy: 0 };
  if (a === 90) return { dx: 0, dy: 1 };
  return { dx: 0, dy: -1 };
}

/**
 * Supply-name shapes for the last-resort classification below. Deliberately
 * narrow, and narrow in ONE direction: a rail misread as a signal draws labels
 * (exactly what the engine did before the fallback existed), while a signal
 * misread as a rail draws a power symbol and makes the sheet assert a supply
 * the design does not have. So an underscore may join a VOLTAGE suffix
 * (VDD_3V3, VCC_1V8) and nothing else — VBUS_DET, VCC_SENSE and VDD_MON are
 * measurement nodes on real boards and stay signals. Anything the shapes miss
 * is still correctable with an IR `kind` declaration, which outranks all of
 * this, and the report names the basis so a miss is visible.
 */
const GROUND_NAME = /^([adp]?gnd[0-9a-z]*|vss[0-9a-z]*)$/i;
const RAIL_NAME = /^(?:[+-]?[0-9]+(?:\.[0-9]+)?v[0-9]*|(?:vcc|vdd|vbus|vee)[0-9a-z]*(?:_[0-9]+v[0-9]*)?)$/i;

function classifyNet(
  net: IntentNet,
  pinsOf: (ep: string) => DraftPin | null,
): { cls: NetClass; overridden: boolean; basis: NetClassBasis } {
  if (net.kind === 'power') return { cls: 'rail', overridden: true, basis: 'declared' };
  if (net.kind === 'ground') return { cls: 'ground', overridden: true, basis: 'declared' };
  if (net.kind === 'signal') return { cls: 'signal', overridden: true, basis: 'declared' };
  const touchesPower = net.pins.some((ep) => {
    const p = pinsOf(ep);
    return p !== null && (p.etype === 'power_in' || p.etype === 'power_out');
  });
  if (!touchesPower) {
    // No electrical-type evidence: real boards routinely carry their supplies
    // on embedded symbols whose pins are all `passive` (stickhub's GND, 80
    // pins, drafted as 80 labels and zero ground bars). Fall back to the
    // unambiguous supply-name shapes only; anything else stays signal.
    if (GROUND_NAME.test(net.name)) return { cls: 'ground', overridden: false, basis: 'name' };
    if (RAIL_NAME.test(net.name)) return { cls: 'rail', overridden: false, basis: 'name' };
    return { cls: 'signal', overridden: false, basis: 'name' };
  }
  return { cls: /gnd|vss/i.test(net.name) ? 'ground' : 'rail', overridden: false, basis: 'pin-type' };
}

const boundsOverlap = (a: Bounds, b: Bounds): boolean =>
  a.minX < b.maxX - 0.01 && a.maxX > b.minX + 0.01 && a.minY < b.maxY - 0.01 && a.maxY > b.minY + 0.01;

/**
 * The box a label's text occupies, matching the legibility checker's
 * conservative metrics. Shared by the de-collision pass and the overlap report
 * so "clear" means one thing in the engine.
 */
const labelTextBox = (name: string, x: number, y: number, rot: number): Bounds => {
  const w = Math.max(1, name.length) * LABEL_ADVANCE * LABEL_HEIGHT;
  const h = LABEL_HEIGHT / 2;
  return rot === 180
    ? { minX: x - w, minY: y - h, maxX: x, maxY: y + h }
    : { minX: x, minY: y - h, maxX: x + w, maxY: y + h };
};

/**
 * Pairs of labels naming DIFFERENT nets whose text boxes overlap.
 *
 * Distinct from `findMergedNets`, which looks for a shared label *point*. A
 * shared point is electrical — KiCad fuses the nets. Overlapping text is
 * cosmetic: the sheet reads badly, the netlist is right. Reported one entry per
 * colliding label position, nets sorted, so the same pair is not listed twice.
 */
export function findLabelOverlaps(
  labels: { name: string; x: number; y: number; rot: number }[],
): { x: number; y: number; nets: string[] }[] {
  const out = new Map<string, { x: number; y: number; nets: Set<string> }>();
  const boxes = labels.map((l) => labelTextBox(l.name, l.x, l.y, l.rot));
  for (let i = 0; i < labels.length; i++) {
    for (let j = i + 1; j < labels.length; j++) {
      const a = labels[i]!;
      const b = labels[j]!;
      if (a.name === b.name) continue;
      // an exact coincidence is a merged net, reported by findMergedNets; do
      // not also count it here or one fault reads as two
      if (sameCoord(a.x, b.x) && sameCoord(a.y, b.y)) continue;
      if (!boundsOverlap(boxes[i]!, boxes[j]!)) continue;
      for (const [l, other] of [[a, b], [b, a]] as const) {
        const key = pointKey(l.x, l.y);
        const e = out.get(key) ?? { x: l.x, y: l.y, nets: new Set<string>([l.name]) };
        e.nets.add(other.name);
        out.set(key, e);
      }
    }
  }
  return [...out.values()]
    .map((e) => ({ x: e.x, y: e.y, nets: [...e.nets].sort() }))
    .sort((a, b) => a.nets[0]!.localeCompare(b.nets[0]!) || a.x - b.x || a.y - b.y);
}

const segCrossesBody = (x1: number, y1: number, x2: number, y2: number, b: Bounds): boolean => {
  const inX = Math.max(Math.min(x1, x2), b.minX) < Math.min(Math.max(x1, x2), b.maxX) - 0.01;
  const inY = Math.max(Math.min(y1, y2), b.minY) < Math.min(Math.max(y1, y2), b.maxY) - 0.01;
  if (x1 === x2) return x1 > b.minX + 0.01 && x1 < b.maxX - 0.01 && inY;
  if (y1 === y2) return y1 > b.minY + 0.01 && y1 < b.maxY - 0.01 && inX;
  return inX && inY; // conservative for diagonals (the engine never draws them)
};

export function draftSchematicPlacement(validated: ValidatedIntent, projectName: string, today: string): { model: PlacementModel; report: SchematicDraftReport } {
  const { intent, symbols, docGroups } = validated;
  const notes: string[] = [];

  // ---------- net classification (deterministic, visible in the report) ----------
  const partByRef = new Map(intent.parts.map((p) => [p.ref, p]));

  // ---------- instance expansion (multi-unit parts, #218) ----------
  // Units none of whose OWN pins a net or no-connect references are left
  // unplaced (the intent says nothing about them, and drawing them would add
  // unconnected pins the intent never declared). Common (unit-0) pins do not
  // count as a unit's own: they appear in every unit's view because KiCad
  // draws them on every placed unit — an LM358's V+/V- reaching the rails
  // must not drag an unused second opamp onto the sheet. A multi-unit part
  // with NO referenced pins at all places all its units, so the part stays
  // visible like an unwired single-unit part does.
  const usedEps = new Set<string>();
  for (const net of intent.nets) for (const ep of net.pins) if (typeof ep === 'string') usedEps.add(ep);
  for (const ep of intent.noConnect ?? []) if (typeof ep === 'string') usedEps.add(ep);
  /** Endpoints of common (unit-0) pins: drawn — and wired — on EVERY placed
   * instance of their part. */
  const commonEps = new Set<string>();
  const instances: Instance[] = intent.parts.flatMap((p): Instance[] => {
    const sym = symbols.get(p.ref);
    if (!sym) return [];
    if (!sym.multiUnit || !sym.units?.length) return [{ key: p.ref, ref: p.ref, unit: null, part: p, sym }];
    const common = new Set(sym.commonUnitPins ?? []);
    for (const n of common) commonEps.add(`${p.ref}.${n}`);
    const referenced = sym.units.filter((u) =>
      u.pins.some((pin) => !common.has(pin.number) && usedEps.has(`${p.ref}.${pin.number}`)),
    );
    return (referenced.length ? referenced : sym.units).map((u) => ({
      key: `${p.ref}#${u.unit}`,
      ref: p.ref,
      unit: u.unit,
      part: p,
      sym: { ...sym, pins: u.pins, body: u.body },
    }));
  });
  const instByKey = new Map(instances.map((i) => [i.key, i]));
  /** Placed instances per refdes, for expanding a common pin's endpoint. */
  const instancesOfRef = new Map<string, Instance[]>();
  for (const inst of instances) instancesOfRef.set(inst.ref, [...(instancesOfRef.get(inst.ref) ?? []), inst]);
  const epInstKey = new Map<string, string>();
  for (const inst of instances) {
    for (const pin of inst.sym.pins) {
      const ep = `${inst.ref}.${pin.number}`;
      if (!commonEps.has(ep)) epInstKey.set(ep, inst.key);
    }
  }
  /** Placement-instance key owning endpoint REF.PIN. A common pin resolves to
   * its part's FIRST placed instance (single-instance callers — layering,
   * idiom passes — need one answer; the wiring passes use `expandEp` and
   * reach every appearance). Falls back to the ref itself so lookups fail
   * softly like before. */
  const instKeyOf = (ref: string, pin: string): string =>
    epInstKey.get(`${ref}.${pin}`) ?? instancesOfRef.get(ref)?.[0]?.key ?? ref;
  /** Every placed instance carrying endpoint REF.PIN: one for a unit's own
   * pin, all of the part's instances for a common pin. */
  const expandEp = (ref: string, pin: string): Instance[] => {
    if (commonEps.has(`${ref}.${pin}`)) return instancesOfRef.get(ref) ?? [];
    const inst = instByKey.get(instKeyOf(ref, pin));
    return inst ? [inst] : [];
  };

  const pinLookup = (ep: string): DraftPin | null => {
    const m = /^([^.]+)\.(.+)$/.exec(ep);
    if (!m) return null;
    const sym = symbols.get(m[1]!);
    return sym?.pins.find((p) => p.number === m[2]) ?? null;
  };
  const netClasses = new Map<string, { cls: NetClass; overridden: boolean; basis: NetClassBasis }>();
  for (const net of intent.nets) netClasses.set(net.name, classifyNet(net, pinLookup));
  const powerNets = intent.nets.filter((n) => netClasses.get(n.name)!.cls !== 'signal');
  const signalNets = intent.nets.filter((n) => netClasses.get(n.name)!.cls === 'signal');

  // ---------- reductions: decoupling caps and connectors ----------
  // Structural, not name-based (#233): the reduction's own conditions below
  // (a rail on one pin, ground on the other, an owner IC on the same rail)
  // are what make a part a decoupling element. Real boards carry their caps
  // under embedded, renamed lib ids the old `Device:C` test never matched,
  // so their banks stayed in the columns as label islands; and a rail-clamp
  // TVS drawn beside the caps is how the hand-drawn sheets show it too.
  const isTwoPin = (p: IntentPart): boolean => (symbols.get(p.ref)?.pins.length ?? 0) === 2;
  const railsOf = (ref: string): string[] =>
    powerNets
      .filter((net) => netClasses.get(net.name)!.cls === 'rail' && net.pins.some((ep) => ep.startsWith(`${ref}.`)))
      .map((net) => net.name);
  const railOf = (ref: string): string | null => railsOf(ref)[0] ?? null;
  const touchesGround = (ref: string): boolean =>
    powerNets.some((n) => netClasses.get(n.name)!.cls === 'ground' && n.pins.some((ep) => ep.startsWith(`${ref}.`)));

  const decapOwner = new Map<string, string>(); // cap ref -> owner IC ref
  for (const p of intent.parts) {
    const sym = symbols.get(p.ref)!;
    if (sym.isPower || !isTwoPin(p)) continue;
    const rail = railOf(p.ref);
    if (!rail || !touchesGround(p.ref)) continue;
    // owner: an IC (3+ pins) on the same rail — same group first, then most
    // shared nets, then refdes order (deterministic tie-break, engine spec)
    const candidates = intent.parts
      .filter((c) => c.ref !== p.ref && (symbols.get(c.ref)?.pins.length ?? 0) >= 3 && railsOf(c.ref).includes(rail))
      .map((c) => ({
        ref: c.ref,
        sameGroup: c.group === p.group ? 1 : 0,
        shared: intent.nets.filter((n) => n.pins.some((e) => e.startsWith(`${c.ref}.`)) && n.pins.some((e) => e.startsWith(`${p.ref}.`))).length,
      }))
      .sort((a, b) => b.sameGroup - a.sameGroup || b.shared - a.shared || a.ref.localeCompare(b.ref, undefined, { numeric: true }));
    if (candidates.length) decapOwner.set(p.ref, candidates[0]!.ref);
  }
  const isConnector = (p: IntentPart): boolean => p.libId.startsWith('Connector');

  // ---------- facing-label extents ----------
  // A labelled stub extends horizontal TEXT into the channel beside its pin:
  // the stub plus the net name at the checker's conservative advance. The base
  // column channel and group gap assume short names; two facing pins whose
  // combined names run past ~25 characters overrun them, and the de-collision
  // pass cannot help (riding a stub outward moves the text further INTO the
  // facing group). So the gaps below are widened by the facing extents, and a
  // long-named pair drafts clean by construction instead of surviving as an
  // error-severity text collision. Conservative on purpose: whether a signal
  // net is wired or labelled is decided after placement, so every signal net
  // counts here — typical names fit inside the base gaps and nothing widens.
  const signalNetOfPin = new Map<string, string>();
  for (const net of signalNets) for (const ep of net.pins) signalNetOfPin.set(ep, net.name);
  /** Every endpoint's net, power-class nets included (the idiom passes need
   * to see a chain's rail/ground end, which signalNetOfPin cannot). */
  const netByEndpoint = new Map<string, IntentNet>();
  for (const net of intent.nets) for (const ep of net.pins) netByEndpoint.set(ep, net);
  const labelExtents = (keys: string[]): { left: number; right: number } => {
    let left = 0;
    let right = 0;
    for (const key of keys) {
      const inst = instByKey.get(key);
      for (const pin of inst?.sym.pins ?? []) {
        const net = signalNetOfPin.get(`${inst!.ref}.${pin.number}`);
        if (!net) continue;
        const o = outward(pin);
        if (o.dx === 0) continue;
        const extent = STUB * U + Math.max(1, net.length) * LABEL_ADVANCE * LABEL_HEIGHT;
        if (o.dx === -1) left = Math.max(left, extent);
        else right = Math.max(right, extent);
      }
    }
    return { left, right };
  };
  /** Extra gap units so facing label text fits a boundary whose body-to-body
   * clearance is `baseUnits` (one unit of slack between the two texts). */
  const widenBy = (rightOfPrev: number, leftOfNext: number, baseUnits: number): number =>
    Math.max(0, ceilU(rightOfPrev + leftOfNext) + 1 - baseUnits);

  // ---------- group ordering: hints, then SUBSYSTEMS.md order, then name ----------
  const groupNames = [...new Set(intent.parts.filter((p) => !symbols.get(p.ref)!.isPower).map((p) => p.group))];
  const orderIndex = (g: string): number => {
    const hinted = intent.hints?.groupOrder?.findIndex((h) => h.toLowerCase() === g.toLowerCase());
    if (hinted !== undefined && hinted >= 0) return hinted;
    const doc = docGroups?.findIndex((h) => h.toLowerCase() === g.toLowerCase());
    if (doc !== undefined && doc >= 0) return 1000 + doc;
    return 2000;
  };
  groupNames.sort((a, b) => orderIndex(a) - orderIndex(b) || a.localeCompare(b));

  // ---------- in-group placement: layering + barycenter, integer grid ----------
  const placed = new Map<string, Placed>();
  const groupRects: { name: string; x1: number; y1: number; x2: number; y2: number }[] = [];
  const groupOf = new Map<string, string>();
  const groupExtents = new Map<string, { left: number; right: number }>();
  for (const gname of groupNames) {
    groupExtents.set(
      gname,
      labelExtents(instances.filter((i) => i.part.group === gname && !i.sym.isPower).map((i) => i.key)),
    );
  }

  /**
   * Place every group's cells. `bandBudgetW` caps a single group's width, in
   * grid units: a column that would tile past it starts a new band of columns
   * below the ones already placed (#219). `colBudgetH` caps a single column's
   * height, in grid units: a depth whose parts stack taller becomes several
   * side-by-side columns, the vertical analog of banding (#220 phase 4).
   * `Infinity` for both keeps the classic single-band ribbon. Placement is
   * deterministic in (intent, budgets), so the paper-selection pass below may
   * re-run it with tighter budgets when a sheet is worth compacting onto.
   * Returns each group's band count.
   */
  const placeAllGroups = (bandBudgetW: number, colBudgetH: number = Infinity): Map<string, number> => {
    placed.clear();
    groupRects.length = 0;
    groupOf.clear();
    const bandsOf = new Map<string, number>();
    let groupX = 0; // running x origin (units) for group tiling
    let prevGroup: string | null = null; // last group that actually placed cells

    for (const gname of groupNames) {
      // widen the gap to the previous group when facing label text needs it
      if (prevGroup !== null) {
        groupX += widenBy(groupExtents.get(prevGroup)!.right, groupExtents.get(gname)!.left, 2 * MARGIN + GROUP_GAP);
      }
      const members = instances.filter(
        (i) => i.part.group === gname && !i.sym.isPower && !decapOwner.has(i.key),
      );
      const caps = instances.filter((i) => i.part.group === gname && decapOwner.has(i.key));
      for (const i of [...members, ...caps]) groupOf.set(i.key, gname);
      const memberKeySet = new Set(members.map((m) => m.key));

      // layer assignment: connectors at depth 0; signal edges push depth forward
      const depth = new Map<string, number>(members.map((m) => [m.key, isConnector(m.part) ? 0 : 1]));
      const edges: { from: string; to: string }[] = [];
      for (const net of signalNets) {
        const eps = net.pins
          .map((ep) => {
            const m = /^([^.]+)\.(.+)$/.exec(ep);
            return m ? instKeyOf(m[1]!, m[2]!) : '';
          })
          .filter((k) => memberKeySet.has(k));
        const uniq = [...new Set(eps)];
        for (let i = 0; i < uniq.length; i++) {
          for (let j = i + 1; j < uniq.length; j++) {
            const [a, b] = [uniq[i]!, uniq[j]!].sort((x, y) => x.localeCompare(y, undefined, { numeric: true }));
            edges.push({ from: a!, to: b! });
          }
        }
      }
      for (let iter = 0; iter < members.length; iter++) {
        let changed = false;
        for (const e of edges) {
          const want = (depth.get(e.from) ?? 0) + 1;
          if ((depth.get(e.to) ?? 0) < want && want <= members.length) {
            depth.set(e.to, want);
            changed = true;
          }
        }
        if (!changed) break;
      }
      const depths = [...new Set([...depth.values()])].sort((a, b) => a - b);
      const columns: string[][] = depths.map((d) => members.filter((m) => depth.get(m.key) === d).map((m) => m.key));

      // barycenter row ordering (two sweeps), refdes as the deterministic tie
      const rowOf = new Map<string, number>();
      columns.forEach((col) => col.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).forEach((r, i) => rowOf.set(r, i)));
      for (let sweep = 0; sweep < 2; sweep++) {
        for (let ci = 1; ci < columns.length; ci++) {
          const col = columns[ci]!;
          const bary = (ref: string): number => {
            const neigh = edges
              .filter((e) => e.from === ref || e.to === ref)
              .map((e) => (e.from === ref ? e.to : e.from))
              .filter((o) => rowOf.has(o));
            if (!neigh.length) return rowOf.get(ref)!;
            return neigh.reduce((s, o) => s + rowOf.get(o)!, 0) / neigh.length;
          };
          col.sort((a, b) => bary(a) - bary(b) || a.localeCompare(b, undefined, { numeric: true })).forEach((r, i) => rowOf.set(r, i));
        }
      }

      // cells: sized from body plus margins, positions snapped to the grid
      const cellDims = new Map<string, { w: number; h: number; body: Bounds }>();
      for (const m of members) {
        const b = bodyBoundsOf(m.sym);
        cellDims.set(m.key, {
          w: ceilU(b.maxX - b.minX) + 2 * MARGIN,
          h: ceilU(b.maxY - b.minY) + 2 * MARGIN,
          body: b,
        });
      }
      // Column height budget (#220 phase 4): a depth whose parts stack taller
      // than the budget splits into several side-by-side columns, in row
      // order, so a 24-part board stops drafting as one full-height strip on
      // a sheet two sizes too large. Cells never shrink; only the arrangement
      // changes, so readability is untouched.
      const columnsToPlace: string[][] =
        colBudgetH === Infinity
          ? columns
          : columns.flatMap((col) => {
              const chunks: string[][] = [];
              let cur: string[] = [];
              let h = 0;
              for (const ref of col) {
                const add = cellDims.get(ref)!.h + (cur.length ? ROW_GAP : 0);
                if (cur.length && h + add > colBudgetH) {
                  chunks.push(cur);
                  cur = [ref];
                  h = cellDims.get(ref)!.h;
                } else {
                  cur.push(ref);
                  h += add;
                }
              }
              if (cur.length) chunks.push(cur);
              return chunks;
            });
      let colX = groupX;
      let groupMaxY = 0;
      let bandTop = 0; // y origin (units) of the current band of columns
      let bandCount = 1;
      // The budget must leave room for the label TEXT facing the sheet edges:
      // a band filled to the full usable width puts the leftmost column's
      // left-facing labels outside the frame (#220 phase 1), and no later
      // shift can fix both edges at once.
      const ext = groupExtents.get(gname)!;
      const bandW = Math.max(1, bandBudgetW - ceilU(ext.left) - ceilU(ext.right));
      for (let ci = 0; ci < columnsToPlace.length; ci++) {
        const col = columnsToPlace[ci]!;
        const colW = Math.max(...col.map((r) => cellDims.get(r)!.w));
        // Banding (#219): a column that would tile past the width budget starts
        // a new band of columns below everything placed so far, the way the
        // shelf-wrap below re-rows whole groups. Never before the first column
        // of a band, so a single over-wide column still places (and the caller
        // rejects this budget instead).
        if (colX > groupX && colX + colW - groupX > bandW) {
          bandTop = groupMaxY + GROUP_GAP;
          colX = groupX;
          bandCount++;
        }
        let rowY = bandTop;
        for (const ref of col) {
          const dims = cellDims.get(ref)!;
          const cx = colX + Math.floor(colW / 2); // shared column axis (units)
          const cy = rowY + Math.floor(dims.h / 2);
          const b = dims.body;
          // origin so the body centers on the cell center, snapped to grid
          const ox = grid(cx - Math.round((b.minX + b.maxX) / 2 / U));
          const oy = grid(cy + Math.round((b.minY + b.maxY) / 2 / U));
          const inst = instByKey.get(ref)!;
          placed.set(ref, {
            part: inst.part,
            refDes: inst.ref,
            unit: inst.unit,
            sym: inst.sym,
            x: ox,
            y: oy,
            body: { minX: ox + b.minX, minY: oy - b.maxY, maxX: ox + b.maxX, maxY: oy - b.minY },
            cellW: dims.w,
            cellH: dims.h,
          });
          rowY += dims.h + ROW_GAP;
        }
        groupMaxY = Math.max(groupMaxY, rowY - ROW_GAP);
        const next = columnsToPlace[ci + 1];
        colX += colW + CHANNEL + (next ? widenBy(labelExtents(col).right, labelExtents(next).left, 2 * MARGIN + CHANNEL) : 0);
      }

      // decoupling rows: caps in a uniform row under their owner (or the group)
      const capRefs = caps.map((c) => c.key).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
      if (capRefs.length) {
        // The bank stacks under the circuit at the circuit's own width, the
        // way a hand-drawn sheet does — a 45-cap ribbon run out to the band
        // budget alone turned the group into an L-shape wider than the sheet
        // it deserved (#233). The floor keeps a short bank (four typical cap
        // cells) on one row even when the circuit above it is narrower.
        const blockW = Math.max(64, colX - groupX);
        const capBudget = Math.min(bandW, blockW);
        let capX = groupX;
        let capY = groupMaxY + MARGIN + 4;
        for (const ref of capRefs) {
          const inst = instByKey.get(ref)!;
          const b = bodyBoundsOf(inst.sym);
          // Banding (#219): a decoupling bank wider than the budget wraps onto
          // another uniform row rather than running past the frame.
          if (capX > groupX && capX + ceilU(b.maxX - b.minX) + 2 * MARGIN - groupX > capBudget) {
            capX = groupX;
            capY += 2 * MARGIN + 6;
          }
          const ox = grid(capX + MARGIN);
          const oy = grid(capY + MARGIN);
          placed.set(ref, {
            part: inst.part,
            refDes: inst.ref,
            unit: inst.unit,
            sym: inst.sym,
            x: ox,
            y: oy,
            body: { minX: ox + b.minX, minY: oy - b.maxY, maxX: ox + b.maxX, maxY: oy - b.minY },
            cellW: ceilU(b.maxX - b.minX) + 2 * MARGIN,
            cellH: ceilU(b.maxY - b.minY) + 2 * MARGIN,
          });
          capX += ceilU(b.maxX - b.minX) + 2 * MARGIN;
        }
        groupMaxY = capY + 2 * MARGIN + 6;
      }

      // ---------- idiom micro-templates and the alignment pass (7.5/7.5a) ----------
      // Column placement is correct but reads machine-made for the small
      // structures a human drafter draws by reflex: a pull-up sits directly on
      // the pin it pulls with its rail above, a series RC hangs as one straight
      // vertical run, crystal load caps mirror about their crystal. Two passes
      // rearrange exactly those shapes after column placement, both no-ops
      // unless the textbook topology is present, and both collision-checked so
      // a failed fit falls back to the column position rather than overlapping.
      const inGroup = new Set(members.map((m) => m.key));
      const idiomPlaced = new Set<string>();
      const CHAIN_GAP = 4 * U;
      /** The two pins of a vertically-pinned two-lead instance, or null. */
      const vertPins = (key: string): { top: DraftPin; bot: DraftPin } | null => {
        const pins = placed.get(key)?.sym.pins ?? [];
        if (pins.length !== 2) return null;
        const top = pins.find((p) => outward(p).dy === -1);
        const bot = pins.find((p) => outward(p).dy === 1);
        return top && bot ? { top, bot } : null;
      };
      const isCrystal = (key: string): boolean => /crystal|reson/i.test(placed.get(key)?.part.libId ?? '');
      /** An instance the chain pass may move: two vertical leads, in this group,
       * not already spoken for by the decap row or the crystal template. */
      const chainable = (key: string): boolean =>
        inGroup.has(key) && !decapOwner.has(key) && !idiomPlaced.has(key) && !isCrystal(key) && vertPins(key) !== null;
      /** Endpoint REF.PIN for an instance's pin (the base refdes, never the key). */
      const epOf = (key: string, pin: string): string => `${placed.get(key)?.refDes ?? key}.${pin}`;
      const parseEp = (ep: string): { ref: string; pin: string; key: string } | null => {
        const m = /^([^.]+)\.(.+)$/.exec(ep);
        return m ? { ref: m[1]!, pin: m[2]!, key: instKeyOf(m[1]!, m[2]!) } : null;
      };
      const classOf = (name: string): NetClass => netClasses.get(name)?.cls ?? 'signal';
      const padOverlap = (a: Bounds, b: Bounds, pad: number): boolean =>
        a.minX < b.maxX + pad && a.maxX > b.minX - pad && a.minY < b.maxY + pad && a.maxY > b.minY - pad;
      /** Candidate placement putting `key`'s TOP pin connection point at (x, y). */
      const candidateAt = (key: string, x: number, y: number): Placed => {
        const prev = placed.get(key)!;
        const v = vertPins(key)!;
        const b = bodyBoundsOf(prev.sym);
        const ox = x - v.top.x;
        const oy = y + v.top.y;
        return {
          part: prev.part,
          refDes: prev.refDes,
          unit: prev.unit,
          sym: prev.sym,
          x: ox,
          y: oy,
          body: { minX: ox + b.minX, minY: oy - b.maxY, maxX: ox + b.maxX, maxY: oy - b.minY },
          cellW: prev.cellW,
          cellH: prev.cellH,
        };
      };
      /** Apply candidate moves unless any moved body lands within a grid unit of
       * an unmoved one; all-or-nothing so a failed fit changes nothing. */
      const applyMoves = (moves: Map<string, Placed>): boolean => {
        for (const cand of moves.values()) {
          for (const [oref, op] of placed) {
            if (moves.has(oref)) continue;
            if (padOverlap(cand.body, op.body, U)) return false;
          }
        }
        for (const [ref, cand] of moves) placed.set(ref, cand);
        return true;
      };
      /** Every endpoint of every net a set of parts touches (the chain's own
       * connection points, allowed to sit on its axis by definition). */
      const ownEndpoints = (keys: Iterable<string>): Set<string> => {
        const eps = new Set<string>();
        for (const key of keys) {
          for (const pin of placed.get(key)?.sym.pins ?? []) {
            const net = netByEndpoint.get(epOf(key, pin.number));
            for (const ep of net?.pins ?? []) eps.add(ep);
          }
        }
        return eps;
      };
      /**
       * A chain's wires run vertically along one x. No FOREIGN connected pin or
       * stub end may sit on that line within the chain's y-range: KiCad joins
       * wires at coincident endpoints, so a chain routed down a column of
       * neighbouring stub ends silently merges nets. The first npn-switch run
       * of this pass did exactly that — the reset pull-up's run down U1's
       * left-pin stub column attached 5V to DRIVE. Body boxes cannot catch
       * this; the check must be against connection points.
       */
      const axisClear = (
        axisX: number,
        yMin: number,
        yMax: number,
        ownEps: Set<string>,
        conn: { y: number; net: string }[] = [],
        movedRefs: Set<string> = new Set<string>(),
      ): boolean => {
        for (const [oref, opl] of placed) {
          for (const pin of opl.sym.pins) {
            const ep = `${opl.refDes}.${pin.number}`;
            const net = netByEndpoint.get(ep);
            if (!net) continue;
            const o = outward(pin);
            const len = classOf(net.name) !== 'signal' && o.dx !== 0 ? STUB + 2 : STUB;
            const p = pinAt(opl, pin);
            const end = { x: p.x + o.dx * len * U, y: p.y + o.dy * len * U };
            if (!ownEps.has(ep)) {
              for (const q of [p, end]) {
                if (sameCoord(q.x, axisX) && q.y > yMin - U && q.y < yMax + U) return false;
              }
            }
            // A horizontal stub SEGMENT crossing the axis exactly at a chain
            // CONNECTION row of a DIFFERENT net passes through that connection
            // point — a mid-segment crossing elsewhere is harmless, but a lead
            // parked on the crossing row is a KiCad join. The pull-up idiom
            // parked R1's bottom lead on U1's power-pin row and the VCC stub
            // ran straight through the pulled SIG node (I22's chain-pass face,
            // #204). Net-aware, because ownEps is too coarse here: U1's VCC pin
            // shares a net with the chain's rail end, yet its stub through a
            // SIG row still merges. Moved parts are skipped — `placed` holds
            // their stale pre-move positions.
            if (o.dx !== 0 && !movedRefs.has(oref)) {
              const row = conn.find((c) => sameCoord(c.y, p.y));
              if (row && row.net !== net.name) {
                const lo = Math.min(p.x, end.x) - 0.001;
                const hi = Math.max(p.x, end.x) + 0.001;
                if (axisX >= lo && axisX <= hi) return false;
              }
            }
          }
        }
        return true;
      };
      /** The room a rail/ground end grows past its pin: stub, bar, value text. */
      const POWER_CLEAR = 8 * U;
      const powerEndBox = (axisX: number, pinY: number, dir: -1 | 1): Bounds => ({
        minX: axisX - 3 * U,
        maxX: axisX + 3 * U,
        minY: dir === -1 ? pinY - POWER_CLEAR : pinY,
        maxY: dir === -1 ? pinY : pinY + POWER_CLEAR,
      });
      /** Clearance-check a chain (or flank) move set against its axis and its
       * power-end growth, then apply; marks the parts idiom-placed only when
       * everything held. */
      const finalizeMoves = (
        segments: { axisX: number; ys: number[]; conn?: { y: number; net: string }[] }[],
        moves: Map<string, Placed>,
        clearBoxes: Bounds[] = [],
      ): boolean => {
        const own = ownEndpoints(moves.keys());
        const movedRefs = new Set(moves.keys());
        for (const seg of segments) {
          // the pad covers the power stub and symbol a rail/ground end grows
          if (!axisClear(seg.axisX, Math.min(...seg.ys) - 4 * U, Math.max(...seg.ys) + 4 * U, own, seg.conn ?? [], movedRefs)) return false;
        }
        // a power symbol is not a body, so the body check cannot see it: the
        // divider repro grew R2's GND bar and value text straight into the body
        // of the part below until these boxes were checked explicitly
        for (const box of clearBoxes) {
          for (const [oref, op] of placed) {
            if (moves.has(oref)) continue;
            if (padOverlap(box, op.body, 0)) return false;
          }
        }
        if (!applyMoves(moves)) return false;
        for (const ref of moves.keys()) idiomPlaced.add(ref);
        return true;
      };

      // Crystal flanking: each horizontal crystal pin whose net also reaches a
      // two-lead cap-to-ground drops that cap below the pin's stub end. The
      // crystal's pins are symmetric about its body, so the two caps come out
      // mirror-placed at equal offsets and a common height by construction.
      for (const m of members) {
        if (!isCrystal(m.key)) continue;
        const xpl = placed.get(m.key);
        if (!xpl || xpl.sym.pins.length !== 2) continue;
        const moves = new Map<string, Placed>();
        const segments: { axisX: number; ys: number[] }[] = [];
        const clearBoxes: Bounds[] = [];
        for (const pin of xpl.sym.pins) {
          const o = outward(pin);
          if (o.dx === 0) continue;
          const net = netByEndpoint.get(`${m.ref}.${pin.number}`);
          if (!net || classOf(net.name) !== 'signal') continue;
          const cap = net.pins
            .map(parseEp)
            .find((e): e is { ref: string; pin: string; key: string } => {
              if (!e || e.key === m.key || !chainable(e.key) || moves.has(e.key)) return false;
              const v = vertPins(e.key)!;
              if (e.pin !== v.top.number) return false; // crystal node must enter the cap's top lead
              const other = netByEndpoint.get(`${e.ref}.${v.bot.number}`);
              return other !== undefined && classOf(other.name) !== 'signal';
            });
          if (!cap) continue;
          const at = pinAt(xpl, pin);
          const axisX = at.x + o.dx * STUB * U;
          const cand = candidateAt(cap.key, axisX, at.y + CHAIN_GAP);
          const v = vertPins(cap.key)!;
          moves.set(cap.key, cand);
          segments.push({ axisX, ys: [at.y, cand.y - v.bot.y] });
          clearBoxes.push(powerEndBox(axisX, cand.y - v.bot.y, 1)); // the ground symbol below the cap
        }
        // all-or-nothing per crystal: one dropped cap and one column cap would
        // read worse than the plain columns the pass is improving on
        if (moves.size) finalizeMoves(segments, moves, clearBoxes);
      }

      // Drop chains: a maximal run of two-lead vertical parts linked pin-to-pin
      // by two-endpoint signal nets, ended on each side by an anchor pin (any
      // other part) or a power-class net. The run is restacked as one straight
      // vertical line: on the anchor's stub-end axis when there is an anchor
      // (the wire from the anchor continues dead straight into the chain), on
      // its own column axis when both ends are rails (a divider). Uniform gaps,
      // top-to-bottom in connectivity order — AC-16.31's zero-bend contract.
      type ChainEnd =
        | { kind: 'power' | 'open' | 'invalid' }
        | { kind: 'anchor'; ref: string; pin: DraftPin };
      const walk = (start: string, dir: 'up' | 'down', chain: string[]): ChainEnd => {
        let current = start;
        for (;;) {
          const v = vertPins(current)!;
          const pinN = dir === 'up' ? v.top.number : v.bot.number;
          const net = netByEndpoint.get(epOf(current, pinN));
          if (!net) return { kind: 'open' }; // declared no-connect or unused
          if (classOf(net.name) !== 'signal') return { kind: 'power' };
          if (net.pins.length !== 2) return { kind: 'invalid' }; // a tapped node is not a series chain
          const otherEp = net.pins.map(parseEp).find((e) => e !== null && e.key !== current);
          if (!otherEp) return { kind: 'invalid' };
          const opl = placed.get(otherEp.key);
          if (!opl || groupOf.get(otherEp.key) !== gname) return { kind: 'invalid' };
          if (chainable(otherEp.key) && !chain.includes(otherEp.key)) {
            const ov = vertPins(otherEp.key)!;
            // the link must enter through the lead facing the chain, or the
            // drawn run would have to cross the part's own body
            if (otherEp.pin !== (dir === 'up' ? ov.bot.number : ov.top.number)) return { kind: 'invalid' };
            if (dir === 'up') chain.unshift(otherEp.key);
            else chain.push(otherEp.key);
            current = otherEp.key;
            continue;
          }
          const pin = opl.sym.pins.find((p) => p.number === otherEp.pin);
          if (!pin || chain.includes(otherEp.key)) return { kind: 'invalid' };
          return { kind: 'anchor', ref: otherEp.key, pin };
        }
      };
      const chained = new Set<string>();
      for (const m of members) {
        if (!chainable(m.key) || chained.has(m.key)) continue;
        const chain = [m.key];
        const topEnd = walk(m.key, 'up', chain);
        const bottomEnd = walk(chain[chain.length - 1]!, 'down', chain);
        for (const ref of chain) chained.add(ref);
        if (topEnd.kind === 'invalid' || bottomEnd.kind === 'invalid') continue;
        if (chain.length > 4) continue; // beyond four parts this is a network, not an idiom
        const anchors = [topEnd, bottomEnd].filter((e): e is Extract<ChainEnd, { kind: 'anchor' }> => e.kind === 'anchor');
        if (anchors.length === 0 && chain.length < 2) continue; // a lone floating part has nothing to align to
        if (topEnd.kind === 'open' && bottomEnd.kind === 'open') continue;

        const stubEndOf = (a: Extract<ChainEnd, { kind: 'anchor' }>): { x: number; y: number; o: { dx: number; dy: number } } => {
          const at = pinAt(placed.get(a.ref)!, a.pin);
          const o = outward(a.pin);
          return { x: at.x + o.dx * STUB * U, y: at.y + o.dy * STUB * U, o };
        };
        let axisX: number;
        let cursor: number; // y of the next TOP pin to place
        let order = chain;
        if (topEnd.kind === 'anchor') {
          const s = stubEndOf(topEnd);
          if (s.o.dy === -1) continue; // an up-facing pin cannot feed a downward run
          if (bottomEnd.kind === 'anchor') {
            const b = stubEndOf(bottomEnd);
            // both ends must sit on one axis with the second anchor below and
            // able to receive from above, else leave the columns alone
            if (!sameCoord(s.x, b.x) || b.y <= s.y || b.o.dy === 1) continue;
          }
          axisX = s.x;
          cursor = s.y + CHAIN_GAP;
        } else if (bottomEnd.kind === 'anchor') {
          // rail above, anchor below (a pull-up): stack upward from the anchor
          const s = stubEndOf(bottomEnd);
          if (s.o.dy === 1) continue; // a down-facing pin cannot feed an upward run
          axisX = s.x;
          order = [...chain].reverse();
          // Bounded lift: when a connection row would sit on a foreign stub's
          // crossing (axisClear's segment check), raise the whole stack a grid
          // row at a time rather than shipping the contact or losing the idiom.
          const netOf = (key: string, pinN: string): string => netByEndpoint.get(epOf(key, pinN))?.name ?? '';
          for (let lift = 0; lift < 3; lift++) {
            let up = s.y - CHAIN_GAP - lift * 2 * U;
            const moves = new Map<string, Placed>();
            const conn: { y: number; net: string }[] = [{ y: s.y, net: netOf(bottomEnd.ref, bottomEnd.pin.number) }];
            for (const ref of order) {
              const v = vertPins(ref)!;
              const span = v.top.y - v.bot.y; // symbol-space lead separation
              const cand = candidateAt(ref, axisX, up - span);
              moves.set(ref, cand);
              conn.push({ y: up, net: netOf(ref, v.bot.number) }, { y: up - span, net: netOf(ref, v.top.number) });
              up = up - span - CHAIN_GAP;
            }
            const topY = up + CHAIN_GAP;
            const topRef = order[order.length - 1]!;
            const done = finalizeMoves(
              [{ axisX, ys: [s.y, topY], conn: [...conn, { y: topY, net: netOf(topRef, vertPins(topRef)!.top.number) }] }],
              moves,
              topEnd.kind === 'power' ? [powerEndBox(axisX, topY, -1)] : [],
            );
            if (done) break;
          }
          continue;
        } else {
          // both ends are rails: a divider — straighten in place on its own axis
          const first = placed.get(chain[0]!)!;
          const v = vertPins(chain[0]!)!;
          const topAt = pinAt(first, v.top);
          axisX = topAt.x;
          cursor = topAt.y;
        }
        const cursor0 = cursor;
        const netOf2 = (key: string, pinN: string): string => netByEndpoint.get(epOf(key, pinN))?.name ?? '';
        for (let lift = 0; lift < 3; lift++) {
          cursor = cursor0 + lift * 2 * U;
          const moves = new Map<string, Placed>();
          const startY = cursor;
          const conn: { y: number; net: string }[] = [];
          let fits = true;
          for (const ref of order) {
            const cand = candidateAt(ref, axisX, cursor);
            moves.set(ref, cand);
            const v = vertPins(ref)!;
            conn.push({ y: cursor, net: netOf2(ref, v.top.number) }, { y: cursor + (v.top.y - v.bot.y), net: netOf2(ref, v.bot.number) });
            cursor = cursor + (v.top.y - v.bot.y) + CHAIN_GAP;
          }
          let axisEndY = cursor - CHAIN_GAP;
          if (bottomEnd.kind === 'anchor') {
            // cursor now sits one gap below the last lead; it may not pass the
            // lower anchor's stub end or the closing wire would run backwards
            const b = stubEndOf(bottomEnd);
            if (cursor > b.y + 0.001) fits = false;
            axisEndY = b.y;
          }
          const clearBoxes: Bounds[] = [];
          if (topEnd.kind === 'power') clearBoxes.push(powerEndBox(axisX, startY, -1));
          if (bottomEnd.kind === 'power') clearBoxes.push(powerEndBox(axisX, cursor - CHAIN_GAP, 1));
          const endNet = conn.length ? conn[0]!.net : '';
          const startConn = { y: cursor0 - CHAIN_GAP, net: topEnd.kind === 'anchor' ? netOf2(topEnd.ref, topEnd.pin.number) : endNet };
          const lastConn = { y: axisEndY, net: bottomEnd.kind === 'anchor' ? netOf2(bottomEnd.ref, bottomEnd.pin.number) : (conn.length ? conn[conn.length - 1]!.net : '') };
          if (fits && finalizeMoves([{ axisX, ys: [cursor0 - CHAIN_GAP, axisEndY], conn: [startConn, ...conn, lastConn] }], moves, clearBoxes)) break;
          if (!fits) break; // lifting only shrinks the room below; no retry can help
        }
      }

      const memberRefs = [...members.map((m) => m.key), ...capRefs];
      const cells = memberRefs.map((r) => placed.get(r)!);
      if (cells.length) {
        const minX = Math.min(...cells.map((c) => c.body.minX)) - MARGIN * U;
        const maxX = Math.max(...cells.map((c) => c.body.maxX)) + MARGIN * U;
        const minY = Math.min(...cells.map((c) => c.body.minY)) - (MARGIN + 4) * U;
        const maxY = Math.max(...cells.map((c) => c.body.maxY)) + (MARGIN + 2) * U;
        groupRects.push({ name: gname, x1: minX, y1: minY, x2: maxX, y2: maxY });
        groupX = Math.round(maxX / U) + GROUP_GAP;
        prevGroup = gname;
        bandsOf.set(gname, bandCount);
      }
    }
    return bandsOf;
  };

  // ---------- shelf-wrap: reflow the group ribbon into rows (design D12) ----------
  // Groups tile left-to-right above, which on a design with many subsystems
  // yields a ribbon: this repo's light controller came out 750 x 83 mm, a 9:1
  // strip that forces A1 and leaves 85% of the sheet empty. Wrapping that into
  // rows is what a human drafter does, and it costs nothing in readability as
  // long as the reading order is preserved — groups keep their declared order
  // and fill left-to-right, then top-to-bottom, exactly like text.
  //
  // Runs BEFORE the wire/label pass so spans are measured on final coordinates:
  // a shorter sheet turns some label pairs back into real wires.
  const paperHint = intent.hints?.paper;
  if (paperHint && !PAPERS.some((p) => p.name === paperHint)) {
    notes.push(`paper hint "${paperHint}" is not a standard size; deriving paper from content`);
  }
  const hinted = paperHint ? PAPERS.find((p) => p.name === paperHint) : undefined;
  // A hint pins the width budget; otherwise try every sheet, smallest first.
  const candidates = hinted ? [hinted] : PAPERS;
  const gap = GROUP_GAP * U;
  const usableW = (p: { w: number }): number => p.w - 2 * FRAME;
  const usableH = (p: { h: number }): number => p.h - 2 * FRAME - TITLE_STRIP;

  /**
   * Shelf-wrap the group rects to a width budget; returns per-group offsets.
   *
   * Offsets are relative to where the single-row pass already put each group,
   * never absolute targets: a row that does not wrap gets dx = dy = 0 and its
   * geometry is bit-for-bit what it was. Re-deriving absolute positions here
   * would re-round every group's width through the grid and shift
   * long-standing layouts by a unit for no reason.
   */
  const wrapTo = (budgetW: number): { deltas: { dx: number; dy: number }[]; w: number; h: number } => {
    const originX = groupRects[0]!.x1;
    const leftExtOf = (name: string): number => groupExtents.get(name)?.left ?? 0;
    const rightExtOf = (name: string): number => groupExtents.get(name)?.right ?? 0;
    const deltas: { dx: number; dy: number }[] = [];
    let rowOriginX = originX;
    // Label text on the row's flanks needs budget too: a row filled to the
    // full usable width hangs its leading group's left-facing labels outside
    // the frame, where no later shift can reach them (#220, the shelf-wrap
    // analog of the band budget's reserved extents).
    let rowLeftExt = leftExtOf(groupRects[0]!.name);
    let dyUnits = 0;
    let rowH = 0;
    for (const r of groupRects) {
      // A group wider than the whole budget still starts its own row; it will
      // overflow, and the caller rejects this paper for it.
      if (r.x1 > rowOriginX && r.x2 - rowOriginX + rowLeftExt + rightExtOf(r.name) > budgetW) {
        dyUnits += Math.ceil((rowH + gap) / U);
        rowOriginX = r.x1;
        rowLeftExt = leftExtOf(r.name);
        rowH = 0;
      }
      deltas.push({ dx: grid(Math.round((originX - rowOriginX) / U)), dy: dyUnits * U });
      rowH = Math.max(rowH, r.y2 - r.y1);
    }
    const xs = groupRects.flatMap((r, i) => [r.x1 + deltas[i]!.dx, r.x2 + deltas[i]!.dx]);
    const ys = groupRects.flatMap((r, i) => [r.y1 + deltas[i]!.dy, r.y2 + deltas[i]!.dy]);
    return { deltas, w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
  };

  type SheetFit = { paper: (typeof PAPERS)[number]; wrap: { deltas: { dx: number; dy: number }[]; w: number; h: number } | null };
  /**
   * Whether the current placement fits sheet `p`, with the group shelf-wrap
   * deltas that make it fit. `wrap` is null when there is nothing to reflow:
   * one group is already its own row, and an intent whose parts are all power
   * symbols has no group rect to measure from at all.
   */
  const fitsOn = (p: (typeof PAPERS)[number]): SheetFit | null => {
    if (groupRects.length > 1) {
      const w = wrapTo(usableW(p));
      return w.w <= usableW(p) && w.h <= usableH(p) ? { paper: p, wrap: w } : null;
    }
    const r = groupRects[0];
    return !r || (r.x2 - r.x1 <= usableW(p) && r.y2 - r.y1 <= usableH(p)) ? { paper: p, wrap: null } : null;
  };
  /** The smallest candidate sheet the current placement fits, or null. */
  const bestFit = (): SheetFit | null => {
    for (const p of candidates) {
      const f = fitsOn(p);
      if (f) return f;
    }
    return null;
  };

  /**
   * Budgeted attempt at one sheet. The width budget alone reshapes a ribbon
   * into bands, but a group of stacked two-pin parts fills the HEIGHT first
   * and leaves the landscape width untouched (stickhub reflowed to 347 mm of
   * A1's 821 usable and still overflowed the bottom). Shorter column budgets
   * spread the same cells into more side-by-side columns, so walk the height
   * fractions until the content matches the sheet's aspect or nothing fits.
   */
  const tryPaperBudgeted = (p: (typeof PAPERS)[number]): { fit: SheetFit; bands: Map<string, number> } | null => {
    for (const frac of [1, 0.7, 0.5]) {
      const b = placeAllGroups(Math.floor(usableW(p) / U), Math.floor((usableH(p) * frac) / U));
      const f = fitsOn(p);
      if (f) return { fit: f, bands: b };
    }
    return null;
  };

  let bands = placeAllGroups(Infinity);
  let fit = bestFit();
  if (!fit) {
    // No sheet holds the natural ribbon even with whole groups wrapped into
    // rows: some group is by itself wider than the widest usable frame (#219
    // drew 94 parts as one strip four sizes past the designer's A3, with 367
    // out-of-frame findings — a sheet that would not plot). Growing the paper
    // cannot fix that, so instead wrap COLUMNS into bands inside the oversized
    // groups, targeting the smallest sheet that fits. Each attempt must fit
    // the sheet whose width it banded to: accepting a narrow banding on a
    // larger sheet would re-create the empty-ribbon failure, rotated 90°.
    for (const p of candidates) {
      const t = tryPaperBudgeted(p);
      if (t) {
        bands = t.bands;
        fit = t.fit;
        break;
      }
    }
    if (!fit) {
      const largest = candidates[candidates.length - 1]!;
      bands = placeAllGroups(Math.floor(usableW(largest) / U), Math.floor(usableH(largest) / U));
      fit = { paper: largest, wrap: groupRects.length > 1 ? wrapTo(usableW(largest)) : null };
      notes.push(
        `content does not fit the ${hinted ? 'hinted' : 'largest standard'} sheet (${largest.name}) even with groups and columns wrapped; the drawing will overflow the frame`,
      );
    }
    for (const [g, n] of bands) {
      if (n > 1) notes.push(`group "${g}" was wider than the sheet; its columns wrapped onto ${n} bands`);
    }
  } else if (!hinted && fit.paper !== PAPERS[0]) {
    // ---------- compaction (#220 phase 4) ----------
    // The natural ribbon FITS a sheet, but mostly with air: a 24-part board
    // whose parts stack into one full-height strip "fits" A1 while the person
    // drew the same circuit on A3. When the natural fit uses less than the
    // checker's utilization floor, retry the smaller sheets, smallest first,
    // with both budgets, and take the first that holds the reflowed content.
    // A paper hint pins the sheet and skips this entirely.
    // Utilization by INK, not bounding box: an L-shaped layout (a tall column
    // strip plus a wide bank ribbon) spans a bbox that reads "full" while the
    // sheet is mostly air, and the bbox measure let stickhub sprawl onto A0
    // uncompacted. The sum of placed cell areas is what is actually drawn.
    const inkArea = [...placed.values()].reduce((s, p) => s + p.cellW * p.cellH * U * U, 0);
    const utilOf = (f: SheetFit): number => inkArea / (usableW(f.paper) * usableH(f.paper));
    const naturalUtil = utilOf(fit);
    if (naturalUtil < COMPACT_UTILIZATION) {
      const naturalPaper = fit.paper;
      let compacted: SheetFit | null = null;
      let compactedBands = bands;
      for (const p of candidates) {
        if (p === naturalPaper) break; // only sheets smaller than the natural fit
        const t = tryPaperBudgeted(p);
        if (t) {
          compacted = t.fit;
          compactedBands = t.bands;
          break;
        }
      }
      if (compacted) {
        bands = compactedBands;
        fit = compacted;
        notes.push(
          `sheet compacted: the natural layout fit ${naturalPaper.name} at ${Math.round(naturalUtil * 100)}% utilization; reflowed onto ${fit.paper.name}`,
        );
        for (const [g, n] of bands) {
          if (n > 1) notes.push(`group "${g}" was wider than the sheet; its columns wrapped onto ${n} bands`);
        }
      } else {
        // nothing smaller holds the reflowed content: restore the natural
        // placement byte for byte
        bands = placeAllGroups(Infinity);
        fit = bestFit()!;
      }
    }
  }
  if (fit.wrap) {
    const wrap = fit.wrap;
    const rows = new Set(wrap.deltas.map((d) => d.dy)).size;
    if (rows > 1) notes.push(`groups wrapped onto ${rows} rows to fit the sheet`);
    groupRects.forEach((r, i) => {
      const d = wrap.deltas[i]!;
      if (!d.dx && !d.dy) return;
      for (const ref of [...groupOf.entries()].filter(([, g]) => g === r.name).map(([ref]) => ref)) {
        const pl = placed.get(ref);
        if (!pl) continue;
        pl.x += d.dx;
        pl.y += d.dy;
        pl.body.minX += d.dx;
        pl.body.maxX += d.dx;
        pl.body.minY += d.dy;
        pl.body.maxY += d.dy;
      }
      r.x1 += d.dx;
      r.x2 += d.dx;
      r.y1 += d.dy;
      r.y2 += d.dy;
    });
  }

  // ---------- stubs, power symbols, labels, wires (design D2/D6a) ----------
  const wires: PlacementModel['wires'] = [];
  const labels: PlacementModel['labels'] = [];
  const junctions: { x: number; y: number }[] = [];
  const extraSymbols: EmitSymbol[] = [];
  const libSymbols = new Map<string, string>();
  const pwrFlags: string[] = [];
  /** Labels sitting at a stub end, with the stub they may ride outward. */
  const stubbedLabels: {
    label: number;
    wire: number;
    o: { dx: number; dy: number };
    /** The net's own endpoints, so a clearance check can ignore them (#217). */
    pins: string[];
  }[] = [];
  /**
   * Wired-net labels with every wire point of their run as fallback anchors.
   * `pts` is sorted for anchor preference (topmost-leftmost first) and so says
   * nothing about which point joins which; `segs` keeps the run's segments in
   * emission order, which is what the interior walk must step along.
   */
  const wiredLabels: {
    label: number;
    pts: { x: number; y: number }[];
    segs: Seg[];
  }[] = [];
  let wireIdx = new Map<string, number>();
  const addWire = (net: string, x1: number, y1: number, x2: number, y2: number): void => {
    if (sameCoord(x1, x2) && sameCoord(y1, y2)) return; // zero-length once emitted

    const i = wireIdx.get(net) ?? 0;
    wireIdx.set(net, i + 1);
    wires.push({ x1, y1, x2, y2, net, index: i });
  };

  let pwrSeq = 0;
  let flgSeq = 0;
  const endpointsOf = (net: IntentNet): { ref: string; pin: DraftPin; at: { x: number; y: number } }[] => {
    const eps = net.pins
      // a common (unit-0) pin is drawn on every placed instance of its part;
      // every appearance is wired to this same net, so the appearances stay
      // one electrical point and no drawn pin end dangles
      .flatMap((ep) => {
        const m = /^([^.]+)\.(.+)$/.exec(ep)!;
        return expandEp(m[1]!, m[2]!).map((inst) => {
          const pl = placed.get(inst.key);
          const pin = pl?.sym.pins.find((p) => p.number === m[2]);
          if (!pl || !pin) return null;
          return { ref: inst.key, pin, at: pinAt(pl, pin) };
        });
      })
      .filter((e): e is NonNullable<typeof e> => e !== null)
      .sort((a, b) => a.ref.localeCompare(b.ref, undefined, { numeric: true }) || a.pin.number.localeCompare(b.pin.number, undefined, { numeric: true }));
    // Stacked pins are one point on the sheet: KiCad symbols routinely repeat a
    // pin at the same coordinate (a thermal pad carried as a second GND pin, a
    // doubled supply pin). Drafting per PIN would stack a stub, a power symbol,
    // and its value text exactly on top of an identical one — invisible in the
    // render, an overlap to the checker, redundant to a reviewer. One item per
    // POINT; connectivity is unchanged because the pins share the point.
    return eps.filter((e, i) => eps.findIndex((o) => o.at.x === e.at.x && o.at.y === e.at.y) === i);
  };

  // power-class nets: per-pin power symbols, rails up, grounds down; one
  // PWR_FLAG per net without a power_out driver (design D6a). The stub runs in
  // the pin's OUTWARD direction — a fixed vertical drop would land on the next
  // pin of a connector-style part (2 grid rows apart) and short two nets.
  // Horizontal stubs run 4 units so their symbol clears the 2-unit signal
  // stubs and label anchors of neighbouring rows.
  const powerBodies = [...placed.values()].map((p) => p.body);

  /**
   * True when any of `segs` touches a FOREIGN connection point: a pin, the
   * stub end any connected pin grows (predicted — stubs of nets sorted later
   * are not emitted yet), or an already-emitted wire of another net. KiCad
   * joins wires at coincident endpoints and at an endpoint on a wire's
   * interior, so any such contact merges nets (I22, #204).
   *
   * Used by every pass that decides where a wire may end: the trunk-and-branch
   * veto, the labelled-stub fallback (the cap-to-ground drop placed a cap whose
   * own 2-unit stub ended exactly on the neighbouring power pin's stub interior,
   * so stubs need the check as much as trunks), the power-stub ladder, and the
   * label nudge. Defined here rather than beside the signal pass because the
   * power pass below runs first and needs it too (#217).
   */
  const touchesForeign = (
    segs: { x1: number; y1: number; x2: number; y2: number }[],
    netName: string,
    ownEps: Set<string>,
    opts: { predictStubs?: boolean } = {},
  ): boolean => {
    const predictStubs = opts.predictStubs ?? true;
    for (const opl of placed.values()) {
      for (const pin of opl.sym.pins) {
        const ep = `${opl.refDes}.${pin.number}`;
        const onet = netByEndpoint.get(ep);
        // A pin with NO net is still a connection point: a wire through it
        // joins it in KiCad. jetson-agx-thor-baseboard put an L-route corner
        // exactly on such a pin (J14.46, a single-pin group the intent never
        // names) and shipped a merged net past every gate. Only the pin's
        // POINT is guarded for netless pins; there is no stub to predict.
        if (onet?.name === netName || ownEps.has(ep)) continue;
        const p = pinAt(opl, pin);
        if (segs.some((c) => pointOnSeg(p.x, p.y, c))) return true;
        if (!predictStubs || !onet) continue;
        const o = outward(pin);
        const len = (netClasses.get(onet.name)?.cls ?? 'signal') !== 'signal' && o.dx !== 0 ? STUB + 2 : STUB;
        const end = { x: p.x + o.dx * len * U, y: p.y + o.dy * len * U };
        if (segs.some((c) => pointOnSeg(end.x, end.y, c))) return true;
      }
    }
    for (const w of wires) {
      if (w.net === netName) continue;
      if (
        segs.some(
          (c) =>
            pointOnSeg(w.x1, w.y1, c) ||
            pointOnSeg(w.x2, w.y2, c) ||
            pointOnSeg(c.x1, c.y1, w) ||
            pointOnSeg(c.x2, c.y2, w),
        )
      ) {
        return true;
      }
    }
    return false;
  };

  /** Visible power value texts placed so far, for the collision rules below. */
  const shownPowerValues: { net: string; box: Bounds }[] = [];
  const powerValueBox = (net: string, x: number, y: number): Bounds => {
    const w = Math.max(1, net.length) * LABEL_ADVANCE * LABEL_HEIGHT;
    return { minX: x - w / 2, minY: y - LABEL_HEIGHT / 2, maxX: x + w / 2, maxY: y + LABEL_HEIGHT / 2 };
  };
  for (const net of [...powerNets].sort((a, b) => a.name.localeCompare(b.name))) {
    const cls = netClasses.get(net.name)!.cls;
    const src = powerSymbolSource(net.name, cls === 'ground' ? 'ground' : 'rail');
    libSymbols.set(src.libId, src.sourceText);
    const hasDriver = net.pins.some((ep) => pinLookup(ep)?.etype === 'power_out');
    const eps = endpointsOf(net);
    /** One PWR_FLAG per undriven net, on the net's FIRST endpoint — whether
     * that endpoint drafts as a bank member or a lone symbol. */
    const maybeFlag = (i: number, x: number, y: number): void => {
      if (i !== 0 || hasDriver) return;
      const flag = pwrFlagSource();
      libSymbols.set(flag.libId, flag.sourceText);
      flgSeq++;
      extraSymbols.push({
        ref: `#FLG${String(flgSeq).padStart(2, '0')}`,
        libId: flag.libId,
        value: 'PWR_FLAG',
        footprint: '',
        at: { x, y, rot: 0 },
        refAt: { x, y },
        valueAt: { x, y },
        hideRef: true,
        hideValue: true,
        pinNumbers: ['1'],
      });
      pwrFlags.push(net.name);
    };
    // ---------- rail-bank trunks (#233, #220 phase 3) ----------
    // Decap-row caps adjacent on the same power net chain on ONE trunk: a
    // stub per pin, horizontal joins between consecutive stub ends, a single
    // power symbol and value at the first end. The human's sixteen-cap VBUS
    // bank carries two power symbols; the per-pin idiom drew twenty-six.
    // Every stub and trunk segment must clear foreign points and bodies, and
    // a member that cannot join cleanly splits the run — a bank never buys
    // density with a merged net.
    const consumed = new Set<number>();
    {
      const ownEps = new Set(net.pins);
      // Structural, not name-based: any two-pin part with a vertical pin on
      // this power net banks — real boards carry their caps under embedded,
      // renamed symbols the Device:C test never matches, and a pull-up array
      // on one rail trunk is drawn the same way by hand.
      const cands = eps
        .map((ep, i) => ({ ep, i, o: outward(ep.pin) }))
        .filter((c) => c.o.dy !== 0 && c.o.dx === 0 && (placed.get(c.ep.ref)?.sym.pins.length ?? 0) === 2);
      const byLine = new Map<string, typeof cands>();
      for (const c of cands) {
        const k = `${c.o.dy}|${knum(c.ep.at.y + c.o.dy * STUB * U)}`;
        byLine.set(k, [...(byLine.get(k) ?? []), c]);
      }
      const stubClear = (c: (typeof cands)[number]): boolean => {
        const end = { x: c.ep.at.x, y: c.ep.at.y + c.o.dy * STUB * U };
        return !touchesForeign([{ x1: c.ep.at.x, y1: c.ep.at.y, x2: end.x, y2: end.y }], net.name, ownEps, {
          predictStubs: false,
        });
      };
      /**
       * A trunk may not cross the LINE a foreign stub could grow along. The
       * geometry is `segCrossesStubGrowth` (tested directly); this walks every
       * foreign pin over it at the signal stub's maximum grown length.
       */
      const crossesForeignStubLine = (seg: Seg): boolean => {
        for (const opl of placed.values()) {
          for (const pin of opl.sym.pins) {
            const ep = `${opl.refDes}.${pin.number}`;
            const onet = netByEndpoint.get(ep);
            if (!onet || onet.name === net.name) continue;
            if (segCrossesStubGrowth(seg, pinAt(opl, pin), outward(pin), (STUB + 2) * U, SEG_EPS)) return true;
          }
        }
        return false;
      };
      const emitBank = (run: typeof cands): void => {
        const dy = run[0]!.o.dy;
        const ends = run.map((c) => ({ x: c.ep.at.x, y: c.ep.at.y + dy * STUB * U }));
        run.forEach((c, j) => {
          addWire(net.name, c.ep.at.x, c.ep.at.y, ends[j]!.x, ends[j]!.y);
          consumed.add(c.i);
        });
        for (let j = 1; j < ends.length; j++) {
          addWire(net.name, ends[j - 1]!.x, ends[j - 1]!.y, ends[j]!.x, ends[j]!.y);
        }
        const first = ends[0]!;
        const valueAt = { x: first.x, y: first.y + dy * 3.556 };
        const box = powerValueBox(net.name, valueAt.x, valueAt.y);
        const hideValue = shownPowerValues.some((p) => p.net === net.name && boundsOverlap(p.box, box));
        if (!hideValue) shownPowerValues.push({ net: net.name, box });
        pwrSeq++;
        extraSymbols.push({
          ref: `#PWR${String(pwrSeq).padStart(2, '0')}`,
          libId: src.libId,
          value: net.name,
          footprint: '',
          at: { x: first.x, y: first.y, rot: 0 },
          refAt: { x: first.x, y: first.y },
          valueAt,
          hideRef: true,
          hideValue,
          pinNumbers: ['1'],
        });
        for (const [j, c] of run.entries()) maybeFlag(c.i, ends[j]!.x, ends[j]!.y);
      };
      const joinClear = (prev: (typeof cands)[number], c: (typeof cands)[number]): boolean => {
        const y = c.ep.at.y + c.o.dy * STUB * U;
        const seg = { x1: prev.ep.at.x, y1: y, x2: c.ep.at.x, y2: y };
        return (
          c.ep.at.x - prev.ep.at.x <= BANK_PITCH_MAX * U &&
          !powerBodies.some((b) => segCrossesBody(seg.x1, seg.y1, seg.x2, seg.y2, b)) &&
          !touchesForeign([seg], net.name, ownEps, { predictStubs: true }) &&
          !crossesForeignStubLine(seg)
        );
      };
      for (const line of [...byLine.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([, v]) => v)) {
        line.sort((a, b) => a.ep.at.x - b.ep.at.x);
        for (const run of splitBankRuns(line, stubClear, joinClear)) emitBank(run);
      }
    }
    eps.forEach((ep, i) => {
      if (consumed.has(i)) return;
      const o = outward(ep.pin);
      let len = o.dx !== 0 ? STUB + 2 : STUB;
      // Fair share of the channel: a stub may never cross the MIDLINE to the
      // nearest facing foreign pin on its own line, whatever the text pass
      // wants. Drafting order decides who draws first, and a first-drafted
      // stub that fills the channel leaves the facing pin no clear rung at
      // any length — jetson's text-grown 8-unit stub in a 9-unit channel did
      // exactly that, and the facing GND shipped touching (a refusal).
      let maxLen = Infinity;
      for (const opl of placed.values()) {
        for (const pin of opl.sym.pins) {
          const fep = `${opl.refDes}.${pin.number}`;
          if (netByEndpoint.get(fep)?.name === net.name) continue;
          const p2 = pinAt(opl, pin);
          if (o.dx !== 0 && sameCoord(p2.y, ep.at.y) && Math.sign(p2.x - ep.at.x) === o.dx) {
            maxLen = Math.min(maxLen, Math.max(1, Math.floor(Math.abs(p2.x - ep.at.x) / U / 2)));
          } else if (o.dy !== 0 && sameCoord(p2.x, ep.at.x) && Math.sign(p2.y - ep.at.y) === o.dy) {
            maxLen = Math.min(maxLen, Math.max(1, Math.floor(Math.abs(p2.y - ep.at.y) / U / 2)));
          }
        }
      }
      if (len > maxLen) len = maxLen;
      const at = (l: number): { x: number; y: number } => ({ x: ep.at.x + o.dx * l * U, y: ep.at.y + o.dy * l * U });
      const valueAtOf = (end: { x: number; y: number }): { x: number; y: number } => ({
        x: end.x,
        y: end.y + (o.dy !== 0 ? o.dy * 3.556 : cls === 'ground' ? 3.556 : -3.556),
      });
      // Adjacent power pins collide their value texts two ways, resolved two
      // ways. The SAME net repeated (a TQFP's VCC pins one row apart) hides
      // the duplicates: one visible name per cluster carries the same
      // information. A DIFFERENT net's name may never be hidden, so its
      // symbol rides its own stub outward, a bounded grid step at a time,
      // until the text clears — keeping "every gate failure is resolvable
      // through the IR" true for a collision the IR cannot otherwise reach.
      let hideValue = false;
      {
        const first = valueAtOf(at(len));
        const firstBox = powerValueBox(net.name, first.x, first.y);
        if (shownPowerValues.some((p) => p.net === net.name && boundsOverlap(p.box, firstBox))) {
          hideValue = true;
        } else {
          for (let extra = 0; extra < 4; extra++) {
            const v = valueAtOf(at(len));
            const b = powerValueBox(net.name, v.x, v.y);
            if (!shownPowerValues.some((p) => p.net !== net.name && boundsOverlap(p.box, b))) break;
            if (len + 2 > maxLen) break; // text never buys past the midline
            const extended = at(len + 2);
            if (powerBodies.some((bd) => segCrossesBody(ep.at.x, ep.at.y, extended.x, extended.y, bd))) break;
            len += 2;
          }
        }
      }
      /**
       * The length chosen above answers a typographic question: where does the
       * value text stop colliding. It says nothing about where the stub's
       * ENDPOINT lands, and a power stub that ends on another net's stub is a
       * shorted rail (#217: cm5_minima put a +5V pin 4 units above a GND pin,
       * both stubs grew 2 units toward each other, and they met exactly in the
       * middle — the drawn sheet ties +5V to GND).
       *
       * So the text-driven length is only a preference. Try it first, then
       * lengths either side of it, and take the first whose endpoint touches no
       * foreign connection point. Shorter is in the ladder deliberately: two
       * pins facing each other cannot be separated by growing the stub, only by
       * pulling it back. One unit is the floor — the power symbol still needs
       * somewhere to sit.
       *
       * When nothing clears, keep the preferred length and let the merged-net
       * gate refuse loudly. Shipping a quiet short is the one outcome barred.
       */
      const ownPinEps = new Set(net.pins);
      /**
       * Which bodies a stub of length `l` would cross, by index.
       *
       * A pin sits ON its own part's outline, so EVERY length crosses at least
       * that body, including the preferred one the engine ships today. Treating
       * any crossing as disqualifying would veto the whole ladder (it did, on
       * the first attempt at #217). What matters is that moving the stub does
       * not put it through something the preferred length was already clear of.
       */
      const crossedBy = (l: number): Set<number> => {
        const e = at(l);
        const out = new Set<number>();
        powerBodies.forEach((bd, i) => {
          if (segCrossesBody(ep.at.x, ep.at.y, e.x, e.y, bd)) out.add(i);
        });
        return out;
      };
      const baseCrossed = crossedBy(len);
      const clearsAt = (l: number): boolean => {
        if ([...crossedBy(l)].some((i) => !baseCrossed.has(i))) return false;
        const e = at(l);
        return !touchesForeign([{ x1: ep.at.x, y1: ep.at.y, x2: e.x, y2: e.y }], net.name, ownPinEps, {
          predictStubs: false,
        });
      };
      /**
       * Whether the value text would still be clear at length `l`. The length
       * chosen above already answers this for the preferred length; the ladder
       * has to keep answering it, or a stub moved for electrical reasons drags
       * its rail name into a neighbouring body (it dragged "+3V3" into R1 on
       * the pull-up idiom the first time this ladder was written).
       *
       * Only a preference: a text collision is a legibility cost the report
       * names, while a merged net refuses the draft outright. So a rung that is
       * electrically clear but typographically ugly still beats no rung at all.
       */
      const textClearAt = (l: number): boolean => {
        if (hideValue) return true;
        const v = valueAtOf(at(l));
        const b = powerValueBox(net.name, v.x, v.y);
        if (powerBodies.some((bd) => boundsOverlap(b, bd))) return false;
        return !shownPowerValues.some((p) => p.net !== net.name && boundsOverlap(p.box, b));
      };
      if (!clearsAt(len)) {
        const ladder: number[] = [];
        for (let d = 1; d <= MAX_POWER_STUB_SHIFT; d++) {
          if (len + d <= maxLen) ladder.push(len + d);
          if (len - d >= 1) ladder.push(len - d);
        }
        // Full retreat, beyond the bounded shift: the TEXT-driven growth above
        // can carry `len` so far out that every rung within
        // MAX_POWER_STUB_SHIFT still overlaps the facing pin's stub, and the
        // electrically clear short lengths sit out of reach (jetson's D2
        // shipped a 10-unit VCC_IN stub through the facing net's 4-unit stub
        // and its power symbol that way). Last rungs, so any bounded rung
        // that clears still wins and existing layouts do not move.
        for (let l = Math.min(len, STUB + 2); l >= 1; l--) {
          if (!ladder.includes(l)) ladder.push(l);
        }
        const freed = ladder.find((l) => clearsAt(l) && textClearAt(l)) ?? ladder.find(clearsAt);
        if (freed !== undefined) len = freed;
      }
      const stubEnd = at(len);
      const valueAt = valueAtOf(stubEnd);
      if (!hideValue) shownPowerValues.push({ net: net.name, box: powerValueBox(net.name, valueAt.x, valueAt.y) });
      addWire(net.name, ep.at.x, ep.at.y, stubEnd.x, stubEnd.y);
      pwrSeq++;
      extraSymbols.push({
        ref: `#PWR${String(pwrSeq).padStart(2, '0')}`,
        libId: src.libId,
        value: net.name,
        footprint: '',
        at: { x: stubEnd.x, y: stubEnd.y, rot: 0 },
        refAt: { x: stubEnd.x, y: stubEnd.y },
        // The bar is drawn on a fixed side of its own pin (rails above, grounds
        // below), but a stub leaves its pin in whatever direction the pin
        // faces. Offsetting the value by class alone therefore throws the text
        // back across the stub and into the part whenever the two disagree —
        // a rail hanging off a downward pin puts "+5V" on the symbol above it.
        // The text follows the stub outward, so it always lands on the far
        // side of the symbol from the part it serves.
        valueAt,
        hideRef: true,
        // the net name IS the flag's meaning: an anonymous bar tells a
        // reviewer nothing, so the value stays visible like stock power
        // symbols (the checker verifies it collides with nothing)
        hideValue,
        pinNumbers: ['1'],
      });
      // the flag's pin sits exactly on the stub END so KiCad's connectivity
      // (which joins at wire endpoints) sees the power_out driver
      maybeFlag(i, stubEnd.x, stubEnd.y);
    });
  }

  // signal nets: local nets wired, everything else labelled at a stub
  const bodies = [...placed.values()].map((p) => p.body);
  let wired = 0;
  let labelled = 0;
  for (const net of [...signalNets].sort((a, b) => a.name.localeCompare(b.name))) {
    const eps = endpointsOf(net);
    if (!eps.length) continue;
    const stubs = eps.map((ep) => {
      const o = outward(ep.pin);
      return { ep, end: { x: ep.at.x + o.dx * STUB * U, y: ep.at.y + o.dy * STUB * U }, o };
    });
    const groupsTouched = new Set(eps.map((e) => groupOf.get(e.ref)));
    const spanX = Math.max(...stubs.map((s) => s.end.x)) - Math.min(...stubs.map((s) => s.end.x));
    const spanY = Math.max(...stubs.map((s) => s.end.y)) - Math.min(...stubs.map((s) => s.end.y));
    let asWire = groupsTouched.size === 1 && eps.length <= MAX_WIRED_ENDPOINTS && Math.max(spanX, spanY) <= MAX_WIRE_SPAN;

    if (asWire) {
      // trunk-and-branch: a vertical trunk with horizontal branches. Several
      // deterministic trunk positions are tried in order (median stub x, right
      // of everything, left of everything); the first collision-free routing
      // wins, and if none exists the net falls back to labels — the engine may
      // never trip its own wire-through-symbol gate.
      const xs = stubs.map((s) => s.end.x).sort((a, b) => a - b);
      const ys = stubs.map((s) => s.end.y);
      const trunkCandidates = [
        grid(Math.round(xs[Math.floor(xs.length / 2)]! / U)),
        grid(Math.round(xs[xs.length - 1]! / U) + STUB),
        grid(Math.round(xs[0]! / U) - STUB),
      ];
      let routed = false;
      for (const trunkX of trunkCandidates) {
        const candidate: { x1: number; y1: number; x2: number; y2: number }[] = [];
        for (const s of stubs) {
          candidate.push({ x1: s.ep.at.x, y1: s.ep.at.y, x2: s.end.x, y2: s.end.y });
          if (!sameCoord(s.end.x, trunkX)) candidate.push({ x1: s.end.x, y1: s.end.y, x2: trunkX, y2: s.end.y });
        }
        // the trunk is split at every branch meet: coincident wire ENDPOINTS
        // are what both KiCad and the geometric netlister join on
        const meetYs = [...new Map(ys.map((y) => [knum(y), y])).values()].sort((a, b) => a - b);
        for (let i = 1; i < meetYs.length; i++) {
          candidate.push({ x1: trunkX, y1: meetYs[i - 1]!, x2: trunkX, y2: meetYs[i]! });
        }
        if (candidate.some((c) => bodies.some((b) => segCrossesBody(c.x1, c.y1, c.x2, c.y2, b)))) continue;
        // No candidate segment may touch a foreign connection point (I22,
        // #204): a trunk routed down a column of neighbouring stub ends
        // silently merges nets. Mirrors the chain pass's axisClear,
        // generalized to every candidate segment.
        if (touchesForeign(candidate, net.name, new Set(net.pins))) continue;
        for (const c of candidate) addWire(net.name, c.x1, c.y1, c.x2, c.y2);
        // one label names the wired net (topmost-leftmost wire point): the net
        // stays identifiable to PINOUT/drift and to a reviewer without a
        // label-per-pin, matching hand-drafting practice
        const pts = candidate.flatMap((c) => [
          { x: c.x1, y: c.y1 },
          { x: c.x2, y: c.y2 },
        ]);
        pts.sort((a, b) => a.y - b.y || a.x - b.x);
        labels.push({ name: net.name, x: pts[0]!.x, y: pts[0]!.y, rot: 0 });
        wiredLabels.push({ label: labels.length - 1, pts, segs: candidate.map((c) => ({ ...c })) });
        wired++;
        if (eps.length > 2) {
          for (const s of stubs) {
            const meet = sameCoord(s.end.x, trunkX) ? s.end : { x: trunkX, y: s.end.y };
            if (meet.y > Math.min(...ys) && meet.y < Math.max(...ys)) junctions.push(meet);
          }
        }
        routed = true;
        break;
      }
      if (!routed) asWire = false;
    }
    if (!asWire) {
      for (const s of stubs) {
        // A stub is a wire too: its endpoint resting on a foreign net's wire
        // or connection point merges nets exactly like a trunk would (the
        // cap-to-ground drop's 2-unit stub ended on the neighbouring power
        // pin's stub interior — I22's third face). Grow the stub a grid unit
        // at a time until the endpoint is clear; the interior then CROSSES
        // the foreign wire mid-segment, which does not connect. If no length
        // clears, emit the plain stub and let the merged-net gate refuse
        // loudly rather than ship the contact.
        let end = s.end;
        const own = new Set(net.pins);
        // Rungs in preference order: the classic 0..2 extensions first so
        // clear cases stay byte-identical, then deeper extensions, then a
        // one-unit retreat. A stub that ships with NO clear rung still ends
        // touching a foreign wire and the merge gate refuses the draft, so
        // every extra rung here is a board that drafts instead of refusing
        // (jetson's twelve wire-contact refusals were exactly this fallback).
        for (const len of [STUB, STUB + 1, STUB + 2, STUB + 3, STUB + 4, STUB + 5, STUB + 6, 1]) {
          const cand = {
            x: s.ep.at.x + s.o.dx * len * U,
            y: s.ep.at.y + s.o.dy * len * U,
          };
          if (!touchesForeign([{ x1: s.ep.at.x, y1: s.ep.at.y, x2: cand.x, y2: cand.y }], net.name, own)) {
            end = cand;
            break;
          }
        }
        addWire(net.name, s.ep.at.x, s.ep.at.y, end.x, end.y);
        // labels are always horizontal (drafting standard): leftward pins read
        // outward to the left, everything else extends to the right
        labels.push({ name: net.name, x: end.x, y: end.y, rot: s.o.dx === -1 ? 180 : 0 });
        stubbedLabels.push({ label: labels.length - 1, wire: wires.length - 1, o: s.o, pins: net.pins });
        labelled++;
      }
    }
  }

  // ---------- member symbols with collision-free text slots ----------
  // Built BEFORE the label de-collision pass so the pass can treat every
  // visible ref/value text as an obstacle: the checker measures text-vs-text
  // collisions at error severity, so a box the checker will see must be a box
  // the avoider saw first.
  const emitSymbols: EmitSymbol[] = [];
  /** Emit entry with its placement, for the slot-refinement pass below (two
   * unit instances share one refdes, so `ref` alone no longer keys `placed`). */
  const emitPairs: { sym: EmitSymbol; pl: Placed }[] = [];
  /** What KiCad renders for the reference: a multi-unit instance shows its
   * unit letter (U1A, U1B), so width metrics must measure the rendered text. */
  const displayRefOf = (pl: Placed): string =>
    pl.unit !== null ? `${pl.refDes}${String.fromCharCode(64 + Math.min(pl.unit, 26))}` : pl.refDes;
  for (const [, pl] of [...placed.entries()].sort((a, b) => a[0].localeCompare(b[0], undefined, { numeric: true }))) {
    const pinSides = new Set(pl.sym.pins.map((p) => {
      const o = outward(p);
      return o.dx === -1 ? 'left' : o.dx === 1 ? 'right' : o.dy === -1 ? 'top' : 'bottom';
    }));
    const cy = (pl.body.minY + pl.body.maxY) / 2;
    const cx = (pl.body.minX + pl.body.maxX) / 2;
    const textW = Math.max(displayRefOf(pl).length, pl.part.value.length) * 0.8 * 1.27;
    let refAt: { x: number; y: number };
    let valueAt: { x: number; y: number };
    if (!pinSides.has('top')) {
      refAt = { x: cx, y: pl.body.minY - 2.54 };
      // value stacks above the ref when the bottom also carries pins, and sits
      // below the body otherwise
      valueAt = pinSides.has('bottom') ? { x: cx, y: pl.body.minY - 5.08 } : { x: cx, y: pl.body.maxY + 2.54 };
    } else if (
      pl.body.maxX - pl.body.minX >= textW + 2.54 &&
      pl.body.maxY - pl.body.minY >= 7.62
    ) {
      // pins on top AND a body big enough to hold its own name: a TQFP-class
      // part carries pins on all four sides, so every outside slot lands on
      // some pin's stub or label; the body interior is the one guaranteed-free
      // area, and it is where KiCad's own large symbols put their text
      refAt = { x: cx, y: cy - 1.27 };
      valueAt = { x: cx, y: cy + 1.27 };
    } else {
      refAt = { x: pl.body.maxX + textW / 2 + 1.27, y: cy - 1.27 };
      valueAt = { x: pl.body.maxX + textW / 2 + 1.27, y: cy + 1.27 };
    }
    const sym: EmitSymbol = {
      ref: pl.refDes,
      libId: pl.sym.libId,
      value: pl.part.value,
      footprint: pl.part.footprint ?? '',
      at: { x: pl.x, y: pl.y, rot: 0 },
      refAt,
      valueAt,
      pinNumbers: pl.sym.pins.map((p) => p.number),
      ...(pl.unit !== null ? { unit: pl.unit } : {}),
    };
    emitSymbols.push(sym);
    emitPairs.push({ sym, pl });
    libSymbols.set(pl.sym.libId, pl.sym.sourceText);
  }

  /** Centered text box, matching the checker's `textBounds` metrics. */
  const centeredTextBox = (s: string, x: number, y: number): Bounds => {
    const w = Math.max(1, s.length) * LABEL_ADVANCE * LABEL_HEIGHT;
    return { minX: x - w / 2, minY: y - LABEL_HEIGHT / 2, maxX: x + w / 2, maxY: y + LABEL_HEIGHT / 2 };
  };
  /** Text-box-vs-segment overlap; hoisted so slot refinement below and the
   * label pass share one metric. */
  const segHitsBoxEarly = (w: { x1: number; y1: number; x2: number; y2: number }, b: Bounds): boolean =>
    Math.min(w.x1, w.x2) < b.maxX - 0.01 &&
    Math.max(w.x1, w.x2) > b.minX + 0.01 &&
    Math.min(w.y1, w.y2) < b.maxY - 0.01 &&
    Math.max(w.y1, w.y2) > b.minY + 0.01;

  // ---------- symbol-field slot refinement (I23, #210) ----------
  // The heuristic slots above consult nothing: attempt-07 ended ERC-clean
  // with 8 error-severity findings that were exactly these ref/value fields
  // sitting on wires and neighbouring bodies, with no IR lever to move them.
  // Re-slot each dirty pair down a deterministic ladder; the first slot whose
  // boxes clear every wire, every FOREIGN body, and all field text placed so
  // far wins. Where the heuristic is already clean the output is
  // byte-identical; where nothing clears, the heuristic stays so the checker
  // still reports the collision honestly.
  {
    const fieldBoxes: Bounds[] = extraSymbols
      .filter((s) => !s.hideValue)
      .map((s) => centeredTextBox(s.value, s.valueAt.x, s.valueAt.y));
    for (const { sym, pl } of emitPairs) {
      const dref = displayRefOf(pl);
      const cx = (pl.body.minX + pl.body.maxX) / 2;
      const cy = (pl.body.minY + pl.body.maxY) / 2;
      const textW = Math.max(dref.length, sym.value.length) * 0.8 * 1.27;
      const pairClear = (r: { x: number; y: number }, v: { x: number; y: number }): boolean => {
        for (const b of [centeredTextBox(dref, r.x, r.y), centeredTextBox(sym.value, v.x, v.y)]) {
          if (wires.some((w) => segHitsBoxEarly(w, b))) return false;
          for (const op of placed.values()) {
            if (op !== pl && boundsOverlap(b, op.body)) return false;
          }
          if (fieldBoxes.some((t) => boundsOverlap(t, b))) return false;
        }
        return true;
      };
      if (!pairClear(sym.refAt, sym.valueAt)) {
        const ladder: [{ x: number; y: number }, { x: number; y: number }][] = [];
        for (const extra of [0, 2.54]) {
          ladder.push(
            [{ x: cx, y: pl.body.maxY + 2.54 + extra }, { x: cx, y: pl.body.maxY + 5.08 + extra }],
            [{ x: cx, y: pl.body.minY - 5.08 - extra }, { x: cx, y: pl.body.minY - 2.54 - extra }],
            [
              { x: pl.body.maxX + textW / 2 + 1.27 + extra, y: cy - 1.27 },
              { x: pl.body.maxX + textW / 2 + 1.27 + extra, y: cy + 1.27 },
            ],
            [
              { x: pl.body.minX - textW / 2 - 1.27 - extra, y: cy - 1.27 },
              { x: pl.body.minX - textW / 2 - 1.27 - extra, y: cy + 1.27 },
            ],
          );
        }
        for (const [r, v] of ladder) {
          if (pairClear(r, v)) {
            sym.refAt = r;
            sym.valueAt = v;
            break;
          }
        }
      }
      fieldBoxes.push(centeredTextBox(dref, sym.refAt.x, sym.refAt.y), centeredTextBox(sym.value, sym.valueAt.x, sym.valueAt.y));
    }
  }

  /** Every visible ref/value text the checker will measure. */
  const textObstacles: Bounds[] = [
    ...emitPairs.flatMap(({ sym: s, pl }) => [centeredTextBox(displayRefOf(pl), s.refAt.x, s.refAt.y), centeredTextBox(s.value, s.valueAt.x, s.valueAt.y)]),
    ...extraSymbols.filter((s) => !s.hideValue).map((s) => centeredTextBox(s.value, s.valueAt.x, s.valueAt.y)),
  ];

  // Nets are drafted in name order, so a net can only avoid what is already on
  // the sheet: "COMP" cannot see the trunk "COMP_Z" is about to run through the
  // very point its label occupies. This pass runs once the routing is complete
  // and walks each stub-anchored label outward a grid unit at a time until its
  // text box clears every foreign wire, body, and visible ref/value text. The
  // anchor rides the stub it extends, so the label stays attached and
  // connectivity never changes.
  const segHitsBox = (w: { x1: number; y1: number; x2: number; y2: number }, b: Bounds): boolean =>
    Math.min(w.x1, w.x2) < b.maxX - 0.01 &&
    Math.max(w.x1, w.x2) > b.minX + 0.01 &&
    Math.min(w.y1, w.y2) < b.maxY - 0.01 &&
    Math.max(w.y1, w.y2) > b.minY + 0.01;
  /** Is (x, y) on the (axis-aligned) segment, endpoints included? */
  const segContains = (w: { x1: number; y1: number; x2: number; y2: number }, x: number, y: number): boolean =>
    x >= Math.min(w.x1, w.x2) - 0.01 &&
    x <= Math.max(w.x1, w.x2) + 0.01 &&
    y >= Math.min(w.y1, w.y2) - 0.01 &&
    y <= Math.max(w.y1, w.y2) + 0.01 &&
    (Math.abs(w.x1 - w.x2) < 0.01 ? Math.abs(x - w.x1) <= 0.01 : Math.abs(y - w.y1) <= 0.01);

  // Wired-net labels first: the single label naming a wired run used to be
  // pinned at the topmost-leftmost wire point with no clearance check, and on
  // a drop chain that point is the anchor corner — the text immediately lies
  // across the chain's vertical run. The label may sit at ANY point of its own
  // net's wires, so walk the run's points and take the first whose text box
  // clears everything the checker will measure; wires the point itself lies on
  // are the label's own attachment and never count as collisions.
  for (const rec of wiredLabels) {
    const lb = labels[rec.label]!;
    const clearWired = (x: number, y: number): boolean => {
      const box = labelTextBox(lb.name, x, y, 0);
      if (bodies.some((b) => boundsOverlap(box, b))) return false;
      if (textObstacles.some((b) => boundsOverlap(box, b))) return false;
      if (wires.some((w) => !segContains(w, x, y) && segHitsBox(w, box))) return false;
      return !labels.some(
        (o, i) => i !== rec.label && o.name !== lb.name && boundsOverlap(box, labelTextBox(o.name, o.x, o.y, o.rot)),
      );
    };
    if (clearWired(lb.x, lb.y)) continue;
    const alt = rec.pts.find((p) => clearWired(p.x, p.y));
    if (alt) {
      lb.x = alt.x;
      lb.y = alt.y;
      continue;
    }
    // No segment endpoint clears, but the label may sit at ANY point of its
    // own net's wires: walk the interior grid points of each segment too
    // (#220 phase 2). Endpoints stay the first choice so a run that used to
    // clear keeps its exact label point.
    //
    // Walk `segs`, never `pts`: `pts` is sorted for anchor preference, so
    // pairing it up interpolates between two points that share no wire and
    // anchors the label in open sheet, where KiCad attaches nothing and the
    // net silently carries whatever name KiCad invents for it instead of the
    // one the IR gave it. Three corpus nets shipped exactly that way —
    // Net-(F201-Pad1), Net-(U8-BIN) and Net-(U8-RIN), each anchored on no
    // wire of its own run.
    const inner = interiorGridPoints(rec.segs, U).find((p) => clearWired(p.x, p.y));
    if (inner) {
      lb.x = inner.x;
      lb.y = inner.y;
    }
  }

  for (const rec of stubbedLabels) {
    const lb = labels[rec.label]!;
    const stub = wires[rec.wire]!;
    const clearAt = (x: number, y: number, rot: number = lb.rot): boolean => {
      const box = labelTextBox(lb.name, x, y, rot);
      if (bodies.some((b) => boundsOverlap(box, b))) return false;
      if (textObstacles.some((b) => boundsOverlap(box, b))) return false;
      if (wires.some((w, i) => i !== rec.wire && segHitsBox(w, box))) return false;
      // Foreign labels are part of what a label must clear, not just bodies and
      // wires. Without this the pass declares a point clear that another net's
      // label already holds, both labels stay put, and `findMergedNets` then
      // refuses the draft for a collision the avoider was never looking for —
      // an engine state no IR can steer out of, because the IR does not choose
      // coordinates. Read live from `labels`, so already-nudged neighbours are
      // seen at their final positions and immovable wired-net labels (which
      // carry no stub to ride) are seen at all.
      return !labels.some(
        (o, i) =>
          i !== rec.label &&
          o.name !== lb.name &&
          boundsOverlap(box, labelTextBox(o.name, o.x, o.y, o.rot)),
      );
    };
    /**
     * Does another net's label sit on exactly this point? That is the fatal
     * case — KiCad fuses the two nets — as opposed to merely overlapping text.
     */
    const mergesAt = (x: number, y: number): boolean =>
      labels.some((o, i) => i !== rec.label && o.name !== lb.name && sameCoord(o.x, x) && sameCoord(o.y, y));
    /**
     * Riding a label outward drags the stub's ENDPOINT with it (`rideTo` moves
     * both). Every test above this asks a typographic question — does the text
     * box clear a body, a wire, another label — and none asks the electrical
     * one, so the pass could answer "the text is clear here" about a point that
     * sits on another net's wire and silently tie the two together (#217:
     * interf_u rode /PC-RD's stub from 2 units to 4 and parked its end on
     * /WR_REG's trunk).
     *
     * A candidate must therefore be electrically clear as well as legible.
     * The stub's own wire needs no exclusion: `touchesForeign` skips wires of
     * the same net, and this one is the net's own.
     */
    const wireClearAt = (x: number, y: number): boolean =>
      !touchesForeign([{ x1: stub.x1, y1: stub.y1, x2: x, y2: y }], lb.name, new Set(rec.pins), {
        predictStubs: false,
      });
    const rideTo = (x: number, y: number): void => {
      stub.x2 = x;
      stub.y2 = y;
      lb.x = x;
      lb.y = y;
    };
    if (clearAt(lb.x, lb.y)) continue;
    /** Candidate points along the stub, nearest first. */
    const candidates: { x: number; y: number }[] = [];
    for (let extra = 1; extra <= MAX_LABEL_NUDGE; extra++) {
      const x = lb.x + rec.o.dx * extra * U;
      const y = lb.y + rec.o.dy * extra * U;
      // an extension that would run the stub through a symbol is no better
      // than the collision it fixes
      if (bodies.some((b) => segCrossesBody(stub.x1, stub.y1, x, y, b))) break;
      candidates.push({ x, y });
    }
    // Last rung: pull the stub BACK to one unit. Riding outward moves a
    // facing pair's text toward each other, so two long names in a tight
    // channel can never separate that way — but each is under a grid unit
    // deep into the other, and one unit of retreat clears it (#220 phase 2).
    {
      const shortened = { x: stub.x1 + rec.o.dx * U, y: stub.y1 + rec.o.dy * U };
      if (Math.abs(lb.x - stub.x1) + Math.abs(lb.y - stub.y1) > U + 0.01) candidates.push(shortened);
    }
    const clear = candidates.find((c) => clearAt(c.x, c.y) && wireClearAt(c.x, c.y));
    if (clear) {
      rideTo(clear.x, clear.y);
      continue;
    }
    // A vertical stub may flip its text to the other side of the anchor: a
    // trunk running parallel beside the stub blocks every rung on one side
    // while the other side is empty (#220 phase 2). The anchor point itself is
    // unchanged, so this is purely typographic — but the flipped box no longer
    // overlaps a same-point foreign label, so the merge check must be explicit.
    if (rec.o.dy !== 0) {
      const flipRot = lb.rot === 0 ? 180 : 0;
      const flip = [{ x: lb.x, y: lb.y }, ...candidates].find(
        (c) =>
          clearAt(c.x, c.y, flipRot) &&
          !mergesAt(c.x, c.y) &&
          (sameCoord(c.x, lb.x) && sameCoord(c.y, lb.y) ? true : wireClearAt(c.x, c.y)),
      );
      if (flip) {
        lb.rot = flipRot;
        rideTo(flip.x, flip.y);
        continue;
      }
    }
    // Nothing fully clear within the nudge budget. Overlapping text is a
    // legibility cost the sheet can carry and the report will name; a shared
    // point is a merged net and refuses the whole draft. So when the label is
    // currently ON another net's point, take the nearest candidate that at
    // least breaks the coincidence — trading a refusal for a flagged blemish.
    // A label that merely overlaps is left alone: moving it would buy nothing
    // and the emitted sheet must stay a function of the IR alone.
    if (!mergesAt(lb.x, lb.y)) continue;
    // Same precedence as above, one rung down: this is already the consolation
    // move for a label sitting on another net's point, so it may accept
    // overlapping text, but it still may not trade one merge for another.
    const unmerged = candidates.find((c) => !mergesAt(c.x, c.y) && wireClearAt(c.x, c.y));
    if (unmerged) rideTo(unmerged.x, unmerged.y);
  }

  // ---------- power-value sweep (#220 phase 2) ----------
  // The power pass placed its value text before any signal label existed, and
  // the label ride above can fail to clear in a dense row — whichever mover
  // ran last was blind to the other, and cm5_minima's residual error findings
  // were exactly "#PWR Value and label X overlap". The value text is the one
  // item on the sheet with no electrical meaning, so it moves LAST, with the
  // finished drawing as its obstacle set: slide it outward along its stub
  // axis, then allow a small lateral step, to the first slot the checker will
  // measure as clean. Nothing clear keeps the placed slot so the report stays
  // honest, and a value that is already clean does not move at all.
  {
    const labelBoxesFinal = labels.map((l) => labelTextBox(l.name, l.x, l.y, l.rot));
    const memberText = emitPairs.flatMap(({ sym: s, pl }) => [
      centeredTextBox(displayRefOf(pl), s.refAt.x, s.refAt.y),
      centeredTextBox(s.value, s.valueAt.x, s.valueAt.y),
    ]);
    const valueEntries = extraSymbols.filter((s) => !s.hideValue);
    const liveBoxes = new Map(valueEntries.map((s) => [s, powerValueBox(s.value, s.valueAt.x, s.valueAt.y)]));
    const clearFor = (self: EmitSymbol, b: Bounds): boolean =>
      !bodies.some((bd) => boundsOverlap(b, bd)) &&
      !wires.some((w) => segHitsBoxEarly(w, b)) &&
      !labelBoxesFinal.some((lb) => boundsOverlap(lb, b)) &&
      !memberText.some((t) => boundsOverlap(t, b)) &&
      ![...liveBoxes].some(([o, ob]) => o !== self && boundsOverlap(ob, b));
    for (const s of valueEntries) {
      if (clearFor(s, liveBoxes.get(s)!)) continue;
      // outward = the side of the symbol the text was already offset to
      const dir = Math.sign(s.valueAt.y - s.at.y) || -1;
      const cands: { x: number; y: number }[] = [];
      for (let k = 1; k <= 8; k++) cands.push({ x: s.valueAt.x, y: s.valueAt.y + dir * k * U });
      for (let k = 0; k <= 8; k++) {
        for (const lx of [U, -U, 2 * U, -2 * U, 3 * U, -3 * U, 4 * U, -4 * U]) {
          cands.push({ x: s.valueAt.x + lx, y: s.valueAt.y + dir * k * U });
        }
      }
      const found = cands.find((c) => clearFor(s, powerValueBox(s.value, c.x, c.y)));
      if (found) {
        s.valueAt = { x: found.x, y: found.y };
        liveBoxes.set(s, powerValueBox(s.value, found.x, found.y));
      }
    }
  }

  // junctions: any point where three or more wire ends meet
  const endCount = new Map<string, { x: number; y: number; n: number }>();
  for (const w of wires) {
    for (const [x, y] of [[w.x1, w.y1], [w.x2, w.y2]] as const) {
      const k = pointKey(x, y);
      const e = endCount.get(k) ?? { x, y, n: 0 };
      e.n++;
      endCount.set(k, e);
    }
  }
  for (const e of endCount.values()) if (e.n >= 3) junctions.push({ x: e.x, y: e.y });
  const uniqJunctions = [...new Map(junctions.map((j) => [pointKey(j.x, j.y), j])).values()];

  // no-connect markers (design D6a); a common pin's marker lands on every
  // placed appearance, mirroring how the wiring passes treat such pins
  const noConnects: { x: number; y: number }[] = [];
  for (const ep of intent.noConnect ?? []) {
    const m = /^([^.]+)\.(.+)$/.exec(ep);
    if (!m) continue;
    for (const inst of expandEp(m[1]!, m[2]!)) {
      const pl = placed.get(inst.key);
      const pin = pl?.sym.pins.find((p) => p.number === m[2]);
      if (pl && pin) noConnects.push(pinAt(pl, pin));
    }
  }

  // ---------- sheet: content-derived paper, balanced placement ----------
  const allX = [...groupRects.map((r) => r.x1), ...groupRects.map((r) => r.x2)];
  const allY = [...groupRects.map((r) => r.y1), ...groupRects.map((r) => r.y2)];
  const contentW = allX.length ? Math.max(...allX) - Math.min(...allX) : 0;
  const contentH = allY.length ? Math.max(...allY) - Math.min(...allY) : 0;
  // The sheet was already decided by the wrap-and-band pass above: `fit` names
  // the smallest candidate the final group rects fit (or the largest, noted,
  // when nothing holds them). Re-deriving it from content here could only
  // disagree with the budget the columns were banded to.
  const paper = fit.paper;

  // offset so content sits centered in the usable area (whitespace balance,
  // design D11), snapped to the grid so origins stay grid-true
  const minX = allX.length ? Math.min(...allX) : 0;
  const minY = allY.length ? Math.min(...allY) : 0;
  const availW = paper.w - 2 * FRAME;
  const availH = paper.h - 2 * FRAME - TITLE_STRIP;
  let dx = grid(Math.round((FRAME + Math.max(0, (availW - contentW) / 2) - minX) / U));
  let dy = grid(Math.round((FRAME + 4 * U + Math.max(0, (availH - contentH) / 2) - minY) / U));

  // The group rects measure bodies plus margins; label TEXT extends past them
  // at the sheet-facing edges, and on a sheet banded near the full usable
  // width the centered offset leaves that text outside the frame (#220
  // phase 1). Clamp the shift against the true extent, label boxes included:
  // a whole-unit correction keeps the grid, fires only when text would cross
  // the frame, and an extent wider than the window keeps the centered offset
  // (that overflow was already noted by the fit pass).
  const textBoxes = [
    ...labels.map((l) => labelTextBox(l.name, l.x, l.y, l.rot)),
    // power VALUE text is measured by the checker too, and the sweep above
    // may have slid it past its group rect's margin (pic_programmer put a
    // rail name 1 mm over the top edge of a compacted sheet)
    ...extraSymbols.filter((s) => !s.hideValue).map((s) => powerValueBox(s.value, s.valueAt.x, s.valueAt.y)),
  ];
  const fullMinX = Math.min(minX, ...textBoxes.map((b) => b.minX));
  const fullMaxX = Math.max(minX + contentW, ...textBoxes.map((b) => b.maxX));
  const fullMinY = Math.min(minY, ...textBoxes.map((b) => b.minY));
  const fullMaxY = Math.max(minY + contentH, ...textBoxes.map((b) => b.maxY));
  // Both edges are corrected, far edge first, so the whole-unit rounding of
  // the far-edge shift can never leave the near edge (the checker-visible
  // frame line) outside: the near-edge correction runs last and wins. When
  // the span nearly fills the window, the far edge may keep up to one unit
  // of overhang into the engine's conservative title strip; the strip is
  // wider than the checker's reserved corner, so that overhang is invisible.
  const clampShift = (d: number, lo0: number, hi0: number, lo: number, hi: number): number => {
    if (hi0 - lo0 > hi - lo) return d;
    if (hi0 + d > hi) d -= Math.ceil((hi0 + d - hi) / U - 1e-9) * U;
    if (lo0 + d < lo) d += Math.ceil((lo - lo0 - d) / U - 1e-9) * U;
    return d;
  };
  dx = clampShift(dx, fullMinX, fullMaxX, FRAME, paper.w - FRAME);
  // the bottom edge is the engine's own usable bottom, ABOVE the title strip:
  // content that fills the sheet's height exactly would otherwise carry the
  // centering pass's 4-unit downward offset into the reserved corner
  dy = clampShift(dy, fullMinY, fullMaxY, FRAME, paper.h - FRAME - TITLE_STRIP);
  const shift = <T extends { x?: number; y?: number; x1?: number; y1?: number; x2?: number; y2?: number }>(o: T): T => {
    if (o.x !== undefined) o.x += dx;
    if (o.y !== undefined) o.y += dy;
    if (o.x1 !== undefined) o.x1 += dx;
    if (o.y1 !== undefined) o.y1 += dy;
    if (o.x2 !== undefined) o.x2 += dx;
    if (o.y2 !== undefined) o.y2 += dy;
    return o;
  };
  for (const s of [...emitSymbols, ...extraSymbols]) {
    s.at.x += dx;
    s.at.y += dy;
    shift(s.refAt);
    shift(s.valueAt);
  }
  wires.forEach(shift);
  labels.forEach(shift);
  uniqJunctions.forEach(shift);
  noConnects.forEach(shift);
  groupRects.forEach(shift);

  // Two labels of DIFFERENT nets at one point is a merged net, not a cosmetic
  // overlap: KiCad resolves co-located labels to a single net and reports
  // `Both A and B are attached to the same items; A will be used in the
  // netlist` — as a warning. A live run drew ISET (charge-current program) and
  // NTC (thermistor input) onto the same node of a BQ24040 that way, which
  // would have shipped a board whose charge current is not set by its
  // programming resistor and whose temperature cutoff does not work.
  //
  // The engine computes every coordinate, so this is ours to catch, and it is
  // strictly worse than the failures we do gate: an unreadable sheet stops the
  // pipeline loudly, while a merged net passes ERC-as-warning and flows into
  // layout and fabrication outputs. Reported as a hard finding — the netlist
  // the IR declared is not the netlist that got drawn.
  const mergedNets = [
    ...findMergedNets(labels).map((m) => ({ ...m, via: 'labels' as const })),
    ...findWireContactMerges(wires, labels).map((m) => ({ ...m, via: 'wires' as const })),
  ];

  // Overlapping label TEXT is the other half of the same pass and deliberately
  // not a gate. The de-collision loop clears what it can and, where it cannot,
  // prefers a legible-but-overlapping position over a merged net. What survives
  // is counted against a budget and named in the report, so a sheet never ships
  // a blemish silently and never stalls a run over one either.
  const labelOverlaps = findLabelOverlaps(labels);
  const labelOverlapBudgetExceeded =
    labels.length > 0 && labelOverlaps.length / labels.length > LABEL_OVERLAP_BUDGET;
  if (labelOverlaps.length) {
    const pct = ((labelOverlaps.length / Math.max(1, labels.length)) * 100).toFixed(1);
    const where = labelOverlaps
      .slice(0, 8)
      .map((o) => `${o.nets.join('/')} at (${o.x}, ${o.y})`)
      .join('; ');
    notes.push(
      `${labelOverlapBudgetExceeded ? 'LABEL OVERLAP BUDGET EXCEEDED: ' : ''}` +
        `${labelOverlaps.length} of ${labels.length} label(s) (${pct}%, budget ` +
        `${(LABEL_OVERLAP_BUDGET * 100).toFixed(1)}%) overlap a foreign net's label text. ` +
        `The netlist is unaffected — these are legibility defects, listed so they can be ` +
        `fixed or accepted deliberately: ${where}` +
        `${labelOverlaps.length > 8 ? `; and ${labelOverlaps.length - 8} more` : ''}`,
    );
  }

  const model: PlacementModel = {
    projectName,
    paper: paper.name,
    title: { title: projectName, date: today, rev: 'A' },
    libSymbols: [...libSymbols.entries()].map(([libId, sourceText]) => ({ libId, sourceText })),
    symbols: [...emitSymbols, ...extraSymbols],
    wires,
    junctions: uniqJunctions,
    labels,
    noConnects,
    rectangles: groupRects.map((r) => ({ x1: r.x1, y1: r.y1, x2: r.x2, y2: r.y2, stroke: 'solid' as const, name: r.name })),
    captions: groupRects.map((r) => ({ text: r.name, x: r.x1 + 2, y: r.y1 + 2, name: r.name })),
  };

  const report: SchematicDraftReport = {
    groups: groupNames.map((g) => ({
      name: g,
      // instance keys fold back to refdes (a dual opamp is one member, not two)
      members: [
        ...new Set([...groupOf.entries()].filter(([, gg]) => gg === g).map(([k]) => placed.get(k)?.refDes ?? k)),
      ].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })),
    })),
    netClasses: [...netClasses.entries()]
      .sort((a, b) => a[0].localeCompare(b[0]))
      .map(([name, c]) => ({ name, class: c.cls, overridden: c.overridden, basis: c.basis })),
    wireCount: wires.length,
    labelCount: labels.length,
    pwrFlags,
    noConnects: noConnects.length,
    paper: paper.name,
    notes,
    mergedNets,
    labelOverlaps,
    labelOverlapBudgetExceeded,
  };
  return { model, report };
}