Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
// The edit loop, end to end: a pointer on the canvas, a request on the wire, a
// file on the other side, and what the screen says about all three.
//
// Everything below drives the whole `BoardWorkspace` — the PCB tab and move
// mode are *clicked*, the part is dragged at a client pixel derived from the
// transform the canvas actually painted, and the answer is read out of the DOM
// and out of the request body. Nothing here composes the pieces itself. That
// is the point: `usePlacementEditor` is well covered, `placementDrag` is well
// covered, `planSourceWrite` is well covered, and this repo has twice shipped a
// broken app made of covered pieces (8fb33cd `snapDelta`, e7f1434 the right
// button) because no test ever ran the *join*.
//
// The server is the real `planSourceWrite`, not a yes-man — see
// boardWorkspace.test-helper.js. So a client edit the shipped server would
// refuse fails here too, and the SOURCE_CHANGED case below is produced by
// actually changing the file under the client rather than by hand-writing a
// 409.
import assert from "node:assert/strict";
import test from "node:test";
import { click, key, pointer } from "../../../test/render.js";
import { openWorkspace } from "./boardWorkspace.test-helper.js";
import { parseBoardSource } from "../boardSource.js";
import { REASONS } from "../placementFields.js";
/** Every placement's position, keyed by id — for "nothing else moved". */
function positions(source) {
const map = new Map();
for (const placement of parseBoardSource(source).placements) {
map.set(placement.id, `${placement.x},${placement.y}`);
}
return map;
}
/**
* Grab R30 and carry it 2 mm east.
*
* R30 is a real 0402 at (-2, -6) on the real hydrate-coaster board, and 2 mm is
* an exact multiple of the 0.5 mm default snap step, so the expected result is
* a constant the test writes out rather than `snapDelta` re-run against itself.
*/
function dragR30East(w) {
const r30 = w.placements.byId.get("resistor[1]");
assert.equal(r30.name, "R30");
assert.deepEqual({ x: r30.x, y: r30.y }, { x: -2, y: -6 }, "the board moved under this test");
const start = w.at(r30.x, r30.y);
const dxPx = 2 * w.view.scale;
pointer(w.canvas, "down", start);
pointer(w.canvas, "move", { clientX: start.clientX + dxPx, clientY: start.clientY });
// The live readout only exists if the drag reached state — this is the line
// that goes quiet when `snapDelta` is missing from PcbCanvas again.
assert.match(w.text('[data-slot="pcb-move-readout"]'), /R30\s*Δ 2, 0 mm/);
pointer(w.canvas, "up", { clientX: start.clientX + dxPx, clientY: start.clientY });
return r30;
}
test("a drag writes the board file's own byte range, in the board file it names", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const before = positions(w.source);
dragR30East(w);
await w.settle();
const posts = w.server.requests.filter((one) => one.method === "POST");
// One write, and one question about it. The write is the invariant this
// line has always guarded — not none, and never two, because a second
// write of the same drag would double the move. The verdict request beside
// it is the other half of the gesture (BoardWorkspace.verdict.render.test.js
// owns what it carries); asserting both here keeps a *third* request from
// arriving unnoticed.
assert.deepEqual(
posts.map((one) => one.command),
["board_source_write", "board_fast_check"],
);
const body = w.server.writes[0];
assert.equal(body.id, "p1");
// The file, not "a" file: the workspace has one board open and the write
// has to name that board's source, not the sidecar and not the IR.
assert.equal(body.file, "boards/main.tsx");
assert.equal(body.sourceLength, w.source.length, "the compare-and-swap token is the file that was read");
assert.equal(body.edits.length, 1, "moving one part in x is one literal");
const [edit] = body.edits;
// The offsets are R30's own `pcbX` literal, checked against the bytes on
// disk rather than written down — an edit that lands two lines away would
// otherwise pass on a coincidence of `-2` appearing somewhere.
assert.equal(w.source.slice(edit.start - 6, edit.end + 1), "pcbX={-2}");
assert.equal(edit.expected, "-2");
assert.equal(edit.text, "0");
// And what the server ended up holding. This is the assertion that would
// survive the whole request shape being redesigned: R30 is at 0, -6 in the
// file now, and every other placement is exactly where it was.
const after = positions(w.server.source);
assert.equal(after.get("resistor[1]"), "0,-6");
for (const [id, at] of before) {
if (id === "resistor[1]") continue;
assert.equal(after.get(id), at, `${id} moved and nobody asked it to`);
}
assert.deepEqual(w.ui.errors, [], "a handler threw where only the console would have seen it");
} finally {
w.close();
}
});
test("the moved part is redrawn where the file now says, and the screen says the copper has not followed", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
dragR30East(w);
await w.settle();
// The part is repainted at its new home by an offset group — the copper
// around it stays where the last router run put it, which is the honest
// state until a rebuild.
const pending = [...w.ui.container.querySelectorAll('[data-slot="pcb-pending-move"]')];
assert.equal(pending.length, 1, "nothing on the canvas is drawn away from its built position");
assert.equal(pending[0].dataset.placement, "resistor[1]");
assert.equal(pending[0].getAttribute("transform"), "translate(2 0)");
// Properties is the typed half of the same edit and must agree with the
// canvas: the file says one thing, the built board still says the other.
assert.equal(
w.text('[data-slot="property-placement-pending"]'),
"the file says 0, -6 — the board below is still the last build at -2, -6",
);
// And the strip: that the edit is saved, what changed, and that a rebuild
// is owed for it. The "Saved to …" prefix is the only thing in the app
// that tells an engineer their work is safe — there is no Save button.
assert.equal(
w.text('[data-slot="placement-edit-note"]'),
"Saved to boards/main.tsx — R30 moved 2, 0 mm." +
" The board below is still the last build — the copper has not moved with the part," +
" and a turn does not show on screen until you rebuild.",
);
assert.equal(w.text('[data-slot="placement-rebuild"]'), "Rebuild (1 change)");
assert.equal(w.text('[data-slot="placement-edit-error"]'), "", "a clean write reported an error");
assert.deepEqual(w.ui.errors, []);
} finally {
w.close();
}
});
test("undo sends the inverse edit, and the board file comes back byte for byte", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
dragR30East(w);
await w.settle();
const undo = w.find('[data-slot="placement-undo"]');
assert.equal(undo.disabled, false, "a drag left nothing to undo");
click(undo);
await w.settle();
assert.equal(w.server.writes.length, 2, "undo is a write of its own");
const [forward, back] = w.server.writes;
// Not merely "an edit that restores -2": the inverse. It expects to find
// exactly what the forward edit wrote, at the offset that edit left behind
// — one character shorter, because `0` is one character shorter than `-2`.
assert.equal(back.file, forward.file);
assert.equal(back.sourceLength, w.source.length - 1);
assert.deepEqual(back.edits, [{ start: forward.edits[0].start, end: forward.edits[0].start + 1, text: "-2", expected: "0" }]);
// The only test of an undo that cannot be argued with.
assert.equal(w.server.source, w.source, "the board file did not come back to what it was");
assert.match(w.text('[data-slot="placement-edit-note"]'), /undid: R30\./);
// Nothing is owed to a rebuild any more: the file on disk is the file the
// board on screen was built from.
assert.equal(w.text('[data-slot="placement-rebuild"]'), "Rebuild");
assert.equal(w.find('[data-slot="placement-undo"]').disabled, true, "one drag, one undo");
assert.equal(w.find('[data-slot="placement-redo"]').disabled, false, "undo without redo is a one-way door");
assert.deepEqual(w.ui.errors, []);
} finally {
w.close();
}
});
test("a write the server refuses reaches the screen, not the console", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
// The agent edits the same file — the whole reason `board_source_write` is
// a compare-and-swap. The offsets the canvas is holding now describe a file
// that no longer exists, and the real `planSourceWrite` refuses them.
const agentText = `${w.source}\n// the agent was here\n`;
w.server.agentWrites(agentText);
dragR30East(w);
await w.settle();
assert.equal(w.server.writes.length, 1, "the drag never reached the server");
// Both places a user could be looking: the strip above the canvas and the
// panel where the same number can be typed instead of dragged. And the
// refusal must NAME the collision — "reopen and try again" told an
// engineer they had lost without telling them to what (round-4 finding).
const refused = w.text('[data-slot="placement-edit-error"]');
assert.match(refused, /the board file changed since it was read/);
assert.match(refused, /23 bytes longer than when you read it/, `refusal said: ${refused}`);
assert.match(refused, /Nothing was written/);
assert.equal(w.text('[data-slot="property-placement-error"]'), refused);
assert.equal(w.server.source, agentText, "a refused write changed the file anyway");
// A failed write is not history and is not a change owed to a rebuild.
assert.equal(w.find('[data-slot="placement-undo"]').disabled, true, "a refused write left an undo entry");
assert.equal(w.text('[data-slot="placement-rebuild"]'), "Rebuild");
assert.equal(w.text('[data-slot="placement-edit-note"]'), "", "a refused write reported as a change");
// The failure is a rejection, not a crash: `errors` holds anything a React
// handler threw, and a swallowed throw here is how the last one hid.
assert.deepEqual(w.ui.errors, []);
} finally {
w.close();
}
});
test("a part the board file places in code cannot be dragged, and the panel says which part and why", async () => {
// terminal-keyboard, because 100 of its 137 parts have no literal in the
// board file — 50 emitted by `keyCells()` directly and 50 as block instances.
// On hydrate-coaster every part is placed by hand and this case cannot arise.
const w = await openWorkspace({ example: "terminal-keyboard" });
try {
const d1 = w.index.components.find((one) => one.refdes === "D1");
assert.ok(d1, "D1 is not on this board");
const centre = {
x: (d1.pcbBox.minX + d1.pcbBox.maxX) / 2,
y: (d1.pcbBox.minY + d1.pcbBox.maxY) / 2,
};
assert.equal(w.placements.byComponentKey.get(d1.key), undefined, "D1 is placed by a literal after all");
// A click still selects it — refusing to move a part is not refusing to
// talk about it.
const spot = w.at(centre.x, centre.y);
pointer(w.canvas, "down", spot);
pointer(w.canvas, "up", spot);
await w.settle();
assert.match(w.text('[data-slot="properties-panel"]'), /D1/);
// The reason, in the DOM, naming the part. Not "unavailable", and not the
// generic sentence for a placement with nothing behind it: this one tells
// an EE the thing they have to change instead.
const why = "D1 has no pcbX/pcbY in the board file — it is placed in code";
const reasons = [...w.ui.container.querySelectorAll('[data-slot="property-locked-reason"]')].map(
(node) => node.textContent,
);
assert.deepEqual(reasons, [why, why, why], "X, Y and Rotation should each carry the reason");
assert.notEqual(why, REASONS.unbound);
// And the coordinate is genuinely not typeable — a reason printed beside a
// live input would be a different lie.
assert.equal(w.find('[data-slot="property-input-x"]'), null);
assert.equal(w.find('[data-slot="property-input-y"]'), null);
// Now drag it. The gesture is not swallowed: with nothing to grab the
// canvas pans, which is what the pointer arbiter says a left press over
// un-grabbable board means.
const before = w.view;
const from = w.at(centre.x, centre.y);
const travelPx = 3 * before.scale;
pointer(w.canvas, "down", from);
pointer(w.canvas, "move", { clientX: from.clientX + travelPx, clientY: from.clientY });
assert.equal(w.text('[data-slot="pcb-move-readout"]'), "", "a part with no literal started a move");
pointer(w.canvas, "up", { clientX: from.clientX + travelPx, clientY: from.clientY });
await w.settle();
assert.equal(w.server.writes.length, 0, "the board file was written for a part it does not place");
const after = w.view;
assert.equal(after.scale, before.scale);
// Within a thousandth of a pixel, because the client coordinate this test
// pressed at was itself computed through the transform — `(tx + x·s) - tx`
// does not come back as `x·s` in binary floating point, and the claim here
// is "it panned by the travel", not "it panned by that exact bit pattern".
assert.ok(
Math.abs(after.tx - before.tx - travelPx) < 1e-3,
`the drag did nothing at all — not even pan (moved ${after.tx - before.tx} of ${travelPx})`,
);
assert.deepEqual(w.ui.errors, []);
} finally {
w.close();
}
});
test("four fast taps of the turn button are four turns, not two", async () => {
// The gesture Altium trains is tapping Spacebar, and a tap is faster than a
// round trip to the server. Every tap used to compute its target from the
// angle *on screen* — which is one write behind while a tap is in flight —
// so taps two, three and four asked for the angle tap one had already
// written, found nothing to change, and vanished without a word. Four taps
// of 90° must come back to where the part started, to the byte.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const r30 = w.placements.byId.get("resistor[1]");
const at = w.at(r30.x, r30.y);
pointer(w.canvas, "down", at);
pointer(w.canvas, "up", at);
await w.settle();
const cw = w.find('[data-slot="placement-rotate-cw"]');
assert.ok(cw, "no turn button — the part did not select");
assert.equal(cw.dataset.rotateVia, "prop", "this test needs a part that takes an angle of its own");
const before = w.server.source;
// Not awaited between clicks. That is the whole point.
click(cw);
click(cw);
click(cw);
click(cw);
await w.settle(10);
const turns = w.server.writes.length;
assert.equal(turns, 4, `four taps wrote ${turns} times`);
assert.equal(w.server.source, before, "four 90° turns did not come back to the starting angle");
// And one turn alone still turns it, so the round trip above is not just
// four no-ops cancelling out.
click(cw);
await w.settle(6);
const after = parseBoardSource(w.server.source).placements.find((one) => one.id === "resistor[1]");
assert.equal(after.rotation, 270);
} finally {
w.close();
}
});
test("undo refuses to overwrite somebody else's edit to the same part", async () => {
// The collision this whole app is built around: an agent and a human editing
// one file. Undo writes a coordinate recorded before the forward edit, and
// the byte-level compare-and-swap cannot object — the edits are recomputed
// against the current text, so their `expected` always matches. Measured on
// the running app: human moves a part, agent moves it again, human presses
// ⌘Z, and the agent's work disappears behind a green tick.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
dragR30East(w);
await w.settle();
assert.equal(positions(w.server.source).get("resistor[1]"), "0,-6");
// The agent gets there next, and the client re-reads the file — which is
// what the catalog watcher makes it do in production, and what makes this
// dangerous: after the reload the undo's byte ranges are computed against
// the agent's text, so every `expected` matches and the compare-and-swap
// has nothing to object to. The loss is semantic, not a stale offset.
w.server.agentWrites(w.server.source.replace("pcbX={0} pcbY={-6}", "pcbX={9} pcbY={-6}"));
w.ui.set({ manifestRevision: 99 });
await w.settle(6);
assert.equal(positions(w.server.source).get("resistor[1]"), "9,-6");
const undo = w.find('[data-slot="placement-undo"]');
click(undo);
await w.settle(6);
const note = w.text('[data-slot="placement-edit-error"]');
assert.match(note, /R30 is at 9, -6 now, not the 0, -6 your change left it at/);
assert.match(note, /somebody else moved it since/i);
assert.equal(
positions(w.server.source).get("resistor[1]"),
"9,-6",
"undo wrote over an edit it did not make",
);
} finally {
w.close();
}
});
test("the turn buttons say what they will write, because 270 reads as a bug", async () => {
// `pcbRotation` counts counterclockwise, so turning a part clockwise from 0°
// writes 270. That is correct, and to anyone who then opens the board file
// it is indistinguishable from a broken button — so the button says it.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const r30 = w.placements.byId.get("resistor[1]");
const at = w.at(r30.x, r30.y);
pointer(w.canvas, "down", at);
pointer(w.canvas, "up", at);
await w.settle();
const cw = w.find('[data-slot="placement-rotate-cw"]');
const ccw = w.find('[data-slot="placement-rotate-ccw"]');
assert.match(cw.title, /clockwise/);
assert.match(cw.title, /writes pcbRotation=\{270\}/);
assert.match(cw.title, /counts counterclockwise/);
assert.match(ccw.title, /writes pcbRotation=\{90\}/);
} finally {
w.close();
}
});
test("Spacebar turns the part being dragged — Altium's own gesture", async () => {
// The arbiter answered Space and this canvas swallowed it, with a comment
// saying there was no callback to reach the editor. There was one: the
// workspace was already passing `onPlacementRotate` and PcbCanvas never
// declared the prop. Two halves of one wire, neither connected — the same
// shape as the right button and as `board_fast_check` before it.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const r30 = w.placements.byId.get("resistor[1]");
const start = w.at(r30.x, r30.y);
pointer(w.canvas, "down", start);
pointer(w.canvas, "move", { clientX: start.clientX + 2 * w.view.scale, clientY: start.clientY });
key(window, " ");
await w.settle(6);
const turned = parseBoardSource(w.server.source).placements.find((one) => one.id === "resistor[1]");
assert.equal(turned.rotation, 90, "Space did not turn the part being dragged");
// Shift+Space turns it back the other way, and the drag is still live —
// the position commits on mouse-up as it always did.
key(window, " ", { shiftKey: true });
await w.settle(6);
assert.equal(
parseBoardSource(w.server.source).placements.find((one) => one.id === "resistor[1]").rotation,
0,
);
pointer(w.canvas, "up", { clientX: start.clientX + 2 * w.view.scale, clientY: start.clientY });
await w.settle(6);
const after = parseBoardSource(w.server.source).placements.find((one) => one.id === "resistor[1]");
assert.equal(after.x, 0, "the drag that carried the turn lost its move");
} finally {
w.close();
}
});
test("move mode outlines everything the file can move, so nothing has to be guessed at", async () => {
// Asked from the outside, in these words: "I can drag some components, some
// can't be dragged?" Both true — a part inside a block moves with the block,
// a part placed by a `for` loop has no literal to change, and copper belongs
// to the router — and until now the difference was invisible until you
// pressed on something and nothing happened.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const outlines = () => [...w.ui.container.querySelectorAll('[data-slot="pcb-editable-outlines"] rect')];
assert.equal(
outlines().length,
w.placements.byId.size,
"the outlines and the bound placements are the same set or the drawing is lying",
);
// The strip's own count is the same number, said in words.
assert.match(w.text('[data-slot="placement-edit-count"]'), new RegExp(`^${w.placements.byId.size} parts`));
// Leaving move mode takes them away: they are an affordance for an action
// that is no longer available.
click(w.find('[data-slot="placement-edit-close"]'));
await w.settle();
assert.equal(outlines().length, 0, "the outlines outlived move mode");
} finally {
w.close();
}
});
test("the strip says why a part cannot be dragged, in the words of the file", async () => {
// Reported by an engineer building `macropad-6`: "moving a key was
// impossible — named-constant coordinates make a placement invisible to the
// editor". It was not invisible. `editEngine.scanRefusals` has named every
// refused tag, its line and its expression since the day it was written, and
// **nothing imported the module** — the same built-and-never-wired shape as
// the verdict gate and the right mouse button before it.
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const count = w.find('[data-slot="placement-edit-count"]');
assert.ok(count, "no count on the strip");
const toggle = w.find('[data-slot="placement-refusals-toggle"]');
assert.ok(toggle, "the refused parts are a number nobody can open");
assert.match(toggle.textContent, /\d+ cannot/);
click(toggle);
await w.settle();
const list = w.text('[data-slot="placement-refusals"]');
assert.ok(list.length > 0, "opening the list showed nothing");
// Every row names the tag and the line it is on, then says why in a
// sentence somebody can act on. hydrate-coaster's RP2040 is wrapped in a
// `<group>`, which is one of the reasons:
assert.match(list, /[A-Za-z0-9]+:\d+/, "a row that does not name its tag and line");
assert.match(list, /line to change|computed|loop|component/i);
assert.deepEqual(w.ui.errors, []);
} finally {
w.close();
}
});
// Round 4, editing judge, scored 6/10 on this one case: placement ids are
// positional (`tag[ordinal]`), so an agent inserting an earlier element of the
// same tag renames every later one. The human's next nudge then re-resolved
// the id against the new text, found a DIFFERENT real part, computed clean
// spans for it, and wrote — no refusal, nothing on screen. A mouse drag
// happened to self-correct because it re-hit-tests real geometry, so the
// defect was invisible depending on which input you used.
test("an agent inserting a part above yours does not redirect your nudge onto a neighbour", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
// Select R31 — the second <resistor> in the file, id `resistor[2]`.
const target = w.placements.byId.get("resistor[2]");
assert.equal(target.name, "R31", `fixture moved: resistor[2] is ${target.name}`);
const at = w.at(target.x, target.y);
pointer(w.canvas, "down", at);
pointer(w.canvas, "up", at);
await w.settle(4);
// The agent inserts one resistor ABOVE it. Every later ordinal shifts by
// one, so `resistor[2]` now names the part that used to be `resistor[1]`.
const before = w.server.source;
const anchor = " <resistor";
const inserted = before.replace(
anchor,
` <resistor name="R99" resistance="1k" footprint="0402" pcbX={40} pcbY={40} />\n${anchor}`,
);
assert.notEqual(inserted, before, "could not insert ahead of the first resistor");
w.server.agentWrites(inserted);
await w.settle(4);
// Nudge. This is the input method that used to write to the wrong part.
w.ui.container.querySelector('[data-slot="pcb-canvas"]')?.focus?.();
key(window, "ArrowRight", { ctrlKey: true });
await w.settle(6);
const source = w.server.source;
// R31 either moved, or nothing moved — but R30 must not have.
const r30 = /name="R30"[^/]*pcbX=\{(-?[\d.]+)\}/.exec(source);
const r30Before = /name="R30"[^/]*pcbX=\{(-?[\d.]+)\}/.exec(inserted);
assert.ok(r30 && r30Before, "could not read R30's x out of the board file");
assert.equal(
r30[1],
r30Before[1],
"the nudge landed on R30 — a part the engineer never selected",
);
// Two acceptable outcomes, and the file decides which happened — a
// refused request still counts as a request, so the request log cannot.
if (source !== inserted) {
// Something was written: it must be the part that was selected.
const r31 = /name="R31"[^/]*pcbX=\{(-?[\d.]+)\}/.exec(source);
assert.ok(r31, "R31 left the file");
assert.notEqual(r31[1], String(target.x), "the file changed but R31 did not move");
} else {
// Nothing was written, which is the safe answer — but it has to say so
// where the engineer is looking, not only in the console.
const shown = w.text('[data-slot="placement-edit-error"]');
assert.ok(shown.trim(), "the nudge did nothing and said nothing");
}
} finally {
w.close();
}
});
// The editor autosaves and will never grow a Save button — that is a standing
// product decision. Three panel rounds running found it real and stated
// nowhere in the UI, and a person who does not know it goes looking for a
// Save, does not find one, and assumes the worst about their work.
test("the strip says where edits go before one is made, and says they are saved after", async () => {
const w = await openWorkspace({ example: "hydrate-coaster" });
try {
const before = w.text('[data-slot="placement-edit-note"]');
assert.match(before, /written straight to/, `nothing told the engineer where edits go: "${before}"`);
assert.match(before, /no Save button/);
assert.match(before, /boards\/main\.tsx/);
dragR30East(w);
await w.settle(6);
assert.equal(w.text('[data-slot="placement-edit-error"]'), "", "the drag was refused");
const saved = w.text('[data-slot="placement-saved"]');
assert.match(saved, /Saved to boards\/main\.tsx/, `no confirmation after a write: "${saved}"`);
} finally {
w.close();
}
});
62869109eThis file is pinned to the selected release. Download the original to open it in your design tool.