Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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: 3 additions & 3 deletions browser_tests/tests/actionbar.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ webSocketTest.describe(
const sampler = window.app!.graph._nodes.find(
(node) => node.type === 'KSampler'
)
const control = sampler?.widgets?.find(
(widget) => widget.name === 'control_after_generate'
)
const control = sampler
?.getLayoutWidgets()
.find((widget) => widget.name === 'control_after_generate')
if (!control) throw new Error('seed control widget missing')
control.value = 'fixed'
;(
Expand Down
6 changes: 3 additions & 3 deletions browser_tests/tests/selectionToolboxActions.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -320,9 +320,9 @@ test.describe('Selection Toolbox - Button Actions', { tag: '@ui' }, () => {
const sampler = window.app!.graph._nodes.find(
(node) => node.type === 'KSampler'
)
const control = sampler?.widgets?.find(
(widget) => widget.name === 'control_after_generate'
)
const control = sampler
?.getLayoutWidgets()
.find((widget) => widget.name === 'control_after_generate')
if (!control) throw new Error('seed control widget missing')
control.value = 'randomize'
})
Expand Down
4 changes: 2 additions & 2 deletions browser_tests/tests/subgraph/subgraphPromotion.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ test.describe(
const ksampler = await comfyPage.nodeOps.getNodeRefById('1')
await ksampler.click('title')

const stepsWidget = await ksampler.getWidget(2)
const stepsWidget = await ksampler.getWidgetByName('steps')
const widgetPos = await stepsWidget.getPosition()
await comfyPage.canvasOps.mouseClickAt(widgetPos, { button: 'right' })

Expand All @@ -270,7 +270,7 @@ test.describe(
await subgraphNode.navigateIntoSubgraph()

const ksampler = await comfyPage.nodeOps.getNodeRefById('1')
const stepsWidget = await ksampler.getWidget(2)
const stepsWidget = await ksampler.getWidgetByName('steps')
const widgetPos = await stepsWidget.getPosition()

await comfyPage.canvasOps.mouseClickAt(widgetPos, { button: 'right' })
Expand Down
16 changes: 16 additions & 0 deletions docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,22 @@ may retain a partial registration or removal.
measuring remaining use over a stated observation window. Define the
threshold and rollback condition in the deprecation proposal.

### Migrate widget controls

Control rows no longer appear in `node.widgets`. Extensions must use these
replacements:

- Call `addValueControlWidget()` or `addValueControlWidgets()` to configure a
target widget. Read its `controlConfig` instead of finding a linked control
widget.
- Call `node.getLayoutWidgets()` only when code needs the transient rows used
by classic canvas layout. Do not store or serialize those projections.
- Keep workflow persistence positional. A controlled target serializes as
`[targetValue, controlMode]`, followed by the filter for controls that have
one. Control values are not part of API prompt serialization.
- Remove extension callbacks attached to a control row. The graph-level control
system updates the target and invokes the target widget callback.

Removing the compatibility adapter requires a follow-up ADR or an amendment to
this one.

Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/domains/boundaries.json
Original file line number Diff line number Diff line change
Expand Up @@ -1390,7 +1390,6 @@
"src/composables/node/useWatchWidget.test.ts",
"src/core/graph/widgets/__fixtures__/**",
"src/core/graph/widgets/comboWidgetInventory.ts",
"src/core/graph/widgets/controlWidgetMarker.ts",
"src/core/graph/widgets/dynamicGroupWidget.ts",
"src/core/graph/widgets/dynamicGroupWidget.test.ts",
"src/core/graph/widgets/dynamicInputSpec.ts",
Expand All @@ -1403,8 +1402,8 @@
"src/core/graph/widgets/nodeWidgetValues.test.ts",
"src/core/graph/widgets/revealDynamicInputSlot.ts",
"src/core/graph/widgets/revealDynamicInputSlot.test.ts",
"src/core/graph/widgets/valueControl.ts",
"src/core/graph/widgets/valueControl.test.ts",
"src/core/graph/widgets/control/valueControl.ts",
"src/core/graph/widgets/control/valueControl.test.ts",
"src/core/graph/widgets/valueControlWidgets.ts",
"src/core/graph/widgets/valueControlWidgets.controlAfterGenerateName.test.ts",
"src/extensions/core/customWidgets.ts",
Expand Down Expand Up @@ -1746,6 +1745,7 @@
"src/scripts/errorNodeWidgets.ts",
"src/scripts/errorNodeWidgets.test.ts",
"src/scripts/widgets.ts",
"src/scripts/widgets.test.ts",
"src/stores/domWidgetStore.ts",
"src/stores/domWidgetStore.test.ts",
"src/stores/widgetStore.ts",
Expand Down
7 changes: 2 additions & 5 deletions docs/architecture/domains/records/node-widgets.domain.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"id": "node-widgets",
"capability": "Node widgets",
Expand All @@ -12,9 +12,6 @@
{
"path": "src/core/graph/widgets/comboWidgetInventory.ts"
},
{
"path": "src/core/graph/widgets/controlWidgetMarker.ts"
},
{
"path": "src/core/graph/widgets/dynamicGroupWidget.ts"
},
Expand All @@ -37,7 +34,7 @@
"path": "src/core/graph/widgets/revealDynamicInputSlot.ts"
},
{
"path": "src/core/graph/widgets/valueControl.ts"
"path": "src/core/graph/widgets/control/valueControl.ts"
},
{
"path": "src/core/graph/widgets/valueControlWidgets.ts"
Expand Down Expand Up @@ -135,7 +132,7 @@
"checks": [
"src/core/graph/widgets/dynamicWidgets.test.ts",
"src/core/graph/widgets/dynamicGroupWidget.test.ts",
"src/core/graph/widgets/valueControl.test.ts",
"src/core/graph/widgets/control/valueControl.test.ts",
"src/core/graph/widgets/valueControlWidgets.controlAfterGenerateName.test.ts"
]
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"checks": [
"src/core/graph/subgraph/resolveConcretePromotedWidget.test.ts",
"src/core/graph/subgraph/promotedInputWidget.test.ts",
"src/core/graph/subgraph/promotedWidgetControl.test.ts",
"src/core/graph/widgets/control/widgetControlSystem.promoted.test.ts",
"src/core/graph/subgraph/promotionAfterReplacement.test.ts"
]
},
Expand Down
139 changes: 139 additions & 0 deletions docs/specs/widget-control-ecs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Widget Control ECS

## Objective

Replace `control_after_generate` widgets with plain control state attached to
the widget they control and one graph-level system that advances controlled
values during queueing.

The workflow format and user-visible controls remain compatible. The runtime
model changes from linked widgets with callbacks to a Component and System.

## Model

Each controlled target has one `WidgetControlState` keyed by the target's
canonical `WidgetId`:

```ts
interface WidgetControlState {
mode: 'fixed' | 'increment' | 'increment-wrap' | 'decrement' | 'randomize'
filter?: string
hasExecuted: boolean
}
```

- `filter` exists only for combo controls that expose a filter field.
- `hasExecuted` implements the existing first-run skip in "before" mode.
- The component contains no widget, node, graph, callback, or DOM references.
- The target value and options remain in `widgetValueStore`.
- Popover, focus, and hover state remain local to the view.

The component is registered when the target receives its `WidgetId`, released
with the target, renamed with the target, and cleared with the root graph.
Re-registration preserves the current component state. Replacing the target
with a different widget type removes stale control state.

## System

`runWidgetControl(rootGraph, phase, controlMode)` runs once in each existing queue
phase.

1. Skip the phase not selected by the captured `controlMode`.
2. Query controls scoped to the root graph.
3. Derive link-fed target IDs from the live graph and skip them.
4. In "before" mode, mark the component executed and skip its first run.
5. Compute the next value with the existing pure value-control rules.
6. Write through `widgetValueStore`.

There is no general ECS scheduler. The existing queue lifecycle is the system's
explicit scheduling boundary.

## Presentation

The control is not present in `node.widgets` and is not identified through
`linkedWidgets`.

- Classic canvas rendering projects transient mode and filter rows beside the
target. Projection objects may be cached for stable layout but hold no source
of truth.
- Vue rendering reads and updates `WidgetControlState` directly by target
`WidgetId`.
- Control labels continue to reflect the before/after user setting.

## Persistence

Existing workflows retain their positional layout:

- Number: `[targetValue, controlMode]`
- Combo: `[targetValue, controlMode, filter]`

Serialization appends component values after each controlled target.
Configuration consumes valid control slots after registering the target. A
missing or invalid control slot must not consume the next target widget's
value. Control values remain absent from API prompt serialization.

Named widget values include compatibility entries for each control mode and
optional filter, using the same stable names as the classic projections.
API prompt serialization excludes these control entries.

## Promotion and graph scope

A promoted target is controlled at the graph level where its authoritative
value lives. Promotion copies the source control configuration to a component
keyed by the host target's `WidgetId`; host and interior components are
independent after promotion.

The system queries the root graph once and handles regular, nested, and
promoted targets uniformly. It must not traverse into an interior widget at
execution time to mutate a promoted value.

## Compatibility constraints

- Preserve fixed, increment, decrement, randomize, combo wrap, and combo
filtering behavior.
- Preserve before-mode first-run behavior and after-mode timing.
- Preserve control updates during partial execution and suppress link-fed
targets.
- Preserve positional workflow round trips, including older files with omitted
control slots.
- Preserve target widget callbacks required by custom widgets when a system
changes a value.
- Preserve the exported `addValueControlWidget(s)` call signatures and return
component-backed projections for legacy callers.
- Do not add state or behavior to `LGraphNode`, `LGraphCanvas`, `LGraph`, or
`Subgraph` beyond narrow projection and lifecycle integration.

## Removal

Once all presentation and persistence paths use the component, remove:

- Real `control_after_generate` and filter widgets from `node.widgets`.
- `IS_CONTROL_WIDGET` and control-widget duck typing.
- Per-control `beforeQueued` and `afterQueued` closures.
- Runtime control identity through `linkedWidgets`.
- The separate promoted-widget control execution path and its `WeakSet`.

## Acceptance criteria

1. A regular number or combo control behaves identically before and after
workflow save/load.
2. Classic and Vue node renderers edit the same component state.
3. Partial executions advance controls, but link-fed targets do not advance.
4. Before mode skips the first execution and advances subsequent executions.
5. Promoted and nested promoted targets advance their authoritative host value
exactly once.
6. Deleting, replacing, renaming, or clearing a target cannot leave an active
orphan control.
7. Existing workflow fixtures round-trip without changing positional value
meaning.
8. No control form widget participates in prompt serialization or
`node.widgets` iteration.

## Implementation order

1. Component state and lifecycle in the widget value store.
2. Pure value transition and graph-level queue system.
3. Registration, classic projection, and positional persistence.
4. Vue component bridge.
5. Promotion copy and removal of the legacy promoted execution path.
6. Delete obsolete widget markers, callbacks, and compatibility code.
19 changes: 19 additions & 0 deletions packages/graph-model/src/widgetState.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@ import type { IBaseWidget, IWidgetOptions } from './widgets'
import type { NodeId } from './nodeId'
import type { WidgetValue } from './widgetValue'

export type ValueControlMode =
| 'fixed'
| 'increment'
| 'increment-wrap'
| 'decrement'
| 'randomize'

export interface WidgetState<
TValue = WidgetValue,
TType extends string = string,
Expand All @@ -28,3 +35,15 @@ export type WidgetStateInit<
name?: string
y?: number
}

export interface WidgetControlState {
mode: ValueControlMode
filter?: string
hasExecuted: boolean
}

export interface WidgetControlConfig {
mode: ValueControlMode
hasFilter: boolean
filter?: string
}
3 changes: 3 additions & 0 deletions packages/graph-model/src/widgets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import type { BoundingBox } from './boundingBoxes'
import type { LightInfoEntry } from '@comfyorg/viewport3d/lightInfo/types'
import type { WidgetValue } from './widgetValue'
import type { WidgetId } from './widgetId'
import type { WidgetControlConfig } from './widgetState'
import type {
WidgetSurfaces,
WidgetVisibilityComponent
Expand Down Expand Up @@ -538,6 +539,8 @@ export interface IBaseWidget<

linkedWidgets?: IBaseWidget[]

controlConfig?: WidgetControlConfig

readonly widgetId?: WidgetId

name: string
Expand Down
Loading
Loading