Project-level tools need stable access to `.kicad_pro` text variables, variants, and JSON persistence without depending on raw dictionaries.
Wrap project JSON with typed helpers for text variables, variant lookup, serialization, and future project metadata.
Tests must cover JSON construction, text-variable get/set/remove behavior, variant iteration, file writing, and reload.
A project facade is public when callers can handle common project metadata without direct raw-JSON mutation.
Higher-level tools need a design aggregate that can load related project, schematic, and board documents and expose them through one query surface.
Aggregate project, schematic, and board objects; dispatch from common file suffixes; expose document queries; and provide design-level IR and JSON entrypoints. The design facade also expands hierarchical sheet instantiations so repeated schematic files can be rendered, indexed, and reviewed as distinct concrete sheet views.
Enriched schematic SVG metadata embeds the KiCad design JSON plus
view-local indexes. Applications should resolve a clicked schematic SVG
group by checking view_indexes.svg_to_net[group_id] first.
That entry returns the KiCad-facing net name and design net uid for the
rendered sheet view.
Repeated hierarchical sheets share source UUIDs, so design-wide lookups
can have multiple candidate nets for the same SVG id. The view-local
index is built from the rendered sheet instance path and is the preferred
API for interactive schematic highlighting. Use
design.indexes.sheet_svg_to_nets and
design.indexes.svg_to_nets only for cross-sheet analysis,
global search, and diagnostics.
const net = svgPayload.view_indexes.svg_to_net[groupId];
if (net) {
highlightNet(net.uid || net.name);
}Tests must cover file dispatch, aggregate object queries, schematic mutators, hierarchy instance navigation, design JSON output, schematic SVG view-local net linkage, and PCB IR delegation.
A design facade is public when CLI and application tools can work from one loaded design object rather than coordinating independent file models.
Application tools need to distinguish a schematic source file from each concrete place that file appears in a hierarchical design.
Represent one rendered sheet view with its source schematic, human sheet path, KiCad UUID instance path, parent sheet link, sheet numbering, and IR render arguments.
Use KiCadDesign.iter_schematic_instances() to enumerate all
concrete sheet views. Use
KiCadDesign.schematic_instances_for(source) to answer where
a schematic file or object is used, and use
child_schematic_instances() /
parent_schematic_instance() to navigate between a sheet view
and its immediate neighbors.
Tests must cover repeated use of one child schematic file, source-object and source-path lookup, parent/child navigation, UUID instance paths, and schematic IR argument generation.
A schematic instance record is public when higher-level tools can render and inspect each sheet view without reconstructing KiCad hierarchy paths themselves.