Comfy-Org / Comfy-Org/ComfyUI_frontend

[Epic] Stable node/widget API + command pattern + ECS on-ramps (from 1.47 reflow/label fixes)

Open
#13,964 2 comments 3 reactions 0 assignees View on GitHub
enhancement Public API
Dominant language
TypeScript
Stars
2k
Forks
699
Avg merge
1d 7h
Merged PRs (30d)
490

Description

## Problem / Goal

The 1.47 QA round produced several fixes that are correct but are **compensating stopgaps** for a missing stable public API — most notably the runtime size-**Proxy** (#13867) for the `node.size[1]=` idiom, the `renameWidget` `input.label` interim (#13865), and the widget-store branches. The frontend is already moving toward a stable extension API ("v2 handles": `NodeHandle`/`WidgetHandle`, `defineNodeExtension`), a command pattern (`commandStore` → `useLayoutMutations().resizeNode`), and ECS (ADR-0008). We want these stopgaps shaped as **on-ramps** to that end-state, with concrete follow-ups tracked so the migration actually happens and isn't forgotten.

Design basis: the reflow design review (3 memos, unanimous the Proxy is correct as a bridge) + `research/architecture/toward-new-api-plan.md`. First slice already up as a draft: #13929 (`Comfy.Node.Resize` + `NodeHandle.setSize`).

## Proposed Solution (A1–A9)

- [ ] **A1** — File a **command-pattern ADR** (ADR-0003 is CRDT-layout; there is no command ADR today).
- [ ] **A2** — `Comfy.Node.Resize` command routing to `resizeNode`. *(started in #13929)*
- [ ] **A3** — `NodeHandle.setSize()` + `autosize()` + `on('resize')`. *(setSize started in #13929; autosize/on are stubs)*
- [ ] **A4** — Add `warnDeprecated` to the #13867 size-Proxy set-trap once A2/A3 land (names the sanctioned call; warning-only grace period).
- [ ] **A5** — ECS `WidgetIdentity.label` serialized field (name=identity, label=display; ADR-0009) + `WidgetHandle.setLabel` — replaces the #13865 `input.label` interim and fixes socketless by construction.
- [ ] **A6** — Stable `WidgetEntityId` render key (root of the #13866 unstable-key churn) — makes the TransitionGroup workaround revertible.
- [ ] **A7** — Steer the widget-store branches to the ECS identity/value/layout component split; expose `NodeHandle.widget()/widgets()`.
- [ ] **A8** — `registerCustomNodes` v2 (BLOCKER for the public extension API).
- [ ] **A9** — Cross-link the new-API docs from the ecosystem repo + migration-coverage map.

## Acceptance Criteria

- A1–A9 tracked here with linked issues/PRs; each stopgap PR references its end-state item.
- The stable resize API (A2/A3) merged and documented; #13867's Proxy carries a `warnDeprecated` (A4) pointing at it.
- Migration path documented so `node.size[1]=` / hand-written types / direct widget mutation have a sanctioned replacement.

Refs: plan `research/architecture/toward-new-api-plan.md`; ecosystem repo `christian-byrne/ComfyUI_frontend-ecosystem`; on-ramp PRs #13867 / #13865 / #13866; first API slice #13929.

Contributor guide

Open the contributing guide

Research direction

Start with research/architecture/toward-new-api-plan.md, the reflow design-review memos, and draft #13929 for the resize API. Review the A1–A9 checklist and linked stopgap issues #13865, #13866, and #13867 before choosing a scoped follow-up. Done means the relevant stable API, migration documentation, and tracking links satisfy the stated acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, developer-experience, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.