Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
4f60067
feat: tag core badge rows with projection part, keep raw text
DrJKL Jul 6, 2026
b752a11
feat: aggregate subgraph credits in the badge system
DrJKL Jul 6, 2026
73bdad9
feat: cut both renderers over to store badge rows
DrJKL Jul 6, 2026
bb0ba79
docs: record slice B implementation and resolved badge decisions
DrJKL Jul 6, 2026
88902ed
fix: preserve legacy subgraph credits semantics and settle pricing cache
DrJKL Jul 6, 2026
b890988
fix: resolve badge graph id live and register nodes after onNodeAdded
DrJKL Jul 6, 2026
2f665ef
refactor: trim badge comments to constraints the code cannot show
DrJKL Jul 6, 2026
0c61bd3
fix: track badge bucket membership so workflow loads wake the system
DrJKL Jul 6, 2026
c803336
refactor: address badge review feedback
DrJKL Jul 15, 2026
6e0429b
refactor: unify unique-node traversal as mapUniqueNodes
DrJKL Jul 15, 2026
0ec2f55
refactor: system-owned badge rows, wholesale writes, dead code removal
DrJKL Jul 15, 2026
c3d1f33
refactor: derive badge rows on read, delete the badge store
DrJKL Jul 15, 2026
c4c30c0
refactor: clarify badge derivation boundary
DrJKL Jul 15, 2026
6f3cbf9
test: assert badge behavior
DrJKL Jul 15, 2026
b70d690
Remove excessive mini-modules
DrJKL Jul 15, 2026
2b69f93
Small type/comment/ordering cleanup
DrJKL Jul 15, 2026
33b218c
fix: bump graph version after onNodeAdded
DrJKL Jul 16, 2026
067d1ca
test: stop returning raw LGraphNode[] from evaluate
DrJKL Jul 16, 2026
5d98bd1
fix: read nodeDef inside partition computed
DrJKL Jul 16, 2026
1306091
docs: drop stale version/badge comments
DrJKL Jul 16, 2026
15cdf31
refactor: hoist graph credits projection into badgeSystem
DrJKL Jul 16, 2026
6d219b1
style: sort CreditsBadgeEntry keys
DrJKL Jul 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions browser_tests/fixtures/helpers/NodeOperationsHelper.ts
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,6 @@ export class NodeOperationsHelper {
return await this.page.evaluate(() => window.app!.graph.nodes.length)
}

async getNodes(): Promise<LGraphNode[]> {
return await this.page.evaluate(() => {
return window.app!.graph.nodes
})
}

async waitForGraphNodes(count: number): Promise<void> {
await this.page.waitForFunction((count) => {
return window.app?.canvas.graph?.nodes?.length === count
Expand Down
19 changes: 0 additions & 19 deletions browser_tests/tests/nodeBadge.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,25 +48,6 @@ test.describe('Node Badge', { tag: ['@screenshot', '@smoke', '@node'] }, () => {

await expect(comfyPage.canvas).toHaveScreenshot('node-badge-multiple.png')
})

test('Can add badge left-side', async ({ comfyPage }) => {
await comfyPage.page.evaluate(() => {
const LGraphBadge = window.LGraphBadge!
const app = window.app as ComfyApp
const graph = app.graph
const nodes = graph.nodes

for (const node of nodes) {
node.badges = [new LGraphBadge({ text: 'Test Badge' })]
// @ts-expect-error - Enum value
node.badgePosition = 'top-left'
}

graph.setDirtyCanvas(true, true)
})

await expect(comfyPage.canvas).toHaveScreenshot('node-badge-left.png')
})
})

test.describe(
Expand Down
Binary file not shown.
7 changes: 3 additions & 4 deletions browser_tests/tests/workflowPersistence.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -252,10 +252,9 @@ test.describe('Workflow Persistence', () => {
await expect.poll(() => comfyPage.nodeOps.getNodeCount()).toBe(1)

await expect
.poll(async () => {
const nodes = await comfyPage.nodeOps.getNodes()
return nodes[0]?.type
})
.poll(() =>
comfyPage.page.evaluate(() => window.app!.graph.nodes[0]?.type)
)
.toBe('KSampler')
})

Expand Down
29 changes: 22 additions & 7 deletions docs/adr/0008-entity-component-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,14 +37,20 @@ writes are tracked without an action chokepoint. The `layoutStore` link
connectivity mirror and the `slot._floatingLinks` sets were deleted in
the same work; the layout store now holds geometry only.

### Amendment (2026-07-14, PR 13458)
### Amendment (2026-07-15, PR 13458)

`nodeBadgeStore` joined the dedicated-store set: plain `BadgeData` rows
keyed by `NodeId` in root-graph-scoped buckets. Unlike the
proxy-adoption stores above, rows are written by a reactive badge
system (`src/systems/badgeSystem.ts`) — a pure `computeBadges` inside a
per-node effect scope — see
[Node Badge Store](../architecture/node-badge-store.md).
Node badge rows remain plain `BadgeData`, but they are derived presentation
data rather than authoritative entity state. Materializing them in a dedicated
store duplicated settings, node definitions, palette, pricing, widget, link,
and graph state. It also required registration, teardown, and cache lifecycle
logic.

Instead, `src/systems/badgeSystem.ts` keeps one lazy computed projection per
node instance. Renderers query that projection through a temporary app-layer
registration seam, which keeps the litegraph layer independent from the badge
system's pricing dependencies. Badge rows remain transient: they are
not serialized, transmitted through CRDT, or included in undo history. See
[Node Badge Store](../architecture/node-badge-store.md) for the design history.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

## Context

Expand Down Expand Up @@ -247,6 +253,15 @@ Systems are pure functions that query the relevant store(s) for entities with sp
- **LayoutSystem** — queries `Position` + `Dimensions` + structural components for auto-layout
- **SelectionSystem** — queries `Position` for point entities and `Position` + `Dimensions` for box hit-testing

Until a `RenderSystem` owns render orchestration, node badges use a registered
query function so the legacy canvas can read the app-owned projection without
importing the badge system. Once the `RenderSystem` can query entity data and
compose renderer input, badge lookup should move there. That migration should
delete the registration seam and remove badge projection access from
`LGraphNode`; the render system will query `BadgeData` and pass plain draw data
to the canvas. This keeps badge derivation app-owned without materializing its
output as a second source of truth.

System design is deferred to a future ADR. For detailed before/after walkthroughs of how lifecycle operations (node removal, link creation, subgraph nesting, etc.) transform under ECS, see [ECS Lifecycle Scenarios](../architecture/ecs-lifecycle-scenarios.md).

### Migration Strategy
Expand Down
173 changes: 120 additions & 53 deletions docs/architecture/node-badge-store.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Node Badge Store

Date: 2026-07-05 (updated 2026-07-06)
Status: Partially implemented — decisions 1–4 shipped as
`src/stores/nodeBadgeStore.ts` + `src/systems/badgeSystem.ts` (slice A);
decision 5 and the open decisions below await the consumer-cutover PR
(slice B). Follow-up to the
Date: 2026-07-05 (updated 2026-07-15)
Status: Superseded on this branch by a derive-on-read prototype — see
[Prototype: derive-on-read](#prototype-derive-on-read-2026-07-15) below.
Slices A and B shipped as described; the prototype then removed the
store. Follow-up to the
[link topology store](link-topology-store.md),
[reroute chain store](reroute-chain-store.md), and the
[node data store draft](node-data-store.md)
Expand Down Expand Up @@ -38,15 +38,15 @@ the store rows the single truth both renderers read.
The store holds only plain data (ADR 0008 component rule):

```
BadgeData {
kind: 'core' | 'credits' | 'extension'
text: string
fgColor?: string
bgColor?: string
iconKey?: string // resolved via a small icon registry ('credits' → SVG)
}
BadgeData = CoreBadgeData | CreditsBadgeData // discriminated on `kind`
// core rows require `part`; credits rows may carry an `iconKey`
// resolved via a small icon registry ('credits' → SVG)
```

There is no `extension` kind: resolved decision 1 below keeps
`node.badges` as the raw extension surface, so the store holds only
system-computed rows and the system replaces them wholesale per write.

No `onClick` (no producer exists; `LGraphButton`/`title_buttons` are a
separate surface and out of scope). No `Image` objects — icons are
referenced by key. A `commandId` field can be added if a clickable badge
Expand All @@ -65,8 +65,9 @@ unregister / unregister-all trio at the `LGraph.add` / `LGraph.remove` /
conventions.

Rows are partitioned by `kind` at read time; the positional `slice(1)`
convention and icon-identity credits detection are deleted. Display
order is kind order (core, credits, extension), not insertion order.
convention and icon-identity credits detection are deleted. The system
emits rows in display order (core, then credits) and replaces a node's
array wholesale, so reads are identity-stable between writes.

## Decision 3: A reactive BadgeSystem writes the rows

Expand Down Expand Up @@ -110,53 +111,119 @@ Frame-budget parity per ADR 0008's render mitigations applies.
`registeredNodeIds` to attach/detach per-node effect scopes. Litegraph
never imports the system, so the pricing/nodeDef dependency graph
(which runtime-imports the litegraph barrel) stays acyclic. The system
takes a `resolveNode` seam and will be bootstrapped at the app layer
in slice B, when the `Comfy.NodeBadge` extension stops pushing
closures; until then rows are written only under test. Row writes are
takes `resolveGraphId`/`resolveNode` seams and is bootstrapped once at
the app layer by the `Comfy.NodeBadge` extension (`useNodeBadge`).
The graph id is resolved live on every recompute because
`LGraph.clear()` and `configure()` reassign the root graph's id; a
captured id strands the system on a dead bucket. Row writes are
refused for unregistered nodes so a late effect flush cannot
resurrect a bucket key the chokepoints deleted.
- Two write paths: `setBadgesOfKind` is the system's bulk
replace-one-kind recompute path (`@internal`); extension rows go
through `registerBadge`/`deleteBadge` per row, identity-checked, so
independent writers cannot stomp each other.
resurrect a bucket key the chokepoints deleted. `LGraph.add`
registers the node only after `onNodeAdded`: the store write wakes
the system's watcher and queues Vue's flush microtask, which must not
overtake the paste-scan microtask `useErrorClearingHooks` enqueues
from `onNodeAdded`.
- One write path: the system replaces a node's rows wholesale via
`setBadges` on every recompute, so no intermediate per-kind state is
ever observable.
- The shell still reads `node.constructor.nodeData` and `node.inputs`
(untracked instance state) to map pricing input names to slot
indices — parity with the legacy closures. Those reads become store
lookups when slot data is store-backed (node data store draft).
- Core rows are fine-grained — one row per part in lifecycle, id, source
order — with one visibility rule (`badgeTextVisible`, the legacy
semantics: `HideBuiltIn` respected for every part). Joining,
bracket decoration, and truncation are renderer presentation and move
to the slice-B legacy draw cache. Rows store lifecycle text with the
`[]` brackets trimmed. Known unification effects: the Vue renderer
gains `HideBuiltIn` handling for id badges, and core nodes' `🦊`
source row becomes data the Vue partition may substitute with its
Comfy-logo chip.
- Core rows are fine-grained — one row per part, tagged
`part: 'lifecycle' | 'id' | 'source'` and carrying the raw projected
text — with one visibility rule (`badgeTextVisible`, the legacy
semantics: `HideBuiltIn` respected for every part). Each renderer owns
presentation: the legacy draw cache joins parts in id, lifecycle,
source order and truncates; the Vue partition trims lifecycle
brackets, and replaces a built-in node's source row with its
Comfy-logo chip. Known unification effect: the Vue renderer gains
`HideBuiltIn` handling for id and lifecycle badges on built-in nodes.
- A credits row is emitted only when the display price label is
non-empty; async pricing fills it via the per-node revision ref.
- Subgraph credits aggregation is not yet in the system — it stays on
the `updateSubgraphCredits` closure path until open decision 3 below
is resolved.

## Open decisions (interview pending)

1. **Legacy `node.badges` surface** — recommended: a converting
accessor exposing the node's `BadgeData[]` proxy; bare
`LGraphBadge`/thunk pushes auto-convert (thunk evaluated once,
`Image` icons dropped) with a one-time deprecation warning pointing
at the store API. Alternatives: delete the property outright, or a
read-only view. Ecosystem scan found zero genuine third-party
writers; ADR 0008 extension-impact guidance applies regardless.
2. **`node.badgePosition`** — recommended: delete (single writer sets a
constant `TopRight` on every node; single reader; renderer policy,
not badge data). Deprecated accessor warns on write.
3. **Subgraph credits aggregation triggers** — recommended: the three
existing events (`litegraph:set-graph`, `subgraph-converted`,
`afterConfigureGraph`) bump a revision the system watches; swap to
reactive `SubgraphStructure` dependencies when that state is
store-backed.

## Scope and sequencing
## Implementation notes (slice B)

- Wrapper `SubgraphNode` credits rows are aggregated by the system over
the inner (recursively collected, non-wrapper) api nodes — the same
count basis as the old unconditional per-api-node badges: several
collapse to `Partner Nodes x N` (localized), exactly one shows its
price with the wrapper's promoted widget values overriding the inner
node's own. The aggregation tracks the inner nodes' pricing
revisions, the registered-node set, and a structure revision.
`useNodePricing` caches labels per signature so a leaf's own read and
its wrapper's override read do not evict each other and re-schedule
forever.
- Legacy `drawBadges` renders the store rows through a per-node
memoized `LGraphBadge` cache (decision 5) keyed on the rows array's
identity — wholesale replacement makes identity the change signal, so
the per-frame path allocates nothing on cache hits. `iconKey` resolves
through a generic litegraph `badgeIconRegistry`, with the `credits`
icon registered when the system starts.
- The Vue renderer samples `node.badges` whenever its partition computed
re-runs; live array mutation and ticking thunks are visible per frame
only in the legacy canvas. Array interception was considered and
rejected: it cannot see thunk output changes (the dominant ecosystem
pattern), so it buys property patching without covering the real case.
If a pack demonstrably needs live Vue updates, the escalation is a
reactive accessor declared on `LGraphNode` itself, not renderer-side
`defineProperty`.

## Resolved decisions (2026-07-06 interview)

1. **Legacy `node.badges` surface — kept as a raw extension-only push
surface.** Directive: delete unless actively used. A GitHub-wide scan
found three custom-node packs actively writing it
(ComfyUI-Wildcard-Pipeline pushes and splices `LGraphBadge`
instances; ComfyUI-Enhancement-Utils and ComfyUI-XENodes push
per-frame getter thunks for ticking execution-time badges), so the
array stays, is no longer written by core/credits code, and both
renderers append it after the store rows — thunks still evaluate per
frame in the legacy canvas. The earlier "zero third-party writers"
scan was wrong.
2. **`node.badgePosition` — deleted**, along with the `BadgePosition`
enum. Zero uses outside this repo; the legacy canvas now always
renders badges top-right (the only surviving behaviour). A no-op
deprecated accessor remains and warns on access.
3. **Subgraph credits aggregation triggers — event-bumped revision.**
`litegraph:set-graph`, `subgraph-converted`, and
`afterConfigureGraph` bump `bumpSubgraphCreditsRevision()`; swap to
reactive `SubgraphStructure` dependencies when that state is
store-backed. Aggregation behaviour itself is preserved (explicit
user requirement).

## Prototype: derive-on-read (2026-07-15)

Badge rows are derived presentation, not authoritative entity state:
every row is a pure projection of settings, node definitions, palette,
pricing, and graph structure. Materializing that projection into a store
made the registration/watcher/scope machinery cache invalidation. The
prototype replaces the store with a memoized derivation:

- `nodeBadges(node)` in `src/systems/badgeSystem.ts` — one lazy
`computed` per node instance in a `WeakMap`. Entries die with their
nodes (workflow loads create new instances), so registration,
unregistration, teardown, and the stale-bucket bug class do not exist.
`computeBadges` stays pure and data-first; the authoritative sources
of truth remain the settings/def/palette/pricing stores and the graph.
- `LGraph`'s ref-backed `id` and `_version` (bumped by
`incrementVersion()` at the `add`/`remove`/`clear` chokepoints and
read by the `nodes` getter) — the revision signals replacing store
bucket membership, `subgraphCreditsRevision`, and the live-graph-id
seams: graph-id-keyed reads and subgraph aggregation re-resolve after
loads and structural changes. Bumps only invalidate; recomputes happen
lazily on the next read.
- `setBadgeRowsProvider` (in `nodeBadgeDraw.ts`) — a one-function seam
installed by `useNodeBadge`, so litegraph never imports the
derivation's pricing/nodeDef dependency graph (same acyclicity
property the store's import-light trio provided). The identity-keyed
draw cache is unchanged: a computed returns the same array until it
recomputes.

Trade-offs accepted: badge rows are no longer enumerable per graph
(`PartnerNodesList` traverses the graph via `mapUniqueNodes`
instead of querying a bucket), and the structure revision is coarse —
any structural change invalidates all badge computeds, which is cheap
because invalidation is a flag and recomputation is per-read.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
Slices: (A) store + `BadgeData` + system for core and credits +
chokepoint registration; (B) consumer cutover — Vue partition query,
Expand Down
11 changes: 0 additions & 11 deletions src/composables/graph/useGraphNodeManager.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ import type { NodeId } from '@/types/nodeId'

import type {
LGraph,
LGraphBadge,
LGraphNode,
LGraphTriggerAction,
LGraphTriggerEvent,
Expand All @@ -23,8 +22,6 @@ import type {
import type { TitleMode } from '@/lib/litegraph/src/types/globalEnums'
import { NodeSlotType } from '@/lib/litegraph/src/types/globalEnums'

type Badges = (LGraphBadge | (() => LGraphBadge))[]

const reactiveArrayNodes = new WeakSet<LGraphNode>()

export interface VueNodeData {
Expand All @@ -35,7 +32,6 @@ export interface VueNodeData {
title: string
type: string
apiNode?: boolean
badges?: Badges
bgcolor?: string
color?: string
flags?: {
Expand Down Expand Up @@ -155,7 +151,6 @@ export function extractVueNodeData(node: LGraphNode): VueNodeData {
executing: false,
subgraphId,
apiNode: node.constructor?.nodeData?.api_node ?? false,
badges: node.badges,
hasErrors: !!node.has_errors,
inputs,
outputs,
Expand Down Expand Up @@ -386,12 +381,6 @@ export function useGraphNodeManager(graph: LGraph): GraphNodeManager {
showAdvanced: Boolean(propertyEvent.newValue)
})
break
case 'badges':
vueNodeData.set(nodeId, {
...currentData,
badges: propertyEvent.newValue as Badges
})
break
}
}
},
Expand Down
Loading
Loading