Comfy-Org / Comfy-Org/ComfyUI_frontend
Document the createMutationView geometry mirror contract (node.pos / node.size)
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 699
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 490
Description
`createMutationView` is the compatibility shim that keeps `node.pos[0] = x`, `node.size = [w,h]`, `group.pos`, `Reroute.pos` and `SubgraphSlot.pos` working after geometry moved into the CRDT layout store. It is documented nowhere.
```
git grep -c createMutationView 5002fae1b1 -- docs # zero files
```
Five other ECS concerns got a per-concern doc on #14246 (`link-topology-store.md`, `node-data-store.md`, `reroute-chain-store.md`, `node-badge-store.md`, `output-slot-connectivity.md`). Layout got none. ADR 0003 carries the reasoning across three good amendments but never names the mechanism, so a reader cannot answer "what happens if my extension mutates `node.pos` in place" from anything written down — only by reading a Proxy.
This matters because the equivalent contract on the slot surface was undocumented too, and #15620 was a pack breaking on it: `NodeOutputSlot` honours removals through the legacy view and discards additions.
The geometry surface does not have that bug. I verified it by execution at `5002fae1b12d44831a21367afa7c0f798f7e7a2c` — all ten idioms commit to the store, and reads re-synchronise:
| idiom | result |
| --- | --- |
| `node.pos = [x, y]` | commits |
| `node.pos[0] = x` | commits |
| `node.size = [w, h]` | commits |
| `node.size[0] = w` | commits |
| `node.pos.set([x, y])` | commits |
| `node.pos.fill(v)` | commits |
| `node.pos[0] += 15` | commits |
| `Object.assign(node, { pos })` | commits |
| read after an external store move | reflects the store |
| `{...node}` | **drops `pos` and `size`** (prototype accessors) |
That last row is the one an extension author cannot guess.
Usage, so this is not hypothetical. Local custom-node corpus, 157 frontend files / 29 packs, control arm `/registerExtension/` matching 84 of 157 files:
| idiom | files | sites | packs |
| --- | --- | --- | --- |
| `.pos[0\|1] =` | 2 | 13 | 2 |
| `.size[0\|1] =` | 4 | 18 | 1 |
| `.pos =` / `.size =` | 6 | 8 | 3 |
| `.setPos(` / `.setSize(` | 12 | 29 | 5 |
68 call sites across 6 packs mutate node geometry through this shim today.
**Ask:** a short doc stating the mirror contract — in-place element writes commit, whole-array assignment commits, array methods commit, reads re-synchronise from the store, and spreading a node drops `pos`/`size`.
Blame on `src/lib/litegraph/src/infrastructure/createMutationView.ts:42` is Alexander Brown (DrJKL), commit `test: cover direct widget array mutations (#15453)` — a real commit, not a bulk reformat.
Related: #15620, #15618, #15594, #15577. Found reviewing #14246 (slice C3, layout/geometry).
Contributor guide
Assessment
This issue has not been assessed yet.