Project-level tools need stable access to `.kicad_pro` text variables, variants, and JSON persistence without depending on raw dictionaries. Project creation tools also need a named aggregate API for assembling a new project folder without overloading the public constructor.
Wrap project JSON with typed helpers for text variables, variant lookup,
serialization, and future project metadata. For new project folders,
KiCadProject.create(name, directory) starts the writable
aggregate that can attach schematics, boards, library tables, worksheet
references, and then write the resulting folder.
from_file, from_text, and
from_json_dict load existing project JSON. The dataclass
constructor keeps its existing project-facade field order for
compatibility. New multi-file project assembly uses
KiCadProject.create, not positional constructor overloads.
Tests must cover JSON construction, text-variable get/set/remove behavior,
variant iteration, file writing, reload, constructor compatibility, and
KiCadProject.create folder assembly.
A project facade is public when callers can handle common project metadata without direct raw-JSON mutation, and can create new project folders through a named aggregate operation.
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.
KiCadDesign.from_project_file loads the project JSON and top
schematic up front. The adjacent PCB file is parsed lazily when
design.pcb, PCB IR, PCB SVG, or design JSON output needs
board data. User-facing workflow selection is canonical in
Project Workflows And
Read-Path Selection.
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.