Board-level tools need a stable facade for object query, property cleanup, mutation, serialization, and IR-backed board SVG generation.
Own the PCB OOP model and provide common object, property, and IR methods without exposing parser internals.
Tests must cover board property mutation, object add/remove, read-only object queries, and the public board IR entrypoint.
A PCB facade is public when downstream tools can inspect and modify board content through the model before rendering or writing.
Large boards need fast source-aware access to selected PCB sub-objects without paying the cost of a complete board parse for every workflow.
Project selected board forms into the same domain object classes returned by `KiCadPcb`, while preserving exact source spans for diagnostics and repair tooling.
Tests must prove projected footprints, vias, tracks, graphics, layers, pads, and model references hydrate as normal domain objects and match full parser counts on real corpus boards.
A PCB projection facade is public when callers can use projected objects like full-parser objects and can recover source spans for those objects.
Projection callers need exact source ownership for object diagnostics, comparisons, and targeted rewrite tools.
Carry the exact selected form span and optional parent span associated with one projected domain object.
Tests must prove source metadata can return exact object text and parse back to the selected KiCad S-expression form.
Source metadata is public when projected objects can be mapped back to their file text without requiring a full board parse.
3D model health checks need parent footprint context and source spans for nested model forms.
Represent one footprint-owned model reference with the hydrated model object, parent footprint, and source span context.
Tests must prove model references expose parent reference/value data, model path data, and nested model source spans.
A model reference inventory record is public when project health and library extraction tools can inspect model usage without custom scanners.
Standalone `.kicad_mod` files are edited and rendered independently of a board, so they need their own facade.
Represent one standalone footprint file with object query, property mutation, serialization, and footprint IR conversion.
Tests must cover reference/value helpers, object add/remove, property queries, and standalone footprint IR output.
A standalone footprint facade is public when callers can use the same query and property style as board-embedded footprints.
Board workflows often mutate placed footprint properties and graphics before generating SVG, netlist, or assembly views.
Represent a board-embedded footprint with object query, named property helpers, and PCB-footprint IR conversion.
Tests must cover property mutation, embedded object queries, object add/remove, and footprint-record IR output.
An embedded footprint is public when board callers can manipulate it through the same facade style as standalone footprint files.