Comfy-Org / Comfy-Org/ComfyUI_frontend

litegraph barrel: BadgePosition removed and registerNodeState published, neither in the compat audit

Open
#15,587 0 comments 0 reactions 0 assignees View on GitHub
Public API
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.