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.
`KiCadPcb.get_bounds()` is a source-model contract. Board graphical shapes use KiCad-style geometry bounds, including stroke-width expansion, and are tested separately from renderer viewBox behavior. PCB SVG output remains canonical through the plotter IR renderer; `KiCadPcb.to_svg()` delegates to that path rather than maintaining a second direct renderer.
KiCadPcb.from_file, KiCadPcb(path),
KiCadPcb.to_ir(), and KiCadPcb.to_svg() are
full-model paths. User-facing read-path and render-cost guidance is
canonical in Project
Workflows And Read-Path Selection.
Existing code may use KiCadPcb(path) to parse a file or
KiCadPcb() as an empty parser/model container.
from_file is the named loader. KiCadPcb.new()
is reserved for a blank KiCad-openable board with default document state,
including the standard layer stack and setup block.
Tests must cover board property mutation, object add/remove, read-only
object queries, the public board IR entrypoint, graphical source-model
bounds, layer-filtered board bounds, and IR-backed SVG wrapper behavior.
Numerical bounds parity should be proven with analytic cases and a direct
KiCad bbox oracle when the patched CLI is available. Blank-board creation
tests must prove KiCadPcb.new() emits a valid default layer
stack rather than the lower-level empty container.
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.
Projection may cache immutable source-derived indexes, including line-column lookups, direct child spans, and PCB net lookup tables, to avoid repeated scans on large boards. These caches are private acceleration details; projected objects, source metadata, and unresolved net fallback behavior remain the public contract.
A projection created from a file reads and scans the source text, then hydrates only the requested object families. The projection facade is the supported file-level PCB inventory API; measured tradeoffs and net-table caveats are canonical in Project Workflows And Read-Path Selection.
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.
Tests must also prove nested pad/model source spans retain exact offsets, line/column values, source text, and reparsed S-expression content, and that KiCad v10 name-only net references remain unresolved-by-ordinal when no top-level net table exists.
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.