Comfy-Org / Comfy-Org/ComfyUI_frontend
litegraph barrel: BadgePosition removed and registerNodeState published, neither in the compat audit
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 699
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 490
Description
## Summary
The public litegraph barrel loses a type export and gains an internal one, in the same file, and the branch's own compatibility audit documents neither.
Measured on `src/lib/litegraph/src/litegraph.ts`, merge-base `848cd39ed0` vs head `f04692ea20`:
| Symbol | `main` | branch | Direction |
| --- | --- | --- | --- |
| `BadgePosition` | present | **absent** | public export **removed** |
| `registerNodeState` / `unregisterNodeState` | absent | **present** | internal store fn **published** |
| `LGraphBadge` *(control)* | present | present | unchanged |
The control matters: `LGraphBadge` resolves on both refs with the same grep, so the zero for `BadgePosition` is a real absence rather than a broken command.
## Why each direction is a problem
**`BadgePosition` removed.** It is an enum in the public barrel, so an extension doing `import { BadgePosition } from '@comfyorg/litegraph'` breaks at import time. There is no deprecation path — the repo has a `defineDeprecatedProperty` helper (`src/lib/litegraph/src/utils/feedback.ts`) and this removal does not use it.
`docs/architecture/ecs/ecs-extension-compatibility-audit.md` covers `badgePosition`, the **node accessor**, and says it becomes a warning-only no-op. It never mentions `BadgePosition`, the **exported enum**. Those are different symbols with different failure modes: the accessor degrades quietly, the enum fails the import.
**`registerNodeState` / `unregisterNodeState` published.** These are store-registration internals. Once they are in the barrel they are API — someone will call them, and the next refactor that changes their contract becomes a breaking change nobody intended to sign up for. Adding to a public barrel is a one-way door in a way that adding to an internal module is not.
## Ask
Neither is necessarily wrong. But they are both currently **silent**, and the audit that exists specifically to catalogue extension-facing changes does not list them.
1. Is the `BadgePosition` removal intentional? If so it wants an entry in the compat audit and, ideally, a deprecation shim for one release.
2. Are `registerNodeState`/`unregisterNodeState` meant to be public? If not, drop them from the barrel before merge — cheap now, expensive later.
## How this was found
A reviewer-lens sweep noted that the completed subsystem reviews of #14246 read `LinkMap`/`LLink`, the widget files and `serialisation.ts`, but **none of them opened `litegraph.ts`** — the file that defines what is public. The barrel is the API surface and it was the one file nobody reviewed.
Contributor guide
Research direction
Start with src/lib/litegraph/src/litegraph.ts and compare the listed exports at merge-base 848cd39ed0 and head f04692ea20. Read docs/architecture/ecs/ecs-extension-compatibility-audit.md and the defineDeprecatedProperty helper in src/lib/litegraph/src/utils/feedback.ts. Done means the intended public API is decided, the compatibility audit records both changes, and the barrel reflects that decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100