@protoboardai/views 0.0.0-stage → 0.2.1

package/src/drawing/kicadSchematic.ts

@@ -0,0 +1,277 @@
+/**
+ * What a KiCad schematic export (`kicad-cli sch export svg`, a locked board's
+ * schematic.svg) says once it is read for its geometry: KiCad writes no nets
+ * and no parts into the file, only strokes, with an invisible `<text>` beside
+ * each piece of text. From those:
+ *
+ * - wires are the strokes in the wire colour (`data-pb-stroke="wire"`, svg.ts);
+ *   wires that meet (end to end, or an end on another wire) are one network;
+ * - a label (or a power symbol's name) is text whose anchor lies on a wire:
+ *   it names that network, and networks with the same name are one net;
+ * - a reference designator (R20, U5) is text in the field colour that looks
+ *   like one; the next field text after it is its value; a symbol body (the
+ *   part fill) belongs to the reference nearest it.
+ *
+ * The geometry functions are plain data (tested in Node); `indexKicadSchematic`
+ * reads them from the drawing in the page.
+ */
+
+export type Pt = [number, number];
+export interface Segment {
+  a: Pt;
+  b: Pt;
+}
+export interface Label {
+  text: string;
+  /** The text's anchor and the far end of its run (the label's own line). */
+  at: Pt;
+  end: Pt;
+}
+
+/** The segments of a path's `d` (absolute moves and lines: what KiCad writes). */
+export function segmentsOf(d: string): Segment[] {
+  const out: Segment[] = [];
+  let last: Pt | undefined;
+  let start: Pt | undefined;
+  for (const m of d.matchAll(/([MLZmlz])|(-?[\d.]+(?:e-?\d+)?)[\s,]+(-?[\d.]+(?:e-?\d+)?)/g)) {
+    if (m[1]) {
+      const c = m[1].toUpperCase();
+      if (c === "M") last = undefined;
+      if (c === "Z" && last && start) out.push({ a: last, b: start });
+      continue;
+    }
+    const p: Pt = [Number(m[2]), Number(m[3])];
+    if (last) out.push({ a: last, b: p });
+    else start = p;
+    last = p;
+  }
+  return out;
+}
+
+/** Distance from a point to a segment. */
+export function distance(p: Pt, s: Segment): number {
+  const [ax, ay] = s.a;
+  const dx = s.b[0] - ax;
+  const dy = s.b[1] - ay;
+  const len = dx * dx + dy * dy;
+  const t = len ? Math.max(0, Math.min(1, ((p[0] - ax) * dx + (p[1] - ay) * dy) / len)) : 0;
+  return Math.hypot(p[0] - (ax + t * dx), p[1] - (ay + t * dy));
+}
+
+/** A grid of segments by cell, for the near ones to a point. */
+class Grid {
+  private cells = new Map<string, number[]>();
+  constructor(
+    private segs: Segment[],
+    private size = 5,
+  ) {
+    segs.forEach((s, i) => {
+      const [x0, x1] = [Math.min(s.a[0], s.b[0]), Math.max(s.a[0], s.b[0])];
+      const [y0, y1] = [Math.min(s.a[1], s.b[1]), Math.max(s.a[1], s.b[1])];
+      for (let x = Math.floor(x0 / size); x <= Math.floor(x1 / size); x++)
+        for (let y = Math.floor(y0 / size); y <= Math.floor(y1 / size); y++) {
+          const k = `${x},${y}`;
+          const c = this.cells.get(k);
+          if (c) c.push(i);
+          else this.cells.set(k, [i]);
+        }
+    });
+  }
+  near(p: Pt, r: number): number[] {
+    const out = new Set<number>();
+    for (let x = Math.floor((p[0] - r) / this.size); x <= Math.floor((p[0] + r) / this.size); x++)
+      for (let y = Math.floor((p[1] - r) / this.size); y <= Math.floor((p[1] + r) / this.size); y++) for (const i of this.cells.get(`${x},${y}`) ?? []) if (distance(p, this.segs[i]) <= r) out.add(i);
+    return [...out];
+  }
+}
+
+/**
+ * The networks of a schematic's wires, each named by the labels on it: for
+ * each segment, the net it is on (its name, or `~<n>` for a network no label
+ * names), and for each label, its net.
+ */
+export function wireNets(segs: Segment[], labels: Label[], tolerance = 0.05, reach = 0.6): { segmentNet: string[]; labelNet: (string | undefined)[] } {
+  const parent = segs.map((_, i) => i);
+  const find = (i: number): number => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+  const join = (a: number, b: number) => {
+    const [x, y] = [find(a), find(b)];
+    if (x !== y) parent[x] = y;
+  };
+  const grid = new Grid(segs);
+  // an end of a wire on another wire (end to end, or a T) joins them
+  segs.forEach((s, i) => {
+    for (const p of [s.a, s.b]) for (const j of grid.near(p, tolerance)) if (j !== i) join(i, j);
+  });
+  // a label on a wire names its network (the anchor, or the end of its run, on the wire)
+  const named = new Map<number, string>();
+  const labelRoot = labels.map((l) => {
+    const hits = [...grid.near(l.at, reach), ...grid.near(l.end, reach)];
+    if (!hits.length) return undefined;
+    const r = find(hits[0]);
+    if (!named.has(r)) named.set(r, l.text);
+    return r;
+  });
+  // networks with the same name are one net
+  const byName = new Map<string, number>();
+  for (const [r, name] of named) {
+    const other = byName.get(name);
+    if (other === undefined) byName.set(name, r);
+    else join(r, other);
+  }
+  const nameOf = new Map<number, string>();
+  for (const [r, name] of named) nameOf.set(find(r), name);
+  const netOf = (i: number) => {
+    const r = find(i);
+    return nameOf.get(r) ?? `~${r}`;
+  };
+  return { segmentNet: segs.map((_, i) => netOf(i)), labelNet: labelRoot.map((r) => (r === undefined ? undefined : netOf(r))) };
+}
+
+/** A reference designator as KiCad writes one (R20, U5, BT1, SW1, D23); not a power symbol's `#PWR01`. */
+export const isReference = (t: string) => /^[A-Z]{1,4}\d{1,4}[A-Z]?$/.test(t);
+
+export interface SchematicPart {
+  ref: string;
+  value?: string;
+  at: Pt;
+  /** The elements that draw it (its reference, its value, its body), lit when it is picked. */
+  els: Element[];
+  /** Its body's box (drawing units), when it has one. */
+  box?: [number, number, number, number];
+}
+
+export interface SchematicIndex {
+  /** Each net's elements (wires, labels), by the net's key (its name, or `~<n>` for an unnamed one). */
+  nets: Map<string, Element[]>;
+  /** The net of an element the pointer can be over. */
+  netOf: Map<Element, string>;
+  parts: SchematicPart[];
+  /** The net nearest a drawing point within `reach` (a wire, or a label's run): strokes are too thin to hit with a pointer. */
+  netAt(p: Pt, reach: number): string | undefined;
+}
+
+/** The text an invisible `<text>` stands for, and the group of strokes KiCad drew for it (its next sibling). */
+const drawnText = (t: Element): Element[] => {
+  const next = t.nextElementSibling;
+  return next?.matches("g.stroked-text") ? [t, next] : [t];
+};
+
+/** Read a KiCad schematic drawing in the page for its nets and parts. */
+export function indexKicadSchematic(root: SVGSVGElement): SchematicIndex {
+  // the wires
+  const wirePaths = [...root.querySelectorAll('[data-pb-stroke="wire"] path, path[data-pb-stroke="wire"], [data-pb-stroke="wire"] polyline, polyline[data-pb-stroke="wire"]')].filter((e) => !e.closest(".stroked-text"));
+  const segs: Segment[] = [];
+  const segEl: Element[] = [];
+  for (const p of wirePaths) {
+    const d = p.getAttribute("d") ?? (p.getAttribute("points") ? `M ${p.getAttribute("points")}` : "");
+    for (const s of segmentsOf(d)) {
+      segs.push(s);
+      segEl.push(p);
+    }
+  }
+  // the symbols' bodies (the part fill): a pin's name is inside one, a reference never is
+  const bodies: { el: Element; box: [number, number, number, number] }[] = [];
+  for (const b of root.querySelectorAll('[data-pb-fill="body"]')) {
+    try {
+      const r = (b as SVGGraphicsElement).getBBox();
+      if (r.width && r.height) bodies.push({ el: b, box: [r.x, r.y, r.width, r.height] });
+    } catch {
+      /* not drawn */
+    }
+  }
+  const inBody = (x: number, y: number) => bodies.some(({ box: q }) => x > q[0] && x < q[0] + q[2] && y > q[1] && y < q[1] + q[3]);
+  // the texts: labels (lower-case names on a wire), references and values (the field colour)
+  const texts = [...root.querySelectorAll("text")];
+  const labels: Label[] = [];
+  const labelEls: Element[][] = [];
+  const parts: SchematicPart[] = [];
+  let lastPart: SchematicPart | undefined;
+  for (const t of texts) {
+    const text = t.textContent?.trim() ?? "";
+    if (!text) continue;
+    const x = parseFloat(t.getAttribute("x") ?? "");
+    const y = parseFloat(t.getAttribute("y") ?? "");
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+    const field = t.closest('[data-pb-stroke="label"]');
+    if (field && isReference(text) && !inBody(x, y)) {
+      lastPart = { ref: text, at: [x, y], els: drawnText(t) };
+      parts.push(lastPart);
+      continue;
+    }
+    if (field && lastPart && !lastPart.value && !/^\d+$/.test(text)) {
+      lastPart.value = text;
+      lastPart.els.push(...drawnText(t));
+      lastPart = undefined;
+      continue;
+    }
+    lastPart = undefined;
+    if (/^\d+$/.test(text)) continue;
+    // a rotated label runs along its own axis: its far end is where the rotation takes the run's end
+    const len = parseFloat(t.getAttribute("textLength") ?? "0") || 0;
+    const rotated = /rotate\(\s*-?90/.test(t.closest("g[transform]")?.getAttribute("transform") ?? "");
+    const anchor = t.getAttribute("text-anchor");
+    const dir = anchor === "end" ? -1 : 1;
+    const end: Pt = rotated ? [x, y - dir * len] : [x + dir * len, y];
+    labels.push({ text, at: [x, y], end });
+    labelEls.push(drawnText(t));
+  }
+  const { segmentNet, labelNet } = wireNets(segs, labels);
+  const grid = new Grid(segs);
+  const nets = new Map<string, Element[]>();
+  const netOf = new Map<Element, string>();
+  const add = (net: string, els: Element[]) => {
+    const list = nets.get(net) ?? [];
+    for (const e of els) {
+      if (!netOf.has(e)) list.push(e);
+      netOf.set(e, net);
+    }
+    nets.set(net, list);
+  };
+  segmentNet.forEach((net, i) => add(net, [segEl[i]]));
+  labelNet.forEach((net, i) => net && add(net, labelEls[i]));
+
+  // a body belongs to the reference nearest it
+  for (const { el: b, box } of bodies) {
+    let best: SchematicPart | undefined;
+    let bestD = Infinity;
+    for (const p of parts) {
+      const dx = Math.max(box[0] - p.at[0], 0, p.at[0] - (box[0] + box[2]));
+      const dy = Math.max(box[1] - p.at[1], 0, p.at[1] - (box[1] + box[3]));
+      const d = Math.hypot(dx, dy);
+      if (d < bestD) [best, bestD] = [p, d];
+    }
+    if (best && bestD < 8 && !best.box) {
+      best.box = box;
+      best.els.push(b);
+    }
+  }
+  const netAt = (p: Pt, reach: number): string | undefined => {
+    let best: string | undefined;
+    let bestD = reach;
+    for (const i of grid.near(p, reach)) {
+      const d = distance(p, segs[i]);
+      if (d <= bestD) [best, bestD] = [segmentNet[i], d];
+    }
+    labels.forEach((l, i) => {
+      const net = labelNet[i];
+      if (!net) return;
+      const d = distance(p, { a: l.at, b: l.end });
+      if (d <= bestD) [best, bestD] = [net, d];
+    });
+    return best;
+  };
+  return { nets, netOf, parts, netAt };
+}
+
+/** The part at a drawing point: the one whose body holds it, else the reference nearest it within `reach`. */
+export function partAt(parts: SchematicPart[], p: Pt, reach = 4): SchematicPart | undefined {
+  const inside = parts.filter((q) => q.box && p[0] >= q.box[0] && p[0] <= q.box[0] + q.box[2] && p[1] >= q.box[1] && p[1] <= q.box[1] + q.box[3]);
+  if (inside.length) return inside.sort((a, b) => a.box![2] * a.box![3] - b.box![2] * b.box![3])[0];
+  let best: SchematicPart | undefined;
+  let bestD = reach;
+  for (const q of parts) {
+    const d = Math.hypot(q.at[0] - p[0], q.at[1] - p[1]);
+    if (d < bestD) [best, bestD] = [q, d];
+  }
+  return best;
+}

package/src/drawing/palettes.ts

@@ -0,0 +1,150 @@
+/**
+ * The colours circuit tools write into their standard-output drawings and the
+ * role each plays, and what each role is drawn with in the shell's theme.
+ *
+ * The drawings are found by file name (schematic.svg, pcb-top.svg,
+ * pcb-bottom.svg; docs/specs/tool-integrations.md §8), never by the tool. The
+ * palettes below know the colours of the drawings the stack's circuit
+ * provider writes: tscircuit's circuit-to-svg defaults, and KiCad's default
+ * colours for a locked board's export (`kicad-cli sch|pcb export svg`); a
+ * drawing in other colours keeps them.
+ */
+import type { Palette } from "./svg.js";
+
+const map = (entries: Record<string, string>): Palette => new Map(Object.entries(entries));
+
+/** Schematic roles: paper, ink (symbols, outlines), body (part fill), wire, pin numbers, labels. */
+export const SCHEMATIC_PALETTE = map({
+  "#f5f1ed": "paper",
+  "#ffffff": "paper",
+  "#840000": "ink",
+  "#ffffc2": "body",
+  "#009600": "wire",
+  "#a90000": "pin",
+  "#006464": "label",
+  "#0f0f0f": "net-text",
+  "#ffffff/0.6": "net-fill",
+  "#ff0000": "hover",
+  // KiCad (Eeschema): the sheet, labels and their text, no-connect marks and buses
+  "#f5f4ef": "paper",
+  "#000000": "net-text",
+  "#000084": "ink",
+  "#c2c2c2": "label",
+});
+
+/** PCB roles: the page, copper on each side, silkscreen, drills, the board's edge, keepouts. */
+export const PCB_PALETTE = map({
+  "#000000": "paper",
+  "#c83434": "copper-top",
+  "#4d7fc4": "copper-bottom",
+  "#ff26e2": "drill",
+  "#f2eda1": "silk",
+  "#5da9e9": "silk",
+  "#ffffff": "edge",
+  "#ffffff/0.5": "edge",
+  "#ff6b6b": "keepout",
+  "#ff6b6b/0.2": "keepout-fill",
+  // KiCad (Pcbnew): the mask's openings over the pads on each side, the bottom silkscreen, the edge cuts
+  "#d864ff": "pad",
+  "#02ffee": "pad",
+  "#e8b2a7": "silk",
+  "#d0d2cd": "edge",
+});
+
+/**
+ * The roles in theme tokens. Copper and drills are data colours: the same
+ * family in every theme, mixed toward the canvas so they sit on it; the
+ * page, ink, labels and edges are the theme's own. High contrast draws every
+ * line in the foreground and keeps fills out of the way.
+ */
+export const DRAWING_CSS = `
+.pb-board-drawing {
+  --pb-d-paper: var(--uhd-canvas);
+  --pb-d-ink: color-mix(in oklab, var(--uhd-text) 88%, var(--uhd-canvas));
+  --pb-d-body: var(--uhd-node);
+  --pb-d-wire: var(--uhd-domain-software);
+  /* pin names and numbers: quieter than the ink, but opaque and readable on every canvas (a theme's faint text may be translucent) */
+  --pb-d-pin: color-mix(in oklab, var(--uhd-text) 70%, var(--uhd-canvas));
+  --pb-d-label: var(--uhd-text-muted);
+  --pb-d-net-text: var(--uhd-text);
+  --pb-d-net-fill: color-mix(in oklab, var(--uhd-surface) 85%, transparent);
+  --pb-d-hover: var(--uhd-highlight);
+  --pb-d-board: color-mix(in oklab, var(--uhd-text) 7%, var(--uhd-canvas));
+  --pb-d-copper-top: color-mix(in oklab, #c94a3e 85%, var(--uhd-canvas));
+  --pb-d-copper-bottom: color-mix(in oklab, #4d7fc4 82%, var(--uhd-canvas));
+  --pb-d-drill: color-mix(in oklab, var(--uhd-text) 30%, var(--uhd-canvas));
+  --pb-d-silk: color-mix(in oklab, var(--uhd-text) 92%, var(--uhd-canvas));
+  --pb-d-edge: var(--uhd-border-strong);
+  --pb-d-keepout: var(--uhd-severity-error);
+  --pb-d-keepout-fill: color-mix(in oklab, var(--uhd-severity-error) 14%, transparent);
+  --pb-d-select: var(--uhd-accent);
+  /* the routed board (CircuitPcbView): inner copper, the far side's silkscreen, courtyards, the fabrication drawing */
+  --pb-d-copper-inner-0: color-mix(in oklab, #d1a23a 80%, var(--uhd-canvas));
+  --pb-d-copper-inner-1: color-mix(in oklab, #4fa66a 78%, var(--uhd-canvas));
+  --pb-d-copper-inner-2: color-mix(in oklab, #9a6cc9 78%, var(--uhd-canvas));
+  --pb-d-copper-inner-3: color-mix(in oklab, #3aa7a7 78%, var(--uhd-canvas));
+  --pb-d-silk-bottom: color-mix(in oklab, var(--uhd-text) 55%, var(--uhd-canvas));
+  --pb-d-courtyard: color-mix(in oklab, var(--uhd-text-muted) 80%, var(--uhd-canvas));
+  --pb-d-fab: color-mix(in oklab, var(--uhd-domain-mechanical, var(--uhd-text-muted)) 75%, var(--uhd-canvas));
+  /* a pad the solder mask leaves open (KiCad's export draws the openings over the copper): the finish */
+  --pb-d-pad: color-mix(in oklab, #d9a441 82%, var(--uhd-canvas));
+}
+/* the board check's marks on the routed board: a fixed size on screen at any zoom (--pb-px: drawing units per pixel) */
+.pb-pcb .pb-finding-ring { r: calc(var(--pb-px, 0.05) * 6px); opacity: 0.9; }
+.pb-pcb .pb-finding-dot { r: calc(var(--pb-px, 0.05) * 2px); }
+.pb-pcb [data-severity="warning"] .pb-finding-ring { r: calc(var(--pb-px, 0.05) * 4.5px); opacity: 0.75; }
+.pb-pcb [data-severity="info"] .pb-finding-ring { r: calc(var(--pb-px, 0.05) * 3.5px); opacity: 0.6; }
+.pb-pcb .pb-pcb-layer[data-layer="edge"] { color: var(--pb-d-board); }
+.pb-pcb .pb-pcb-layer[data-layer="edge"] > * { fill: var(--pb-d-board); stroke: var(--pb-d-edge); stroke-width: 0.12px; vector-effect: non-scaling-stroke; }
+.pb-pcb .pb-pcb-copper > * { opacity: 0.9; }
+.pb-pcb .pb-pcb-copper .pb-pour { opacity: 0.2; }
+.pb-pcb .pb-pcb-layer[data-layer="drill"] { color: var(--pb-d-paper); }
+.pb-pcb [data-net], .pb-pcb [data-ref] { cursor: pointer; }
+.pb-pcb .pb-pcb-findings { pointer-events: none; }
+.pb-drawing { background: var(--pb-d-paper); }
+.pb-drawing svg { display: block; overflow: visible; }
+.pb-drawing text { font-family: var(--uhd-font-ui); }
+.pb-drawing .pcb-board { fill: var(--pb-d-board); }
+.pb-drawing .schematic-boundary, .pb-drawing .pcb-boundary { stroke: var(--pb-d-edge); }
+/* hit areas the tool draws invisible stay invisible */
+.pb-drawing .trace-invisible-hover-outline, .pb-drawing .schematic-port-hover { opacity: 0; }
+/* what the pointer is over, and what is selected */
+.pb-drawing [data-pb-hot] { cursor: pointer; }
+.pb-drawing .pb-net-on :is(path, line) { stroke: var(--pb-d-hover) !important; stroke-width: 0.9px; }
+.pb-drawing .pb-net-on.sch-trace-junction, .pb-drawing .pb-net-on circle { fill: var(--pb-d-hover) !important; }
+.pb-drawing .pb-pad-on { fill: var(--pb-d-hover) !important; stroke: var(--pb-d-hover) !important; }
+.pb-drawing .pb-part-hover :is(.sch-component-body, .sch-component-symbol-path) { stroke: var(--pb-d-hover) !important; }
+.pb-drawing .pb-part-on :is(.sch-component-body, .sch-component-symbol-path, .component-pin) { stroke: var(--pb-d-select) !important; stroke-width: 0.9px; }
+.pb-drawing .pb-part-on .sch-component-body { fill: color-mix(in oklab, var(--pb-d-select) 14%, var(--pb-d-body)) !important; }
+.pb-drawing .pb-part-on text { fill: var(--pb-d-select) !important; }
+.pb-drawing .pb-pad-part { fill: var(--pb-d-select) !important; }
+/* KiCad's drawings: lines never thinner than a pixel at any zoom (its strokes are a tenth of a millimetre), wires as wide as the symbols' */
+.pb-kicad .pb-drawing svg :is(path, line, polyline, polygon, circle, rect) { stroke-width: max(var(--pb-kicad-w, 0.1524px), calc(var(--pb-px, 0.05) * 0.9px)); }
+.pb-kicad .pb-drawing [data-pb-stroke="wire"], .pb-kicad .pb-drawing [data-pb-stroke="wire"] :is(path, line, polyline) { --pb-kicad-w: 0.254px; }
+.pb-kicad .pb-drawing [data-pb-page] { stroke: none; }
+/* a KiCad net lit end to end (its wires and labels), a part picked (its reference, value and body) */
+.pb-drawing .pb-kicad-net, .pb-drawing .pb-kicad-net path { stroke: var(--pb-d-hover) !important; stroke-width: max(0.3px, calc(var(--pb-px, 0.05) * 2.5px)) !important; }
+.pb-drawing .pb-kicad-part-hover, .pb-drawing .pb-kicad-part-hover path { stroke: var(--pb-d-hover) !important; }
+.pb-drawing .pb-kicad-part, .pb-drawing .pb-kicad-part path { stroke: var(--pb-d-select) !important; }
+.pb-drawing [data-pb-fill="body"].pb-kicad-part { fill: color-mix(in oklab, var(--pb-d-select) 18%, var(--pb-d-body)) !important; stroke-width: max(0.25px, calc(var(--pb-px, 0.05) * 2px)) !important; }
+/* KiCad's board export fills a pour as many polygons side by side: a hairline of the same copper closes the seams between them */
+.pb-kicad-pcb .pb-drawing [data-pb-fill^="copper"]:not([data-pb-stroke]) { stroke: var(--pb-d-copper-top) !important; stroke-width: 0.02px !important; }
+.pb-kicad-pcb .pb-drawing [data-pb-fill="copper-bottom"]:not([data-pb-stroke]) { stroke: var(--pb-d-copper-bottom) !important; }
+[data-uhd-scheme^="high-contrast"] .pb-board-drawing {
+  --pb-d-ink: var(--uhd-text);
+  --pb-d-body: var(--uhd-canvas);
+  --pb-d-wire: var(--uhd-text);
+  --pb-d-pin: var(--uhd-text);
+  --pb-d-label: var(--uhd-text);
+  --pb-d-net-fill: var(--uhd-canvas);
+  --pb-d-board: var(--uhd-canvas);
+  --pb-d-silk: var(--uhd-text);
+  --pb-d-edge: var(--uhd-contrast-border);
+  --pb-d-hover: var(--uhd-contrast-active-border);
+  --pb-d-select: var(--uhd-contrast-active-border);
+  --pb-d-silk-bottom: var(--uhd-text);
+  --pb-d-courtyard: var(--uhd-text);
+  --pb-d-fab: var(--uhd-text);
+  --pb-d-pad: var(--uhd-text);
+}
+`;