Comfy-Org / Comfy-Org/ComfyUI_frontend
nodeApi: add a command interface alongside the direct-mutation API
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 699
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 490
Description
Follow-up owned from review of #16790 (thread on `graphHandle.ts`).
## Context
The published node API mutates LiteGraph objects directly — `node.setTitle()`, `slot.connectTo()`, `widget.setValue()` all write through immediately. ADR 0003/0008 require entity state changes to be serializable, idempotent and deterministic commands so they are replayable, undoable and transmittable over CRDT. The current surface bypasses that.
## Decision
The direct-mutation surface **stays**. It is what packs are being converted against, it is what the guide documents, and an API where every edit is an envelope to construct would not be adopted. What is missing is the other half: a command interface offered *in addition*, so a pack that wants undo/replay/multiplayer-safe edits can opt into it, and so the host can route the ergonomic calls through the same protocol underneath.
Not done in #16790 because it is a design piece across every handle, not a fix, and that PR is already 20k lines under review.
## Done looks like
- A command representation for each mutation the API exposes, serializable and replayable
- The existing direct methods dispatch commands internally rather than writing to LiteGraph, so both paths share one protocol
- A published way for a pack to build and submit commands itself, including batches
- Undo/redo and CRDT transport work for pack-originated edits the same as for user edits
- An ADR recording the two-surface decision and why the direct API was retained
## Notes
Sequencing matters: doing this after the handles settle avoids rewriting the command set twice. It should land before the API is advertised as stable, because moving mutations onto commands later is a behavioural change for anyone depending on write timing.
Contributor guide
Research direction
Read graphHandle.ts, ADR 0003/0008, and the review thread for #16790 first; the issue names no tests or other entry points. Map the mutation surface across the handles before defining serializable commands, then verify that direct methods, pack-submitted batches, undo/redo, and CRDT transport share the protocol and that the two-surface decision is recorded in an ADR.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, distributed-systems, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100