@huaqiu/dsh-tool-kicad-schematic-gen 0.0.0-stage → 0.6.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @huaqiu/dsh-tool-kicad-schematic-gen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](README.zh.md)
+
+One installable plugin containing twelve tools and the kicad-schematic-design skill. Internal modules preserve the former component-library, module-catalog and schematic-tool contracts. Component search is provided by the KiCad built-in plugin @huaqiu/dsh-tool-part-search and its search_hqsch_parts tool.
+
+Configuration is grouped under components, modules.search, modules.download and schematic. Templates ship under skills/kicad-schematic-design; the public scripting API is available at ./builder. Module downloads resolve the current HQ Edge host at execution time, so a missing host does not prevent other tools or the skill from loading.
+
+Imports remain workspace scoped and use DSH sandbox policy. Model inspection reports pin/pad summaries; paired import checks unique pin/pad number sets, but does not verify electrical suitability or package dimensions. Placement and routing are explicitly authored in design scripts. Datasheet extraction preserves missing/truncated status.
+
+Build, typecheck and test from the repository workspace. Restart the KiCad assistant after replacing the old bundles. See [merge notes](../../docs/SCHEMATIC-MERGE.md).
+
+Paired import: `import_kicad_component({manufacturer_id, mpn, projectDir})` downloads a symbol and footprint, registers `sym-lib-table` and `fp-lib-table`, and returns `footprintId`. Place with `addSymbol({libraryPath, libId, footprint: footprintId, ...})`. Success requires both usable models and matching unique pin/pad number sets. Public tool arguments use required `manufacturer_id` and `mpn`, matching `@huaqiu/dsh-tool-part-search`; imports also accept optional `projectDir` (defaults to the workspace root). `mfgId` is retained only by the internal identity parser for legacy direct callers; schema-validated tool calls must use `manufacturer_id`. See the skill's [component and PCB reference](skills/kicad-schematic-design/references/component-pcb.md).
+
+Power symbols: declare actual shared nets with the builder's `requiredPowerSymbols` option. `powerLabelCatalog(nets)` returns current-build label UUIDs, coordinates and imported-module names for reproducible placement. `checkPowerSymbols()` and render/save reject missing symbols or unconverted labels for declared nets. Layout warnings still require visual review. See [power-symbol delivery](skills/kicad-schematic-design/references/power-symbols.md).
+
+`planPowerPlacements({libraryPath, nets})` plans bounded rotations, horizontal text placement and short straight leads before conversion. Diagnostics list unresolved overlaps and unmeasured objects; visual review remains required.
+
+Standalone common-only symbols with pins (e.g. SW-PTB-2_0_1) are automatically normalized in project copies to unit 1 without changing pins or graphics. Model summaries and import results report builderCompatibility.normalization=common_only_to_unit_1. Inherited, empty, malformed or alternate-only definitions are not normalized. Unsupported imports report part, symbol, sections and source URL.
+
+最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，显示页面切换、缩放、ZIP 下载。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer 与前端加载支持；不可用时仍返回本地预览路径。快照保存在插件 `.overview-cache/`，重启后可读取；移除该目录后历史卡片下载将失效。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
+
+Module analysis queries use `analyze_kicad_module({schematicPath, view, reference?, pin?, net?, offset?, kicadCliPath?})`, with explicit `view`. Downloads already return a summary: query only needed components, grouped nets or grouped BOM. CLI/project options are resolved internally; optional absolute `kicadCliPath` is for recovery using the existing `get_eda_host_info` result. On `CLI_START_FAILED`, retry analysis with that path and `view:summary`, without downloading again. Successful paths are reused; default CLI command names preserve automatic discovery. Probe errors return `error:{code,executable}` and retain causes; capability failures are distinct from startup failures. Matching same-stem projects and downloaded `.source.kicad_pro` files are discovered. Detail output contains `status`, `items`, and optional `nextOffset`/`warnings`; missing `nextOffset` means completion. Component custom fields require a reference filter. Partial results are reused for detail queries; after fixing configuration use `view:summary` to retry. Full local artifacts are preserved. This replaces the previous analysis query arguments and response contract; existing callers must migrate. See [module analysis](skills/kicad-schematic-design/references/module-analysis.md).

package/README.zh.md

@@ -0,0 +1,49 @@
+# @huaqiu/dsh-tool-kicad-schematic-gen
+
+将四个原理图插件统一安装为一个插件，内部继续分为 components、modules、schematic 与设计技能。
+
+| 模块 | 工具 |
+| --- | --- |
+| 器件模型与文档 | get_kicad_component_models、get_kicad_datasheet、import_kicad_symbol、import_kicad_component |
+| 电路模块搜索下载 | eda_module_rag_search、eda_module_category_search、eda_module_precise_search、download_eda_module_schematic |
+| 原理图工具 | get_kicad_module_ports、render_kicad_module_preview、create_kicad_hierarchy、edit_kicad_flat_schematic |
+
+同时注册 kicad-schematic-design 技能。元件搜索由KiCad 内置的 @huaqiu/dsh-tool-part-search 提供，调用 search_hqsch_parts。该搜索插件随 KiCad 提供，可在插件管理器中启用；原理图插件本身不注册它的四个查询工具。两者间将搜索结果的 manufacturer.id 映射为 manufacturer_id，mpn 保持不变；公开工具统一要求 manufacturer_id 和 mpn，不再暴露 mfgId；两个导入工具额外支持可选 projectDir，默认工作区根目录。内部身份解析保留旧调用兼容，经过工具 Schema 校验的调用必须使用 manufacturer_id。
+
+配置分为 components、modules.search、modules.download、schematic，使用原配置的默认限额。flatTemplateDir 默认指向本包技能模板。Node 22.19+，KiCad 10 CLI 路径可通过 schematic.kicadCliPath 配置。
+
+模块下载按调用时的 HQ Edge 宿主与当前项目校验；没有 HQ Edge 时只让该下载调用失败，其它工具仍注册。符号导入继续使用会话文件系统及沙箱策略。工具不是自动电气验证；模型摘要不检查引脚焊盘匹配，手册文字可能被截断，构建库的放置和布线由设计脚本显式指定。
+
+公开脚本入口是 lib/builder.js 或包的 ./builder 导出。设计技能、资源与模板位于 skills/kicad-schematic-design/。
+
+新导入器件库默认保存到 `project/libraries/symbols/` 和 `project/libraries/footprints/`，库表保留在 project 根目录，使用 `${KIPRJMOD}` 相对路径注册。相同器件重复导入复用原文件；旧项目已有根目录库时保持兼容，不自动移动。脚本使用导入返回的实际 libraryPath 和 footprintId；概览 ZIP 会递归收集 libraries 下的器件库。
+
+复用模块的封装通过 `localize_kicad_module_footprints` 的 list/import/check 流程本地化。模块下载现在保留 ZIP 中的 `.kicad_mod` 并返回 footprints 列表；缺失时使用明确选择的 manufacturer_id/mpn 查询在线封装。原嵌入符号、引脚和布线不替换，编号集合不匹配时拒绝导入。映射存入 `libraries/mappings/`，在设计脚本中使用 `importModule({...,footprintMappingPath})` 持久应用；来源变化后旧映射会拒绝使用。正式 delivery 在生成概览前验证根图和子页的本地封装引用。映射和封装一并进入项目 ZIP；尺寸、电气功能及 3D 完整性仍需单独确认。已有工程不会在插件加载时自动选择或替换器件。
+
+KiCad CLI 自动从当前运行时安装位置或 PATH 查找，也可通过 KICAD_CLI_PATH 或 schematic.kicadCliPath 指定。skill 加载时提供本机插件目录及符号库路径，脚本通过 DSH_SCHEMATIC_PLUGIN_DIR、KICAD_SYMBOL_DIR 使用这些路径。
+
+路径发现由配置与 skill 共用缓存，环境变量变化后重新识别。模型已有 get_eda_host_info 返回结果时，可以把其中的 kicad-cli 绝对路径传给 render_kicad_module_preview 的可选 kicadCliPath；只影响当前调用，不修改默认配置。原理图文件生成和预览不要求 PCB IPC 诊断或 Python 路径查询。
+
+正式概览快照保存到当前 DSH_HOME/plugin-data/dsh-tool-kicad-schematic-gen/overview-cache；没有 DSH_HOME 时使用用户数据目录，不要求插件安装目录可写。快照完整写入后才发布，旧会话仍可读取插件目录中原有的 .overview-cache。不会自动删除历史快照；手动清理对应快照后，旧会话中的下载和放置操作将失效。
+
+在工作区根目录执行 pnpm --filter @huaqiu/dsh-tool-kicad-schematic-gen build、typecheck 或 test。使用配套 DSH CLI 注册本目录，替换旧四个插件，并重新打开 KiCad AI 助手。历史备份和旧脚本兼容见 [合并说明](../../docs/SCHEMATIC-MERGE.md)。
+
+成套器件导入：`import_kicad_component({manufacturer_id, mpn, projectDir})` 同时下载符号与封装，登记两个项目库表，返回 `footprintId`。放置时传 `footprint: imported.footprintId`。两种实际模型可用且引脚/焊盘编号集合匹配才成功；仍需手册核对尺寸与功能。公开调用只使用 `manufacturer_id`，旧 `mfgId` 仅在内部解析层为历史直接调用保留。
+
+电源符号：在构建选项中声明实际共享网络 `requiredPowerSymbols`。`powerLabelCatalog(nets)` 返回本次标签 UUID、网络、坐标和导入模块名，按这些条件定位后生成 placements，不引用上一轮 UUID。`checkPowerSymbols()` 与 render/save 检查声明网络的标准符号和残留标签；未完成时拒绝保存。遮挡提示仍需局部预览确认，详见 [电源符号交付](skills/kicad-schematic-design/references/power-symbols.md)。
+
+`planPowerPlacements({libraryPath, nets})` 在转换前批量规划方向、水平文字与短引出线，返回 placements 和剩余问题诊断；局部预览仍需确认。
+
+含引脚的独立公共单元符号（如 SW-PTB-2_0_1）在项目副本中自动规范为单元 1，保留引脚与图形。模型摘要和导入结果通过 builderCompatibility.normalization=common_only_to_unit_1 报告；继承、空单元、异常命名及仅替代图形的符号不做自动规范。不支持的导入错误包含器件、符号、单元名称及源文件 URL。
+
+最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，显示页面切换、缩放、ZIP 下载。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer 与前端加载支持；不可用时仍返回本地预览路径。快照保存在插件 `.overview-cache/`，重启后可读取；移除该目录后历史卡片下载将失效。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
+# 生成流程耗时优化
+
+- 模块封装 `import` 返回 `stage: prepared`，仅表示本地库和映射准备完成；源文件默认不改写。`check_mapping` 验证来源应用映射后的状态，`check` 检查实际候选或最终原理图，避免混淆。
+- 封装准备最多 4 并发；项目库表按项目串行写入。批次验证失败不写库，错误返回失败 assignment 索引；已验证下载在当前进程缓存 15 分钟（最多 128 项、16 MiB），退出进程后清空。瞬时网络/429/5xx 错误内部最多重试一次，格式和编号错误不自动重试。
+- 使用现有供应商符号缓存对齐逻辑读取模块，支持旧式 `(module ...)` 封装的焊盘元数据，不改写源封装。编号核对不等于尺寸或电气验证。
+- builder 新增 `attachPinLabel`，支持显式方向、引线长度与通道错列；不推断引脚方向或自动避障。
+- 技能目录 `scripts/run-design.mjs` 使用参数数组启动生成脚本，将退出码、执行时间和完整输出保存为 UTF-8 JSON；终端仅返回摘要，避免 PowerShell 转义、输出截断和 BOM 返工。模块封装准备提前进行，文档与脚本复用连接计划。
+
+
+模块分析查询：`analyze_kicad_module({schematicPath, view, reference?, pin?, net?, offset?, kicadCliPath?})`。`view` 必填；下载已给分析摘要，直接查询所需 `components`、`nets` 或 `bom`。CLI/源工程默认内部解析；路径或启动失败 `CLI_START_FAILED` 时，复用 `get_eda_host_info` 返回的 kicad-cli 绝对路径，通过可选 `kicadCliPath` + `view:summary` 直接重试分析，不重新下载。成功路径后续复用，默认命令名不会覆盖自动发现；探测失败返回 `error:{code,executable}` 并区分启动、能力不支持、超时和命令失败。任意本地图采用同名 `.kicad_pro`，下载模块重启后可识别同名 `.source.kicad_pro`。详情返回 `status`、`items`、可选 `nextOffset`/`warnings`；网络按组分块，BOM 按全部物料字段与装配状态合并，器件自定义字段在指定 `reference` 时返回。部分失败结果供详情查询复用，修复后用 `view:summary` 重试。缺失 `nextOffset` 表示结束；不可用数据会明确警告。完整本地分析文件仍保留，详见 [模块分析](skills/kicad-schematic-design/references/module-analysis.md)。此接口替换旧版分析查询参数及返回结构，旧调用需同步更新。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: dsh-tool-kicad-schematic-gen
+      name: '@huaqiu/dsh-tool-kicad-schematic-gen'
+      inject: ['tools', 'fs', 'sandboxPolicy', 'skills', 'webServer']

package/lib/builder.d.ts

@@ -0,0 +1,486 @@
+//#region src/schematic/flat-layout.d.ts
+/** Axis-aligned range in schematic millimetres. Text ranges are conservative estimates. */
+interface FlatBounds {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+/** PNG placement metadata; image data is never returned to the model. */
+interface FlatImage {
+  pixels: [number, number];
+  ppi: number;
+  scale: number;
+  size: [number, number];
+}
+/** Template-controlled margins, grid, and conservative text metrics. */
+interface FlatLayoutStyle {
+  contentPadding: number;
+  grid: number;
+  textWidthFactor: number;
+  textHeightFactor: number;
+}
+//#endregion
+//#region src/schematic/flat.d.ts
+/** Coordinates in schematic millimetres. */
+type FlatPoint = [number, number];
+/** Explicit wire endpoint; pin numbers use the retained source symbol cache. */
+type FlatEndpoint = FlatPoint | {
+  reference: string;
+  pin: string;
+};
+/** One graphic module frame and its visible explanation. */
+type FlatFrame = {
+  name: string;
+  description: string;
+} & ({
+  start: FlatPoint;
+  end: FlatPoint;
+  autoBounds?: false;
+} | {
+  autoBounds: true;
+  objectUuids?: string[];
+  excludeUuids: string[];
+});
+/** Final frame coordinates, including automatically calculated ranges. */
+interface ResolvedFlatFrame {
+  name: string;
+  description: string;
+  start: FlatPoint;
+  end: FlatPoint;
+}
+/** Supported edits; deleting a component does not delete surrounding wires. */
+interface FlatPlan {
+  removeReferences: string[];
+  removeUuids: string[];
+  /** Selected source annotations only; electrical objects are rejected. */
+  removeTextUuids: string[];
+  setValues: Array<{
+    reference: string;
+    value: string;
+  }>;
+  setLabels: Array<{
+    uuid: string;
+    name?: string;
+    at?: FlatPoint;
+    angle?: number;
+  }>;
+  addWires: Array<{
+    from: FlatEndpoint;
+    to: FlatEndpoint;
+    via: FlatPoint[];
+  }>;
+  frames: FlatFrame[];
+}
+/** Editable top-level object returned by list action. */
+interface FlatObject {
+  type: string;
+  uuid: string;
+  reference?: string;
+  libId?: string;
+  unit?: number;
+  angle?: number;
+  mirror?: string;
+  footprint?: string;
+  dnp?: boolean;
+  value?: string;
+  name?: string;
+  at?: FlatPoint;
+  from?: FlatPoint;
+  to?: FlatPoint;
+  pinError?: string;
+  pins?: Array<{
+    number: string;
+    name: string;
+    at: FlatPoint;
+    electricalType: string;
+  }>;
+  bounds?: FlatBounds;
+  boundsError?: string;
+  image?: FlatImage;
+}
+/** Deployment-selected templates shared with the flat skill. */
+interface FlatTemplates {
+  project: Record<string, unknown> & {
+    meta: {
+      filename: string;
+      version: number;
+    };
+  };
+  frame: string;
+  style: FlatLayoutStyle & {
+    inset: number;
+    titleOffset: number;
+    descriptionBottom: number;
+    lineHeight: number;
+    wireWidth: number;
+  };
+}
+/** List editable IDs and pin locations without inspecting net connectivity or writing files.
+ * @param source Exact source schematic text.
+ * @param style Optional template-selected text allowances for layout measurements.
+ * @returns Object IDs and component pins, plus PNG geometry and optional conservative bounds.
+ */
+declare function listFlatObjects(source: string, style?: FlatLayoutStyle): FlatObject[];
+/** Apply an explicit plan and create a project copy in memory; no endpoint audit or external processes run.
+ * @param source Existing single-sheet source with embedded symbols.
+ * @param projectName ASCII project filename stem.
+ * @param plan Explicit edits and module frames with manual or automatic bounds.
+ * @param templates Validated project and graphic templates.
+ * @returns New schematic and project text, resolved frame coordinates, and applied edit counts.
+ */
+declare function buildFlatCopy(source: string, projectName: string, plan: FlatPlan, templates: FlatTemplates): {
+  schematic: string;
+  project: string;
+  resolvedFrames: ResolvedFlatFrame[];
+  changes: {
+    removedObjects: number;
+    changedValues: number;
+    changedLabels: number;
+    addedWireSegments: number;
+    addedFrames: number;
+  };
+};
+//#endregion
+//#region src/schematic/import-flat.d.ts
+/** Explicit module placement and shared network names; other named nets remain private. */
+interface FlatImportSpec {
+  name: string;
+  offset: FlatPoint;
+  nets: Record<string, string>;
+}
+/** Imported object identities, renamed references and source-label anchors on the final sheet. */
+interface FlatImportResult {
+  references: Record<string, string>;
+  ports: Record<string, FlatPoint[]>;
+  netNames: Record<string, string>;
+  objectUuids: string[];
+}
+//#endregion
+//#region src/schematic/power-layout.d.ts
+interface PowerPlacementPlan {
+  placements: NonNullable<PowerLabelSpec['placements']>;
+  diagnostics: {
+    plannedCount: number;
+    rotatedCount: number;
+    movedCount: number;
+    candidateCount: number;
+    unresolved: Array<{
+      uuid: string;
+      net: string;
+      at: FlatPoint;
+      obstacleUuids: string[];
+    }>;
+    unmeasuredObjectUuids: string[];
+  };
+}
+interface PowerPlanningOptions extends Pick<PowerLabelSpec, 'libraryPath' | 'nets'> {
+  clearanceMm?: number;
+  /** Maximum short cardinal lead, 0 disables movement. Default 5.08 mm. */
+  maxMoveMm?: number;
+}
+//#endregion
+//#region src/schematic/builder.d.ts
+/** Explicit instance placement in millimetres; library files must be trusted project inputs. */
+interface SymbolPlacement {
+  libraryPath: string;
+  libId: string;
+  reference: string;
+  at: FlatPoint;
+  value?: string;
+  angle?: 0 | 90 | 180 | 270;
+  mirror?: 'x' | 'y';
+  unit?: number;
+  footprint?: string;
+  referenceAt?: FlatPoint;
+  valueAt?: FlatPoint;
+  fieldAngle?: number;
+  hideReference?: boolean;
+  hideValue?: boolean;
+}
+/** Explicit deployment templates and page choice; no implicit file discovery. */
+interface SchematicOptions {
+  projectName: string;
+  templateDir: string;
+  paper: 'A4' | 'A3' | 'A2' | 'A1' | 'A0';
+  title: string;
+  /** Explicit shared power nets required before render/save; never inferred from names. */
+  requiredPowerSymbols?: Record<string, string>;
+}
+/** Planned module rectangle; origin and size use sheet millimetres. */
+interface ModuleRegionSpec {
+  name: string;
+  description: string;
+  origin: FlatPoint;
+  size: FlatPoint;
+}
+/** Explicit shared-net conversion; library Value must equal each selected network name. */
+interface PowerLabelSpec {
+  libraryPath: string;
+  nets: Record<string, string>;
+  placements?: Record<string, {
+    at: FlatPoint;
+    via?: FlatPoint[];
+    angle?: 0 | 90 | 180 | 270;
+    valueAt?: FlatPoint;
+  }>;
+}
+/** Conservative power-symbol overlap hint; not an electrical check. */
+interface PowerLayoutWarning {
+  code: 'POWER_LAYOUT_OVERLAP';
+  uuid: string;
+  reference: string;
+  otherUuid: string;
+  otherType: string;
+}
+/** Converted label identity and final symbol pin position; explicit movement adds connected wire segments. */
+interface PowerLabelReplacement {
+  uuid: string;
+  reference: string;
+  net: string;
+  libId: string;
+  at: FlatPoint;
+}
+/** Current-build label identity and sheet coordinates; module identifies imported provenance. */
+interface PowerLabelEntry {
+  uuid: string;
+  net: string;
+  at: FlatPoint;
+  angle: number;
+  type: 'label' | 'global_label';
+  module?: string;
+}
+/** Structural completion check, not connectivity or layout verification. */
+interface PowerSymbolStatus {
+  net: string;
+  libId: string;
+  symbolCount: number;
+  remainingLabelUuids: string[];
+}
+/** Region-local script operations; changing its origin in the script moves the regenerated group. */
+declare class ModuleRegion {
+  private readonly schematic;
+  private readonly origin;
+  /** Keep one planned origin for symbols, properties, wire bends and annotations.
+   * @param schematic Owning sheet. @param origin Planned top-left sheet coordinate.
+   */
+  constructor(schematic: Schematic, origin: FlatPoint);
+  /** Convert a region-relative coordinate to sheet coordinates.
+   * @param local Millimetres from the region's top-left. @returns Sheet coordinate.
+   */
+  at(local: FlatPoint): FlatPoint;
+  /** Place an instance with region-relative position and explicit property anchors.
+   * @param spec Actual symbol and local placement. @returns Instance UUID.
+   */
+  addSymbol(spec: SymbolPlacement): string;
+  /** Resolve a placed pin as a region-relative coordinate.
+   * @param reference Placed instance. @param number Actual pin number. @returns Local coordinate.
+   */
+  pin(reference: string, number: string): FlatPoint;
+  private endpoint;
+  /** Route local points or named pins through local explicit bends.
+   * @param from Local point or pin. @param to Local point or pin. @param via Local bends.
+   * @returns Segment UUIDs.
+   */
+  wire(from: FlatEndpoint, to: FlatEndpoint, via?: FlatPoint[]): string[];
+  /** Add a local network label.
+   * @param name Network name. @param at Local point or pin. @param angle Orthogonal angle. @returns UUID.
+   */
+  label(name: string, at: FlatEndpoint, angle?: 0 | 90 | 180 | 270): string;
+  /** Mark an explicit branch or intentionally unused pin.
+   * @param kind Marker kind. @param at Local point or pin. @returns UUID.
+   */
+  marker(kind: 'junction' | 'no_connect', at: FlatEndpoint): string;
+  /** Add an explicitly connected child-sheet port at a local point or actual pin.
+   * @param name Port name. @param at Local point or actual pin. @param angle Text rotation.
+   * @returns Label UUID.
+   */
+  hierarchicalLabel(name: string, at: FlatEndpoint, angle?: 0 | 90 | 180 | 270): string;
+}
+/** Build a circuit through explicit script calls; generation errors throw before save. */
+declare class Schematic {
+  private readonly options;
+  private readonly rootId;
+  private readonly definitions;
+  private readonly instances;
+  private readonly graphics;
+  private readonly references;
+  private placedPins;
+  private readonly frames;
+  private readonly regions;
+  private readonly importedModules;
+  private readonly objectModules;
+  private readonly requiredPowerSymbols;
+  private readonly templates;
+  /** Load validated templates. @param options Project identity, page and template directory. */
+  constructor(options: SchematicOptions);
+  /** Reserve a non-overlapping fixed module frame before placing its circuit.
+   * @param spec Model-planned size, origin, title and explanation.
+   * @returns Local-coordinate operations; no content fitting or automatic placement is performed.
+   */
+  region(spec: ModuleRegionSpec): ModuleRegion;
+  private source;
+  /** Persist source-reference mappings in scripts after importModule returns final references. */
+  assignFootprints(mappings: Record<string, string>): void;
+  /** Merge an existing single-sheet circuit, isolating private nets and renumbering instances.
+   * @param spec Source path, unique module name, global translation and explicit shared nets.
+   * @returns Reference map, translated label anchors, net names and object UUIDs for frames.
+   */
+  importModule(spec: FlatImportSpec & {
+    sourcePath: string;
+    footprintMappingPath?: string;
+  }): FlatImportResult;
+  /** Place a symbol using its actual library definition, expanding simple inheritance.
+   * @param spec Exact library symbol and model-selected placement.
+   * @returns UUID for grouping this instance in a frame.
+   */
+  addSymbol(spec: SymbolPlacement): string;
+  /** Read every placed pin in one catalog, including rotation and mirror transforms.
+   * @returns Instance identities, exact sheet pins and explicit pin errors; no connectivity is inferred.
+   */
+  pinCatalog(): ReturnType<typeof listFlatObjects>;
+  /** Resolve a placed symbol's numbered pin; ambiguous multi-unit matches fail.
+   * @param reference Placed reference. @param number Actual library pin number.
+   * @returns Transformed sheet coordinates in millimetres.
+   */
+  pin(reference: string, number: string): FlatPoint;
+  private endpoint;
+  /** Add explicitly routed orthogonal wire segments; no junctions are inferred.
+   * @param from Pin or coordinate. @param to Pin or coordinate. @param via Explicit intermediate bends.
+   * @returns UUIDs of generated segments for frame grouping.
+   */
+  wire(from: FlatEndpoint, to: FlatEndpoint, via?: FlatPoint[]): string[];
+  /** Add a local electrical label at a pin or wire point.
+   * @param name Exact network name. @param at Explicit anchor. @param angle Text rotation.
+   * @returns Label UUID for grouping.
+   */
+  label(name: string, at: FlatEndpoint, angle?: 0 | 90 | 180 | 270): string;
+  /** List only explicitly selected local/global labels in this build, before conversion.
+   * UUIDs are fresh each build; select by module/net/coordinates and use this returned UUID.
+   * @param nets Exact shared networks, never a heuristic power-name filter.
+   * @returns Detached label records in sheet millimetres; hierarchical labels are excluded.
+   */
+  powerLabelCatalog(nets: readonly string[]): PowerLabelEntry[];
+  /** Verify constructor-declared power-symbol delivery requirements before publication.
+   * Each exact net must have a genuine power definition, matching libId and Value,
+   * and no unconverted local/global label. Does not infer or merge power domains.
+   * @returns Per-net completion counts; throws without mutating the sheet on failure.
+   */
+  checkPowerSymbols(): PowerSymbolStatus[];
+  /** Plan bounded cardinal rotations, readable text positions and safe short straight leads.
+   * Does not mutate the sheet; consume placements in replacePowerLabels in this same build.
+   * Unresolved conservative overlaps are returned, not presented as a clean layout.
+   */
+  planPowerPlacements(spec: PowerPlanningOptions): PowerPlacementPlan;
+  /** Replace explicitly shared local/global power labels using zero-length-pin power symbols.
+   * @param spec Trusted library, exact net map and optional label-UUID placements with caller-routed bends.
+   * @returns Replaced labels with retained UUIDs and network names; moved anchors receive explicit connecting wires.
+   */
+  replacePowerLabels(spec: PowerLabelSpec): PowerLabelReplacement[];
+  /** Locate conservative overlaps around power symbols and their visible fields.
+   * @returns Suspected object intersections; attached wire endpoints are excluded. Review hints in preview.
+   */
+  powerLayoutWarnings(): PowerLayoutWarning[];
+  /** Add a passive hierarchy port connected at an explicit anchor; no connection is inferred.
+   * @param name Port name. @param at Actual pin or sheet coordinate. @param angle Text rotation.
+   * @returns Label UUID for a generated child sheet.
+   */
+  hierarchicalLabel(name: string, at: FlatEndpoint, angle?: 0 | 90 | 180 | 270): string;
+  /** Add an explicit branch junction or intentionally unconnected pin marker.
+   * @param kind Marker kind. @param at Pin or coordinate.
+   * @returns Marker UUID.
+   */
+  marker(kind: 'junction' | 'no_connect', at: FlatEndpoint): string;
+  /** Add a module frame with manual bounds or explicitly grouped automatic bounds.
+   * @param frame Visible title, explanation and range selection; omitted excludeUuids resolves to an empty list.
+   */
+  frame(frame: {
+    name: string;
+    description: string;
+  } & ({
+    start: FlatPoint;
+    end: FlatPoint;
+    autoBounds?: false;
+  } | {
+    autoBounds: true;
+    objectUuids?: string[];
+    excludeUuids?: string[];
+  })): void;
+  /** Serialize the current design with existing frame and project templates.
+   * @returns Schematic text, project JSON text, resolved frames and edit counts.
+   */
+  render(): ReturnType<typeof buildFlatCopy>;
+  /** Write a new output pair without overwriting existing files; use a unique candidate directory.
+   * @param directory Explicit output directory; created recursively when absent.
+   * @returns Written paths, resolved frames and conservative power-layout warnings from the saved design. Errors may leave a partial pair.
+   */
+  save(directory: string): {
+    schematicPath: string;
+    projectPath: string;
+    frames: ResolvedFlatFrame[];
+    layoutWarnings: PowerLayoutWarning[];
+  };
+}
+//#endregion
+//#region src/runtime-paths.d.ts
+/** Explicit paths override discovery; default command names still discover the host and PATH. */
+declare function resolveKiCadPaths(executable?: string, env?: NodeJS.ProcessEnv): {
+  kicadCliPath: string;
+  symbolDir?: string;
+};
+//#endregion
+//#region src/schematic/label-leads.d.ts
+interface LabelTarget {
+  pin(reference: string, number: string): FlatPoint;
+  wire(from: FlatPoint, to: FlatPoint, via?: FlatPoint[]): unknown;
+  label(name: string, at: FlatPoint, angle?: number): unknown;
+}
+/** Explicit, reusable label fanout. Caller chooses outward direction and clear lanes.
+ * Coordinates stay in the target's coordinate system (sheet or region).
+ * This does not infer pin orientation, avoid obstacles or validate connectivity.
+ */
+declare function attachPinLabel(target: LabelTarget, spec: {
+  reference: string;
+  pin: string;
+  net: string;
+  direction: 'left' | 'right' | 'up' | 'down';
+  length?: number;
+  lane?: number;
+  pitch?: number;
+}): {
+  at: FlatPoint;
+  label: unknown;
+};
+/** One side of a symbol: straight leads and labels over wires by default.
+ * Does not infer pin sides or reroute existing connections. Inspect warnings in preview.
+ */
+declare function attachPinLabels(target: LabelTarget, spec: {
+  reference: string;
+  pins: {
+    pin: string;
+    net: string;
+  }[];
+  direction: 'left' | 'right' | 'up' | 'down';
+  length?: number;
+  alignAt?: number;
+  minPitch?: number;
+  textPosition?: 'overWire' | 'outside';
+}): {
+  items: {
+    pin: string;
+    net: string;
+    at: FlatPoint;
+    end: FlatPoint;
+    label: unknown;
+  }[];
+  warnings: ({
+    code: "LABEL_PITCH_TIGHT";
+    pins: string[];
+    pitch: number;
+  } | {
+    code: "LABEL_LEAD_SHORT";
+    pins: string[];
+  })[];
+};
+//#endregion
+export { ModuleRegion, ModuleRegionSpec, PowerLabelEntry, PowerLabelReplacement, PowerLabelSpec, PowerLayoutWarning, type PowerPlacementPlan, type PowerPlanningOptions, PowerSymbolStatus, Schematic, SchematicOptions, SymbolPlacement, attachPinLabel, attachPinLabels, resolveKiCadPaths };