Skip to content

WIDGET_SERIALIZATION.md

Latest commit

 

History

History
58 lines (38 loc) · 5.28 KB

WIDGET_SERIALIZATION.md

File metadata and controls

58 lines (38 loc) · 5.28 KB

Widget Serialization: widget.serialize vs widget.options.serialize

Two properties named serialize exist at different levels of a widget object. They control different serialization layers and are checked by completely different code paths.

widget.serialize — Controls workflow persistence. Checked by LGraphNode.serialize() and configure() when reading/writing widgets_values in the workflow JSON. When false, the widget is skipped in both serialization and deserialization. Used for UI-only widgets (image previews, progress text, audio players). Typed as IBaseWidget.serialize in src/lib/litegraph/src/types/widgets.ts.

widget.options.serialize — Controls prompt/API serialization. Checked by executionUtil.ts when building the API payload sent to the backend. When false, the widget is excluded from prompt inputs. Used for client-side-only controls (control_after_generate, combo filter lists) that the server doesn't need. Typed as IWidgetOptions.serialize in src/lib/litegraph/src/types/widgets.ts.

These correspond to the two data formats in ComfyMetadata embedded in output files (PNG, GLTF, WebM, AVIF, etc.): widget.serialize → ComfyMetadataTags.WORKFLOW, widget.options.serialize → ComfyMetadataTags.PROMPT.

Permutation table

widget.serialize widget.options.serialize In workflow? In prompt? Examples
✅ default ✅ default Yes Yes seed, cfg, sampler_name
✅ default ❌ false Yes No control_after_generate, combo filter list
❌ false ✅ default No Yes No current usage (would be a transient value computed at queue time)
❌ false ❌ false No No Image/video previews, audio players, progress text

Gotchas

  • addWidget('combo', name, value, cb, { serialize: false }) puts serialize into widget.options, not onto widget directly. These are different properties consumed by different systems.
  • LGraphNode.serialize() checks widget.serialize === false (line 967). It does not check widget.options.serialize. A widget with options.serialize = false is still included in widgets_values.
  • LGraphNode.serialize() only writes widgets_values if this.widgets is truthy. Nodes that create widgets dynamically (like PrimitiveNode) will have no widgets_values in serialized output if serialized before widget creation — even if this.widgets_values exists on the instance from a prior configure() call.
  • widget.options.serialize is typed as IWidgetOptions.serialize — both properties share the name serialize but live at different levels of the widget object.

PrimitiveNode and copy/paste

PrimitiveNode creates widgets dynamically on connection — it starts as an empty polymorphic node and morphs to match its target widget in _onFirstConnection(). This interacts badly with the copy/paste pipeline.

The clone→serialize gap

LGraphCanvas._serializeItems() copies nodes via item.clone()?.serialize() (line 3911). For PrimitiveNode this fails:

  1. clone() calls this.serialize() on the original node (which has widgets, so widgets_values is captured correctly).
  2. clone() creates a fresh PrimitiveNode via LiteGraph.createNode() and calls configure(data) on it — this stores widgets_values on the instance.
  3. But the fresh PrimitiveNode has no this.widgets (widgets are created only on connection), so when serialize() is called on the clone, LGraphNode.serialize() skips the widgets_values block entirely (line 964: if (widgets && this.serialize_widgets)).

Result: widgets_values is silently dropped from the clipboard data.

Why seed survives but control_after_generate doesn't

When the pasted PrimitiveNode reconnects to the pasted target node, _createWidget() copies theirWidget.value from the target (line 254). This restores the primary widget value (e.g., seed).

But control_after_generate is a secondary widget created by addValueControlWidgets(), which reads its initial value from this.widgets_values?.[1] (line 263). That value was lost during clone→serialize, so it falls back to 'fixed' (line 265).

See ADR-0006 for proposed fixes and design tradeoffs.

Code references

  • widget.serialize checked: src/lib/litegraph/src/LGraphNode.ts serialize() and configure()
  • widget.options.serialize checked: src/utils/executionUtil.ts
  • widget.options.serialize set: src/scripts/widgets.ts addValueControlWidgets()
  • widget.serialize set: src/composables/node/useNodeImage.ts, src/extensions/core/previewAny.ts, etc.
  • Metadata types: src/types/metadataTypes.ts
  • PrimitiveNode: src/extensions/core/widgetInputs.ts
  • Copy/paste serialization: src/lib/litegraph/src/LGraphCanvas.ts _serializeItems()
  • Clone: src/lib/litegraph/src/LGraphNode.ts clone()