@huaqiu/dsh-eda-host 0.3.25 → 0.4.2

package/lib/index.d.mts

@@ -16,6 +16,8 @@ interface EdaHostConfig {
   hqEdgeBaseUrl?: string;
   /** Path prefix on the host; default "/api/v1/netlist". */
   netlistPathPrefix?: string;
+  /** Path prefix for PCB selection; default "/api/v1/pcb-selection". */
+  pcbSelectionPathPrefix?: string;
   /** Path prefix for host discovery; default "/api/v1/host". */
   hostPathPrefix?: string;
   /**
@@ -68,6 +70,123 @@ interface SchematicNetlist {
   components: SchematicComponent[];
   nets: ElectricalNet[];
 }
+/**
+ * Semantic PCB selection types.
+ *
+ * Self-contained structural mirror of `hq.pcb.v1` (the hq-edge-owned semantic
+ * protobuf contract for `PcbSelectionService.GetSelection`). Units follow the
+ * hq.pcb.v1 convention: positions/sizes/lengths in mm, rotations in degrees,
+ * `id` is the KiCad native object identity.
+ */
+interface PcbPoint {
+  x: number;
+  y: number;
+}
+interface PcbNetRef {
+  name: string;
+  code: number;
+}
+interface PcbPad {
+  id: string;
+  pin: string;
+  type: string;
+  shape: string;
+  position?: PcbPoint;
+  widthMm: number;
+  heightMm: number;
+  rotationDeg: number;
+  layer: string;
+  net?: PcbNetRef;
+}
+interface PcbFootprint {
+  id: string;
+  reference: string;
+  value: string;
+  footprint: string;
+  position?: PcbPoint;
+  rotationDeg: number;
+  pads: PcbPad[];
+}
+interface PcbTrack {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  widthMm: number;
+  lengthMm: number;
+  net?: PcbNetRef;
+}
+interface PcbArc {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  mid?: PcbPoint;
+  net?: PcbNetRef;
+}
+interface PcbVia {
+  id: string;
+  layers: string[];
+  drillMm: number;
+  viaType: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+}
+interface PcbSegment {
+  start?: PcbPoint;
+  end?: PcbPoint;
+}
+interface PcbZone {
+  id: string;
+  layer: string;
+  net?: PcbNetRef;
+  outline: PcbSegment[];
+}
+interface PcbShape {
+  id: string;
+  layer: string;
+  shapeType: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  center?: PcbPoint;
+  radiusMm: number;
+  mid?: PcbPoint;
+  widthMm: number;
+}
+interface PcbText {
+  id: string;
+  layer: string;
+  text: string;
+  position?: PcbPoint;
+  rotationDeg: number;
+  hJustify: string;
+  vJustify: string;
+}
+interface PcbDimension {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  value: string;
+  dimType: string;
+}
+interface PcbGroup {
+  id: string;
+  itemIds: string[];
+}
+interface PcbSelection {
+  footprints: PcbFootprint[];
+  pads: PcbPad[];
+  tracks: PcbTrack[];
+  arcs: PcbArc[];
+  vias: PcbVia[];
+  zones: PcbZone[];
+  shapes: PcbShape[];
+  texts: PcbText[];
+  dimensions: PcbDimension[];
+  groups: PcbGroup[];
+  nets: PcbNetRef[];
+}
 /**
  * Semantic error categories for netlist retrieval. Mirrors the gRPC status
  * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish
@@ -174,6 +293,12 @@ interface EdaHostClient {
   getEdaHostInfo(options?: EdaHostRequestOptions): Promise<EdaHostInfo>;
   /** Capabilities the host currently provides. */
   getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>;
+  /**
+   * Semantic PCB selection of the current PCB editor (hq.pcb.v1
+   * PcbSelectionService.GetSelection bridged through hq-edge). An empty
+   * selection resolves to an all-empty `PcbSelection` — never an error.
+   */
+  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSelection>;
 }
 /**
  * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
@@ -248,4 +373,4 @@ declare module '@deepseek-ai/cordis' {
  */
 declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
 //#endregion
-export { type EdaHostCapability, type EdaHostClient, type EdaHostConfig, type EdaHostExecutable, type EdaHostIdentity, type EdaHostInfo, type EdaHostInstallation, type EdaHostRequestOptions, type EdaHostType, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };
+export { type EdaHostCapability, type EdaHostClient, type EdaHostConfig, type EdaHostExecutable, type EdaHostIdentity, type EdaHostInfo, type EdaHostInstallation, type EdaHostRequestOptions, type EdaHostType, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PcbArc, type PcbDimension, type PcbFootprint, type PcbGroup, type PcbNetRef, type PcbPad, type PcbPoint, type PcbSegment, type PcbSelection, type PcbShape, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };

package/lib/index.mjs

@@ -9,12 +9,14 @@ const SCOPE_ROUTE = {
 function resolveEdaHostConfig(config, env = process.env) {
 	const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "";
 	const pathPrefix = config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? "/api/v1/netlist";
+	const pcbSelectionPrefix = config?.pcbSelectionPathPrefix ?? env.HQ_EDGE_PCB_SELECTION_PATH ?? "/api/v1/pcb-selection";
 	const hostPrefix = config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? "/api/v1/host";
 	const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS;
 	const timeout = Number.parseInt(String(timeoutRaw ?? ""), 10);
 	return {
 		hqEdgeBaseUrl: baseUrl,
 		netlistPathPrefix: pathPrefix,
+		pcbSelectionPathPrefix: pcbSelectionPrefix,
 		hostPathPrefix: hostPrefix,
 		requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
 	};
@@ -27,6 +29,10 @@ function hasHost(config) {
 function netlistUrlOf(config, scope) {
 	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.netlistPathPrefix ?? "/api/v1/netlist").replace(/^\/+|\/+$/g, "")}${SCOPE_ROUTE[scope]}`;
 }
+/** Build the absolute URL for the PCB selection route. */
+function pcbSelectionUrlOf(config) {
+	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.pcbSelectionPathPrefix ?? "/api/v1/pcb-selection").replace(/^\/+|\/+$/g, "")}`;
+}
 const HOST_ROUTE = {
 	info: "/info",
 	capabilities: "/capabilities"
@@ -185,6 +191,23 @@ function createEdaHostClient(config, deps = {}) {
 	async function fetchScope(scope, options) {
 		return parseNetlistBody(await getJson(netlistUrlOf(resolveConfig(), scope), options, "netlist"));
 	}
+	function parsePcbSelection(value) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new NetlistError("INTERNAL", "eda-host: malformed PCB selection response from hq-edge");
+		const asArray = (v) => Array.isArray(v) ? v : [];
+		return {
+			footprints: asArray(value.footprints),
+			pads: asArray(value.pads),
+			tracks: asArray(value.tracks),
+			arcs: asArray(value.arcs),
+			vias: asArray(value.vias),
+			zones: asArray(value.zones),
+			shapes: asArray(value.shapes),
+			texts: asArray(value.texts),
+			dimensions: asArray(value.dimensions),
+			groups: asArray(value.groups),
+			nets: asArray(value.nets)
+		};
+	}
 	return {
 		getSelectionNetlist: (options) => fetchScope("selection", options),
 		getProjectNetlist: (options) => fetchScope("project", options),
@@ -198,6 +221,9 @@ function createEdaHostClient(config, deps = {}) {
 			const body = await getJson(hostUrlOf(resolveConfig(), "capabilities"), options, "host capabilities");
 			if (!body || !Array.isArray(body.capabilities)) throw new NetlistError("INTERNAL", "eda-host: malformed host capabilities response from hq-edge");
 			return body.capabilities.filter((c) => typeof c === "string");
+		},
+		getPcbSelection: async (options) => {
+			return parsePcbSelection(await getJson(pcbSelectionUrlOf(resolveConfig()), options, "pcb selection"));
 		}
 	};
 }
@@ -298,51 +324,77 @@ function createNetListTools(env) {
 * a claim that the host can provide it, nothing more.
 */
 function createEdaHostTools(env) {
-	return [defineTool({
-		name: "get_eda_host_info",
-		description: "Describe the EDA host currently connected through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, info: { identity: { hostType, hostName, version }, installation: { applicationPath, executables[]: { name, path } } } }. Use it when you need factual information about the current EDA environment, such as \"what EDA host am I connected to\", \"what version is it\", \"where is it installed\", or \"where is kicad-cli\". The returned information is authoritative host-provided ground truth. " + ERROR_SEMANTICS,
-		parameters: {},
-		output: {
-			schema: { type: "json" },
-			render: renderJson
-		},
-		async execute(_args, exec) {
-			try {
-				const options = exec?.signal ? { signal: exec.signal } : {};
-				return asJson({
-					ok: true,
-					info: await env.client.getEdaHostInfo(options)
-				});
-			} catch (err) {
-				return asJson({
-					ok: false,
-					error: failureOf(err)
-				});
+	return [
+		defineTool({
+			name: "get_eda_host_info",
+			description: "Describe the EDA host currently connected through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, info: { identity: { hostType, hostName, version }, installation: { applicationPath, executables[]: { name, path } } } }. Use it when you need factual information about the current EDA environment, such as \"what EDA host am I connected to\", \"what version is it\", \"where is it installed\", or \"where is kicad-cli\". The returned information is authoritative host-provided ground truth. " + ERROR_SEMANTICS,
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			async execute(_args, exec) {
+				try {
+					const options = exec?.signal ? { signal: exec.signal } : {};
+					return asJson({
+						ok: true,
+						info: await env.client.getEdaHostInfo(options)
+					});
+				} catch (err) {
+					return asJson({
+						ok: false,
+						error: failureOf(err)
+					});
+				}
 			}
-		}
-	}), defineTool({
-		name: "get_eda_host_capabilities",
-		description: "List the capabilities the CURRENT EDA host provides, using EDA-independent capability identifiers such as EDA_HOST_CAPABILITY_NETLIST, EDA_HOST_CAPABILITY_PCB or EDA_HOST_CAPABILITY_BOM. Returns { ok, capabilities: string[] }. This is DISCOVERY, not execution: it reports capabilities already provided by the connected EDA host. Treat the returned capability list as the authoritative runtime contract for the current host. Do not assume a capability is available merely because the EDA application is generally known to support it. Unknown capability identifiers MUST be treated as unsupported. " + ERROR_SEMANTICS,
-		parameters: {},
-		output: {
-			schema: { type: "json" },
-			render: renderJson
-		},
-		async execute(_args, exec) {
-			try {
-				const options = exec?.signal ? { signal: exec.signal } : {};
-				return asJson({
-					ok: true,
-					capabilities: await env.client.getEdaHostCapabilities(options)
-				});
-			} catch (err) {
-				return asJson({
-					ok: false,
-					error: failureOf(err)
-				});
+		}),
+		defineTool({
+			name: "get_pcb_selection",
+			description: "Read the semantic PCB selection from the current PCB editor through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, selection: { footprints[], pads[], tracks[], arcs[], vias[], zones[], shapes[], texts[], dimensions[], groups[], nets[] } }. Each footprint has reference, value, footprint, position {x,y} in mm, rotationDeg and pads[] (pin, type, shape, position, widthMm, heightMm, rotationDeg, layer, net{name, code}); tracks have layer, start/end in mm, widthMm, lengthMm and net; vias have layers[], drillMm, viaType and start/end; zones have layer, net and outline segments. Every object carries id — the EDA-host native object identity. IMPORTANT: ok:true with all-empty arrays is a VALID empty selection (nothing selected) — do not treat it as a failure. " + ERROR_SEMANTICS,
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			async execute(_args, exec) {
+				try {
+					const options = exec?.signal ? { signal: exec.signal } : {};
+					return asJson({
+						ok: true,
+						selection: await env.client.getPcbSelection(options)
+					});
+				} catch (err) {
+					return asJson({
+						ok: false,
+						error: failureOf(err)
+					});
+				}
 			}
-		}
-	})];
+		}),
+		defineTool({
+			name: "get_eda_host_capabilities",
+			description: "List the capabilities the CURRENT EDA host provides, using EDA-independent capability identifiers such as EDA_HOST_CAPABILITY_NETLIST, EDA_HOST_CAPABILITY_PCB or EDA_HOST_CAPABILITY_BOM. Returns { ok, capabilities: string[] }. This is DISCOVERY, not execution: it reports capabilities already provided by the connected EDA host. Treat the returned capability list as the authoritative runtime contract for the current host. Do not assume a capability is available merely because the EDA application is generally known to support it. Unknown capability identifiers MUST be treated as unsupported. " + ERROR_SEMANTICS,
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			async execute(_args, exec) {
+				try {
+					const options = exec?.signal ? { signal: exec.signal } : {};
+					return asJson({
+						ok: true,
+						capabilities: await env.client.getEdaHostCapabilities(options)
+					});
+				} catch (err) {
+					return asJson({
+						ok: false,
+						error: failureOf(err)
+					});
+				}
+			}
+		})
+	];
 }
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-eda-host",
-  "version": "0.3.25",
+  "version": "0.4.2",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.3.25"
+    "@huaqiu/dsh-plugin-log": "0.4.2"
   },
   "files": [
     "lib",

package/src/client.ts

@@ -10,11 +10,12 @@
  * @module
  */
 
-import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
+import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbSelectionUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
 import {
   NetlistError,
   type EdaHostCapability,
   type EdaHostInfo,
+  type PcbSelection,
   type SchematicNetlist,
 } from './types.js'
 
@@ -51,6 +52,12 @@ export interface EdaHostClient {
   getEdaHostInfo(options?: EdaHostRequestOptions): Promise<EdaHostInfo>
   /** Capabilities the host currently provides. */
   getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>
+  /**
+   * Semantic PCB selection of the current PCB editor (hq.pcb.v1
+   * PcbSelectionService.GetSelection bridged through hq-edge). An empty
+   * selection resolves to an all-empty `PcbSelection` — never an error.
+   */
+  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSelection>
 }
 
 /** HTTP status → semantic error kind (see routes/edaHostStatus.ts on hq-edge). */
@@ -260,6 +267,32 @@ export function createEdaHostClient(
     return parseNetlistBody(await getJson(url, options, 'netlist'))
   }
 
+  function parsePcbSelection(value: unknown): PcbSelection {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new NetlistError(
+        'INTERNAL',
+        'eda-host: malformed PCB selection response from hq-edge',
+      )
+    }
+
+    const asArray = (v: unknown): unknown[] => (Array.isArray(v) ? v : [])
+
+    // proto3 JSON omits empty arrays; every field is a repeated list.
+    return {
+      footprints: asArray((value as Record<string, unknown>).footprints),
+      pads: asArray((value as Record<string, unknown>).pads),
+      tracks: asArray((value as Record<string, unknown>).tracks),
+      arcs: asArray((value as Record<string, unknown>).arcs),
+      vias: asArray((value as Record<string, unknown>).vias),
+      zones: asArray((value as Record<string, unknown>).zones),
+      shapes: asArray((value as Record<string, unknown>).shapes),
+      texts: asArray((value as Record<string, unknown>).texts),
+      dimensions: asArray((value as Record<string, unknown>).dimensions),
+      groups: asArray((value as Record<string, unknown>).groups),
+      nets: asArray((value as Record<string, unknown>).nets),
+    } as PcbSelection
+  }
+
   return {
     getSelectionNetlist: (options) => fetchScope('selection', options),
     getProjectNetlist: (options) => fetchScope('project', options),
@@ -293,5 +326,12 @@ export function createEdaHostClient(
         (c): c is EdaHostCapability => typeof c === 'string',
       )
     },
+
+    getPcbSelection: async (options) => {
+      const resolved = resolveConfig()
+      const url = pcbSelectionUrlOf(resolved)
+      const body = (await getJson(url, options, 'pcb selection')) as unknown
+      return parsePcbSelection(body)
+    },
   }
 }

package/src/config.ts

@@ -15,6 +15,8 @@ export interface EdaHostConfig {
   hqEdgeBaseUrl?: string
   /** Path prefix on the host; default "/api/v1/netlist". */
   netlistPathPrefix?: string
+  /** Path prefix for PCB selection; default "/api/v1/pcb-selection". */
+  pcbSelectionPathPrefix?: string
   /** Path prefix for host discovery; default "/api/v1/host". */
   hostPathPrefix?: string
   /**
@@ -30,6 +32,8 @@ export interface EdaHostConfig {
 
 export const DEFAULT_NETLIST_PATH_PREFIX = '/api/v1/netlist'
 
+export const DEFAULT_PCB_SELECTION_PATH_PREFIX = '/api/v1/pcb-selection'
+
 export const DEFAULT_HOST_PATH_PREFIX = '/api/v1/host'
 
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
@@ -50,6 +54,10 @@ export function resolveEdaHostConfig(
   const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? ''
   const pathPrefix =
     config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? DEFAULT_NETLIST_PATH_PREFIX
+  const pcbSelectionPrefix =
+    config?.pcbSelectionPathPrefix ??
+    env.HQ_EDGE_PCB_SELECTION_PATH ??
+    DEFAULT_PCB_SELECTION_PATH_PREFIX
   const hostPrefix =
     config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? DEFAULT_HOST_PATH_PREFIX
   const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS
@@ -57,6 +65,7 @@ export function resolveEdaHostConfig(
   return {
     hqEdgeBaseUrl: baseUrl,
     netlistPathPrefix: pathPrefix,
+    pcbSelectionPathPrefix: pcbSelectionPrefix,
     hostPathPrefix: hostPrefix,
     requestTimeoutMs:
       Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
@@ -75,6 +84,16 @@ export function netlistUrlOf(config: EdaHostConfig, scope: NetlistScope): string
   return `${base}/${prefix}${SCOPE_ROUTE[scope]}`
 }
 
+/** Build the absolute URL for the PCB selection route. */
+export function pcbSelectionUrlOf(config: EdaHostConfig): string {
+  const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
+  const prefix = (config.pcbSelectionPathPrefix ?? DEFAULT_PCB_SELECTION_PATH_PREFIX).replace(
+    /^\/+|\/+$/g,
+    '',
+  )
+  return `${base}/${prefix}`
+}
+
 /** Host discovery route suffix. */
 export type HostRoute = 'info' | 'capabilities'
 

package/src/index.ts

@@ -2,11 +2,12 @@
  * `@huaqiu/dsh-eda-host` — node plugin entry.
  *
  * Provides the `edaHost` service (semantic EDA-host capability) and registers
- * five agent tools:
+ * six agent tools:
  *
  *   get_project_netlist      complete project netlist
  *   get_selection_netlist    currently selected components netlist
  *   get_active_page_netlist  active schematic page netlist
+ *   get_pcb_selection        semantic PCB selection of the current PCB editor
  *   get_eda_host_info        which EDA host, version, installation
  *   get_eda_host_capabilities  what the current host can actually do
  *
@@ -63,6 +64,20 @@ export type {
   ElectricalNet,
   ElectricalType,
   NetlistErrorKind,
+  PcbArc,
+  PcbDimension,
+  PcbFootprint,
+  PcbGroup,
+  PcbNetRef,
+  PcbPad,
+  PcbPoint,
+  PcbSegment,
+  PcbSelection,
+  PcbShape,
+  PcbText,
+  PcbTrack,
+  PcbVia,
+  PcbZone,
   PinDefinition,
   PinReference,
   SchematicComponent,

package/src/tools.ts

@@ -24,7 +24,7 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { EdaHostClient, EdaHostRequestOptions } from './client.js'
-import { NetlistError, type EdaHostCapability, type EdaHostInfo, type SchematicNetlist } from './types.js'
+import { NetlistError, type EdaHostCapability, type EdaHostInfo, type PcbSelection, type SchematicNetlist } from './types.js'
 
 /** Structural alias of the DSH `JsonValue`. */
 type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
@@ -62,6 +62,10 @@ type HostCapabilitiesResult =
   | { ok: true; capabilities: EdaHostCapability[] }
   | { ok: false; error: { kind: string; message: string } }
 
+type PcbSelectionResult =
+  | { ok: true; selection: PcbSelection }
+  | { ok: false; error: { kind: string; message: string } }
+
 /**
  * Every failure kind, and what the agent should do about it.
  *
@@ -192,6 +196,36 @@ export function createNetListTools(env: NetlistToolEnv) {
        },
      }),
 
+     defineTool({
+       name: 'get_pcb_selection',
+       description:
+         `Read the semantic PCB selection from the current PCB editor through hq-edge ` +
+         `(DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, selection: { footprints[], ` +
+         `pads[], tracks[], arcs[], vias[], zones[], shapes[], texts[], dimensions[], groups[], ` +
+         `nets[] } }. ` +
+         `Each footprint has reference, value, footprint, position {x,y} in mm, rotationDeg and ` +
+         `pads[] (pin, type, shape, position, widthMm, heightMm, rotationDeg, layer, net{name, ` +
+         `code}); tracks have layer, start/end in mm, widthMm, lengthMm and net; vias have ` +
+         `layers[], drillMm, viaType and start/end; zones have layer, net and outline segments. ` +
+         `Every object carries id — the EDA-host native object identity. ` +
+         `IMPORTANT: ok:true with all-empty arrays is a VALID empty selection (nothing selected) ` +
+         `— do not treat it as a failure. ` +
+         ERROR_SEMANTICS,
+       parameters: {},
+       output: { schema: { type: 'json' }, render: renderJson },
+       async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
+         try {
+           const options: EdaHostRequestOptions = exec?.signal
+             ? { signal: exec.signal }
+             : {}
+           const selection = await env.client.getPcbSelection(options)
+           return asJson<PcbSelectionResult>({ ok: true, selection })
+         } catch (err) {
+           return asJson<PcbSelectionResult>({ ok: false, error: failureOf(err) })
+         }
+       },
+     }),
+
      defineTool({
        name: 'get_eda_host_capabilities',
        description:

package/src/types.ts

@@ -54,6 +54,138 @@ export interface SchematicNetlist {
   nets: ElectricalNet[]
 }
 
+/**
+ * Semantic PCB selection types.
+ *
+ * Self-contained structural mirror of `hq.pcb.v1` (the hq-edge-owned semantic
+ * protobuf contract for `PcbSelectionService.GetSelection`). Units follow the
+ * hq.pcb.v1 convention: positions/sizes/lengths in mm, rotations in degrees,
+ * `id` is the KiCad native object identity.
+ */
+
+export interface PcbPoint {
+  x: number
+  y: number
+}
+
+export interface PcbNetRef {
+  name: string
+  code: number
+}
+
+export interface PcbPad {
+  id: string
+  pin: string
+  type: string
+  shape: string
+  position?: PcbPoint
+  widthMm: number
+  heightMm: number
+  rotationDeg: number
+  layer: string
+  net?: PcbNetRef
+}
+
+export interface PcbFootprint {
+  id: string
+  reference: string
+  value: string
+  footprint: string
+  position?: PcbPoint
+  rotationDeg: number
+  pads: PcbPad[]
+}
+
+export interface PcbTrack {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  widthMm: number
+  lengthMm: number
+  net?: PcbNetRef
+}
+
+export interface PcbArc {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  mid?: PcbPoint
+  net?: PcbNetRef
+}
+
+export interface PcbVia {
+  id: string
+  layers: string[]
+  drillMm: number
+  viaType: string
+  start?: PcbPoint
+  end?: PcbPoint
+}
+
+export interface PcbSegment {
+  start?: PcbPoint
+  end?: PcbPoint
+}
+
+export interface PcbZone {
+  id: string
+  layer: string
+  net?: PcbNetRef
+  outline: PcbSegment[]
+}
+
+export interface PcbShape {
+  id: string
+  layer: string
+  shapeType: string
+  start?: PcbPoint
+  end?: PcbPoint
+  center?: PcbPoint
+  radiusMm: number
+  mid?: PcbPoint
+  widthMm: number
+}
+
+export interface PcbText {
+  id: string
+  layer: string
+  text: string
+  position?: PcbPoint
+  rotationDeg: number
+  hJustify: string
+  vJustify: string
+}
+
+export interface PcbDimension {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  value: string
+  dimType: string
+}
+
+export interface PcbGroup {
+  id: string
+  itemIds: string[]
+}
+
+export interface PcbSelection {
+  footprints: PcbFootprint[]
+  pads: PcbPad[]
+  tracks: PcbTrack[]
+  arcs: PcbArc[]
+  vias: PcbVia[]
+  zones: PcbZone[]
+  shapes: PcbShape[]
+  texts: PcbText[]
+  dimensions: PcbDimension[]
+  groups: PcbGroup[]
+  nets: PcbNetRef[]
+}
+
 /**
  * Semantic error categories for netlist retrieval. Mirrors the gRPC status
  * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish