perfboard-designer-mcp 0.3.0 → 0.5.0

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.
Files changed (3) hide show
  1. package/README.md +2 -1
  2. package/dist/server.js +347 -57
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -81,7 +81,7 @@ Point them at a local Worker with `http://localhost:8787/render.svg` and `http:/
81
81
  | `list_parts` | Lists the parts a project can place (79 today). Without a query, every part by category, one line each (its id, name and pin count). With words such as `"capacitor"` or `"555"`, the parts matching all of them, or the closest ones when none do. |
82
82
  | `get_part` | Parts in full, as many as you name in `ids`: which list each goes in, its pins and pin labels, polarity, value unit, holes its body covers, and an example entry to copy. |
83
83
  | `new_project` | Starts a project kept in memory and returns its `projectId`: a blank perfboard or stripboard of the size you give, or a copy of an example (`example: "555-led-blinker"`). |
84
- | `edit_project` | Changes a kept project with a list of ops, all or none: `add_part` (by part id, with `at`, or `from`/`to` for two-lead parts; refs are numbered if left out), `update_part` (move, turn, change value or ref), `remove_parts`, `add_wire` (`from`/`to`, with `via` for the holes it bends at, or a `path` of holes made into one wire per leg; any end can be a pin by name, e.g. `"U1.7"` or `"D1.K"`, for the hole it's in), `update_wire` (ends by hole or pin too, `via` to replace its bends), `remove_wires`, `set_board`, `add_cuts`/`remove_cuts`, `set_pad` (a note on a hole). Returns what changed, where the new or moved parts' pins landed, and the board checked as `validate_project` does; when it has no errors, also its nets. |
84
+ | `edit_project` | Changes a kept project with a list of ops, all or none: `add_part` (by part id, with `at`, or `from`/`to` for two-lead parts; refs are numbered if left out; or a part of the agent's own: `custom`, pins anywhere or a catalog part's package via `shape` with its own pin names, or `chip`, a dual-row chip or dev board, placed again later by name), `update_part` (move, turn, change value or ref), `remove_parts`, `add_wire` (`from`/`to`, with `via` for the holes it bends at, or a `path` of holes made into one wire per leg; any end can be a pin by name, e.g. `"U1.7"` or `"D1.K"`, for the hole it's in), `update_wire` (ends by hole or pin too, `via` to replace its bends), `remove_wires`, `set_board`, `add_cuts`/`remove_cuts`, `set_pad` (a note on a hole). Returns what changed, where the new or moved parts' pins landed, and the board checked as `validate_project` does; when it has no errors, also its nets. |
85
85
  | `get_project` | The whole project file of a kept project. |
86
86
  | `get_pin_positions` | Where every placed part's pins land on the board after rotation, e.g. `U1 pin 8 (VCC) at [9, 3]`, so wires can be routed to the right holes. |
87
87
  | `render_board` | Draws the board as text, one cell per hole with column and row numbers: pins by part key and number (`a1`), holes under a body, wire ends, holes a wire runs over without joining them, strip cuts and holes with notes, then which part each key is and every wire with its net. `area` draws only part of the board (needed above 6000 holes). `format: "png"` draws a picture instead, as the editor draws it (holes 50 px apart, scaled down to fit 1000 px; `area` crops it), for an agent to look at. |
@@ -262,6 +262,7 @@ doesn't connect it, and two wires crossing aren't shorted, so a crossing is fine
262
262
  it so it doesn't pass for a joint, and the 3D view arches the upper wire). A hole takes one part's
263
263
  pin or lead at most (a second part there is an error, as on a real board) plus any number of wire
264
264
  ends, and everything in a hole is joined: to connect two parts, run a wire between their pins.
265
+ A jumper can lie on the solder side (`side: "bottom"`, format version 9): it joins its end holes the same way but never crosses a top wire.
265
266
  On a stripboard, every hole along a strip is joined up to the next cut, and a cut hole connects to
266
267
  nothing. `get_nets` and `validate_project` work this out with the same code as the
267
268
  editor's Nets panel, so they agree with what you see there.
package/dist/server.js CHANGED
@@ -38129,7 +38129,7 @@ Rules: holes are [column, row] from the top-left hole, from 0, 2.54 mm apart. A
38129
38129
  The full guide, with more on all this and on changing a board the user shares (read_share_link): the resource perfboard://docs/guide.`;
38130
38130
  var GUIDE = `# Designing a board with Perfboard Designer
38131
38131
 
38132
- Perfboard Designer (https://perfboarddesigner.com) is a browser editor for perfboard and stripboard layouts. With these tools you design a board as a project file (JSON through version 8) and give the user a link that opens it in the editor. Parts may carry an instanceId; version 8 adds optional requirements (independent intended nets, unused pins, component snapshots and a validate flag). Preserve these when editing. Requirement connections never derive from the board's wiring. When requirements.validate is true, validation also reports missing components/pins, missing or unexpected connections, and incomplete pin coverage. Unspecified pins are unchecked, not assumed disconnected; this differs from the existing complete-list expectNets contract. New parts join the requirement inventory unconnected; board changes must never overwrite intended nets. The goal is a board that's electrically right, looks neat and is easy to solder by hand: the user will build it.
38132
+ Perfboard Designer (https://perfboarddesigner.com) is a browser editor for perfboard and stripboard layouts. With these tools you design a board as a project file (JSON through version 9) and give the user a link that opens it in the editor. Parts may carry an instanceId; version 8 adds optional requirements (independent intended nets, unused pins, component snapshots and a validate flag). Preserve these when editing. Requirement connections never derive from the board's wiring. When requirements.validate is true, validation also reports missing components/pins, missing or unexpected connections, and incomplete pin coverage. Unspecified pins are unchecked, not assumed disconnected; this differs from the existing complete-list expectNets contract. New parts join the requirement inventory unconnected; board changes must never overwrite intended nets. The goal is a board that's electrically right, looks neat and is easy to solder by hand: the user will build it.
38133
38133
 
38134
38134
  ## Workflow
38135
38135
 
@@ -38156,6 +38156,8 @@ Wires are insulated jumpers: a wire joins only the holes at its two ends, never
38156
38156
 
38157
38157
  A wire can bend: add_wire's "via" lists the holes it bends at on its way, in order, and the file keeps them as the wire's "via" (format version 4). A bend joins nothing, like a hole a wire passes over: the wire is one piece of wire, soldered only at its two ends. update_wire's "via" replaces a wire's bends ([] straightens it). add_wire's "path" is different: each corner of a path is the end of one wire and the start of the next, so it joins whatever is in that hole; use it only when a corner should connect.
38158
38158
 
38159
+ A jumper can lie on the solder side instead of the top: add_wire/update_wire "side": "bottom" (the file's "side", format version 9; absent means the top). It joins its end holes like any jumper, and one in the same hole as a top wire's end or a pin is on that net, but it never crosses a top wire, so use it to take a long run out of the way of a crowded top. The top view shows it faded; render_board's wire list marks it "solder side". Solder paths are always on the copper side and take no "side".
38160
+
38159
38161
  A solder path is the other way to connect holes: a trail of solder bridging pad to pad on the copper side, which many people use instead of short jumpers. add_wire with "solder": true makes one ("from"/"to" with "via", or a "path", which here makes one solder path bending at its corners); the file marks it "kind": "solder" (format version 5), with no color or width. Unlike a jumper it's bare metal: it joins every hole it runs over, its ends, its bends and each hole between, and any solder path it touches, so run it only over holes that belong to one net, and never across another net's pins or solder path. Keep them short and straight, along a row or column between neighbouring parts; use jumper wires for longer runs and wherever a connection has to cross another. In render_board's text a solder path's holes show as "=", and its wire list says "solder path".
38160
38162
 
38161
38163
  ## Laying it out well
@@ -38171,9 +38173,19 @@ A board that's right isn't done until it looks neat and someone can easily solde
38171
38173
  - On a stripboard, let the strips do the connecting: place parts so pins that share a net sit on one strip, and use wires and cuts only where strips can't.
38172
38174
  - Look at the board as you go: render_board shows free space as text; with format "png" you see it as the user will. Tidy it up before you give the user the link: fewer crossings, fewer bends, straighter rows. Never break a connection to make it look better.
38173
38175
 
38176
+ ## Parts the catalog doesn't have
38177
+
38178
+ When list_parts has nothing for a part, make it with add_part, then place more of it with \`part\` and its name (\`{"op": "add_part", "part": "BC337", "at": [8, 2]}\`). Don't stand in a catalog part with the wrong pinout. Three kinds:
38179
+
38180
+ - A part in a package the catalog has, with its own name and pinout: a BC337 or 2N3906 is a TO-92 transistor, an IRLZ44N or LM7812 a TO-220. \`custom\` with \`shape\`, the catalog part's id, and the pin names in its pin order (get_part gives the package's pins): \`{"op": "add_part", "custom": {"name": "BC337", "shape": "transistor", "pins": [{"label": "C"}, {"label": "B"}, {"label": "E"}]}, "at": [2, 2]}\`. Check the pinout in the part's datasheet: they differ from part to part. It's drawn as the package, and its refs follow it (Q1).
38181
+ - A module or anything else with pins anywhere: \`custom\` with every pin's hole \`at\` within its body, from the body's top-left hole, pin 1 first; \`cols\` and \`rows\` (the body's size, else just big enough for its pins), \`color\` and \`refPrefix\` (default M) are optional. An HC-SR04's four pins along the bottom of an 8\xD74 body: \`{"name": "HC-SR04", "cols": 8, "rows": 4, "pins": [{"at": [2, 3], "label": "VCC"}, {"at": [3, 3], "label": "TRIG"}, {"at": [4, 3], "label": "ECHO"}, {"at": [5, 3], "label": "GND"}]}\`. add_part's \`at\` is pin 1's hole on the board; the body reaches from there as the pins say.
38182
+ - A dual-row chip or dev board: \`chip\` with \`pinsPerSide\`, \`width\` (columns from one pin row to the other, both included: 4 for a narrow DIP), \`pins\` (names in DIP order: down the left row from pin 1 at the top left, then up the right row) and \`board: true\` for a dev board. add_part's \`at\` is its top-left pin.
38183
+
38184
+ Name pins: wires and expectNets can then use the names ("M1.VCC", "Q1.B"), and get_nets shows them. The project file keeps each custom part whole in its placed part's "custom" (version 6) and each chip in "customIcs", so the user's editor adds them to its parts list when they open the board. A name already in the catalog is refused: use the catalog's part.
38185
+
38174
38186
  ## More
38175
38187
 
38176
- get_project returns the whole file. Kept projects don't last forever (on your computer, only while the server runs; hosted, 30 days unused); a whole project file works in place of a projectId everywhere. To change a board the user shares with you, read it with read_share_link: it returns a projectId to edit. Such a board may hold the user's own parts, made in the editor: custom ICs and dev boards (the file's customIcs, placed as placedIcs) and custom modules (format version 6: a placedAdvancedComponents entry with definitionId "custom" carrying the whole part in "custom": its size, its pins' holes and names). Wire to their pins by name like any part's ("M1.VCC" or "M1.1") and keep them as they are; edit_project can remove them but not make new ones. The format is documented in the resource perfboard://docs/project-file, links in perfboard://docs/share-links, and the whole parts catalog is perfboard://parts.
38188
+ get_project returns the whole file. Kept projects don't last forever (on your computer, only while the server runs; hosted, 30 days unused); a whole project file works in place of a projectId everywhere. To change a board the user shares with you, read it with read_share_link: it returns a projectId to edit. Such a board may hold the user's own parts, made in the editor: custom ICs and dev boards (the file's customIcs, placed as placedIcs) and custom modules (format version 6: a placedAdvancedComponents entry with definitionId "custom" carrying the whole part in "custom": its size, its pins' holes and names, and with "shape" a built-in part's package it takes, such as "transistor" for a TO-92 BC337). Wire to their pins by name like any part's ("M1.VCC" or "M1.1"), place more of them by name, and keep them as they are (see Parts the catalog doesn't have). The format is documented in the resource perfboard://docs/project-file, links in perfboard://docs/share-links, and the whole parts catalog is perfboard://parts.
38177
38189
  `;
38178
38190
 
38179
38191
  // src/tools/catalog-tools.ts
@@ -38217,9 +38229,10 @@ function holesAlong(px) {
38217
38229
  init_define_COMPONENT_ICONS();
38218
38230
  init_define_EXAMPLE_PROJECTS();
38219
38231
  init_define_PNG_FONTS();
38220
- var PROJECT_FILE_VERSION = 8;
38232
+ var PROJECT_FILE_VERSION = 9;
38221
38233
  function fileVersionFor(project) {
38222
- if (project.requirements) return PROJECT_FILE_VERSION;
38234
+ if (project.wires.some((wire) => wire.side === "bottom")) return PROJECT_FILE_VERSION;
38235
+ if (project.requirements) return 8;
38223
38236
  if (project.placedAdvancedComponents.some((part) => part.custom)) return 6;
38224
38237
  if (project.wires.some((wire) => wire.kind === "solder")) return 5;
38225
38238
  return project.wires.some((wire) => wire.via?.length) ? 4 : 3;
@@ -38232,6 +38245,9 @@ init_define_PNG_FONTS();
38232
38245
  function isSolderPath(wire) {
38233
38246
  return wire.kind === "solder";
38234
38247
  }
38248
+ function isBottomWire(wire) {
38249
+ return wire.side === "bottom";
38250
+ }
38235
38251
  function wirePoints(wire) {
38236
38252
  return [wire.from, ...wire.via ?? [], wire.to];
38237
38253
  }
@@ -39048,10 +39064,61 @@ var CUSTOM_PART_ID = "custom";
39048
39064
  var CUSTOM_REF_PREFIX = "M";
39049
39065
  var MAX_CUSTOM_PART_SIDE = 40;
39050
39066
  var BODY_MARGIN = 0.45;
39067
+ function isShapeable(def) {
39068
+ return !def.gridSizable && !def.perPinIcon;
39069
+ }
39070
+ var CUSTOM_PART_SHAPES = ADVANCED_COMPONENT_DEFINITIONS.filter(isShapeable);
39071
+ function customPartShape(id) {
39072
+ const def = id ? getAdvancedComponentDefinition(id) : void 0;
39073
+ return def && isShapeable(def) ? def : void 0;
39074
+ }
39075
+ function shapeHoles(shape) {
39076
+ const holes = [...shape.pinOffsets, ...shape.shadedOffsets ?? []];
39077
+ const left = Math.min(...holes.map((h2) => h2.dx)), top = Math.min(...holes.map((h2) => h2.dy));
39078
+ const right = Math.max(...holes.map((h2) => h2.dx)), bottom = Math.max(...holes.map((h2) => h2.dy));
39079
+ return {
39080
+ cols: right - left + 1,
39081
+ rows: bottom - top + 1,
39082
+ pins: shape.pinOffsets.map((pin) => [pin.dx - left, pin.dy - top])
39083
+ };
39084
+ }
39085
+ function shapedPartSpec(shape, fields) {
39086
+ const { cols, rows, pins } = shapeHoles(shape);
39087
+ return {
39088
+ ...fields.id ? { id: fields.id } : {},
39089
+ name: fields.name,
39090
+ ...fields.refPrefix ? { refPrefix: fields.refPrefix } : {},
39091
+ cols,
39092
+ rows,
39093
+ pins: pins.map((at, i) => {
39094
+ const label = fields.labels[i]?.trim();
39095
+ return { at, ...label ? { label } : {} };
39096
+ }),
39097
+ shape: shape.id
39098
+ };
39099
+ }
39051
39100
  var definitions = /* @__PURE__ */ new WeakMap();
39052
39101
  function customPartDefinition(spec) {
39053
39102
  const cached2 = definitions.get(spec);
39054
39103
  if (cached2) return cached2;
39104
+ const shape = customPartShape(spec.shape);
39105
+ const definition = shape ? shapedDefinition(spec, shape) : moduleDefinition(spec);
39106
+ definitions.set(spec, definition);
39107
+ return definition;
39108
+ }
39109
+ function shapedDefinition(spec, shape) {
39110
+ return {
39111
+ ...shape,
39112
+ id: CUSTOM_PART_ID,
39113
+ name: spec.name,
39114
+ keywords: void 0,
39115
+ refPrefix: spec.refPrefix || shape.refPrefix,
39116
+ // The package's artwork, which the shape names by its own id.
39117
+ iconFile: getIconFile(shape),
39118
+ pinLabels: shape.pinOffsets.map((_2, i) => spec.pins[i]?.label?.trim() ?? "")
39119
+ };
39120
+ }
39121
+ function moduleDefinition(spec) {
39055
39122
  const [ax, ay] = spec.pins[0]?.at ?? [0, 0];
39056
39123
  const offset2 = ([col, row]) => ({ dx: col - ax, dy: row - ay });
39057
39124
  const pinHoles = new Set(spec.pins.map((pin) => `${pin.at[0]},${pin.at[1]}`));
@@ -39063,7 +39130,7 @@ function customPartDefinition(spec) {
39063
39130
  }
39064
39131
  const left = -ax - BODY_MARGIN, top = -ay - BODY_MARGIN;
39065
39132
  const right = spec.cols - 1 - ax + BODY_MARGIN, bottom = spec.rows - 1 - ay + BODY_MARGIN;
39066
- const definition = {
39133
+ return {
39067
39134
  id: CUSTOM_PART_ID,
39068
39135
  category: "modules.custom",
39069
39136
  name: spec.name,
@@ -39079,8 +39146,6 @@ function customPartDefinition(spec) {
39079
39146
  noIcon: true,
39080
39147
  ...spec.color ? { bodyColor: spec.color } : {}
39081
39148
  };
39082
- definitions.set(spec, definition);
39083
- return definition;
39084
39149
  }
39085
39150
  function advancedDefinitionFor(part) {
39086
39151
  return part.custom ? customPartDefinition(part.custom) : getAdvancedComponentDefinition(part.definitionId);
@@ -39694,9 +39759,19 @@ var REF_PREFIX = /^[A-Za-z]{1,4}$/;
39694
39759
  var MAX_LABEL_LENGTH = 24;
39695
39760
  function readCustomPart(value) {
39696
39761
  const entry = asEntry(value);
39697
- const cols = entry && wholeCount(entry.cols);
39698
- const rows = entry && wholeCount(entry.rows);
39699
- if (!entry || !cols || !rows || cols > MAX_CUSTOM_PART_SIDE || rows > MAX_CUSTOM_PART_SIDE || !Array.isArray(entry.pins)) return void 0;
39762
+ if (!entry) return void 0;
39763
+ const refPrefix = typeof entry.refPrefix === "string" && REF_PREFIX.test(entry.refPrefix) ? entry.refPrefix.toUpperCase() : void 0;
39764
+ const id = text(entry.id)?.slice(0, 64);
39765
+ const name = text(entry.name)?.trim().slice(0, 60);
39766
+ const shapeId = text(entry.shape)?.trim().slice(0, 64);
39767
+ const shape = customPartShape(shapeId);
39768
+ if (shape) {
39769
+ const labels = Array.isArray(entry.pins) ? entry.pins.map((item) => text(asEntry(item)?.label)?.trim().slice(0, MAX_LABEL_LENGTH) ?? "") : [];
39770
+ return shapedPartSpec(shape, { ...id ? { id } : {}, name: name || shape.name, ...refPrefix ? { refPrefix } : {}, labels });
39771
+ }
39772
+ const cols = wholeCount(entry.cols);
39773
+ const rows = wholeCount(entry.rows);
39774
+ if (!cols || !rows || cols > MAX_CUSTOM_PART_SIDE || rows > MAX_CUSTOM_PART_SIDE || !Array.isArray(entry.pins)) return void 0;
39700
39775
  const pins = [];
39701
39776
  const taken = /* @__PURE__ */ new Set();
39702
39777
  for (const item of entry.pins) {
@@ -39710,17 +39785,17 @@ function readCustomPart(value) {
39710
39785
  pins.push({ at: [col, row], ...label ? { label } : {} });
39711
39786
  }
39712
39787
  if (!pins.length) return void 0;
39713
- const refPrefix = typeof entry.refPrefix === "string" && REF_PREFIX.test(entry.refPrefix) ? entry.refPrefix.toUpperCase() : void 0;
39714
39788
  const color = text(entry.color)?.trim().slice(0, 32);
39715
- const id = text(entry.id)?.slice(0, 64);
39716
39789
  return {
39717
39790
  ...id ? { id } : {},
39718
- name: text(entry.name)?.trim().slice(0, 60) || "Custom Module",
39791
+ name: name || "Custom Module",
39719
39792
  ...refPrefix ? { refPrefix } : {},
39720
39793
  cols,
39721
39794
  rows,
39722
39795
  pins,
39723
- ...color ? { color } : {}
39796
+ ...color ? { color } : {},
39797
+ // A package this build doesn't have: drawn as a plain module, and kept for one that has it.
39798
+ ...shapeId ? { shape: shapeId } : {}
39724
39799
  };
39725
39800
  }
39726
39801
  var Reader = class {
@@ -39860,7 +39935,8 @@ function readGridFile(data, version2) {
39860
39935
  to,
39861
39936
  ...via.length ? { via } : {},
39862
39937
  ...optional2("color", text(entry.color)),
39863
- ...optional2("width", positiveNumber(entry.width))
39938
+ ...optional2("width", positiveNumber(entry.width)),
39939
+ ...version2 >= 9 && entry.side === "bottom" ? { side: "bottom" } : {}
39864
39940
  };
39865
39941
  });
39866
39942
  const placedIcs = r2.list(data.placedIcs, (entry) => {
@@ -39982,7 +40058,7 @@ function readProjectFile(raw) {
39982
40058
  const data = asEntry(raw);
39983
40059
  if (!data) throw new ProjectFileError(NOT_A_PROJECT);
39984
40060
  if (data.version === void 0) return asEntry(data.board) ? readGridFile(data, PROJECT_FILE_VERSION) : readV1(data);
39985
- if (data.version === 2 || data.version === 3 || data.version === 4 || data.version === 5 || data.version === 6 || data.version === 7 || data.version === 8) return readGridFile(data, data.version);
40061
+ if (data.version === 2 || data.version === 3 || data.version === 4 || data.version === 5 || data.version === 6 || data.version === 7 || data.version === 8 || data.version === 9) return readGridFile(data, data.version);
39986
40062
  if (typeof data.version === "number" && data.version > PROJECT_FILE_VERSION) {
39987
40063
  throw new ProjectFileError(
39988
40064
  "This project was saved by a newer version of Perfboard Designer. Reload the page to get the latest version, then open it again."
@@ -40041,6 +40117,7 @@ function layoutWires(wires, pinHoles) {
40041
40117
  for (let i = 0; i < wires.length; i++) {
40042
40118
  const endsOfI = /* @__PURE__ */ new Set([key3(wires[i].from), key3(wires[i].to)]);
40043
40119
  for (let j2 = i + 1; j2 < wires.length; j2++) {
40120
+ if (isBottomWire(wires[i]) !== isBottomWire(wires[j2])) continue;
40044
40121
  const isEnd = (at) => endsOfI.has(key3(at)) || key3(at) === key3(wires[j2].from) || key3(at) === key3(wires[j2].to);
40045
40122
  const seen = /* @__PURE__ */ new Set();
40046
40123
  for (const a of legs[i]) {
@@ -40055,8 +40132,29 @@ function layoutWires(wires, pinHoles) {
40055
40132
  }
40056
40133
  }
40057
40134
  hops.sort((a, b) => a.wire - b.wire || a.along - b.along);
40135
+ const runs = [];
40136
+ for (let i = 0; i < wires.length; i++) {
40137
+ for (let j2 = i + 1; j2 < wires.length; j2++) {
40138
+ if (isBottomWire(wires[i]) !== isBottomWire(wires[j2])) continue;
40139
+ for (const a of legs[i]) {
40140
+ legs[j2].forEach((b, l) => {
40141
+ const [bx, by] = b.leg.from;
40142
+ const sx = b.leg.to[0] - bx, sy = b.leg.to[1] - by;
40143
+ const length2 = sx * sx + sy * sy;
40144
+ const rx = a.leg.to[0] - a.leg.from[0], ry = a.leg.to[1] - a.leg.from[1];
40145
+ if (!length2 || rx * sy - ry * sx !== 0 || (a.leg.from[0] - bx) * sy - (a.leg.from[1] - by) * sx !== 0) return;
40146
+ const along = (p3) => ((p3[0] - bx) * sx + (p3[1] - by) * sy) / length2;
40147
+ const [p2, q] = [along(a.leg.from), along(a.leg.to)];
40148
+ const lo = Math.max(0, Math.min(p2, q)), hi = Math.min(1, Math.max(p2, q));
40149
+ if (hi - lo <= 0) return;
40150
+ runs.push({ wire: j2, leg: l, from: [bx + lo * sx, by + lo * sy], to: [bx + hi * sx, by + hi * sy], under: i });
40151
+ });
40152
+ }
40153
+ }
40154
+ }
40058
40155
  const junctions = [...ends2.entries()].filter(([hole2, count]) => count + (pins.has(hole2) ? 1 : 0) >= 3).map(([hole2]) => hole2.split(",").map(Number));
40059
40156
  return {
40157
+ runs,
40060
40158
  hops: hops.map((hop) => ({ wire: hop.wire, leg: hop.leg, at: hop.at, over: hop.over, ...hop.under !== void 0 ? { under: hop.under } : {} })),
40061
40159
  junctions
40062
40160
  };
@@ -40483,11 +40581,13 @@ function roundedWireLine(points) {
40483
40581
  line.push(points[points.length - 1]);
40484
40582
  return line;
40485
40583
  }
40486
- function drawWires(painter, wires, hops, view) {
40584
+ function drawWires(painter, wires, hops, view, face = "all", only) {
40487
40585
  const hopsByWire = /* @__PURE__ */ new Map();
40488
40586
  for (const hop of hops) hopsByWire.set(hop.wire, [...hopsByWire.get(hop.wire) ?? [], hop]);
40489
40587
  wires.forEach((wire, index) => {
40490
40588
  if (isSolderPath(wire)) return;
40589
+ if (face !== "all" && isBottomWire(wire) !== (face === "bottom")) return;
40590
+ if (only && !only(index)) return;
40491
40591
  const line = wireLine(wire);
40492
40592
  const ends2 = [line[0], line[line.length - 1]];
40493
40593
  const width = widthOf(wire);
@@ -40585,7 +40685,7 @@ function drawWiresThroughParts(painter, wires) {
40585
40685
  if (isSolderPath(wire)) painter.line(wireLine(wire), { paint: SOLDER_COLOR, width: SOLDER_PATH_WIDTH, cap: "round", join: "round" });
40586
40686
  }
40587
40687
  for (const wire of wires) {
40588
- if (isSolderPath(wire)) continue;
40688
+ if (isSolderPath(wire) || isBottomWire(wire)) continue;
40589
40689
  painter.line(wireLine(wire), { paint: wire.color || DEFAULT_WIRE_COLOR, width: widthOf(wire), cap: "round", join: "round" });
40590
40690
  }
40591
40691
  });
@@ -41748,7 +41848,10 @@ function drawBoard(painter, project, view = PLAIN_VIEW) {
41748
41848
  drawLayer("under-board");
41749
41849
  drawHoles(painter, project, look, holesUnderChips(project), view);
41750
41850
  drawSolderPaths(painter, project.wires, view);
41751
- drawWires(painter, project.wires, wireLayout.hops, view);
41851
+ const isPicked = (index) => isSameItem(view.selected, { kind: "wire", index }) || isHovered(view, { kind: "wire", index });
41852
+ painter.group({ opacity: GHOST_BOTTOM_WIRES }, () => drawWires(painter, project.wires, wireLayout.hops, PLAIN_VIEW, "bottom", (index) => !isPicked(index)));
41853
+ drawWires(painter, project.wires, wireLayout.hops, view, "bottom", isPicked);
41854
+ drawWires(painter, project.wires, wireLayout.hops, view, "top");
41752
41855
  drawLayer("over-wires");
41753
41856
  drawWiresThroughParts(painter, project.wires);
41754
41857
  for (const part of parts) artistFor(part).drawPinMarks?.(painter, part.entry);
@@ -41759,6 +41862,7 @@ function drawBoard(painter, project, view = PLAIN_VIEW) {
41759
41862
  }
41760
41863
  var GHOST_PARTS = 0.18;
41761
41864
  var GHOST_WIRES = 0.4;
41865
+ var GHOST_BOTTOM_WIRES = 0.35;
41762
41866
  function drawSolderSide(painter, project, holeLabels) {
41763
41867
  const { width, height } = boardSizePx(project.board);
41764
41868
  const look = boardLookFor(project.board.type);
@@ -41778,9 +41882,10 @@ function drawSolderSide(painter, project, holeLabels) {
41778
41882
  }
41779
41883
  painter.stamp(look.hole, holes);
41780
41884
  painter.group({ opacity: GHOST_PARTS }, () => drawLayer("under-board"));
41781
- painter.group({ opacity: GHOST_WIRES }, () => drawWires(painter, project.wires, [], PLAIN_VIEW));
41885
+ painter.group({ opacity: GHOST_WIRES }, () => drawWires(painter, project.wires, [], PLAIN_VIEW, "top"));
41782
41886
  painter.group({ opacity: GHOST_PARTS }, () => drawLayer("over-wires"));
41783
41887
  for (const wire of project.wires) if (isSolderPath(wire)) drawSolderPath(painter, wire);
41888
+ drawWires(painter, project.wires, layoutProjectWires(project).hops, PLAIN_VIEW, "bottom");
41784
41889
  });
41785
41890
  if (holeLabels) drawHoleLabels(painter, project.board, width, height, true);
41786
41891
  if (project.board.type === "stripboard") drawCutMarks(painter, project.board.cuts, width);
@@ -42517,12 +42622,34 @@ function expectedNets(given, held) {
42517
42622
 
42518
42623
  // src/edit-ops.ts
42519
42624
  var wireEnd = union([array(number2().int()).length(2), string2()]).describe('A hole [column, row], or a pin by name: "U1.7", "U1.DISCH", "D1.K", "R2.1" (the hole that pin is in).');
42625
+ var wireSide = _enum2(["top", "bottom"]).optional().describe('Which face a jumper lies on: "top" (default) or "bottom", the solder side (format version 9). A bottom wire joins its end holes like any jumper but never crosses a top wire, so use it to take a long wire out of the way; it is shown faded in the top view. Not for solder paths.');
42520
42626
  var rotation2 = union([literal(0), literal(90), literal(180), literal(270)]);
42521
42627
  var wireSelector = union([number2().int().min(0), array(holeInput).length(2)]).describe("A wire by its index in wires, or by its two end holes [[c, r], [c, r]] (either way round).");
42628
+ var customPart = object({
42629
+ name: string2().describe('What it is, e.g. "HC-SR04", "BC337". Later add_part ops can place more of it by this name.'),
42630
+ shape: string2().optional().describe(`The id of a fixed-pin part from list_parts whose package this part comes in, e.g. "transistor" (TO-92) for a BC337 or "mosfet" (TO-220) for an IRLZ44N: its pins, outline and look, with this part's name and pin names. Any fixed-pin part but header-pins. Leave out for a body of your own with pins anywhere.`),
42631
+ pins: array(object({
42632
+ at: holeInput.optional().describe("Without shape: the pin's hole [column, row] within the body, from its top-left hole. With shape: leave out, the package decides."),
42633
+ label: string2().optional().describe('Its name, e.g. "VCC", "TRIG", "B". Wire to it by name ("M1.VCC").')
42634
+ })).optional().describe("In pin order, pin 1 first; pin 1 is the hole add_part's `at` places it by. Without shape: every pin with its `at`. With shape: just their names, in the package's pin order (get_part gives it), as many as it has pins."),
42635
+ cols: number2().int().min(1).optional().describe("Without shape: the body's width in holes. Default: just wide enough for its pins."),
42636
+ rows: number2().int().min(1).optional().describe("Without shape: the body's height in holes. Default: just tall enough for its pins."),
42637
+ refPrefix: string2().optional().describe(`Letters of its refs: "Q" makes Q1, Q2. Default: the package's, else "M".`),
42638
+ color: string2().optional().describe(`Without shape: the body's colour, "#rrggbb", e.g. a blue module board "#1d4ed8".`)
42639
+ });
42640
+ var customChip = object({
42641
+ name: string2().describe('What it is, e.g. "LM358", "ESP32 DevKit". Later add_part ops can place more of it by this name.'),
42642
+ pinsPerSide: number2().int().min(2).describe("Pins in each of its two rows."),
42643
+ width: number2().int().min(2).describe(`Columns from one pin row to the other, both included: 4 for a narrow (0.3") DIP, 7 for a wide (0.6") one; a dev board's row spacing in holes plus one.`),
42644
+ pins: array(string2()).optional().describe('Pin names in DIP order: pin 1 at the top of the left row (at rotation 0), down the left row, then up the right row, so the last pin is at the top right. "" for a pin without a name.'),
42645
+ board: boolean2().optional().describe("true: a dev board or module (drawn as a board, listed under Modules); else a DIP chip.")
42646
+ });
42522
42647
  var editOp = discriminatedUnion("op", [
42523
42648
  object({
42524
42649
  op: literal("add_part"),
42525
- part: string2().describe(`The part's id from list_parts ("resistor", "ne555", "header-pins"), or the name of one of the project's customIcs.`),
42650
+ part: string2().optional().describe('The part\'s id from list_parts ("resistor", "ne555", "header-pins"), or the name of a custom part or chip the project already has. Give this, `custom` or `chip`.'),
42651
+ custom: customPart.optional().describe("Instead of `part`, a new part of your own for one the catalog doesn't have, placed by `at` and `rotation`."),
42652
+ chip: customChip.optional().describe("Instead of `part`, a new dual-row chip or dev board of your own, placed by `at` (its top-left pin) and `rotation`."),
42526
42653
  ref: string2().optional().describe("Its reference designator. The next free one (R1, R2...) when left out."),
42527
42654
  from: holeInput.optional().describe("Two-lead parts: the hole of lead 1. On a polarized part get_part's leadLabels say which that is: K for a diode or LED, - for an electrolytic."),
42528
42655
  to: holeInput.optional().describe("Two-lead parts: the hole of lead 2."),
@@ -42556,7 +42683,8 @@ var editOp = discriminatedUnion("op", [
42556
42683
  path: array(wireEnd).min(2).optional().describe("Instead of from/to: holes (or pins) to run through in order, made into one wire per leg. Each corner is a wire end, so it joins whatever is in that hole. For corners that only bend, use from/to with via."),
42557
42684
  solder: boolean2().optional().describe("true: a solder path instead of a jumper wire, a trail of solder on the copper side, made as one path (a `path`'s corners and any `via` are its bends). Bare solder joins every hole it runs over, ends, bends and all, and every solder path it touches: run it only over holes it should connect. No color or width."),
42558
42685
  color: string2().optional(),
42559
- width: number2().positive().optional()
42686
+ width: number2().positive().optional(),
42687
+ side: wireSide
42560
42688
  }),
42561
42689
  object({
42562
42690
  op: literal("update_wire"),
@@ -42565,7 +42693,8 @@ var editOp = discriminatedUnion("op", [
42565
42693
  to: wireEnd.optional(),
42566
42694
  via: array(holeInput).optional().describe("Its bends, replacing the ones it has; [] makes it straight. Left out, its bends stay."),
42567
42695
  color: string2().optional(),
42568
- width: number2().positive().optional()
42696
+ width: number2().positive().optional(),
42697
+ side: wireSide
42569
42698
  }),
42570
42699
  object({
42571
42700
  op: literal("remove_wires"),
@@ -42736,10 +42865,22 @@ function pinsOf(project, refs) {
42736
42865
  return result;
42737
42866
  }
42738
42867
  function addPart(project, op, placed) {
42739
- const part = findPart(op.part);
42740
- const custom2 = part ? void 0 : project.customIcs.find((ic) => ic.name.toLowerCase() === op.part.trim().toLowerCase());
42741
- if (!part && !custom2) throw new OpError(`${noSuchPart(op.part)} Use list_parts to find one.`);
42742
- if (part?.kind === "standard-component") {
42868
+ const given = [op.part, op.custom, op.chip].filter((field) => field !== void 0).length;
42869
+ if (given !== 1) {
42870
+ throw new OpError("Give one of `part` (a catalog id, or the name of a custom part or chip the project has), `custom` (a new part of your own) or `chip` (a new chip or dev board of your own).");
42871
+ }
42872
+ if (op.custom) return placeCustomPart(project, op, makeCustomPart(project, op.custom), true, placed);
42873
+ if (op.chip) return placeChip(project, op, makeChip(project, op.chip), true, placed);
42874
+ const name = op.part;
42875
+ const part = findPart(name);
42876
+ if (!part) {
42877
+ const chip = findCustomChip(project, name);
42878
+ if (chip) return placeChip(project, op, chip, false, placed);
42879
+ const custom2 = findCustomPart(project, name);
42880
+ if (custom2) return placeCustomPart(project, op, structuredClone(custom2), false, placed);
42881
+ throw new OpError(`${noSuchPart(name)} Use list_parts to find one, or make it with \`custom\` or \`chip\`.`);
42882
+ }
42883
+ if (part.kind === "standard-component") {
42743
42884
  notFor(`a two-lead part (${part.id})`, op, ["at", "rotation", "rows", "cols"]);
42744
42885
  if (!op.from || !op.to) throw new OpError(`${part.id} is a two-lead part: give \`from\` and \`to\`, the holes of its two leads.`);
42745
42886
  checkOnBoard(project, op.from, "`from`");
@@ -42756,20 +42897,15 @@ function addPart(project, op, placed) {
42756
42897
  placed.add(ref2);
42757
42898
  return `Added ${ref2} (${part.name}${op.value ? ` ${op.value}` : ""}) from ${showHole(op.from)} to ${showHole(op.to)}.`;
42758
42899
  }
42759
- notFor("a part placed by `at`", op, ["from", "to", "color"]);
42760
- if (!op.at) throw new OpError("Give `at`: the hole of pin 1 (a chip's or pin block's top-left pin).");
42761
- checkOnBoard(project, op.at, "`at`");
42762
- const at = toGridPos(op.at);
42763
- const rotation3 = op.rotation ?? 0;
42764
- const turned = rotation3 ? `, turned ${rotation3}\xB0` : "";
42765
- if (part?.kind === "advanced-component") {
42900
+ const { at, turned } = placedBy(project, op);
42901
+ if (part.kind === "advanced-component") {
42766
42902
  if (!part.sizable) notFor(`${part.id} (not a pin block)`, op, ["rows", "cols"]);
42767
42903
  const ref2 = claimRef(project, op.ref, part.refPrefix);
42768
42904
  project.placedAdvancedComponents.push({
42769
42905
  ref: ref2,
42770
42906
  definitionId: part.id,
42771
42907
  at,
42772
- rotation: rotation3,
42908
+ rotation: op.rotation ?? 0,
42773
42909
  rows: op.rows ?? 1,
42774
42910
  cols: op.cols ?? 1,
42775
42911
  ...op.value ? { value: op.value } : {}
@@ -42779,24 +42915,167 @@ function addPart(project, op, placed) {
42779
42915
  }
42780
42916
  notFor("a chip", op, ["rows", "cols", "value"]);
42781
42917
  const ref = claimRef(project, op.ref, "U");
42782
- if (part?.kind === "ic") {
42783
- project.placedIcs.push(icEntry(part, at, rotation3, ref));
42918
+ project.placedIcs.push(icEntry(part, at, op.rotation ?? 0, ref));
42919
+ placed.add(ref);
42920
+ return `Added ${ref} (${part.name}) with its top-left pin at ${showHole(at)}${turned}.`;
42921
+ }
42922
+ function placedBy(project, op) {
42923
+ notFor("a part placed by `at`", op, ["from", "to", "color"]);
42924
+ if (!op.at) throw new OpError("Give `at`: the hole of pin 1 (a chip's or pin block's top-left pin).");
42925
+ checkOnBoard(project, op.at, "`at`");
42926
+ return { at: toGridPos(op.at), turned: op.rotation ? `, turned ${op.rotation}\xB0` : "" };
42927
+ }
42928
+ var REF_LETTERS = /^[A-Z]{1,4}$/;
42929
+ var MAX_NAME = 60;
42930
+ var MAX_PIN_NAME = 24;
42931
+ function findCustomPart(project, name) {
42932
+ const wanted = name.trim().toLowerCase();
42933
+ return project.placedAdvancedComponents.find((part) => part.custom?.name.toLowerCase() === wanted)?.custom;
42934
+ }
42935
+ function findCustomChip(project, name) {
42936
+ const wanted = name.trim().toLowerCase();
42937
+ return project.customIcs.find((ic) => ic.name.toLowerCase() === wanted);
42938
+ }
42939
+ function newPartName(given, what) {
42940
+ const name = given.trim();
42941
+ if (!name) throw new OpError(`\`${what}.name\` is empty: name the part, e.g. "BC337".`);
42942
+ if (name.length > MAX_NAME) throw new OpError(`\`${what}.name\` is longer than ${MAX_NAME} characters.`);
42943
+ const catalog = findPart(name);
42944
+ if (catalog) throw new OpError(`"${name}" is already the catalog's ${catalog.name} (id ${catalog.id}): place that with \`part\`, or give yours another name.`);
42945
+ return name;
42946
+ }
42947
+ function checkedPinName(label, i, what) {
42948
+ const name = label?.trim() ?? "";
42949
+ if (name.length > MAX_PIN_NAME) throw new OpError(`${what} pin ${i + 1}'s name is longer than ${MAX_PIN_NAME} characters.`);
42950
+ return name;
42951
+ }
42952
+ function makeCustomPart(project, custom2) {
42953
+ const name = newPartName(custom2.name, "custom");
42954
+ if (findCustomChip(project, name)) throw new OpError(`The project already has a custom chip named "${name}": give this part another name.`);
42955
+ const existing = findCustomPart(project, name);
42956
+ const refPrefix = custom2.refPrefix?.trim().toUpperCase();
42957
+ if (refPrefix !== void 0 && !REF_LETTERS.test(refPrefix)) throw new OpError("`custom.refPrefix` is 1 to 4 letters, such as M or Q.");
42958
+ const pins = custom2.pins ?? [];
42959
+ const labels = pins.map((pin, i) => checkedPinName(pin.label, i, "`custom.pins`:"));
42960
+ let spec;
42961
+ if (custom2.shape !== void 0) {
42962
+ const shape = customPartShape(custom2.shape);
42963
+ if (!shape) {
42964
+ const part = findPart(custom2.shape);
42965
+ throw new OpError(part ? `${part.id} can't be a custom part's \`shape\`: give a fixed-pin part from list_parts other than header-pins, such as "transistor" (TO-92) or "mosfet" (TO-220).` : `${noSuchPart(custom2.shape)} \`custom.shape\` is the id of a fixed-pin part from list_parts, such as "transistor" (TO-92) or "mosfet" (TO-220).`);
42966
+ }
42967
+ const holes = ["cols", "rows", "color"].filter((field) => custom2[field] !== void 0);
42968
+ if (pins.some((pin) => pin.at)) holes.push("pins[].at");
42969
+ if (holes.length) throw new OpError(`With \`shape\` the package decides the part's holes and look: leave out ${holes.map((f2) => `\`custom.${f2}\``).join(", ")}.`);
42970
+ if (labels.length > shape.pinOffsets.length) {
42971
+ throw new OpError(`${shape.name} has ${plural2(shape.pinOffsets.length, "pin")}, but \`custom.pins\` names ${labels.length}.`);
42972
+ }
42973
+ spec = shapedPartSpec(shape, { name, ...refPrefix ? { refPrefix } : {}, labels });
42784
42974
  } else {
42785
- const ic = custom2;
42786
- const sideways = rotation3 === 90 || rotation3 === 270;
42787
- project.placedIcs.push({
42788
- ref,
42789
- name: ic.name,
42790
- at,
42791
- rotation: rotation3,
42792
- widthPin: sideways ? ic.heightPin : ic.widthPin,
42793
- heightPin: sideways ? ic.widthPin : ic.heightPin,
42794
- pinDescription: { ...ic.pinDescription },
42795
- ...ic.category ? { category: ic.category } : {}
42796
- });
42975
+ if (!pins.length) {
42976
+ throw new OpError("`custom.pins` needs every pin's hole `at` within the body, pin 1 first. Or give `custom.shape` to take a catalog part's package.");
42977
+ }
42978
+ const holes = pins.map((pin, i) => {
42979
+ if (!pin.at) throw new OpError(`\`custom.pins[${i}]\` has no \`at\`: without \`shape\`, give each pin's hole within the body.`);
42980
+ if (pin.at[0] < 0 || pin.at[1] < 0) throw new OpError(`\`custom.pins[${i}].at\` ${showHole(pin.at)} is outside the body: holes count from its top-left one, [0, 0].`);
42981
+ return toGridPos(pin.at);
42982
+ });
42983
+ const cols = custom2.cols ?? Math.max(...holes.map((at) => at[0])) + 1;
42984
+ const rows = custom2.rows ?? Math.max(...holes.map((at) => at[1])) + 1;
42985
+ if (cols > MAX_CUSTOM_PART_SIDE || rows > MAX_CUSTOM_PART_SIDE) {
42986
+ throw new OpError(`The body is ${cols}\xD7${rows} holes; a custom part is at most ${MAX_CUSTOM_PART_SIDE} holes a side.`);
42987
+ }
42988
+ holes.forEach((at, i) => {
42989
+ if (at[0] >= cols || at[1] >= rows) throw new OpError(`\`custom.pins[${i}].at\` ${showHole(at)} is outside a body of ${cols}\xD7${rows} holes.`);
42990
+ const first = holes.findIndex((other) => sameHole(other, at));
42991
+ if (first < i) throw new OpError(`Pins ${first + 1} and ${i + 1} are both at ${showHole(at)}: each pin needs its own hole.`);
42992
+ });
42993
+ const color = custom2.color?.trim();
42994
+ spec = {
42995
+ name,
42996
+ ...refPrefix ? { refPrefix } : {},
42997
+ cols,
42998
+ rows,
42999
+ pins: holes.map((at, i) => ({ at, ...labels[i] ? { label: labels[i] } : {} })),
43000
+ ...color ? { color } : {}
43001
+ };
43002
+ }
43003
+ const read = readCustomPart(spec);
43004
+ if (!read) throw new OpError("That custom part can't be saved: check its pins and size.");
43005
+ if (existing && JSON.stringify({ ...existing, id: void 0 }) !== JSON.stringify({ ...read, id: void 0 })) {
43006
+ throw new OpError(`The board already has a different custom part named "${name}": place that one with \`part\`, or give this one another name.`);
42797
43007
  }
43008
+ return read;
43009
+ }
43010
+ function placeCustomPart(project, op, spec, isNew, placed) {
43011
+ notFor("a custom part", op, ["rows", "cols"]);
43012
+ const { at, turned } = placedBy(project, op);
43013
+ const ref = claimRef(project, op.ref, customPartDefinition(spec).refPrefix);
43014
+ project.placedAdvancedComponents.push({
43015
+ ref,
43016
+ definitionId: CUSTOM_PART_ID,
43017
+ at,
43018
+ rotation: op.rotation ?? 0,
43019
+ rows: 1,
43020
+ cols: 1,
43021
+ ...op.value ? { value: op.value } : {},
43022
+ custom: spec
43023
+ });
42798
43024
  placed.add(ref);
42799
- return `Added ${ref} (${part?.name ?? custom2.name}) with its top-left pin at ${showHole(at)}${turned}.`;
43025
+ const shape = customPartShape(spec.shape);
43026
+ const what = shape ? `in the ${shape.name} package` : `${spec.cols}\xD7${spec.rows} holes, ${plural2(spec.pins.length, "pin")}`;
43027
+ return `Added ${ref} (${spec.name}, ${isNew ? "a new custom part" : "custom"}, ${what}) with pin 1 at ${showHole(at)}${turned}.`;
43028
+ }
43029
+ function makeChip(project, chip) {
43030
+ const name = newPartName(chip.name, "chip");
43031
+ if (findCustomPart(project, name)) throw new OpError(`The board already has a custom part named "${name}": give this chip another name.`);
43032
+ const total = chip.pinsPerSide * 2;
43033
+ const names = chip.pins ?? [];
43034
+ if (names.length > total) throw new OpError(`A chip with ${chip.pinsPerSide} pins a side has ${total} pins, but \`chip.pins\` names ${names.length}.`);
43035
+ const pinDescription = {};
43036
+ names.forEach((label, i) => {
43037
+ const pin = checkedPinName(label, i, "`chip.pins`:");
43038
+ if (pin) pinDescription[i + 1] = pin;
43039
+ });
43040
+ const entry = {
43041
+ name,
43042
+ widthPin: chip.width,
43043
+ heightPin: chip.pinsPerSide,
43044
+ pinDescription,
43045
+ category: chip.board ? "modules.custom" : "ics.custom"
43046
+ };
43047
+ const existing = findCustomChip(project, name);
43048
+ if (existing) {
43049
+ const same = existing.widthPin === entry.widthPin && existing.heightPin === entry.heightPin && JSON.stringify(existing.pinDescription) === JSON.stringify(entry.pinDescription) && (existing.category ?? "ics.custom") === entry.category;
43050
+ if (!same) throw new OpError(`The project already has a different custom chip named "${name}": place that one with \`part\`, or give this one another name.`);
43051
+ return existing;
43052
+ }
43053
+ project.customIcs.push({ id: 1e3 + hashOf(JSON.stringify(entry)), ...entry });
43054
+ return project.customIcs[project.customIcs.length - 1];
43055
+ }
43056
+ function placeChip(project, op, chip, isNew, placed) {
43057
+ notFor("a chip", op, ["rows", "cols", "value"]);
43058
+ const { at, turned } = placedBy(project, op);
43059
+ const rotation3 = op.rotation ?? 0;
43060
+ const ref = claimRef(project, op.ref, "U");
43061
+ const sideways = rotation3 === 90 || rotation3 === 270;
43062
+ project.placedIcs.push({
43063
+ ref,
43064
+ name: chip.name,
43065
+ at,
43066
+ rotation: rotation3,
43067
+ widthPin: sideways ? chip.heightPin : chip.widthPin,
43068
+ heightPin: sideways ? chip.widthPin : chip.heightPin,
43069
+ pinDescription: { ...chip.pinDescription },
43070
+ ...chip.category ? { category: chip.category } : {}
43071
+ });
43072
+ placed.add(ref);
43073
+ return `Added ${ref} (${chip.name}${isNew ? ", a new custom chip" : ""}) with its top-left pin at ${showHole(at)}${turned}.`;
43074
+ }
43075
+ function hashOf(text2) {
43076
+ let hash2 = 2166136261;
43077
+ for (let i = 0; i < text2.length; i++) hash2 = Math.imul(hash2 ^ text2.charCodeAt(i), 16777619);
43078
+ return (hash2 >>> 0) % 1e9;
42800
43079
  }
42801
43080
  function updatePart(project, op, placed) {
42802
43081
  const found = findRef(project, op.ref);
@@ -42894,6 +43173,7 @@ function notFor(kind, op, fields) {
42894
43173
  const given = fields.filter((field) => op[field] !== void 0);
42895
43174
  if (given.length) throw new OpError(`${given.map((f2) => `\`${f2}\``).join(", ")} ${given.length === 1 ? "doesn't" : "don't"} apply to ${kind}.`);
42896
43175
  }
43176
+ var sideOf = (op) => op.side === "bottom" ? { side: "bottom" } : {};
42897
43177
  function addWire(project, op) {
42898
43178
  if (op.path && (op.from || op.to)) throw new OpError("Give either `path` or `from` and `to`, not both.");
42899
43179
  if (op.solder) return addSolderPath(project, op);
@@ -42910,7 +43190,8 @@ function addWire(project, op) {
42910
43190
  from: corners[i - 1].at,
42911
43191
  to: corners[i].at,
42912
43192
  ...op.color ? { color: op.color } : {},
42913
- ...op.width ? { width: op.width } : {}
43193
+ ...op.width ? { width: op.width } : {},
43194
+ ...sideOf(op)
42914
43195
  });
42915
43196
  }
42916
43197
  const made = corners.length - 1;
@@ -42924,13 +43205,15 @@ function addBentWire(project, op, fromEnd, toEnd, via) {
42924
43205
  to: to.at,
42925
43206
  ...withBends(project, from.at, to.at, via),
42926
43207
  ...op.color ? { color: op.color } : {},
42927
- ...op.width ? { width: op.width } : {}
43208
+ ...op.width ? { width: op.width } : {},
43209
+ ...sideOf(op)
42928
43210
  };
42929
43211
  project.wires.push(wire);
42930
43212
  return `Added wires[${project.wires.length - 1}] from ${from.said} to ${to.said}${bendsSaid(wire)}.`;
42931
43213
  }
42932
43214
  function addSolderPath(project, op) {
42933
43215
  if (op.color !== void 0 || op.width !== void 0) throw new OpError("A solder path is bare solder: it takes no `color` or `width`.");
43216
+ if (op.side !== void 0) throw new OpError("A solder path is always on the copper side: `side` is for jumper wires.");
42934
43217
  if (op.path && op.via) throw new OpError("Give a solder path's bends as `path` or as `via` with `from` and `to`, not both.");
42935
43218
  const given = op.path ?? (op.from && op.to ? [op.from, ...op.via ?? [], op.to] : void 0);
42936
43219
  if (!given) throw new OpError("A solder path needs `from` and `to`, or a `path` of two or more holes.");
@@ -42960,6 +43243,7 @@ function updateWire(project, op) {
42960
43243
  if (isSolderPath(project.wires[i]) && (op.color !== void 0 || op.width !== void 0)) {
42961
43244
  throw new OpError(`wires[${i}] is a solder path: it has no \`color\` or \`width\`.`);
42962
43245
  }
43246
+ if (isSolderPath(project.wires[i]) && op.side !== void 0) throw new OpError(`wires[${i}] is a solder path: it's always on the copper side.`);
42963
43247
  const updated = {
42964
43248
  ...project.wires[i],
42965
43249
  ...from ? { from: from.at } : {},
@@ -42968,6 +43252,8 @@ function updateWire(project, op) {
42968
43252
  ...op.width !== void 0 ? { width: op.width } : {}
42969
43253
  };
42970
43254
  if (!updated.color) delete updated.color;
43255
+ if (op.side === "top") delete updated.side;
43256
+ if (op.side === "bottom") updated.side = "bottom";
42971
43257
  if (sameHole(updated.from, updated.to)) throw new OpError(`The wire would start and end in hole ${showHole(updated.from)}.`);
42972
43258
  if (op.via !== void 0) {
42973
43259
  delete updated.via;
@@ -43139,6 +43425,10 @@ function validateProject(raw, expectNets) {
43139
43425
  const solder = (Array.isArray(data.wires) ? data.wires : []).flatMap((wire, i) => asEntry2(wire)?.kind === "solder" ? [wireName(i)] : []);
43140
43426
  if (solder.length) report.warn(`${joinList(solder)} ${solder.length === 1 ? "is" : "are"} "kind": "solder", which version ${data.version} files don't have, so ${solder.length === 1 ? "it was" : "they were"} read as jumper wires. Set "version": ${PROJECT_FILE_VERSION} to keep solder paths.`);
43141
43427
  }
43428
+ if (typeof data.version === "number" && data.version < 9) {
43429
+ const bottom = (Array.isArray(data.wires) ? data.wires : []).flatMap((wire, i) => asEntry2(wire)?.side === "bottom" ? [wireName(i)] : []);
43430
+ if (bottom.length) report.warn(`${joinList(bottom)} ${bottom.length === 1 ? "is" : "are"} "side": "bottom", which version ${data.version} files don't have, so ${bottom.length === 1 ? "it was" : "they were"} read as top wires. Set "version": ${PROJECT_FILE_VERSION} to keep the solder side.`);
43431
+ }
43142
43432
  const entries2 = readEntriesAlone(data, project);
43143
43433
  report.problems.push(...entries2.unreadable);
43144
43434
  const unnamed = skipped - entries2.unreadable.length;
@@ -43647,7 +43937,7 @@ function renderBoard(project, area) {
43647
43937
  out.push("", "Wires (index: ends, net):");
43648
43938
  for (const { wire, i } of shownWires) {
43649
43939
  const bends = wire.via?.length ? ` bending at ${wire.via.map(showHole).join(", ")}` : "";
43650
- out.push(`${i}: ${isSolderPath(wire) ? "solder path " : ""}${showHole(wire.from)}-${showHole(wire.to)}${bends}, ${netText(netOf.get(i))}`);
43940
+ out.push(`${i}: ${isSolderPath(wire) ? "solder path " : wire.side === "bottom" ? "solder side " : ""}${showHole(wire.from)}-${showHole(wire.to)}${bends}, ${netText(netOf.get(i))}`);
43651
43941
  }
43652
43942
  }
43653
43943
  return out.join("\n");
@@ -44678,7 +44968,7 @@ function registerShowBoardTool(server, DEFAULT_EDITOR_URL) {
44678
44968
  description: "The page show_board shows the board in.",
44679
44969
  // The picture is a data: image, and the page loads nothing else.
44680
44970
  _meta: { ui: { prefersBorder: false } }
44681
- }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: p, text: '<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=device-width, initial-scale=1">\n<title>Perfboard board</title>\n<style>\n :root { color-scheme: light dark; font-family: system-ui, sans-serif; font-size: 14px; }\n body { margin: 0; background: transparent; color: CanvasText; }\n figure { margin: 0; display: flex; flex-direction: column; gap: 8px; }\n img { display: block; width: 100%; height: auto; border-radius: 6px; }\n img:not([src]) { display: none; }\n figcaption { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; }\n #caption { opacity: 0.75; }\n button { font: inherit; padding: 6px 12px; border-radius: 6px; border: 1px solid #1f7a3a; background: #1f7a3a; color: #fff; cursor: pointer; }\n button:hover { background: #18602e; }\n button[hidden] { display: none; }\n</style>\n</head>\n<body>\n<figure>\n <img id="board" alt="">\n <figcaption>\n <span id="caption">Drawing the board\u2026</span>\n <button id="open" type="button" hidden>Open in Perfboard Designer</button>\n </figcaption>\n</figure>\n<script type="module">var f="2026-01-26",r=document.getElementById("board"),a=document.getElementById("caption"),u=document.getElementById("open"),i,g=1,s=new Map,o=t=>window.parent.postMessage({jsonrpc:"2.0",...t},"*");function m(t,e){let n=g++;return o({id:n,method:t,params:e}),new Promise(p=>s.set(n,p))}function h(t){let e=t._meta?.board;if(t.isError||!e){a.textContent=t.content?.find(n=>n.type==="text")?.text??"The board couldn\'t be shown.";return}r.src=`data:image/svg+xml;charset=utf-8,${encodeURIComponent(e.svg)}`,r.alt=e.caption,a.textContent=e.caption,i=e.link,u.hidden=!i}window.addEventListener("message",({source:t,data:e})=>{t!==window.parent||e?.jsonrpc!=="2.0"||(e.method===void 0?(s.get(e.id)?.(e.result),s.delete(e.id)):e.method==="ui/notifications/tool-result"?h(e.params??{}):e.id!==void 0&&o({id:e.id,result:{}}))});u.addEventListener("click",()=>{i&&m("ui/open-link",{url:i})});var c=0,l=0;function d(){let t=document.documentElement,e=Math.ceil(t.getBoundingClientRect().height),n=Math.ceil(window.innerWidth);n===c&&e===l||(c=n,l=e,o({method:"ui/notifications/size-changed",params:{width:n,height:e}}))}await m("ui/initialize",{protocolVersion:f,appInfo:{name:"Perfboard Designer board",version:"0.3.0"},appCapabilities:{}});o({method:"ui/notifications/initialized",params:{}});new ResizeObserver(()=>requestAnimationFrame(d)).observe(document.body);r.addEventListener("load",d);d();\n</script>\n</body>\n</html>\n', _meta: { ui: { prefersBorder: false } } }] }));
44971
+ }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: p, text: '<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=device-width, initial-scale=1">\n<title>Perfboard board</title>\n<style>\n :root { color-scheme: light dark; font-family: system-ui, sans-serif; font-size: 14px; }\n body { margin: 0; background: transparent; color: CanvasText; }\n figure { margin: 0; display: flex; flex-direction: column; gap: 8px; }\n img { display: block; width: 100%; height: auto; border-radius: 6px; }\n img:not([src]) { display: none; }\n figcaption { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; }\n #caption { opacity: 0.75; }\n button { font: inherit; padding: 6px 12px; border-radius: 6px; border: 1px solid #1f7a3a; background: #1f7a3a; color: #fff; cursor: pointer; }\n button:hover { background: #18602e; }\n button[hidden] { display: none; }\n</style>\n</head>\n<body>\n<figure>\n <img id="board" alt="">\n <figcaption>\n <span id="caption">Drawing the board\u2026</span>\n <button id="open" type="button" hidden>Open in Perfboard Designer</button>\n </figcaption>\n</figure>\n<script type="module">var f="2026-01-26",r=document.getElementById("board"),a=document.getElementById("caption"),u=document.getElementById("open"),i,g=1,s=new Map,o=t=>window.parent.postMessage({jsonrpc:"2.0",...t},"*");function m(t,e){let n=g++;return o({id:n,method:t,params:e}),new Promise(p=>s.set(n,p))}function h(t){let e=t._meta?.board;if(t.isError||!e){a.textContent=t.content?.find(n=>n.type==="text")?.text??"The board couldn\'t be shown.";return}r.src=`data:image/svg+xml;charset=utf-8,${encodeURIComponent(e.svg)}`,r.alt=e.caption,a.textContent=e.caption,i=e.link,u.hidden=!i}window.addEventListener("message",({source:t,data:e})=>{t!==window.parent||e?.jsonrpc!=="2.0"||(e.method===void 0?(s.get(e.id)?.(e.result),s.delete(e.id)):e.method==="ui/notifications/tool-result"?h(e.params??{}):e.id!==void 0&&o({id:e.id,result:{}}))});u.addEventListener("click",()=>{i&&m("ui/open-link",{url:i})});var c=0,l=0;function d(){let t=document.documentElement,e=Math.ceil(t.getBoundingClientRect().height),n=Math.ceil(window.innerWidth);n===c&&e===l||(c=n,l=e,o({method:"ui/notifications/size-changed",params:{width:n,height:e}}))}await m("ui/initialize",{protocolVersion:f,appInfo:{name:"Perfboard Designer board",version:"0.5.0"},appCapabilities:{}});o({method:"ui/notifications/initialized",params:{}});new ResizeObserver(()=>requestAnimationFrame(d)).observe(document.body);r.addEventListener("load",d);d();\n</script>\n</body>\n</html>\n', _meta: { ui: { prefersBorder: false } } }] }));
44682
44972
  K3(server, "show_board", {
44683
44973
  title: "Show board",
44684
44974
  description: "Shows the user a picture of the board right in the conversation, as the editor draws it, with a button that opens it in Perfboard Designer. Only in clients that show MCP Apps (e.g. Claude, ChatGPT); elsewhere the user sees nothing, so give them make_share_link's link too. The picture goes to the user, not to you: to look at the board yourself, use render_board.",
@@ -44721,12 +45011,12 @@ function registerResources(server) {
44721
45011
  title: "Project file format",
44722
45012
  description: "The project file format (version 8), including component identities and optional circuit requirements, as TypeScript types.",
44723
45013
  mimeType: "text/plain"
44724
- }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/plain", text: 'import {GridPos} from "./grid";\nimport type {CustomPartSpec} from "../parts/custom-parts";\nimport type {CircuitRequirements} from "./requirements";\n\n// The project file format, version 8. Positions are grid [column, row] pairs counted from the\n// top-left hole (column = left to right, row = top to bottom), not pixels, and only holes with a\n// note are listed. Older files are still read, see read-project-file.ts:\n// - version 7: the same, minus circuit requirements (`requirements`).\n// - version 6: the same as 7, minus part identities (a placed part\'s `instanceId`).\n// - version 5: the same as 6, minus custom parts (a fixed-pin part\'s `custom`).\n// - version 4: the same as 5, minus solder paths (a wire\'s `kind`).\n// - version 3: the same as 4, minus bent wires (a wire\'s `via`).\n// - version 2: the same as 3, minus the board type (always a perfboard) and part refs.\n// - version 1 (no `version` field): pixel coordinates, every hole listed, the whole IC catalog.\nexport const PROJECT_FILE_VERSION = 8;\n\n// A file says the oldest version that holds everything in it: 8 with requirements, else 6 with a\n// custom part, else 5 with a solder path, else 4 if a wire bends, else 3. So a board without them\n// still opens in editors and tools from before. Part identities (version 7) don\'t raise it: older\n// readers skip the field, and identities only matter to requirements, which are version 8.\nexport type FileVersion = 3 | 4 | 5 | 6 | typeof PROJECT_FILE_VERSION;\n\nexport function fileVersionFor(project: Pick<ProjectFile, "wires" | "placedAdvancedComponents" | "requirements">): FileVersion {\n if (project.requirements) return PROJECT_FILE_VERSION;\n if (project.placedAdvancedComponents.some(part => part.custom)) return 6;\n if (project.wires.some(wire => wire.kind === "solder")) return 5;\n return project.wires.some(wire => wire.via?.length) ? 4 : 3;\n}\n\nexport type Rotation = 0 | 90 | 180 | 270;\n\n// A perfboard has a separate copper pad around every hole: nothing is connected until it\'s wired.\n// A stripboard has long copper strips instead, each connecting a whole line of holes.\nexport type BoardType = "perfboard" | "stripboard";\n\n// Which way a stripboard\'s strips run. "horizontal": every hole in the same row is on one strip.\n// "vertical": every hole in the same column is.\nexport type StripDirection = "horizontal" | "vertical";\n\nexport interface SavedPerfboard {\n type: "perfboard";\n cols: number;\n rows: number;\n}\n\nexport interface SavedStripboard {\n type: "stripboard";\n cols: number;\n rows: number;\n strips: StripDirection;\n // Holes where the strip is cut (drilled through). A cut splits its strip in two, and the cut\n // hole itself connects to neither side: a lead in it is connected to nothing.\n cuts: GridPos[];\n}\n\nexport type SavedBoard = SavedPerfboard | SavedStripboard;\n\n// A hole with a note on it ("+9V", "GND", "to battery"). Purely a label: it says nothing about\n// what\'s connected. (Files from before notes were the only mark may give a hole a `color` too;\n// it\'s ignored.)\nexport interface SavedPad {\n at: GridPos;\n note: string;\n}\n\n// What a wire is made of (version 5):\n// - "jumper": an insulated jumper wire on the component side. It joins the holes at its two ends\n// and nothing else: not the holes it passes over, and not its corners.\n// - "solder": a solder path, a trail of solder bridging pad to pad on the copper side. Bare metal,\n// so it joins every hole it runs over: its ends, its corners and each hole along the way\n// (solderPathHoles() in wire-path.ts), and any solder path it touches. A cut hole on a\n// stripboard has no copper for it to join, so whatever is in one stays unconnected.\nexport type WireKind = "jumper" | "solder";\n\n// A wire: a jumper unless `kind` says otherwise.\nexport interface SavedWire {\n from: GridPos;\n to: GridPos;\n // Where it bends on its way from `from` to `to`, in order (version 4): it runs straight from\n // hole to hole through these. A jumper\'s corner is a bend over a hole, never a joint; a solder\n // path\'s joins that hole like the rest of its holes. Absent: straight.\n via?: GridPos[];\n // Absent: "jumper". Only solder paths say it.\n kind?: WireKind;\n // A jumper\'s insulation colour and thickness (drawing px). A solder path has neither.\n color?: string;\n width?: number;\n}\n\n// Every placed part has a `ref`: its reference designator (R1, C2, U1...), unique on the board\n// ignoring case. See part-refs.ts.\n\nexport interface SavedIc {\n instanceId?: string;\n ref: string;\n name: string;\n // Pin columns and rows as placed, i.e. already swapped by any 90/270 rotation.\n widthPin: number;\n heightPin: number;\n rotation: Rotation;\n pinDescription: Record<number, string>;\n // Top-left pin.\n at: GridPos;\n // The catalog category the chip was placed from; "modules\u2026" parts are drawn as boards. Absent in\n // files from before this was recorded.\n category?: string;\n}\n\nexport interface SavedStandardComponent {\n instanceId?: string;\n ref: string;\n definitionId: string;\n from: GridPos;\n to: GridPos;\n value?: string;\n color?: string;\n}\n\nexport interface SavedAdvancedComponent {\n instanceId?: string;\n ref: string;\n definitionId: string;\n // The anchor pin (the definition\'s pins[0]), or a grid-sizable block\'s top-left pin.\n at: GridPos;\n rotation: Rotation;\n rows: number;\n cols: number;\n value?: string;\n // A user-made part (version 6, definitionId "custom"): its whole definition, so the board needs\n // nothing else to draw it and know its pins (src/parts/custom-parts.ts): `name`, `cols` x `rows`\n // holes of body, its `pins` in order, each `at` a [column, row] within the body from its top-left\n // hole with an optional `label`, and optionally `refPrefix`, `color` (the body\'s) and `id` (its\n // entry in the editor\'s catalog). `at` above is pin 1\'s hole.\n custom?: CustomPartSpec;\n}\n\n// A user-made IC catalog entry. Loading a file adds these to the catalog (keyed by id) rather\n// than replacing it.\nexport interface SavedCustomIc {\n id?: number;\n name: string;\n widthPin: number;\n heightPin: number;\n pinDescription: Record<number, string>;\n // Where the part is listed in the Components panel; absent in files from before the catalog.\n category?: string;\n}\n\nexport interface ProjectFile {\n requirements?: CircuitRequirements;\n version: FileVersion;\n board: SavedBoard;\n pads: SavedPad[];\n wires: SavedWire[];\n // One array per kind, each in stacking order (see PartState.parts).\n placedIcs: SavedIc[];\n placedStandardComponents: SavedStandardComponent[];\n placedAdvancedComponents: SavedAdvancedComponent[];\n customIcs: SavedCustomIc[];\n}\n\nimport type { ProjectFile } from "./project-file";\nimport { partPins } from "./pin-positions";\nimport { computeNets, Net, NetPin } from "./nets";\n\nexport interface RequiredPin {\n componentId: string;\n pin: number;\n}\n\nexport interface RequiredComponent {\n id: string;\n ref: string;\n name: string;\n pins: { pin: number; label?: string }[];\n}\n\nexport interface RequiredNet {\n id: string;\n pins: RequiredPin[];\n}\n\nexport interface CircuitRequirements {\n validate: boolean;\n components: RequiredComponent[];\n nets: RequiredNet[];\n unused: RequiredPin[];\n}\n\nexport interface RequirementIssue {\n kind:\n | "missing-component"\n | "missing-pin"\n | "missing-connection"\n | "unexpected-connection";\n message: string;\n pins: RequiredPin[];\n}\n\nexport interface RequirementValidation {\n status: "disabled" | "incomplete" | "mismatch" | "match";\n issues: RequirementIssue[];\n unspecified: RequiredPin[];\n checked: number;\n total: number;\n}\n\n' }] }));
45014
+ }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/plain", text: 'import {GridPos} from "./grid";\nimport type {CustomPartSpec} from "../parts/custom-parts";\nimport type {CircuitRequirements} from "./requirements";\n\n// The project file format, version 9. Positions are grid [column, row] pairs counted from the\n// top-left hole (column = left to right, row = top to bottom), not pixels, and only holes with a\n// note are listed. Older files are still read, see read-project-file.ts:\n// - version 8: the same, minus wires on the solder side (a wire\'s `side`).\n// - version 7: the same as 8, minus circuit requirements (`requirements`).\n// - version 6: the same as 7, minus part identities (a placed part\'s `instanceId`).\n// - version 5: the same as 6, minus custom parts (a fixed-pin part\'s `custom`).\n// - version 4: the same as 5, minus solder paths (a wire\'s `kind`).\n// - version 3: the same as 4, minus bent wires (a wire\'s `via`).\n// - version 2: the same as 3, minus the board type (always a perfboard) and part refs.\n// - version 1 (no `version` field): pixel coordinates, every hole listed, the whole IC catalog.\nexport const PROJECT_FILE_VERSION = 9;\n\n// A file says the oldest version that holds everything in it: 9 with a wire on the solder side,\n// else 8 with requirements, else 6 with a\n// custom part, else 5 with a solder path, else 4 if a wire bends, else 3. So a board without them\n// still opens in editors and tools from before. Part identities (version 7) don\'t raise it: older\n// readers skip the field, and identities only matter to requirements, which are version 8.\nexport type FileVersion = 3 | 4 | 5 | 6 | 8 | typeof PROJECT_FILE_VERSION;\n\nexport function fileVersionFor(project: Pick<ProjectFile, "wires" | "placedAdvancedComponents" | "requirements">): FileVersion {\n if (project.wires.some(wire => wire.side === "bottom")) return PROJECT_FILE_VERSION;\n if (project.requirements) return 8;\n if (project.placedAdvancedComponents.some(part => part.custom)) return 6;\n if (project.wires.some(wire => wire.kind === "solder")) return 5;\n return project.wires.some(wire => wire.via?.length) ? 4 : 3;\n}\n\nexport type Rotation = 0 | 90 | 180 | 270;\n\n// A perfboard has a separate copper pad around every hole: nothing is connected until it\'s wired.\n// A stripboard has long copper strips instead, each connecting a whole line of holes.\nexport type BoardType = "perfboard" | "stripboard";\n\n// Which way a stripboard\'s strips run. "horizontal": every hole in the same row is on one strip.\n// "vertical": every hole in the same column is.\nexport type StripDirection = "horizontal" | "vertical";\n\nexport interface SavedPerfboard {\n type: "perfboard";\n cols: number;\n rows: number;\n}\n\nexport interface SavedStripboard {\n type: "stripboard";\n cols: number;\n rows: number;\n strips: StripDirection;\n // Holes where the strip is cut (drilled through). A cut splits its strip in two, and the cut\n // hole itself connects to neither side: a lead in it is connected to nothing.\n cuts: GridPos[];\n}\n\nexport type SavedBoard = SavedPerfboard | SavedStripboard;\n\n// A hole with a note on it ("+9V", "GND", "to battery"). Purely a label: it says nothing about\n// what\'s connected. (Files from before notes were the only mark may give a hole a `color` too;\n// it\'s ignored.)\nexport interface SavedPad {\n at: GridPos;\n note: string;\n}\n\n// What a wire is made of (version 5):\n// - "jumper": an insulated jumper wire on the component side. It joins the holes at its two ends\n// and nothing else: not the holes it passes over, and not its corners.\n// - "solder": a solder path, a trail of solder bridging pad to pad on the copper side. Bare metal,\n// so it joins every hole it runs over: its ends, its corners and each hole along the way\n// (solderPathHoles() in wire-path.ts), and any solder path it touches. A cut hole on a\n// stripboard has no copper for it to join, so whatever is in one stays unconnected.\nexport type WireKind = "jumper" | "solder";\n\n// A wire: a jumper unless `kind` says otherwise.\nexport interface SavedWire {\n from: GridPos;\n to: GridPos;\n // Where it bends on its way from `from` to `to`, in order (version 4): it runs straight from\n // hole to hole through these. A jumper\'s corner is a bend over a hole, never a joint; a solder\n // path\'s joins that hole like the rest of its holes. Absent: straight.\n via?: GridPos[];\n // Absent: "jumper". Only solder paths say it.\n kind?: WireKind;\n // A jumper\'s insulation colour and thickness (drawing px). A solder path has neither.\n color?: string;\n width?: number;\n // Which face of the board a jumper lies on (version 9). Absent: "top", the component side.\n // A "bottom" jumper is on the solder side: it joins the holes at its ends like any jumper (so a\n // wire or a pin in the same hole is on its net), but never goes over or under a top wire, since\n // they\'re on different faces. Only jumpers have it; a solder path is always on the copper side.\n side?: WireSide;\n}\n\nexport type WireSide = "top" | "bottom";\n\n// Every placed part has a `ref`: its reference designator (R1, C2, U1...), unique on the board\n// ignoring case. See part-refs.ts.\n\nexport interface SavedIc {\n instanceId?: string;\n ref: string;\n name: string;\n // Pin columns and rows as placed, i.e. already swapped by any 90/270 rotation.\n widthPin: number;\n heightPin: number;\n rotation: Rotation;\n pinDescription: Record<number, string>;\n // Top-left pin.\n at: GridPos;\n // The catalog category the chip was placed from; "modules\u2026" parts are drawn as boards. Absent in\n // files from before this was recorded.\n category?: string;\n}\n\nexport interface SavedStandardComponent {\n instanceId?: string;\n ref: string;\n definitionId: string;\n from: GridPos;\n to: GridPos;\n value?: string;\n color?: string;\n}\n\nexport interface SavedAdvancedComponent {\n instanceId?: string;\n ref: string;\n definitionId: string;\n // The anchor pin (the definition\'s pins[0]), or a grid-sizable block\'s top-left pin.\n at: GridPos;\n rotation: Rotation;\n rows: number;\n cols: number;\n value?: string;\n // A user-made part (version 6, definitionId "custom"): its whole definition, so the board needs\n // nothing else to draw it and know its pins (src/parts/custom-parts.ts): `name`, `cols` x `rows`\n // holes of body, its `pins` in order, each `at` a [column, row] within the body from its top-left\n // hole with an optional `label`, and optionally `refPrefix`, `color` (the body\'s) and `id` (its\n // entry in the editor\'s catalog). `at` above is pin 1\'s hole. With `shape`, the id of a built-in\n // fixed-pin part (e.g. "transistor", a TO-92), it\'s that part\'s package with its own name and pin\n // names: the package decides its pins\' holes (`cols`, `rows` and each `at` are written to match,\n // so a reader without shapes still finds the same pins) and how it\'s drawn; `color` is unused.\n custom?: CustomPartSpec;\n}\n\n// A user-made IC catalog entry. Loading a file adds these to the catalog (keyed by id) rather\n// than replacing it.\nexport interface SavedCustomIc {\n id?: number;\n name: string;\n widthPin: number;\n heightPin: number;\n pinDescription: Record<number, string>;\n // Where the part is listed in the Components panel; absent in files from before the catalog.\n category?: string;\n}\n\nexport interface ProjectFile {\n requirements?: CircuitRequirements;\n version: FileVersion;\n board: SavedBoard;\n pads: SavedPad[];\n wires: SavedWire[];\n // One array per kind, each in stacking order (see PartState.parts).\n placedIcs: SavedIc[];\n placedStandardComponents: SavedStandardComponent[];\n placedAdvancedComponents: SavedAdvancedComponent[];\n customIcs: SavedCustomIc[];\n}\n\nimport type { ProjectFile } from "./project-file";\nimport { partPins } from "./pin-positions";\nimport { computeNets, Net, NetPin } from "./nets";\n\nexport interface RequiredPin {\n componentId: string;\n pin: number;\n}\n\nexport interface RequiredComponent {\n id: string;\n ref: string;\n name: string;\n pins: { pin: number; label?: string }[];\n}\n\nexport interface RequiredNet {\n id: string;\n pins: RequiredPin[];\n}\n\nexport interface CircuitRequirements {\n validate: boolean;\n components: RequiredComponent[];\n nets: RequiredNet[];\n unused: RequiredPin[];\n}\n\nexport interface RequirementIssue {\n kind:\n | "missing-component"\n | "missing-pin"\n | "missing-connection"\n | "unexpected-connection";\n message: string;\n pins: RequiredPin[];\n}\n\nexport interface RequirementValidation {\n status: "disabled" | "incomplete" | "mismatch" | "match";\n issues: RequirementIssue[];\n unspecified: RequiredPin[];\n checked: number;\n total: number;\n}\n\n' }] }));
44725
45015
  server.registerResource("share-links", "perfboard://docs/share-links", {
44726
45016
  title: "Share links",
44727
45017
  description: "How a share link carries a project, and what happens when the user opens one.",
44728
45018
  mimeType: "text/markdown"
44729
- }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: '# Share links\n\nA share link opens a board in Perfboard Designer for whoever clicks it. The whole project travels\ninside the link itself, so there\'s no account, no upload and no server. In the editor, use\n**\u{1F517} Share** (or **File \u2192 Share Link...**) to make one. The same dialog can also make a **short\nlink** to a copy of the board stored on Perfboard Designer\'s server (`p`, below).\n\nThis page is the link format, written so that people and programs can make links too, including\nAI agents that design a board and hand the user a link to open it. The code is\n[`src/project-file/share-link.ts`](../src/project-file/share-link.ts). An agent that can use MCP\ncan skip most of this page: the [MCP server](../mcp/README.md) looks up parts, checks the project\nand makes the link for it.\n\n## What happens when a link is opened\n\n- The project is added to the receiver\'s projects (kept in their browser) as a **new project**,\n and opened. Whatever they had open stays as it was. The link is a snapshot: later changes by the\n sender aren\'t in it.\n- It\'s named after the link\'s `name`, or "Shared project". If a project with that name exists,\n the new one is numbered: "LED demo 2".\n- The link is then removed from the address bar, so reloading doesn\'t add the project again.\n- The project is checked like an imported file. Entries that can\'t be read are left out, and the\n user is told how many. A link that can\'t be read at all leaves everything untouched and says why.\n\n## Format\n\n```\nhttps://perfboarddesigner.com/app/#<fragment>\n```\n\nThe project goes in the URL **fragment** (after `#`), which browsers never send to a server. The\nfragment holds `key=value` parameters joined with `&`, like a query string:\n\n| Parameter | Value |\n| --- | --- |\n| `name` | Optional. The project\'s name, percent-encoded. |\n| `z` | The project file, compressed (see below). This is what the editor makes. |\n| `json` | The project file as plain JSON, percent-encoded. Must be the **last** parameter. |\n| `src` | The `https://` address of a project file hosted somewhere else, percent-encoded. |\n| `p` | The id of a project stored on Perfboard Designer\'s server: a short link. |\n\nUse exactly one of `z`, `json`, `src` and `p`. If several are present, `json` wins, then `z`, then\n`src`, then `p`.\n\n### `z`: compressed (shortest)\n\n1. Write the project file as JSON (minified is best).\n2. Compress its UTF-8 bytes with **raw DEFLATE** (no zlib or gzip header).\n3. Encode the result as **base64url** (`-` and `_` instead of `+` and `/`) with no `=` padding.\n\nThe reader is forgiving about what programs commonly produce instead. It also accepts zlib- or\ngzip-wrapped data, plain base64 with `+`, `/` and `=` padding, and line breaks in the base64 text.\n\nPython:\n\n```python\nimport base64, json, urllib.parse, zlib\n\ndef share_link(project: dict, name: str = "") -> str:\n data = json.dumps(project, separators=(",", ":")).encode("utf-8")\n deflate = zlib.compressobj(9, zlib.DEFLATED, -15) # -15: raw DEFLATE, no header\n z = base64.urlsafe_b64encode(deflate.compress(data) + deflate.flush()).rstrip(b"=").decode()\n name_param = f"name={urllib.parse.quote(name, safe=\'\')}&" if name else ""\n return f"https://perfboarddesigner.com/app/#{name_param}z={z}"\n```\n\nNode.js:\n\n```js\nconst zlib = require("zlib");\n\nfunction shareLink(project, name = "") {\n const z = zlib.deflateRawSync(Buffer.from(JSON.stringify(project))).toString("base64url");\n const nameParam = name ? `name=${encodeURIComponent(name)}&` : "";\n return `https://perfboarddesigner.com/app/#${nameParam}z=${z}`;\n}\n```\n\n### `json`: plain JSON (no tools needed)\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20demo&json=<percent-encoded project file JSON>\n```\n\nThis is for writers that can\'t compress, such as a language model writing the link directly.\nThese links are 3 to 7 times longer than `z` links. Rules:\n\n- `json` must be the **last parameter**: everything after `json=` is the project.\n- Percent-encode the JSON, as `encodeURIComponent` or Python\'s\n `urllib.parse.quote(text, safe="")` do. Encode at least spaces (`%20`), `#` (`%23`, which\n starts every color), `%` (`%25`) and `+` (`%2B`). A `+` is kept as a plus sign, never read as\n a space. Unencoded links may survive in a browser\'s address bar but are often broken by the chat\n apps and editors that turn text into links.\n- The reader tolerates a stray `%` that doesn\'t start an escape, such as a note saying `50%`.\n\n### `src`: a file hosted elsewhere\n\n```\nhttps://perfboarddesigner.com/app/#src=https%3A%2F%2Fexample.com%2Fmy-board.json\n```\n\n- The address must be `http://` or `https://`, and the site must allow other websites to read\n the file (CORS). Raw GitHub Gist and raw GitHub file addresses\n (`gist.githubusercontent.com`, `raw.githubusercontent.com`) do. A gist\'s normal page does not.\n- The user is asked before anything is downloaded, since fetching the file shows that site the\n visit.\n- Without a `name`, the project is named after the file (`my-board.json` \u2192 "my-board").\n- There\'s no size limit to worry about here, so this suits large boards and programs that can\n publish files.\n\n### `p`: a stored project (short link)\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20blinker&p=led-blinker\n```\n\n- The project is stored on Perfboard Designer\'s own server, `https://projects.perfboarddesigner.com`\n (below), and the link names it by its id. It\'s fetched without asking, since it\'s the site\'s own.\n- Without a `name`, the project is named after its id.\n- A stored project never changes, and it\'s deleted after a year unopened. Anyone with the link\n can open it. Unlike the other forms, it needs the server: the Share dialog offers the full link\n beside it, which works without one.\n\n### Stored projects\n\n`https://projects.perfboarddesigner.com` keeps projects for short links. Anyone can store one:\n\n| Request | Answer |\n| --- | --- |\n| `POST /projects` with `{"project": {\u2026}, "id": "led-blinker", "name": "LED blinker"}` (`id` and `name` optional) | `{id, link, file, image, png}`: the id it got, a short link, the file\'s address and its pictures\' |\n| `GET /<id>.json` | the project file |\n| `GET /<id>.png`, `GET /<id>.svg` | pictures of the board |\n\n- **Ids** are lowercase letters, digits and dashes, at most 40 characters, made from the wanted\n `id` or else the `name` (`"M\xE1gneses kapcsol\xF3!"` \u2192 `magneses-kapcsolo`). If another board has\n that id, a few characters of the board\'s SHA-256 are added (`led-blinker-08196a`); storing the\n same board under the same id again gives the same id back. With neither, the id is the hash.\n- Only valid project files are stored, as the editor reads them, up to 1 MB.\n- Every site may call it (CORS). There\'s no sign-in.\n- It\'s the [MCP server\'s](../mcp/README.md) Cloudflare Worker, which agents store through too.\n\n### Limits\n\n- The project file may be at most 5 MB once unpacked, and a board at most 500 holes on a side.\n- Links longer than about 8,000 characters may be cut off by some chat apps and mail clients; the\n Share dialog warns about these. For scale, the boards in [`examples/`](../examples) make `z`\n links of 0.8k to 2.7k characters.\n\n## The project file\n\nVersion 8 adds optional `requirements`: independent intended `nets` containing\n`{componentId, pin}` terminals, an explicit `unused` terminal list, component/pin snapshots\n(`components`) and an opt-in `validate` flag.\nAll terminals refer to stable component identities, not editable reference names. Snapshots\nkeep missing components/pins reportable; unspecified terminals are unchecked rather than unused.\nInvalid or overlapping requirement assignments reject the import instead of silently dropping\nconstraints. Board edits must preserve intended nets; adding a component extends the shared\ninventory without assigning new connections.\n\nVersion 7 adds a project-scoped `instanceId` to each placed part. Older readers skip it, so it\ndoesn\'t need a newer version on its own. A top-level `schematic` field, written by older editors,\nis ignored.\n\nA share link carries the same project file as **File \u2192 Save Project to File**. Every version\nopens, but write the oldest one that holds your board: version 8 with requirements,\nelse version 6 with a custom module, else 5\nwith a solder path, else 4 if a wire bends, else 3 (the same without any of them), which older\neditors open too. It\'s documented field by field in\n[`src/project-file/project-file.ts`](../src/project-file/project-file.ts). In short:\n\n- Positions are `[column, row]` grid holes counted from the **top-left hole**, both starting at 0.\n Neighbouring holes are 2.54 mm (0.1 in) apart.\n- `board`: `{"type": "perfboard", "cols": 12, "rows": 8}`, or a stripboard with\n `"strips": "horizontal" | "vertical"` and `"cuts": [[col, row], ...]`.\n- `pads`: holes with a `note` (like `+9V` or `GND`), as `{"at": [c, r], "note": "+9V"}`. Purely\n a label: it doesn\'t connect anything.\n- `wires`: `{"from": [c, r], "to": [c, r]}`, with optional `color` (`"#rrggbb"`) and `width`. A\n wire joins only its two end holes. With `"via": [[c, r], ...]` (version 4) it bends at those\n holes on its way, in order; a bend joins nothing. With `"kind": "solder"` (version 5) it\'s a\n solder path instead: a trail of solder on the copper side, with no `color` or `width`, that\n joins every hole it runs over (ends, bends and the holes between) and any solder path it\n touches.\n- `placedStandardComponents`: two-lead parts placed between two holes: `definitionId`, `from`,\n `to`, optional `value` (`"10k"`, `"100n"`) and `color` (LEDs). On polarized parts, `from` is\n an LED\'s cathode, a diode\'s anode and an electrolytic capacitor\'s \u2212 lead (`leadLabels` in the\n definitions).\n- `placedAdvancedComponents`: fixed-footprint parts: `definitionId`, the anchor pin `at`,\n `rotation` (0, 90, 180 or 270), `rows` and `cols` (1 except for sizable parts such as header\n pins), optional `value`. A user-made module has `"definitionId": "custom"` and carries the\n whole part in `custom` (version 6): `name`, optional `refPrefix`, its size in holes `cols` and\n `rows`, its `pins` in order as `{"at": [c, r], "label": "VCC"}` (holes within the body from its\n top-left hole; pin 1 is the anchor `at`) and an optional `color`.\n- `placedIcs`: DIP chips and dual-row modules: `name`, `at` (top-left pin), `widthPin` (columns\n including both pin rows, 4 for a 0.3" DIP), `heightPin` (pins per side), `rotation`, and\n `pinDescription` (`{"1": "GND", "2": "TRIG", ...}`, numbered counter-clockwise from pin 1).\n- `customIcs`: user-made catalog entries. `[]` is fine.\n- Every part should have a unique `ref` (R1, C2, U1...). Missing or duplicate refs are numbered\n automatically.\n\nThe reader is forgiving: empty lists can be left out, a file without `version` that has a `board`\nis read as version 8, and board entries it can\'t read are skipped (and counted) instead of failing the\nwhole project.\n\nThe `definitionId`s, with each part\'s pins, are in\n[`component-definitions.ts`](../src/parts/component-definitions.ts)\n(two-lead parts such as `resistor`, `ceramic-capacitor`, `electrolytic-capacitor`, `led` and\n`diode`) and\n[`advanced-component-definitions.ts`](../src/parts/advanced-component-definitions.ts)\n(fixed-footprint parts such as `transistor`, `potentiometer` and `header-pins`). Built-in chips are\nin [`ic-definitions.ts`](../src/parts/ic-definitions.ts), and footprints are described in\n[component-footprints.md](component-footprints.md). Check ids against these files: a part with an\nunknown `definitionId` isn\'t skipped, it stays on the board as an unrecognised part with an `X` ref.\n\n## Example\n\nA 9 V LED circuit on a 12 \xD7 8 perfboard:\n\n```json\n{\n "version": 3,\n "board": {"type": "perfboard", "cols": 12, "rows": 8},\n "pads": [{"at": [1, 1], "note": "+9V"}, {"at": [1, 6], "note": "GND"}],\n "wires": [\n {"from": [1, 1], "to": [3, 1], "color": "#ef4444"},\n {"from": [8, 4], "to": [8, 6]},\n {"from": [8, 6], "to": [1, 6]}\n ],\n "placedIcs": [],\n "placedStandardComponents": [\n {"ref": "R1", "definitionId": "resistor", "from": [3, 1], "to": [8, 1], "value": "470"},\n {"ref": "D1", "definitionId": "led", "from": [8, 2], "to": [8, 4], "color": "#22c55e"}\n ],\n "placedAdvancedComponents": [\n {"ref": "J1", "definitionId": "header-pins", "at": [0, 1], "rotation": 0, "rows": 6, "cols": 1}\n ],\n "customIcs": []\n}\n```\n\nAs a `json` link (the start of it):\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20demo&json=%7B%22version%22%3A3%2C%22board%22%3A%7B%22type%22%3A%22perfboard%22%2C...\n```\n' }] }));
45019
+ }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: '# Share links\n\nA share link opens a board in Perfboard Designer for whoever clicks it. The whole project travels\ninside the link itself, so there\'s no account, no upload and no server. In the editor, use\n**\u{1F517} Share** (or **File \u2192 Share Link...**) to make one. The same dialog can also make a **short\nlink** to a copy of the board stored on Perfboard Designer\'s server (`p`, below).\n\nThis page is the link format, written so that people and programs can make links too, including\nAI agents that design a board and hand the user a link to open it. The code is\n[`src/project-file/share-link.ts`](../src/project-file/share-link.ts). An agent that can use MCP\ncan skip most of this page: the [MCP server](../mcp/README.md) looks up parts, checks the project\nand makes the link for it.\n\n## What happens when a link is opened\n\n- The project is added to the receiver\'s projects (kept in their browser) as a **new project**,\n and opened. Whatever they had open stays as it was. The link is a snapshot: later changes by the\n sender aren\'t in it.\n- It\'s named after the link\'s `name`, or "Shared project". If a project with that name exists,\n the new one is numbered: "LED demo 2".\n- The link is then removed from the address bar, so reloading doesn\'t add the project again.\n- The project is checked like an imported file. Entries that can\'t be read are left out, and the\n user is told how many. A link that can\'t be read at all leaves everything untouched and says why.\n\n## Format\n\n```\nhttps://perfboarddesigner.com/app/#<fragment>\n```\n\nThe project goes in the URL **fragment** (after `#`), which browsers never send to a server. The\nfragment holds `key=value` parameters joined with `&`, like a query string:\n\n| Parameter | Value |\n| --- | --- |\n| `name` | Optional. The project\'s name, percent-encoded. |\n| `z` | The project file, compressed (see below). This is what the editor makes. |\n| `json` | The project file as plain JSON, percent-encoded. Must be the **last** parameter. |\n| `src` | The `https://` address of a project file hosted somewhere else, percent-encoded. |\n| `p` | The id of a project stored on Perfboard Designer\'s server: a short link. |\n\nUse exactly one of `z`, `json`, `src` and `p`. If several are present, `json` wins, then `z`, then\n`src`, then `p`.\n\n### `z`: compressed (shortest)\n\n1. Write the project file as JSON (minified is best).\n2. Compress its UTF-8 bytes with **raw DEFLATE** (no zlib or gzip header).\n3. Encode the result as **base64url** (`-` and `_` instead of `+` and `/`) with no `=` padding.\n\nThe reader is forgiving about what programs commonly produce instead. It also accepts zlib- or\ngzip-wrapped data, plain base64 with `+`, `/` and `=` padding, and line breaks in the base64 text.\n\nPython:\n\n```python\nimport base64, json, urllib.parse, zlib\n\ndef share_link(project: dict, name: str = "") -> str:\n data = json.dumps(project, separators=(",", ":")).encode("utf-8")\n deflate = zlib.compressobj(9, zlib.DEFLATED, -15) # -15: raw DEFLATE, no header\n z = base64.urlsafe_b64encode(deflate.compress(data) + deflate.flush()).rstrip(b"=").decode()\n name_param = f"name={urllib.parse.quote(name, safe=\'\')}&" if name else ""\n return f"https://perfboarddesigner.com/app/#{name_param}z={z}"\n```\n\nNode.js:\n\n```js\nconst zlib = require("zlib");\n\nfunction shareLink(project, name = "") {\n const z = zlib.deflateRawSync(Buffer.from(JSON.stringify(project))).toString("base64url");\n const nameParam = name ? `name=${encodeURIComponent(name)}&` : "";\n return `https://perfboarddesigner.com/app/#${nameParam}z=${z}`;\n}\n```\n\n### `json`: plain JSON (no tools needed)\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20demo&json=<percent-encoded project file JSON>\n```\n\nThis is for writers that can\'t compress, such as a language model writing the link directly.\nThese links are 3 to 7 times longer than `z` links. Rules:\n\n- `json` must be the **last parameter**: everything after `json=` is the project.\n- Percent-encode the JSON, as `encodeURIComponent` or Python\'s\n `urllib.parse.quote(text, safe="")` do. Encode at least spaces (`%20`), `#` (`%23`, which\n starts every color), `%` (`%25`) and `+` (`%2B`). A `+` is kept as a plus sign, never read as\n a space. Unencoded links may survive in a browser\'s address bar but are often broken by the chat\n apps and editors that turn text into links.\n- The reader tolerates a stray `%` that doesn\'t start an escape, such as a note saying `50%`.\n\n### `src`: a file hosted elsewhere\n\n```\nhttps://perfboarddesigner.com/app/#src=https%3A%2F%2Fexample.com%2Fmy-board.json\n```\n\n- The address must be `http://` or `https://`, and the site must allow other websites to read\n the file (CORS). Raw GitHub Gist and raw GitHub file addresses\n (`gist.githubusercontent.com`, `raw.githubusercontent.com`) do. A gist\'s normal page does not.\n- The user is asked before anything is downloaded, since fetching the file shows that site the\n visit.\n- Without a `name`, the project is named after the file (`my-board.json` \u2192 "my-board").\n- There\'s no size limit to worry about here, so this suits large boards and programs that can\n publish files.\n\n### `p`: a stored project (short link)\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20blinker&p=led-blinker\n```\n\n- The project is stored on Perfboard Designer\'s own server, `https://projects.perfboarddesigner.com`\n (below), and the link names it by its id. It\'s fetched without asking, since it\'s the site\'s own.\n- Without a `name`, the project is named after its id.\n- A stored project never changes, and it\'s deleted after a year unopened. Anyone with the link\n can open it. Unlike the other forms, it needs the server: the Share dialog offers the full link\n beside it, which works without one.\n\n### Stored projects\n\n`https://projects.perfboarddesigner.com` keeps projects for short links. Anyone can store one:\n\n| Request | Answer |\n| --- | --- |\n| `POST /projects` with `{"project": {\u2026}, "id": "led-blinker", "name": "LED blinker"}` (`id` and `name` optional) | `{id, link, file, image, png}`: the id it got, a short link, the file\'s address and its pictures\' |\n| `GET /<id>.json` | the project file |\n| `GET /<id>.png`, `GET /<id>.svg` | pictures of the board |\n\n- **Ids** are lowercase letters, digits and dashes, at most 40 characters, made from the wanted\n `id` or else the `name` (`"M\xE1gneses kapcsol\xF3!"` \u2192 `magneses-kapcsolo`). If another board has\n that id, a few characters of the board\'s SHA-256 are added (`led-blinker-08196a`); storing the\n same board under the same id again gives the same id back. With neither, the id is the hash.\n- Only valid project files are stored, as the editor reads them, up to 1 MB.\n- Every site may call it (CORS). There\'s no sign-in.\n- It\'s the [MCP server\'s](../mcp/README.md) Cloudflare Worker, which agents store through too.\n\n### Limits\n\n- The project file may be at most 5 MB once unpacked, and a board at most 500 holes on a side.\n- Links longer than about 8,000 characters may be cut off by some chat apps and mail clients; the\n Share dialog warns about these. For scale, the boards in [`examples/`](../examples) make `z`\n links of 0.8k to 2.7k characters.\n\n## The project file\n\nVersion 8 adds optional `requirements`: independent intended `nets` containing\n`{componentId, pin}` terminals, an explicit `unused` terminal list, component/pin snapshots\n(`components`) and an opt-in `validate` flag.\nAll terminals refer to stable component identities, not editable reference names. Snapshots\nkeep missing components/pins reportable; unspecified terminals are unchecked rather than unused.\nInvalid or overlapping requirement assignments reject the import instead of silently dropping\nconstraints. Board edits must preserve intended nets; adding a component extends the shared\ninventory without assigning new connections.\n\nVersion 7 adds a project-scoped `instanceId` to each placed part. Older readers skip it, so it\ndoesn\'t need a newer version on its own. A top-level `schematic` field, written by older editors,\nis ignored.\n\nA share link carries the same project file as **File \u2192 Save Project to File**. Every version\nopens, but write the oldest one that holds your board: version 9 with a wire on the solder side,\nelse version 8 with requirements, else version 6 with a custom module, else 5\nwith a solder path, else 4 if a wire bends, else 3 (the same without any of them), which older\neditors open too. It\'s documented field by field in\n[`src/project-file/project-file.ts`](../src/project-file/project-file.ts). In short:\n\n- Positions are `[column, row]` grid holes counted from the **top-left hole**, both starting at 0.\n Neighbouring holes are 2.54 mm (0.1 in) apart.\n- `board`: `{"type": "perfboard", "cols": 12, "rows": 8}`, or a stripboard with\n `"strips": "horizontal" | "vertical"` and `"cuts": [[col, row], ...]`.\n- `pads`: holes with a `note` (like `+9V` or `GND`), as `{"at": [c, r], "note": "+9V"}`. Purely\n a label: it doesn\'t connect anything.\n- `wires`: `{"from": [c, r], "to": [c, r]}`, with optional `color` (`"#rrggbb"`) and `width`. A\n wire joins only its two end holes. With `"via": [[c, r], ...]` (version 4) it bends at those\n holes on its way, in order; a bend joins nothing. With `"kind": "solder"` (version 5) it\'s a\n solder path instead: a trail of solder on the copper side, with no `color` or `width`, that\n joins every hole it runs over (ends, bends and the holes between) and any solder path it\n touches. With `"side": "bottom"` (version 9) a jumper lies on the solder side of the board: it\n joins its end holes like any jumper (so it shares a net with a pin or another wire\'s end in the\n same hole) but never crosses a top wire. Absent: the top. A solder path takes no `side`.\n- `placedStandardComponents`: two-lead parts placed between two holes: `definitionId`, `from`,\n `to`, optional `value` (`"10k"`, `"100n"`) and `color` (LEDs). On polarized parts, `from` is\n an LED\'s cathode, a diode\'s anode and an electrolytic capacitor\'s \u2212 lead (`leadLabels` in the\n definitions).\n- `placedAdvancedComponents`: fixed-footprint parts: `definitionId`, the anchor pin `at`,\n `rotation` (0, 90, 180 or 270), `rows` and `cols` (1 except for sizable parts such as header\n pins), optional `value`. A user-made module has `"definitionId": "custom"` and carries the\n whole part in `custom` (version 6): `name`, optional `refPrefix`, its size in holes `cols` and\n `rows`, its `pins` in order as `{"at": [c, r], "label": "VCC"}` (holes within the body from its\n top-left hole; pin 1 is the anchor `at`) and an optional `color`. With `"shape"`, the id of a\n built-in fixed-pin part (e.g. `"transistor"` for a TO-92), it\'s that package with its own `name`\n and pin names (`pins` in the package\'s pin order, each `{"label": "B"}`): the package decides its\n holes, and `cols`, `rows` and each `at` are written to match it.\n- `placedIcs`: DIP chips and dual-row modules: `name`, `at` (top-left pin), `widthPin` (columns\n including both pin rows, 4 for a 0.3" DIP), `heightPin` (pins per side), `rotation`, and\n `pinDescription` (`{"1": "GND", "2": "TRIG", ...}`, numbered counter-clockwise from pin 1).\n- `customIcs`: user-made catalog entries. `[]` is fine.\n- Every part should have a unique `ref` (R1, C2, U1...). Missing or duplicate refs are numbered\n automatically.\n\nThe reader is forgiving: empty lists can be left out, a file without `version` that has a `board`\nis read as version 9, and board entries it can\'t read are skipped (and counted) instead of failing the\nwhole project.\n\nThe `definitionId`s, with each part\'s pins, are in\n[`component-definitions.ts`](../src/parts/component-definitions.ts)\n(two-lead parts such as `resistor`, `ceramic-capacitor`, `electrolytic-capacitor`, `led` and\n`diode`) and\n[`advanced-component-definitions.ts`](../src/parts/advanced-component-definitions.ts)\n(fixed-footprint parts such as `transistor`, `potentiometer` and `header-pins`). Built-in chips are\nin [`ic-definitions.ts`](../src/parts/ic-definitions.ts), and footprints are described in\n[component-footprints.md](component-footprints.md). Check ids against these files: a part with an\nunknown `definitionId` isn\'t skipped, it stays on the board as an unrecognised part with an `X` ref.\n\n## Example\n\nA 9 V LED circuit on a 12 \xD7 8 perfboard:\n\n```json\n{\n "version": 3,\n "board": {"type": "perfboard", "cols": 12, "rows": 8},\n "pads": [{"at": [1, 1], "note": "+9V"}, {"at": [1, 6], "note": "GND"}],\n "wires": [\n {"from": [1, 1], "to": [3, 1], "color": "#ef4444"},\n {"from": [8, 4], "to": [8, 6]},\n {"from": [8, 6], "to": [1, 6]}\n ],\n "placedIcs": [],\n "placedStandardComponents": [\n {"ref": "R1", "definitionId": "resistor", "from": [3, 1], "to": [8, 1], "value": "470"},\n {"ref": "D1", "definitionId": "led", "from": [8, 2], "to": [8, 4], "color": "#22c55e"}\n ],\n "placedAdvancedComponents": [\n {"ref": "J1", "definitionId": "header-pins", "at": [0, 1], "rotation": 0, "rows": 6, "cols": 1}\n ],\n "customIcs": []\n}\n```\n\nAs a `json` link (the start of it):\n\n```\nhttps://perfboarddesigner.com/app/#name=LED%20demo&json=%7B%22version%22%3A3%2C%22board%22%3A%7B%22type%22%3A%22perfboard%22%2C...\n```\n' }] }));
44730
45020
  server.registerResource("parts", "perfboard://parts", {
44731
45021
  title: "Parts catalog",
44732
45022
  description: "Every part a project can place, with pins and pin labels, as JSON.",
@@ -44743,7 +45033,7 @@ function registerResources(server) {
44743
45033
 
44744
45034
  // src/create-server.ts
44745
45035
  function createServer({ editorUrl, imageUrl: imageUrl2, storage }) {
44746
- const server = new McpServer({ name: "perfboard-designer", version: "0.3.0" }, { instructions: INSTRUCTIONS });
45036
+ const server = new McpServer({ name: "perfboard-designer", version: "0.5.0" }, { instructions: INSTRUCTIONS });
44747
45037
  registerCatalogTools(server);
44748
45038
  registerProjectTools(server);
44749
45039
  registerBoardTools(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "perfboard-designer-mcp",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "MCP server for Perfboard Designer: lets AI agents look up parts, check perfboard and stripboard layouts, and hand back a link that opens the board in the editor.",
5
5
  "license": "ISC",
6
6
  "mcpName": "com.perfboarddesigner/mcp",