Comfy-Org / Comfy-Org/ComfyUI_frontend

nodeApi: add a command interface alongside the direct-mutation API

Open
#16,852 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.