Comfy-Org / Comfy-Org/ComfyUI_frontend
[Epic] Stable node/widget API + command pattern + ECS on-ramps (from 1.47 reflow/label fixes)
- 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
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