@protoboardai/ext-tscircuit 0.0.0-stage → 0.2.1

package/lib/probe.cjs

@@ -0,0 +1,31 @@
+// Tool probe for `protoboard doctor` and capability operations: the tscircuit
+// libraries this provider runs in-process are installed at the exact versions
+// package.json pins, on Node 22 or newer. Prints one line; exits 1 otherwise.
+const { existsSync, readFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const KEY = ["@tscircuit/core", "@tscircuit/checks", "circuit-json-to-gerber", "circuit-json-to-gltf", "circuit-json-to-step", "circuit-to-svg", "sucrase"];
+const root = dirname(require.resolve("@protoboardai/ext-tscircuit/package.json", { paths: [process.cwd(), __dirname] }));
+const pins = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).dependencies;
+
+function installed(name) {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const f = join(dir, "node_modules", name, "package.json");
+    if (existsSync(f)) return JSON.parse(readFileSync(f, "utf8")).version;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+const problems = [];
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22) problems.push(`Node ${process.version} (needs 22 or newer)`);
+for (const name of KEY) {
+  const v = installed(name);
+  if (!v) problems.push(`${name} not installed`);
+  else if (v !== pins[name]) problems.push(`${name} ${v} (pinned ${pins[name]})`);
+}
+if (problems.length) {
+  console.error(`tscircuit libraries not usable: ${problems.join("; ")}`);
+  process.exit(1);
+}
+console.log(`tscircuit @tscircuit/core ${pins["@tscircuit/core"]}, converters pinned, Node ${process.version}`);

package/lib/runtime.ts

@@ -0,0 +1,185 @@
+/**
+ * Running tscircuit in Protoboard's own Node process, offline by
+ * construction (docs/research/tscircuit-spike.md §1, §7, §9):
+ *
+ *   - the native source (TSX) is compiled with sucrase and evaluated here;
+ *     `tsci` (which needs Bun) is never spawned
+ *   - @tscircuit/core renders it with the parts engine disabled, the cloud
+ *     autorouter off and a local autorouter preset
+ *   - `fetch` is replaced for the duration by a guard that serves absolute
+ *     local paths and file:// URLs from disk and refuses everything else, so
+ *     a build or an export cannot reach the network even by accident
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, extname, join, posix, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { transform } from "sucrase";
+
+const localRequire = createRequire(import.meta.url);
+
+/** A circuit JSON element (the tscircuit interchange format). */
+export type CircuitElement = { type: string; [key: string]: any };
+
+/** Network requests refused while the guard was installed (for reports and tests). */
+export const refusedRequests: string[] = [];
+
+/**
+ * The local file a model URL names, or undefined when it names none: a
+ * file:// URL, or an absolute path. On Windows that is `C:\\…`, `C:/…` or a
+ * UNC path as well as `/…`, and a file:// URL is `file:///C:/…` (whose URL
+ * pathname `/C:/…` is not a path there). `platform` is for tests.
+ */
+export function localFile(url: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  const windows = platform === "win32";
+  if (url.startsWith("file://")) {
+    try {
+      return fileURLToPath(url, { windows });
+    } catch {
+      return undefined;
+    }
+  }
+  return (windows ? win32 : posix).isAbsolute(url) ? url : undefined;
+}
+
+/** Local files the guard was asked for while installed: found and read, or missing. */
+export interface FileRequests {
+  read: string[];
+  missing: string[];
+}
+
+/**
+ * Run `fn` with `fetch` restricted to local files. Absolute paths and
+ * file:// URLs are read from disk; data: and blob: URLs pass through;
+ * anything else throws. `files`, when given, collects the local files asked
+ * for (so a caller can say which bodies loaded).
+ */
+export async function offline<T>(fn: () => Promise<T>, options: { files?: FileRequests; platform?: NodeJS.Platform } = {}): Promise<T> {
+  const real = globalThis.fetch;
+  globalThis.fetch = (async (input: unknown, init?: unknown) => {
+    const url = typeof input === "string" ? input : ((input as { url?: string })?.url ?? String(input));
+    const file = localFile(url, options.platform);
+    if (file) {
+      if (!existsSync(file)) {
+        options.files?.missing.push(file);
+        return new Response(null, { status: 404 });
+      }
+      options.files?.read.push(file);
+      return new Response(readFileSync(file));
+    }
+    if (url.startsWith("data:") || url.startsWith("blob:")) return real(input as Parameters<typeof fetch>[0], init as Parameters<typeof fetch>[1]);
+    refusedRequests.push(url);
+    throw new Error(`@protoboardai/ext-tscircuit works offline: refused a network request to ${url.slice(0, 120)}`);
+  }) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = real;
+  }
+}
+
+const SOURCE_EXT = [".tsx", ".ts", ".jsx", ".js"];
+
+/**
+ * Load a TSX module and its relative imports; bare imports resolve from this package (react, react/jsx-runtime).
+ * `loaded` collects the absolute path of every file read: the entry, each relative import (JSON included),
+ * wherever it lives (a hand file shared with another board's folder).
+ */
+export function loadTsx(entry: string, loaded?: Set<string>): Record<string, unknown> {
+  const cache = new Map<string, { exports: Record<string, unknown> }>();
+  const load = (file: string): Record<string, unknown> => {
+    const hit = cache.get(file);
+    if (hit) return hit.exports;
+    const mod = { exports: {} as Record<string, unknown> };
+    cache.set(file, mod);
+    loaded?.add(file);
+    if (extname(file) === ".json") {
+      mod.exports = JSON.parse(readFileSync(file, "utf8"));
+      return mod.exports;
+    }
+    const { code } = transform(readFileSync(file, "utf8"), { transforms: ["typescript", "jsx", "imports"], jsxRuntime: "automatic", production: true, filePath: file });
+    const req = (spec: string) => {
+      if (spec.startsWith(".") || spec.startsWith("/")) {
+        const base = resolve(dirname(file), spec);
+        const found = [base, ...SOURCE_EXT.map((e) => base + e), ...SOURCE_EXT.map((e) => join(base, "index" + e))].find((p) => existsSync(p) && !readdirSafe(p));
+        if (!found) throw new Error(`${file}: cannot resolve ${spec}`);
+        return load(found);
+      }
+      return localRequire(spec);
+    };
+    new Function("exports", "require", "module", "__filename", "__dirname", code)(mod.exports, req, mod, file, dirname(file));
+    return mod.exports;
+  };
+  return load(resolve(entry));
+}
+
+function readdirSafe(p: string): boolean {
+  try {
+    readdirSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface BuildResult {
+  circuitJson: CircuitElement[];
+  ms: number;
+  /** @tscircuit/core version that rendered it. */
+  coreVersion: string;
+  /** What tscircuit printed while building (router progress, solver notes). */
+  log: string[];
+  /** Every source file the build read (absolute): the entry and its relative imports, JSON included. */
+  files: string[];
+}
+
+/** Installed version of a dependency, read from its package.json (several hide it behind "exports"). */
+export function packageVersion(name: string): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const file = join(dir, "node_modules", name, "package.json");
+    if (existsSync(file)) return (JSON.parse(readFileSync(file, "utf8")) as { version: string }).version;
+    const up = dirname(dir);
+    if (up === dir) return "unknown";
+    dir = up;
+  }
+}
+
+export const coreVersion = (): string => packageVersion("@tscircuit/core");
+
+/** Run `fn` with console.log/info/warn collected instead of printed (the router is chatty); `only` keeps just the lines it accepts. */
+export async function quietly<T>(fn: () => Promise<T>, log: string[], only?: (line: string) => boolean): Promise<T> {
+  const saved = { log: console.log, info: console.info, warn: console.warn, debug: console.debug, error: console.error };
+  const keep = (...args: unknown[]) => {
+    const line = args.map(String).join(" ");
+    if (log.length < 2000 && (!only || only(line))) log.push(line);
+  };
+  Object.assign(console, { log: keep, info: keep, warn: keep, debug: keep, error: keep });
+  try {
+    return await fn();
+  } finally {
+    Object.assign(console, saved);
+  }
+}
+
+/**
+ * Render the board exported by `entry` (default export: a component taking
+ * no props) to circuit JSON with @tscircuit/core, offline.
+ */
+export async function buildCircuit(entry: string, options: { routing?: boolean } = {}): Promise<BuildResult> {
+  const t0 = performance.now();
+  const loaded = new Set<string>();
+  const mod = loadTsx(entry, loaded);
+  const Board = mod.default as (() => unknown) | undefined;
+  if (typeof Board !== "function") throw new Error(`${entry} has no default export (the board component)`);
+  const log: string[] = [];
+  const circuitJson = await quietly(() => offline(async () => {
+    const { Circuit } = (await import("@tscircuit/core")) as unknown as { Circuit: new (o: unknown) => { add(e: unknown): void; renderUntilSettled(): Promise<void>; getCircuitJson(): CircuitElement[] } };
+    const { createElement } = localRequire("react") as { createElement: (c: unknown) => unknown };
+    const circuit = new Circuit({ platform: { partsEngineDisabled: true, useCloudAutorouter: false, ...(options.routing === false ? { routingDisabled: true } : {}) } });
+    circuit.add(createElement(Board));
+    await circuit.renderUntilSettled();
+    return circuit.getCircuitJson();
+  }), log);
+  return { circuitJson, ms: Math.round(performance.now() - t0), coreVersion: coreVersion(), log, files: [...loaded].sort() };
+}

package/lib/silk.ts

@@ -0,0 +1,141 @@
+/**
+ * The silkscreen for authored land patterns: tscircuit draws silkscreen
+ * (outline and reference) only for its built-in footprint strings, so a board
+ * whose parts all have authored land patterns would go to the fab with an
+ * empty silkscreen. After each build this pass adds, for every component
+ * with an authored land pattern:
+ *
+ *   - its reference designator (R12, U3: tscircuit/refdes.json, which the
+ *     KiCad handoff keeps; the UHD instance path only for a component that
+ *     has none), 0.8 mm high (the usual fab
+ *     minimum), set beside its courtyard on the first side where it clears
+ *     every pad, hole, courtyard, the board edge and the references already
+ *     set; at 0.6 mm when none of the four sides has room; left off (and
+ *     reported) when neither size fits;
+ *   - a pin-1 mark (a Ø0.3 mm dot) beside the pin-1 pad, on the clear side
+ *     farthest from the part's centre, for parts with a pin 1 and three or
+ *     more pins.
+ *
+ * Nothing is drawn over a pad or a hole, so the fab need not clip silkscreen
+ * from the solder-mask openings.
+ */
+import type { CircuitElement } from "./runtime.ts";
+import type { NameMap } from "./source.ts";
+
+type Box = [number, number, number, number]; // x0, y0, x1, y1
+
+const r4 = (v: number) => Math.round(v * 1e4) / 1e4;
+const overlaps = (a: Box, b: Box, gap = 0) => a[0] < b[2] + gap && b[0] < a[2] + gap && a[1] < b[3] + gap && b[1] < a[3] + gap;
+
+/** Axis-aligned box of a copper or hole element (rotated pads by their corners), grown by `grow`. */
+function boxOf(e: CircuitElement, grow = 0): Box | undefined {
+  if (typeof e.x !== "number" || typeof e.y !== "number") return undefined;
+  let w = e.width ?? e.outer_width ?? e.outer_diameter ?? e.hole_diameter ?? (e.radius ?? 0) * 2;
+  let h = e.height ?? e.outer_height ?? e.outer_diameter ?? e.hole_diameter ?? (e.radius ?? 0) * 2;
+  const a = (((e.ccw_rotation as number) ?? 0) * Math.PI) / 180;
+  if (a) [w, h] = [Math.abs(w * Math.cos(a)) + Math.abs(h * Math.sin(a)), Math.abs(w * Math.sin(a)) + Math.abs(h * Math.cos(a))];
+  const m = (e.soldermask_margin ?? 0) + grow;
+  return [e.x - w / 2 - m, e.y - h / 2 - m, e.x + w / 2 + m, e.y + h / 2 + m];
+}
+
+/** Point in polygon (even-odd). */
+function inside([x, y]: [number, number], poly: { x: number; y: number }[]): boolean {
+  let c = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const [a, b] = [poly[i], poly[j]];
+    if (a.y > y !== b.y > y && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) c = !c;
+  }
+  return c;
+}
+
+export function addSilkscreen(cj: CircuitElement[], map: NameMap, designators: Record<string, string> = {}): { circuitJson: CircuitElement[]; references: number; marks: number; omitted: string[] } {
+  const board = cj.find((e) => e.type === "pcb_board");
+  const outline: { x: number; y: number }[] | undefined = board?.outline;
+  const onBoard = (b: Box, margin = 0.2) => {
+    if (!outline) return true;
+    const pts: [number, number][] = [[b[0] - margin, b[1] - margin], [b[2] + margin, b[1] - margin], [b[2] + margin, b[3] + margin], [b[0] - margin, b[3] + margin], [(b[0] + b[2]) / 2, b[1] - margin], [(b[0] + b[2]) / 2, b[3] + margin], [b[0] - margin, (b[1] + b[3]) / 2], [b[2] + margin, (b[1] + b[3]) / 2]];
+    return pts.every((p) => inside(p, outline));
+  };
+  const nameOf = new Map(cj.filter((e) => e.type === "source_component").map((s) => [s.source_component_id, s.name as string]));
+  // what silkscreen must not touch, per side: every pad and hole (mask openings) and every courtyard
+  const side = (layer: string) => (e: CircuitElement) => e.layer === layer || (Array.isArray(e.layers) && e.layers.includes(layer)) || e.type === "pcb_hole" || e.type === "pcb_plated_hole";
+  const copper = (layer: string) => cj.filter((e) => ["pcb_smtpad", "pcb_plated_hole", "pcb_hole", "pcb_via"].includes(e.type)).filter(side(layer)).map((e) => boxOf(e, 0.1)).filter(Boolean) as Box[];
+  const courtyards = (layer: string) =>
+    cj
+      .filter((e) => e.type === "pcb_courtyard_rect" && e.layer === layer)
+      .map((e) => {
+        const a = ((e.ccw_rotation ?? 0) * Math.PI) / 180;
+        const w = Math.abs(e.width * Math.cos(a)) + Math.abs(e.height * Math.sin(a));
+        const h = Math.abs(e.width * Math.sin(a)) + Math.abs(e.height * Math.cos(a));
+        return { id: e.pcb_component_id as string, box: [e.center.x - w / 2, e.center.y - h / 2, e.center.x + w / 2, e.center.y + h / 2] as Box };
+      });
+  const obstacles = { top: copper("top"), bottom: copper("bottom") };
+  const yards = { top: courtyards("top"), bottom: courtyards("bottom") };
+  const placed: Record<string, Box[]> = { top: [], bottom: [] };
+  const add: CircuitElement[] = [];
+  const omitted: string[] = [];
+  let references = 0;
+  let marks = 0;
+  let n = 0;
+
+  for (const pc of cj.filter((e) => e.type === "pcb_component")) {
+    const m = map.components[nameOf.get(pc.source_component_id) ?? ""];
+    if (!m?.paste) continue; // built-in footprint strings: tscircuit's own silkscreen
+    const layer: "top" | "bottom" = pc.layer === "bottom" ? "bottom" : "top";
+    const own = yards[layer].find((y) => y.id === pc.pcb_component_id)?.box;
+    if (!own) continue;
+
+    // the reference: beside the courtyard, on the first place that is clear (each side's middle, then its ends)
+    let set = false;
+    for (const size of [0.8, 0.6]) {
+      const w = (designators[m.instance] ?? m.instance).length * size * 0.75 + 0.15;
+      const h = size + 0.15;
+      const [cx, cy] = [(own[0] + own[2]) / 2, (own[1] + own[3]) / 2];
+      const [hw, hh] = [(own[2] - own[0]) / 2, (own[3] - own[1]) / 2];
+      const along = (half: number, len: number) => [0, -(half - len / 2), half - len / 2].filter((d, i) => i === 0 || half > len / 2);
+      const spots: [number, number][] = [
+        ...along(hw, w).map((d) => [cx + d, own[3] + h / 2 + 0.05] as [number, number]),
+        ...along(hw, w).map((d) => [cx + d, own[1] - h / 2 - 0.05] as [number, number]),
+        ...along(hh, h).map((d) => [own[2] + w / 2 + 0.05, cy + d] as [number, number]),
+        ...along(hh, h).map((d) => [own[0] - w / 2 - 0.05, cy + d] as [number, number]),
+      ];
+      for (const [x, y] of spots) {
+        const b: Box = [x - w / 2, y - h / 2, x + w / 2, y + h / 2];
+        if (!onBoard(b)) continue;
+        if (obstacles[layer].some((o) => overlaps(b, o))) continue;
+        if (yards[layer].some((c) => c.id !== pc.pcb_component_id && overlaps(b, c.box))) continue;
+        if (placed[layer].some((p) => overlaps(b, p, 0.1))) continue;
+        placed[layer].push(b);
+        add.push({ type: "pcb_silkscreen_text", pcb_silkscreen_text_id: `pcb_silkscreen_text_ref_${n++}`, pcb_component_id: pc.pcb_component_id, layer, text: designators[m.instance] ?? m.instance, font: "tscircuit2024", font_size: size, anchor_alignment: "center", anchor_position: { x: r4(x), y: r4(y) }, ccw_rotation: 0 });
+        references++;
+        set = true;
+        break;
+      }
+      if (set) break;
+    }
+    if (!set) omitted.push(m.instance);
+
+    // the pin-1 mark: beside the pin-1 pad, on the side away from the part's centre
+    const own_pads = cj.filter((e) => (e.type === "pcb_smtpad" || e.type === "pcb_plated_hole") && e.pcb_component_id === pc.pcb_component_id);
+    const pin1 = own_pads.find((e) => (e.port_hints ?? []).includes("pin1"));
+    const pins = new Set(own_pads.flatMap((e) => (e.port_hints ?? []).filter((h: string) => /^pin\d+$/.test(h))));
+    if (pin1 && pins.size >= 3) {
+      const [mx, my] = [own_pads.reduce((a, e) => a + e.x, 0) / own_pads.length, own_pads.reduce((a, e) => a + e.y, 0) / own_pads.length];
+      const pb = boxOf(pin1)!;
+      const [px, py] = [(pb[0] + pb[2]) / 2, (pb[1] + pb[3]) / 2];
+      const [hx, hy] = [(pb[2] - pb[0]) / 2 + 0.35, (pb[3] - pb[1]) / 2 + 0.35];
+      const spots: [number, number][] = [];
+      for (const dx of [-1, 0, 1]) for (const dy of [-1, 0, 1]) if (dx || dy) spots.push([px + dx * hx, py + dy * hy]);
+      spots.sort((a, b) => Math.hypot(b[0] - mx, b[1] - my) - Math.hypot(a[0] - mx, a[1] - my));
+      for (const [x, y] of spots) {
+        const dot: Box = [x - 0.15, y - 0.15, x + 0.15, y + 0.15];
+        if (obstacles[layer].some((o) => overlaps(dot, o)) || !onBoard(dot, 0) || placed[layer].some((p) => overlaps(dot, p))) continue;
+        add.push({ type: "pcb_silkscreen_circle", pcb_silkscreen_circle_id: `pcb_silkscreen_circle_pin1_${n++}`, pcb_component_id: pc.pcb_component_id, layer, center: { x: r4(x), y: r4(y) }, radius: 0.15, stroke_width: 0.15 });
+        placed[layer].push(dot);
+        marks++;
+        break;
+      }
+    }
+  }
+  return { circuitJson: [...cj, ...add], references, marks, omitted };
+}