perfboard-designer-mcp 0.4.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.
- package/README.md +1 -0
- package/dist/server.js +68 -18
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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
|
|
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
|
|
@@ -38227,9 +38229,10 @@ function holesAlong(px) {
|
|
|
38227
38229
|
init_define_COMPONENT_ICONS();
|
|
38228
38230
|
init_define_EXAMPLE_PROJECTS();
|
|
38229
38231
|
init_define_PNG_FONTS();
|
|
38230
|
-
var PROJECT_FILE_VERSION =
|
|
38232
|
+
var PROJECT_FILE_VERSION = 9;
|
|
38231
38233
|
function fileVersionFor(project) {
|
|
38232
|
-
if (project.
|
|
38234
|
+
if (project.wires.some((wire) => wire.side === "bottom")) return PROJECT_FILE_VERSION;
|
|
38235
|
+
if (project.requirements) return 8;
|
|
38233
38236
|
if (project.placedAdvancedComponents.some((part) => part.custom)) return 6;
|
|
38234
38237
|
if (project.wires.some((wire) => wire.kind === "solder")) return 5;
|
|
38235
38238
|
return project.wires.some((wire) => wire.via?.length) ? 4 : 3;
|
|
@@ -38242,6 +38245,9 @@ init_define_PNG_FONTS();
|
|
|
38242
38245
|
function isSolderPath(wire) {
|
|
38243
38246
|
return wire.kind === "solder";
|
|
38244
38247
|
}
|
|
38248
|
+
function isBottomWire(wire) {
|
|
38249
|
+
return wire.side === "bottom";
|
|
38250
|
+
}
|
|
38245
38251
|
function wirePoints(wire) {
|
|
38246
38252
|
return [wire.from, ...wire.via ?? [], wire.to];
|
|
38247
38253
|
}
|
|
@@ -39929,7 +39935,8 @@ function readGridFile(data, version2) {
|
|
|
39929
39935
|
to,
|
|
39930
39936
|
...via.length ? { via } : {},
|
|
39931
39937
|
...optional2("color", text(entry.color)),
|
|
39932
|
-
...optional2("width", positiveNumber(entry.width))
|
|
39938
|
+
...optional2("width", positiveNumber(entry.width)),
|
|
39939
|
+
...version2 >= 9 && entry.side === "bottom" ? { side: "bottom" } : {}
|
|
39933
39940
|
};
|
|
39934
39941
|
});
|
|
39935
39942
|
const placedIcs = r2.list(data.placedIcs, (entry) => {
|
|
@@ -40051,7 +40058,7 @@ function readProjectFile(raw) {
|
|
|
40051
40058
|
const data = asEntry(raw);
|
|
40052
40059
|
if (!data) throw new ProjectFileError(NOT_A_PROJECT);
|
|
40053
40060
|
if (data.version === void 0) return asEntry(data.board) ? readGridFile(data, PROJECT_FILE_VERSION) : readV1(data);
|
|
40054
|
-
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);
|
|
40055
40062
|
if (typeof data.version === "number" && data.version > PROJECT_FILE_VERSION) {
|
|
40056
40063
|
throw new ProjectFileError(
|
|
40057
40064
|
"This project was saved by a newer version of Perfboard Designer. Reload the page to get the latest version, then open it again."
|
|
@@ -40110,6 +40117,7 @@ function layoutWires(wires, pinHoles) {
|
|
|
40110
40117
|
for (let i = 0; i < wires.length; i++) {
|
|
40111
40118
|
const endsOfI = /* @__PURE__ */ new Set([key3(wires[i].from), key3(wires[i].to)]);
|
|
40112
40119
|
for (let j2 = i + 1; j2 < wires.length; j2++) {
|
|
40120
|
+
if (isBottomWire(wires[i]) !== isBottomWire(wires[j2])) continue;
|
|
40113
40121
|
const isEnd = (at) => endsOfI.has(key3(at)) || key3(at) === key3(wires[j2].from) || key3(at) === key3(wires[j2].to);
|
|
40114
40122
|
const seen = /* @__PURE__ */ new Set();
|
|
40115
40123
|
for (const a of legs[i]) {
|
|
@@ -40124,8 +40132,29 @@ function layoutWires(wires, pinHoles) {
|
|
|
40124
40132
|
}
|
|
40125
40133
|
}
|
|
40126
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
|
+
}
|
|
40127
40155
|
const junctions = [...ends2.entries()].filter(([hole2, count]) => count + (pins.has(hole2) ? 1 : 0) >= 3).map(([hole2]) => hole2.split(",").map(Number));
|
|
40128
40156
|
return {
|
|
40157
|
+
runs,
|
|
40129
40158
|
hops: hops.map((hop) => ({ wire: hop.wire, leg: hop.leg, at: hop.at, over: hop.over, ...hop.under !== void 0 ? { under: hop.under } : {} })),
|
|
40130
40159
|
junctions
|
|
40131
40160
|
};
|
|
@@ -40552,11 +40581,13 @@ function roundedWireLine(points) {
|
|
|
40552
40581
|
line.push(points[points.length - 1]);
|
|
40553
40582
|
return line;
|
|
40554
40583
|
}
|
|
40555
|
-
function drawWires(painter, wires, hops, view) {
|
|
40584
|
+
function drawWires(painter, wires, hops, view, face = "all", only) {
|
|
40556
40585
|
const hopsByWire = /* @__PURE__ */ new Map();
|
|
40557
40586
|
for (const hop of hops) hopsByWire.set(hop.wire, [...hopsByWire.get(hop.wire) ?? [], hop]);
|
|
40558
40587
|
wires.forEach((wire, index) => {
|
|
40559
40588
|
if (isSolderPath(wire)) return;
|
|
40589
|
+
if (face !== "all" && isBottomWire(wire) !== (face === "bottom")) return;
|
|
40590
|
+
if (only && !only(index)) return;
|
|
40560
40591
|
const line = wireLine(wire);
|
|
40561
40592
|
const ends2 = [line[0], line[line.length - 1]];
|
|
40562
40593
|
const width = widthOf(wire);
|
|
@@ -40654,7 +40685,7 @@ function drawWiresThroughParts(painter, wires) {
|
|
|
40654
40685
|
if (isSolderPath(wire)) painter.line(wireLine(wire), { paint: SOLDER_COLOR, width: SOLDER_PATH_WIDTH, cap: "round", join: "round" });
|
|
40655
40686
|
}
|
|
40656
40687
|
for (const wire of wires) {
|
|
40657
|
-
if (isSolderPath(wire)) continue;
|
|
40688
|
+
if (isSolderPath(wire) || isBottomWire(wire)) continue;
|
|
40658
40689
|
painter.line(wireLine(wire), { paint: wire.color || DEFAULT_WIRE_COLOR, width: widthOf(wire), cap: "round", join: "round" });
|
|
40659
40690
|
}
|
|
40660
40691
|
});
|
|
@@ -41817,7 +41848,10 @@ function drawBoard(painter, project, view = PLAIN_VIEW) {
|
|
|
41817
41848
|
drawLayer("under-board");
|
|
41818
41849
|
drawHoles(painter, project, look, holesUnderChips(project), view);
|
|
41819
41850
|
drawSolderPaths(painter, project.wires, view);
|
|
41820
|
-
|
|
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");
|
|
41821
41855
|
drawLayer("over-wires");
|
|
41822
41856
|
drawWiresThroughParts(painter, project.wires);
|
|
41823
41857
|
for (const part of parts) artistFor(part).drawPinMarks?.(painter, part.entry);
|
|
@@ -41828,6 +41862,7 @@ function drawBoard(painter, project, view = PLAIN_VIEW) {
|
|
|
41828
41862
|
}
|
|
41829
41863
|
var GHOST_PARTS = 0.18;
|
|
41830
41864
|
var GHOST_WIRES = 0.4;
|
|
41865
|
+
var GHOST_BOTTOM_WIRES = 0.35;
|
|
41831
41866
|
function drawSolderSide(painter, project, holeLabels) {
|
|
41832
41867
|
const { width, height } = boardSizePx(project.board);
|
|
41833
41868
|
const look = boardLookFor(project.board.type);
|
|
@@ -41847,9 +41882,10 @@ function drawSolderSide(painter, project, holeLabels) {
|
|
|
41847
41882
|
}
|
|
41848
41883
|
painter.stamp(look.hole, holes);
|
|
41849
41884
|
painter.group({ opacity: GHOST_PARTS }, () => drawLayer("under-board"));
|
|
41850
|
-
painter.group({ opacity: GHOST_WIRES }, () => drawWires(painter, project.wires, [], PLAIN_VIEW));
|
|
41885
|
+
painter.group({ opacity: GHOST_WIRES }, () => drawWires(painter, project.wires, [], PLAIN_VIEW, "top"));
|
|
41851
41886
|
painter.group({ opacity: GHOST_PARTS }, () => drawLayer("over-wires"));
|
|
41852
41887
|
for (const wire of project.wires) if (isSolderPath(wire)) drawSolderPath(painter, wire);
|
|
41888
|
+
drawWires(painter, project.wires, layoutProjectWires(project).hops, PLAIN_VIEW, "bottom");
|
|
41853
41889
|
});
|
|
41854
41890
|
if (holeLabels) drawHoleLabels(painter, project.board, width, height, true);
|
|
41855
41891
|
if (project.board.type === "stripboard") drawCutMarks(painter, project.board.cuts, width);
|
|
@@ -42586,6 +42622,7 @@ function expectedNets(given, held) {
|
|
|
42586
42622
|
|
|
42587
42623
|
// src/edit-ops.ts
|
|
42588
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.');
|
|
42589
42626
|
var rotation2 = union([literal(0), literal(90), literal(180), literal(270)]);
|
|
42590
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).");
|
|
42591
42628
|
var customPart = object({
|
|
@@ -42646,7 +42683,8 @@ var editOp = discriminatedUnion("op", [
|
|
|
42646
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."),
|
|
42647
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."),
|
|
42648
42685
|
color: string2().optional(),
|
|
42649
|
-
width: number2().positive().optional()
|
|
42686
|
+
width: number2().positive().optional(),
|
|
42687
|
+
side: wireSide
|
|
42650
42688
|
}),
|
|
42651
42689
|
object({
|
|
42652
42690
|
op: literal("update_wire"),
|
|
@@ -42655,7 +42693,8 @@ var editOp = discriminatedUnion("op", [
|
|
|
42655
42693
|
to: wireEnd.optional(),
|
|
42656
42694
|
via: array(holeInput).optional().describe("Its bends, replacing the ones it has; [] makes it straight. Left out, its bends stay."),
|
|
42657
42695
|
color: string2().optional(),
|
|
42658
|
-
width: number2().positive().optional()
|
|
42696
|
+
width: number2().positive().optional(),
|
|
42697
|
+
side: wireSide
|
|
42659
42698
|
}),
|
|
42660
42699
|
object({
|
|
42661
42700
|
op: literal("remove_wires"),
|
|
@@ -43134,6 +43173,7 @@ function notFor(kind, op, fields) {
|
|
|
43134
43173
|
const given = fields.filter((field) => op[field] !== void 0);
|
|
43135
43174
|
if (given.length) throw new OpError(`${given.map((f2) => `\`${f2}\``).join(", ")} ${given.length === 1 ? "doesn't" : "don't"} apply to ${kind}.`);
|
|
43136
43175
|
}
|
|
43176
|
+
var sideOf = (op) => op.side === "bottom" ? { side: "bottom" } : {};
|
|
43137
43177
|
function addWire(project, op) {
|
|
43138
43178
|
if (op.path && (op.from || op.to)) throw new OpError("Give either `path` or `from` and `to`, not both.");
|
|
43139
43179
|
if (op.solder) return addSolderPath(project, op);
|
|
@@ -43150,7 +43190,8 @@ function addWire(project, op) {
|
|
|
43150
43190
|
from: corners[i - 1].at,
|
|
43151
43191
|
to: corners[i].at,
|
|
43152
43192
|
...op.color ? { color: op.color } : {},
|
|
43153
|
-
...op.width ? { width: op.width } : {}
|
|
43193
|
+
...op.width ? { width: op.width } : {},
|
|
43194
|
+
...sideOf(op)
|
|
43154
43195
|
});
|
|
43155
43196
|
}
|
|
43156
43197
|
const made = corners.length - 1;
|
|
@@ -43164,13 +43205,15 @@ function addBentWire(project, op, fromEnd, toEnd, via) {
|
|
|
43164
43205
|
to: to.at,
|
|
43165
43206
|
...withBends(project, from.at, to.at, via),
|
|
43166
43207
|
...op.color ? { color: op.color } : {},
|
|
43167
|
-
...op.width ? { width: op.width } : {}
|
|
43208
|
+
...op.width ? { width: op.width } : {},
|
|
43209
|
+
...sideOf(op)
|
|
43168
43210
|
};
|
|
43169
43211
|
project.wires.push(wire);
|
|
43170
43212
|
return `Added wires[${project.wires.length - 1}] from ${from.said} to ${to.said}${bendsSaid(wire)}.`;
|
|
43171
43213
|
}
|
|
43172
43214
|
function addSolderPath(project, op) {
|
|
43173
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.");
|
|
43174
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.");
|
|
43175
43218
|
const given = op.path ?? (op.from && op.to ? [op.from, ...op.via ?? [], op.to] : void 0);
|
|
43176
43219
|
if (!given) throw new OpError("A solder path needs `from` and `to`, or a `path` of two or more holes.");
|
|
@@ -43200,6 +43243,7 @@ function updateWire(project, op) {
|
|
|
43200
43243
|
if (isSolderPath(project.wires[i]) && (op.color !== void 0 || op.width !== void 0)) {
|
|
43201
43244
|
throw new OpError(`wires[${i}] is a solder path: it has no \`color\` or \`width\`.`);
|
|
43202
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.`);
|
|
43203
43247
|
const updated = {
|
|
43204
43248
|
...project.wires[i],
|
|
43205
43249
|
...from ? { from: from.at } : {},
|
|
@@ -43208,6 +43252,8 @@ function updateWire(project, op) {
|
|
|
43208
43252
|
...op.width !== void 0 ? { width: op.width } : {}
|
|
43209
43253
|
};
|
|
43210
43254
|
if (!updated.color) delete updated.color;
|
|
43255
|
+
if (op.side === "top") delete updated.side;
|
|
43256
|
+
if (op.side === "bottom") updated.side = "bottom";
|
|
43211
43257
|
if (sameHole(updated.from, updated.to)) throw new OpError(`The wire would start and end in hole ${showHole(updated.from)}.`);
|
|
43212
43258
|
if (op.via !== void 0) {
|
|
43213
43259
|
delete updated.via;
|
|
@@ -43379,6 +43425,10 @@ function validateProject(raw, expectNets) {
|
|
|
43379
43425
|
const solder = (Array.isArray(data.wires) ? data.wires : []).flatMap((wire, i) => asEntry2(wire)?.kind === "solder" ? [wireName(i)] : []);
|
|
43380
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.`);
|
|
43381
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
|
+
}
|
|
43382
43432
|
const entries2 = readEntriesAlone(data, project);
|
|
43383
43433
|
report.problems.push(...entries2.unreadable);
|
|
43384
43434
|
const unnamed = skipped - entries2.unreadable.length;
|
|
@@ -43887,7 +43937,7 @@ function renderBoard(project, area) {
|
|
|
43887
43937
|
out.push("", "Wires (index: ends, net):");
|
|
43888
43938
|
for (const { wire, i } of shownWires) {
|
|
43889
43939
|
const bends = wire.via?.length ? ` bending at ${wire.via.map(showHole).join(", ")}` : "";
|
|
43890
|
-
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))}`);
|
|
43891
43941
|
}
|
|
43892
43942
|
}
|
|
43893
43943
|
return out.join("\n");
|
|
@@ -44918,7 +44968,7 @@ function registerShowBoardTool(server, DEFAULT_EDITOR_URL) {
|
|
|
44918
44968
|
description: "The page show_board shows the board in.",
|
|
44919
44969
|
// The picture is a data: image, and the page loads nothing else.
|
|
44920
44970
|
_meta: { ui: { prefersBorder: false } }
|
|
44921
|
-
}, 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.
|
|
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 } } }] }));
|
|
44922
44972
|
K3(server, "show_board", {
|
|
44923
44973
|
title: "Show board",
|
|
44924
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.",
|
|
@@ -44961,12 +45011,12 @@ function registerResources(server) {
|
|
|
44961
45011
|
title: "Project file format",
|
|
44962
45012
|
description: "The project file format (version 8), including component identities and optional circuit requirements, as TypeScript types.",
|
|
44963
45013
|
mimeType: "text/plain"
|
|
44964
|
-
}, 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
|
|
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' }] }));
|
|
44965
45015
|
server.registerResource("share-links", "perfboard://docs/share-links", {
|
|
44966
45016
|
title: "Share links",
|
|
44967
45017
|
description: "How a share link carries a project, and what happens when the user opens one.",
|
|
44968
45018
|
mimeType: "text/markdown"
|
|
44969
|
-
}, 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`. 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 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' }] }));
|
|
44970
45020
|
server.registerResource("parts", "perfboard://parts", {
|
|
44971
45021
|
title: "Parts catalog",
|
|
44972
45022
|
description: "Every part a project can place, with pins and pin labels, as JSON.",
|
|
@@ -44983,7 +45033,7 @@ function registerResources(server) {
|
|
|
44983
45033
|
|
|
44984
45034
|
// src/create-server.ts
|
|
44985
45035
|
function createServer({ editorUrl, imageUrl: imageUrl2, storage }) {
|
|
44986
|
-
const server = new McpServer({ name: "perfboard-designer", version: "0.
|
|
45036
|
+
const server = new McpServer({ name: "perfboard-designer", version: "0.5.0" }, { instructions: INSTRUCTIONS });
|
|
44987
45037
|
registerCatalogTools(server);
|
|
44988
45038
|
registerProjectTools(server);
|
|
44989
45039
|
registerBoardTools(server);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "perfboard-designer-mcp",
|
|
3
|
-
"version": "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",
|