Code organization

Modules before classes

Use functions in a concept-named module for pure transformations. Use an instance class only when several operations share state, that state has a clear lifetime, and the class protects an invariant.

Current stateful lifetimes:

• FamilyRegistry: one configured family catalogue;
• ChannelRoutingSession: one routing run;
• ClusterLayoutSession: one recursive cluster placement;
• TreePackingSession: one packing attempt.

There are no static utility classes.

File boundaries

A file owns one concept or algorithm phase—not one helper function and not an entire subsystem. Split when independent responsibilities can be named, tested, or documented separately. Do not split to satisfy an arbitrary line count.

Control flow

All control-flow bodies use multiline braces:

if (route.points.length < 2) {
  return fallback;
}

Mathematical code

packages/engine/README.md explains each subsystem’s inputs, outputs, phases, invariants, tuned constants, and deterministic tie-breaking in one place, rather than in a README per directory. Source comments explain why a rule exists and which visual failure it prevents; they do not narrate syntax.

Refactoring discipline

Move mechanics while preserving geometry first. Change policy separately and review the affected renders. A structural refactor should not require a snapshot update unless it also deliberately repairs an output contract.