The layout is copied, belongs to its device, and is two finite numbers (#1325) #1326

Merged
jaylouisw merged 1 commit from fix/layout-honesty into main 2026-11-10 03:11:26 +00:00
Owner

The layout is copied, belongs to its device, and is two finite numbers.

Fixes #1325.

The third thing a board holds, after devices (#1321) and cables (#1323). Where each box sits was the least guarded of
the three.

Measured before

1. serialize().layout === topo.layout: true
   write to the document      -> the board says d1.x = 999
   add a box to the document  -> the board has a box at {x:1,y:1}
2. after removeDevice('d2')   -> layout still holds d2, in memory AND in the next save
3. a position for a device the document does not contain -> kept as a ghost
4. {"x":"left","y":"top"}     -> adopted; the canvas draws pos.x, so the box lands at NaN
   {"d1":null}                -> adopted
   layout: []                 -> accepted (an array is an object), kept in memory, then silently
                                 dropped at the next save (JSON ignores an array's string keys)
5. POST /devices {x:0,y:0}    -> the device is placed at 160,160

Why each is a defect and not a taste

  • The document is not the board — the same fault #1323 fixed for link endpoints; layout was still handing out its
    own object.
  • removeDevice() left the position. The server remembered delete topo.layout[devId]; the engine did not. A
    removal from anywhere else left a box in the file that is not on the board.
  • A position is drawn. web/canvas.js reads pos.x straight from the layout, so {"x": "left"} gives NaN
    coordinates and the box is drawn nowhere with nothing to explain it. layout: [] is worse — accepted, kept, then
    lost at the next save.
  • A ghost position is a lie in the file and a target for the next device that takes that id.
  • 0 is a coordinate. { x: body.x || 160 } treats zero as missing, so a device placed at the origin is quietly
    moved to 160,160.
  • /layout stored whatever it was handed, unvalidated.

Fixes

serialize() copies the layout; removeDevice() takes the position with the device; fromJSON validates every entry
(E_LAYOUT_BAD_ENTRY, E_LAYOUT_MALFORMED, E_LAYOUT_UNKNOWN_DEVICE — through loadIssues, which every payload
already carries); the API checks every position before storing any, so a bad entry cannot half-apply a layout, and
answers 400 naming the rule; and 0 places a device at 0.

Evidence

test/layout-roundtrip.test.js — 20 checks: a fractional negative position and the origin both survive a reload;
the handed-out document can be changed without moving the board; removing a device removes its position from memory,
from the saved document and from the reload; six impossible layouts are each reported with the right code and none
becomes a position the canvas will draw, while a good position beside a bad one survives; over HTTP a device placed at
0,0 is at 0,0, a string coordinate is a 400 with the board unmoved, a real position applies, and deleting the
device takes its position out of the state.

With engine/topology.js and server/index.js reverted, 12 of the 20 fail.

docs/ARCHITECTURE.md: "Where the boxes are".

Suite: 178 suites, 7,043 assertions, 0 failed.

The layout is copied, belongs to its device, and is two finite numbers. Fixes #1325. The third thing a board holds, after devices (#1321) and cables (#1323). Where each box sits was the least guarded of the three. ## Measured before ``` 1. serialize().layout === topo.layout: true write to the document -> the board says d1.x = 999 add a box to the document -> the board has a box at {x:1,y:1} 2. after removeDevice('d2') -> layout still holds d2, in memory AND in the next save 3. a position for a device the document does not contain -> kept as a ghost 4. {"x":"left","y":"top"} -> adopted; the canvas draws pos.x, so the box lands at NaN {"d1":null} -> adopted layout: [] -> accepted (an array is an object), kept in memory, then silently dropped at the next save (JSON ignores an array's string keys) 5. POST /devices {x:0,y:0} -> the device is placed at 160,160 ``` ## Why each is a defect and not a taste * **The document is not the board** — the same fault #1323 fixed for link endpoints; `layout` was still handing out its own object. * **`removeDevice()` left the position.** The server remembered `delete topo.layout[devId]`; the engine did not. A removal from anywhere else left a box in the file that is not on the board. * **A position is drawn.** `web/canvas.js` reads `pos.x` straight from the layout, so `{"x": "left"}` gives NaN coordinates and the box is drawn nowhere with nothing to explain it. `layout: []` is worse — accepted, kept, then **lost at the next save**. * **A ghost position** is a lie in the file and a target for the next device that takes that id. * **`0` is a coordinate.** `{ x: body.x || 160 }` treats zero as missing, so a device placed at the origin is quietly moved to 160,160. * `/layout` stored whatever it was handed, unvalidated. ## Fixes `serialize()` copies the layout; `removeDevice()` takes the position with the device; `fromJSON` validates every entry (`E_LAYOUT_BAD_ENTRY`, `E_LAYOUT_MALFORMED`, `E_LAYOUT_UNKNOWN_DEVICE` — through `loadIssues`, which every payload already carries); the API checks **every** position before storing any, so a bad entry cannot half-apply a layout, and answers `400` naming the rule; and `0` places a device at `0`. ## Evidence `test/layout-roundtrip.test.js` — **20 checks**: a fractional negative position and the origin both survive a reload; the handed-out document can be changed without moving the board; removing a device removes its position from memory, from the saved document and from the reload; six impossible layouts are each reported with the right code and none becomes a position the canvas will draw, while a good position beside a bad one survives; over HTTP a device placed at `0,0` is at `0,0`, a string coordinate is a `400` with the board unmoved, a real position applies, and deleting the device takes its position out of the state. With `engine/topology.js` and `server/index.js` reverted, **12 of the 20 fail**. `docs/ARCHITECTURE.md`: "Where the boxes are". Suite: 178 suites, 7,043 assertions, 0 failed.
The layout is copied, belongs to its device, and is two finite numbers (#1325)
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 12s
CI / Test (Node 20) (pull_request) Successful in 3m11s
CI / Test (Node 18) (pull_request) Successful in 3m22s
CI / Server smoke test (pull_request) Successful in 37s
CI / Docker build (pull_request) Successful in 1m2s
CI / Test (Node 22) (pull_request) Successful in 2m53s
0d35d67408
The third thing a board holds, after devices (#1321) and cables (#1323). Where each box sits was the least guarded of
the three. Measured before:

  1. serialize().layout === topo.layout: true - write to the document and the board moves; add a box to the document
     and the board has it;
  2. after removeDevice('d2'), the layout still holds d2 - in memory and in the next save;
  3. a position for a device the document does not contain was kept as a ghost;
  4. {"x":"left"} was adopted (the canvas draws pos.x, so the box lands at NaN), {"d1":null} was adopted, and
     layout: [] was accepted - an array is an object - kept in memory, then silently dropped at the next save,
     because JSON.stringify ignores an array's string keys;
  5. POST /devices {x:0,y:0} placed the device at 160,160, because body.x || 160 treats zero as missing.

Fixes:

  * serialize() copies the layout, for the same reason link endpoints are copies (#1323): the document the API, the
    UI, the example builder and every fixture receives must not be the live board;
  * removeDevice() deletes the position. The server remembered to do it; the engine did not, so a removal from any
    other caller left a box in the file that was not on the board;
  * fromJSON validates the layout: a position must be two finite numbers else it is dropped and reported
    (E_LAYOUT_BAD_ENTRY), a layout that is not a map is refused (E_LAYOUT_MALFORMED), and a position for a device the
    document does not contain is a warning (E_LAYOUT_UNKNOWN_DEVICE) - all through loadIssues, which every state
    payload already carries;
  * the API checks every position before storing any, so a bad entry cannot half-apply a layout, and answers 400
    naming the rule;
  * 0 is a coordinate: a device asked for at 0,0 is placed at 0,0.

test/layout-roundtrip.test.js: 20 checks. A fractional negative position and the origin both survive a reload; the
handed-out document can be changed without moving the board; removing a device removes its position from memory, from
the saved document and from the reload; six impossible layouts are each reported with the right code and none of them
becomes a position the canvas will draw, while a good position beside a bad one survives; and over HTTP a device
placed at 0,0 is at 0,0, a string coordinate is a 400 with the board unmoved, a real position applies, and deleting
the device takes its position out of the state.

With engine/topology.js and server/index.js reverted, 12 of the 20 fail - aliasing, the orphaned position, every junk
layout adopted, and the device at 160,160.

docs/ARCHITECTURE.md: "Where the boxes are".

Suite: 178 suites, 7,043 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 03:11:20 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1326
No description provided.