@huaqiu/dsh-eda-host 0.6.24 → 0.6.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.mts CHANGED
@@ -29,6 +29,11 @@ interface EdaHostConfig {
29
29
  * hq-edge forwards it to the EDA host's native handler.
30
30
  */
31
31
  syncSchematicToPcbPathPrefix?: string;
32
+ /**
33
+ * Path prefix for schematic render (PNG/SVG export); default
34
+ * "/api/v1/schematic-render". Covers capabilities, sheet listing, and render.
35
+ */
36
+ schematicRenderPathPrefix?: string;
32
37
  /**
33
38
  * End-to-end budget for one EDA-host request, in milliseconds.
34
39
  *
@@ -245,7 +250,7 @@ type EdaHostType = 'EDA_HOST_TYPE_UNSPECIFIED' | 'EDA_HOST_TYPE_KICAD' | 'EDA_HO
245
250
  * MUST be treated as "not supported" so a newer host cannot confuse an older
246
251
  * plugin.
247
252
  */
248
- type EdaHostCapability = 'EDA_HOST_CAPABILITY_UNSPECIFIED' | 'EDA_HOST_CAPABILITY_SCHEMATIC' | 'EDA_HOST_CAPABILITY_PCB' | 'EDA_HOST_CAPABILITY_NETLIST' | 'EDA_HOST_CAPABILITY_NETLIST_SELECTION' | 'EDA_HOST_CAPABILITY_NETLIST_ACTIVE_PAGE' | 'EDA_HOST_CAPABILITY_ERC' | 'EDA_HOST_CAPABILITY_DRC' | 'EDA_HOST_CAPABILITY_BOM' | 'EDA_HOST_CAPABILITY_PLACEMENT';
253
+ type EdaHostCapability = 'EDA_HOST_CAPABILITY_UNSPECIFIED' | 'EDA_HOST_CAPABILITY_SCHEMATIC' | 'EDA_HOST_CAPABILITY_PCB' | 'EDA_HOST_CAPABILITY_NETLIST' | 'EDA_HOST_CAPABILITY_NETLIST_SELECTION' | 'EDA_HOST_CAPABILITY_NETLIST_ACTIVE_PAGE' | 'EDA_HOST_CAPABILITY_ERC' | 'EDA_HOST_CAPABILITY_DRC' | 'EDA_HOST_CAPABILITY_BOM' | 'EDA_HOST_CAPABILITY_PLACEMENT' | 'EDA_HOST_CAPABILITY_SCHEMATIC_RENDER';
249
254
  /** A host-provided command line tool. */
250
255
  interface EdaHostExecutable {
251
256
  /** Stable tool name, e.g. "kicad-cli". */
@@ -283,6 +288,87 @@ interface EdaHostInfo {
283
288
  identity: EdaHostIdentity;
284
289
  installation: EdaHostInstallation;
285
290
  }
291
+ /** Mirror of protobuf `SchematicSource` enum. */
292
+ type SchematicSource = 'SCHEMATIC_SOURCE_UNSPECIFIED' | 'SCHEMATIC_SOURCE_ACTIVE_DOCUMENT' | 'SCHEMATIC_SOURCE_DOCUMENT_ID';
293
+ /** Mirror of protobuf `SchematicImageFormat` enum. */
294
+ type SchematicImageFormat = 'SCHEMATIC_IMAGE_FORMAT_UNSPECIFIED' | 'SCHEMATIC_IMAGE_FORMAT_PNG';
295
+ /**
296
+ * Mirror of protobuf `SchematicDocumentRef`. Identifies which schematic
297
+ * document to render. When `source` is `ACTIVE_DOCUMENT`, `documentId` is
298
+ * ignored; when `source` is `DOCUMENT_ID`, `documentId` must be provided.
299
+ */
300
+ interface SchematicDocumentRef {
301
+ source: SchematicSource;
302
+ documentId?: string;
303
+ }
304
+ /** Mirror of protobuf `GetRenderCapabilitiesResponse`. */
305
+ interface RenderCapabilities {
306
+ supportsActiveDocument: boolean;
307
+ supportsDocumentId: boolean;
308
+ supportsHierarchy: boolean;
309
+ supportsSheetInstance: boolean;
310
+ supportsPng: boolean;
311
+ supportsSvg: boolean;
312
+ supportsRegionRender: boolean;
313
+ maxWidth: number;
314
+ maxHeight: number;
315
+ }
316
+ /** Mirror of protobuf `SchematicSheetInstance`. */
317
+ interface SchematicSheetInstance {
318
+ instancePath: string;
319
+ sheetName: string;
320
+ sourcePath: string;
321
+ sheetUuid: string;
322
+ }
323
+ /** Mirror of protobuf `ListSchematicSheetsResponse`. */
324
+ interface ListSchematicSheetsResult {
325
+ documentId: string;
326
+ documentRevision: string;
327
+ sheets: SchematicSheetInstance[];
328
+ }
329
+ /**
330
+ * Input parameters for `RenderSchematicRequest`. The tool layer supplies
331
+ * defaults (PNG format, active document); all fields are optional here so
332
+ * the tool call can be minimal.
333
+ */
334
+ interface RenderSchematicParams {
335
+ document?: SchematicDocumentRef;
336
+ /** Empty means render all sheets (when `activeDocument` is false). */
337
+ sheetInstancePaths?: string[];
338
+ /** Numeric enum value (1 = PNG) or its enum-name alias. */
339
+ format?: SchematicImageFormat | number;
340
+ maxWidth?: number;
341
+ maxHeight?: number;
342
+ scale?: number;
343
+ transparentBackground?: boolean;
344
+ expectedRevision?: string;
345
+ /**
346
+ * `true` (default): render only the currently-active sheet in frame.
347
+ * `false`: render according to `sheetInstancePaths` (empty → all sheets).
348
+ */
349
+ activeDocument?: boolean;
350
+ }
351
+ /**
352
+ * Mirror of protobuf `RenderedSchematicImage`. The `imageData` field is
353
+ * protobuf `bytes` → proto3 JSON base64 string. Artifact large-image fallback
354
+ * is intentionally NOT handled yet; clients must handle empty `imageData`
355
+ * gracefully when that fallback is implemented upstream.
356
+ */
357
+ interface RenderedSchematicImage {
358
+ sheetInstancePath: string;
359
+ format: SchematicImageFormat;
360
+ width: number;
361
+ height: number;
362
+ /** protobuf `bytes image_data` → proto3 JSON base64 string. */
363
+ imageData: string;
364
+ contentHash?: string;
365
+ }
366
+ /** Mirror of protobuf `RenderSchematicResponse`. */
367
+ interface RenderSchematicResult {
368
+ documentId: string;
369
+ documentRevision: string;
370
+ images: RenderedSchematicImage[];
371
+ }
286
372
  //#endregion
287
373
  //#region src/client.d.ts
288
374
  /** Per-call options. `signal` lets DSH cancel a request (see §6 of the task). */
@@ -323,6 +409,25 @@ interface EdaHostClient {
323
409
  * or unsupported). It performs no synchronization itself.
324
410
  */
325
411
  syncSchematicToPcb(options?: EdaHostRequestOptions): Promise<void>;
412
+ /**
413
+ * Query the connected EDA host's schematic render capabilities
414
+ * (`hq.services.v1.SchematicRenderService.GetRenderCapabilities`).
415
+ * Tells the caller whether PNG/SVG/hierarchy/region render are supported,
416
+ * along with max image dimensions.
417
+ */
418
+ getRenderCapabilities(options?: EdaHostRequestOptions): Promise<RenderCapabilities>;
419
+ /**
420
+ * List schematic sheets available for rendering
421
+ * (`hq.services.v1.SchematicRenderService.ListSchematicSheets`).
422
+ */
423
+ listSchematicSheets(document?: RenderSchematicParams['document'], options?: EdaHostRequestOptions): Promise<ListSchematicSheetsResult>;
424
+ /**
425
+ * Render one or more schematic sheets to PNG images
426
+ * (`hq.services.v1.SchematicRenderService.RenderSchematic`).
427
+ * Returns proto3 JSON where each image's `imageData` field is base64-encoded
428
+ * bytes from the upstream protobuf response.
429
+ */
430
+ renderSchematic(params: RenderSchematicParams, options?: EdaHostRequestOptions): Promise<RenderSchematicResult>;
326
431
  }
327
432
  /**
328
433
  * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
@@ -397,4 +502,4 @@ declare module '@deepseek-ai/cordis' {
397
502
  */
398
503
  declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
399
504
  //#endregion
400
- 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 PcbShape, type PcbSnapshot, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };
505
+ export { type EdaHostCapability, type EdaHostClient, type EdaHostConfig, type EdaHostExecutable, type EdaHostIdentity, type EdaHostInfo, type EdaHostInstallation, type EdaHostRequestOptions, type EdaHostType, type ElectricalNet, type ElectricalType, type ListSchematicSheetsResult, NetlistError, type NetlistErrorKind, type PcbArc, type PcbDimension, type PcbFootprint, type PcbGroup, type PcbNetRef, type PcbPad, type PcbPoint, type PcbSegment, type PcbShape, type PcbSnapshot, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type RenderCapabilities, type RenderSchematicParams, type RenderSchematicResult, type RenderedSchematicImage, type SchematicComponent, type SchematicDocumentRef, type SchematicImageFormat, type SchematicNetlist, type SchematicSheetInstance, type SchematicSource, apply, inject, name, parseNetlistBody };
package/lib/index.mjs CHANGED
@@ -13,6 +13,7 @@ function resolveEdaHostConfig(config, env = process.env) {
13
13
  const pcbBoardPrefix = config?.pcbBoardPathPrefix ?? env.HQ_EDGE_PCB_BOARD_PATH ?? "/api/v1/pcb-board";
14
14
  const hostPrefix = config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? "/api/v1/host";
15
15
  const syncSchematicToPcbPrefix = config?.syncSchematicToPcbPathPrefix ?? env.HQ_EDGE_SYNC_SCHEMATIC_TO_PCB_PATH ?? "/api/v1/sync-schematic-to-pcb";
16
+ const schematicRenderPrefix = config?.schematicRenderPathPrefix ?? env.HQ_EDGE_SCHEMATIC_RENDER_PATH ?? "/api/v1/schematic-render";
16
17
  const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS;
17
18
  const timeout = Number.parseInt(String(timeoutRaw ?? ""), 10);
18
19
  return {
@@ -22,6 +23,7 @@ function resolveEdaHostConfig(config, env = process.env) {
22
23
  pcbBoardPathPrefix: pcbBoardPrefix,
23
24
  hostPathPrefix: hostPrefix,
24
25
  syncSchematicToPcbPathPrefix: syncSchematicToPcbPrefix,
26
+ schematicRenderPathPrefix: schematicRenderPrefix,
25
27
  requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
26
28
  };
27
29
  }
@@ -53,6 +55,15 @@ function hostUrlOf(config, route) {
53
55
  function syncSchematicToPcbUrlOf(config) {
54
56
  return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.syncSchematicToPcbPathPrefix ?? "/api/v1/sync-schematic-to-pcb").replace(/^\/+|\/+$/g, "")}`;
55
57
  }
58
+ const SCHEMATIC_RENDER_ROUTE = {
59
+ capabilities: "/capabilities",
60
+ sheets: "/sheets",
61
+ render: "/render"
62
+ };
63
+ /** Build the absolute URL for one schematic render sub-route. */
64
+ function schematicRenderUrlOf(config, route) {
65
+ return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.schematicRenderPathPrefix ?? "/api/v1/schematic-render").replace(/^\/+|\/+$/g, "")}${SCHEMATIC_RENDER_ROUTE[route]}`;
66
+ }
56
67
  //#endregion
57
68
  //#region src/types.ts
58
69
  var NetlistError = class extends Error {
@@ -227,6 +238,34 @@ function createEdaHostClient(config, deps = {}) {
227
238
  throw new NetlistError(statusToKind(response.status), `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ""})`);
228
239
  }
229
240
  }
241
+ /** Perform one POST with a JSON body and return the parsed JSON response. */
242
+ async function postJson(url, body, options, what) {
243
+ const signal = resolveSignal(config.requestTimeoutMs ?? 3e4, options?.signal);
244
+ let response;
245
+ try {
246
+ response = await fetchImpl(url, {
247
+ method: "POST",
248
+ headers: {
249
+ "content-type": "application/json",
250
+ Accept: "application/json"
251
+ },
252
+ body: JSON.stringify(body ?? {}),
253
+ ...signal ? { signal } : {}
254
+ });
255
+ } catch (err) {
256
+ if (isAbortError(err)) throw new NetlistError("DEADLINE_EXCEEDED", `eda-host: ${what} request exceeded its time budget at ${url}`);
257
+ throw new NetlistError("UNAVAILABLE", `eda-host: cannot reach hq-edge at ${url}: ${String(err?.message ?? err)}`);
258
+ }
259
+ if (!response.ok) {
260
+ let detail = "";
261
+ try {
262
+ const body = await response.json();
263
+ if (typeof body.detail === "string") detail = body.detail;
264
+ } catch {}
265
+ throw new NetlistError(statusToKind(response.status), `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ""})`);
266
+ }
267
+ return response.json();
268
+ }
230
269
  async function fetchScope(scope, options) {
231
270
  return parseNetlistBody(await getJson(netlistUrlOf(resolveConfig(), scope), options, "netlist"));
232
271
  }
@@ -269,6 +308,67 @@ function createEdaHostClient(config, deps = {}) {
269
308
  },
270
309
  syncSchematicToPcb: async (options) => {
271
310
  await postSync(syncSchematicToPcbUrlOf(resolveConfig()), options, "schematic-to-pcb sync");
311
+ },
312
+ getRenderCapabilities: async (options) => {
313
+ const body = await getJson(schematicRenderUrlOf(resolveConfig(), "capabilities"), options, "render capabilities");
314
+ if (!body || typeof body !== "object") throw new NetlistError("INTERNAL", "eda-host: malformed render capabilities response from hq-edge");
315
+ const pickBool = (k) => typeof body[k] === "boolean" ? body[k] : false;
316
+ const pickUint = (k) => {
317
+ const v = body[k];
318
+ return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0;
319
+ };
320
+ return {
321
+ supportsActiveDocument: pickBool("supportsActiveDocument"),
322
+ supportsDocumentId: pickBool("supportsDocumentId"),
323
+ supportsHierarchy: pickBool("supportsHierarchy"),
324
+ supportsSheetInstance: pickBool("supportsSheetInstance"),
325
+ supportsPng: pickBool("supportsPng"),
326
+ supportsSvg: pickBool("supportsSvg"),
327
+ supportsRegionRender: pickBool("supportsRegionRender"),
328
+ maxWidth: pickUint("maxWidth"),
329
+ maxHeight: pickUint("maxHeight")
330
+ };
331
+ },
332
+ listSchematicSheets: async (document, options) => {
333
+ const baseUrl = schematicRenderUrlOf(resolveConfig(), "sheets");
334
+ const params = new URLSearchParams();
335
+ if (document?.source) params.set("source", document.source);
336
+ if (document?.documentId) params.set("document_id", document.documentId);
337
+ const body = await getJson(params.size > 0 ? `${baseUrl}?${params.toString()}` : baseUrl, options, "schematic sheets");
338
+ if (!body || typeof body !== "object") throw new NetlistError("INTERNAL", "eda-host: malformed schematic sheets response from hq-edge");
339
+ const sheets = (Array.isArray(body.sheets) ? body.sheets : []).filter((s) => Boolean(s) && typeof s === "object").map((s) => ({
340
+ instancePath: str(s.instancePath),
341
+ sheetName: str(s.sheetName),
342
+ sourcePath: str(s.sourcePath),
343
+ sheetUuid: str(s.sheetUuid)
344
+ }));
345
+ return {
346
+ documentId: str(body.documentId),
347
+ documentRevision: str(body.documentRevision),
348
+ sheets
349
+ };
350
+ },
351
+ renderSchematic: async (params, options) => {
352
+ const url = schematicRenderUrlOf(resolveConfig(), "render");
353
+ const requestBody = {};
354
+ if (params.document) requestBody.document = params.document;
355
+ if (params.sheetInstancePaths && params.sheetInstancePaths.length > 0) requestBody.sheetInstancePaths = params.sheetInstancePaths;
356
+ if (typeof params.activeDocument === "boolean") requestBody.activeDocument = params.activeDocument;
357
+ const body = await postJson(url, requestBody, options, "schematic render");
358
+ if (!body || typeof body !== "object") throw new NetlistError("INTERNAL", "eda-host: malformed schematic render response from hq-edge");
359
+ const images = (Array.isArray(body.images) ? body.images : []).filter((img) => Boolean(img) && typeof img === "object").map((img) => ({
360
+ sheetInstancePath: str(img.sheetInstancePath),
361
+ format: typeof img.format === "string" ? img.format : "SCHEMATIC_IMAGE_FORMAT_UNSPECIFIED",
362
+ width: typeof img.width === "number" ? img.width : 0,
363
+ height: typeof img.height === "number" ? img.height : 0,
364
+ imageData: str(img.imageData),
365
+ contentHash: typeof img.contentHash === "string" ? img.contentHash : void 0
366
+ }));
367
+ return {
368
+ documentId: str(body.documentId),
369
+ documentRevision: str(body.documentRevision),
370
+ images
371
+ };
272
372
  }
273
373
  };
274
374
  }
@@ -486,6 +586,104 @@ function createEdaHostTools(env) {
486
586
  });
487
587
  }
488
588
  }
589
+ }),
590
+ defineTool({
591
+ name: "get_schematic_render_capabilities",
592
+ description: "Query the connected EDA host's schematic render capabilities through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Uses the hq.services.v1.SchematicRenderService.GetRenderCapabilities RPC. Returns { ok, capabilities } where capabilities reports supportsPng, supportsHierarchy, supportsSheetInstance, supportsRegionRender, maxWidth, maxHeight and related flags. Only PNG is currently supported; other format flags (SVG etc.) are reserved for future use. Call this FIRST before using get_schematic_png_screenshot — a host that does not advertise supportsPng=true will fail the render call. " + ERROR_SEMANTICS,
593
+ parameters: {},
594
+ output: {
595
+ schema: { type: "json" },
596
+ render: renderJson
597
+ },
598
+ async execute(_args, exec) {
599
+ try {
600
+ const options = exec?.signal ? { signal: exec.signal } : {};
601
+ return asJson({
602
+ ok: true,
603
+ capabilities: await env.client.getRenderCapabilities(options)
604
+ });
605
+ } catch (err) {
606
+ return asJson({
607
+ ok: false,
608
+ error: failureOf(err)
609
+ });
610
+ }
611
+ }
612
+ }),
613
+ defineTool({
614
+ name: "list_schematic_sheets",
615
+ description: "List the schematic sheets available for PNG rendering on the current project, through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Uses the hq.services.v1.SchematicRenderService.ListSchematicSheets RPC. Returns { ok, sheets: { documentId, documentRevision, sheets[] } } where each sheet has instancePath, sheetName, sourcePath and sheetUuid. Call this before get_schematic_png_screenshot when you need to render a specific sheet rather than the currently-active one. " + ERROR_SEMANTICS,
616
+ parameters: {
617
+ source: {
618
+ type: "string",
619
+ description: "Schematic source selector. \"SCHEMATIC_SOURCE_ACTIVE_DOCUMENT\" (default) uses the currently-open schematic; \"SCHEMATIC_SOURCE_DOCUMENT_ID\" requires document_id."
620
+ },
621
+ document_id: {
622
+ type: "string",
623
+ description: "Required when source is SCHEMATIC_SOURCE_DOCUMENT_ID."
624
+ }
625
+ },
626
+ output: {
627
+ schema: { type: "json" },
628
+ render: renderJson
629
+ },
630
+ async execute(args, exec) {
631
+ try {
632
+ const a = args;
633
+ const options = exec?.signal ? { signal: exec.signal } : {};
634
+ const document = a.source && a.source !== "SCHEMATIC_SOURCE_UNSPECIFIED" ? {
635
+ source: a.source,
636
+ documentId: a.document_id
637
+ } : void 0;
638
+ return asJson({
639
+ ok: true,
640
+ sheets: await env.client.listSchematicSheets(document, options)
641
+ });
642
+ } catch (err) {
643
+ return asJson({
644
+ ok: false,
645
+ error: failureOf(err)
646
+ });
647
+ }
648
+ }
649
+ }),
650
+ defineTool({
651
+ name: "get_schematic_png_screenshot",
652
+ description: "Render schematic sheets to PNG images through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). This invokes the host's NATIVE schematic render path — NOT reimplemented in TypeScript. Uses the hq.services.v1.SchematicRenderService.RenderSchematic RPC. Returns { ok, render: { documentId, documentRevision, images[] } } where each image carries base64-encoded PNG data in imageData, plus width/height in pixels and sheetInstancePath. DEFAULT BEHAVIOUR: active_document=true renders only the currently active view as PNG. Set active_document=false to render all sheets, optionally narrowed by sheet_instance_paths. Call get_schematic_render_capabilities first to confirm supportsPng=true; a host that does not support PNG will return ok:false with kind UNIMPLEMENTED. " + ERROR_SEMANTICS,
653
+ parameters: {
654
+ active_document: {
655
+ type: "boolean",
656
+ description: "When true (default): render only the currently-active view. When false: render all sheets."
657
+ },
658
+ sheet_instance_paths: {
659
+ type: "array",
660
+ items: { type: "string" },
661
+ description: "Sheet instance paths to render. Empty (default) = all sheets when active_document=false; ignored when active_document=true. Use list_schematic_sheets to discover valid paths.",
662
+ default: []
663
+ }
664
+ },
665
+ output: {
666
+ schema: { type: "json" },
667
+ render: renderJson
668
+ },
669
+ async execute(args, exec) {
670
+ try {
671
+ const a = args;
672
+ const options = exec?.signal ? { signal: exec.signal } : {};
673
+ return asJson({
674
+ ok: true,
675
+ render: await env.client.renderSchematic({
676
+ activeDocument: a.active_document ?? true,
677
+ sheetInstancePaths: a.sheet_instance_paths ?? []
678
+ }, options)
679
+ });
680
+ } catch (err) {
681
+ return asJson({
682
+ ok: false,
683
+ error: failureOf(err)
684
+ });
685
+ }
686
+ }
489
687
  })
490
688
  ];
491
689
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@huaqiu/dsh-eda-host",
3
- "version": "0.6.24",
3
+ "version": "0.6.27",
4
4
  "type": "module",
5
5
  "main": "./lib/index.mjs",
6
6
  "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
22
22
  "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
23
23
  },
24
24
  "dependencies": {
25
- "@huaqiu/dsh-plugin-log": "0.6.24"
25
+ "@huaqiu/dsh-plugin-log": "0.6.27"
26
26
  },
27
27
  "files": [
28
28
  "lib",
package/src/client.ts CHANGED
@@ -10,12 +10,16 @@
10
10
  * @module
11
11
  */
12
12
 
13
- import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbBoardUrlOf, pcbSelectionUrlOf, syncSchematicToPcbUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
13
+ import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbBoardUrlOf, pcbSelectionUrlOf, schematicRenderUrlOf, syncSchematicToPcbUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
14
14
  import {
15
15
  NetlistError,
16
16
  type EdaHostCapability,
17
17
  type EdaHostInfo,
18
+ type ListSchematicSheetsResult,
18
19
  type PcbSnapshot,
20
+ type RenderCapabilities,
21
+ type RenderSchematicParams,
22
+ type RenderSchematicResult,
19
23
  type SchematicNetlist,
20
24
  } from './types.js'
21
25
 
@@ -72,6 +76,31 @@ export interface EdaHostClient {
72
76
  * or unsupported). It performs no synchronization itself.
73
77
  */
74
78
  syncSchematicToPcb(options?: EdaHostRequestOptions): Promise<void>
79
+ /**
80
+ * Query the connected EDA host's schematic render capabilities
81
+ * (`hq.services.v1.SchematicRenderService.GetRenderCapabilities`).
82
+ * Tells the caller whether PNG/SVG/hierarchy/region render are supported,
83
+ * along with max image dimensions.
84
+ */
85
+ getRenderCapabilities(options?: EdaHostRequestOptions): Promise<RenderCapabilities>
86
+ /**
87
+ * List schematic sheets available for rendering
88
+ * (`hq.services.v1.SchematicRenderService.ListSchematicSheets`).
89
+ */
90
+ listSchematicSheets(
91
+ document?: RenderSchematicParams['document'],
92
+ options?: EdaHostRequestOptions,
93
+ ): Promise<ListSchematicSheetsResult>
94
+ /**
95
+ * Render one or more schematic sheets to PNG images
96
+ * (`hq.services.v1.SchematicRenderService.RenderSchematic`).
97
+ * Returns proto3 JSON where each image's `imageData` field is base64-encoded
98
+ * bytes from the upstream protobuf response.
99
+ */
100
+ renderSchematic(
101
+ params: RenderSchematicParams,
102
+ options?: EdaHostRequestOptions,
103
+ ): Promise<RenderSchematicResult>
75
104
  }
76
105
 
77
106
  /** HTTP status → semantic error kind (see routes/edaHostStatus.ts on hq-edge). */
@@ -318,6 +347,53 @@ export function createEdaHostClient(
318
347
  }
319
348
  }
320
349
 
350
+ /** Perform one POST with a JSON body and return the parsed JSON response. */
351
+ async function postJson(
352
+ url: string,
353
+ body: unknown,
354
+ options: EdaHostRequestOptions | undefined,
355
+ what: string,
356
+ ): Promise<unknown> {
357
+ const signal = resolveSignal(config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, options?.signal)
358
+
359
+ let response: Response
360
+ try {
361
+ response = await fetchImpl(url, {
362
+ method: 'POST',
363
+ headers: { 'content-type': 'application/json', Accept: 'application/json' },
364
+ body: JSON.stringify(body ?? {}),
365
+ ...(signal ? { signal } : {}),
366
+ })
367
+ } catch (err) {
368
+ if (isAbortError(err)) {
369
+ throw new NetlistError(
370
+ 'DEADLINE_EXCEEDED',
371
+ `eda-host: ${what} request exceeded its time budget at ${url}`,
372
+ )
373
+ }
374
+ throw new NetlistError(
375
+ 'UNAVAILABLE',
376
+ `eda-host: cannot reach hq-edge at ${url}: ${String((err as Error)?.message ?? err)}`,
377
+ )
378
+ }
379
+
380
+ if (!response.ok) {
381
+ let detail = ''
382
+ try {
383
+ const body = (await response.json()) as { detail?: unknown }
384
+ if (typeof body.detail === 'string') detail = body.detail
385
+ } catch {
386
+ // non-JSON error body — fall through with empty detail
387
+ }
388
+ throw new NetlistError(
389
+ statusToKind(response.status),
390
+ `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ''})`,
391
+ )
392
+ }
393
+
394
+ return response.json()
395
+ }
396
+
321
397
  async function fetchScope(
322
398
  scope: NetlistScope,
323
399
  options?: EdaHostRequestOptions,
@@ -406,5 +482,124 @@ export function createEdaHostClient(
406
482
  const url = syncSchematicToPcbUrlOf(resolved)
407
483
  await postSync(url, options, 'schematic-to-pcb sync')
408
484
  },
485
+
486
+ getRenderCapabilities: async (options) => {
487
+ const resolved = resolveConfig()
488
+ const url = schematicRenderUrlOf(resolved, 'capabilities')
489
+ const body = (await getJson(url, options, 'render capabilities')) as Record<string, unknown>
490
+
491
+ if (!body || typeof body !== 'object') {
492
+ throw new NetlistError('INTERNAL', 'eda-host: malformed render capabilities response from hq-edge')
493
+ }
494
+
495
+ const pickBool = (k: string): boolean =>
496
+ typeof (body as Record<string, unknown>)[k] === 'boolean'
497
+ ? ((body as Record<string, unknown>)[k] as boolean)
498
+ : false
499
+ const pickUint = (k: string): number => {
500
+ const v = (body as Record<string, unknown>)[k]
501
+ return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0
502
+ }
503
+
504
+ return {
505
+ supportsActiveDocument: pickBool('supportsActiveDocument'),
506
+ supportsDocumentId: pickBool('supportsDocumentId'),
507
+ supportsHierarchy: pickBool('supportsHierarchy'),
508
+ supportsSheetInstance: pickBool('supportsSheetInstance'),
509
+ supportsPng: pickBool('supportsPng'),
510
+ supportsSvg: pickBool('supportsSvg'),
511
+ supportsRegionRender: pickBool('supportsRegionRender'),
512
+ maxWidth: pickUint('maxWidth'),
513
+ maxHeight: pickUint('maxHeight'),
514
+ } satisfies RenderCapabilities
515
+ },
516
+
517
+ listSchematicSheets: async (document, options) => {
518
+ const resolved = resolveConfig()
519
+ const baseUrl = schematicRenderUrlOf(resolved, 'sheets')
520
+
521
+ const params = new URLSearchParams()
522
+ if (document?.source) params.set('source', document.source)
523
+ if (document?.documentId) params.set('document_id', document.documentId)
524
+ const url = params.size > 0 ? `${baseUrl}?${params.toString()}` : baseUrl
525
+
526
+ const body = (await getJson(url, options, 'schematic sheets')) as Record<string, unknown>
527
+
528
+ if (!body || typeof body !== 'object') {
529
+ throw new NetlistError('INTERNAL', 'eda-host: malformed schematic sheets response from hq-edge')
530
+ }
531
+
532
+ const rawSheets = Array.isArray((body as Record<string, unknown>).sheets)
533
+ ? ((body as Record<string, unknown>).sheets as unknown[])
534
+ : []
535
+
536
+ const sheets = rawSheets
537
+ .filter((s): s is Record<string, unknown> => Boolean(s) && typeof s === 'object')
538
+ .map((s) => ({
539
+ instancePath: str(s.instancePath as unknown),
540
+ sheetName: str(s.sheetName as unknown),
541
+ sourcePath: str(s.sourcePath as unknown),
542
+ sheetUuid: str(s.sheetUuid as unknown),
543
+ }))
544
+
545
+ return {
546
+ documentId: str((body as Record<string, unknown>).documentId as unknown),
547
+ documentRevision: str((body as Record<string, unknown>).documentRevision as unknown),
548
+ sheets,
549
+ } satisfies ListSchematicSheetsResult
550
+ },
551
+
552
+ renderSchematic: async (params, options) => {
553
+ const resolved = resolveConfig()
554
+ const url = schematicRenderUrlOf(resolved, 'render')
555
+
556
+ // Proto3 JSON omits defaults — we only send fields that have a real value.
557
+ const requestBody: Record<string, unknown> = {}
558
+ if (params.document) requestBody.document = params.document
559
+ if (params.sheetInstancePaths && params.sheetInstancePaths.length > 0) {
560
+ requestBody.sheetInstancePaths = params.sheetInstancePaths
561
+ }
562
+ // if (typeof params.maxWidth === 'number') requestBody.maxWidth = params.maxWidth
563
+ // if (typeof params.maxHeight === 'number') requestBody.maxHeight = params.maxHeight
564
+ // if (typeof params.scale === 'number') requestBody.scale = params.scale
565
+ // if (typeof params.transparentBackground === 'boolean') {
566
+ // requestBody.transparentBackground = params.transparentBackground
567
+ // }
568
+ // if (params.expectedRevision) requestBody.expectedRevision = params.expectedRevision
569
+ if (typeof params.activeDocument === 'boolean') {
570
+ requestBody.activeDocument = params.activeDocument
571
+ }
572
+
573
+ const body = (await postJson(url, requestBody, options, 'schematic render')) as Record<string, unknown>
574
+
575
+ if (!body || typeof body !== 'object') {
576
+ throw new NetlistError('INTERNAL', 'eda-host: malformed schematic render response from hq-edge')
577
+ }
578
+
579
+ const rawImages = Array.isArray((body as Record<string, unknown>).images)
580
+ ? ((body as Record<string, unknown>).images as unknown[])
581
+ : []
582
+
583
+ const images = rawImages
584
+ .filter((img): img is Record<string, unknown> => Boolean(img) && typeof img === 'object')
585
+ .map((img) => ({
586
+ sheetInstancePath: str(img.sheetInstancePath as unknown),
587
+ format: (typeof img.format === 'string'
588
+ ? img.format
589
+ : 'SCHEMATIC_IMAGE_FORMAT_UNSPECIFIED') as RenderSchematicResult['images'][number]['format'],
590
+ width: typeof img.width === 'number' ? img.width : 0,
591
+ height: typeof img.height === 'number' ? img.height : 0,
592
+ // proto3 JSON: bytes image_data → base64 string
593
+ imageData: str(img.imageData as unknown),
594
+ contentHash:
595
+ typeof img.contentHash === 'string' ? img.contentHash : undefined,
596
+ }))
597
+
598
+ return {
599
+ documentId: str((body as Record<string, unknown>).documentId as unknown),
600
+ documentRevision: str((body as Record<string, unknown>).documentRevision as unknown),
601
+ images,
602
+ } satisfies RenderSchematicResult
603
+ },
409
604
  }
410
605
  }
package/src/config.ts CHANGED
@@ -28,6 +28,11 @@ export interface EdaHostConfig {
28
28
  * hq-edge forwards it to the EDA host's native handler.
29
29
  */
30
30
  syncSchematicToPcbPathPrefix?: string
31
+ /**
32
+ * Path prefix for schematic render (PNG/SVG export); default
33
+ * "/api/v1/schematic-render". Covers capabilities, sheet listing, and render.
34
+ */
35
+ schematicRenderPathPrefix?: string
31
36
  /**
32
37
  * End-to-end budget for one EDA-host request, in milliseconds.
33
38
  *
@@ -49,6 +54,8 @@ export const DEFAULT_HOST_PATH_PREFIX = '/api/v1/host'
49
54
 
50
55
  export const DEFAULT_SYNC_SCHEMATIC_TO_PCB_PATH_PREFIX = '/api/v1/sync-schematic-to-pcb'
51
56
 
57
+ export const DEFAULT_SCHEMATIC_RENDER_PATH_PREFIX = '/api/v1/schematic-render'
58
+
52
59
  export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
53
60
 
54
61
  /** Scope → route suffix on the host netlist router. */
@@ -81,6 +88,10 @@ export function resolveEdaHostConfig(
81
88
  config?.syncSchematicToPcbPathPrefix ??
82
89
  env.HQ_EDGE_SYNC_SCHEMATIC_TO_PCB_PATH ??
83
90
  DEFAULT_SYNC_SCHEMATIC_TO_PCB_PATH_PREFIX
91
+ const schematicRenderPrefix =
92
+ config?.schematicRenderPathPrefix ??
93
+ env.HQ_EDGE_SCHEMATIC_RENDER_PATH ??
94
+ DEFAULT_SCHEMATIC_RENDER_PATH_PREFIX
84
95
  const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS
85
96
  const timeout = Number.parseInt(String(timeoutRaw ?? ''), 10)
86
97
  return {
@@ -90,6 +101,7 @@ export function resolveEdaHostConfig(
90
101
  pcbBoardPathPrefix: pcbBoardPrefix,
91
102
  hostPathPrefix: hostPrefix,
92
103
  syncSchematicToPcbPathPrefix: syncSchematicToPcbPrefix,
104
+ schematicRenderPathPrefix: schematicRenderPrefix,
93
105
  requestTimeoutMs:
94
106
  Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
95
107
  }
@@ -151,3 +163,25 @@ export function syncSchematicToPcbUrlOf(config: EdaHostConfig): string {
151
163
  )
152
164
  return `${base}/${prefix}`
153
165
  }
166
+
167
+ /** Schematic render sub-route suffix. */
168
+ export type SchematicRenderRoute = 'capabilities' | 'sheets' | 'render'
169
+
170
+ const SCHEMATIC_RENDER_ROUTE: Record<SchematicRenderRoute, string> = {
171
+ capabilities: '/capabilities',
172
+ sheets: '/sheets',
173
+ render: '/render',
174
+ }
175
+
176
+ /** Build the absolute URL for one schematic render sub-route. */
177
+ export function schematicRenderUrlOf(
178
+ config: EdaHostConfig,
179
+ route: SchematicRenderRoute,
180
+ ): string {
181
+ const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
182
+ const prefix = (config.schematicRenderPathPrefix ?? DEFAULT_SCHEMATIC_RENDER_PATH_PREFIX).replace(
183
+ /^\/+|\/+$/g,
184
+ '',
185
+ )
186
+ return `${base}/${prefix}${SCHEMATIC_RENDER_ROUTE[route]}`
187
+ }
package/src/index.ts CHANGED
@@ -2,16 +2,19 @@
2
2
  * `@huaqiu/dsh-eda-host` — node plugin entry.
3
3
  *
4
4
  * Provides the `edaHost` service (semantic EDA-host capability) and registers
5
- * eight agent tools:
5
+ * eleven agent tools:
6
6
  *
7
- * get_project_netlist complete project netlist
8
- * get_selection_netlist currently selected components netlist
9
- * get_active_page_netlist active schematic page netlist
10
- * get_pcb_selection semantic PCB selection of the current PCB editor
11
- * get_pcb_board complete semantic PCB board snapshot
12
- * get_eda_host_info which EDA host, version, installation
13
- * get_eda_host_capabilities what the current host can actually do
14
- * sync_schematic_to_pcb ask the host to synchronize schematic → PCB
7
+ * get_project_netlist complete project netlist
8
+ * get_selection_netlist currently selected components netlist
9
+ * get_active_page_netlist active schematic page netlist
10
+ * get_pcb_selection semantic PCB selection of the current PCB editor
11
+ * get_pcb_board complete semantic PCB board snapshot
12
+ * get_eda_host_info which EDA host, version, installation
13
+ * get_eda_host_capabilities what the current host can actually do
14
+ * sync_schematic_to_pcb ask the host to synchronize schematic → PCB
15
+ * get_schematic_render_capabilities whether PNG render is supported plus dimensions
16
+ * list_schematic_sheets list all schematic sheets available for rendering
17
+ * get_schematic_png_screenshot render schematic sheet(s) to PNG images (base64)
15
18
  *
16
19
  * ── Architectural boundary (task: add-dsh-eda-host) ─────────────────────────
17
20
  * The ONLY production request path is DSH → dsh-eda-host → hq-edge → EDA host.
@@ -65,6 +68,7 @@ export type {
65
68
  EdaHostType,
66
69
  ElectricalNet,
67
70
  ElectricalType,
71
+ ListSchematicSheetsResult,
68
72
  NetlistErrorKind,
69
73
  PcbArc,
70
74
  PcbDimension,
@@ -82,8 +86,16 @@ export type {
82
86
  PcbZone,
83
87
  PinDefinition,
84
88
  PinReference,
89
+ RenderCapabilities,
90
+ RenderSchematicParams,
91
+ RenderSchematicResult,
92
+ RenderedSchematicImage,
85
93
  SchematicComponent,
94
+ SchematicDocumentRef,
95
+ SchematicImageFormat,
86
96
  SchematicNetlist,
97
+ SchematicSheetInstance,
98
+ SchematicSource,
87
99
  } from './types.js'
88
100
  export { NetlistError } from './types.js'
89
101
  export { parseNetlistBody } from './client.js'
package/src/tools.ts CHANGED
@@ -28,7 +28,7 @@
28
28
 
29
29
  import { defineTool } from '@deepseek-ai/dsh-tools'
30
30
  import type { EdaHostClient, EdaHostRequestOptions } from './client.js'
31
- import { NetlistError, type EdaHostCapability, type EdaHostInfo, type PcbSnapshot, type SchematicNetlist } from './types.js'
31
+ import { NetlistError, type EdaHostCapability, type EdaHostInfo, type ListSchematicSheetsResult, type PcbSnapshot, type RenderCapabilities, type RenderSchematicResult, type SchematicNetlist, type SchematicSource } from './types.js'
32
32
 
33
33
  /** Structural alias of the DSH `JsonValue`. */
34
34
  type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
@@ -78,6 +78,18 @@ type SyncSchematicToPcbResult =
78
78
  | { ok: true }
79
79
  | { ok: false; error: { kind: string; message: string } }
80
80
 
81
+ type RenderCapabilitiesResult =
82
+ | { ok: true; capabilities: RenderCapabilities }
83
+ | { ok: false; error: { kind: string; message: string } }
84
+
85
+ type ListSchematicSheetsResultEnvelope =
86
+ | { ok: true; sheets: ListSchematicSheetsResult }
87
+ | { ok: false; error: { kind: string; message: string } }
88
+
89
+ type SchematicRenderResultEnvelope =
90
+ | { ok: true; render: RenderSchematicResult }
91
+ | { ok: false; error: { kind: string; message: string } }
92
+
81
93
  /**
82
94
  * Every failure kind, and what the agent should do about it.
83
95
  *
@@ -328,5 +340,140 @@ export function createNetListTools(env: NetlistToolEnv) {
328
340
  }
329
341
  },
330
342
  }),
343
+
344
+ // ── Schematic Render (PNG export) ────────────────────────────────────
345
+
346
+ defineTool({
347
+ name: 'get_schematic_render_capabilities',
348
+ description:
349
+ `Query the connected EDA host's schematic render capabilities through ` +
350
+ `hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). ` +
351
+ `Uses the hq.services.v1.SchematicRenderService.GetRenderCapabilities ` +
352
+ `RPC. ` +
353
+ `Returns { ok, capabilities } where capabilities reports supportsPng, ` +
354
+ `supportsHierarchy, supportsSheetInstance, supportsRegionRender, ` +
355
+ `maxWidth, maxHeight and related flags. Only PNG is currently supported; ` +
356
+ `other format flags (SVG etc.) are reserved for future use. ` +
357
+ `Call this FIRST before using get_schematic_png_screenshot — a host ` +
358
+ `that does not advertise supportsPng=true will fail the render call. ` +
359
+ ERROR_SEMANTICS,
360
+ parameters: {},
361
+ output: { schema: { type: 'json' }, render: renderJson },
362
+ async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
363
+ try {
364
+ const options: EdaHostRequestOptions = exec?.signal
365
+ ? { signal: exec.signal }
366
+ : {}
367
+ const capabilities = await env.client.getRenderCapabilities(options)
368
+ return asJson<RenderCapabilitiesResult>({ ok: true, capabilities })
369
+ } catch (err) {
370
+ return asJson<RenderCapabilitiesResult>({ ok: false, error: failureOf(err) })
371
+ }
372
+ },
373
+ }),
374
+
375
+ defineTool({
376
+ name: 'list_schematic_sheets',
377
+ description:
378
+ `List the schematic sheets available for PNG rendering on the current ` +
379
+ `project, through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). ` +
380
+ `Uses the hq.services.v1.SchematicRenderService.ListSchematicSheets ` +
381
+ `RPC. Returns { ok, sheets: { documentId, documentRevision, sheets[] } } ` +
382
+ `where each sheet has instancePath, sheetName, sourcePath and sheetUuid. ` +
383
+ `Call this before get_schematic_png_screenshot when you need to render ` +
384
+ `a specific sheet rather than the currently-active one. ` +
385
+ ERROR_SEMANTICS,
386
+ parameters: {
387
+ source: {
388
+ type: 'string',
389
+ description:
390
+ 'Schematic source selector. "SCHEMATIC_SOURCE_ACTIVE_DOCUMENT" (default) uses the currently-open schematic; "SCHEMATIC_SOURCE_DOCUMENT_ID" requires document_id.',
391
+ },
392
+ document_id: {
393
+ type: 'string',
394
+ description: 'Required when source is SCHEMATIC_SOURCE_DOCUMENT_ID.',
395
+ },
396
+ },
397
+ output: { schema: { type: 'json' }, render: renderJson },
398
+ async execute(args: unknown, exec: ToolExecLike): Promise<Json> {
399
+ try {
400
+ const a = args as { source?: SchematicSource; document_id?: string }
401
+ const options: EdaHostRequestOptions = exec?.signal
402
+ ? { signal: exec.signal }
403
+ : {}
404
+ const document =
405
+ a.source && a.source !== 'SCHEMATIC_SOURCE_UNSPECIFIED'
406
+ ? {
407
+ source: a.source,
408
+ documentId: a.document_id,
409
+ }
410
+ : undefined
411
+ const sheets = await env.client.listSchematicSheets(document, options)
412
+ return asJson<ListSchematicSheetsResultEnvelope>({ ok: true, sheets })
413
+ } catch (err) {
414
+ return asJson<ListSchematicSheetsResultEnvelope>({
415
+ ok: false,
416
+ error: failureOf(err),
417
+ })
418
+ }
419
+ },
420
+ }),
421
+
422
+ defineTool({
423
+ name: 'get_schematic_png_screenshot',
424
+ description:
425
+ `Render schematic sheets to PNG images through hq-edge ` +
426
+ `(DSH → dsh-eda-host → hq-edge → EDA host). This invokes the host's ` +
427
+ `NATIVE schematic render path — NOT reimplemented in TypeScript. ` +
428
+ `Uses the hq.services.v1.SchematicRenderService.RenderSchematic RPC. ` +
429
+ `Returns { ok, render: { documentId, documentRevision, images[] } } ` +
430
+ `where each image carries base64-encoded PNG data in imageData, plus ` +
431
+ `width/height in pixels and sheetInstancePath. ` +
432
+ `DEFAULT BEHAVIOUR: active_document=true renders only the currently ` +
433
+ `active view as PNG. Set active_document=false to render all sheets, ` +
434
+ `optionally narrowed by sheet_instance_paths. ` +
435
+ `Call get_schematic_render_capabilities first to confirm supportsPng=true; ` +
436
+ `a host that does not support PNG will return ok:false with kind UNIMPLEMENTED. ` +
437
+ ERROR_SEMANTICS,
438
+ parameters: {
439
+ active_document: {
440
+ type: 'boolean',
441
+ description:
442
+ 'When true (default): render only the currently-active view. When false: render all sheets.',
443
+ },
444
+ sheet_instance_paths: {
445
+ type: 'array',
446
+ items: { type: 'string' },
447
+ description:
448
+ 'Sheet instance paths to render. Empty (default) = all sheets when active_document=false; ignored when active_document=true. Use list_schematic_sheets to discover valid paths.',
449
+ default: [],
450
+ },
451
+ },
452
+ output: { schema: { type: 'json' }, render: renderJson },
453
+ async execute(args: unknown, exec: ToolExecLike): Promise<Json> {
454
+ try {
455
+ const a = args as {
456
+ active_document?: boolean
457
+ sheet_instance_paths?: string[]
458
+ }
459
+ const options: EdaHostRequestOptions = exec?.signal
460
+ ? { signal: exec.signal }
461
+ : {}
462
+ const render = await env.client.renderSchematic(
463
+ {
464
+ activeDocument: a.active_document ?? true,
465
+ sheetInstancePaths: a.sheet_instance_paths ?? [],
466
+ },
467
+ options,
468
+ )
469
+ return asJson<SchematicRenderResultEnvelope>({ ok: true, render })
470
+ } catch (err) {
471
+ return asJson<SchematicRenderResultEnvelope>({
472
+ ok: false,
473
+ error: failureOf(err),
474
+ })
475
+ }
476
+ },
477
+ }),
331
478
  ]
332
479
  }
package/src/types.ts CHANGED
@@ -262,6 +262,7 @@ export type EdaHostCapability =
262
262
  | 'EDA_HOST_CAPABILITY_DRC'
263
263
  | 'EDA_HOST_CAPABILITY_BOM'
264
264
  | 'EDA_HOST_CAPABILITY_PLACEMENT'
265
+ | 'EDA_HOST_CAPABILITY_SCHEMATIC_RENDER'
265
266
 
266
267
  /** A host-provided command line tool. */
267
268
  export interface EdaHostExecutable {
@@ -303,3 +304,102 @@ export interface EdaHostInfo {
303
304
  identity: EdaHostIdentity
304
305
  installation: EdaHostInstallation
305
306
  }
307
+
308
+ // ---------------------------------------------------------------------------
309
+ // Schematic render — structural mirror of `hq.services.v1.SchematicRenderService`
310
+ // ---------------------------------------------------------------------------
311
+
312
+ /** Mirror of protobuf `SchematicSource` enum. */
313
+ export type SchematicSource =
314
+ | 'SCHEMATIC_SOURCE_UNSPECIFIED'
315
+ | 'SCHEMATIC_SOURCE_ACTIVE_DOCUMENT'
316
+ | 'SCHEMATIC_SOURCE_DOCUMENT_ID'
317
+
318
+ /** Mirror of protobuf `SchematicImageFormat` enum. */
319
+ export type SchematicImageFormat =
320
+ | 'SCHEMATIC_IMAGE_FORMAT_UNSPECIFIED'
321
+ | 'SCHEMATIC_IMAGE_FORMAT_PNG'
322
+
323
+ /**
324
+ * Mirror of protobuf `SchematicDocumentRef`. Identifies which schematic
325
+ * document to render. When `source` is `ACTIVE_DOCUMENT`, `documentId` is
326
+ * ignored; when `source` is `DOCUMENT_ID`, `documentId` must be provided.
327
+ */
328
+ export interface SchematicDocumentRef {
329
+ source: SchematicSource
330
+ documentId?: string
331
+ }
332
+
333
+ /** Mirror of protobuf `GetRenderCapabilitiesResponse`. */
334
+ export interface RenderCapabilities {
335
+ supportsActiveDocument: boolean
336
+ supportsDocumentId: boolean
337
+ supportsHierarchy: boolean
338
+ supportsSheetInstance: boolean
339
+ supportsPng: boolean
340
+ supportsSvg: boolean
341
+ supportsRegionRender: boolean
342
+ maxWidth: number
343
+ maxHeight: number
344
+ }
345
+
346
+ /** Mirror of protobuf `SchematicSheetInstance`. */
347
+ export interface SchematicSheetInstance {
348
+ instancePath: string
349
+ sheetName: string
350
+ sourcePath: string
351
+ sheetUuid: string
352
+ }
353
+
354
+ /** Mirror of protobuf `ListSchematicSheetsResponse`. */
355
+ export interface ListSchematicSheetsResult {
356
+ documentId: string
357
+ documentRevision: string
358
+ sheets: SchematicSheetInstance[]
359
+ }
360
+
361
+ /**
362
+ * Input parameters for `RenderSchematicRequest`. The tool layer supplies
363
+ * defaults (PNG format, active document); all fields are optional here so
364
+ * the tool call can be minimal.
365
+ */
366
+ export interface RenderSchematicParams {
367
+ document?: SchematicDocumentRef
368
+ /** Empty means render all sheets (when `activeDocument` is false). */
369
+ sheetInstancePaths?: string[]
370
+ /** Numeric enum value (1 = PNG) or its enum-name alias. */
371
+ format?: SchematicImageFormat | number
372
+ maxWidth?: number
373
+ maxHeight?: number
374
+ scale?: number
375
+ transparentBackground?: boolean
376
+ expectedRevision?: string
377
+ /**
378
+ * `true` (default): render only the currently-active sheet in frame.
379
+ * `false`: render according to `sheetInstancePaths` (empty → all sheets).
380
+ */
381
+ activeDocument?: boolean
382
+ }
383
+
384
+ /**
385
+ * Mirror of protobuf `RenderedSchematicImage`. The `imageData` field is
386
+ * protobuf `bytes` → proto3 JSON base64 string. Artifact large-image fallback
387
+ * is intentionally NOT handled yet; clients must handle empty `imageData`
388
+ * gracefully when that fallback is implemented upstream.
389
+ */
390
+ export interface RenderedSchematicImage {
391
+ sheetInstancePath: string
392
+ format: SchematicImageFormat
393
+ width: number
394
+ height: number
395
+ /** protobuf `bytes image_data` → proto3 JSON base64 string. */
396
+ imageData: string
397
+ contentHash?: string
398
+ }
399
+
400
+ /** Mirror of protobuf `RenderSchematicResponse`. */
401
+ export interface RenderSchematicResult {
402
+ documentId: string
403
+ documentRevision: string
404
+ images: RenderedSchematicImage[]
405
+ }