diff --git a/calliope-backend/scripts/audit_reference_conversion.py b/calliope-backend/scripts/audit_reference_conversion.py
new file mode 100644
index 00000000..ee78efa3
--- /dev/null
+++ b/calliope-backend/scripts/audit_reference_conversion.py
@@ -0,0 +1,134 @@
+"""Compare bounded public-reference behavior to six supplied APIs, never mark ready.
+
+PYTHONPATH=src python scripts/audit_reference_conversion.py --repo .. --output report.json
+The report intentionally includes only supported fields/legacy links, alongside
+whole-graph blockers. It is not a substitute for compare_frontend_exports.py's
+source/version binding checks or a target node snapshot.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+from compare_frontend_exports import differences
+
+from calliope.comfyui.companions import load_companions
+from calliope.comfyui.delivery_scope import exclusion_for
+from calliope.comfyui.serialization_reference import (
+ PROFILE,
+ resolve_reference_link,
+ serialize_reference_widgets,
+)
+from calliope.comfyui.ui2api import convert, convert_reference
+
+
+def audit(repo: Path) -> dict:
+ rows = []
+ records = load_companions(repo / "docs/hel-892/supplied-api/manifest.json")
+ for path, record in records.items():
+ binding = record["binding"]
+ if exclusion_for(path):
+ continue
+ raw = (repo / path).read_bytes()
+ assert hashlib.sha1(raw).hexdigest() == binding["source_sha"]
+ assert hashlib.sha256(raw).hexdigest() == binding["source_sha256"]
+ source, api = json.loads(raw), json.loads(record["raw"])
+ assert convert(api).prompt is not None
+ nodes = {str(n["id"]): n for n in source["nodes"]}
+ links = {str(link[0]): link for link in source.get("links", [])}
+ fields, edges, unsupported = [], [], []
+ for nid, node in nodes.items():
+ if node.get("type") in ("Reroute", "Note", "MarkdownNote"):
+ continue
+ try:
+ values = serialize_reference_widgets(node)
+ except ValueError as exc:
+ unsupported.append({"node_id": nid, "type": node["type"], "reason": str(exc)})
+ else:
+ for name, value in values.items():
+ expected = api.get(nid, {}).get("inputs", {}).get(name)
+ fields.append(
+ {
+ "node_id": nid,
+ "field": name,
+ "source_reference": value,
+ "api": expected,
+ "differences": differences(expected, value),
+ }
+ )
+ for socket in node.get("inputs", []):
+ lid = socket.get("link")
+ if lid is None:
+ continue
+ try:
+ endpoint = resolve_reference_link(nodes, links, lid)
+ except (ValueError, KeyError, TypeError, AttributeError) as exc:
+ edges.append(
+ {
+ "node_id": nid,
+ "input": socket["name"],
+ "status": "unsupported",
+ "reason": str(exc),
+ }
+ )
+ continue
+ expected = api.get(nid, {}).get("inputs", {}).get(socket["name"])
+ edges.append(
+ {
+ "node_id": nid,
+ "input": socket["name"],
+ "via_reroute": nodes[str(links[str(lid)][1])]["type"] == "Reroute",
+ "source_reference": endpoint,
+ "api": expected,
+ "differences": differences(expected, endpoint),
+ }
+ )
+ candidate = convert_reference(source)
+ rows.append(
+ {
+ "id": binding["id"],
+ "source_path": path,
+ "source_sha256": binding["source_sha256"],
+ "api_sha256": binding["export_sha256"],
+ "source_frontend_version": source.get("extra", {}).get("frontendVersion"),
+ "export_frontend_version": binding["frontend_version"],
+ "whole_prompt_available": candidate.prompt is not None,
+ "whole_prompt_differences": differences(api, candidate.prompt)
+ if candidate.prompt is not None
+ else None,
+ "whole_prompt_issues": candidate.issues,
+ "production_prompt_available": convert(source).prompt is not None,
+ "serialized_fields": fields,
+ "topology_edges": edges,
+ "unsupported_widget_nodes": unsupported,
+ "executable": False,
+ "execution_verified": False,
+ }
+ )
+ return {
+ "profile": PROFILE,
+ "authority": "public_reference_only_not_object_info",
+ "comparison_scope": "supported root scalar widgets and legacy root link endpoints only",
+ "target_version_match": "unknown",
+ "whole_source_equivalence_verified": False,
+ "execution_verified": False,
+ "cases": rows,
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--repo", type=Path, required=True)
+ parser.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ report = audit(args.repo)
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+ print(json.dumps({"reference_only": True, "active_cases": len(report["cases"])}))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/calliope-backend/scripts/verify_frontend_sources.py b/calliope-backend/scripts/verify_frontend_sources.py
new file mode 100644
index 00000000..c36502e6
--- /dev/null
+++ b/calliope-backend/scripts/verify_frontend_sources.py
@@ -0,0 +1,51 @@
+"""Verify pinned frontend/core source bytes; never import or execute upstream code."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+from urllib.request import urlopen
+
+
+def verify(directory: Path, fetch: bool = False) -> dict:
+ manifest = json.loads((directory / "sources.json").read_text())
+ verified = []
+ for source in manifest["sources"]:
+ path = directory / source["local_file"]
+ if fetch:
+ with urlopen(source["raw_url"], timeout=30) as response:
+ raw = response.read()
+ else:
+ raw = path.read_bytes()
+ if hashlib.sha256(raw).hexdigest() != source["sha256"]:
+ raise ValueError(f"哈希不一致:{source['id']}")
+ lines = raw.decode("utf-8").splitlines()
+ for start, end in source["lines"]:
+ if not 1 <= start <= end <= len(lines):
+ raise ValueError(f"行号越界:{source['id']}")
+ if fetch:
+ path.write_bytes(raw)
+ verified.append({"id": source["id"], "sha256": source["sha256"]})
+ return {
+ "authority": "public_reference_only",
+ "sources_verified": verified,
+ "upstream_code_executed": False,
+ "target_version_match": "unknown",
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--source-dir", type=Path, required=True)
+ parser.add_argument("--fetch", action="store_true")
+ parser.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ report = verify(args.source_dir, args.fetch)
+ args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+ print(f"verified {len(report['sources_verified'])} sources; no upstream execution")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/calliope-backend/src/calliope/comfyui/serialization_reference.py b/calliope-backend/src/calliope/comfyui/serialization_reference.py
new file mode 100644
index 00000000..facd2368
--- /dev/null
+++ b/calliope-backend/src/calliope/comfyui/serialization_reference.py
@@ -0,0 +1,143 @@
+"""Small, explicit public-reference contract, never a target object_info snapshot.
+
+Sources and limits: docs/hel-892/serialization-evidence/sources.json.
+Only unmodified scalar core widgets are covered. No plugin, dynamic prompt,
+seed controller, subgraph, bypass or custom serializeValue is inferred.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+PROFILE = "comfy-frontend-1.37.11-core-reference"
+
+# Widget construction order, including workflow-only upload button. A None type
+# is a workflow-persisted widget with options.serialize=false in graphToPrompt.
+_LAYOUTS = {
+ "Canny": (("low_threshold", float), ("high_threshold", float)),
+ "ImageStitch": (
+ ("direction", str),
+ ("match_image_size", bool),
+ ("spacing_width", int),
+ ("spacing_color", str),
+ ),
+ "LoadImage": (("image", str), ("upload", None)),
+ "PreviewImage": (),
+}
+
+
+def reference_definitions() -> dict[str, Any]:
+ """Only public core reference schemas; no model/file availability assertion."""
+
+ def spec(required, outputs, optional=None):
+ return {
+ "input": {
+ "required": {k: [v] for k, v in required.items()},
+ "optional": {k: [v] for k, v in (optional or {}).items()},
+ },
+ "output": outputs,
+ }
+
+ return {
+ "Canny": spec(
+ {"image": "IMAGE", "low_threshold": "FLOAT", "high_threshold": "FLOAT"}, ["IMAGE"]
+ ),
+ "ImageStitch": spec(
+ {
+ "image1": "IMAGE",
+ "direction": "COMBO",
+ "match_image_size": "BOOLEAN",
+ "spacing_width": "INT",
+ "spacing_color": "COMBO",
+ },
+ ["IMAGE"],
+ {"image2": "IMAGE"},
+ ),
+ "LoadImage": spec({"image": "COMBO"}, ["IMAGE", "MASK"]),
+ "PreviewImage": spec({"images": "IMAGE"}, []),
+ }
+
+
+def serialize_reference_widgets(node: dict[str, Any]) -> dict[str, Any]:
+ """Apply only the pinned identity serializers; reject any extra/missing value."""
+ if node.get("mode", 0) != 0:
+ raise ValueError("静音/旁路不在序列化参考契约内")
+ properties = node.get("properties") or {}
+ expected_version = "0.17.0" if node.get("type") == "ImageStitch" else "0.21.1"
+ if (
+ properties.get("cnr_id", "comfy-core") != "comfy-core"
+ or properties.get("ver", expected_version) != expected_version
+ ):
+ raise ValueError("源节点声明与固定核心参考版本不符")
+ layout = _LAYOUTS.get(node.get("type"))
+ values = node.get("widgets_values", [])
+ if layout is None or not isinstance(values, list) or len(values) != len(layout):
+ raise ValueError("控件数量/形式或节点类型不在固定参考契约内")
+ result = {}
+ for (name, kind), value in zip(layout, values):
+ if kind is None:
+ if value != "image":
+ raise ValueError("upload 不是已知的前端按钮占位值")
+ continue
+ if (kind is float and type(value) not in (int, float)) or (
+ kind is not float and type(value) is not kind
+ ):
+ raise ValueError(f"{name} 的类型不符合固定标量契约")
+ result[name] = value
+ return result
+
+
+def validate_reroute(node: dict[str, Any]) -> None:
+ if (
+ node.get("mode", 0) != 0
+ or node.get("widgets_values") not in (None, [])
+ or len(node.get("inputs", [])) != 1
+ or len(node.get("outputs", [])) != 1
+ or node["inputs"][0].get("name") != ""
+ ):
+ raise ValueError("Reroute 必须是无控件、单入口/出口、非旁路的固定参考形式")
+
+
+def resolve_reference_link(nodes, links, link_id) -> list[Any]:
+ """Trace legacy six-field links through slot 0 of Reroute, preserving source slot.
+
+ Validate reciprocal endpoints at every hop. Fail instead of the frontend's
+ optional discard of dangling links. This helper is also usable to compare
+ topology alone when unsupported third-party widgets block the whole prompt.
+ It makes no assertion about those third-party nodes' input/output types.
+ """
+ seen = set()
+ while True:
+ key = str(link_id)
+ if key in seen:
+ raise ValueError("Reroute 链路循环")
+ seen.add(key)
+ link = links.get(key)
+ if not isinstance(link, list) or len(link) != 6:
+ raise ValueError("缺失连线或非六字段旧式连线")
+ _, origin, output_slot, target, input_slot, _ = link
+ upstream, downstream = nodes.get(str(origin)), nodes.get(str(target))
+ if not upstream or not downstream:
+ raise ValueError("悬空节点")
+ for slot, sockets in (
+ (output_slot, upstream.get("outputs", [])),
+ (input_slot, downstream.get("inputs", [])),
+ ):
+ if type(slot) is not int or not 0 <= slot < len(sockets):
+ raise ValueError("连线槽无效")
+ outgoing = upstream["outputs"][output_slot].get("links") or []
+ if (
+ sum(str(x) == key for x in outgoing) != 1
+ or str(downstream["inputs"][input_slot].get("link")) != key
+ ):
+ raise ValueError("连线与入口/出口记录不互相对应")
+ if upstream.get("mode", 0) != 0 or downstream.get("mode", 0) != 0:
+ raise ValueError("静音/旁路不在追线参考契约内")
+ if upstream.get("type") != "Reroute":
+ return [str(origin), output_slot]
+ validate_reroute(upstream)
+ if output_slot != 0:
+ raise ValueError("Reroute 出口必须为零槽")
+ link_id = upstream["inputs"][0].get("link")
+ if link_id is None:
+ raise ValueError("Reroute 无上游连线")
diff --git a/calliope-backend/src/calliope/comfyui/ui2api.py b/calliope-backend/src/calliope/comfyui/ui2api.py
index 90dbd592..62da560d 100644
--- a/calliope-backend/src/calliope/comfyui/ui2api.py
+++ b/calliope-backend/src/calliope/comfyui/ui2api.py
@@ -2,7 +2,9 @@
object_info does not define custom frontend widget serialization. Only named
widgets pass. Even input_order cannot prove arbitrary frontend serialization.
-Subgraphs, virtual nodes, seed extra controls, mute and bypass need API exports.
+The separate convert_reference entry point supports a bounded public-source
+profile for offline comparison only; it never changes production eligibility.
+Subgraphs, seed extra controls, mute and bypass remain unsupported.
"""
from __future__ import annotations
@@ -10,14 +12,47 @@ from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
+from .serialization_reference import (
+ PROFILE,
+ reference_definitions,
+ resolve_reference_link,
+ serialize_reference_widgets,
+ validate_reroute,
+)
+
@dataclass
class Conversion:
prompt: dict[str, Any] | None
issues: list[dict[str, Any]] = field(default_factory=list)
+ reference_only: bool = False
def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversion:
+ return _convert(source, object_info)
+
+
+def convert_reference(source: Any, profile: str = PROFILE) -> Conversion:
+ """Offline candidate only. Never consumed by production library import.
+
+ An unknown profile is rejected, not interpreted as a widget-order contract.
+ Public reference definitions cannot establish target execution eligibility.
+ """
+ if profile != PROFILE or not isinstance(source, dict) or "nodes" not in source:
+ return Conversion(
+ None,
+ [{"code": "invalid_reference_contract", "message": "未知参考版本或不是 UI 图"}],
+ True,
+ )
+ try:
+ result = _convert(source, reference_definitions(), reference=True)
+ except (ValueError, TypeError, KeyError, AttributeError, IndexError) as exc:
+ return Conversion(None, [{"code": "invalid_reference_contract", "message": str(exc)}], True)
+ result.reference_only = True
+ return result
+
+
+def _convert(source, object_info=None, *, reference=False) -> Conversion:
issues: list[dict[str, Any]] = []
def fail(code: str, message: str, node_id: Any = "") -> None:
@@ -65,6 +100,29 @@ def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversio
if str(link[0]) in links:
fail("duplicate_link", "连线 ID 重复")
links[str(link[0])] = link
+ if reference:
+ frontend_version = (source.get("extra") or {}).get("frontendVersion")
+ if frontend_version is not None and frontend_version != "1.37.11":
+ fail("reference_frontend_mismatch", "源图声明的前端版本与固定参考不一致")
+ # Validate every stored link, even unused branches: never silently drop
+ # an unsupported connection to obtain a partial candidate.
+ for node in nodes.values():
+ for slot, socket in enumerate(node.get("inputs", [])):
+ lid = socket.get("link")
+ if lid is not None:
+ link = links.get(str(lid))
+ if not link or str(link[3]) != str(node["id"]) or link[4] != slot:
+ fail("reference_link_invalid", "输入与连线目标记录不对应", node["id"])
+ for slot, socket in enumerate(node.get("outputs", [])):
+ for lid in socket.get("links") or []:
+ link = links.get(str(lid))
+ if not link or str(link[1]) != str(node["id"]) or link[2] != slot:
+ fail("reference_link_invalid", "输出与连线来源记录不对应", node["id"])
+ for lid in links:
+ try:
+ resolve_reference_link(nodes, links, lid)
+ except (ValueError, TypeError, KeyError, AttributeError) as exc:
+ fail("reference_link_invalid", str(exc))
prompt = {}
for nid, node in nodes.items():
ct = node.get("type", "")
@@ -73,9 +131,19 @@ def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversio
if node.get("mode", 0) != 0:
fail("mode_requires_export", f"{ct} 包含静音/旁路状态,需 API 导出核对", nid)
continue
+ if reference and ct == "Reroute":
+ try:
+ validate_reroute(node)
+ resolve_reference_link(nodes, links, node["inputs"][0].get("link"))
+ except (ValueError, TypeError, KeyError, AttributeError) as exc:
+ fail("reference_link_invalid", str(exc), nid)
+ continue
spec = info.get(ct)
if not isinstance(spec, dict):
- fail("node_definition_unavailable", f"待提供目标机节点定义:{ct}", nid)
+ if reference:
+ fail("reference_node_unsupported", f"固定参考契约未覆盖节点:{ct}", nid)
+ else:
+ fail("node_definition_unavailable", f"待提供目标机节点定义:{ct}", nid)
continue
declared = {
**spec.get("input", {}).get("required", {}),
@@ -84,7 +152,19 @@ def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversio
sockets = {s["name"]: s for s in node.get("inputs", []) if "name" in s}
widgets = node.get("widgets_values") or []
inputs = {}
- if isinstance(widgets, dict):
+ if reference:
+ try:
+ inputs.update(serialize_reference_widgets(node))
+ if [s.get("type") for s in node.get("outputs", [])] != spec["output"]:
+ raise ValueError("源输出槽不符合固定参考契约")
+ names = [s.get("name") for s in node.get("inputs", [])]
+ allowed = set(declared) | ({"upload"} if ct == "LoadImage" else set())
+ if len(names) != len(set(names)) or set(names) - allowed:
+ raise ValueError("额外或重复输入槽不在固定参考契约内")
+ except (ValueError, TypeError, AttributeError) as exc:
+ fail("reference_widget_unverified", str(exc), nid)
+ continue
+ elif isinstance(widgets, dict):
if set(widgets) - set(declared):
fail("unknown_widget", f"{ct} 存在节点定义以外的具名控件", nid)
inputs.update({k: v for k, v in widgets.items() if k in declared})
@@ -111,6 +191,13 @@ def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversio
if node["inputs"][link[4]].get("name") != name or name not in declared:
fail("invalid_socket", f"输入 {name} 的目标槽不匹配", nid)
continue
+ if reference:
+ try:
+ resolved = resolve_reference_link(nodes, links, lid)
+ link = [link[0], resolved[0], resolved[1], *link[3:]]
+ except (ValueError, TypeError, KeyError, AttributeError) as exc:
+ fail("reference_link_invalid", str(exc), nid)
+ continue
upstream = nodes.get(str(link[1]))
outputs = info.get((upstream or {}).get("type"), {}).get("output", [])
if not upstream or not isinstance(link[2], int) or not 0 <= link[2] < len(outputs):
diff --git a/calliope-backend/tests/test_reference_serialization.py b/calliope-backend/tests/test_reference_serialization.py
new file mode 100644
index 00000000..884542c7
--- /dev/null
+++ b/calliope-backend/tests/test_reference_serialization.py
@@ -0,0 +1,235 @@
+"""Synthetic contract tests and bounded real-source comparison; no execution proof."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from pathlib import Path
+
+import pytest
+
+from calliope.comfyui.serialization_reference import (
+ reference_definitions,
+ resolve_reference_link,
+ serialize_reference_widgets,
+)
+from calliope.comfyui.ui2api import convert, convert_reference
+
+REPO = Path(__file__).resolve().parents[2]
+
+
+def synthetic_graph():
+ return {
+ "nodes": [
+ {
+ "id": 1,
+ "type": "LoadImage",
+ "widgets_values": ["测试.png", "image"],
+ "outputs": [{"type": "IMAGE", "links": [10]}, {"type": "MASK", "links": []}],
+ },
+ {
+ "id": 2,
+ "type": "Reroute",
+ "inputs": [{"name": "", "link": 10}],
+ "outputs": [{"type": "IMAGE", "links": [11]}],
+ },
+ {
+ "id": 3,
+ "type": "Reroute",
+ "inputs": [{"name": "", "link": 11}],
+ "outputs": [{"type": "IMAGE", "links": [12]}],
+ },
+ {
+ "id": 4,
+ "type": "Canny",
+ "widgets_values": [0.23, 0.91],
+ "inputs": [{"name": "image", "link": 12}],
+ "outputs": [{"type": "IMAGE", "links": [13]}],
+ },
+ {
+ "id": 5,
+ "type": "PreviewImage",
+ "widgets_values": [],
+ "inputs": [{"name": "images", "link": 13}],
+ "outputs": [],
+ },
+ ],
+ "links": [
+ [10, 1, 0, 2, 0, "IMAGE"],
+ [11, 2, 0, 3, 0, "IMAGE"],
+ [12, 3, 0, 4, 0, "IMAGE"],
+ [13, 4, 0, 5, 0, "IMAGE"],
+ ],
+ }
+
+
+def test_identity_widgets_upload_omission_and_reroute_chain():
+ graph = synthetic_graph()
+ before = copy.deepcopy(graph)
+ result = convert_reference(graph)
+ assert result.reference_only and not result.issues
+ assert set(result.prompt) == {"1", "4", "5"}
+ assert result.prompt["1"]["inputs"] == {"image": "测试.png"}
+ assert result.prompt["4"]["inputs"] == {
+ "image": ["1", 0],
+ "low_threshold": 0.23,
+ "high_threshold": 0.91,
+ }
+ assert result.prompt["5"]["inputs"] == {"images": ["4", 0]}
+ assert graph == before
+ assert convert(graph).prompt is None
+ assert not convert(graph).reference_only
+ # Even a matching input_order does not opt production into public contracts.
+ definitions = reference_definitions()
+ for spec in definitions.values():
+ spec["input_order"] = {"required": list(spec["input"]["required"])}
+ assert convert(graph, definitions).prompt is None
+
+
+def test_nonzero_original_source_slot_is_preserved_but_type_mismatch_rejected():
+ graph = synthetic_graph()
+ graph["nodes"][0]["outputs"][0]["links"] = []
+ graph["nodes"][0]["outputs"][1]["links"] = [10]
+ graph["links"][0][2] = 1
+ assert resolve_reference_link(
+ {str(n["id"]): n for n in graph["nodes"]},
+ {str(link[0]): link for link in graph["links"]},
+ 12,
+ ) == ["1", 1]
+ result = convert_reference(graph)
+ assert result.prompt is None
+ assert "link_type_unverified" in {i["code"] for i in result.issues}
+
+
+@pytest.mark.parametrize(
+ "change",
+ [
+ "cycle",
+ "missing_link",
+ "missing_node",
+ "negative_slot",
+ "bool_slot",
+ "wrong_target",
+ "output_disagrees",
+ "duplicate_link",
+ "missing_output_link",
+ "extra_reroute_input",
+ "reroute_widgets",
+ "bypass",
+ "subgraph",
+ "extra_widget",
+ "missing_widget",
+ "bool_numeric",
+ "dynamic_value",
+ "extra_input",
+ "ambiguous_output",
+ "node_version",
+ "node_provider",
+ "frontend_version",
+ ],
+)
+def test_unsupported_graph_never_returns_partial_prompt(change):
+ graph = synthetic_graph()
+ if change == "cycle":
+ graph["links"][0][1:3] = [3, 0]
+ graph["nodes"][2]["outputs"][0]["links"].append(10)
+ elif change == "missing_link":
+ graph["links"].pop(0)
+ elif change == "missing_node":
+ graph["nodes"].pop(0)
+ elif change in ("negative_slot", "bool_slot"):
+ graph["links"][0][2] = -1 if change == "negative_slot" else False
+ elif change == "wrong_target":
+ graph["links"][0][4] = 1
+ elif change == "output_disagrees":
+ graph["nodes"][0]["outputs"][0]["links"] = []
+ elif change == "duplicate_link":
+ graph["links"].append(graph["links"][0])
+ elif change == "missing_output_link":
+ graph["nodes"][0]["outputs"][0]["links"].append(999)
+ elif change == "extra_reroute_input":
+ graph["nodes"][1]["inputs"].append({"name": "", "link": None})
+ elif change == "reroute_widgets":
+ graph["nodes"][1]["widgets_values"] = [123]
+ elif change == "bypass":
+ graph["nodes"][1]["mode"] = 4
+ elif change == "subgraph":
+ graph["definitions"] = {"subgraphs": [{"id": "unsupported"}]}
+ elif change == "extra_widget":
+ graph["nodes"][3]["widgets_values"].append("randomize")
+ elif change == "missing_widget":
+ graph["nodes"][3]["widgets_values"].pop()
+ elif change in ("bool_numeric", "dynamic_value"):
+ graph["nodes"][3]["widgets_values"][0] = True if change == "bool_numeric" else {"x": 1}
+ elif change == "node_version":
+ graph["nodes"][3]["properties"] = {"cnr_id": "comfy-core", "ver": "9.9.9"}
+ elif change == "node_provider":
+ graph["nodes"][3]["properties"] = {"cnr_id": "unknown-plugin"}
+ elif change == "frontend_version":
+ graph["extra"] = {"frontendVersion": "9.9.9"}
+ elif change == "ambiguous_output":
+ graph["nodes"][0]["outputs"][1]["links"] = [10]
+ elif change == "extra_input":
+ graph["nodes"][3]["inputs"].append({"name": "custom", "link": None})
+ result = convert_reference(graph)
+ assert result.prompt is None and result.issues and result.reference_only
+ if change == "cycle":
+ assert any("循环" in issue["message"] for issue in result.issues)
+
+
+@pytest.mark.parametrize(
+ "source,profile",
+ [
+ (synthetic_graph(), "input_order_is_not_a_contract"),
+ ({"nodes": "malformed"}, None),
+ ({"nodes": [{"id": 1, "type": "LoadImage", "inputs": None}]}, None),
+ ],
+)
+def test_bad_contracts_rejected(source, profile):
+ result = convert_reference(source, profile) if profile else convert_reference(source)
+ assert result.prompt is None and result.issues and result.reference_only
+
+
+def test_seed_and_custom_serializers_are_not_inferred():
+ with pytest.raises(ValueError):
+ serialize_reference_widgets({"type": "KSampler", "widgets_values": [12, "fixed"]})
+ with pytest.raises(ValueError):
+ serialize_reference_widgets({"type": "Canny", "widgets_values": {"low_threshold": 0.4}})
+
+
+def test_real_case01_edges_and_supported_fields_match_supplied_export():
+ record = json.loads((REPO / "docs/hel-892/supplied-api/manifest.json").read_text())["cases"][0]
+ raw = (REPO / record["source_path"]).read_bytes()
+ assert hashlib.sha256(raw).hexdigest() == record["source_sha256"]
+ api_raw = (REPO / "docs/hel-892/supplied-api" / record["export_file"]).read_bytes()
+ assert hashlib.sha256(api_raw).hexdigest() == record["export_sha256"]
+ source, api = json.loads(raw), json.loads(api_raw)
+ before = copy.deepcopy(source)
+ nodes = {str(n["id"]): n for n in source["nodes"]}
+ links = {str(link[0]): link for link in source["links"]}
+ fields = edges = rerouted = 0
+ for nid, node in nodes.items():
+ if node["type"] == "Reroute":
+ continue
+ try:
+ values = serialize_reference_widgets(node)
+ except ValueError:
+ pass
+ else:
+ for name, value in values.items():
+ assert type(value) is type(api[nid]["inputs"][name])
+ assert value == api[nid]["inputs"][name]
+ fields += 1
+ for socket in node.get("inputs", []):
+ if socket.get("link") is None:
+ continue
+ lid = socket["link"]
+ assert resolve_reference_link(nodes, links, lid) == api[nid]["inputs"][socket["name"]]
+ edges += 1
+ rerouted += nodes[str(links[str(lid)][1])]["type"] == "Reroute"
+ assert (fields, edges, rerouted) == (16, 23, 9)
+ result = convert_reference(source)
+ assert result.prompt is None
+ assert "reference_node_unsupported" in {i["code"] for i in result.issues}
+ assert source == before
diff --git a/docs/hel-892/README.md b/docs/hel-892/README.md
index e5baf854..e6167f22 100644
--- a/docs/hel-892/README.md
+++ b/docs/hel-892/README.md
@@ -1,3 +1,5 @@
+> 当前 UI 转换增量:见 `UI序列化与Reroute参考转换.md` 与 `serialization-evidence/`。case01 的16项核心标量、23条输入端点(9条经转接)已由固定官方参考算法对齐;整图仍因第三方契约关闭。参考不改变生产导入资格,全量目标未完成。
+
> 当前输出协议增量:见 `输出协议固定参考与兼容验证.md`、`protocol-evidence/` 与后台 `protocol_references.json`。case02/03及case04/07的同协议预览已补公开固定版本参考与实际说明;目标版本/history仍未验证,配套保持停用,全量目标未完成。
> 当前范围:源文件156 / 本次目标155 / 用户明确排除case06共1份。落实策略、协调恢复与证据见 `155份范围落地与协调恢复.md`、`scope-evidence/`;当前145份UI通用转换未证明,6份采用API配套、139份尚无配套,完整定稿/实跑为0。下面156/146及7份收件数字保留为历史范围。
diff --git a/docs/hel-892/UI序列化与Reroute参考转换.md b/docs/hel-892/UI序列化与Reroute参考转换.md
new file mode 100644
index 00000000..4e3cf1b7
--- /dev/null
+++ b/docs/hel-892/UI序列化与Reroute参考转换.md
@@ -0,0 +1,98 @@
+# HEL-892 UI 序列化与 Reroute 参考转换
+
+本轮新增可执行的离线转换算法,并保留生产导入关闭策略。未重做第七批输出协议、源审校或非阻塞建议。继续原 PR #25、分支 `agent/agent/a64a969a6a44`,目标 `main`。增量基点为 `f62786f4a0c2eed48c22da7164e248d473be0d83`;开工通过 Gitea PR API 核对 head/base,PR 未合并。Multica PR 链接表为空,因此以直接 PR API 和 Git 远端引用核对,未盲改链接或另开 PR。
+
+## 实际算法与接口
+
+- `calliope-backend/src/calliope/comfyui/ui2api.py`:复用原转换器的节点、输入、类型检查和全图失败返回逻辑;新增 `convert_reference(source, profile)` 离线入口,结果一律 `reference_only=True`。原 `convert(source, object_info)` 签名与生产行为保留,库导入没有调用参考入口。不是另造执行器,不返回任何包含未支持节点的部分 prompt。
+- `serialization_reference.py`:固定 profile `comfy-frontend-1.37.11-core-reference`,仅覆盖未被扩展修改的本地核心 Canny、ImageStitch、LoadImage、PreviewImage 标量控件。按具体构造契约取值,严格核对数量和类型;LoadImage 的 upload 按钮占位在 workflow 中保留、在 prompt 中排除。没有按 `input_order` 自动推断任意第三方布局;不支持 seed/noise_seed 控制、任意数组值、动态提示、云端/远程 combo 或未知 `serializeValue`。
+- 同模块 `resolve_reference_link`:沿旧式六字段连线,从 Reroute 的输出零槽追到输入零槽,保留最终实体源节点 ID 和原始输出槽。每跳核对输入/输出相互引用、槽范围、循环、悬空、模式;全图额外校验所有存储连线和槽的对应关系。Reroute 本身不出现在候选 prompt 中。额外入口/出口、控件、坏连线、多义对应、静音/旁路继续拒绝。
+- `audit_reference_conversion.py`:复用既有 `load_companions` 的来源/哈希与 `compare_frontend_exports.differences` 的严格类型差分;读取六份现存 API,对照受支持字段及根图连线端点,并保留完整候选的阻塞。它不绕过旧工具的原始前端导出声明/版本绑定要求,不标 equal/可执行。
+- `verify_frontend_sources.py`:只核对固定来源全文 SHA256 和行号范围,可显式重新下载复验;不导入或执行上游代码。
+- `test_reference_serialization.py`:实际源图与 API 的受限对照,以及明确标为合成的算法验证。源码原件、来源、差分、回归和隔离审计均在 `serialization-evidence/`;本说明和 README 是唯一文字入口更新,没有批量修改未知说明。
+
+调用方式:
+
+```python
+from calliope.comfyui.ui2api import convert_reference
+result = convert_reference(source)
+assert result.reference_only # 不是运行资格
+# 有任何不支持项则 result.prompt is None;不得提取局部候选交执行队列。
+```
+
+未知 profile 直接拒绝。源图若声明非 1.37.11 前端则记录不匹配;已声明核心提供方/版本与固定契约不同也拒绝相应节点。缺声明只允许在显式参考模式做假设比较,绝不当版本已匹配。输入顺序即使一致,也不能使生产入口消费位置数组。
+
+## 固定官方依据
+
+case01 没有 `extra.frontendVersion`,不能确认原前端。选择已有 case02 源图声明的官方 `v1.37.11` 作为明确的公开参考,commit `4bf6a1960028cc5cda57d48f9fb01a74dfaade43`。case01 核心节点声明 Canny/LoadImage/PreviewImage `0.21.1`、ImageStitch `0.17.0`,分别取得官方 tag commit `26515acd23fa291a8f5ab53c5997258598de0701`、`63d1bbdb407c69370d407ce5ced6ca3f917528a8`。这些是源图声明与公开代码,均不是用户实际导出版本或目标 object_info。
+
+来源完整记录在 `serialization-evidence/sources.json`:19 个全文原件(18 份代码、1 份许可证),逐个包含 tag/完整 commit、仓库、原文件、固定 URL、行号、获取时间和 SHA256。未安装、导入任何节点包或插件。主要证据:
+
+- [graphToPrompt](https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/utils/executionUtil.ts#L74):74–145 行处理虚拟/静音/旁路、`options.serialize`、`serializeValue` 与链接覆盖。数组包装虽有源码,本轮没有未经节点契约证明就放行任意数组。
+- [Reroute](https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/rerouteNode.ts#L21):21–38 行创建单入口/出口并标记虚拟;[ExecutableNodeDTO](https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts#L250) 250–320 行检查访问环并经同槽输入递归追线,最终保留源槽。本轮只实现普通 Reroute 子集;不照搬可丢弃悬空输入的行为,保守拒绝坏图。
+- [LGraphNode](https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/LGraphNode.ts#L866):866–875、913–922 行区分 workflow 控件读取/写入和 widget.serialize。`litegraphService.ts` 202–212、`nodeDefOrderingUtil.ts` 14–60、具体 float/int/boolean/combo 构造器,连同官方核心 schema,组成顺序契约。没有把单独的 input_order 当完整证明。
+- [上传按钮](https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts#L104):104–120 行默认按钮值 image、`options.serialize=false`;`uploadImage.ts` 给图片 combo 加入 upload 控件。字符串路径原样取源值,不猜实际文件是否存在。
+- [Canny](https://github.com/Comfy-Org/ComfyUI/blob/26515acd23fa291a8f5ab53c5997258598de0701/comfy_extras/nodes_canny.py#L9)、[ImageStitch](https://github.com/Comfy-Org/ComfyUI/blob/63d1bbdb407c69370d407ce5ced6ca3f917528a8/comfy_extras/nodes_images.py#L253)、[LoadImage/PreviewImage](https://github.com/Comfy-Org/ComfyUI/blob/26515acd23fa291a8f5ab53c5997258598de0701/nodes.py#L1665):具名 schema/顺序/输出槽及类注册依据。`widgets.ts` 的额外 seed 控制、`litegraphUtil.ts` 的旧 forceInput 控件迁移和 `dynamicPrompts.ts` 的自定义序列化是保留关闭的具体边界。
+
+原图还含 UE 扩展版本属性,实际扩展是否改变构造/序列化未证实。参考只说明在上述官方原实现条件下算法的结果;即使值对齐也不把扩展或目标环境判为一致。上游 GPL 原件保留,许可证随附。
+
+## 实际 case01 覆盖
+
+源路径 `example_ComfyUI_workflows/0-基础处理:图像合并-音频分离-视频截取合并-图像视频放大/ControlNet_aux_常用样例.json`;源 SHA256 `8898689d777330c4749a079cd762f573bb12a278c47a2fefbd066ffbdc122b6b`,API SHA256 `0ed76e088a23af43d6fecbf273fc0a983d7112e2b046d347f715afffac56d57e`,均与既有收件 manifest 一致,未改字节。
+
+新算法实际追过 4 个 Reroute:24、31、32、35。23 条非虚拟节点输入连线全部与 API 端点相同,其中 9 条经过转接:
+
+- 24 → 18/19/20/21 的 image,最终均为 `['2', 0]`;
+- 31 → 10/12 的 image,最终均为 `['2', 0]`;
+- 32 → 4/1 的 image,最终均为 `['2', 0]`;
+- 35 → 33 的 image,最终为 `['2', 0]`。
+
+这解决旧逐原始连线比对中的 9 项转接端点差异,**仅在本轮明确的参考拓扑范围内**。既有配套比较/审批状态并未因此清除 link_difference 或 companion_unverified。
+
+具名序列化实际覆盖节点 10 的 2 项 Canny 值、28/29/30 的 12 项 ImageStitch 值、2/38 的 2 个 LoadImage 字符串,共 16 项,与 API 类型和值全部一致。2 个 upload 按钮占位按源码排除;3/5/11/13/22/36/37 共 7 个 PreviewImage 无标量控件。共覆盖 13 个核心节点的控件布局,另 4 个转接节点只负责连线。
+
+**整张 case01 仍返回 prompt=None**:8 个 AIO_Preprocessor(1/12/18/19/20/21/33/34)和 1 个 DepthAnythingPreprocessor(4)的前端契约未纳入本轮固定核心 profile,其相关类型检查也继续阻塞。没有从整图裁掉它们再宣称完成。非零源槽在合成链路中另测:LoadImage MASK 槽 1 经多级转接保持 1;后续 MASK→IMAGE 类型不符仍拒绝。
+
+## 六份原导出对照
+
+`serialization-evidence/six-case-comparison.json` 逐项列原值/端点与严格差分。仅根图层,不展开子图、Primitive、循环或第三方动态输入;未覆盖标量不计 equal,元数据/种子/其他路径差异不忽略。
+
+|case|受支持标量一致|根图连线端点一致|端点不同|追线拒绝|整图候选|
+|---|---:|---:|---:|---:|---|
+|01|16|23|0|0|关闭:第三方控件/节点|
+|02|0|5|1|0|关闭:Primitive/字幕等未覆盖|
+|03|0|0|1|0|关闭:子图、版本及高级音频未覆盖|
+|04|0|0|4|0|关闭:子图、版本与动态输入未覆盖|
+|05|0|18|0|0|关闭:其他核心/第三方控件、版本未覆盖|
+|07|0|4|33|2|关闭:子图/循环、静音分支、版本等|
+
+02 的 hints 仍是源节点7连线与 API 内联文本之间的差异,未实现 Primitive 折叠;03 的 `37` vs `37:43`、04 的 `459` vs `459:457` 等仍是子图边界;07 的 33 项差异和 2 项拒绝原样记录。07 的 LoadImage 声明 0.31.1,与固定 0.21.1 不同,故不消费其控件。05 的根图连线相同仍不能证明节点参数或全图等价。其它种子、媒体路径、版本等原有差异继续留在配套审计中,未改写已有证据。
+
+## 本次验证与复现
+
+在 `calliope-backend` 目录,用已安装依赖的 Python 3.11 环境执行,显式 `PYTHONPATH=src`,并核实 ui2api 导入的是本 checkout,未安装新依赖。实际命令:
+
+```bash
+PYTHONPATH=src python -m pytest tests/test_reference_serialization.py \
+ tests/test_ui2api_differential.py tests/test_frontend_export_comparison.py \
+ tests/test_workflow_library.py tests/test_supplied_companions.py tests/test_delivery_scope.py -q
+PYTHONPATH=src python scripts/audit_reference_conversion.py --repo .. \
+ --output ../docs/hel-892/serialization-evidence/six-case-comparison.json
+python scripts/verify_frontend_sources.py \
+ --source-dir ../docs/hel-892/serialization-evidence \
+ --output ../docs/hel-892/serialization-evidence/source-verification.json
+# 可添加 --fetch,重新读取19份固定URL并核验全文哈希;不执行源码。
+uv build --offline --out-dir ../.local-evidence/serialization-build
+```
+
+本次受影响回归 **91 通过**;所有失败关闭场景、版本/提供方不符、原 API 字段保留、重导、用户整行保护、源变化失效和 case06 精确排除均包含在内。只有已安装 Starlette 的弃用警告。已改/新增 5 个 Python 文件 Ruff 通过,diff 检查通过;wheel/sdist 构建与 wheel 内新模块/既有保护资源检查通过。没有重跑共享下载、worker、前端或全后台,因本轮未修改这些路径。历史全后台 865 通过/5 个既有失败/6 跳过、历史 259 项回归仅沿用,绝非本次结果。
+
+隔离库按原生产导入入口执行首导/重导,并调用既有 `audit_library_documents.py` 与 `audit_supplied_api.py`。结果见 import/reimport/document/companion/protection 摘要:源156 / 目标155 / 排除1;16 pending_check / 139 needs_conversion;全部停用,重导155 skipped;1217 源具名值、3660 位置控件节点、294 配套具名值保留,说明完成0、实跑0,完成/实跑时间戳为空。原始7份附件、156份源文件无改动。
+
+## 剩余阶段
+
+本轮只完成核心标量与普通 Reroute 的参考算法;145 份 UI 通用可靠转换、155 份完整说明定稿与必要实跑仍未完成。case06 继续精确排除,不再索要材料。
+
+下一阶段可按具体节点逐类扩充有版本依据的前端构造/序列化契约,优先 case01 的 AIO_Preprocessor 和 DepthAnythingPreprocessor;再另做 Primitive、子图/循环等独立语义。每段都要保留完整图失败关闭与真实导出差分。真正目标版本/扩展、模型/文件、history/编码与必要实跑仍按以后批准的阶段协调,不要求现在提供材料或开放机器。
+
+未连接目标机、停止 TTS、启动 ComfyUI、提交 prompt、下载模型、调用付费服务、写在线库、修改界面、合并或部署。由总管交 HEL-893 审核本轮实际增量。
diff --git a/docs/hel-892/serialization-evidence/LICENSE b/docs/hel-892/serialization-evidence/LICENSE
new file mode 100644
index 00000000..f288702d
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/LICENSE
@@ -0,0 +1,674 @@
+ GNU GENERAL PUBLIC LICENSE
+ Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+ The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users. We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors. You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+ To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. You must make sure that they, too, receive
+or can get the source code. And you must show them these terms so they
+know their rights.
+
+ Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+ For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+ Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so. This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software. The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable. Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products. If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+ Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary. To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS
+
+ 0. Definitions.
+
+ "This License" refers to version 3 of the GNU General Public License.
+
+ "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+ "The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+ To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+ A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+ To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+ To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+ An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+ 1. Source Code.
+
+ The "source code" for a work means the preferred form of the work
+for making modifications to it. "Object code" means any non-source
+form of a work.
+
+ A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+ The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+ The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+ The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+ The Corresponding Source for a work in source code form is that
+same work.
+
+ 2. Basic Permissions.
+
+ All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+ You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force. You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright. Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+ Conveying under any other circumstances is permitted solely under
+the conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+ No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+ When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+ 4. Conveying Verbatim Copies.
+
+ You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+ You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+ 5. Conveying Modified Source Versions.
+
+ You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+ a) The work must carry prominent notices stating that you modified
+ it, and giving a relevant date.
+
+ b) The work must carry prominent notices stating that it is
+ released under this License and any conditions added under section
+ 7. This requirement modifies the requirement in section 4 to
+ "keep intact all notices".
+
+ c) You must license the entire work, as a whole, under this
+ License to anyone who comes into possession of a copy. This
+ License will therefore apply, along with any applicable section 7
+ additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no
+ permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+
+ d) If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your
+ work need not make them do so.
+
+ A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+ 6. Conveying Non-Source Forms.
+
+ You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+ a) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by the
+ Corresponding Source fixed on a durable physical medium
+ customarily used for software interchange.
+
+ b) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by a
+ written offer, valid for at least three years and valid for as
+ long as you offer spare parts or customer support for that product
+ model, to give anyone who possesses the object code either (1) a
+ copy of the Corresponding Source for all the software in the
+ product that is covered by this License, on a durable physical
+ medium customarily used for software interchange, for a price no
+ more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the
+ Corresponding Source from a network server at no charge.
+
+ c) Convey individual copies of the object code with a copy of the
+ written offer to provide the Corresponding Source. This
+ alternative is allowed only occasionally and noncommercially, and
+ only if you received the object code with such an offer, in accord
+ with subsection 6b.
+
+ d) Convey the object code by offering access from a designated
+ place (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to
+ copy the object code is a network server, the Corresponding Source
+ may be on a different server (operated by you or a third party)
+ that supports equivalent copying facilities, provided you maintain
+ clear directions next to the object code saying where to find the
+ Corresponding Source. Regardless of what server hosts the
+ Corresponding Source, you remain obligated to ensure that it is
+ available for as long as needed to satisfy these requirements.
+
+ e) Convey the object code using peer-to-peer transmission, provided
+ you inform other peers where the object code and Corresponding
+ Source of the work are being offered to the general public at no
+ charge under subsection 6d.
+
+ A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+ A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage. For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product. A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+ "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source. The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+ If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+ The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+ Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+ 7. Additional Terms.
+
+ "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+ When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+ Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+ a) Disclaiming warranty or limiting liability differently from the
+ terms of sections 15 and 16 of this License; or
+
+ b) Requiring preservation of specified reasonable legal notices or
+ author attributions in that material or in the Appropriate Legal
+ Notices displayed by works containing it; or
+
+ c) Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+
+ d) Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+
+ e) Declining to grant rights under trademark law for use of some
+ trade names, trademarks, or service marks; or
+
+ f) Requiring indemnification of licensors and authors of that
+ material by anyone who conveys the material (or modified versions of
+ it) with contractual assumptions of liability to the recipient, for
+ any liability that these contractual assumptions directly impose on
+ those licensors and authors.
+
+ All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+ If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+ Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+ 8. Termination.
+
+ You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+ However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+ Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+ 9. Acceptance Not Required for Having Copies.
+
+ You are not required to accept this License in order to receive or
+run a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+ 10. Automatic Licensing of Downstream Recipients.
+
+ Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+ An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+ You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+ 11. Patents.
+
+ A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+ A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+ In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+ If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+ If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+ A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License. You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+ Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+ 12. No Surrender of Others' Freedom.
+
+ If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all. For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+ 13. Use with the GNU Affero General Public License.
+
+ Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+ 14. Revised Versions of this License.
+
+ The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+ If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+ Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+ 15. Disclaimer of Warranty.
+
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+ 16. Limitation of Liability.
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+ 17. Interpretation of Sections 15 and 16.
+
+ If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+
+ Copyright (C)
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+ Copyright (C)
+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+ .
+
+ The GNU General Public License does not permit incorporating your program
+into proprietary programs. If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License. But first, please read
+.
diff --git a/docs/hel-892/serialization-evidence/build.txt b/docs/hel-892/serialization-evidence/build.txt
new file mode 100644
index 00000000..8bf8e341
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/build.txt
@@ -0,0 +1,4 @@
+Building source distribution...
+Building wheel from source distribution...
+Successfully built ../.local-evidence/serialization-build/calliope-1.5.8.tar.gz
+Successfully built ../.local-evidence/serialization-build/calliope-1.5.8-py3-none-any.whl
diff --git a/docs/hel-892/serialization-evidence/companion-audit-summary.json b/docs/hel-892/serialization-evidence/companion-audit-summary.json
new file mode 100644
index 00000000..b02e47c7
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/companion-audit-summary.json
@@ -0,0 +1,9 @@
+{
+ "adopted": 6,
+ "user_excluded": 1,
+ "source_files": 156,
+ "target_files": 155,
+ "general_conversion_verified": 0,
+ "execution_verified": 0,
+ "new_api_literal_params": 294
+}
diff --git a/docs/hel-892/serialization-evidence/core-commits.json b/docs/hel-892/serialization-evidence/core-commits.json
new file mode 100644
index 00000000..3bc60237
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/core-commits.json
@@ -0,0 +1,4 @@
+{
+ "v0.21.1": "26515acd23fa291a8f5ab53c5997258598de0701",
+ "v0.17.0": "63d1bbdb407c69370d407ce5ced6ca3f917528a8"
+}
diff --git a/docs/hel-892/serialization-evidence/corev0.17.0__comfy_extras__nodes_images.py b/docs/hel-892/serialization-evidence/corev0.17.0__comfy_extras__nodes_images.py
new file mode 100644
index 00000000..4c57bb5c
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/corev0.17.0__comfy_extras__nodes_images.py
@@ -0,0 +1,849 @@
+from __future__ import annotations
+
+import nodes
+import folder_paths
+
+import json
+import os
+import re
+import math
+import torch
+import comfy.utils
+
+from server import PromptServer
+from comfy_api.latest import ComfyExtension, IO, UI
+from typing_extensions import override
+
+SVG = IO.SVG.Type # TODO: temporary solution for backward compatibility, will be removed later.
+
+MAX_RESOLUTION = nodes.MAX_RESOLUTION
+
+class ImageCrop(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageCrop",
+ search_aliases=["trim"],
+ display_name="Image Crop (Deprecated)",
+ category="image/transform",
+ is_deprecated=True,
+ essentials_category="Image Tools",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input("width", default=512, min=1, max=nodes.MAX_RESOLUTION, step=1),
+ IO.Int.Input("height", default=512, min=1, max=nodes.MAX_RESOLUTION, step=1),
+ IO.Int.Input("x", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
+ IO.Int.Input("y", default=0, min=0, max=nodes.MAX_RESOLUTION, step=1),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, width, height, x, y) -> IO.NodeOutput:
+ x = min(x, image.shape[2] - 1)
+ y = min(y, image.shape[1] - 1)
+ to_x = width + x
+ to_y = height + y
+ img = image[:,y:to_y, x:to_x, :]
+ return IO.NodeOutput(img)
+
+ crop = execute # TODO: remove
+
+
+class ImageCropV2(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageCropV2",
+ search_aliases=["trim"],
+ display_name="Image Crop",
+ category="image/transform",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.BoundingBox.Input("crop_region", component="ImageCrop"),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, crop_region) -> IO.NodeOutput:
+ x = crop_region.get("x", 0)
+ y = crop_region.get("y", 0)
+ width = crop_region.get("width", 512)
+ height = crop_region.get("height", 512)
+
+ x = min(x, image.shape[2] - 1)
+ y = min(y, image.shape[1] - 1)
+ to_x = width + x
+ to_y = height + y
+ img = image[:,y:to_y, x:to_x, :]
+ return IO.NodeOutput(img, ui=UI.PreviewImage(img))
+
+
+class BoundingBox(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="PrimitiveBoundingBox",
+ display_name="Bounding Box",
+ category="utils/primitive",
+ inputs=[
+ IO.Int.Input("x", default=0, min=0, max=MAX_RESOLUTION),
+ IO.Int.Input("y", default=0, min=0, max=MAX_RESOLUTION),
+ IO.Int.Input("width", default=512, min=1, max=MAX_RESOLUTION),
+ IO.Int.Input("height", default=512, min=1, max=MAX_RESOLUTION),
+ ],
+ outputs=[IO.BoundingBox.Output()],
+ )
+
+ @classmethod
+ def execute(cls, x, y, width, height) -> IO.NodeOutput:
+ return IO.NodeOutput({"x": x, "y": y, "width": width, "height": height})
+
+
+class RepeatImageBatch(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="RepeatImageBatch",
+ search_aliases=["duplicate image", "clone image"],
+ category="image/batch",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input("amount", default=1, min=1, max=4096),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, amount) -> IO.NodeOutput:
+ s = image.repeat((amount, 1,1,1))
+ return IO.NodeOutput(s)
+
+ repeat = execute # TODO: remove
+
+
+class ImageFromBatch(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageFromBatch",
+ search_aliases=["select image", "pick from batch", "extract image"],
+ category="image/batch",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input("batch_index", default=0, min=0, max=4095),
+ IO.Int.Input("length", default=1, min=1, max=4096),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, batch_index, length) -> IO.NodeOutput:
+ s_in = image
+ batch_index = min(s_in.shape[0] - 1, batch_index)
+ length = min(s_in.shape[0] - batch_index, length)
+ s = s_in[batch_index:batch_index + length].clone()
+ return IO.NodeOutput(s)
+
+ frombatch = execute # TODO: remove
+
+
+class ImageAddNoise(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageAddNoise",
+ search_aliases=["film grain"],
+ category="image",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input(
+ "seed",
+ default=0,
+ min=0,
+ max=0xFFFFFFFFFFFFFFFF,
+ control_after_generate=True,
+ tooltip="The random seed used for creating the noise.",
+ ),
+ IO.Float.Input("strength", default=0.5, min=0.0, max=1.0, step=0.01),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, seed, strength) -> IO.NodeOutput:
+ generator = torch.manual_seed(seed)
+ s = torch.clip((image + strength * torch.randn(image.size(), generator=generator, device="cpu").to(image)), min=0.0, max=1.0)
+ return IO.NodeOutput(s)
+
+ repeat = execute # TODO: remove
+
+
+class SaveAnimatedWEBP(IO.ComfyNode):
+ COMPRESS_METHODS = {"default": 4, "fastest": 0, "slowest": 6}
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="SaveAnimatedWEBP",
+ category="image/animation",
+ inputs=[
+ IO.Image.Input("images"),
+ IO.String.Input("filename_prefix", default="ComfyUI"),
+ IO.Float.Input("fps", default=6.0, min=0.01, max=1000.0, step=0.01),
+ IO.Boolean.Input("lossless", default=True),
+ IO.Int.Input("quality", default=80, min=0, max=100),
+ IO.Combo.Input("method", options=list(cls.COMPRESS_METHODS.keys())),
+ # "num_frames": ("INT", {"default": 0, "min": 0, "max": 8192}),
+ ],
+ hidden=[IO.Hidden.prompt, IO.Hidden.extra_pnginfo],
+ is_output_node=True,
+ )
+
+ @classmethod
+ def execute(cls, images, fps, filename_prefix, lossless, quality, method, num_frames=0) -> IO.NodeOutput:
+ return IO.NodeOutput(
+ ui=UI.ImageSaveHelper.get_save_animated_webp_ui(
+ images=images,
+ filename_prefix=filename_prefix,
+ cls=cls,
+ fps=fps,
+ lossless=lossless,
+ quality=quality,
+ method=cls.COMPRESS_METHODS.get(method)
+ )
+ )
+
+ save_images = execute # TODO: remove
+
+
+class SaveAnimatedPNG(IO.ComfyNode):
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="SaveAnimatedPNG",
+ category="image/animation",
+ inputs=[
+ IO.Image.Input("images"),
+ IO.String.Input("filename_prefix", default="ComfyUI"),
+ IO.Float.Input("fps", default=6.0, min=0.01, max=1000.0, step=0.01),
+ IO.Int.Input("compress_level", default=4, min=0, max=9, advanced=True),
+ ],
+ hidden=[IO.Hidden.prompt, IO.Hidden.extra_pnginfo],
+ is_output_node=True,
+ )
+
+ @classmethod
+ def execute(cls, images, fps, compress_level, filename_prefix="ComfyUI") -> IO.NodeOutput:
+ return IO.NodeOutput(
+ ui=UI.ImageSaveHelper.get_save_animated_png_ui(
+ images=images,
+ filename_prefix=filename_prefix,
+ cls=cls,
+ fps=fps,
+ compress_level=compress_level,
+ )
+ )
+
+ save_images = execute # TODO: remove
+
+
+class ImageStitch(IO.ComfyNode):
+ """Upstreamed from https://github.com/kijai/ComfyUI-KJNodes"""
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageStitch",
+ search_aliases=["combine images", "join images", "concatenate images", "side by side"],
+ display_name="Image Stitch",
+ description="Stitches image2 to image1 in the specified direction.\n"
+ "If image2 is not provided, returns image1 unchanged.\n"
+ "Optional spacing can be added between images.",
+ category="image/transform",
+ inputs=[
+ IO.Image.Input("image1"),
+ IO.Combo.Input("direction", options=["right", "down", "left", "up"], default="right"),
+ IO.Boolean.Input("match_image_size", default=True),
+ IO.Int.Input("spacing_width", default=0, min=0, max=1024, step=2, advanced=True),
+ IO.Combo.Input("spacing_color", options=["white", "black", "red", "green", "blue"], default="white", advanced=True),
+ IO.Image.Input("image2", optional=True),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(
+ cls,
+ image1,
+ direction,
+ match_image_size,
+ spacing_width,
+ spacing_color,
+ image2=None,
+ ) -> IO.NodeOutput:
+ if image2 is None:
+ return IO.NodeOutput(image1)
+
+ # Handle batch size differences
+ if image1.shape[0] != image2.shape[0]:
+ max_batch = max(image1.shape[0], image2.shape[0])
+ if image1.shape[0] < max_batch:
+ image1 = torch.cat(
+ [image1, image1[-1:].repeat(max_batch - image1.shape[0], 1, 1, 1)]
+ )
+ if image2.shape[0] < max_batch:
+ image2 = torch.cat(
+ [image2, image2[-1:].repeat(max_batch - image2.shape[0], 1, 1, 1)]
+ )
+
+ # Match image sizes if requested
+ if match_image_size:
+ h1, w1 = image1.shape[1:3]
+ h2, w2 = image2.shape[1:3]
+ aspect_ratio = w2 / h2
+
+ if direction in ["left", "right"]:
+ target_h, target_w = h1, int(h1 * aspect_ratio)
+ else: # up, down
+ target_w, target_h = w1, int(w1 / aspect_ratio)
+
+ image2 = comfy.utils.common_upscale(
+ image2.movedim(-1, 1), target_w, target_h, "lanczos", "disabled"
+ ).movedim(1, -1)
+
+ color_map = {
+ "white": 1.0,
+ "black": 0.0,
+ "red": (1.0, 0.0, 0.0),
+ "green": (0.0, 1.0, 0.0),
+ "blue": (0.0, 0.0, 1.0),
+ }
+
+ color_val = color_map[spacing_color]
+
+ # When not matching sizes, pad to align non-concat dimensions
+ if not match_image_size:
+ h1, w1 = image1.shape[1:3]
+ h2, w2 = image2.shape[1:3]
+ pad_value = 0.0
+ if not isinstance(color_val, tuple):
+ pad_value = color_val
+
+ if direction in ["left", "right"]:
+ # For horizontal concat, pad heights to match
+ if h1 != h2:
+ target_h = max(h1, h2)
+ if h1 < target_h:
+ pad_h = target_h - h1
+ pad_top, pad_bottom = pad_h // 2, pad_h - pad_h // 2
+ image1 = torch.nn.functional.pad(image1, (0, 0, 0, 0, pad_top, pad_bottom), mode='constant', value=pad_value)
+ if h2 < target_h:
+ pad_h = target_h - h2
+ pad_top, pad_bottom = pad_h // 2, pad_h - pad_h // 2
+ image2 = torch.nn.functional.pad(image2, (0, 0, 0, 0, pad_top, pad_bottom), mode='constant', value=pad_value)
+ else: # up, down
+ # For vertical concat, pad widths to match
+ if w1 != w2:
+ target_w = max(w1, w2)
+ if w1 < target_w:
+ pad_w = target_w - w1
+ pad_left, pad_right = pad_w // 2, pad_w - pad_w // 2
+ image1 = torch.nn.functional.pad(image1, (0, 0, pad_left, pad_right), mode='constant', value=pad_value)
+ if w2 < target_w:
+ pad_w = target_w - w2
+ pad_left, pad_right = pad_w // 2, pad_w - pad_w // 2
+ image2 = torch.nn.functional.pad(image2, (0, 0, pad_left, pad_right), mode='constant', value=pad_value)
+
+ # Ensure same number of channels
+ if image1.shape[-1] != image2.shape[-1]:
+ max_channels = max(image1.shape[-1], image2.shape[-1])
+ if image1.shape[-1] < max_channels:
+ image1 = torch.cat(
+ [
+ image1,
+ torch.ones(
+ *image1.shape[:-1],
+ max_channels - image1.shape[-1],
+ device=image1.device,
+ ),
+ ],
+ dim=-1,
+ )
+ if image2.shape[-1] < max_channels:
+ image2 = torch.cat(
+ [
+ image2,
+ torch.ones(
+ *image2.shape[:-1],
+ max_channels - image2.shape[-1],
+ device=image2.device,
+ ),
+ ],
+ dim=-1,
+ )
+
+ # Add spacing if specified
+ if spacing_width > 0:
+ spacing_width = spacing_width + (spacing_width % 2) # Ensure even
+
+ if direction in ["left", "right"]:
+ spacing_shape = (
+ image1.shape[0],
+ max(image1.shape[1], image2.shape[1]),
+ spacing_width,
+ image1.shape[-1],
+ )
+ else:
+ spacing_shape = (
+ image1.shape[0],
+ spacing_width,
+ max(image1.shape[2], image2.shape[2]),
+ image1.shape[-1],
+ )
+
+ spacing = torch.full(spacing_shape, 0.0, device=image1.device)
+ if isinstance(color_val, tuple):
+ for i, c in enumerate(color_val):
+ if i < spacing.shape[-1]:
+ spacing[..., i] = c
+ if spacing.shape[-1] == 4: # Add alpha
+ spacing[..., 3] = 1.0
+ else:
+ spacing[..., : min(3, spacing.shape[-1])] = color_val
+ if spacing.shape[-1] == 4:
+ spacing[..., 3] = 1.0
+
+ # Concatenate images
+ images = [image2, image1] if direction in ["left", "up"] else [image1, image2]
+ if spacing_width > 0:
+ images.insert(1, spacing)
+
+ concat_dim = 2 if direction in ["left", "right"] else 1
+ return IO.NodeOutput(torch.cat(images, dim=concat_dim))
+
+ stitch = execute # TODO: remove
+
+
+class ResizeAndPadImage(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ResizeAndPadImage",
+ search_aliases=["fit to size"],
+ category="image/transform",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input("target_width", default=512, min=1, max=nodes.MAX_RESOLUTION, step=1),
+ IO.Int.Input("target_height", default=512, min=1, max=nodes.MAX_RESOLUTION, step=1),
+ IO.Combo.Input("padding_color", options=["white", "black"], advanced=True),
+ IO.Combo.Input("interpolation", options=["area", "bicubic", "nearest-exact", "bilinear", "lanczos"], advanced=True),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, target_width, target_height, padding_color, interpolation) -> IO.NodeOutput:
+ batch_size, orig_height, orig_width, channels = image.shape
+
+ scale_w = target_width / orig_width
+ scale_h = target_height / orig_height
+ scale = min(scale_w, scale_h)
+
+ new_width = int(orig_width * scale)
+ new_height = int(orig_height * scale)
+
+ image_permuted = image.permute(0, 3, 1, 2)
+
+ resized = comfy.utils.common_upscale(image_permuted, new_width, new_height, interpolation, "disabled")
+
+ pad_value = 0.0 if padding_color == "black" else 1.0
+ padded = torch.full(
+ (batch_size, channels, target_height, target_width),
+ pad_value,
+ dtype=image.dtype,
+ device=image.device
+ )
+
+ y_offset = (target_height - new_height) // 2
+ x_offset = (target_width - new_width) // 2
+
+ padded[:, :, y_offset:y_offset + new_height, x_offset:x_offset + new_width] = resized
+
+ output = padded.permute(0, 2, 3, 1)
+ return IO.NodeOutput(output)
+
+ resize_and_pad = execute # TODO: remove
+
+
+class SaveSVGNode(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="SaveSVGNode",
+ search_aliases=["export vector", "save vector graphics"],
+ description="Save SVG files on disk.",
+ category="image/save",
+ inputs=[
+ IO.SVG.Input("svg"),
+ IO.String.Input(
+ "filename_prefix",
+ default="svg/ComfyUI",
+ tooltip="The prefix for the file to save. This may include formatting information such as %date:yyyy-MM-dd% or %Empty Latent Image.width% to include values from nodes.",
+ ),
+ ],
+ hidden=[IO.Hidden.prompt, IO.Hidden.extra_pnginfo],
+ is_output_node=True,
+ )
+
+ @classmethod
+ def execute(cls, svg: IO.SVG.Type, filename_prefix="svg/ComfyUI") -> IO.NodeOutput:
+ full_output_folder, filename, counter, subfolder, filename_prefix = folder_paths.get_save_image_path(filename_prefix, folder_paths.get_output_directory())
+ results: list[UI.SavedResult] = []
+
+ # Prepare metadata JSON
+ metadata_dict = {}
+ if cls.hidden.prompt is not None:
+ metadata_dict["prompt"] = cls.hidden.prompt
+ if cls.hidden.extra_pnginfo is not None:
+ metadata_dict.update(cls.hidden.extra_pnginfo)
+
+ # Convert metadata to JSON string
+ metadata_json = json.dumps(metadata_dict, indent=2) if metadata_dict else None
+
+
+ for batch_number, svg_bytes in enumerate(svg.data):
+ filename_with_batch_num = filename.replace("%batch_num%", str(batch_number))
+ file = f"{filename_with_batch_num}_{counter:05}_.svg"
+
+ # Read SVG content
+ svg_bytes.seek(0)
+ svg_content = svg_bytes.read().decode('utf-8')
+
+ # Inject metadata if available
+ if metadata_json:
+ # Create metadata element with CDATA section
+ metadata_element = f"""
+
+
+ """
+ # Insert metadata after opening svg tag using regex with a replacement function
+ def replacement(match):
+ # match.group(1) contains the captured tag
+ return match.group(1) + '\n' + metadata_element
+
+ # Apply the substitution
+ svg_content = re.sub(r'(]*>)', replacement, svg_content, flags=re.UNICODE)
+
+ # Write the modified SVG to file
+ with open(os.path.join(full_output_folder, file), 'wb') as svg_file:
+ svg_file.write(svg_content.encode('utf-8'))
+
+ results.append(UI.SavedResult(filename=file, subfolder=subfolder, type=IO.FolderType.output))
+ counter += 1
+ return IO.NodeOutput(ui={"images": results})
+
+ save_svg = execute # TODO: remove
+
+
+class GetImageSize(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="GetImageSize",
+ search_aliases=["dimensions", "resolution", "image info"],
+ display_name="Get Image Size",
+ description="Returns width and height of the image, and passes it through unchanged.",
+ category="image",
+ inputs=[
+ IO.Image.Input("image"),
+ ],
+ outputs=[
+ IO.Int.Output(display_name="width"),
+ IO.Int.Output(display_name="height"),
+ IO.Int.Output(display_name="batch_size"),
+ ],
+ hidden=[IO.Hidden.unique_id],
+ )
+
+ @classmethod
+ def execute(cls, image) -> IO.NodeOutput:
+ height = image.shape[1]
+ width = image.shape[2]
+ batch_size = image.shape[0]
+
+ # Send progress text to display size on the node
+ if cls.hidden.unique_id:
+ PromptServer.instance.send_progress_text(f"width: {width}, height: {height}\n batch size: {batch_size}", cls.hidden.unique_id)
+
+ return IO.NodeOutput(width, height, batch_size)
+
+ get_size = execute # TODO: remove
+
+
+class ImageRotate(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageRotate",
+ display_name="Image Rotate",
+ search_aliases=["turn", "flip orientation"],
+ category="image/transform",
+ essentials_category="Image Tools",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Combo.Input("rotation", options=["none", "90 degrees", "180 degrees", "270 degrees"]),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, rotation) -> IO.NodeOutput:
+ rotate_by = 0
+ if rotation.startswith("90"):
+ rotate_by = 1
+ elif rotation.startswith("180"):
+ rotate_by = 2
+ elif rotation.startswith("270"):
+ rotate_by = 3
+
+ image = torch.rot90(image, k=rotate_by, dims=[2, 1])
+ return IO.NodeOutput(image)
+
+ rotate = execute # TODO: remove
+
+
+class ImageFlip(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageFlip",
+ search_aliases=["mirror", "reflect"],
+ category="image/transform",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Combo.Input("flip_method", options=["x-axis: vertically", "y-axis: horizontally"]),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, flip_method) -> IO.NodeOutput:
+ if flip_method.startswith("x"):
+ image = torch.flip(image, dims=[1])
+ elif flip_method.startswith("y"):
+ image = torch.flip(image, dims=[2])
+
+ return IO.NodeOutput(image)
+
+ flip = execute # TODO: remove
+
+
+class ImageScaleToMaxDimension(IO.ComfyNode):
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageScaleToMaxDimension",
+ category="image/upscaling",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Combo.Input(
+ "upscale_method",
+ options=["area", "lanczos", "bilinear", "nearest-exact", "bilinear", "bicubic"],
+ ),
+ IO.Int.Input("largest_size", default=512, min=0, max=MAX_RESOLUTION, step=1),
+ ],
+ outputs=[IO.Image.Output()],
+ )
+
+ @classmethod
+ def execute(cls, image, upscale_method, largest_size) -> IO.NodeOutput:
+ height = image.shape[1]
+ width = image.shape[2]
+
+ if height > width:
+ width = round((width / height) * largest_size)
+ height = largest_size
+ elif width > height:
+ height = round((height / width) * largest_size)
+ width = largest_size
+ else:
+ height = largest_size
+ width = largest_size
+
+ samples = image.movedim(-1, 1)
+ s = comfy.utils.common_upscale(samples, width, height, upscale_method, "disabled")
+ s = s.movedim(1, -1)
+ return IO.NodeOutput(s)
+
+ upscale = execute # TODO: remove
+
+
+class SplitImageToTileList(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="SplitImageToTileList",
+ category="image/batch",
+ search_aliases=["split image", "tile image", "slice image"],
+ display_name="Split Image into List of Tiles",
+ description="Splits an image into a batched list of tiles with a specified overlap.",
+ inputs=[
+ IO.Image.Input("image"),
+ IO.Int.Input("tile_width", default=1024, min=64, max=MAX_RESOLUTION),
+ IO.Int.Input("tile_height", default=1024, min=64, max=MAX_RESOLUTION),
+ IO.Int.Input("overlap", default=128, min=0, max=4096),
+ ],
+ outputs=[
+ IO.Image.Output(is_output_list=True),
+ ],
+ )
+
+ @staticmethod
+ def get_grid_coords(width, height, tile_width, tile_height, overlap):
+ coords = []
+ stride_x = round(max(tile_width * 0.25, tile_width - overlap))
+ stride_y = round(max(tile_width * 0.25, tile_height - overlap))
+
+ y = 0
+ while y < height:
+ x = 0
+ y_end = min(y + tile_height, height)
+ y_start = max(0, y_end - tile_height)
+
+ while x < width:
+ x_end = min(x + tile_width, width)
+ x_start = max(0, x_end - tile_width)
+
+ coords.append((x_start, y_start, x_end, y_end))
+
+ if x_end >= width:
+ break
+ x += stride_x
+
+ if y_end >= height:
+ break
+ y += stride_y
+
+ return coords
+
+ @classmethod
+ def execute(cls, image, tile_width, tile_height, overlap):
+ b, h, w, c = image.shape
+ coords = cls.get_grid_coords(w, h, tile_width, tile_height, overlap)
+
+ output_list = []
+ for (x_start, y_start, x_end, y_end) in coords:
+ tile = image[:, y_start:y_end, x_start:x_end, :]
+ output_list.append(tile)
+
+ return IO.NodeOutput(output_list)
+
+
+class ImageMergeTileList(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageMergeTileList",
+ display_name="Merge List of Tiles to Image",
+ category="image/batch",
+ search_aliases=["split image", "tile image", "slice image"],
+ is_input_list=True,
+ inputs=[
+ IO.Image.Input("image_list"),
+ IO.Int.Input("final_width", default=1024, min=64, max=32768),
+ IO.Int.Input("final_height", default=1024, min=64, max=32768),
+ IO.Int.Input("overlap", default=128, min=0, max=4096),
+ ],
+ outputs=[
+ IO.Image.Output(is_output_list=False),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, image_list, final_width, final_height, overlap):
+ w = final_width[0]
+ h = final_height[0]
+ ovlp = overlap[0]
+ feather_str = 1.0
+
+ first_tile = image_list[0]
+ b, t_h, t_w, c = first_tile.shape
+ device = first_tile.device
+ dtype = first_tile.dtype
+
+ coords = SplitImageToTileList.get_grid_coords(w, h, t_w, t_h, ovlp)
+
+ canvas = torch.zeros((b, h, w, c), device=device, dtype=dtype)
+ weights = torch.zeros((b, h, w, 1), device=device, dtype=dtype)
+
+ if ovlp > 0:
+ y_w = torch.sin(math.pi * torch.linspace(0, 1, t_h, device=device, dtype=dtype))
+ x_w = torch.sin(math.pi * torch.linspace(0, 1, t_w, device=device, dtype=dtype))
+ y_w = torch.clamp(y_w, min=1e-5)
+ x_w = torch.clamp(x_w, min=1e-5)
+
+ sine_mask = (y_w.unsqueeze(1) * x_w.unsqueeze(0)).unsqueeze(0).unsqueeze(-1)
+ flat_mask = torch.ones_like(sine_mask)
+
+ weight_mask = torch.lerp(flat_mask, sine_mask, feather_str)
+ else:
+ weight_mask = torch.ones((1, t_h, t_w, 1), device=device, dtype=dtype)
+
+ for i, (x_start, y_start, x_end, y_end) in enumerate(coords):
+ if i >= len(image_list):
+ break
+
+ tile = image_list[i]
+
+ region_h = y_end - y_start
+ region_w = x_end - x_start
+
+ real_h = min(region_h, tile.shape[1])
+ real_w = min(region_w, tile.shape[2])
+
+ y_end_actual = y_start + real_h
+ x_end_actual = x_start + real_w
+
+ tile_crop = tile[:, :real_h, :real_w, :]
+ mask_crop = weight_mask[:, :real_h, :real_w, :]
+
+ canvas[:, y_start:y_end_actual, x_start:x_end_actual, :] += tile_crop * mask_crop
+ weights[:, y_start:y_end_actual, x_start:x_end_actual, :] += mask_crop
+
+ weights[weights == 0] = 1.0
+ merged_image = canvas / weights
+
+ return IO.NodeOutput(merged_image)
+
+
+class ImagesExtension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+ return [
+ ImageCrop,
+ ImageCropV2,
+ BoundingBox,
+ RepeatImageBatch,
+ ImageFromBatch,
+ ImageAddNoise,
+ SaveAnimatedWEBP,
+ SaveAnimatedPNG,
+ SaveSVGNode,
+ ImageStitch,
+ ResizeAndPadImage,
+ GetImageSize,
+ ImageRotate,
+ ImageFlip,
+ ImageScaleToMaxDimension,
+ SplitImageToTileList,
+ ImageMergeTileList,
+ ]
+
+
+async def comfy_entrypoint() -> ImagesExtension:
+ return ImagesExtension()
diff --git a/docs/hel-892/serialization-evidence/corev0.21.1__comfy_extras__nodes_canny.py b/docs/hel-892/serialization-evidence/corev0.21.1__comfy_extras__nodes_canny.py
new file mode 100644
index 00000000..648b4279
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/corev0.21.1__comfy_extras__nodes_canny.py
@@ -0,0 +1,45 @@
+from kornia.filters import canny
+from typing_extensions import override
+
+import comfy.model_management
+from comfy_api.latest import ComfyExtension, io
+import torch
+
+
+class Canny(io.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="Canny",
+ display_name="Canny",
+ search_aliases=["edge detection", "outline", "contour detection", "line art"],
+ category="image/preprocessors",
+ essentials_category="Image Tools",
+ inputs=[
+ io.Image.Input("image"),
+ io.Float.Input("low_threshold", default=0.4, min=0.01, max=0.99, step=0.01),
+ io.Float.Input("high_threshold", default=0.8, min=0.01, max=0.99, step=0.01),
+ ],
+ outputs=[io.Image.Output()],
+ )
+
+ @classmethod
+ def detect_edge(cls, image, low_threshold, high_threshold):
+ # Deprecated: use the V3 schema's `execute` method instead of this.
+ return cls.execute(image, low_threshold, high_threshold)
+
+ @classmethod
+ def execute(cls, image, low_threshold, high_threshold) -> io.NodeOutput:
+ output = canny(image.to(device=comfy.model_management.get_torch_device(), dtype=torch.float32).movedim(-1, 1), low_threshold, high_threshold)
+ img_out = output[1].to(device=comfy.model_management.intermediate_device(), dtype=comfy.model_management.intermediate_dtype()).repeat(1, 3, 1, 1).movedim(1, -1)
+ return io.NodeOutput(img_out)
+
+
+class CannyExtension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[io.ComfyNode]]:
+ return [Canny]
+
+
+async def comfy_entrypoint() -> CannyExtension:
+ return CannyExtension()
diff --git a/docs/hel-892/serialization-evidence/corev0.21.1__nodes.py b/docs/hel-892/serialization-evidence/corev0.21.1__nodes.py
new file mode 100644
index 00000000..2b63f9fb
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/corev0.21.1__nodes.py
@@ -0,0 +1,2505 @@
+from __future__ import annotations
+import torch
+
+
+import os
+import sys
+import json
+import glob
+import hashlib
+import inspect
+
+import traceback
+import math
+import time
+import random
+import logging
+
+from PIL import Image, ImageOps, ImageSequence
+from PIL.PngImagePlugin import PngInfo
+
+import numpy as np
+import safetensors.torch
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), "comfy"))
+
+import comfy.diffusers_load
+import comfy.samplers
+import comfy.sample
+import comfy.sd
+import comfy.utils
+import comfy.controlnet
+from comfy.comfy_types import IO, ComfyNodeABC, InputTypeDict, FileLocator
+from comfy_api.internal import register_versions, ComfyAPIWithVersion
+from comfy_api.version_list import supported_versions
+from comfy_api.latest import io, ComfyExtension, InputImpl
+
+import comfy.clip_vision
+
+import comfy.model_management
+from comfy.cli_args import args
+
+import importlib
+
+import folder_paths
+import latent_preview
+import node_helpers
+
+if args.enable_manager:
+ import comfyui_manager
+
+def before_node_execution():
+ comfy.model_management.throw_exception_if_processing_interrupted()
+
+def interrupt_processing(value=True):
+ comfy.model_management.interrupt_current_processing(value)
+
+MAX_RESOLUTION=16384
+
+class CLIPTextEncode(ComfyNodeABC):
+ @classmethod
+ def INPUT_TYPES(s) -> InputTypeDict:
+ return {
+ "required": {
+ "text": (IO.STRING, {"multiline": True, "dynamicPrompts": True, "tooltip": "The text to be encoded."}),
+ "clip": (IO.CLIP, {"tooltip": "The CLIP model used for encoding the text."})
+ }
+ }
+ RETURN_TYPES = (IO.CONDITIONING,)
+ OUTPUT_TOOLTIPS = ("A conditioning containing the embedded text used to guide the diffusion model.",)
+ FUNCTION = "encode"
+
+ CATEGORY = "conditioning"
+ DESCRIPTION = "Encodes a text prompt using a CLIP model into an embedding that can be used to guide the diffusion model towards generating specific images."
+ SEARCH_ALIASES = ["text", "prompt", "text prompt", "positive prompt", "negative prompt", "encode text", "text encoder", "encode prompt"]
+
+ def encode(self, clip, text):
+ if clip is None:
+ raise RuntimeError("ERROR: clip input is invalid: None\n\nIf the clip is from a checkpoint loader node your checkpoint does not contain a valid clip or text encoder model.")
+ tokens = clip.tokenize(text)
+ return (clip.encode_from_tokens_scheduled(tokens), )
+
+
+class ConditioningCombine:
+ ESSENTIALS_CATEGORY = "Image Generation"
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning_1": ("CONDITIONING", ), "conditioning_2": ("CONDITIONING", )}}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "combine"
+
+ CATEGORY = "conditioning"
+ SEARCH_ALIASES = ["combine", "merge conditioning", "combine prompts", "merge prompts", "mix prompts", "add prompt"]
+
+ def combine(self, conditioning_1, conditioning_2):
+ return (conditioning_1 + conditioning_2, )
+
+class ConditioningAverage :
+ SEARCH_ALIASES = ["blend prompts", "interpolate conditioning", "mix prompts", "style fusion", "weighted blend"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning_to": ("CONDITIONING", ), "conditioning_from": ("CONDITIONING", ),
+ "conditioning_to_strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.01})
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "addWeighted"
+
+ CATEGORY = "conditioning"
+
+ def addWeighted(self, conditioning_to, conditioning_from, conditioning_to_strength):
+ out = []
+
+ if len(conditioning_from) > 1:
+ logging.warning("Warning: ConditioningAverage conditioning_from contains more than 1 cond, only the first one will actually be applied to conditioning_to.")
+
+ cond_from = conditioning_from[0][0]
+ pooled_output_from = conditioning_from[0][1].get("pooled_output", None)
+
+ for i in range(len(conditioning_to)):
+ t1 = conditioning_to[i][0]
+ pooled_output_to = conditioning_to[i][1].get("pooled_output", pooled_output_from)
+ t0 = cond_from[:,:t1.shape[1]]
+ if t0.shape[1] < t1.shape[1]:
+ t0 = torch.cat([t0] + [torch.zeros((1, (t1.shape[1] - t0.shape[1]), t1.shape[2]))], dim=1)
+
+ tw = torch.mul(t1, conditioning_to_strength) + torch.mul(t0, (1.0 - conditioning_to_strength))
+ t_to = conditioning_to[i][1].copy()
+ if pooled_output_from is not None and pooled_output_to is not None:
+ t_to["pooled_output"] = torch.mul(pooled_output_to, conditioning_to_strength) + torch.mul(pooled_output_from, (1.0 - conditioning_to_strength))
+ elif pooled_output_from is not None:
+ t_to["pooled_output"] = pooled_output_from
+
+ n = [tw, t_to]
+ out.append(n)
+ return (out, )
+
+class ConditioningConcat:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {
+ "conditioning_to": ("CONDITIONING",),
+ "conditioning_from": ("CONDITIONING",),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "concat"
+
+ CATEGORY = "conditioning"
+
+ def concat(self, conditioning_to, conditioning_from):
+ out = []
+
+ if len(conditioning_from) > 1:
+ logging.warning("Warning: ConditioningConcat conditioning_from contains more than 1 cond, only the first one will actually be applied to conditioning_to.")
+
+ cond_from = conditioning_from[0][0]
+
+ for i in range(len(conditioning_to)):
+ t1 = conditioning_to[i][0]
+ tw = torch.cat((t1, cond_from),1)
+ n = [tw, conditioning_to[i][1].copy()]
+ out.append(n)
+
+ return (out, )
+
+class ConditioningSetArea:
+ SEARCH_ALIASES = ["regional prompt", "area prompt", "spatial conditioning", "localized prompt"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "width": ("INT", {"default": 64, "min": 64, "max": MAX_RESOLUTION, "step": 8}),
+ "height": ("INT", {"default": 64, "min": 64, "max": MAX_RESOLUTION, "step": 8}),
+ "x": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "y": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01}),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "append"
+
+ CATEGORY = "conditioning"
+
+ def append(self, conditioning, width, height, x, y, strength):
+ c = node_helpers.conditioning_set_values(conditioning, {"area": (height // 8, width // 8, y // 8, x // 8),
+ "strength": strength,
+ "set_area_to_bounds": False})
+ return (c, )
+
+class ConditioningSetAreaPercentage:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "width": ("FLOAT", {"default": 1.0, "min": 0, "max": 1.0, "step": 0.01}),
+ "height": ("FLOAT", {"default": 1.0, "min": 0, "max": 1.0, "step": 0.01}),
+ "x": ("FLOAT", {"default": 0, "min": 0, "max": 1.0, "step": 0.01}),
+ "y": ("FLOAT", {"default": 0, "min": 0, "max": 1.0, "step": 0.01}),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01}),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "append"
+
+ CATEGORY = "conditioning"
+
+ def append(self, conditioning, width, height, x, y, strength):
+ c = node_helpers.conditioning_set_values(conditioning, {"area": ("percentage", height, width, y, x),
+ "strength": strength,
+ "set_area_to_bounds": False})
+ return (c, )
+
+class ConditioningSetAreaStrength:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01}),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "append"
+
+ CATEGORY = "conditioning"
+
+ def append(self, conditioning, strength):
+ c = node_helpers.conditioning_set_values(conditioning, {"strength": strength})
+ return (c, )
+
+
+class ConditioningSetMask:
+ SEARCH_ALIASES = ["masked prompt", "regional inpaint conditioning", "mask conditioning"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "mask": ("MASK", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01}),
+ "set_cond_area": (["default", "mask bounds"],),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "append"
+
+ CATEGORY = "conditioning"
+
+ def append(self, conditioning, mask, set_cond_area, strength):
+ set_area_to_bounds = False
+ if set_cond_area != "default":
+ set_area_to_bounds = True
+ if len(mask.shape) < 3:
+ mask = mask.unsqueeze(0)
+
+ c = node_helpers.conditioning_set_values(conditioning, {"mask": mask,
+ "set_area_to_bounds": set_area_to_bounds,
+ "mask_strength": strength})
+ return (c, )
+
+class ConditioningZeroOut:
+ SEARCH_ALIASES = ["null conditioning", "clear conditioning"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", )}}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "zero_out"
+
+ CATEGORY = "advanced/conditioning"
+
+ def zero_out(self, conditioning):
+ c = []
+ for t in conditioning:
+ d = t[1].copy()
+ pooled_output = d.get("pooled_output", None)
+ if pooled_output is not None:
+ d["pooled_output"] = torch.zeros_like(pooled_output)
+ conditioning_lyrics = d.get("conditioning_lyrics", None)
+ if conditioning_lyrics is not None:
+ d["conditioning_lyrics"] = torch.zeros_like(conditioning_lyrics)
+ n = [torch.zeros_like(t[0]), d]
+ c.append(n)
+ return (c, )
+
+class ConditioningSetTimestepRange:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "start": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+ "end": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.001})
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "set_range"
+
+ CATEGORY = "advanced/conditioning"
+
+ def set_range(self, conditioning, start, end):
+ c = node_helpers.conditioning_set_values(conditioning, {"start_percent": start,
+ "end_percent": end})
+ return (c, )
+
+class VAEDecode:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "samples": ("LATENT", {"tooltip": "The latent to be decoded."}),
+ "vae": ("VAE", {"tooltip": "The VAE model used for decoding the latent."})
+ }
+ }
+ RETURN_TYPES = ("IMAGE",)
+ OUTPUT_TOOLTIPS = ("The decoded image.",)
+ FUNCTION = "decode"
+
+ CATEGORY = "latent"
+ DESCRIPTION = "Decodes latent images back into pixel space images."
+ SEARCH_ALIASES = ["decode", "decode latent", "latent to image", "render latent"]
+
+ def decode(self, vae, samples):
+ latent = samples["samples"]
+ if latent.is_nested:
+ latent = latent.unbind()[0]
+
+ images = vae.decode(latent)
+ if len(images.shape) == 5: #Combine batches
+ images = images.reshape(-1, images.shape[-3], images.shape[-2], images.shape[-1])
+ return (images, )
+
+class VAEDecodeTiled:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"samples": ("LATENT", ), "vae": ("VAE", ),
+ "tile_size": ("INT", {"default": 512, "min": 64, "max": 4096, "step": 32, "advanced": True}),
+ "overlap": ("INT", {"default": 64, "min": 0, "max": 4096, "step": 32, "advanced": True}),
+ "temporal_size": ("INT", {"default": 64, "min": 8, "max": 4096, "step": 4, "tooltip": "Only used for video VAEs: Amount of frames to decode at a time.", "advanced": True}),
+ "temporal_overlap": ("INT", {"default": 8, "min": 4, "max": 4096, "step": 4, "tooltip": "Only used for video VAEs: Amount of frames to overlap.", "advanced": True}),
+ }}
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "decode"
+
+ CATEGORY = "experimental"
+
+ def decode(self, vae, samples, tile_size, overlap=64, temporal_size=64, temporal_overlap=8):
+ if tile_size < overlap * 4:
+ overlap = tile_size // 4
+ if temporal_size < temporal_overlap * 2:
+ temporal_overlap = temporal_overlap // 2
+ temporal_compression = vae.temporal_compression_decode()
+ if temporal_compression is not None:
+ temporal_size = max(2, temporal_size // temporal_compression)
+ temporal_overlap = max(1, min(temporal_size // 2, temporal_overlap // temporal_compression))
+ else:
+ temporal_size = None
+ temporal_overlap = None
+
+ compression = vae.spacial_compression_decode()
+ images = vae.decode_tiled(samples["samples"], tile_x=tile_size // compression, tile_y=tile_size // compression, overlap=overlap // compression, tile_t=temporal_size, overlap_t=temporal_overlap)
+ if len(images.shape) == 5: #Combine batches
+ images = images.reshape(-1, images.shape[-3], images.shape[-2], images.shape[-1])
+ return (images, )
+
+class VAEEncode:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "pixels": ("IMAGE", ), "vae": ("VAE", )}}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "encode"
+
+ CATEGORY = "latent"
+ SEARCH_ALIASES = ["encode", "encode image", "image to latent"]
+
+ def encode(self, vae, pixels):
+ t = vae.encode(pixels)
+ return ({"samples":t}, )
+
+class VAEEncodeTiled:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"pixels": ("IMAGE", ), "vae": ("VAE", ),
+ "tile_size": ("INT", {"default": 512, "min": 64, "max": 4096, "step": 64, "advanced": True}),
+ "overlap": ("INT", {"default": 64, "min": 0, "max": 4096, "step": 32, "advanced": True}),
+ "temporal_size": ("INT", {"default": 64, "min": 8, "max": 4096, "step": 4, "tooltip": "Only used for video VAEs: Amount of frames to encode at a time.", "advanced": True}),
+ "temporal_overlap": ("INT", {"default": 8, "min": 4, "max": 4096, "step": 4, "tooltip": "Only used for video VAEs: Amount of frames to overlap.", "advanced": True}),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "encode"
+
+ CATEGORY = "experimental"
+
+ def encode(self, vae, pixels, tile_size, overlap, temporal_size=64, temporal_overlap=8):
+ t = vae.encode_tiled(pixels, tile_x=tile_size, tile_y=tile_size, overlap=overlap, tile_t=temporal_size, overlap_t=temporal_overlap)
+ return ({"samples": t}, )
+
+class VAEEncodeForInpaint:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "pixels": ("IMAGE", ), "vae": ("VAE", ), "mask": ("MASK", ), "grow_mask_by": ("INT", {"default": 6, "min": 0, "max": 64, "step": 1}),}}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "encode"
+
+ CATEGORY = "latent/inpaint"
+
+ def encode(self, vae, pixels, mask, grow_mask_by=6):
+ downscale_ratio = vae.spacial_compression_encode()
+ x = (pixels.shape[1] // downscale_ratio) * downscale_ratio
+ y = (pixels.shape[2] // downscale_ratio) * downscale_ratio
+ mask = torch.nn.functional.interpolate(mask.reshape((-1, 1, mask.shape[-2], mask.shape[-1])), size=(pixels.shape[1], pixels.shape[2]), mode="bilinear")
+
+ pixels = pixels.clone()
+ if pixels.shape[1] != x or pixels.shape[2] != y:
+ x_offset = (pixels.shape[1] % downscale_ratio) // 2
+ y_offset = (pixels.shape[2] % downscale_ratio) // 2
+ pixels = pixels[:,x_offset:x + x_offset, y_offset:y + y_offset,:]
+ mask = mask[:,:,x_offset:x + x_offset, y_offset:y + y_offset]
+
+ #grow mask by a few pixels to keep things seamless in latent space
+ if grow_mask_by == 0:
+ mask_erosion = mask
+ else:
+ kernel_tensor = torch.ones((1, 1, grow_mask_by, grow_mask_by))
+ padding = math.ceil((grow_mask_by - 1) / 2)
+
+ mask_erosion = torch.clamp(torch.nn.functional.conv2d(mask.round(), kernel_tensor, padding=padding), 0, 1)
+
+ m = (1.0 - mask.round()).squeeze(1)
+ for i in range(3):
+ pixels[:,:,:,i] -= 0.5
+ pixels[:,:,:,i] *= m
+ pixels[:,:,:,i] += 0.5
+ t = vae.encode(pixels)
+
+ return ({"samples":t, "noise_mask": (mask_erosion[:,:,:x,:y].round())}, )
+
+
+class InpaintModelConditioning:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"positive": ("CONDITIONING", ),
+ "negative": ("CONDITIONING", ),
+ "vae": ("VAE", ),
+ "pixels": ("IMAGE", ),
+ "mask": ("MASK", ),
+ "noise_mask": ("BOOLEAN", {"default": True, "tooltip": "Add a noise mask to the latent so sampling will only happen within the mask. Might improve results or completely break things depending on the model."}),
+ }}
+
+ RETURN_TYPES = ("CONDITIONING","CONDITIONING","LATENT")
+ RETURN_NAMES = ("positive", "negative", "latent")
+ FUNCTION = "encode"
+
+ CATEGORY = "conditioning/inpaint"
+
+ def encode(self, positive, negative, pixels, vae, mask, noise_mask=True):
+ x = (pixels.shape[1] // 8) * 8
+ y = (pixels.shape[2] // 8) * 8
+ mask = torch.nn.functional.interpolate(mask.reshape((-1, 1, mask.shape[-2], mask.shape[-1])), size=(pixels.shape[1], pixels.shape[2]), mode="bilinear")
+
+ orig_pixels = pixels
+ pixels = orig_pixels.clone()
+ if pixels.shape[1] != x or pixels.shape[2] != y:
+ x_offset = (pixels.shape[1] % 8) // 2
+ y_offset = (pixels.shape[2] % 8) // 2
+ pixels = pixels[:,x_offset:x + x_offset, y_offset:y + y_offset,:]
+ mask = mask[:,:,x_offset:x + x_offset, y_offset:y + y_offset]
+
+ m = (1.0 - mask.round()).squeeze(1)
+ for i in range(3):
+ pixels[:,:,:,i] -= 0.5
+ pixels[:,:,:,i] *= m
+ pixels[:,:,:,i] += 0.5
+ concat_latent = vae.encode(pixels)
+ orig_latent = vae.encode(orig_pixels)
+
+ out_latent = {}
+
+ out_latent["samples"] = orig_latent
+ if noise_mask:
+ out_latent["noise_mask"] = mask
+
+ out = []
+ for conditioning in [positive, negative]:
+ c = node_helpers.conditioning_set_values(conditioning, {"concat_latent_image": concat_latent,
+ "concat_mask": mask})
+ out.append(c)
+ return (out[0], out[1], out_latent)
+
+
+class SaveLatent:
+ SEARCH_ALIASES = ["export latent"]
+
+ def __init__(self):
+ self.output_dir = folder_paths.get_output_directory()
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT", ),
+ "filename_prefix": ("STRING", {"default": "latents/ComfyUI"})},
+ "hidden": {"prompt": "PROMPT", "extra_pnginfo": "EXTRA_PNGINFO"},
+ }
+ RETURN_TYPES = ()
+ FUNCTION = "save"
+
+ OUTPUT_NODE = True
+
+ CATEGORY = "experimental"
+
+ def save(self, samples, filename_prefix="ComfyUI", prompt=None, extra_pnginfo=None):
+ full_output_folder, filename, counter, subfolder, filename_prefix = folder_paths.get_save_image_path(filename_prefix, self.output_dir)
+
+ # support save metadata for latent sharing
+ prompt_info = ""
+ if prompt is not None:
+ prompt_info = json.dumps(prompt)
+
+ metadata = None
+ if not args.disable_metadata:
+ metadata = {"prompt": prompt_info}
+ if extra_pnginfo is not None:
+ for x in extra_pnginfo:
+ metadata[x] = json.dumps(extra_pnginfo[x])
+
+ file = f"{filename}_{counter:05}_.latent"
+
+ results: list[FileLocator] = []
+ results.append({
+ "filename": file,
+ "subfolder": subfolder,
+ "type": "output"
+ })
+
+ file = os.path.join(full_output_folder, file)
+
+ output = {}
+ output["latent_tensor"] = samples["samples"].contiguous()
+ output["latent_format_version_0"] = torch.tensor([])
+
+ comfy.utils.save_torch_file(output, file, metadata=metadata)
+ return { "ui": { "latents": results } }
+
+
+class LoadLatent:
+ SEARCH_ALIASES = ["import latent", "open latent"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ input_dir = folder_paths.get_input_directory()
+ files = [f for f in os.listdir(input_dir) if os.path.isfile(os.path.join(input_dir, f)) and f.endswith(".latent")]
+ return {"required": {"latent": [sorted(files), ]}, }
+
+ CATEGORY = "experimental"
+
+ RETURN_TYPES = ("LATENT", )
+ FUNCTION = "load"
+
+ def load(self, latent):
+ latent_path = folder_paths.get_annotated_filepath(latent)
+ latent = safetensors.torch.load_file(latent_path, device="cpu")
+ multiplier = 1.0
+ if "latent_format_version_0" not in latent:
+ multiplier = 1.0 / 0.18215
+ samples = {"samples": latent["latent_tensor"].float() * multiplier}
+ return (samples, )
+
+ @classmethod
+ def IS_CHANGED(s, latent):
+ image_path = folder_paths.get_annotated_filepath(latent)
+ m = hashlib.sha256()
+ with open(image_path, 'rb') as f:
+ m.update(f.read())
+ return m.digest().hex()
+
+ @classmethod
+ def VALIDATE_INPUTS(s, latent):
+ if not folder_paths.exists_annotated_filepath(latent):
+ return "Invalid latent file: {}".format(latent)
+ return True
+
+
+class CheckpointLoader:
+ SEARCH_ALIASES = ["load model", "model loader"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "config_name": (folder_paths.get_filename_list("configs"), ),
+ "ckpt_name": (folder_paths.get_filename_list("checkpoints"), )}}
+ RETURN_TYPES = ("MODEL", "CLIP", "VAE")
+ FUNCTION = "load_checkpoint"
+
+ CATEGORY = "advanced/loaders"
+ DEPRECATED = True
+
+ def load_checkpoint(self, config_name, ckpt_name):
+ config_path = folder_paths.get_full_path("configs", config_name)
+ ckpt_path = folder_paths.get_full_path_or_raise("checkpoints", ckpt_name)
+ return comfy.sd.load_checkpoint(config_path, ckpt_path, output_vae=True, output_clip=True, embedding_directory=folder_paths.get_folder_paths("embeddings"))
+
+class CheckpointLoaderSimple:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "ckpt_name": (folder_paths.get_filename_list("checkpoints"), {"tooltip": "The name of the checkpoint (model) to load."}),
+ }
+ }
+ RETURN_TYPES = ("MODEL", "CLIP", "VAE")
+ OUTPUT_TOOLTIPS = ("The model used for denoising latents.",
+ "The CLIP model used for encoding text prompts.",
+ "The VAE model used for encoding and decoding images to and from latent space.")
+ FUNCTION = "load_checkpoint"
+
+ CATEGORY = "loaders"
+ DESCRIPTION = "Loads a diffusion model checkpoint, diffusion models are used to denoise latents."
+ SEARCH_ALIASES = ["load model", "checkpoint", "model loader", "load checkpoint", "ckpt", "model"]
+
+ def load_checkpoint(self, ckpt_name):
+ ckpt_path = folder_paths.get_full_path_or_raise("checkpoints", ckpt_name)
+ out = comfy.sd.load_checkpoint_guess_config(ckpt_path, output_vae=True, output_clip=True, embedding_directory=folder_paths.get_folder_paths("embeddings"))
+ return out[:3]
+
+class DiffusersLoader:
+ SEARCH_ALIASES = ["load diffusers model"]
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ paths = []
+ for search_path in folder_paths.get_folder_paths("diffusers"):
+ if os.path.exists(search_path):
+ for root, subdir, files in os.walk(search_path, followlinks=True):
+ if "model_index.json" in files:
+ paths.append(os.path.relpath(root, start=search_path))
+
+ return {"required": {"model_path": (paths,), }}
+ RETURN_TYPES = ("MODEL", "CLIP", "VAE")
+ FUNCTION = "load_checkpoint"
+
+ CATEGORY = "advanced/loaders/deprecated"
+
+ def load_checkpoint(self, model_path, output_vae=True, output_clip=True):
+ for search_path in folder_paths.get_folder_paths("diffusers"):
+ if os.path.exists(search_path):
+ path = os.path.join(search_path, model_path)
+ if os.path.exists(path):
+ model_path = path
+ break
+
+ return comfy.diffusers_load.load_diffusers(model_path, output_vae=output_vae, output_clip=output_clip, embedding_directory=folder_paths.get_folder_paths("embeddings"))
+
+
+class unCLIPCheckpointLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "ckpt_name": (folder_paths.get_filename_list("checkpoints"), ),
+ }}
+ RETURN_TYPES = ("MODEL", "CLIP", "VAE", "CLIP_VISION")
+ FUNCTION = "load_checkpoint"
+
+ CATEGORY = "loaders"
+
+ def load_checkpoint(self, ckpt_name, output_vae=True, output_clip=True):
+ ckpt_path = folder_paths.get_full_path_or_raise("checkpoints", ckpt_name)
+ out = comfy.sd.load_checkpoint_guess_config(ckpt_path, output_vae=True, output_clip=True, output_clipvision=True, embedding_directory=folder_paths.get_folder_paths("embeddings"))
+ return out
+
+class CLIPSetLastLayer:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "clip": ("CLIP", ),
+ "stop_at_clip_layer": ("INT", {"default": -1, "min": -24, "max": -1, "step": 1, "advanced": True}),
+ }}
+ RETURN_TYPES = ("CLIP",)
+ FUNCTION = "set_last_layer"
+
+ CATEGORY = "conditioning"
+
+ def set_last_layer(self, clip, stop_at_clip_layer):
+ clip = clip.clone()
+ clip.clip_layer(stop_at_clip_layer)
+ return (clip,)
+
+class LoraLoader:
+ ESSENTIALS_CATEGORY = "Image Generation"
+
+ def __init__(self):
+ self.loaded_lora = None
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "model": ("MODEL", {"tooltip": "The diffusion model the LoRA will be applied to."}),
+ "clip": ("CLIP", {"tooltip": "The CLIP model the LoRA will be applied to."}),
+ "lora_name": (folder_paths.get_filename_list("loras"), {"tooltip": "The name of the LoRA."}),
+ "strength_model": ("FLOAT", {"default": 1.0, "min": -100.0, "max": 100.0, "step": 0.01, "tooltip": "How strongly to modify the diffusion model. This value can be negative."}),
+ "strength_clip": ("FLOAT", {"default": 1.0, "min": -100.0, "max": 100.0, "step": 0.01, "tooltip": "How strongly to modify the CLIP model. This value can be negative."}),
+ }
+ }
+
+ RETURN_TYPES = ("MODEL", "CLIP")
+ OUTPUT_TOOLTIPS = ("The modified diffusion model.", "The modified CLIP model.")
+ FUNCTION = "load_lora"
+
+ CATEGORY = "loaders"
+ DESCRIPTION = "LoRAs are used to modify diffusion and CLIP models, altering the way in which latents are denoised such as applying styles. Multiple LoRA nodes can be linked together."
+ SEARCH_ALIASES = ["lora", "load lora", "apply lora", "lora loader", "lora model"]
+
+ def load_lora(self, model, clip, lora_name, strength_model, strength_clip):
+ if strength_model == 0 and strength_clip == 0:
+ return (model, clip)
+
+ lora_path = folder_paths.get_full_path_or_raise("loras", lora_name)
+ lora = None
+ if self.loaded_lora is not None:
+ if self.loaded_lora[0] == lora_path:
+ lora = self.loaded_lora[1]
+ else:
+ self.loaded_lora = None
+
+ if lora is None:
+ lora = comfy.utils.load_torch_file(lora_path, safe_load=True)
+ self.loaded_lora = (lora_path, lora)
+
+ model_lora, clip_lora = comfy.sd.load_lora_for_models(model, clip, lora, strength_model, strength_clip)
+ return (model_lora, clip_lora)
+
+class LoraLoaderModelOnly(LoraLoader):
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "model": ("MODEL",),
+ "lora_name": (folder_paths.get_filename_list("loras"), ),
+ "strength_model": ("FLOAT", {"default": 1.0, "min": -100.0, "max": 100.0, "step": 0.01}),
+ }}
+ RETURN_TYPES = ("MODEL",)
+ FUNCTION = "load_lora_model_only"
+
+ def load_lora_model_only(self, model, lora_name, strength_model):
+ return (self.load_lora(model, None, lora_name, strength_model, 0)[0],)
+
+class VAELoader:
+ video_taes = ["taehv", "lighttaew2_2", "lighttaew2_1", "lighttaehy1_5", "taeltx_2"]
+ image_taes = ["taesd", "taesdxl", "taesd3", "taef1", "taef2"]
+
+ @staticmethod
+ def vae_list(s):
+ vaes = folder_paths.get_filename_list("vae")
+ approx_vaes = folder_paths.get_filename_list("vae_approx")
+ have_img_encoder, have_img_decoder = set(), set()
+ for v in approx_vaes:
+ parts = v.split("_", 1)
+ if len(parts) != 2 or parts[0] not in s.image_taes:
+ for tae in s.video_taes:
+ if v.startswith(tae):
+ vaes.append(v)
+ break
+ continue
+ if parts[1].startswith("encoder."):
+ have_img_encoder.add(parts[0])
+ elif parts[1].startswith("decoder."):
+ have_img_decoder.add(parts[0])
+ vaes += [k for k in have_img_decoder if k in have_img_encoder]
+ vaes.append("pixel_space")
+ return vaes
+
+ @staticmethod
+ def load_taesd(name):
+ sd = {}
+ approx_vaes = folder_paths.get_filename_list("vae_approx")
+
+ encoder = next(filter(lambda a: a.startswith("{}_encoder.".format(name)), approx_vaes))
+ decoder = next(filter(lambda a: a.startswith("{}_decoder.".format(name)), approx_vaes))
+
+ enc = comfy.utils.load_torch_file(folder_paths.get_full_path_or_raise("vae_approx", encoder))
+ for k in enc:
+ sd["taesd_encoder.{}".format(k)] = enc[k]
+
+ dec = comfy.utils.load_torch_file(folder_paths.get_full_path_or_raise("vae_approx", decoder))
+ for k in dec:
+ sd["taesd_decoder.{}".format(k)] = dec[k]
+
+ if name == "taesd":
+ sd["vae_scale"] = torch.tensor(0.18215)
+ sd["vae_shift"] = torch.tensor(0.0)
+ elif name == "taesdxl":
+ sd["vae_scale"] = torch.tensor(0.13025)
+ sd["vae_shift"] = torch.tensor(0.0)
+ elif name == "taesd3":
+ sd["vae_scale"] = torch.tensor(1.5305)
+ sd["vae_shift"] = torch.tensor(0.0609)
+ elif name == "taef1":
+ sd["vae_scale"] = torch.tensor(0.3611)
+ sd["vae_shift"] = torch.tensor(0.1159)
+ return sd
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "vae_name": (s.vae_list(s), )}}
+ RETURN_TYPES = ("VAE",)
+ FUNCTION = "load_vae"
+
+ CATEGORY = "loaders"
+
+ #TODO: scale factor?
+ def load_vae(self, vae_name):
+ metadata = None
+ if vae_name == "pixel_space":
+ sd = {}
+ sd["pixel_space_vae"] = torch.tensor(1.0)
+ elif vae_name in self.image_taes:
+ sd = self.load_taesd(vae_name)
+ else:
+ if os.path.splitext(vae_name)[0] in self.video_taes:
+ vae_path = folder_paths.get_full_path_or_raise("vae_approx", vae_name)
+ else:
+ vae_path = folder_paths.get_full_path_or_raise("vae", vae_name)
+ sd, metadata = comfy.utils.load_torch_file(vae_path, return_metadata=True)
+ if vae_name == "taef2":
+ if metadata is None:
+ metadata = {"tae_latent_channels": 128}
+ else:
+ metadata["tae_latent_channels"] = 128
+ vae = comfy.sd.VAE(sd=sd, metadata=metadata)
+ vae.throw_exception_if_invalid()
+ return (vae,)
+
+class ControlNetLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "control_net_name": (folder_paths.get_filename_list("controlnet"), )}}
+
+ RETURN_TYPES = ("CONTROL_NET",)
+ FUNCTION = "load_controlnet"
+
+ CATEGORY = "loaders"
+ SEARCH_ALIASES = ["controlnet", "control net", "cn", "load controlnet", "controlnet loader"]
+
+ def load_controlnet(self, control_net_name):
+ controlnet_path = folder_paths.get_full_path_or_raise("controlnet", control_net_name)
+ controlnet = comfy.controlnet.load_controlnet(controlnet_path)
+ if controlnet is None:
+ raise RuntimeError("ERROR: controlnet file is invalid and does not contain a valid controlnet model.")
+ return (controlnet,)
+
+class DiffControlNetLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "model": ("MODEL",),
+ "control_net_name": (folder_paths.get_filename_list("controlnet"), )}}
+
+ RETURN_TYPES = ("CONTROL_NET",)
+ FUNCTION = "load_controlnet"
+
+ CATEGORY = "loaders"
+
+ def load_controlnet(self, model, control_net_name):
+ controlnet_path = folder_paths.get_full_path_or_raise("controlnet", control_net_name)
+ controlnet = comfy.controlnet.load_controlnet(controlnet_path, model)
+ return (controlnet,)
+
+
+class ControlNetApply:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "control_net": ("CONTROL_NET", ),
+ "image": ("IMAGE", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01})
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "apply_controlnet"
+
+ DEPRECATED = True
+ CATEGORY = "conditioning/controlnet"
+
+ def apply_controlnet(self, conditioning, control_net, image, strength):
+ if strength == 0:
+ return (conditioning, )
+
+ c = []
+ control_hint = image.movedim(-1,1)
+ for t in conditioning:
+ n = [t[0], t[1].copy()]
+ c_net = control_net.copy().set_cond_hint(control_hint, strength)
+ if 'control' in t[1]:
+ c_net.set_previous_controlnet(t[1]['control'])
+ n[1]['control'] = c_net
+ n[1]['control_apply_to_uncond'] = True
+ c.append(n)
+ return (c, )
+
+
+class ControlNetApplyAdvanced:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"positive": ("CONDITIONING", ),
+ "negative": ("CONDITIONING", ),
+ "control_net": ("CONTROL_NET", ),
+ "image": ("IMAGE", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01}),
+ "start_percent": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+ "end_percent": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.001})
+ },
+ "optional": {"vae": ("VAE", ),
+ }
+ }
+
+ RETURN_TYPES = ("CONDITIONING","CONDITIONING")
+ RETURN_NAMES = ("positive", "negative")
+ FUNCTION = "apply_controlnet"
+
+ CATEGORY = "conditioning/controlnet"
+ SEARCH_ALIASES = ["controlnet", "apply controlnet", "use controlnet", "control net"]
+
+ def apply_controlnet(self, positive, negative, control_net, image, strength, start_percent, end_percent, vae=None, extra_concat=[]):
+ if strength == 0:
+ return (positive, negative)
+
+ control_hint = image.movedim(-1,1)
+ cnets = {}
+
+ out = []
+ for conditioning in [positive, negative]:
+ c = []
+ for t in conditioning:
+ d = t[1].copy()
+
+ prev_cnet = d.get('control', None)
+ if prev_cnet in cnets:
+ c_net = cnets[prev_cnet]
+ else:
+ c_net = control_net.copy().set_cond_hint(control_hint, strength, (start_percent, end_percent), vae=vae, extra_concat=extra_concat)
+ c_net.set_previous_controlnet(prev_cnet)
+ cnets[prev_cnet] = c_net
+
+ d['control'] = c_net
+ d['control_apply_to_uncond'] = False
+ n = [t[0], d]
+ c.append(n)
+ out.append(c)
+ return (out[0], out[1])
+
+
+class UNETLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "unet_name": (folder_paths.get_filename_list("diffusion_models"), ),
+ "weight_dtype": (["default", "fp8_e4m3fn", "fp8_e4m3fn_fast", "fp8_e5m2"], {"advanced": True})
+ }}
+ RETURN_TYPES = ("MODEL",)
+ FUNCTION = "load_unet"
+
+ CATEGORY = "advanced/loaders"
+
+ def load_unet(self, unet_name, weight_dtype):
+ model_options = {}
+ if weight_dtype == "fp8_e4m3fn":
+ model_options["dtype"] = torch.float8_e4m3fn
+ elif weight_dtype == "fp8_e4m3fn_fast":
+ model_options["dtype"] = torch.float8_e4m3fn
+ model_options["fp8_optimizations"] = True
+ elif weight_dtype == "fp8_e5m2":
+ model_options["dtype"] = torch.float8_e5m2
+
+ unet_path = folder_paths.get_full_path_or_raise("diffusion_models", unet_name)
+ model = comfy.sd.load_diffusion_model(unet_path, model_options=model_options)
+ return (model,)
+
+class CLIPLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "clip_name": (folder_paths.get_filename_list("text_encoders"), ),
+ "type": (["stable_diffusion", "stable_cascade", "sd3", "stable_audio", "mochi", "ltxv", "pixart", "cosmos", "lumina2", "wan", "hidream", "chroma", "ace", "omnigen2", "qwen_image", "hunyuan_image", "flux2", "ovis", "longcat_image", "cogvideox"], ),
+ },
+ "optional": {
+ "device": (["default", "cpu"], {"advanced": True}),
+ }}
+ RETURN_TYPES = ("CLIP",)
+ FUNCTION = "load_clip"
+
+ CATEGORY = "advanced/loaders"
+
+ DESCRIPTION = "[Recipes]\n\nstable_diffusion: clip-l\nstable_cascade: clip-g\nsd3: t5 xxl/ clip-g / clip-l\nstable_audio: t5 base\nmochi: t5 xxl\ncogvideox: t5 xxl (226-token padding)\ncosmos: old t5 xxl\nlumina2: gemma 2 2B\nwan: umt5 xxl\n hidream: llama-3.1 (Recommend) or t5\nomnigen2: qwen vl 2.5 3B"
+
+ def load_clip(self, clip_name, type="stable_diffusion", device="default"):
+ clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+
+ model_options = {}
+ if device == "cpu":
+ model_options["load_device"] = model_options["offload_device"] = torch.device("cpu")
+
+ clip_path = folder_paths.get_full_path_or_raise("text_encoders", clip_name)
+ clip = comfy.sd.load_clip(ckpt_paths=[clip_path], embedding_directory=folder_paths.get_folder_paths("embeddings"), clip_type=clip_type, model_options=model_options)
+ return (clip,)
+
+class DualCLIPLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "clip_name1": (folder_paths.get_filename_list("text_encoders"), ),
+ "clip_name2": (folder_paths.get_filename_list("text_encoders"), ),
+ "type": (["sdxl", "sd3", "flux", "hunyuan_video", "hidream", "hunyuan_image", "hunyuan_video_15", "kandinsky5", "kandinsky5_image", "ltxv", "newbie", "ace"], ),
+ },
+ "optional": {
+ "device": (["default", "cpu"], {"advanced": True}),
+ }}
+ RETURN_TYPES = ("CLIP",)
+ FUNCTION = "load_clip"
+
+ CATEGORY = "advanced/loaders"
+
+ DESCRIPTION = "[Recipes]\n\nsdxl: clip-l, clip-g\nsd3: clip-l, clip-g / clip-l, t5 / clip-g, t5\nflux: clip-l, t5\nhidream: at least one of t5 or llama, recommended t5 and llama\nhunyuan_image: qwen2.5vl 7b and byt5 small\nnewbie: gemma-3-4b-it, jina clip v2"
+
+ def load_clip(self, clip_name1, clip_name2, type, device="default"):
+ clip_type = getattr(comfy.sd.CLIPType, type.upper(), comfy.sd.CLIPType.STABLE_DIFFUSION)
+
+ clip_path1 = folder_paths.get_full_path_or_raise("text_encoders", clip_name1)
+ clip_path2 = folder_paths.get_full_path_or_raise("text_encoders", clip_name2)
+
+ model_options = {}
+ if device == "cpu":
+ model_options["load_device"] = model_options["offload_device"] = torch.device("cpu")
+
+ clip = comfy.sd.load_clip(ckpt_paths=[clip_path1, clip_path2], embedding_directory=folder_paths.get_folder_paths("embeddings"), clip_type=clip_type, model_options=model_options)
+ return (clip,)
+
+class CLIPVisionLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "clip_name": (folder_paths.get_filename_list("clip_vision"), ),
+ }}
+ RETURN_TYPES = ("CLIP_VISION",)
+ FUNCTION = "load_clip"
+
+ CATEGORY = "loaders"
+
+ def load_clip(self, clip_name):
+ clip_path = folder_paths.get_full_path_or_raise("clip_vision", clip_name)
+ clip_vision = comfy.clip_vision.load(clip_path)
+ if clip_vision is None:
+ raise RuntimeError("ERROR: clip vision file is invalid and does not contain a valid vision model.")
+ return (clip_vision,)
+
+class CLIPVisionEncode:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "clip_vision": ("CLIP_VISION",),
+ "image": ("IMAGE",),
+ "crop": (["center", "none"],)
+ }}
+ RETURN_TYPES = ("CLIP_VISION_OUTPUT",)
+ FUNCTION = "encode"
+
+ CATEGORY = "conditioning"
+
+ def encode(self, clip_vision, image, crop):
+ crop_image = True
+ if crop != "center":
+ crop_image = False
+ output = clip_vision.encode_image(image, crop=crop_image)
+ return (output,)
+
+class StyleModelLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "style_model_name": (folder_paths.get_filename_list("style_models"), )}}
+
+ RETURN_TYPES = ("STYLE_MODEL",)
+ FUNCTION = "load_style_model"
+
+ CATEGORY = "loaders"
+
+ def load_style_model(self, style_model_name):
+ style_model_path = folder_paths.get_full_path_or_raise("style_models", style_model_name)
+ style_model = comfy.sd.load_style_model(style_model_path)
+ return (style_model,)
+
+
+class StyleModelApply:
+ SEARCH_ALIASES = ["style transfer"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "style_model": ("STYLE_MODEL", ),
+ "clip_vision_output": ("CLIP_VISION_OUTPUT", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.001}),
+ "strength_type": (["multiply", "attn_bias"], ),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "apply_stylemodel"
+
+ CATEGORY = "conditioning/style_model"
+
+ def apply_stylemodel(self, conditioning, style_model, clip_vision_output, strength, strength_type):
+ cond = style_model.get_cond(clip_vision_output).flatten(start_dim=0, end_dim=1).unsqueeze(dim=0)
+ if strength_type == "multiply":
+ cond *= strength
+
+ n = cond.shape[1]
+ c_out = []
+ for t in conditioning:
+ (txt, keys) = t
+ keys = keys.copy()
+ # even if the strength is 1.0 (i.e, no change), if there's already a mask, we have to add to it
+ if "attention_mask" in keys or (strength_type == "attn_bias" and strength != 1.0):
+ # math.log raises an error if the argument is zero
+ # torch.log returns -inf, which is what we want
+ attn_bias = torch.log(torch.Tensor([strength if strength_type == "attn_bias" else 1.0]))
+ # get the size of the mask image
+ mask_ref_size = keys.get("attention_mask_img_shape", (1, 1))
+ n_ref = mask_ref_size[0] * mask_ref_size[1]
+ n_txt = txt.shape[1]
+ # grab the existing mask
+ mask = keys.get("attention_mask", None)
+ # create a default mask if it doesn't exist
+ if mask is None:
+ mask = torch.zeros((txt.shape[0], n_txt + n_ref, n_txt + n_ref), dtype=torch.float16)
+ # convert the mask dtype, because it might be boolean
+ # we want it to be interpreted as a bias
+ if mask.dtype == torch.bool:
+ # log(True) = log(1) = 0
+ # log(False) = log(0) = -inf
+ mask = torch.log(mask.to(dtype=torch.float16))
+ # now we make the mask bigger to add space for our new tokens
+ new_mask = torch.zeros((txt.shape[0], n_txt + n + n_ref, n_txt + n + n_ref), dtype=torch.float16)
+ # copy over the old mask, in quandrants
+ new_mask[:, :n_txt, :n_txt] = mask[:, :n_txt, :n_txt]
+ new_mask[:, :n_txt, n_txt+n:] = mask[:, :n_txt, n_txt:]
+ new_mask[:, n_txt+n:, :n_txt] = mask[:, n_txt:, :n_txt]
+ new_mask[:, n_txt+n:, n_txt+n:] = mask[:, n_txt:, n_txt:]
+ # now fill in the attention bias to our redux tokens
+ new_mask[:, :n_txt, n_txt:n_txt+n] = attn_bias
+ new_mask[:, n_txt+n:, n_txt:n_txt+n] = attn_bias
+ keys["attention_mask"] = new_mask.to(txt.device)
+ keys["attention_mask_img_shape"] = mask_ref_size
+
+ c_out.append([torch.cat((txt, cond), dim=1), keys])
+
+ return (c_out,)
+
+class unCLIPConditioning:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning": ("CONDITIONING", ),
+ "clip_vision_output": ("CLIP_VISION_OUTPUT", ),
+ "strength": ("FLOAT", {"default": 1.0, "min": -10.0, "max": 10.0, "step": 0.01}),
+ "noise_augmentation": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1.0, "step": 0.01}),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "apply_adm"
+
+ CATEGORY = "conditioning"
+
+ def apply_adm(self, conditioning, clip_vision_output, strength, noise_augmentation):
+ if strength == 0:
+ return (conditioning, )
+
+ c = node_helpers.conditioning_set_values(conditioning, {"unclip_conditioning": [{"clip_vision_output": clip_vision_output, "strength": strength, "noise_augmentation": noise_augmentation}]}, append=True)
+ return (c, )
+
+class GLIGENLoader:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "gligen_name": (folder_paths.get_filename_list("gligen"), )}}
+
+ RETURN_TYPES = ("GLIGEN",)
+ FUNCTION = "load_gligen"
+
+ CATEGORY = "loaders"
+
+ def load_gligen(self, gligen_name):
+ gligen_path = folder_paths.get_full_path_or_raise("gligen", gligen_name)
+ gligen = comfy.sd.load_gligen(gligen_path)
+ return (gligen,)
+
+class GLIGENTextBoxApply:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {"conditioning_to": ("CONDITIONING", ),
+ "clip": ("CLIP", ),
+ "gligen_textbox_model": ("GLIGEN", ),
+ "text": ("STRING", {"multiline": True, "dynamicPrompts": True}),
+ "width": ("INT", {"default": 64, "min": 8, "max": MAX_RESOLUTION, "step": 8}),
+ "height": ("INT", {"default": 64, "min": 8, "max": MAX_RESOLUTION, "step": 8}),
+ "x": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "y": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ }}
+ RETURN_TYPES = ("CONDITIONING",)
+ FUNCTION = "append"
+
+ CATEGORY = "conditioning/gligen"
+
+ def append(self, conditioning_to, clip, gligen_textbox_model, text, width, height, x, y):
+ c = []
+ cond, cond_pooled = clip.encode_from_tokens(clip.tokenize(text), return_pooled="unprojected")
+ for t in conditioning_to:
+ n = [t[0], t[1].copy()]
+ position_params = [(cond_pooled, height // 8, width // 8, y // 8, x // 8)]
+ prev = []
+ if "gligen" in n[1]:
+ prev = n[1]['gligen'][2]
+
+ n[1]['gligen'] = ("position", gligen_textbox_model, prev + position_params)
+ c.append(n)
+ return (c, )
+
+class EmptyLatentImage:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "width": ("INT", {"default": 512, "min": 16, "max": MAX_RESOLUTION, "step": 8, "tooltip": "The width of the latent images in pixels."}),
+ "height": ("INT", {"default": 512, "min": 16, "max": MAX_RESOLUTION, "step": 8, "tooltip": "The height of the latent images in pixels."}),
+ "batch_size": ("INT", {"default": 1, "min": 1, "max": 4096, "tooltip": "The number of latent images in the batch."})
+ }
+ }
+ RETURN_TYPES = ("LATENT",)
+ OUTPUT_TOOLTIPS = ("The empty latent image batch.",)
+ FUNCTION = "generate"
+
+ CATEGORY = "latent"
+ DESCRIPTION = "Create a new batch of empty latent images to be denoised via sampling."
+ SEARCH_ALIASES = ["empty", "empty latent", "new latent", "create latent", "blank latent", "blank"]
+
+ def generate(self, width, height, batch_size=1):
+ latent = torch.zeros([batch_size, 4, height // 8, width // 8], device=comfy.model_management.intermediate_device(), dtype=comfy.model_management.intermediate_dtype())
+ return ({"samples": latent, "downscale_ratio_spacial": 8}, )
+
+
+class LatentFromBatch:
+ SEARCH_ALIASES = ["select from batch", "pick latent", "batch subset"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "batch_index": ("INT", {"default": 0, "min": 0, "max": 63}),
+ "length": ("INT", {"default": 1, "min": 1, "max": 64}),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "frombatch"
+
+ CATEGORY = "latent/batch"
+
+ def frombatch(self, samples, batch_index, length):
+ s = samples.copy()
+ s_in = samples["samples"]
+ batch_index = min(s_in.shape[0] - 1, batch_index)
+ length = min(s_in.shape[0] - batch_index, length)
+ s["samples"] = s_in[batch_index:batch_index + length].clone()
+ if "noise_mask" in samples:
+ masks = samples["noise_mask"]
+ if masks.shape[0] == 1:
+ s["noise_mask"] = masks.clone()
+ else:
+ if masks.shape[0] < s_in.shape[0]:
+ masks = masks.repeat(math.ceil(s_in.shape[0] / masks.shape[0]), 1, 1, 1)[:s_in.shape[0]]
+ s["noise_mask"] = masks[batch_index:batch_index + length].clone()
+ if "batch_index" not in s:
+ s["batch_index"] = [x for x in range(batch_index, batch_index+length)]
+ else:
+ s["batch_index"] = samples["batch_index"][batch_index:batch_index + length]
+ return (s,)
+
+class RepeatLatentBatch:
+ SEARCH_ALIASES = ["duplicate latent", "clone latent"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "amount": ("INT", {"default": 1, "min": 1, "max": 64}),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "repeat"
+
+ CATEGORY = "latent/batch"
+
+ def repeat(self, samples, amount):
+ s = samples.copy()
+ s_in = samples["samples"]
+
+ s["samples"] = s_in.repeat((amount,) + ((1,) * (s_in.ndim - 1)))
+ if "noise_mask" in samples and samples["noise_mask"].shape[0] > 1:
+ masks = samples["noise_mask"]
+ if masks.shape[0] < s_in.shape[0]:
+ masks = masks.repeat((math.ceil(s_in.shape[0] / masks.shape[0]),) + ((1,) * (masks.ndim - 1)))[:s_in.shape[0]]
+ s["noise_mask"] = samples["noise_mask"].repeat((amount,) + ((1,) * (samples["noise_mask"].ndim - 1)))
+ if "batch_index" in s:
+ offset = max(s["batch_index"]) - min(s["batch_index"]) + 1
+ s["batch_index"] = s["batch_index"] + [x + (i * offset) for i in range(1, amount) for x in s["batch_index"]]
+ return (s,)
+
+class LatentUpscale:
+ SEARCH_ALIASES = ["enlarge latent", "resize latent"]
+
+ upscale_methods = ["nearest-exact", "bilinear", "area", "bicubic", "bislerp"]
+ crop_methods = ["disabled", "center"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",), "upscale_method": (s.upscale_methods,),
+ "width": ("INT", {"default": 512, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "height": ("INT", {"default": 512, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "crop": (s.crop_methods,)}}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "upscale"
+
+ CATEGORY = "latent"
+
+ def upscale(self, samples, upscale_method, width, height, crop):
+ if width == 0 and height == 0:
+ s = samples
+ else:
+ s = samples.copy()
+
+ if width == 0:
+ height = max(64, height)
+ width = max(64, round(samples["samples"].shape[-1] * height / samples["samples"].shape[-2]))
+ elif height == 0:
+ width = max(64, width)
+ height = max(64, round(samples["samples"].shape[-2] * width / samples["samples"].shape[-1]))
+ else:
+ width = max(64, width)
+ height = max(64, height)
+
+ s["samples"] = comfy.utils.common_upscale(samples["samples"], width // 8, height // 8, upscale_method, crop)
+ return (s,)
+
+class LatentUpscaleBy:
+ SEARCH_ALIASES = ["enlarge latent", "resize latent", "scale latent"]
+
+ upscale_methods = ["nearest-exact", "bilinear", "area", "bicubic", "bislerp"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",), "upscale_method": (s.upscale_methods,),
+ "scale_by": ("FLOAT", {"default": 1.5, "min": 0.01, "max": 8.0, "step": 0.01}),}}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "upscale"
+
+ CATEGORY = "latent"
+
+ def upscale(self, samples, upscale_method, scale_by):
+ s = samples.copy()
+ width = round(samples["samples"].shape[-1] * scale_by)
+ height = round(samples["samples"].shape[-2] * scale_by)
+ s["samples"] = comfy.utils.common_upscale(samples["samples"], width, height, upscale_method, "disabled")
+ return (s,)
+
+class LatentRotate:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "rotation": (["none", "90 degrees", "180 degrees", "270 degrees"],),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "rotate"
+
+ CATEGORY = "latent/transform"
+
+ def rotate(self, samples, rotation):
+ s = samples.copy()
+ rotate_by = 0
+ if rotation.startswith("90"):
+ rotate_by = 1
+ elif rotation.startswith("180"):
+ rotate_by = 2
+ elif rotation.startswith("270"):
+ rotate_by = 3
+
+ s["samples"] = torch.rot90(samples["samples"], k=rotate_by, dims=[3, 2])
+ return (s,)
+
+class LatentFlip:
+ SEARCH_ALIASES = ["mirror latent"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "flip_method": (["x-axis: vertically", "y-axis: horizontally"],),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "flip"
+
+ CATEGORY = "latent/transform"
+
+ def flip(self, samples, flip_method):
+ s = samples.copy()
+ if flip_method.startswith("x"):
+ s["samples"] = torch.flip(samples["samples"], dims=[2])
+ elif flip_method.startswith("y"):
+ s["samples"] = torch.flip(samples["samples"], dims=[3])
+
+ return (s,)
+
+class LatentComposite:
+ SEARCH_ALIASES = ["overlay latent", "layer latent", "paste latent"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples_to": ("LATENT",),
+ "samples_from": ("LATENT",),
+ "x": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "y": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "feather": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "composite"
+
+ CATEGORY = "latent"
+
+ def composite(self, samples_to, samples_from, x, y, composite_method="normal", feather=0):
+ x = x // 8
+ y = y // 8
+ feather = feather // 8
+ samples_out = samples_to.copy()
+ s = samples_to["samples"].clone()
+ samples_to = samples_to["samples"]
+ samples_from = samples_from["samples"]
+ if feather == 0:
+ s[:,:,y:y+samples_from.shape[2],x:x+samples_from.shape[3]] = samples_from[:,:,:samples_to.shape[2] - y, :samples_to.shape[3] - x]
+ else:
+ samples_from = samples_from[:,:,:samples_to.shape[2] - y, :samples_to.shape[3] - x]
+ mask = torch.ones_like(samples_from)
+ for t in range(feather):
+ if y != 0:
+ mask[:,:,t:1+t,:] *= ((1.0/feather) * (t + 1))
+
+ if y + samples_from.shape[2] < samples_to.shape[2]:
+ mask[:,:,mask.shape[2] -1 -t: mask.shape[2]-t,:] *= ((1.0/feather) * (t + 1))
+ if x != 0:
+ mask[:,:,:,t:1+t] *= ((1.0/feather) * (t + 1))
+ if x + samples_from.shape[3] < samples_to.shape[3]:
+ mask[:,:,:,mask.shape[3]- 1 - t: mask.shape[3]- t] *= ((1.0/feather) * (t + 1))
+ rev_mask = torch.ones_like(mask) - mask
+ s[:,:,y:y+samples_from.shape[2],x:x+samples_from.shape[3]] = samples_from[:,:,:samples_to.shape[2] - y, :samples_to.shape[3] - x] * mask + s[:,:,y:y+samples_from.shape[2],x:x+samples_from.shape[3]] * rev_mask
+ samples_out["samples"] = s
+ return (samples_out,)
+
+class LatentBlend:
+ SEARCH_ALIASES = ["mix latents", "interpolate latents"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": {
+ "samples1": ("LATENT",),
+ "samples2": ("LATENT",),
+ "blend_factor": ("FLOAT", {
+ "default": 0.5,
+ "min": 0,
+ "max": 1,
+ "step": 0.01
+ }),
+ }}
+
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "blend"
+
+ CATEGORY = "experimental"
+
+ def blend(self, samples1, samples2, blend_factor:float, blend_mode: str="normal"):
+
+ samples_out = samples1.copy()
+ samples1 = samples1["samples"]
+ samples2 = samples2["samples"]
+
+ if samples1.shape != samples2.shape:
+ samples2.permute(0, 3, 1, 2)
+ samples2 = comfy.utils.common_upscale(samples2, samples1.shape[3], samples1.shape[2], 'bicubic', crop='center')
+ samples2.permute(0, 2, 3, 1)
+
+ samples_blended = self.blend_mode(samples1, samples2, blend_mode)
+ samples_blended = samples1 * blend_factor + samples_blended * (1 - blend_factor)
+ samples_out["samples"] = samples_blended
+ return (samples_out,)
+
+ def blend_mode(self, img1, img2, mode):
+ if mode == "normal":
+ return img2
+ else:
+ raise ValueError(f"Unsupported blend mode: {mode}")
+
+class LatentCrop:
+ SEARCH_ALIASES = ["trim latent", "cut latent"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "width": ("INT", {"default": 512, "min": 64, "max": MAX_RESOLUTION, "step": 8}),
+ "height": ("INT", {"default": 512, "min": 64, "max": MAX_RESOLUTION, "step": 8}),
+ "x": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "y": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "crop"
+
+ CATEGORY = "latent/transform"
+
+ def crop(self, samples, width, height, x, y):
+ s = samples.copy()
+ samples = samples['samples']
+ x = x // 8
+ y = y // 8
+
+ #enfonce minimum size of 64
+ if x > (samples.shape[3] - 8):
+ x = samples.shape[3] - 8
+ if y > (samples.shape[2] - 8):
+ y = samples.shape[2] - 8
+
+ new_height = height // 8
+ new_width = width // 8
+ to_x = new_width + x
+ to_y = new_height + y
+ s['samples'] = samples[:,:,y:to_y, x:to_x]
+ return (s,)
+
+class SetLatentNoiseMask:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "samples": ("LATENT",),
+ "mask": ("MASK",),
+ }}
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "set_mask"
+
+ CATEGORY = "latent/inpaint"
+
+ def set_mask(self, samples, mask):
+ s = samples.copy()
+ s["noise_mask"] = mask.reshape((-1, 1, mask.shape[-2], mask.shape[-1]))
+ return (s,)
+
+def common_ksampler(model, seed, steps, cfg, sampler_name, scheduler, positive, negative, latent, denoise=1.0, disable_noise=False, start_step=None, last_step=None, force_full_denoise=False):
+ latent_image = latent["samples"]
+ latent_image = comfy.sample.fix_empty_latent_channels(model, latent_image, latent.get("downscale_ratio_spacial", None))
+
+ if disable_noise:
+ noise = torch.zeros(latent_image.size(), dtype=latent_image.dtype, layout=latent_image.layout, device="cpu")
+ else:
+ batch_inds = latent["batch_index"] if "batch_index" in latent else None
+ noise = comfy.sample.prepare_noise(latent_image, seed, batch_inds)
+
+ noise_mask = None
+ if "noise_mask" in latent:
+ noise_mask = latent["noise_mask"]
+
+ callback = latent_preview.prepare_callback(model, steps)
+ disable_pbar = not comfy.utils.PROGRESS_BAR_ENABLED
+ samples = comfy.sample.sample(model, noise, steps, cfg, sampler_name, scheduler, positive, negative, latent_image,
+ denoise=denoise, disable_noise=disable_noise, start_step=start_step, last_step=last_step,
+ force_full_denoise=force_full_denoise, noise_mask=noise_mask, callback=callback, disable_pbar=disable_pbar, seed=seed)
+ out = latent.copy()
+ out.pop("downscale_ratio_spacial", None)
+ out["samples"] = samples
+ return (out, )
+
+class KSampler:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "model": ("MODEL", {"tooltip": "The model used for denoising the input latent."}),
+ "seed": ("INT", {"default": 0, "min": 0, "max": 0xffffffffffffffff, "control_after_generate": True, "tooltip": "The random seed used for creating the noise."}),
+ "steps": ("INT", {"default": 20, "min": 1, "max": 10000, "tooltip": "The number of steps used in the denoising process."}),
+ "cfg": ("FLOAT", {"default": 8.0, "min": 0.0, "max": 100.0, "step":0.1, "round": 0.01, "tooltip": "The Classifier-Free Guidance scale balances creativity and adherence to the prompt. Higher values result in images more closely matching the prompt however too high values will negatively impact quality."}),
+ "sampler_name": (comfy.samplers.KSampler.SAMPLERS, {"tooltip": "The algorithm used when sampling, this can affect the quality, speed, and style of the generated output."}),
+ "scheduler": (comfy.samplers.KSampler.SCHEDULERS, {"tooltip": "The scheduler controls how noise is gradually removed to form the image."}),
+ "positive": ("CONDITIONING", {"tooltip": "The conditioning describing the attributes you want to include in the image."}),
+ "negative": ("CONDITIONING", {"tooltip": "The conditioning describing the attributes you want to exclude from the image."}),
+ "latent_image": ("LATENT", {"tooltip": "The latent image to denoise."}),
+ "denoise": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.01, "tooltip": "The amount of denoising applied, lower values will maintain the structure of the initial image allowing for image to image sampling."}),
+ }
+ }
+
+ RETURN_TYPES = ("LATENT",)
+ OUTPUT_TOOLTIPS = ("The denoised latent.",)
+ FUNCTION = "sample"
+
+ CATEGORY = "sampling"
+ DESCRIPTION = "Uses the provided model, positive and negative conditioning to denoise the latent image."
+ SEARCH_ALIASES = ["sampler", "sample", "generate", "denoise", "diffuse", "txt2img", "img2img"]
+
+ def sample(self, model, seed, steps, cfg, sampler_name, scheduler, positive, negative, latent_image, denoise=1.0):
+ return common_ksampler(model, seed, steps, cfg, sampler_name, scheduler, positive, negative, latent_image, denoise=denoise)
+
+class KSamplerAdvanced:
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required":
+ {"model": ("MODEL",),
+ "add_noise": (["enable", "disable"], {"advanced": True}),
+ "noise_seed": ("INT", {"default": 0, "min": 0, "max": 0xffffffffffffffff, "control_after_generate": True}),
+ "steps": ("INT", {"default": 20, "min": 1, "max": 10000}),
+ "cfg": ("FLOAT", {"default": 8.0, "min": 0.0, "max": 100.0, "step":0.1, "round": 0.01}),
+ "sampler_name": (comfy.samplers.KSampler.SAMPLERS, ),
+ "scheduler": (comfy.samplers.KSampler.SCHEDULERS, ),
+ "positive": ("CONDITIONING", ),
+ "negative": ("CONDITIONING", ),
+ "latent_image": ("LATENT", ),
+ "start_at_step": ("INT", {"default": 0, "min": 0, "max": 10000, "advanced": True}),
+ "end_at_step": ("INT", {"default": 10000, "min": 0, "max": 10000, "advanced": True}),
+ "return_with_leftover_noise": (["disable", "enable"], {"advanced": True}),
+ }
+ }
+
+ RETURN_TYPES = ("LATENT",)
+ FUNCTION = "sample"
+
+ CATEGORY = "sampling"
+
+ def sample(self, model, add_noise, noise_seed, steps, cfg, sampler_name, scheduler, positive, negative, latent_image, start_at_step, end_at_step, return_with_leftover_noise, denoise=1.0):
+ force_full_denoise = True
+ if return_with_leftover_noise == "enable":
+ force_full_denoise = False
+ disable_noise = False
+ if add_noise == "disable":
+ disable_noise = True
+ return common_ksampler(model, noise_seed, steps, cfg, sampler_name, scheduler, positive, negative, latent_image, denoise=denoise, disable_noise=disable_noise, start_step=start_at_step, last_step=end_at_step, force_full_denoise=force_full_denoise)
+
+class SaveImage:
+ def __init__(self):
+ self.output_dir = folder_paths.get_output_directory()
+ self.type = "output"
+ self.prefix_append = ""
+ self.compress_level = 4
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "images": ("IMAGE", {"tooltip": "The images to save."}),
+ "filename_prefix": ("STRING", {"default": "ComfyUI", "tooltip": "The prefix for the file to save. This may include formatting information such as %date:yyyy-MM-dd% or %Empty Latent Image.width% to include values from nodes."})
+ },
+ "hidden": {
+ "prompt": "PROMPT", "extra_pnginfo": "EXTRA_PNGINFO"
+ },
+ }
+
+ RETURN_TYPES = ()
+ FUNCTION = "save_images"
+
+ OUTPUT_NODE = True
+
+ CATEGORY = "image"
+ ESSENTIALS_CATEGORY = "Basics"
+ DESCRIPTION = "Saves the input images to your ComfyUI output directory."
+ SEARCH_ALIASES = ["save", "save image", "export image", "output image", "write image", "download"]
+
+ def save_images(self, images, filename_prefix="ComfyUI", prompt=None, extra_pnginfo=None):
+ filename_prefix += self.prefix_append
+ full_output_folder, filename, counter, subfolder, filename_prefix = folder_paths.get_save_image_path(filename_prefix, self.output_dir, images[0].shape[1], images[0].shape[0])
+ results = list()
+ for (batch_number, image) in enumerate(images):
+ i = 255. * image.cpu().numpy()
+ img = Image.fromarray(np.clip(i, 0, 255).astype(np.uint8))
+ metadata = None
+ if not args.disable_metadata:
+ metadata = PngInfo()
+ if prompt is not None:
+ metadata.add_text("prompt", json.dumps(prompt))
+ if extra_pnginfo is not None:
+ for x in extra_pnginfo:
+ metadata.add_text(x, json.dumps(extra_pnginfo[x]))
+
+ filename_with_batch_num = filename.replace("%batch_num%", str(batch_number))
+ file = f"{filename_with_batch_num}_{counter:05}_.png"
+ img.save(os.path.join(full_output_folder, file), pnginfo=metadata, compress_level=self.compress_level)
+ results.append({
+ "filename": file,
+ "subfolder": subfolder,
+ "type": self.type
+ })
+ counter += 1
+
+ return { "ui": { "images": results } }
+
+class PreviewImage(SaveImage):
+ def __init__(self):
+ self.output_dir = folder_paths.get_temp_directory()
+ self.type = "temp"
+ self.prefix_append = "_temp_" + ''.join(random.choice("abcdefghijklmnopqrstupvxyz") for x in range(5))
+ self.compress_level = 1
+
+ SEARCH_ALIASES = ["preview", "preview image", "show image", "view image", "display image", "image viewer"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required":
+ {"images": ("IMAGE", ), },
+ "hidden": {"prompt": "PROMPT", "extra_pnginfo": "EXTRA_PNGINFO"},
+ }
+
+class LoadImage:
+ @classmethod
+ def INPUT_TYPES(s):
+ input_dir = folder_paths.get_input_directory()
+ files = [f for f in os.listdir(input_dir) if os.path.isfile(os.path.join(input_dir, f))]
+ files = folder_paths.filter_files_content_types(files, ["image"])
+ return {"required":
+ {"image": (sorted(files), {"image_upload": True})},
+ }
+
+ CATEGORY = "image"
+ ESSENTIALS_CATEGORY = "Basics"
+ SEARCH_ALIASES = ["load image", "open image", "import image", "image input", "upload image", "read image", "image loader"]
+
+ RETURN_TYPES = ("IMAGE", "MASK")
+ FUNCTION = "load_image"
+
+ def load_image(self, image):
+ image_path = folder_paths.get_annotated_filepath(image)
+
+ dtype = comfy.model_management.intermediate_dtype()
+ device = comfy.model_management.intermediate_device()
+
+ components = InputImpl.VideoFromFile(image_path).get_components()
+ if components.images.shape[0] > 0:
+ return (components.images.to(device=device, dtype=dtype), (1.0 - components.alpha[..., -1]).to(device=device, dtype=dtype) if components.alpha is not None else torch.zeros((components.images.shape[0], 64, 64), dtype=dtype, device=device))
+
+ # This code is left here to handle animated webp which pyav does not support loading
+ img = node_helpers.pillow(Image.open, image_path)
+
+ output_images = []
+ output_masks = []
+ w, h = None, None
+
+ for i in ImageSequence.Iterator(img):
+ i = node_helpers.pillow(ImageOps.exif_transpose, i)
+
+ image = i.convert("RGB")
+
+ if len(output_images) == 0:
+ w = image.size[0]
+ h = image.size[1]
+
+ if image.size[0] != w or image.size[1] != h:
+ continue
+
+ image = np.array(image).astype(np.float32) / 255.0
+ image = torch.from_numpy(image)[None,]
+ if 'A' in i.getbands():
+ mask = np.array(i.getchannel('A')).astype(np.float32) / 255.0
+ mask = 1. - torch.from_numpy(mask)
+ else:
+ mask = torch.zeros((64, 64), dtype=torch.float32, device="cpu")
+ output_images.append(image.to(dtype=dtype))
+ output_masks.append(mask.unsqueeze(0).to(dtype=dtype))
+
+ output_image = torch.cat(output_images, dim=0)
+ output_mask = torch.cat(output_masks, dim=0)
+
+ return (output_image.to(device=device, dtype=dtype), output_mask.to(device=device, dtype=dtype))
+
+ @classmethod
+ def IS_CHANGED(s, image):
+ image_path = folder_paths.get_annotated_filepath(image)
+ m = hashlib.sha256()
+ with open(image_path, 'rb') as f:
+ m.update(f.read())
+ return m.digest().hex()
+
+ @classmethod
+ def VALIDATE_INPUTS(s, image):
+ if not folder_paths.exists_annotated_filepath(image):
+ return "Invalid image file: {}".format(image)
+
+ return True
+
+
+class LoadImageMask(LoadImage):
+ ESSENTIALS_CATEGORY = "Image Tools"
+ SEARCH_ALIASES = ["import mask", "alpha mask", "channel mask"]
+
+ _color_channels = ["alpha", "red", "green", "blue"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ types = super().INPUT_TYPES()
+ return {
+ "required": {
+ **types["required"],
+ "channel": (s._color_channels, )
+ }
+ }
+
+ CATEGORY = "mask"
+ RETURN_TYPES = ("MASK",)
+ FUNCTION = "load_image_mask"
+
+ def load_image_mask(self, image, channel):
+ image_tensor, mask_tensor = super().load_image(image)
+ c = channel[0].upper()
+
+ if c == 'A':
+ return (mask_tensor,)
+
+ channel_idx = {'R': 0, 'G': 1, 'B': 2}.get(c, 0)
+
+ if channel_idx < image_tensor.shape[-1]:
+ return (image_tensor[..., channel_idx].clone(),)
+ else:
+ empty_mask = torch.zeros(
+ image_tensor.shape[:-1],
+ dtype=image_tensor.dtype,
+ device=image_tensor.device
+ )
+ return (empty_mask,)
+
+ @classmethod
+ def IS_CHANGED(s, image, channel):
+ return super().IS_CHANGED(image)
+
+
+class LoadImageOutput(LoadImage):
+ SEARCH_ALIASES = ["output image", "previous generation"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "image": ("COMBO", {
+ "image_upload": True,
+ "image_folder": "output",
+ "remote": {
+ "route": "/internal/files/output",
+ "refresh_button": True,
+ "control_after_refresh": "first",
+ },
+ }),
+ }
+ }
+
+ DESCRIPTION = "Load an image from the output folder. When the refresh button is clicked, the node will update the image list and automatically select the first image, allowing for easy iteration."
+ EXPERIMENTAL = True
+ FUNCTION = "load_image"
+
+
+class ImageScale:
+ upscale_methods = ["nearest-exact", "bilinear", "area", "bicubic", "lanczos"]
+ crop_methods = ["disabled", "center"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "image": ("IMAGE",), "upscale_method": (s.upscale_methods,),
+ "width": ("INT", {"default": 512, "min": 0, "max": MAX_RESOLUTION, "step": 1}),
+ "height": ("INT", {"default": 512, "min": 0, "max": MAX_RESOLUTION, "step": 1}),
+ "crop": (s.crop_methods,)}}
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "upscale"
+
+ CATEGORY = "image/upscaling"
+ ESSENTIALS_CATEGORY = "Image Tools"
+ SEARCH_ALIASES = ["resize", "resize image", "scale image", "image resize", "zoom", "zoom in", "change size"]
+
+ def upscale(self, image, upscale_method, width, height, crop):
+ if width == 0 and height == 0:
+ s = image
+ else:
+ samples = image.movedim(-1,1)
+
+ if width == 0:
+ width = max(1, round(samples.shape[3] * height / samples.shape[2]))
+ elif height == 0:
+ height = max(1, round(samples.shape[2] * width / samples.shape[3]))
+
+ s = comfy.utils.common_upscale(samples, width, height, upscale_method, crop)
+ s = s.movedim(1,-1)
+ return (s,)
+
+class ImageScaleBy:
+ ESSENTIALS_CATEGORY = "Image Tools"
+ upscale_methods = ["nearest-exact", "bilinear", "area", "bicubic", "lanczos"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "image": ("IMAGE",), "upscale_method": (s.upscale_methods,),
+ "scale_by": ("FLOAT", {"default": 1.0, "min": 0.01, "max": 8.0, "step": 0.01}),}}
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "upscale"
+
+ CATEGORY = "image/upscaling"
+
+ def upscale(self, image, upscale_method, scale_by):
+ samples = image.movedim(-1,1)
+ width = round(samples.shape[3] * scale_by)
+ height = round(samples.shape[2] * scale_by)
+ s = comfy.utils.common_upscale(samples, width, height, upscale_method, "disabled")
+ s = s.movedim(1,-1)
+ return (s,)
+
+class ImageInvert:
+ SEARCH_ALIASES = ["reverse colors"]
+ ESSENTIALS_CATEGORY = "Image Tools"
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "image": ("IMAGE",)}}
+
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "invert"
+
+ CATEGORY = "image/color"
+
+ def invert(self, image):
+ s = 1.0 - image
+ return (s,)
+
+class ImageBatch:
+ SEARCH_ALIASES = ["combine images", "merge images", "stack images"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "image1": ("IMAGE",), "image2": ("IMAGE",)}}
+
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "batch"
+
+ CATEGORY = "image/batch"
+ DEPRECATED = True
+
+ def batch(self, image1, image2):
+ if image1.shape[-1] != image2.shape[-1]:
+ if image1.shape[-1] > image2.shape[-1]:
+ image2 = torch.nn.functional.pad(image2, (0,1), mode='constant', value=1.0)
+ else:
+ image1 = torch.nn.functional.pad(image1, (0,1), mode='constant', value=1.0)
+ if image1.shape[1:] != image2.shape[1:]:
+ image2 = comfy.utils.common_upscale(image2.movedim(-1,1), image1.shape[2], image1.shape[1], "bilinear", "center").movedim(1,-1)
+ s = torch.cat((image1, image2), dim=0)
+ return (s,)
+
+class EmptyImage:
+ def __init__(self, device="cpu"):
+ self.device = device
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {"required": { "width": ("INT", {"default": 512, "min": 1, "max": MAX_RESOLUTION, "step": 1}),
+ "height": ("INT", {"default": 512, "min": 1, "max": MAX_RESOLUTION, "step": 1}),
+ "batch_size": ("INT", {"default": 1, "min": 1, "max": 4096}),
+ "color": ("INT", {"default": 0, "min": 0, "max": 0xFFFFFF, "step": 1, "display": "color"}),
+ }}
+ RETURN_TYPES = ("IMAGE",)
+ FUNCTION = "generate"
+
+ CATEGORY = "image"
+
+ def generate(self, width, height, batch_size=1, color=0):
+ dtype = comfy.model_management.intermediate_dtype()
+ device = comfy.model_management.intermediate_device()
+ r = torch.full([batch_size, height, width, 1], ((color >> 16) & 0xFF) / 0xFF, device=device, dtype=dtype)
+ g = torch.full([batch_size, height, width, 1], ((color >> 8) & 0xFF) / 0xFF, device=device, dtype=dtype)
+ b = torch.full([batch_size, height, width, 1], ((color) & 0xFF) / 0xFF, device=device, dtype=dtype)
+ return (torch.cat((r, g, b), dim=-1), )
+
+class ImagePadForOutpaint:
+ SEARCH_ALIASES = ["extend canvas", "expand image"]
+
+ @classmethod
+ def INPUT_TYPES(s):
+ return {
+ "required": {
+ "image": ("IMAGE",),
+ "left": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "top": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "right": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "bottom": ("INT", {"default": 0, "min": 0, "max": MAX_RESOLUTION, "step": 8}),
+ "feathering": ("INT", {"default": 40, "min": 0, "max": MAX_RESOLUTION, "step": 1, "advanced": True}),
+ }
+ }
+
+ RETURN_TYPES = ("IMAGE", "MASK")
+ FUNCTION = "expand_image"
+
+ CATEGORY = "image/transform"
+
+ def expand_image(self, image, left, top, right, bottom, feathering):
+ d1, d2, d3, d4 = image.size()
+
+ new_image = torch.ones(
+ (d1, d2 + top + bottom, d3 + left + right, d4),
+ dtype=torch.float32,
+ ) * 0.5
+
+ new_image[:, top:top + d2, left:left + d3, :] = image
+
+ mask = torch.ones(
+ (d2 + top + bottom, d3 + left + right),
+ dtype=torch.float32,
+ )
+
+ t = torch.zeros(
+ (d2, d3),
+ dtype=torch.float32
+ )
+
+ if feathering > 0 and feathering * 2 < d2 and feathering * 2 < d3:
+
+ for i in range(d2):
+ for j in range(d3):
+ dt = i if top != 0 else d2
+ db = d2 - i if bottom != 0 else d2
+
+ dl = j if left != 0 else d3
+ dr = d3 - j if right != 0 else d3
+
+ d = min(dt, db, dl, dr)
+
+ if d >= feathering:
+ continue
+
+ v = (feathering - d) / feathering
+
+ t[i, j] = v * v
+
+ mask[top:top + d2, left:left + d3] = t
+
+ return (new_image, mask.unsqueeze(0))
+
+
+NODE_CLASS_MAPPINGS = {
+ "KSampler": KSampler,
+ "CheckpointLoaderSimple": CheckpointLoaderSimple,
+ "CLIPTextEncode": CLIPTextEncode,
+ "CLIPSetLastLayer": CLIPSetLastLayer,
+ "VAEDecode": VAEDecode,
+ "VAEEncode": VAEEncode,
+ "VAEEncodeForInpaint": VAEEncodeForInpaint,
+ "VAELoader": VAELoader,
+ "EmptyLatentImage": EmptyLatentImage,
+ "LatentUpscale": LatentUpscale,
+ "LatentUpscaleBy": LatentUpscaleBy,
+ "LatentFromBatch": LatentFromBatch,
+ "RepeatLatentBatch": RepeatLatentBatch,
+ "SaveImage": SaveImage,
+ "PreviewImage": PreviewImage,
+ "LoadImage": LoadImage,
+ "LoadImageMask": LoadImageMask,
+ "LoadImageOutput": LoadImageOutput,
+ "ImageScale": ImageScale,
+ "ImageScaleBy": ImageScaleBy,
+ "ImageInvert": ImageInvert,
+ "ImageBatch": ImageBatch,
+ "ImagePadForOutpaint": ImagePadForOutpaint,
+ "EmptyImage": EmptyImage,
+ "ConditioningAverage": ConditioningAverage ,
+ "ConditioningCombine": ConditioningCombine,
+ "ConditioningConcat": ConditioningConcat,
+ "ConditioningSetArea": ConditioningSetArea,
+ "ConditioningSetAreaPercentage": ConditioningSetAreaPercentage,
+ "ConditioningSetAreaStrength": ConditioningSetAreaStrength,
+ "ConditioningSetMask": ConditioningSetMask,
+ "KSamplerAdvanced": KSamplerAdvanced,
+ "SetLatentNoiseMask": SetLatentNoiseMask,
+ "LatentComposite": LatentComposite,
+ "LatentBlend": LatentBlend,
+ "LatentRotate": LatentRotate,
+ "LatentFlip": LatentFlip,
+ "LatentCrop": LatentCrop,
+ "LoraLoader": LoraLoader,
+ "CLIPLoader": CLIPLoader,
+ "UNETLoader": UNETLoader,
+ "DualCLIPLoader": DualCLIPLoader,
+ "CLIPVisionEncode": CLIPVisionEncode,
+ "StyleModelApply": StyleModelApply,
+ "unCLIPConditioning": unCLIPConditioning,
+ "ControlNetApply": ControlNetApply,
+ "ControlNetApplyAdvanced": ControlNetApplyAdvanced,
+ "ControlNetLoader": ControlNetLoader,
+ "DiffControlNetLoader": DiffControlNetLoader,
+ "StyleModelLoader": StyleModelLoader,
+ "CLIPVisionLoader": CLIPVisionLoader,
+ "VAEDecodeTiled": VAEDecodeTiled,
+ "VAEEncodeTiled": VAEEncodeTiled,
+ "unCLIPCheckpointLoader": unCLIPCheckpointLoader,
+ "GLIGENLoader": GLIGENLoader,
+ "GLIGENTextBoxApply": GLIGENTextBoxApply,
+ "InpaintModelConditioning": InpaintModelConditioning,
+
+ "CheckpointLoader": CheckpointLoader,
+ "DiffusersLoader": DiffusersLoader,
+
+ "LoadLatent": LoadLatent,
+ "SaveLatent": SaveLatent,
+
+ "ConditioningZeroOut": ConditioningZeroOut,
+ "ConditioningSetTimestepRange": ConditioningSetTimestepRange,
+ "LoraLoaderModelOnly": LoraLoaderModelOnly,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+ # Sampling
+ "KSampler": "KSampler",
+ "KSamplerAdvanced": "KSampler (Advanced)",
+ # Loaders
+ "CheckpointLoader": "Load Checkpoint With Config (DEPRECATED)",
+ "CheckpointLoaderSimple": "Load Checkpoint",
+ "VAELoader": "Load VAE",
+ "LoraLoader": "Load LoRA (Model and CLIP)",
+ "LoraLoaderModelOnly": "Load LoRA",
+ "CLIPLoader": "Load CLIP",
+ "ControlNetLoader": "Load ControlNet Model",
+ "DiffControlNetLoader": "Load ControlNet Model (diff)",
+ "StyleModelLoader": "Load Style Model",
+ "CLIPVisionLoader": "Load CLIP Vision",
+ "UNETLoader": "Load Diffusion Model",
+ "unCLIPCheckpointLoader": "Load unCLIP Checkpoint",
+ "GLIGENLoader": "Load GLIGEN Model",
+ # Conditioning
+ "CLIPVisionEncode": "CLIP Vision Encode",
+ "StyleModelApply": "Apply Style Model",
+ "CLIPTextEncode": "CLIP Text Encode (Prompt)",
+ "CLIPSetLastLayer": "CLIP Set Last Layer",
+ "ConditioningCombine": "Conditioning (Combine)",
+ "ConditioningAverage ": "Conditioning (Average)",
+ "ConditioningConcat": "Conditioning (Concat)",
+ "ConditioningSetArea": "Conditioning (Set Area)",
+ "ConditioningSetAreaPercentage": "Conditioning (Set Area with Percentage)",
+ "ConditioningSetMask": "Conditioning (Set Mask)",
+ "ControlNetApply": "Apply ControlNet (DEPRECATED)",
+ "ControlNetApplyAdvanced": "Apply ControlNet",
+ # Latent
+ "VAEEncodeForInpaint": "VAE Encode (for Inpainting)",
+ "SetLatentNoiseMask": "Set Latent Noise Mask",
+ "VAEDecode": "VAE Decode",
+ "VAEEncode": "VAE Encode",
+ "LatentRotate": "Rotate Latent",
+ "LatentFlip": "Flip Latent",
+ "LatentCrop": "Crop Latent",
+ "EmptyLatentImage": "Empty Latent Image",
+ "LatentUpscale": "Upscale Latent",
+ "LatentUpscaleBy": "Upscale Latent By",
+ "LatentComposite": "Latent Composite",
+ "LatentBlend": "Latent Blend",
+ "LatentFromBatch" : "Latent From Batch",
+ "RepeatLatentBatch": "Repeat Latent Batch",
+ # Image
+ "EmptyImage": "Empty Image",
+ "SaveImage": "Save Image",
+ "PreviewImage": "Preview Image",
+ "LoadImage": "Load Image",
+ "LoadImageMask": "Load Image (as Mask)",
+ "LoadImageOutput": "Load Image (from Outputs)",
+ "ImageScale": "Upscale Image",
+ "ImageScaleBy": "Upscale Image By",
+ "ImageInvert": "Invert Image Colors",
+ "ImagePadForOutpaint": "Pad Image for Outpainting",
+ "ImageBatch": "Batch Images (DEPRECATED)",
+ "ImageCrop": "Crop Image",
+ "ImageStitch": "Stitch Images",
+ "ImageBlend": "Blend Images",
+ "ImageBlur": "Blur Image",
+ "ImageQuantize": "Quantize Image",
+ "ImageSharpen": "Sharpen Image",
+ "ImageScaleToTotalPixels": "Scale Image to Total Pixels",
+ "GetImageSize": "Get Image Size",
+ # experimental
+ "VAEDecodeTiled": "VAE Decode (Tiled)",
+ "VAEEncodeTiled": "VAE Encode (Tiled)",
+}
+
+EXTENSION_WEB_DIRS = {}
+
+# Dictionary of successfully loaded module names and associated directories.
+LOADED_MODULE_DIRS = {}
+
+
+def get_module_name(module_path: str) -> str:
+ """
+ Returns the module name based on the given module path.
+ Examples:
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node.py") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node/") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node/__init__.py") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node/__init__") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node/__init__/") -> "my_custom_node"
+ get_module_name("C:/Users/username/ComfyUI/custom_nodes/my_custom_node.disabled") -> "custom_nodes
+ Args:
+ module_path (str): The path of the module.
+ Returns:
+ str: The module name.
+ """
+ base_path = os.path.basename(module_path)
+ if os.path.isfile(module_path):
+ base_path = os.path.splitext(base_path)[0]
+ return base_path
+
+
+async def load_custom_node(module_path: str, ignore=set(), module_parent="custom_nodes") -> bool:
+ module_name = get_module_name(module_path)
+ if os.path.isfile(module_path):
+ sp = os.path.splitext(module_path)
+ module_name = sp[0]
+ sys_module_name = module_name
+ elif os.path.isdir(module_path):
+ sys_module_name = module_path.replace(".", "_x_")
+
+ try:
+ logging.debug("Trying to load custom node {}".format(module_path))
+ if os.path.isfile(module_path):
+ module_spec = importlib.util.spec_from_file_location(sys_module_name, module_path)
+ module_dir = os.path.split(module_path)[0]
+ else:
+ module_spec = importlib.util.spec_from_file_location(sys_module_name, os.path.join(module_path, "__init__.py"))
+ module_dir = module_path
+
+ module = importlib.util.module_from_spec(module_spec)
+ sys.modules[sys_module_name] = module
+ module_spec.loader.exec_module(module)
+
+ LOADED_MODULE_DIRS[module_name] = os.path.abspath(module_dir)
+
+ try:
+ from comfy_config import config_parser
+
+ project_config = config_parser.extract_node_configuration(module_path)
+
+ web_dir_name = project_config.tool_comfy.web
+
+ if web_dir_name:
+ web_dir_path = os.path.join(module_path, web_dir_name)
+
+ if os.path.isdir(web_dir_path):
+ project_name = project_config.project.name
+
+ EXTENSION_WEB_DIRS[project_name] = web_dir_path
+
+ logging.info("Automatically register web folder {} for {}".format(web_dir_name, project_name))
+ except Exception as e:
+ logging.warning(f"Unable to parse pyproject.toml due to lack dependency pydantic-settings, please run 'pip install -r requirements.txt': {e}")
+
+ if hasattr(module, "WEB_DIRECTORY") and getattr(module, "WEB_DIRECTORY") is not None:
+ web_dir = os.path.abspath(os.path.join(module_dir, getattr(module, "WEB_DIRECTORY")))
+ if os.path.isdir(web_dir):
+ EXTENSION_WEB_DIRS[module_name] = web_dir
+
+ # V1 node definition
+ if hasattr(module, "NODE_CLASS_MAPPINGS") and getattr(module, "NODE_CLASS_MAPPINGS") is not None:
+ for name, node_cls in module.NODE_CLASS_MAPPINGS.items():
+ if name not in ignore:
+ NODE_CLASS_MAPPINGS[name] = node_cls
+ node_cls.RELATIVE_PYTHON_MODULE = "{}.{}".format(module_parent, get_module_name(module_path))
+ if hasattr(module, "NODE_DISPLAY_NAME_MAPPINGS") and getattr(module, "NODE_DISPLAY_NAME_MAPPINGS") is not None:
+ NODE_DISPLAY_NAME_MAPPINGS.update(module.NODE_DISPLAY_NAME_MAPPINGS)
+ return True
+ # V3 Extension Definition
+ elif hasattr(module, "comfy_entrypoint"):
+ entrypoint = getattr(module, "comfy_entrypoint")
+ if not callable(entrypoint):
+ logging.warning(f"comfy_entrypoint in {module_path} is not callable, skipping.")
+ return False
+ try:
+ if inspect.iscoroutinefunction(entrypoint):
+ extension = await entrypoint()
+ else:
+ extension = entrypoint()
+ if not isinstance(extension, ComfyExtension):
+ logging.warning(f"comfy_entrypoint in {module_path} did not return a ComfyExtension, skipping.")
+ return False
+ await extension.on_load()
+ node_list = await extension.get_node_list()
+ if not isinstance(node_list, list):
+ logging.warning(f"comfy_entrypoint in {module_path} did not return a list of nodes, skipping.")
+ return False
+ for node_cls in node_list:
+ node_cls: io.ComfyNode
+ schema = node_cls.GET_SCHEMA()
+ if schema.node_id not in ignore:
+ NODE_CLASS_MAPPINGS[schema.node_id] = node_cls
+ node_cls.RELATIVE_PYTHON_MODULE = "{}.{}".format(module_parent, get_module_name(module_path))
+ if schema.display_name is not None:
+ NODE_DISPLAY_NAME_MAPPINGS[schema.node_id] = schema.display_name
+ return True
+ except Exception as e:
+ logging.warning(f"Error while calling comfy_entrypoint in {module_path}: {e}")
+ return False
+ else:
+ logging.warning(f"Skip {module_path} module for custom nodes due to the lack of NODE_CLASS_MAPPINGS or comfy_entrypoint (need one).")
+ return False
+ except Exception as e:
+ logging.warning(traceback.format_exc())
+ logging.warning(f"Cannot import {module_path} module for custom nodes: {e}")
+ return False
+
+async def init_external_custom_nodes():
+ """
+ Initializes the external custom nodes.
+
+ This function loads custom nodes from the specified folder paths and imports them into the application.
+ It measures the import times for each custom node and logs the results.
+
+ Returns:
+ None
+ """
+ base_node_names = set(NODE_CLASS_MAPPINGS.keys())
+ node_paths = folder_paths.get_folder_paths("custom_nodes")
+ node_import_times = []
+ for custom_node_path in node_paths:
+ possible_modules = os.listdir(os.path.realpath(custom_node_path))
+ if "__pycache__" in possible_modules:
+ possible_modules.remove("__pycache__")
+
+ for possible_module in possible_modules:
+ module_path = os.path.join(custom_node_path, possible_module)
+ if os.path.isfile(module_path) and os.path.splitext(module_path)[1] != ".py":
+ continue
+ if module_path.endswith(".disabled"):
+ continue
+ if args.disable_all_custom_nodes and possible_module not in args.whitelist_custom_nodes:
+ logging.info(f"Skipping {possible_module} due to disable_all_custom_nodes and whitelist_custom_nodes")
+ continue
+
+ if args.enable_manager:
+ if comfyui_manager.should_be_disabled(module_path):
+ logging.info(f"Blocked by policy: {module_path}")
+ continue
+
+ time_before = time.perf_counter()
+ success = await load_custom_node(module_path, base_node_names, module_parent="custom_nodes")
+ node_import_times.append((time.perf_counter() - time_before, module_path, success))
+
+ if len(node_import_times) > 0:
+ logging.info("\nImport times for custom nodes:")
+ for n in sorted(node_import_times):
+ if n[2]:
+ import_message = ""
+ else:
+ import_message = " (IMPORT FAILED)"
+ logging.info("{:6.1f} seconds{}: {}".format(n[0], import_message, n[1]))
+ logging.info("")
+
+async def init_builtin_extra_nodes():
+ """
+ Initializes the built-in extra nodes in ComfyUI.
+
+ This function loads the extra node files located in the "comfy_extras" directory and imports them into ComfyUI.
+ If any of the extra node files fail to import, a warning message is logged.
+
+ Returns:
+ None
+ """
+ extras_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "comfy_extras")
+ extras_files = [
+ "nodes_latent.py",
+ "nodes_hypernetwork.py",
+ "nodes_upscale_model.py",
+ "nodes_post_processing.py",
+ "nodes_mask.py",
+ "nodes_compositing.py",
+ "nodes_rebatch.py",
+ "nodes_model_merging.py",
+ "nodes_tomesd.py",
+ "nodes_clip_sdxl.py",
+ "nodes_canny.py",
+ "nodes_freelunch.py",
+ "nodes_custom_sampler.py",
+ "nodes_hypertile.py",
+ "nodes_model_advanced.py",
+ "nodes_model_downscale.py",
+ "nodes_images.py",
+ "nodes_video_model.py",
+ "nodes_train.py",
+ "nodes_dataset.py",
+ "nodes_sag.py",
+ "nodes_perpneg.py",
+ "nodes_stable3d.py",
+ "nodes_sdupscale.py",
+ "nodes_photomaker.py",
+ "nodes_pixart.py",
+ "nodes_cond.py",
+ "nodes_morphology.py",
+ "nodes_stable_cascade.py",
+ "nodes_differential_diffusion.py",
+ "nodes_ip2p.py",
+ "nodes_model_merging_model_specific.py",
+ "nodes_pag.py",
+ "nodes_align_your_steps.py",
+ "nodes_attention_multiply.py",
+ "nodes_advanced_samplers.py",
+ "nodes_webcam.py",
+ "nodes_audio.py",
+ "nodes_sd3.py",
+ "nodes_gits.py",
+ "nodes_controlnet.py",
+ "nodes_hunyuan.py",
+ "nodes_eps.py",
+ "nodes_flux.py",
+ "nodes_lora_extract.py",
+ "nodes_torch_compile.py",
+ "nodes_mochi.py",
+ "nodes_slg.py",
+ "nodes_mahiro.py",
+ "nodes_lt_upsampler.py",
+ "nodes_lt_audio.py",
+ "nodes_lt.py",
+ "nodes_hooks.py",
+ "nodes_load_3d.py",
+ "nodes_cosmos.py",
+ "nodes_video.py",
+ "nodes_lumina2.py",
+ "nodes_wan.py",
+ "nodes_lotus.py",
+ "nodes_hunyuan3d.py",
+ "nodes_primitive.py",
+ "nodes_cfg.py",
+ "nodes_optimalsteps.py",
+ "nodes_hidream.py",
+ "nodes_fresca.py",
+ "nodes_apg.py",
+ "nodes_preview_any.py",
+ "nodes_ace.py",
+ "nodes_string.py",
+ "nodes_camera_trajectory.py",
+ "nodes_edit_model.py",
+ "nodes_tcfg.py",
+ "nodes_context_windows.py",
+ "nodes_qwen.py",
+ "nodes_chroma_radiance.py",
+ "nodes_model_patch.py",
+ "nodes_easycache.py",
+ "nodes_audio_encoder.py",
+ "nodes_rope.py",
+ "nodes_logic.py",
+ "nodes_resolution.py",
+ "nodes_nop.py",
+ "nodes_kandinsky5.py",
+ "nodes_wanmove.py",
+ "nodes_ar_video.py",
+ "nodes_image_compare.py",
+ "nodes_zimage.py",
+ "nodes_glsl.py",
+ "nodes_lora_debug.py",
+ "nodes_textgen.py",
+ "nodes_color.py",
+ "nodes_toolkit.py",
+ "nodes_replacements.py",
+ "nodes_nag.py",
+ "nodes_sdpose.py",
+ "nodes_math.py",
+ "nodes_number_convert.py",
+ "nodes_painter.py",
+ "nodes_curve.py",
+ "nodes_bg_removal.py",
+ "nodes_rtdetr.py",
+ "nodes_frame_interpolation.py",
+ "nodes_sam3.py",
+ "nodes_void.py",
+ "nodes_wandancer.py",
+ "nodes_hidream_o1.py",
+ "nodes_save_3d.py",
+ ]
+
+ import_failed = []
+ for node_file in extras_files:
+ if not await load_custom_node(os.path.join(extras_dir, node_file), module_parent="comfy_extras"):
+ import_failed.append(node_file)
+
+ return import_failed
+
+
+async def init_builtin_api_nodes():
+ api_nodes_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "comfy_api_nodes")
+ api_nodes_files = sorted(glob.glob(os.path.join(api_nodes_dir, "nodes_*.py")))
+
+ import_failed = []
+ for node_file in api_nodes_files:
+ if not await load_custom_node(node_file, module_parent="comfy_api_nodes"):
+ import_failed.append(os.path.basename(node_file))
+
+ return import_failed
+
+async def init_public_apis():
+ register_versions([
+ ComfyAPIWithVersion(
+ version=getattr(v, "VERSION"),
+ api_class=v
+ ) for v in supported_versions
+ ])
+
+async def init_extra_nodes(init_custom_nodes=True, init_api_nodes=True):
+ await init_public_apis()
+
+ import_failed = await init_builtin_extra_nodes()
+
+ import_failed_api = []
+ if init_api_nodes:
+ import_failed_api = await init_builtin_api_nodes()
+
+ if init_custom_nodes:
+ await init_external_custom_nodes()
+ else:
+ logging.info("Skipping loading of custom nodes")
+
+ if len(import_failed_api) > 0:
+ logging.warning("WARNING: some comfy_api_nodes/ nodes did not import correctly. This may be because they are missing some dependencies.\n")
+ for node in import_failed_api:
+ logging.warning("IMPORT FAILED: {}".format(node))
+ logging.warning("\nThis issue might be caused by new missing dependencies added the last time you updated ComfyUI.")
+ if args.windows_standalone_build:
+ logging.warning("Please run the update script: update/update_comfyui.bat")
+ else:
+ logging.warning("Please do a: pip install -r requirements.txt")
+ logging.warning("")
+
+ if len(import_failed) > 0:
+ logging.warning("WARNING: some comfy_extras/ nodes did not import correctly. This may be because they are missing some dependencies.\n")
+ for node in import_failed:
+ logging.warning("IMPORT FAILED: {}".format(node))
+ logging.warning("\nThis issue might be caused by new missing dependencies added the last time you updated ComfyUI.")
+ if args.windows_standalone_build:
+ logging.warning("Please run the update script: update/update_comfyui.bat")
+ else:
+ logging.warning("Please do a: pip install -r requirements.txt")
+ logging.warning("")
+
+ return import_failed
diff --git a/docs/hel-892/serialization-evidence/document-audit-summary.json b/docs/hel-892/serialization-evidence/document-audit-summary.json
new file mode 100644
index 00000000..dfd588aa
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/document-audit-summary.json
@@ -0,0 +1,24 @@
+{
+ "total": 155,
+ "audit_scope": "current_delivery",
+ "source_files": 156,
+ "target_files": 155,
+ "user_excluded": 1,
+ "source_structure_purpose_partially_reviewed": 155,
+ "full_documents_completed": 0,
+ "files_with_selected_named_fields_reviewed": 41,
+ "selected_named_fields_reviewed": 1217,
+ "real_executions": 0,
+ "states": {
+ "pending_check": 16,
+ "needs_conversion": 139
+ },
+ "named_values_preserved": 1217,
+ "unnamed_widget_nodes": 3660,
+ "semantic_batch_files": 139,
+ "semantic_batch_without_named_fields": 114,
+ "semantic_batch_named_fields": 490,
+ "named_values_without_manual_field_review": 0,
+ "named_values_without_verified_units_ranges_effects": 1217,
+ "scope_limit": "人工结论与机械原值清单分开;源语义局部审校非完整说明定稿"
+}
diff --git a/docs/hel-892/serialization-evidence/frontend-commit.json b/docs/hel-892/serialization-evidence/frontend-commit.json
new file mode 100644
index 00000000..fe6c13b9
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/frontend-commit.json
@@ -0,0 +1 @@
+{"tag": "v1.37.11", "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43"}
\ No newline at end of file
diff --git a/docs/hel-892/serialization-evidence/import-summary.json b/docs/hel-892/serialization-evidence/import-summary.json
new file mode 100644
index 00000000..45a5bfc6
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/import-summary.json
@@ -0,0 +1 @@
+{"batch_id": "87586f61-6a4e-4227-8ee3-32c7c4f6f204", "source_commit": "f62786f4a0c2eed48c22da7164e248d473be0d83", "counts": {"imported": 155, "user_excluded": 1}, "states": {"pending_check": 16, "needs_conversion": 139}, "source_total": 156, "excluded_total": 1, "target_total": 155, "total": 156, "doc_completed": 0, "exec_verified": 0}
diff --git a/docs/hel-892/serialization-evidence/lint.txt b/docs/hel-892/serialization-evidence/lint.txt
new file mode 100644
index 00000000..1f5f344d
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/lint.txt
@@ -0,0 +1 @@
+All checks passed!
diff --git a/docs/hel-892/serialization-evidence/package-check.txt b/docs/hel-892/serialization-evidence/package-check.txt
new file mode 100644
index 00000000..44e31e01
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/package-check.txt
@@ -0,0 +1 @@
+wheel contains current ui2api and serialization_reference modules and existing protocol/scope resources; source bytes match.
diff --git a/docs/hel-892/serialization-evidence/protection-summary.json b/docs/hel-892/serialization-evidence/protection-summary.json
new file mode 100644
index 00000000..cfd793fb
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/protection-summary.json
@@ -0,0 +1,8 @@
+{
+ "rows": 155,
+ "enabled": 0,
+ "doc_completed": 0,
+ "exec_verified": 0,
+ "source_files_unchanged": true,
+ "user_row_protection": "test_workflow_library.py and test_supplied_companions.py regression"
+}
diff --git a/docs/hel-892/serialization-evidence/regression.txt b/docs/hel-892/serialization-evidence/regression.txt
new file mode 100644
index 00000000..600a76cc
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/regression.txt
@@ -0,0 +1,9 @@
+........................................................................ [ 79%]
+................... [100%]
+=============================== warnings summary ===============================
+../../../../hel-892-830870af070f/workdir/aigc-home/calliope-backend/.venv/lib/python3.11/site-packages/starlette/testclient.py:53
+ /home/xiaomo/multica_workspaces/hello-af23464d222e/hel-892-830870af070f/workdir/aigc-home/calliope-backend/.venv/lib/python3.11/site-packages/starlette/testclient.py:53: DeprecationWarning: The anyio.abc.BlockingPortal alias is deprecated, use anyio.from_thread.BlockingPortal instead.
+ _PortalFactoryType = Callable[[], AbstractContextManager[anyio.abc.BlockingPortal]]
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+91 passed, 1 warning in 8.01s
diff --git a/docs/hel-892/serialization-evidence/reimport-summary.json b/docs/hel-892/serialization-evidence/reimport-summary.json
new file mode 100644
index 00000000..9319e39e
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/reimport-summary.json
@@ -0,0 +1 @@
+{"batch_id": "a9d14faa-e859-4c9e-bde6-d1f85d33821d", "source_commit": "f62786f4a0c2eed48c22da7164e248d473be0d83", "counts": {"skipped": 155, "user_excluded": 1}, "states": {"pending_check": 16, "needs_conversion": 139}, "source_total": 156, "excluded_total": 1, "target_total": 155, "total": 156, "doc_completed": 0, "exec_verified": 0}
diff --git a/docs/hel-892/serialization-evidence/six-case-comparison.json b/docs/hel-892/serialization-evidence/six-case-comparison.json
new file mode 100644
index 00000000..41d4eaeb
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/six-case-comparison.json
@@ -0,0 +1,2608 @@
+{
+ "profile": "comfy-frontend-1.37.11-core-reference",
+ "authority": "public_reference_only_not_object_info",
+ "comparison_scope": "supported root scalar widgets and legacy root link endpoints only",
+ "target_version_match": "unknown",
+ "whole_source_equivalence_verified": false,
+ "execution_verified": false,
+ "cases": [
+ {
+ "id": "01",
+ "source_path": "example_ComfyUI_workflows/0-基础处理:图像合并-音频分离-视频截取合并-图像视频放大/ControlNet_aux_常用样例.json",
+ "source_sha256": "8898689d777330c4749a079cd762f573bb12a278c47a2fefbd066ffbdc122b6b",
+ "api_sha256": "0ed76e088a23af43d6fecbf273fc0a983d7112e2b046d347f715afffac56d57e",
+ "source_frontend_version": null,
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:DepthAnythingPreprocessor",
+ "node_id": "4"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 images 的来源槽无法核对",
+ "node_id": "5"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "PreviewImage.images 缺少源文件值或连线",
+ "node_id": "5"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 images 的来源槽无法核对",
+ "node_id": "3"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "PreviewImage.images 缺少源文件值或连线",
+ "node_id": "3"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 images 的来源槽无法核对",
+ "node_id": "13"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "PreviewImage.images 缺少源文件值或连线",
+ "node_id": "13"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "12"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "1"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 image1 的来源槽无法核对",
+ "node_id": "28"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 image2 的来源槽无法核对",
+ "node_id": "28"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "ImageStitch.image1 缺少源文件值或连线",
+ "node_id": "28"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 image1 的来源槽无法核对",
+ "node_id": "29"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 image2 的来源槽无法核对",
+ "node_id": "29"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "ImageStitch.image1 缺少源文件值或连线",
+ "node_id": "29"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "18"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "19"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "20"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "21"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 images 的来源槽无法核对",
+ "node_id": "36"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "PreviewImage.images 缺少源文件值或连线",
+ "node_id": "36"
+ },
+ {
+ "code": "invalid_output_slot",
+ "message": "输入 images 的来源槽无法核对",
+ "node_id": "37"
+ },
+ {
+ "code": "missing_required_input",
+ "message": "PreviewImage.images 缺少源文件值或连线",
+ "node_id": "37"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "33"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AIO_Preprocessor",
+ "node_id": "34"
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [
+ {
+ "node_id": "10",
+ "field": "low_threshold",
+ "source_reference": 0.4,
+ "api": 0.4,
+ "differences": []
+ },
+ {
+ "node_id": "10",
+ "field": "high_threshold",
+ "source_reference": 0.8,
+ "api": 0.8,
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "field": "direction",
+ "source_reference": "down",
+ "api": "down",
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "field": "match_image_size",
+ "source_reference": true,
+ "api": true,
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "field": "spacing_width",
+ "source_reference": 2,
+ "api": 2,
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "field": "spacing_color",
+ "source_reference": "white",
+ "api": "white",
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "field": "direction",
+ "source_reference": "right",
+ "api": "right",
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "field": "match_image_size",
+ "source_reference": true,
+ "api": true,
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "field": "spacing_width",
+ "source_reference": 2,
+ "api": 2,
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "field": "spacing_color",
+ "source_reference": "white",
+ "api": "white",
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "field": "direction",
+ "source_reference": "right",
+ "api": "right",
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "field": "match_image_size",
+ "source_reference": true,
+ "api": true,
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "field": "spacing_width",
+ "source_reference": 2,
+ "api": 2,
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "field": "spacing_color",
+ "source_reference": "white",
+ "api": "white",
+ "differences": []
+ },
+ {
+ "node_id": "2",
+ "field": "image",
+ "source_reference": "comfyui-airport-editorial_00001_.png",
+ "api": "comfyui-airport-editorial_00001_.png",
+ "differences": []
+ },
+ {
+ "node_id": "38",
+ "field": "image",
+ "source_reference": "1772086821573.png",
+ "api": "1772086821573.png",
+ "differences": []
+ }
+ ],
+ "topology_edges": [
+ {
+ "node_id": "4",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "5",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "4",
+ 0
+ ],
+ "api": [
+ "4",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "3",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "1",
+ 0
+ ],
+ "api": [
+ "1",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "13",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "12",
+ 0
+ ],
+ "api": [
+ "12",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "12",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "1",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "10",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "11",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "10",
+ 0
+ ],
+ "api": [
+ "10",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "input": "image1",
+ "via_reroute": false,
+ "source_reference": [
+ "28",
+ 0
+ ],
+ "api": [
+ "28",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "30",
+ "input": "image2",
+ "via_reroute": false,
+ "source_reference": [
+ "29",
+ 0
+ ],
+ "api": [
+ "29",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "input": "image1",
+ "via_reroute": false,
+ "source_reference": [
+ "18",
+ 0
+ ],
+ "api": [
+ "18",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "28",
+ "input": "image2",
+ "via_reroute": false,
+ "source_reference": [
+ "19",
+ 0
+ ],
+ "api": [
+ "19",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "input": "image1",
+ "via_reroute": false,
+ "source_reference": [
+ "20",
+ 0
+ ],
+ "api": [
+ "20",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "29",
+ "input": "image2",
+ "via_reroute": false,
+ "source_reference": [
+ "21",
+ 0
+ ],
+ "api": [
+ "21",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "18",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "19",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "20",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "22",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "30",
+ 0
+ ],
+ "api": [
+ "30",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "21",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "36",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "33",
+ 0
+ ],
+ "api": [
+ "33",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "37",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "34",
+ 0
+ ],
+ "api": [
+ "34",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "33",
+ "input": "image",
+ "via_reroute": true,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "34",
+ "input": "image",
+ "via_reroute": false,
+ "source_reference": [
+ "38",
+ 0
+ ],
+ "api": [
+ "38",
+ 0
+ ],
+ "differences": []
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "4",
+ "type": "DepthAnythingPreprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "12",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "1",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "18",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "19",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "20",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "21",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "33",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "34",
+ "type": "AIO_Preprocessor",
+ "reason": "源节点声明与固定核心参考版本不符"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ },
+ {
+ "id": "02",
+ "source_path": "example_ComfyUI_workflows/1-语音生成/Qwen3-ASR-Subtitle语音转字幕.json",
+ "source_sha256": "47f9afa955a6a5dce37000cb6a15bac7516d26ff50b6398bda334c825552cfd8",
+ "api_sha256": "daa40971b730076691721afe95e165932df94e3423f1fc44dcb7707026e7125b",
+ "source_frontend_version": "1.37.11",
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "2"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "4"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "3"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "1"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PrimitiveNode",
+ "node_id": "7"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:LoadAudio",
+ "node_id": "6"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:AILab_Qwen3ASRSubtitle",
+ "node_id": "9"
+ },
+ {
+ "code": "empty_prompt",
+ "message": "未得到可执行节点",
+ "node_id": ""
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [],
+ "topology_edges": [
+ {
+ "node_id": "2",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "9",
+ 1
+ ],
+ "api": [
+ "9",
+ 1
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "4",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "9",
+ 0
+ ],
+ "api": [
+ "9",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "3",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "9",
+ 2
+ ],
+ "api": [
+ "9",
+ 2
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "1",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "9",
+ 3
+ ],
+ "api": [
+ "9",
+ 3
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "9",
+ "input": "audio",
+ "via_reroute": false,
+ "source_reference": [
+ "6",
+ 0
+ ],
+ "api": [
+ "6",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "9",
+ "input": "hints",
+ "via_reroute": false,
+ "source_reference": [
+ "7",
+ 0
+ ],
+ "api": "Important terms: ComfyUI, Qwen3-ASR\nUse exact casing for these terms.",
+ "differences": [
+ {
+ "path": "",
+ "expected": "Important terms: ComfyUI, Qwen3-ASR\nUse exact casing for these terms.",
+ "actual": [
+ "7",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "2",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "4",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "3",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "1",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "7",
+ "type": "PrimitiveNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "6",
+ "type": "LoadAudio",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "9",
+ "type": "AILab_Qwen3ASRSubtitle",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ },
+ {
+ "id": "03",
+ "source_path": "example_ComfyUI_workflows/2-音乐生成/minimax_music_文生音乐.json",
+ "source_sha256": "0a655ead5a0da406159dceb46451439df0c02050becaaa25b3018abb41840284",
+ "api_sha256": "91e6c2cea3747a03bbb71f661dbd016b28040781482b956365ff76a7a8b647ce",
+ "source_frontend_version": "1.48.7",
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "subgraph_requires_export",
+ "message": "包含子图:需原 ComfyUI API 导出及差分核对",
+ "node_id": ""
+ },
+ {
+ "code": "reference_frontend_mismatch",
+ "message": "源图声明的前端版本与固定参考不一致",
+ "node_id": ""
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SaveAudioAdvanced",
+ "node_id": "35"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ac99f841-a3de-4329-9564-953b81cf9e16",
+ "node_id": "37"
+ },
+ {
+ "code": "empty_prompt",
+ "message": "未得到可执行节点",
+ "node_id": ""
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [],
+ "topology_edges": [
+ {
+ "node_id": "35",
+ "input": "audio",
+ "via_reroute": false,
+ "source_reference": [
+ "37",
+ 0
+ ],
+ "api": [
+ "37:43",
+ 0
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "37:43",
+ "actual": "37"
+ }
+ ]
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "35",
+ "type": "SaveAudioAdvanced",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "37",
+ "type": "ac99f841-a3de-4329-9564-953b81cf9e16",
+ "reason": "源节点声明与固定核心参考版本不符"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ },
+ {
+ "id": "04",
+ "source_path": "example_ComfyUI_workflows/3-图像生成/Qwen-Image-2.1/Qwen_image2.1_文生图_提示词增强.json",
+ "source_sha256": "dfe10917d101bf1a8a8c20750f4360690ecd478e9eb33d16a59ea0c6f12c086c",
+ "api_sha256": "2066b07b2ca5390ba3e795df6b43934dab83865b12870b6ff26d8c0ef24f091e",
+ "source_frontend_version": "1.53.6",
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "subgraph_requires_export",
+ "message": "包含子图:需原 ComfyUI API 导出及差分核对",
+ "node_id": ""
+ },
+ {
+ "code": "reference_frontend_mismatch",
+ "message": "源图声明的前端版本与固定参考不一致",
+ "node_id": ""
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ResolutionSelector",
+ "node_id": "13"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:c291ceec-b98f-4751-9d0b-7bc288f27b30",
+ "node_id": "459"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SaveImageAdvanced",
+ "node_id": "461"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PrimitiveStringMultiline",
+ "node_id": "483"
+ },
+ {
+ "code": "empty_prompt",
+ "message": "未得到可执行节点",
+ "node_id": ""
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [],
+ "topology_edges": [
+ {
+ "node_id": "459",
+ "input": "prompt",
+ "via_reroute": false,
+ "source_reference": [
+ "483",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "483",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "459",
+ "input": "width",
+ "via_reroute": false,
+ "source_reference": [
+ "13",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "13",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "459",
+ "input": "height",
+ "via_reroute": false,
+ "source_reference": [
+ "13",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "13",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "461",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "459",
+ 0
+ ],
+ "api": [
+ "459:457",
+ 0
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "459:457",
+ "actual": "459"
+ }
+ ]
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "13",
+ "type": "ResolutionSelector",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "459",
+ "type": "c291ceec-b98f-4751-9d0b-7bc288f27b30",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "461",
+ "type": "SaveImageAdvanced",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "483",
+ "type": "PrimitiveStringMultiline",
+ "reason": "源节点声明与固定核心参考版本不符"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ },
+ {
+ "id": "05",
+ "source_path": "example_ComfyUI_workflows/4-视频生成/Minimax-h3/MiniMax_H3_导演台时间线素材_双采样潜空间放大_多分段拼接.json",
+ "source_sha256": "172eb8af3aca70082941427520fdcca06568957bab3d39101c5e9d6641b45e4a",
+ "api_sha256": "95a01c1ea27a8279a6dc202820505099a94161d91e0789189b61208b09007af8",
+ "source_frontend_version": "1.52.7",
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "reference_frontend_mismatch",
+ "message": "源图声明的前端版本与固定参考不一致",
+ "node_id": ""
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SaveVideo",
+ "node_id": "10"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ModelAttentionBackend",
+ "node_id": "19"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:MiniMaxH3SigmaShift",
+ "node_id": "18"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:BlockSparseAttention",
+ "node_id": "20"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:CLIPLoader",
+ "node_id": "2"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:VAELoader",
+ "node_id": "4"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:LoraLoaderModelOnly",
+ "node_id": "21"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ModelPreviewOverrideKJ",
+ "node_id": "22"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:MiniMaxH3FiniteSegmentSampler",
+ "node_id": "8"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:CreateVideo",
+ "node_id": "9"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ResolutionSelector",
+ "node_id": "24"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:MiniMaxH3TimelinePlanner",
+ "node_id": "7"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:VAELoader",
+ "node_id": "3"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:UNETLoader",
+ "node_id": "1"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:BasicScheduler",
+ "node_id": "5"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:KSamplerSelect",
+ "node_id": "6"
+ },
+ {
+ "code": "empty_prompt",
+ "message": "未得到可执行节点",
+ "node_id": ""
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [],
+ "topology_edges": [
+ {
+ "node_id": "10",
+ "input": "video",
+ "via_reroute": false,
+ "source_reference": [
+ "9",
+ 0
+ ],
+ "api": [
+ "9",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "19",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "18",
+ 0
+ ],
+ "api": [
+ "18",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "18",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "21",
+ 0
+ ],
+ "api": [
+ "21",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "20",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "19",
+ 0
+ ],
+ "api": [
+ "19",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "21",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "1",
+ 0
+ ],
+ "api": [
+ "1",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "22",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "20",
+ 0
+ ],
+ "api": [
+ "20",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "22",
+ 0
+ ],
+ "api": [
+ "22",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "clip",
+ "via_reroute": false,
+ "source_reference": [
+ "2",
+ 0
+ ],
+ "api": [
+ "2",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "vae",
+ "via_reroute": false,
+ "source_reference": [
+ "3",
+ 0
+ ],
+ "api": [
+ "3",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "audio_vae",
+ "via_reroute": false,
+ "source_reference": [
+ "4",
+ 0
+ ],
+ "api": [
+ "4",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "finite_plan",
+ "via_reroute": false,
+ "source_reference": [
+ "7",
+ 2
+ ],
+ "api": [
+ "7",
+ 2
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "sampler",
+ "via_reroute": false,
+ "source_reference": [
+ "6",
+ 0
+ ],
+ "api": [
+ "6",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "8",
+ "input": "sigmas",
+ "via_reroute": false,
+ "source_reference": [
+ "5",
+ 0
+ ],
+ "api": [
+ "5",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "9",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "8",
+ 1
+ ],
+ "api": [
+ "8",
+ 1
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "9",
+ "input": "audio",
+ "via_reroute": false,
+ "source_reference": [
+ "8",
+ 2
+ ],
+ "api": [
+ "8",
+ 2
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "7",
+ "input": "width",
+ "via_reroute": false,
+ "source_reference": [
+ "24",
+ 0
+ ],
+ "api": [
+ "24",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "7",
+ "input": "height",
+ "via_reroute": false,
+ "source_reference": [
+ "24",
+ 1
+ ],
+ "api": [
+ "24",
+ 1
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "5",
+ "input": "model",
+ "via_reroute": false,
+ "source_reference": [
+ "22",
+ 0
+ ],
+ "api": [
+ "22",
+ 0
+ ],
+ "differences": []
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "10",
+ "type": "SaveVideo",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "19",
+ "type": "ModelAttentionBackend",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "18",
+ "type": "MiniMaxH3SigmaShift",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "20",
+ "type": "BlockSparseAttention",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "2",
+ "type": "CLIPLoader",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "4",
+ "type": "VAELoader",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "21",
+ "type": "LoraLoaderModelOnly",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "22",
+ "type": "ModelPreviewOverrideKJ",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "8",
+ "type": "MiniMaxH3FiniteSegmentSampler",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "9",
+ "type": "CreateVideo",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "24",
+ "type": "ResolutionSelector",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "7",
+ "type": "MiniMaxH3TimelinePlanner",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "3",
+ "type": "VAELoader",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "1",
+ "type": "UNETLoader",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "5",
+ "type": "BasicScheduler",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "6",
+ "type": "KSamplerSelect",
+ "reason": "源节点声明与固定核心参考版本不符"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ },
+ {
+ "id": "07",
+ "source_path": "example_ComfyUI_workflows/6-动作迁移/Wan_Animate2_动作迁移_for循环长视频.json",
+ "source_sha256": "22b7853e22629822dd354b0b768e2961a53b4c2f480cfaceeaea9dc51c0f0d0b",
+ "api_sha256": "b1b4f6a6c02d8d21701943c67b62805b1210fed17e7e26b618c58e112ea1d70d",
+ "source_frontend_version": "1.48.6",
+ "export_frontend_version": null,
+ "whole_prompt_available": false,
+ "whole_prompt_differences": null,
+ "whole_prompt_issues": [
+ {
+ "code": "subgraph_requires_export",
+ "message": "包含子图:需原 ComfyUI API 导出及差分核对",
+ "node_id": ""
+ },
+ {
+ "code": "reference_frontend_mismatch",
+ "message": "源图声明的前端版本与固定参考不一致",
+ "node_id": ""
+ },
+ {
+ "code": "reference_link_invalid",
+ "message": "静音/旁路不在追线参考契约内",
+ "node_id": ""
+ },
+ {
+ "code": "reference_link_invalid",
+ "message": "静音/旁路不在追线参考契约内",
+ "node_id": ""
+ },
+ {
+ "code": "mode_requires_export",
+ "message": "SaveVideo 包含静音/旁路状态,需 API 导出核对",
+ "node_id": "292"
+ },
+ {
+ "code": "mode_requires_export",
+ "message": "79280513-53b2-4417-93f8-f3e116bb6736 包含静音/旁路状态,需 API 导出核对",
+ "node_id": "291"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PrimitiveStringMultiline",
+ "node_id": "583"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:INTConstant",
+ "node_id": "580"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:TTResolutionSelector",
+ "node_id": "579"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SetNode",
+ "node_id": "600"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:GetNode",
+ "node_id": "603"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:GetNode",
+ "node_id": "602"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:VHS_VideoInfoLoaded",
+ "node_id": "586"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SetNode",
+ "node_id": "604"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:GetNode",
+ "node_id": "605"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PrimitiveStringMultiline",
+ "node_id": "584"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SetNode",
+ "node_id": "597"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "538"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:ComfyMathExpression",
+ "node_id": "536"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:b798a87e-23ec-483d-ab9b-6af5b298d0ad",
+ "node_id": "477"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:GetNode",
+ "node_id": "598"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:11706f8a-428d-4ef9-b24f-863f651c1b0b",
+ "node_id": "261"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:PreviewAny",
+ "node_id": "607"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SetNode",
+ "node_id": "608"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:CreateVideo",
+ "node_id": "245"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:GetNode",
+ "node_id": "609"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SaveVideo",
+ "node_id": "246"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:SetNode",
+ "node_id": "601"
+ },
+ {
+ "code": "reference_widget_unverified",
+ "message": "源节点声明与固定核心参考版本不符",
+ "node_id": "189"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:Label (rgthree)",
+ "node_id": "610"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:bb1c37c2-3479-48a8-88c0-11e7d43715d6",
+ "node_id": "606"
+ },
+ {
+ "code": "reference_node_unsupported",
+ "message": "固定参考契约未覆盖节点:VHS_LoadVideo",
+ "node_id": "585"
+ },
+ {
+ "code": "empty_prompt",
+ "message": "未得到可执行节点",
+ "node_id": ""
+ }
+ ],
+ "production_prompt_available": false,
+ "serialized_fields": [],
+ "topology_edges": [
+ {
+ "node_id": "292",
+ "input": "video",
+ "status": "unsupported",
+ "reason": "静音/旁路不在追线参考契约内"
+ },
+ {
+ "node_id": "291",
+ "input": "video",
+ "status": "unsupported",
+ "reason": "静音/旁路不在追线参考契约内"
+ },
+ {
+ "node_id": "600",
+ "input": "AUDIO",
+ "via_reroute": false,
+ "source_reference": [
+ "585",
+ 2
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "585",
+ 2
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "586",
+ "input": "video_info",
+ "via_reroute": false,
+ "source_reference": [
+ "585",
+ 3
+ ],
+ "api": [
+ "585",
+ 3
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "604",
+ "input": "INT",
+ "via_reroute": false,
+ "source_reference": [
+ "586",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "586",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "597",
+ "input": "FLOAT",
+ "via_reroute": false,
+ "source_reference": [
+ "536",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "536",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "538",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "536",
+ 0
+ ],
+ "api": [
+ "536",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "536",
+ "input": "values.a",
+ "via_reroute": false,
+ "source_reference": [
+ "605",
+ 0
+ ],
+ "api": [
+ "586",
+ 1
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "586",
+ "actual": "605"
+ },
+ {
+ "path": "/1",
+ "kind": "value",
+ "expected": 1,
+ "actual": 0
+ }
+ ]
+ },
+ {
+ "node_id": "536",
+ "input": "values.b",
+ "via_reroute": false,
+ "source_reference": [
+ "580",
+ 0
+ ],
+ "api": [
+ "580",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "477",
+ "input": "input",
+ "via_reroute": true,
+ "source_reference": [
+ "189",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "189",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "continue_motion",
+ "via_reroute": false,
+ "source_reference": [
+ "606",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "606",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "video_frame_offset_1",
+ "via_reroute": false,
+ "source_reference": [
+ "606",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "606",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "text",
+ "via_reroute": false,
+ "source_reference": [
+ "583",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "583",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "text_4",
+ "via_reroute": false,
+ "source_reference": [
+ "584",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "584",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "resize_type.width",
+ "via_reroute": false,
+ "source_reference": [
+ "579",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "579",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "resize_type.height_1",
+ "via_reroute": false,
+ "source_reference": [
+ "579",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "579",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "length",
+ "via_reroute": false,
+ "source_reference": [
+ "580",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "580",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "477",
+ "input": "input_1",
+ "via_reroute": true,
+ "source_reference": [
+ "585",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "585",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "input",
+ "via_reroute": true,
+ "source_reference": [
+ "189",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "189",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "text",
+ "via_reroute": false,
+ "source_reference": [
+ "583",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "583",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "text_4",
+ "via_reroute": false,
+ "source_reference": [
+ "584",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "584",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "resize_type.width",
+ "via_reroute": false,
+ "source_reference": [
+ "579",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "579",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "resize_type.height_1",
+ "via_reroute": false,
+ "source_reference": [
+ "579",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "579",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "length",
+ "via_reroute": false,
+ "source_reference": [
+ "580",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "580",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "261",
+ "input": "input_1",
+ "via_reroute": true,
+ "source_reference": [
+ "585",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "585",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "607",
+ "input": "source",
+ "via_reroute": false,
+ "source_reference": [
+ "606",
+ 3
+ ],
+ "api": [
+ "606:596",
+ 0
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "606:596",
+ "actual": "606"
+ },
+ {
+ "path": "/1",
+ "kind": "value",
+ "expected": 0,
+ "actual": 3
+ }
+ ]
+ },
+ {
+ "node_id": "608",
+ "input": "*",
+ "via_reroute": false,
+ "source_reference": [
+ "606",
+ 2
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "606",
+ 2
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "245",
+ "input": "images",
+ "via_reroute": false,
+ "source_reference": [
+ "609",
+ 0
+ ],
+ "api": [
+ "606:599",
+ 2
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "606:599",
+ "actual": "609"
+ },
+ {
+ "path": "/1",
+ "kind": "value",
+ "expected": 2,
+ "actual": 0
+ }
+ ]
+ },
+ {
+ "node_id": "245",
+ "input": "audio",
+ "via_reroute": false,
+ "source_reference": [
+ "602",
+ 0
+ ],
+ "api": [
+ "585",
+ 2
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "585",
+ "actual": "602"
+ },
+ {
+ "path": "/1",
+ "kind": "value",
+ "expected": 2,
+ "actual": 0
+ }
+ ]
+ },
+ {
+ "node_id": "245",
+ "input": "fps",
+ "via_reroute": false,
+ "source_reference": [
+ "603",
+ 0
+ ],
+ "api": [
+ "586",
+ 0
+ ],
+ "differences": [
+ {
+ "path": "/0",
+ "kind": "value",
+ "expected": "586",
+ "actual": "603"
+ }
+ ]
+ },
+ {
+ "node_id": "246",
+ "input": "video",
+ "via_reroute": false,
+ "source_reference": [
+ "245",
+ 0
+ ],
+ "api": [
+ "245",
+ 0
+ ],
+ "differences": []
+ },
+ {
+ "node_id": "601",
+ "input": "FLOAT",
+ "via_reroute": false,
+ "source_reference": [
+ "586",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "586",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "initial_value1",
+ "via_reroute": false,
+ "source_reference": [
+ "261",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "261",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "initial_value2",
+ "via_reroute": false,
+ "source_reference": [
+ "261",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "261",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "initial_value3",
+ "via_reroute": false,
+ "source_reference": [
+ "261",
+ 2
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "261",
+ 2
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "a",
+ "via_reroute": false,
+ "source_reference": [
+ "598",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "598",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "initial_value1_1",
+ "via_reroute": false,
+ "source_reference": [
+ "477",
+ 0
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "477",
+ 0
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "initial_value2_1",
+ "via_reroute": false,
+ "source_reference": [
+ "477",
+ 1
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "477",
+ 1
+ ],
+ "kind": "type"
+ }
+ ]
+ },
+ {
+ "node_id": "606",
+ "input": "images.image1_1",
+ "via_reroute": false,
+ "source_reference": [
+ "477",
+ 2
+ ],
+ "api": null,
+ "differences": [
+ {
+ "path": "",
+ "expected": null,
+ "actual": [
+ "477",
+ 2
+ ],
+ "kind": "type"
+ }
+ ]
+ }
+ ],
+ "unsupported_widget_nodes": [
+ {
+ "node_id": "292",
+ "type": "SaveVideo",
+ "reason": "静音/旁路不在序列化参考契约内"
+ },
+ {
+ "node_id": "291",
+ "type": "79280513-53b2-4417-93f8-f3e116bb6736",
+ "reason": "静音/旁路不在序列化参考契约内"
+ },
+ {
+ "node_id": "583",
+ "type": "PrimitiveStringMultiline",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "580",
+ "type": "INTConstant",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "579",
+ "type": "TTResolutionSelector",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "600",
+ "type": "SetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "603",
+ "type": "GetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "602",
+ "type": "GetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "586",
+ "type": "VHS_VideoInfoLoaded",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "604",
+ "type": "SetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "605",
+ "type": "GetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "584",
+ "type": "PrimitiveStringMultiline",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "597",
+ "type": "SetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "538",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "536",
+ "type": "ComfyMathExpression",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "477",
+ "type": "b798a87e-23ec-483d-ab9b-6af5b298d0ad",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "598",
+ "type": "GetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "261",
+ "type": "11706f8a-428d-4ef9-b24f-863f651c1b0b",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "607",
+ "type": "PreviewAny",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "608",
+ "type": "SetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "245",
+ "type": "CreateVideo",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "609",
+ "type": "GetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "246",
+ "type": "SaveVideo",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "601",
+ "type": "SetNode",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "189",
+ "type": "LoadImage",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "610",
+ "type": "Label (rgthree)",
+ "reason": "控件数量/形式或节点类型不在固定参考契约内"
+ },
+ {
+ "node_id": "606",
+ "type": "bb1c37c2-3479-48a8-88c0-11e7d43715d6",
+ "reason": "源节点声明与固定核心参考版本不符"
+ },
+ {
+ "node_id": "585",
+ "type": "VHS_LoadVideo",
+ "reason": "源节点声明与固定核心参考版本不符"
+ }
+ ],
+ "executable": false,
+ "execution_verified": false
+ }
+ ]
+}
diff --git a/docs/hel-892/serialization-evidence/source-verification.json b/docs/hel-892/serialization-evidence/source-verification.json
new file mode 100644
index 00000000..e05d7996
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/source-verification.json
@@ -0,0 +1,83 @@
+{
+ "authority": "public_reference_only",
+ "sources_verified": [
+ {
+ "id": "ComfyUI_frontend:LICENSE",
+ "sha256": "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
+ },
+ {
+ "id": "ComfyUI:comfy_extras/nodes_images.py",
+ "sha256": "40f22183dcbc9f871030145ca33d52f3dd9d8f64b21ceb071c2fdf6cd49ff501"
+ },
+ {
+ "id": "ComfyUI:comfy_extras/nodes_canny.py",
+ "sha256": "c69f945190aaeb02fd3e81bbe21f5bf2dd70395a3bf17cbe8726261739146fff"
+ },
+ {
+ "id": "ComfyUI:nodes.py",
+ "sha256": "e09534d2c275b2bd389ba7d28677a24d86ce174cdb2419f3d424ff5e50b5d62a"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/dynamicPrompts.ts",
+ "sha256": "d190ef52ad9ca6d0351a8e08881773baf1dac49cd2eed71c2cceb20d90838216"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/rerouteNode.ts",
+ "sha256": "53abe69665c97427faa7e41d4d0b9b33c8c1415fff84f582ed51862bdf7bfcd8"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/uploadImage.ts",
+ "sha256": "935687284bebc3bbb49616976ccaf83c31998dd7abba231e5c8eaab0e8aa9e04"
+ },
+ {
+ "id": "ComfyUI_frontend:src/lib/litegraph/src/LGraphNode.ts",
+ "sha256": "706225a8a06cd7929f9e04fe2388bcdb8f158cdac756c65c45657c020ab7b319"
+ },
+ {
+ "id": "ComfyUI_frontend:src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts",
+ "sha256": "fd2e19a6b8f4369e6e97d79f407cc1bec130feec9d6d3c979cc03b0a556f249f"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget.ts",
+ "sha256": "36f477f75561e0c7bfc2c6757906724f8ff2c8660ace26759f3f07493877fece"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useComboWidget.ts",
+ "sha256": "578955db305e760d317b394d0c155caa6aa1e60a235a076e14aadadbd25222d4"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useFloatWidget.ts",
+ "sha256": "a6536de10db2ee4dca8f858f1b2ee68077e9313393e3657e9c22a49c408629e5"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts",
+ "sha256": "77d0603c9cb4397cdb33bcbee5721a3690b63f28e82eb11e79a356f0306e149d"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useIntWidget.ts",
+ "sha256": "68cb754c9c9ba48da2031981d65eca244d66c611314fc5690e96fdb941a0e8ff"
+ },
+ {
+ "id": "ComfyUI_frontend:src/scripts/widgets.ts",
+ "sha256": "e8bb428cbf69635015de43a4ebc89817b3443f876cbed52eeafe67d26f2398d8"
+ },
+ {
+ "id": "ComfyUI_frontend:src/services/litegraphService.ts",
+ "sha256": "ccd4b316a41b6e090716e6243f50135f87b209ff1531a4c3d6e29d99e4392041"
+ },
+ {
+ "id": "ComfyUI_frontend:src/utils/executionUtil.ts",
+ "sha256": "4e51bc54e35cb7ac9bb7cba418a74ccdd5974f640b9b088aa4ae7668f746ab36"
+ },
+ {
+ "id": "ComfyUI_frontend:src/utils/litegraphUtil.ts",
+ "sha256": "816d80ceb6a42abb61090f97172345e53827ab8ba1993817108ec6f8abc61505"
+ },
+ {
+ "id": "ComfyUI_frontend:src/workbench/utils/nodeDefOrderingUtil.ts",
+ "sha256": "27e98379fef3cb7158b2968d1b920ff16db662e4e0c5252ed62c7c7edc6f2227"
+ }
+ ],
+ "upstream_code_executed": false,
+ "target_version_match": "unknown"
+}
diff --git a/docs/hel-892/serialization-evidence/sources.json b/docs/hel-892/serialization-evidence/sources.json
new file mode 100644
index 00000000..45d06441
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/sources.json
@@ -0,0 +1,433 @@
+{
+ "schema_version": 1,
+ "authority": "public_reference_only_not_object_info",
+ "profile": "comfy-frontend-1.37.11-core-reference",
+ "source_frontend_version": null,
+ "source_frontend_version_basis": "case01未声明;选择case02声明的1.37.11为公开参考,绝不推定case01或真实导出匹配",
+ "core_schema_basis": "case01源节点属性:Canny/LoadImage 0.21.1、ImageStitch 0.17.0;PreviewImage沿用0.21.1参考,目标未知",
+ "scope": "unmodified local scalar widgets; no cloud, remote combo, custom extension, dynamic serializer or array value",
+ "target_version_match": "unknown",
+ "sources": [
+ {
+ "id": "ComfyUI_frontend:LICENSE",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "LICENSE",
+ "lines": [
+ [
+ 1,
+ 10
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/LICENSE",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/LICENSE",
+ "sha256": "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986",
+ "retrieved_at": "2026-10-29T15:18:59.361315+00:00",
+ "local_file": "LICENSE",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI:comfy_extras/nodes_images.py",
+ "repository": "https://github.com/Comfy-Org/ComfyUI",
+ "commit": "63d1bbdb407c69370d407ce5ced6ca3f917528a8",
+ "tag": "v0.17.0",
+ "file": "comfy_extras/nodes_images.py",
+ "lines": [
+ [
+ 253,
+ 277
+ ],
+ [
+ 832,
+ 841
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI/blob/63d1bbdb407c69370d407ce5ced6ca3f917528a8/comfy_extras/nodes_images.py",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI/63d1bbdb407c69370d407ce5ced6ca3f917528a8/comfy_extras/nodes_images.py",
+ "sha256": "40f22183dcbc9f871030145ca33d52f3dd9d8f64b21ceb071c2fdf6cd49ff501",
+ "retrieved_at": "2026-10-29T15:20:32.983124+00:00",
+ "local_file": "corev0.17.0__comfy_extras__nodes_images.py",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI:comfy_extras/nodes_canny.py",
+ "repository": "https://github.com/Comfy-Org/ComfyUI",
+ "commit": "26515acd23fa291a8f5ab53c5997258598de0701",
+ "tag": "v0.21.1",
+ "file": "comfy_extras/nodes_canny.py",
+ "lines": [
+ [
+ 9,
+ 44
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI/blob/26515acd23fa291a8f5ab53c5997258598de0701/comfy_extras/nodes_canny.py",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI/26515acd23fa291a8f5ab53c5997258598de0701/comfy_extras/nodes_canny.py",
+ "sha256": "c69f945190aaeb02fd3e81bbe21f5bf2dd70395a3bf17cbe8726261739146fff",
+ "retrieved_at": "2026-10-29T15:20:30.921972+00:00",
+ "local_file": "corev0.21.1__comfy_extras__nodes_canny.py",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI:nodes.py",
+ "repository": "https://github.com/Comfy-Org/ComfyUI",
+ "commit": "26515acd23fa291a8f5ab53c5997258598de0701",
+ "tag": "v0.21.1",
+ "file": "nodes.py",
+ "lines": [
+ [
+ 1620,
+ 1633
+ ],
+ [
+ 1665,
+ 1697
+ ],
+ [
+ 2020,
+ 2026
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI/blob/26515acd23fa291a8f5ab53c5997258598de0701/nodes.py",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI/26515acd23fa291a8f5ab53c5997258598de0701/nodes.py",
+ "sha256": "e09534d2c275b2bd389ba7d28677a24d86ce174cdb2419f3d424ff5e50b5d62a",
+ "retrieved_at": "2026-10-29T15:20:30.344472+00:00",
+ "local_file": "corev0.21.1__nodes.py",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/dynamicPrompts.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/extensions/core/dynamicPrompts.ts",
+ "lines": [
+ [
+ 1,
+ 30
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/dynamicPrompts.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/dynamicPrompts.ts",
+ "sha256": "d190ef52ad9ca6d0351a8e08881773baf1dac49cd2eed71c2cceb20d90838216",
+ "retrieved_at": "2026-10-29T15:18:58.033161+00:00",
+ "local_file": "src__extensions__core__dynamicPrompts.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/rerouteNode.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/extensions/core/rerouteNode.ts",
+ "lines": [
+ [
+ 21,
+ 38
+ ],
+ [
+ 80,
+ 113
+ ],
+ [
+ 280,
+ 293
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/rerouteNode.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/rerouteNode.ts",
+ "sha256": "53abe69665c97427faa7e41d4d0b9b33c8c1415fff84f582ed51862bdf7bfcd8",
+ "retrieved_at": "2026-10-29T15:12:31.976041+00:00",
+ "local_file": "src__extensions__core__rerouteNode.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/extensions/core/uploadImage.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/extensions/core/uploadImage.ts",
+ "lines": [
+ [
+ 25,
+ 53
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/uploadImage.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/extensions/core/uploadImage.ts",
+ "sha256": "935687284bebc3bbb49616976ccaf83c31998dd7abba231e5c8eaab0e8aa9e04",
+ "retrieved_at": "2026-10-29T15:12:44.918839+00:00",
+ "local_file": "src__extensions__core__uploadImage.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/lib/litegraph/src/LGraphNode.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/lib/litegraph/src/LGraphNode.ts",
+ "lines": [
+ [
+ 866,
+ 875
+ ],
+ [
+ 913,
+ 922
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/LGraphNode.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/LGraphNode.ts",
+ "sha256": "706225a8a06cd7929f9e04fe2388bcdb8f158cdac756c65c45657c020ab7b319",
+ "retrieved_at": "2026-10-29T15:12:44.050396+00:00",
+ "local_file": "src__lib__litegraph__src__LGraphNode.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts",
+ "lines": [
+ [
+ 142,
+ 170
+ ],
+ [
+ 220,
+ 240
+ ],
+ [
+ 250,
+ 320
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/lib/litegraph/src/subgraph/ExecutableNodeDTO.ts",
+ "sha256": "fd2e19a6b8f4369e6e97d79f407cc1bec130feec9d6d3c979cc03b0a556f249f",
+ "retrieved_at": "2026-10-29T15:14:28.683258+00:00",
+ "local_file": "src__lib__litegraph__src__subgraph__ExecutableNodeDTO.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget.ts",
+ "lines": [
+ [
+ 6,
+ 31
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget.ts",
+ "sha256": "36f477f75561e0c7bfc2c6757906724f8ff2c8660ace26759f3f07493877fece",
+ "retrieved_at": "2026-10-29T15:13:55.060959+00:00",
+ "local_file": "src__renderer__extensions__vueNodes__widgets__composables__useBooleanWidget.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useComboWidget.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/renderer/extensions/vueNodes/widgets/composables/useComboWidget.ts",
+ "lines": [
+ [
+ 215,
+ 252
+ ],
+ [
+ 291,
+ 305
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useComboWidget.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useComboWidget.ts",
+ "sha256": "578955db305e760d317b394d0c155caa6aa1e60a235a076e14aadadbd25222d4",
+ "retrieved_at": "2026-10-29T15:13:53.606321+00:00",
+ "local_file": "src__renderer__extensions__vueNodes__widgets__composables__useComboWidget.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useFloatWidget.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/renderer/extensions/vueNodes/widgets/composables/useFloatWidget.ts",
+ "lines": [
+ [
+ 58,
+ 95
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useFloatWidget.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useFloatWidget.ts",
+ "sha256": "a6536de10db2ee4dca8f858f1b2ee68077e9313393e3657e9c22a49c408629e5",
+ "retrieved_at": "2026-10-29T15:13:50.435623+00:00",
+ "local_file": "src__renderer__extensions__vueNodes__widgets__composables__useFloatWidget.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts",
+ "lines": [
+ [
+ 35,
+ 80
+ ],
+ [
+ 104,
+ 120
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget.ts",
+ "sha256": "77d0603c9cb4397cdb33bcbee5721a3690b63f28e82eb11e79a356f0306e149d",
+ "retrieved_at": "2026-10-29T15:13:49.563730+00:00",
+ "local_file": "src__renderer__extensions__vueNodes__widgets__composables__useImageUploadWidget.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/renderer/extensions/vueNodes/widgets/composables/useIntWidget.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/renderer/extensions/vueNodes/widgets/composables/useIntWidget.ts",
+ "lines": [
+ [
+ 45,
+ 89
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useIntWidget.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/renderer/extensions/vueNodes/widgets/composables/useIntWidget.ts",
+ "sha256": "68cb754c9c9ba48da2031981d65eca244d66c611314fc5690e96fdb941a0e8ff",
+ "retrieved_at": "2026-10-29T15:13:52.076416+00:00",
+ "local_file": "src__renderer__extensions__vueNodes__widgets__composables__useIntWidget.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/scripts/widgets.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/scripts/widgets.ts",
+ "lines": [
+ [
+ 80,
+ 91
+ ],
+ [
+ 126,
+ 161
+ ],
+ [
+ 283,
+ 305
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/scripts/widgets.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/scripts/widgets.ts",
+ "sha256": "e8bb428cbf69635015de43a4ebc89817b3443f876cbed52eeafe67d26f2398d8",
+ "retrieved_at": "2026-10-29T15:12:34.877619+00:00",
+ "local_file": "src__scripts__widgets.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/services/litegraphService.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/services/litegraphService.ts",
+ "lines": [
+ [
+ 90,
+ 106
+ ],
+ [
+ 144,
+ 195
+ ],
+ [
+ 202,
+ 212
+ ],
+ [
+ 350,
+ 367
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/services/litegraphService.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/services/litegraphService.ts",
+ "sha256": "ccd4b316a41b6e090716e6243f50135f87b209ff1531a4c3d6e29d99e4392041",
+ "retrieved_at": "2026-10-29T15:13:48.652249+00:00",
+ "local_file": "src__services__litegraphService.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/utils/executionUtil.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/utils/executionUtil.ts",
+ "lines": [
+ [
+ 74,
+ 145
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/utils/executionUtil.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/utils/executionUtil.ts",
+ "sha256": "4e51bc54e35cb7ac9bb7cba418a74ccdd5974f640b9b088aa4ae7668f746ab36",
+ "retrieved_at": "2026-10-29T15:12:29.674745+00:00",
+ "local_file": "src__utils__executionUtil.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/utils/litegraphUtil.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/utils/litegraphUtil.ts",
+ "lines": [
+ [
+ 95,
+ 137
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/utils/litegraphUtil.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/utils/litegraphUtil.ts",
+ "sha256": "816d80ceb6a42abb61090f97172345e53827ab8ba1993817108ec6f8abc61505",
+ "retrieved_at": "2026-10-29T15:18:57.413086+00:00",
+ "local_file": "src__utils__litegraphUtil.ts",
+ "target_version_match": "unknown"
+ },
+ {
+ "id": "ComfyUI_frontend:src/workbench/utils/nodeDefOrderingUtil.ts",
+ "repository": "https://github.com/Comfy-Org/ComfyUI_frontend",
+ "commit": "4bf6a1960028cc5cda57d48f9fb01a74dfaade43",
+ "tag": "v1.37.11",
+ "file": "src/workbench/utils/nodeDefOrderingUtil.ts",
+ "lines": [
+ [
+ 14,
+ 60
+ ]
+ ],
+ "url": "https://github.com/Comfy-Org/ComfyUI_frontend/blob/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/workbench/utils/nodeDefOrderingUtil.ts",
+ "raw_url": "https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/4bf6a1960028cc5cda57d48f9fb01a74dfaade43/src/workbench/utils/nodeDefOrderingUtil.ts",
+ "sha256": "27e98379fef3cb7158b2968d1b920ff16db662e4e0c5252ed62c7c7edc6f2227",
+ "retrieved_at": "2026-10-29T15:15:05.285092+00:00",
+ "local_file": "src__workbench__utils__nodeDefOrderingUtil.ts",
+ "target_version_match": "unknown"
+ }
+ ]
+}
diff --git a/docs/hel-892/serialization-evidence/src__extensions__core__dynamicPrompts.ts b/docs/hel-892/serialization-evidence/src__extensions__core__dynamicPrompts.ts
new file mode 100644
index 00000000..dabccf96
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__extensions__core__dynamicPrompts.ts
@@ -0,0 +1,30 @@
+import { useExtensionService } from '@/services/extensionService'
+import { processDynamicPrompt } from '@/utils/formatUtil'
+
+// Allows for simple dynamic prompt replacement
+// Inputs in the format {a|b} will have a random value of a or b chosen when the prompt is queued.
+
+useExtensionService().registerExtension({
+ name: 'Comfy.DynamicPrompts',
+ nodeCreated(node) {
+ if (node.widgets) {
+ // Locate dynamic prompt text widgets
+ // Include any widgets with dynamicPrompts set to true, and customtext
+ const widgets = node.widgets.filter((w) => w.dynamicPrompts)
+ for (const widget of widgets) {
+ // Override the serialization of the value to resolve dynamic prompts for all widgets supporting it in this node
+ widget.serializeValue = (workflowNode, widgetIndex) => {
+ if (typeof widget.value !== 'string') return widget.value
+
+ const prompt = processDynamicPrompt(widget.value)
+
+ // Overwrite the value in the serialized workflow pnginfo
+ if (workflowNode?.widgets_values)
+ workflowNode.widgets_values[widgetIndex] = prompt
+
+ return prompt
+ }
+ }
+ }
+ }
+})
diff --git a/docs/hel-892/serialization-evidence/src__extensions__core__rerouteNode.ts b/docs/hel-892/serialization-evidence/src__extensions__core__rerouteNode.ts
new file mode 100644
index 00000000..44c3f315
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__extensions__core__rerouteNode.ts
@@ -0,0 +1,295 @@
+import type { IContextMenuValue } from '@/lib/litegraph/src/litegraph'
+import {
+ LGraphCanvas,
+ LGraphNode,
+ LiteGraph
+} from '@/lib/litegraph/src/litegraph'
+import type { ISlotType } from '@/lib/litegraph/src/interfaces'
+
+import { app } from '../../scripts/app'
+import { getWidgetConfig, mergeIfValid, setWidgetConfig } from './widgetInputs'
+
+// Node that allows you to redirect connections for cleaner graphs
+
+app.registerExtension({
+ name: 'Comfy.RerouteNode',
+ registerCustomNodes(app) {
+ interface RerouteNode extends LGraphNode {
+ __outputType?: string | number
+ }
+
+ class RerouteNode extends LGraphNode {
+ static override category: string | undefined
+ static defaultVisibility = false
+
+ constructor(title?: string) {
+ super(title ?? '')
+ if (!this.properties) {
+ this.properties = {}
+ }
+ this.properties.showOutputText = RerouteNode.defaultVisibility
+ this.properties.horizontal = false
+
+ this.addInput('', '*')
+ this.addOutput(this.properties.showOutputText ? '*' : '', '*')
+
+ // This node is purely frontend and does not impact the resulting prompt so should not be serialized
+ this.isVirtualNode = true
+ }
+ override onAfterGraphConfigured() {
+ requestAnimationFrame(() => {
+ this.onConnectionsChange(LiteGraph.INPUT, undefined, true)
+ })
+ }
+ override clone(): LGraphNode | null {
+ const cloned = super.clone()
+ if (!cloned) return cloned
+ cloned.removeOutput(0)
+ cloned.addOutput(this.properties.showOutputText ? '*' : '', '*')
+ cloned.setSize(cloned.computeSize())
+ return cloned
+ }
+ override onConnectionsChange(
+ type: ISlotType,
+ _index: number | undefined,
+ connected: boolean
+ ) {
+ const { graph } = this
+ if (!graph) return
+ if (app.configuringGraph) return
+
+ // Prevent multiple connections to different types when we have no input
+ if (connected && type === LiteGraph.OUTPUT) {
+ // Ignore wildcard nodes as these will be updated to real types
+ const types = new Set(
+ this.outputs[0].links
+ ?.map((l) => graph.links[l]?.type)
+ ?.filter((t) => t && t !== '*') ?? []
+ )
+ if (types.size > 1) {
+ const linksToDisconnect = []
+ for (const linkId of this.outputs[0].links ?? []) {
+ const link = graph.links[linkId]
+ linksToDisconnect.push(link)
+ }
+ linksToDisconnect.pop()
+ for (const link of linksToDisconnect) {
+ const node = graph.getNodeById(link.target_id)
+ node?.disconnectInput(link.target_slot)
+ }
+ }
+ }
+
+ // Find root input
+ let currentNode: RerouteNode | null = this
+ let updateNodes: RerouteNode[] = []
+ let inputType = null
+ let inputNode = null
+ while (currentNode) {
+ updateNodes.unshift(currentNode)
+ const linkId = currentNode.inputs[0].link
+ if (linkId !== null) {
+ const link = graph.links[linkId]
+ if (!link) return
+ const node = graph.getNodeById(link.origin_id)
+ if (!node) return
+ if (node instanceof RerouteNode) {
+ if (node === this) {
+ // We've found a circle
+ currentNode.disconnectInput(link.target_slot)
+ currentNode = null
+ } else {
+ // Move the previous node
+ currentNode = node
+ }
+ } else {
+ // We've found the end
+ inputNode = currentNode
+ inputType = node.outputs[link.origin_slot]?.type ?? null
+ break
+ }
+ } else {
+ // This path has no input node
+ currentNode = null
+ break
+ }
+ }
+
+ // Find all outputs
+ const nodes: RerouteNode[] = [this]
+ let outputType = null
+ while (nodes.length) {
+ currentNode = nodes.pop()!
+ const outputs = currentNode.outputs?.[0]?.links ?? []
+ for (const linkId of outputs) {
+ const link = graph.links[linkId]
+
+ // When disconnecting sometimes the link is still registered
+ if (!link) continue
+
+ const node = graph.getNodeById(link.target_id)
+ if (!node) continue
+ if (node instanceof RerouteNode) {
+ // Follow reroute nodes
+ nodes.push(node)
+ updateNodes.push(node)
+ } else {
+ // We've found an output
+ const nodeInput = node.inputs[link.target_slot]
+ const nodeOutType = nodeInput.type
+ const keep =
+ !inputType ||
+ !nodeOutType ||
+ LiteGraph.isValidConnection(inputType, nodeOutType)
+ if (!keep) {
+ // The output doesnt match our input so disconnect it
+ node.disconnectInput(link.target_slot)
+ continue
+ }
+ node.onConnectionsChange?.(
+ LiteGraph.INPUT,
+ link.target_slot,
+ keep,
+ link,
+ nodeInput
+ )
+ outputType = node.inputs[link.target_slot].type
+ }
+ }
+ }
+
+ const displayType = inputType || outputType || '*'
+ const color = LGraphCanvas.link_type_colors[displayType]
+
+ let widgetConfig
+ let widgetType
+ // Update the types of each node
+ for (const node of updateNodes) {
+ // If we dont have an input type we are always wildcard but we'll show the output type
+ // This lets you change the output link to a different type and all nodes will update
+ node.outputs[0].type = inputType || '*'
+ node.__outputType = displayType
+ node.outputs[0].name = node.properties.showOutputText
+ ? `${displayType}`
+ : ''
+ node.setSize(node.computeSize())
+
+ for (const l of node.outputs[0].links || []) {
+ const link = graph.links[l]
+ if (!link) continue
+ link.color = color
+
+ if (app.configuringGraph) continue
+ const targetNode = graph.getNodeById(link.target_id)
+ if (!targetNode) continue
+ const targetInput = targetNode.inputs?.[link.target_slot]
+ if (targetInput?.widget) {
+ const config = getWidgetConfig(targetInput)
+ if (!widgetConfig) {
+ widgetConfig = config[1] ?? {}
+ widgetType = config[0]
+ }
+
+ const merged = mergeIfValid(targetInput, [
+ config[0],
+ widgetConfig
+ ])
+ if (merged.customConfig) {
+ widgetConfig = merged.customConfig
+ }
+ }
+ }
+ }
+
+ for (const node of updateNodes) {
+ if (widgetConfig && outputType) {
+ node.inputs[0].widget = { name: 'value' }
+ setWidgetConfig(node.inputs[0], [
+ widgetType ?? `${displayType}`,
+ widgetConfig
+ ])
+ } else {
+ setWidgetConfig(node.inputs[0], undefined)
+ }
+ }
+
+ if (inputNode?.inputs?.[0]?.link) {
+ const link = graph.links[inputNode.inputs[0].link]
+ if (link) {
+ link.color = color
+ }
+ }
+ }
+
+ override getExtraMenuOptions(
+ _: unknown,
+ options: (IContextMenuValue | null)[]
+ ): IContextMenuValue[] {
+ options.unshift(
+ {
+ content:
+ (this.properties.showOutputText ? 'Hide' : 'Show') + ' Type',
+ callback: () => {
+ this.properties.showOutputText = !this.properties.showOutputText
+ if (this.properties.showOutputText) {
+ this.outputs[0].name = `${this.__outputType || this.outputs[0].type}`
+ } else {
+ this.outputs[0].name = ''
+ }
+ this.setSize(this.computeSize())
+ app.canvas.setDirty(true, true)
+ }
+ },
+ {
+ content:
+ (RerouteNode.defaultVisibility ? 'Hide' : 'Show') +
+ ' Type By Default',
+ callback: () => {
+ RerouteNode.setDefaultTextVisibility(
+ !RerouteNode.defaultVisibility
+ )
+ }
+ }
+ )
+ return []
+ }
+ override computeSize(): [number, number] {
+ return [
+ this.properties.showOutputText && this.outputs && this.outputs.length
+ ? Math.max(
+ 75,
+ LiteGraph.NODE_TEXT_SIZE * this.outputs[0].name.length * 0.6 +
+ 40
+ )
+ : 75,
+ 26
+ ]
+ }
+
+ static setDefaultTextVisibility(visible: boolean) {
+ RerouteNode.defaultVisibility = visible
+ if (visible) {
+ localStorage['Comfy.RerouteNode.DefaultVisibility'] = 'true'
+ } else {
+ delete localStorage['Comfy.RerouteNode.DefaultVisibility']
+ }
+ }
+ }
+
+ // Load default visibility
+ RerouteNode.setDefaultTextVisibility(
+ !!localStorage['Comfy.RerouteNode.DefaultVisibility']
+ )
+
+ LiteGraph.registerNodeType(
+ 'Reroute',
+ Object.assign(RerouteNode, {
+ title_mode: LiteGraph.NO_TITLE,
+ title: 'Reroute',
+ collapsable: false
+ })
+ )
+
+ RerouteNode.category = 'utils'
+ }
+})
diff --git a/docs/hel-892/serialization-evidence/src__extensions__core__uploadImage.ts b/docs/hel-892/serialization-evidence/src__extensions__core__uploadImage.ts
new file mode 100644
index 00000000..4cb910da
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__extensions__core__uploadImage.ts
@@ -0,0 +1,53 @@
+import {
+ type ComfyNodeDef,
+ type InputSpec,
+ isComboInputSpecV1
+} from '@/schemas/nodeDefSchema'
+
+import { app } from '../../scripts/app'
+
+// Adds an upload button to the nodes
+
+const isMediaUploadComboInput = (inputSpec: InputSpec) => {
+ const [inputName, inputOptions] = inputSpec
+ if (!inputOptions) return false
+
+ const isUploadInput =
+ inputOptions['image_upload'] === true ||
+ inputOptions['video_upload'] === true ||
+ inputOptions['animated_image_upload'] === true
+
+ return (
+ isUploadInput && (isComboInputSpecV1(inputSpec) || inputName === 'COMBO')
+ )
+}
+
+const createUploadInput = (
+ imageInputName: string,
+ imageInputOptions: InputSpec
+): InputSpec => [
+ 'IMAGEUPLOAD',
+ {
+ ...imageInputOptions[1],
+ imageInputName
+ }
+]
+
+app.registerExtension({
+ name: 'Comfy.UploadImage',
+ beforeRegisterNodeDef(_nodeType, nodeData: ComfyNodeDef) {
+ const { input } = nodeData ?? {}
+ const { required } = input ?? {}
+ if (!required) return
+
+ const found = Object.entries(required).find(([_, input]) =>
+ isMediaUploadComboInput(input)
+ )
+
+ // If media combo input found, attach upload input
+ if (found) {
+ const [inputName, inputSpec] = found
+ required.upload = createUploadInput(inputName, inputSpec)
+ }
+ }
+})
diff --git a/docs/hel-892/serialization-evidence/src__lib__litegraph__src__LGraphNode.ts b/docs/hel-892/serialization-evidence/src__lib__litegraph__src__LGraphNode.ts
new file mode 100644
index 00000000..0ca41a73
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__lib__litegraph__src__LGraphNode.ts
@@ -0,0 +1,4198 @@
+import { LGraphNodeProperties } from '@/lib/litegraph/src/LGraphNodeProperties'
+import {
+ calculateInputSlotPos,
+ calculateInputSlotPosFromSlot,
+ calculateOutputSlotPos,
+ getSlotPosition
+} from '@/renderer/core/canvas/litegraph/slotCalculations'
+import type { SlotPositionContext } from '@/renderer/core/canvas/litegraph/slotCalculations'
+import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
+import { LayoutSource } from '@/renderer/core/layout/types'
+import { adjustColor } from '@/utils/colorUtil'
+import type { ColorAdjustOptions } from '@/utils/colorUtil'
+import { commonType, toClass } from '@/lib/litegraph/src/utils/type'
+
+import { SUBGRAPH_OUTPUT_ID } from '@/lib/litegraph/src/constants'
+import type { DragAndScale } from './DragAndScale'
+import type { LGraph } from './LGraph'
+import { BadgePosition, LGraphBadge } from './LGraphBadge'
+import { LGraphButton } from './LGraphButton'
+import type { LGraphButtonOptions } from './LGraphButton'
+import { LGraphCanvas } from './LGraphCanvas'
+import { LLink } from './LLink'
+import type { Reroute, RerouteId } from './Reroute'
+import { getNodeInputOnPos, getNodeOutputOnPos } from './canvas/measureSlots'
+import type { IDrawBoundingOptions } from './draw'
+import { NullGraphError } from './infrastructure/NullGraphError'
+import type { ReadOnlyRectangle } from './infrastructure/Rectangle'
+import { Rectangle } from './infrastructure/Rectangle'
+import type {
+ ColorOption,
+ CompassCorners,
+ DefaultConnectionColors,
+ Dictionary,
+ IColorable,
+ IContextMenuValue,
+ IFoundSlot,
+ INodeFlags,
+ INodeInputSlot,
+ INodeOutputSlot,
+ INodeSlot,
+ INodeSlotContextItem,
+ IPinnable,
+ ISlotType,
+ Point,
+ Positionable,
+ ReadOnlyRect,
+ Rect,
+ Size
+} from './interfaces'
+import { LiteGraph, Subgraph } from './litegraph'
+import type { LGraphNodeConstructor, SubgraphNode } from './litegraph'
+import {
+ createBounds,
+ isInRect,
+ isInRectangle,
+ isPointInRect,
+ snapPoint
+} from './measure'
+import { NodeInputSlot } from './node/NodeInputSlot'
+import { NodeOutputSlot } from './node/NodeOutputSlot'
+import {
+ inputAsSerialisable,
+ isINodeInputSlot,
+ isWidgetInputSlot,
+ outputAsSerialisable
+} from './node/slotUtils'
+import type { SubgraphInputNode } from './subgraph/SubgraphInputNode'
+import type { SubgraphOutputNode } from './subgraph/SubgraphOutputNode'
+import type { NodeLike } from './types/NodeLike'
+import type { CanvasPointerEvent } from './types/events'
+import {
+ LGraphEventMode,
+ NodeSlotType,
+ RenderShape,
+ TitleMode
+} from './types/globalEnums'
+import type { ISerialisedNode, SubgraphIO } from './types/serialisation'
+import type {
+ IBaseWidget,
+ IWidgetOptions,
+ TWidgetType,
+ TWidgetValue
+} from './types/widgets'
+import { findFreeSlotOfType } from './utils/collections'
+import { warnDeprecated } from './utils/feedback'
+import { distributeSpace } from './utils/spaceDistribution'
+import { truncateText } from './utils/textUtils'
+import { BaseWidget } from './widgets/BaseWidget'
+import { toConcreteWidget } from './widgets/widgetMap'
+import type { WidgetTypeMap } from './widgets/widgetMap'
+
+// #region Types
+
+export type NodeId = number | string
+
+export type NodeProperty = string | number | boolean | object
+
+interface INodePropertyInfo {
+ name: string
+ type?: string
+ default_value: NodeProperty | undefined
+}
+
+interface IMouseOverData {
+ inputId?: number
+ outputId?: number
+ overWidget?: IBaseWidget
+}
+
+interface ConnectByTypeOptions {
+ /** @deprecated Events */
+ createEventInCase?: boolean
+ /** Allow our wildcard slot to connect to typed slots on remote node. Default: true */
+ wildcardToTyped?: boolean
+ /** Allow our typed slot to connect to wildcard slots on remote node. Default: true */
+ typedToWildcard?: boolean
+ /** The {@link Reroute.id} that the connection is being dragged from. */
+ afterRerouteId?: RerouteId
+}
+
+/** Internal type used for type safety when implementing generic checks for inputs & outputs */
+interface IGenericLinkOrLinks {
+ links?: INodeOutputSlot['links']
+ link?: INodeInputSlot['link']
+}
+
+interface FindFreeSlotOptions {
+ /** Slots matching these types will be ignored. Default: [] */
+ typesNotAccepted?: ISlotType[]
+ /** If true, the slot itself is returned instead of the index. Default: false */
+ returnObj?: boolean
+}
+
+interface DrawSlotsOptions {
+ fromSlot?: INodeInputSlot | INodeOutputSlot
+ colorContext: DefaultConnectionColors
+ editorAlpha: number
+ lowQuality: boolean
+}
+
+interface DrawWidgetsOptions {
+ lowQuality?: boolean
+ editorAlpha?: number
+}
+
+interface DrawTitleOptions {
+ scale: number
+ title_height?: number
+ low_quality?: boolean
+}
+
+interface DrawTitleTextOptions extends DrawTitleOptions {
+ default_title_color: string
+}
+
+export interface DrawTitleBoxOptions extends DrawTitleOptions {
+ box_size?: number
+}
+
+/*
+title: string
+pos: [x,y]
+size: [x,y]
+
+input|output: every connection
+ + { name:string, type:string, pos: [x,y]=Optional, direction: "input"|"output", links: Array });
+
+general properties:
+ + clip_area: if you render outside the node, it will be clipped
+ + unsafe_execution: not allowed for safe execution
+ + skip_repeated_outputs: when adding new outputs, it won't show if there is one already connected
+ + resizable: if set to false it won't be resizable with the mouse
+ + widgets_start_y: widgets start at y distance from the top of the node
+
+flags object:
+ + collapsed: if it is collapsed
+
+supported callbacks:
+ + onAdded: when added to graph (warning: this is called BEFORE the node is configured when loading)
+ + onRemoved: when removed from graph
+ + onStart: when the graph starts playing
+ + onStop: when the graph stops playing
+ + onDrawForeground: render the inside widgets inside the node
+ + onDrawBackground: render the background area inside the node (only in edit mode)
+ + onMouseDown
+ + onMouseMove
+ + onMouseUp
+ + onMouseEnter
+ + onMouseLeave
+ + onExecute: execute the node
+ + onPropertyChanged: when a property is changed in the panel (return true to skip default behaviour)
+ + onGetInputs: returns an array of possible inputs
+ + onGetOutputs: returns an array of possible outputs
+ + onBounding: in case this node has a bigger bounding than the node itself (the callback receives the bounding as [x,y,w,h])
+ + onDblClick: double clicked in the node
+ + onNodeTitleDblClick: double clicked in the node title
+ + onInputDblClick: input slot double clicked (can be used to automatically create a node connected)
+ + onOutputDblClick: output slot double clicked (can be used to automatically create a node connected)
+ + onConfigure: called after the node has been configured
+ + onSerialize: to add extra info when serializing (the callback receives the object that should be filled with the data)
+ + onSelected
+ + onDeselected
+ + onDropItem : DOM item dropped over the node
+ + onDropFile : file dropped over the node
+ + onConnectInput : if returns false the incoming connection will be canceled
+ + onConnectionsChange : a connection changed (new one or removed) (NodeSlotType.INPUT or NodeSlotType.OUTPUT, slot, true if connected, link_info, input_info )
+ + onAction: action slot triggered
+ + getExtraMenuOptions: to add option to context menu
+*/
+
+export interface LGraphNode {
+ constructor: LGraphNodeConstructor
+}
+
+// #endregion Types
+
+/**
+ * Base class for all nodes
+ * @param title a name for the node
+ * @param type a type for the node
+ */
+
+export class LGraphNode
+ implements NodeLike, Positionable, IPinnable, IColorable
+{
+ // Static properties used by dynamic child classes
+ static title?: string
+ static MAX_CONSOLE?: number
+ static type?: string
+ static category?: string
+ static description?: string
+ static filter?: string
+ static skip_list?: boolean
+
+ static resizeHandleSize = 15
+ static resizeEdgeSize = 5
+
+ /** Default setting for {@link LGraphNode.connectInputToOutput}. @see {@link INodeFlags.keepAllLinksOnBypass} */
+ static keepAllLinksOnBypass: boolean = false
+
+ /** The title text of the node. */
+ title: string
+ /**
+ * The font style used to render the node's title text.
+ */
+ get titleFontStyle(): string {
+ return `${LiteGraph.NODE_TEXT_SIZE}px ${LiteGraph.NODE_FONT}`
+ }
+
+ get innerFontStyle(): string {
+ return `normal ${LiteGraph.NODE_SUBTEXT_SIZE}px ${LiteGraph.NODE_FONT}`
+ }
+
+ get displayType(): string {
+ return this.type
+ }
+
+ graph: LGraph | Subgraph | null = null
+ id: NodeId
+ type: string = ''
+ inputs: INodeInputSlot[] = []
+ outputs: INodeOutputSlot[] = []
+
+ #concreteInputs: NodeInputSlot[] = []
+ #concreteOutputs: NodeOutputSlot[] = []
+
+ properties: Dictionary = {}
+ properties_info: INodePropertyInfo[] = []
+ flags: INodeFlags = {}
+ widgets?: IBaseWidget[]
+
+ /** Property manager for this node */
+ changeTracker: LGraphNodeProperties
+
+ /**
+ * The amount of space available for widgets to grow into.
+ * @see {@link layoutWidgets}
+ */
+ freeWidgetSpace?: number
+
+ locked?: boolean
+
+ /** Execution order, automatically computed during run @see {@link LGraph.computeExecutionOrder} */
+ order: number = 0
+ mode: LGraphEventMode = LGraphEventMode.ALWAYS
+ last_serialization?: ISerialisedNode
+ serialize_widgets?: boolean
+ /**
+ * The overridden fg color used to render the node.
+ * @see {@link renderingColor}
+ */
+ color?: string
+ /**
+ * The overridden bg color used to render the node.
+ * @see {@link renderingBgColor}
+ */
+ bgcolor?: string
+ /**
+ * The overridden box color used to render the node.
+ * @see {@link renderingBoxColor}
+ */
+ boxcolor?: string
+
+ /** The fg color used to render the node. */
+ get renderingColor(): string {
+ const baseColor =
+ this.color || this.constructor.color || LiteGraph.NODE_DEFAULT_COLOR
+ return adjustColor(baseColor, { lightness: LiteGraph.nodeLightness })
+ }
+
+ /** The bg color used to render the node. */
+ get renderingBgColor(): string {
+ const baseBgColor =
+ this.bgcolor || this.constructor.bgcolor || LiteGraph.NODE_DEFAULT_BGCOLOR
+ const adjustments: ColorAdjustOptions = {
+ opacity: LiteGraph.nodeOpacity,
+ lightness: LiteGraph.nodeLightness
+ }
+
+ return adjustColor(
+ this.mode === LGraphEventMode.BYPASS
+ ? LiteGraph.NODE_DEFAULT_BYPASS_COLOR
+ : baseBgColor,
+ adjustments
+ )
+ }
+
+ /** The box color used to render the node. */
+ get renderingBoxColor(): string {
+ if (this.boxcolor) return this.boxcolor
+
+ if (LiteGraph.node_box_coloured_when_on) {
+ if (this.action_triggered) return '#FFF'
+ if (this.execute_triggered) return '#AAA'
+ }
+
+ if (LiteGraph.node_box_coloured_by_mode) {
+ const modeColour =
+ LiteGraph.NODE_MODES_COLORS[this.mode ?? LGraphEventMode.ALWAYS]
+ if (modeColour) return modeColour
+ }
+ return LiteGraph.NODE_DEFAULT_BOXCOLOR
+ }
+
+ /** @inheritdoc {@link IColorable.setColorOption} */
+ setColorOption(colorOption: ColorOption | null): void {
+ if (colorOption == null) {
+ this.color = undefined
+ this.bgcolor = undefined
+ } else {
+ this.color = colorOption.color
+ this.bgcolor = colorOption.bgcolor
+ }
+ }
+
+ /** @inheritdoc {@link IColorable.getColorOption} */
+ getColorOption(): ColorOption | null {
+ return (
+ Object.values(LGraphCanvas.node_colors).find(
+ (colorOption) =>
+ colorOption.color === this.color &&
+ colorOption.bgcolor === this.bgcolor
+ ) ?? null
+ )
+ }
+
+ /**
+ * The stroke styles that should be applied to the node.
+ */
+ strokeStyles: Record<
+ string,
+ (this: LGraphNode) => IDrawBoundingOptions | undefined
+ >
+
+ /**
+ * The progress of node execution. Used to render a progress bar. Value between 0 and 1.
+ */
+ progress?: number
+
+ exec_version?: number
+ action_call?: string
+ execute_triggered?: number
+ action_triggered?: number
+ widgets_up?: boolean
+ widgets_start_y?: number
+ lostFocusAt?: number
+ gotFocusAt?: number
+ badges: (LGraphBadge | (() => LGraphBadge))[] = []
+ title_buttons: LGraphButton[] = []
+ badgePosition: BadgePosition = BadgePosition.TopLeft
+ onOutputRemoved?(this: LGraphNode, slot: number): void
+ onInputRemoved?(this: LGraphNode, slot: number, input: INodeInputSlot): void
+ /**
+ * The width of the node when collapsed.
+ * Updated by {@link LGraphCanvas.drawNode}
+ */
+ _collapsed_width?: number
+ /**
+ * Called once at the start of every frame. Caller may change the values in {@link out}, which will be reflected in {@link boundingRect}.
+ * WARNING: Making changes to boundingRect via onBounding is poorly supported, and will likely result in strange behaviour.
+ */
+ onBounding?(this: LGraphNode, out: Rect): void
+ console?: string[]
+ _level?: number
+ _shape?: RenderShape
+ mouseOver?: IMouseOverData
+ redraw_on_mouse?: boolean
+ resizable?: boolean
+ clonable?: boolean
+ _relative_id?: number
+ clip_area?: boolean
+ ignore_remove?: boolean
+ has_errors?: boolean
+ removable?: boolean
+ block_delete?: boolean
+ selected?: boolean
+ showAdvanced?: boolean
+
+ declare comfyDynamic?: Record
+ declare comfyClass?: string
+ declare isVirtualNode?: boolean
+ applyToGraph?(extraLinks?: LLink[]): void
+
+ isSubgraphNode(): this is SubgraphNode {
+ return false
+ }
+
+ /** @inheritdoc {@link renderArea} */
+ #renderArea = new Rectangle()
+ /**
+ * Rect describing the node area, including shadows and any protrusions.
+ * Determines if the node is visible. Calculated once at the start of every frame.
+ */
+ get renderArea(): ReadOnlyRect {
+ return this.#renderArea
+ }
+
+ /** @inheritdoc {@link boundingRect} */
+ #boundingRect: Rectangle = new Rectangle()
+ /**
+ * Cached node position & area as `x, y, width, height`. Includes changes made by {@link onBounding}, if present.
+ *
+ * Determines the node hitbox and other rendering effects. Calculated once at the start of every frame.
+ */
+ get boundingRect(): ReadOnlyRectangle {
+ return this.#boundingRect
+ }
+
+ /** The offset from {@link pos} to the top-left of {@link boundingRect}. */
+ get boundingOffset(): Readonly {
+ const {
+ pos: [posX, posY],
+ boundingRect: [bX, bY]
+ } = this
+ return [posX - bX, posY - bY]
+ }
+
+ /** {@link pos} and {@link size} values are backed by this {@link Rectangle}. */
+ _posSize = new Rectangle()
+ _pos: Point = this._posSize.pos
+ _size: Size = this._posSize.size
+
+ public get pos() {
+ return this._pos
+ }
+
+ /** Node position does not necessarily correlate to the top-left corner. */
+ public set pos(value) {
+ if (!value || value.length < 2) return
+
+ this._pos[0] = value[0]
+ this._pos[1] = value[1]
+ }
+
+ public get size() {
+ return this._size
+ }
+
+ public set size(value) {
+ if (!value || value.length < 2) return
+
+ this._size[0] = value[0]
+ this._size[1] = value[1]
+ }
+
+ /**
+ * The size of the node used for rendering.
+ */
+ get renderingSize(): Size {
+ return this.flags.collapsed ? [this._collapsed_width ?? 0, 0] : this._size
+ }
+
+ get shape(): RenderShape | undefined {
+ return this._shape
+ }
+
+ set shape(v: RenderShape | 'default' | 'box' | 'round' | 'circle' | 'card') {
+ const oldValue = this._shape
+ switch (v) {
+ case 'default':
+ this._shape = undefined
+ break
+ case 'box':
+ this._shape = RenderShape.BOX
+ break
+ case 'round':
+ this._shape = RenderShape.ROUND
+ break
+ case 'circle':
+ this._shape = RenderShape.CIRCLE
+ break
+ case 'card':
+ this._shape = RenderShape.CARD
+ break
+ default:
+ this._shape = v
+ }
+ if (oldValue !== this._shape) {
+ this.graph?.trigger('node:property:changed', {
+ nodeId: this.id,
+ property: 'shape',
+ oldValue,
+ newValue: this._shape
+ })
+ }
+ }
+
+ /**
+ * The shape of the node used for rendering. @see {@link RenderShape}
+ */
+ get renderingShape(): RenderShape {
+ return this._shape || this.constructor.shape || LiteGraph.NODE_DEFAULT_SHAPE
+ }
+
+ public get is_selected(): boolean | undefined {
+ return this.selected
+ }
+
+ public set is_selected(value: boolean) {
+ this.selected = value
+ }
+
+ public get title_mode(): TitleMode {
+ return this.constructor.title_mode ?? TitleMode.NORMAL_TITLE
+ }
+
+ onConnectInput?(
+ this: LGraphNode,
+ target_slot: number,
+ type: unknown,
+ output: INodeOutputSlot | SubgraphIO,
+ node: LGraphNode | SubgraphInputNode,
+ slot: number
+ ): boolean
+ onConnectOutput?(
+ this: LGraphNode,
+ slot: number,
+ type: unknown,
+ input: INodeInputSlot | SubgraphIO,
+ target_node: number | LGraphNode | SubgraphOutputNode,
+ target_slot: number
+ ): boolean
+ onResize?(this: LGraphNode, size: Size): void
+ onPropertyChanged?(
+ this: LGraphNode,
+ name: string,
+ value: unknown,
+ prev_value?: unknown
+ ): boolean
+ /** Called for each connection that is created, updated, or removed. This includes "restored" connections when deserialising. */
+ onConnectionsChange?(
+ this: LGraphNode,
+ type: ISlotType,
+ index: number,
+ isConnected: boolean,
+ link_info: LLink | null | undefined,
+ inputOrOutput: INodeInputSlot | INodeOutputSlot | SubgraphIO
+ ): void
+ onInputAdded?(this: LGraphNode, input: INodeInputSlot): void
+ onOutputAdded?(this: LGraphNode, output: INodeOutputSlot): void
+ onConfigure?(this: LGraphNode, serialisedNode: ISerialisedNode): void
+ onSerialize?(this: LGraphNode, serialised: ISerialisedNode): void
+ onExecute?(
+ this: LGraphNode,
+ param?: unknown,
+ options?: { action_call?: string }
+ ): void
+ onAction?(
+ this: LGraphNode,
+ action: string,
+ param: unknown,
+ options: { action_call?: string }
+ ): void
+ onDrawBackground?(this: LGraphNode, ctx: CanvasRenderingContext2D): void
+ onNodeCreated?(this: LGraphNode): void
+ /**
+ * Callback invoked by {@link connect} to override the target slot index.
+ * Its return value overrides the target index selection.
+ * @param target_slot The current input slot index
+ * @param requested_slot The originally requested slot index - could be negative, or if using (deprecated) name search, a string
+ * @returns {number | null} If a number is returned, the connection will be made to that input index.
+ * If an invalid index or non-number (false, null, NaN etc) is returned, the connection will be cancelled.
+ */
+ onBeforeConnectInput?(
+ this: LGraphNode,
+ target_slot: number,
+ requested_slot?: number | string
+ ): number | false | null
+ onShowCustomPanelInfo?(this: LGraphNode, panel: any): void
+ onAddPropertyToPanel?(this: LGraphNode, pName: string, panel: any): boolean
+ onWidgetChanged?(
+ this: LGraphNode,
+ name: string,
+ value: unknown,
+ old_value: unknown,
+ w: IBaseWidget
+ ): void
+ onDeselected?(this: LGraphNode): void
+ onKeyUp?(this: LGraphNode, e: KeyboardEvent): void
+ onKeyDown?(this: LGraphNode, e: KeyboardEvent): void
+ onSelected?(this: LGraphNode): void
+ getExtraMenuOptions?(
+ this: LGraphNode,
+ canvas: LGraphCanvas,
+ options: (IContextMenuValue | null)[]
+ ): (IContextMenuValue | null)[]
+ getMenuOptions?(this: LGraphNode, canvas: LGraphCanvas): IContextMenuValue[]
+ onAdded?(this: LGraphNode, graph: LGraph): void
+ onDrawCollapsed?(
+ this: LGraphNode,
+ ctx: CanvasRenderingContext2D,
+ cavnas: LGraphCanvas
+ ): boolean
+ onDrawForeground?(
+ this: LGraphNode,
+ ctx: CanvasRenderingContext2D,
+ canvas: LGraphCanvas,
+ canvasElement: HTMLCanvasElement
+ ): void
+ onMouseLeave?(this: LGraphNode, e: CanvasPointerEvent): void
+ /**
+ * Override the default slot menu options.
+ */
+ getSlotMenuOptions?(this: LGraphNode, slot: IFoundSlot): IContextMenuValue[]
+ /**
+ * Add extra menu options to the slot context menu.
+ */
+ getExtraSlotMenuOptions?(
+ this: LGraphNode,
+ slot: IFoundSlot
+ ): IContextMenuValue[]
+
+ // FIXME: Re-typing
+ onDropItem?(this: LGraphNode, event: Event): boolean
+ onDropData?(
+ this: LGraphNode,
+ data: string | ArrayBuffer,
+ filename: string,
+ file: File
+ ): void
+ onDropFile?(this: LGraphNode, file: File): void
+ onInputClick?(this: LGraphNode, index: number, e: CanvasPointerEvent): void
+ onInputDblClick?(this: LGraphNode, index: number, e: CanvasPointerEvent): void
+ onOutputClick?(this: LGraphNode, index: number, e: CanvasPointerEvent): void
+ onOutputDblClick?(
+ this: LGraphNode,
+ index: number,
+ e: CanvasPointerEvent
+ ): void
+ // TODO: Return type
+ onGetPropertyInfo?(this: LGraphNode, property: string): any
+ onNodeOutputAdd?(this: LGraphNode, value: unknown): void
+ onNodeInputAdd?(this: LGraphNode, value: unknown): void
+ onMenuNodeInputs?(
+ this: LGraphNode,
+ entries: (IContextMenuValue | null)[]
+ ): (IContextMenuValue | null)[]
+ onMenuNodeOutputs?(
+ this: LGraphNode,
+ entries: (IContextMenuValue | null)[]
+ ): (IContextMenuValue | null)[]
+ onMouseUp?(
+ this: LGraphNode,
+ e: CanvasPointerEvent,
+ pos: Point,
+ canvas: LGraphCanvas
+ ): void
+ onMouseEnter?(this: LGraphNode, e: CanvasPointerEvent): void
+ /** Blocks drag if return value is truthy. @param pos Offset from {@link LGraphNode.pos}. */
+ onMouseDown?(
+ this: LGraphNode,
+ e: CanvasPointerEvent,
+ pos: Point,
+ canvas: LGraphCanvas
+ ): boolean
+ /** @param pos Offset from {@link LGraphNode.pos}. */
+ onDblClick?(
+ this: LGraphNode,
+ e: CanvasPointerEvent,
+ pos: Point,
+ canvas: LGraphCanvas
+ ): void
+ /** @param pos Offset from {@link LGraphNode.pos}. */
+ onNodeTitleDblClick?(
+ this: LGraphNode,
+ e: CanvasPointerEvent,
+ pos: Point,
+ canvas: LGraphCanvas
+ ): void
+ onDrawTitle?(this: LGraphNode, ctx: CanvasRenderingContext2D): void
+ onDrawTitleText?(
+ this: LGraphNode,
+ ctx: CanvasRenderingContext2D,
+ title_height: number,
+ size: Size,
+ scale: number,
+ title_text_font: string,
+ selected?: boolean
+ ): void
+ onDrawTitleBox?(
+ this: LGraphNode,
+ ctx: CanvasRenderingContext2D,
+ title_height: number,
+ size: Size,
+ scale: number
+ ): void
+ onDrawTitleBar?(
+ this: LGraphNode,
+ ctx: CanvasRenderingContext2D,
+ title_height: number,
+ size: Size,
+ scale: number,
+ fgcolor: string
+ ): void
+ onRemoved?(this: LGraphNode): void
+ onMouseMove?(
+ this: LGraphNode,
+ e: CanvasPointerEvent,
+ pos: Point,
+ arg2: LGraphCanvas
+ ): void
+ onPropertyChange?(this: LGraphNode): void
+ updateOutputData?(this: LGraphNode, origin_slot: number): void
+
+ #getErrorStrokeStyle(this: LGraphNode): IDrawBoundingOptions | undefined {
+ if (this.has_errors) {
+ return {
+ padding: 12,
+ lineWidth: 10,
+ color: LiteGraph.NODE_ERROR_COLOUR
+ }
+ }
+ }
+
+ #getSelectedStrokeStyle(this: LGraphNode): IDrawBoundingOptions | undefined {
+ if (this.selected) {
+ return {
+ padding: this.has_errors ? 20 : undefined
+ }
+ }
+ }
+
+ constructor(title: string, type?: string) {
+ this.id = LiteGraph.use_uuids ? LiteGraph.uuidv4() : -1
+ this.title = title || 'Unnamed'
+ this.type = type ?? ''
+ this.size = [LiteGraph.NODE_WIDTH, 60]
+ this.pos = [10, 10]
+ this.strokeStyles = {
+ error: this.#getErrorStrokeStyle,
+ selected: this.#getSelectedStrokeStyle
+ }
+ // Initialize property manager with tracked properties
+ this.changeTracker = new LGraphNodeProperties(this)
+ }
+
+ /** Internal callback for subgraph nodes. Do not implement externally. */
+ _internalConfigureAfterSlots?(): void
+
+ /**
+ * configure a node from an object containing the serialized info
+ */
+ configure(info: ISerialisedNode): void {
+ if (this.graph) {
+ this.graph._version++
+ }
+ for (const j in info) {
+ if (j == 'properties') {
+ // i don't want to clone properties, I want to reuse the old container
+ for (const k in info.properties) {
+ this.properties[k] = info.properties[k]
+ this.onPropertyChanged?.(k, info.properties[k])
+ }
+ continue
+ }
+
+ // @ts-expect-error #594
+ if (info[j] == null) {
+ continue
+ // @ts-expect-error #594
+ } else if (typeof info[j] == 'object') {
+ // @ts-expect-error #594
+ if (this[j]?.configure) {
+ // @ts-expect-error #594
+ this[j]?.configure(info[j])
+ } else {
+ // @ts-expect-error #594
+ this[j] = LiteGraph.cloneObject(info[j], this[j])
+ }
+ } else {
+ // value
+ // @ts-expect-error #594
+ this[j] = info[j]
+ }
+ }
+
+ if (!info.title) {
+ this.title = this.constructor.title
+ }
+
+ this.inputs ??= []
+ this.inputs = this.inputs.map((input) =>
+ toClass(NodeInputSlot, input, this)
+ )
+ for (const [i, input] of this.inputs.entries()) {
+ const link =
+ this.graph && input.link != null
+ ? this.graph._links.get(input.link)
+ : null
+ this.onConnectionsChange?.(NodeSlotType.INPUT, i, true, link, input)
+ this.onInputAdded?.(input)
+ }
+
+ this.outputs ??= []
+ this.outputs = this.outputs.map((output) =>
+ toClass(NodeOutputSlot, output, this)
+ )
+ for (const [i, output] of this.outputs.entries()) {
+ if (!output.links) continue
+
+ for (const linkId of output.links) {
+ const link = this.graph ? this.graph._links.get(linkId) : null
+ this.onConnectionsChange?.(NodeSlotType.OUTPUT, i, true, link, output)
+ }
+ this.onOutputAdded?.(output)
+ }
+
+ // SubgraphNode callback.
+ this._internalConfigureAfterSlots?.()
+
+ if (this.widgets) {
+ for (const w of this.widgets) {
+ if (!w) continue
+
+ const input = this.inputs.find((i) => i.widget?.name === w.name)
+ if (input?.label) w.label = input.label
+
+ if (
+ w.options?.property &&
+ this.properties[w.options.property] != undefined
+ )
+ w.value = JSON.parse(
+ JSON.stringify(this.properties[w.options.property])
+ )
+ }
+
+ if (info.widgets_values) {
+ let i = 0
+ for (const widget of this.widgets ?? []) {
+ if (widget.serialize === false) continue
+ if (i >= info.widgets_values.length) break
+ widget.value = info.widgets_values[i++]
+ }
+ }
+ }
+
+ // Sync the state of this.resizable.
+ if (this.pinned) this.resizable = false
+
+ this.onConfigure?.(info)
+ }
+
+ /**
+ * serialize the content
+ */
+ serialize(): ISerialisedNode {
+ // create serialization object
+ const o: ISerialisedNode = {
+ id: this.id,
+ type: this.type,
+ pos: [this.pos[0], this.pos[1]],
+ size: [this.size[0], this.size[1]],
+ flags: LiteGraph.cloneObject(this.flags),
+ order: this.order,
+ mode: this.mode,
+ showAdvanced: this.showAdvanced
+ }
+
+ // special case for when there were errors
+ if (this.constructor === LGraphNode && this.last_serialization)
+ return { ...this.last_serialization, mode: o.mode, pos: o.pos }
+
+ if (this.inputs)
+ o.inputs = this.inputs.map((input) => inputAsSerialisable(input))
+ if (this.outputs)
+ // @ts-expect-error - Output serialization type mismatch
+ o.outputs = this.outputs.map((output) => outputAsSerialisable(output))
+
+ if (this.title && this.title != this.constructor.title) o.title = this.title
+
+ if (this.properties) o.properties = LiteGraph.cloneObject(this.properties)
+
+ const { widgets } = this
+ if (widgets && this.serialize_widgets) {
+ o.widgets_values = []
+ for (const [i, widget] of widgets.entries()) {
+ if (widget.serialize === false) continue
+ // @ts-expect-error #595 No-null
+ o.widgets_values[i] = widget ? widget.value : null
+ }
+ }
+
+ if (!o.type && this.constructor.type) o.type = this.constructor.type
+
+ if (this.color) o.color = this.color
+ if (this.bgcolor) o.bgcolor = this.bgcolor
+ if (this.boxcolor) o.boxcolor = this.boxcolor
+ if (this.shape) o.shape = this.shape
+
+ if (this.onSerialize?.(o))
+ console.warn(
+ "node onSerialize shouldn't return anything, data should be stored in the object pass in the first parameter"
+ )
+
+ return o
+ }
+
+ /* Creates a clone of this node */
+ clone(): LGraphNode | null {
+ if (this.type == null) return null
+ const node = LiteGraph.createNode(this.type)
+ if (!node) return null
+
+ // we clone it because serialize returns shared containers
+ const data = LiteGraph.cloneObject(this.serialize())
+ const { inputs, outputs } = data
+
+ // remove links
+ if (inputs) {
+ for (const input of inputs) {
+ input.link = null
+ }
+ }
+
+ if (outputs) {
+ for (const { links } of outputs) {
+ if (links) links.length = 0
+ }
+ }
+
+ // @ts-expect-error Exceptional case: id is removed so that the graph can assign a new one on add.
+ data.id = undefined
+
+ if (LiteGraph.use_uuids) data.id = LiteGraph.uuidv4()
+
+ node.configure(data)
+
+ return node
+ }
+
+ /**
+ * serialize and stringify
+ */
+ toString(): string {
+ return JSON.stringify(this.serialize())
+ }
+
+ /**
+ * get the title string
+ */
+ getTitle(): string {
+ return this.title || this.constructor.title
+ }
+
+ /**
+ * sets the value of a property
+ * @param name
+ * @param value
+ */
+ setProperty(name: string, value: TWidgetValue): void {
+ this.properties ||= {}
+ if (value === this.properties[name]) return
+
+ const prev_value = this.properties[name]
+ this.properties[name] = value
+ // abort change
+ if (this.onPropertyChanged?.(name, value, prev_value) === false)
+ this.properties[name] = prev_value
+
+ if (this.widgets) {
+ for (const w of this.widgets) {
+ if (!w) continue
+
+ if (w.options.property == name) {
+ w.value = value
+ break
+ }
+ }
+ }
+ }
+
+ /**
+ * sets the output data
+ * @param slot
+ * @param data
+ */
+ setOutputData(
+ slot: number,
+ data: number | string | boolean | { toToolTip?(): string }
+ ): void {
+ const { outputs } = this
+ if (!outputs) return
+
+ // this maybe slow and a niche case
+ if (slot == -1 || slot >= outputs.length) return
+
+ const output_info = outputs[slot]
+ if (!output_info) return
+
+ // store data in the output itself in case we want to debug
+ output_info._data = data
+
+ if (!this.graph) throw new NullGraphError()
+
+ // if there are connections, pass the data to the connections
+ const { links } = outputs[slot]
+ if (links) {
+ for (const id of links) {
+ const link = this.graph._links.get(id)
+ if (link) link.data = data
+ }
+ }
+ }
+
+ /**
+ * sets the output data type, useful when you want to be able to overwrite the data type
+ */
+ setOutputDataType(slot: number, type: ISlotType): void {
+ const { outputs } = this
+ if (!outputs || slot == -1 || slot >= outputs.length) return
+
+ const output_info = outputs[slot]
+ if (!output_info) return
+ // store data in the output itself in case we want to debug
+ output_info.type = type
+
+ if (!this.graph) throw new NullGraphError()
+
+ // if there are connections, pass the data to the connections
+ const { links } = outputs[slot]
+ if (links) {
+ for (const id of links) {
+ const link = this.graph._links.get(id)
+ if (link) link.type = type
+ }
+ }
+ }
+
+ /**
+ * Retrieves the input data (data traveling through the connection) from one slot
+ * @param slot
+ * @param force_update if set to true it will force the connected node of this slot to output data into this link
+ * @returns data or if it is not connected returns undefined
+ */
+ getInputData(slot: number, force_update?: boolean): unknown {
+ if (!this.inputs) return
+
+ if (slot >= this.inputs.length || this.inputs[slot].link == null) return
+ if (!this.graph) throw new NullGraphError()
+
+ const link_id = this.inputs[slot].link
+ const link = this.graph._links.get(link_id)
+ // bug: weird case but it happens sometimes
+ if (!link) return null
+
+ if (!force_update) return link.data
+
+ // special case: used to extract data from the incoming connection before the graph has been executed
+ const node = this.graph.getNodeById(link.origin_id)
+ if (!node) return link.data
+
+ if (node.updateOutputData) {
+ node.updateOutputData(link.origin_slot)
+ } else {
+ node.onExecute?.()
+ }
+
+ return link.data
+ }
+
+ /**
+ * Retrieves the input data type (in case this supports multiple input types)
+ * @param slot
+ * @returns datatype in string format
+ */
+ getInputDataType(slot: number): ISlotType | null {
+ if (!this.inputs) return null
+ if (slot >= this.inputs.length || this.inputs[slot].link == null)
+ return null
+ if (!this.graph) throw new NullGraphError()
+
+ const link_id = this.inputs[slot].link
+ const link = this.graph._links.get(link_id)
+ // bug: weird case but it happens sometimes
+ if (!link) return null
+
+ const node = this.graph.getNodeById(link.origin_id)
+ if (!node) return link.type
+
+ const output_info = node.outputs[link.origin_slot]
+ return output_info ? output_info.type : null
+ }
+
+ /**
+ * Retrieves the input data from one slot using its name instead of slot number
+ * @param slot_name
+ * @param force_update if set to true it will force the connected node of this slot to output data into this link
+ * @returns data or if it is not connected returns null
+ */
+ getInputDataByName(slot_name: string, force_update: boolean): unknown {
+ const slot = this.findInputSlot(slot_name)
+ return slot == -1 ? null : this.getInputData(slot, force_update)
+ }
+
+ /**
+ * tells you if there is a connection in one input slot
+ * @param slot The 0-based index of the input to check
+ * @returns `true` if the input slot has a link ID (does not perform validation)
+ */
+ isInputConnected(slot: number): boolean {
+ if (!this.inputs) return false
+ return slot < this.inputs.length && this.inputs[slot].link != null
+ }
+
+ /**
+ * tells you info about an input connection (which node, type, etc)
+ * @returns object or null { link: id, name: string, type: string or 0 }
+ */
+ getInputInfo(slot: number): INodeInputSlot | null {
+ return !this.inputs || !(slot < this.inputs.length)
+ ? null
+ : this.inputs[slot]
+ }
+
+ /**
+ * Returns the link info in the connection of an input slot
+ * @returns object or null
+ */
+ getInputLink(slot: number): LLink | null {
+ if (!this.inputs) return null
+
+ if (slot < this.inputs.length) {
+ if (!this.graph) throw new NullGraphError()
+
+ const input = this.inputs[slot]
+ if (input.link != null) {
+ return this.graph._links.get(input.link) ?? null
+ }
+ }
+ return null
+ }
+
+ /**
+ * returns the node connected in the input slot
+ * @returns node or null
+ */
+ getInputNode(slot: number): LGraphNode | null {
+ if (!this.inputs) return null
+ if (slot >= this.inputs.length) return null
+
+ const input = this.inputs[slot]
+ if (!input || input.link === null) return null
+ if (!this.graph) throw new NullGraphError()
+
+ const link_info = this.graph._links.get(input.link)
+ if (!link_info) return null
+
+ return this.graph.getNodeById(link_info.origin_id)
+ }
+
+ /**
+ * returns the value of an input with this name, otherwise checks if there is a property with that name
+ * @returns value
+ */
+ getInputOrProperty(name: string): unknown {
+ const { inputs } = this
+ if (!inputs?.length) {
+ return this.properties ? this.properties[name] : null
+ }
+ if (!this.graph) throw new NullGraphError()
+
+ for (const input of inputs) {
+ if (name == input.name && input.link != null) {
+ const link = this.graph._links.get(input.link)
+ if (link) return link.data
+ }
+ }
+ return this.properties[name]
+ }
+
+ /**
+ * tells you the last output data that went in that slot
+ * @returns object or null
+ */
+ getOutputData(slot: number): unknown {
+ if (!this.outputs) return null
+ if (slot >= this.outputs.length) return null
+
+ const info = this.outputs[slot]
+ return info._data
+ }
+
+ /**
+ * tells you info about an output connection (which node, type, etc)
+ * @returns object or null { name: string, type: string, links: [ ids of links in number ] }
+ */
+ getOutputInfo(slot: number): INodeOutputSlot | null {
+ return !this.outputs || !(slot < this.outputs.length)
+ ? null
+ : this.outputs[slot]
+ }
+
+ /**
+ * tells you if there is a connection in one output slot
+ */
+ isOutputConnected(slot: number): boolean {
+ if (!this.outputs) return false
+ return (
+ slot < this.outputs.length && Number(this.outputs[slot].links?.length) > 0
+ )
+ }
+
+ /**
+ * tells you if there is any connection in the output slots
+ */
+ isAnyOutputConnected(): boolean {
+ const { outputs } = this
+ if (!outputs) return false
+
+ for (const output of outputs) {
+ if (output.links?.length) return true
+ }
+ return false
+ }
+
+ /**
+ * retrieves all the nodes connected to this output slot
+ */
+ getOutputNodes(slot: number): LGraphNode[] | null {
+ const { outputs } = this
+ if (!outputs || outputs.length == 0) return null
+
+ if (slot >= outputs.length) return null
+
+ const { links } = outputs[slot]
+ if (!links || links.length == 0) return null
+ if (!this.graph) throw new NullGraphError()
+
+ const r: LGraphNode[] = []
+ for (const id of links) {
+ const link = this.graph._links.get(id)
+ if (link) {
+ const target_node = this.graph.getNodeById(link.target_id)
+ if (target_node) {
+ r.push(target_node)
+ }
+ }
+ }
+ return r
+ }
+
+ addOnTriggerInput(): number {
+ const trigS = this.findInputSlot('onTrigger')
+ if (trigS == -1) {
+ this.addInput('onTrigger', LiteGraph.EVENT, {
+ nameLocked: true
+ })
+ return this.findInputSlot('onTrigger')
+ }
+ return trigS
+ }
+
+ addOnExecutedOutput(): number {
+ const trigS = this.findOutputSlot('onExecuted')
+ if (trigS == -1) {
+ this.addOutput('onExecuted', LiteGraph.ACTION, {
+ nameLocked: true
+ })
+ return this.findOutputSlot('onExecuted')
+ }
+ return trigS
+ }
+
+ onAfterExecuteNode(param: unknown, options?: { action_call?: string }) {
+ const trigS = this.findOutputSlot('onExecuted')
+ if (trigS != -1) {
+ this.triggerSlot(trigS, param, null, options)
+ }
+ }
+
+ changeMode(modeTo: number): boolean {
+ switch (modeTo) {
+ case LGraphEventMode.ON_EVENT:
+ break
+
+ case LGraphEventMode.ON_TRIGGER:
+ this.addOnTriggerInput()
+ this.addOnExecutedOutput()
+ break
+
+ case LGraphEventMode.NEVER:
+ break
+
+ case LGraphEventMode.ALWAYS:
+ break
+
+ // @ts-expect-error Not impl.
+ case LiteGraph.ON_REQUEST:
+ break
+
+ default:
+ return false
+ break
+ }
+ this.mode = modeTo
+ return true
+ }
+
+ /**
+ * Triggers the node code execution, place a boolean/counter to mark the node as being executed
+ */
+ doExecute(param?: unknown, options?: { action_call?: string }): void {
+ options = options || {}
+ if (this.onExecute) {
+ // enable this to give the event an ID
+ options.action_call ||= `${this.id}_exec_${Math.floor(Math.random() * 9999)}`
+ if (!this.graph) throw new NullGraphError()
+
+ // @ts-expect-error Technically it works when id is a string. Array gets props.
+ this.graph.nodes_executing[this.id] = true
+ this.onExecute(param, options)
+ // @ts-expect-error deprecated
+ this.graph.nodes_executing[this.id] = false
+
+ // save execution/action ref
+ this.exec_version = this.graph.iteration
+ if (options?.action_call) {
+ this.action_call = options.action_call
+ // @ts-expect-error deprecated
+ this.graph.nodes_executedAction[this.id] = options.action_call
+ }
+ }
+ // the nFrames it will be used (-- each step), means "how old" is the event
+ this.execute_triggered = 2
+ this.onAfterExecuteNode?.(param, options)
+ }
+
+ /**
+ * Triggers an action, wrapped by logics to control execution flow
+ * @param action name
+ */
+ actionDo(
+ action: string,
+ param: unknown,
+ options: { action_call?: string }
+ ): void {
+ options = options || {}
+ if (this.onAction) {
+ // enable this to give the event an ID
+ options.action_call ||= `${this.id}_${action || 'action'}_${Math.floor(Math.random() * 9999)}`
+ if (!this.graph) throw new NullGraphError()
+
+ // @ts-expect-error deprecated
+ this.graph.nodes_actioning[this.id] = action || 'actioning'
+ this.onAction(action, param, options)
+ // @ts-expect-error deprecated
+ this.graph.nodes_actioning[this.id] = false
+
+ // save execution/action ref
+ if (options?.action_call) {
+ this.action_call = options.action_call
+ // @ts-expect-error deprecated
+ this.graph.nodes_executedAction[this.id] = options.action_call
+ }
+ }
+ // the nFrames it will be used (-- each step), means "how old" is the event
+ this.action_triggered = 2
+ this.onAfterExecuteNode?.(param, options)
+ }
+
+ /**
+ * Triggers an event in this node, this will trigger any output with the same name
+ * @param action name ( "on_play", ... ) if action is equivalent to false then the event is send to all
+ */
+ trigger(
+ action: string,
+ param: unknown,
+ options: { action_call?: string }
+ ): void {
+ const { outputs } = this
+ if (!outputs || !outputs.length) {
+ return
+ }
+
+ if (this.graph) this.graph._last_trigger_time = LiteGraph.getTime()
+
+ for (const [i, output] of outputs.entries()) {
+ if (
+ !output ||
+ output.type !== LiteGraph.EVENT ||
+ (action && output.name != action)
+ ) {
+ continue
+ }
+ this.triggerSlot(i, param, null, options)
+ }
+ }
+
+ /**
+ * Triggers a slot event in this node: cycle output slots and launch execute/action on connected nodes
+ * @param slot the index of the output slot
+ * @param link_id [optional] in case you want to trigger and specific output link in a slot
+ */
+ triggerSlot(
+ slot: number,
+ param: unknown,
+ link_id: number | null,
+ options?: { action_call?: string }
+ ): void {
+ options = options || {}
+ if (!this.outputs) return
+
+ if (slot == null) {
+ console.error('slot must be a number')
+ return
+ }
+
+ if (typeof slot !== 'number')
+ console.warn(
+ "slot must be a number, use node.trigger('name') if you want to use a string"
+ )
+
+ const output = this.outputs[slot]
+ if (!output) return
+
+ const links = output.links
+ if (!links || !links.length) return
+
+ if (!this.graph) throw new NullGraphError()
+ this.graph._last_trigger_time = LiteGraph.getTime()
+
+ // for every link attached here
+ for (const id of links) {
+ // to skip links
+ if (link_id != null && link_id != id) continue
+
+ const link_info = this.graph._links.get(id)
+ // not connected
+ if (!link_info) continue
+
+ link_info._last_time = LiteGraph.getTime()
+ const node = this.graph.getNodeById(link_info.target_id)
+ // node not found?
+ if (!node) continue
+
+ if (node.mode === LGraphEventMode.ON_TRIGGER) {
+ // generate unique trigger ID if not present
+ if (!options.action_call)
+ options.action_call = `${this.id}_trigg_${Math.floor(Math.random() * 9999)}`
+ // -- wrapping node.onExecute(param); --
+ node.doExecute?.(param, options)
+ } else if (node.onAction) {
+ // generate unique action ID if not present
+ if (!options.action_call)
+ options.action_call = `${this.id}_act_${Math.floor(Math.random() * 9999)}`
+ // pass the action name
+ const target_connection = node.inputs[link_info.target_slot]
+ node.actionDo(target_connection.name, param, options)
+ }
+ }
+ }
+
+ /**
+ * clears the trigger slot animation
+ * @param slot the index of the output slot
+ * @param link_id [optional] in case you want to trigger and specific output link in a slot
+ */
+ clearTriggeredSlot(slot: number, link_id: number): void {
+ if (!this.outputs) return
+
+ const output = this.outputs[slot]
+ if (!output) return
+
+ const links = output.links
+ if (!links || !links.length) return
+
+ if (!this.graph) throw new NullGraphError()
+
+ // for every link attached here
+ for (const id of links) {
+ // to skip links
+ if (link_id != null && link_id != id) continue
+
+ const link_info = this.graph._links.get(id)
+ // not connected
+ if (!link_info) continue
+
+ link_info._last_time = 0
+ }
+ }
+
+ /**
+ * changes node size and triggers callback
+ */
+ setSize(size: Size): void {
+ this.size = size
+ this.onResize?.(this.size)
+ }
+
+ /**
+ * Expands the node size to fit its content.
+ */
+ expandToFitContent(): void {
+ const newSize = this.computeSize()
+ this.setSize([
+ Math.max(this.size[0], newSize[0]),
+ Math.max(this.size[1], newSize[1])
+ ])
+ }
+
+ /**
+ * add a new property to this node
+ * @param type string defining the output type ("vec3","number",...)
+ * @param extra_info this can be used to have special properties of the property (like values, etc)
+ */
+ addProperty(
+ name: string,
+ default_value: NodeProperty | undefined,
+ type?: string,
+ extra_info?: Partial
+ ): INodePropertyInfo {
+ const o: INodePropertyInfo = { name, type, default_value }
+ if (extra_info) Object.assign(o, extra_info)
+
+ this.properties_info ||= []
+ this.properties_info.push(o)
+ this.properties ||= {}
+ this.properties[name] = default_value
+ return o
+ }
+
+ /**
+ * add a new output slot to use in this node
+ * @param type string defining the output type ("vec3","number",...)
+ * @param extra_info this can be used to have special properties of an output (label, special color, position, etc)
+ */
+ addOutput>(
+ name: string,
+ type: ISlotType,
+ extra_info?: TProperties
+ ): INodeOutputSlot & TProperties {
+ const output = Object.assign(
+ new NodeOutputSlot({ name, type, links: null }, this),
+ extra_info
+ )
+
+ this.outputs ||= []
+ this.outputs.push(output)
+ this.onOutputAdded?.(output)
+
+ if (LiteGraph.auto_load_slot_types)
+ LiteGraph.registerNodeAndSlotType(this, type, true)
+
+ this.expandToFitContent()
+ this.setDirtyCanvas(true, true)
+ return output
+ }
+
+ /**
+ * remove an existing output slot
+ */
+ removeOutput(slot: number): void {
+ // Only disconnect if node is part of a graph
+ if (this.graph) {
+ this.disconnectOutput(slot)
+ }
+ const { outputs } = this
+ outputs.splice(slot, 1)
+
+ for (let i = slot; i < outputs.length; ++i) {
+ const output = outputs[i]
+ if (!output || !output.links) continue
+
+ // Only update link indices if node is part of a graph
+ if (this.graph) {
+ for (const linkId of output.links) {
+ const link = this.graph._links.get(linkId)
+ if (link) link.origin_slot--
+ }
+ }
+ }
+
+ this.onOutputRemoved?.(slot)
+ this.setDirtyCanvas(true, true)
+ }
+
+ /**
+ * add a new input slot to use in this node
+ * @param type string defining the input type ("vec3","number",...), it its a generic one use 0
+ * @param extra_info this can be used to have special properties of an input (label, color, position, etc)
+ */
+ addInput>(
+ name: string,
+ type: ISlotType,
+ extra_info?: TProperties
+ ): INodeInputSlot & TProperties {
+ type ||= 0
+
+ const input = Object.assign(
+ new NodeInputSlot({ name, type, link: null }, this),
+ extra_info
+ )
+
+ this.inputs ||= []
+ this.inputs.push(input)
+ this.expandToFitContent()
+
+ this.onInputAdded?.(input)
+ LiteGraph.registerNodeAndSlotType(this, type)
+
+ this.setDirtyCanvas(true, true)
+ return input
+ }
+
+ /**
+ * remove an existing input slot
+ */
+ removeInput(slot: number): void {
+ // Only disconnect if node is part of a graph
+ if (this.graph) {
+ this.disconnectInput(slot, true)
+ }
+ const { inputs } = this
+ const slot_info = inputs.splice(slot, 1)
+
+ for (let i = slot; i < inputs.length; ++i) {
+ const input = inputs[i]
+ if (!input?.link) continue
+
+ // Only update link indices if node is part of a graph
+ if (this.graph) {
+ const link = this.graph._links.get(input.link)
+ if (link) link.target_slot--
+ }
+ }
+ this.onInputRemoved?.(slot, slot_info[0])
+ this.setDirtyCanvas(true, true)
+ }
+
+ /**
+ * computes the minimum size of a node according to its inputs and output slots
+ * @returns the total size
+ */
+ computeSize(out?: Size): Size {
+ const ctorSize = this.constructor.size
+ if (ctorSize) return [ctorSize[0], ctorSize[1]]
+
+ const { inputs, outputs, widgets } = this
+ let rows = Math.max(
+ inputs ? inputs.filter((input) => !isWidgetInputSlot(input)).length : 1,
+ outputs ? outputs.length : 1
+ )
+ const size = out ?? [0, 0]
+ rows = Math.max(rows, 1)
+ // although it should be graphcanvas.inner_text_font size
+ const font_size = LiteGraph.NODE_TEXT_SIZE
+
+ const padLeft = LiteGraph.NODE_TITLE_HEIGHT
+ const padRight = padLeft * 0.33
+ const title_width =
+ padLeft + compute_text_size(this.title, this.titleFontStyle) + padRight
+ let input_width = 0
+ let widgetWidth = 0
+ let output_width = 0
+
+ if (inputs) {
+ for (const input of inputs) {
+ const text = input.label || input.localized_name || input.name || ''
+ const text_width = compute_text_size(text, this.innerFontStyle)
+ if (isWidgetInputSlot(input)) {
+ const widget = this.getWidgetFromSlot(input)
+ if (widget && !this.isWidgetVisible(widget)) continue
+
+ if (text_width > widgetWidth) widgetWidth = text_width
+ } else {
+ if (text_width > input_width) input_width = text_width
+ }
+ }
+ }
+
+ if (outputs) {
+ for (const output of outputs) {
+ const text = output.label || output.localized_name || output.name || ''
+ const text_width = compute_text_size(text, this.innerFontStyle)
+ if (output_width < text_width) output_width = text_width
+ }
+ }
+
+ const minWidth = LiteGraph.NODE_WIDTH * (widgets?.length ? 1.5 : 1)
+ // Text + slot width + centre padding
+ const centrePadding = input_width && output_width ? 5 : 0
+ const slotsWidth =
+ input_width +
+ output_width +
+ 2 * LiteGraph.NODE_SLOT_HEIGHT +
+ centrePadding
+
+ // Total distance from edge of node to the inner edge of the widget 'previous' arrow button
+ const widgetMargin =
+ BaseWidget.margin + BaseWidget.arrowMargin + BaseWidget.arrowWidth
+ const widgetPadding = BaseWidget.minValueWidth + 2 * widgetMargin
+ if (widgetWidth) widgetWidth += widgetPadding
+
+ size[0] = Math.max(slotsWidth, widgetWidth, title_width, minWidth)
+ size[1] =
+ (this.constructor.slot_start_y || 0) + rows * LiteGraph.NODE_SLOT_HEIGHT
+
+ // Get widget height & expand size if necessary
+ let widgets_height = 0
+ if (widgets?.length) {
+ for (const widget of widgets) {
+ if (!this.isWidgetVisible(widget)) continue
+
+ let widget_height = 0
+ if (widget.computeSize) {
+ widget_height += widget.computeSize(size[0])[1]
+ } else if (widget.computeLayoutSize) {
+ // Expand widget width if necessary
+ const { minHeight, minWidth } = widget.computeLayoutSize(this)
+ const widgetWidth = minWidth + widgetPadding
+ if (widgetWidth > size[0]) size[0] = widgetWidth
+
+ widget_height += minHeight
+ } else {
+ widget_height += LiteGraph.NODE_WIDGET_HEIGHT
+ }
+ widgets_height += widget_height + 4
+ }
+ widgets_height += 8
+ }
+
+ // compute height using widgets height
+ if (this.widgets_up) size[1] = Math.max(size[1], widgets_height)
+ else if (this.widgets_start_y != null)
+ size[1] = Math.max(size[1], widgets_height + this.widgets_start_y)
+ else size[1] += widgets_height
+
+ function compute_text_size(text: string, fontStyle: string) {
+ return (
+ LGraphCanvas._measureText?.(text, fontStyle) ??
+ font_size * (text?.length ?? 0) * 0.6
+ )
+ }
+
+ if (this.constructor.min_height && size[1] < this.constructor.min_height) {
+ size[1] = this.constructor.min_height
+ }
+
+ // margin
+ size[1] += 6
+
+ return size
+ }
+
+ inResizeCorner(canvasX: number, canvasY: number): boolean {
+ const rows = this.outputs ? this.outputs.length : 1
+ const outputs_offset =
+ (this.constructor.slot_start_y || 0) + rows * LiteGraph.NODE_SLOT_HEIGHT
+ return isInRectangle(
+ canvasX,
+ canvasY,
+ this.pos[0] + this.size[0] - 15,
+ this.pos[1] + Math.max(this.size[1] - 15, outputs_offset),
+ 20,
+ 20
+ )
+ }
+
+ /**
+ * Returns which resize corner the point is over, if any.
+ * @param canvasX X position in canvas coordinates
+ * @param canvasY Y position in canvas coordinates
+ * @returns The compass corner the point is in, otherwise `undefined`.
+ */
+ findResizeDirection(
+ canvasX: number,
+ canvasY: number
+ ): CompassCorners | undefined {
+ if (this.resizable === false) return
+
+ const { boundingRect } = this
+ if (!boundingRect.containsXy(canvasX, canvasY)) return
+
+ // Check corners first (they take priority over edges)
+ return boundingRect.findContainingCorner(
+ canvasX,
+ canvasY,
+ LGraphNode.resizeHandleSize
+ )
+ }
+
+ /**
+ * returns all the info available about a property of this node.
+ * @param property name of the property
+ * @returns the object with all the available info
+ */
+ getPropertyInfo(property: string) {
+ let info = null
+
+ // there are several ways to define info about a property
+ // legacy mode
+ const { properties_info } = this
+ if (properties_info) {
+ for (const propInfo of properties_info) {
+ if (propInfo.name == property) {
+ info = propInfo
+ break
+ }
+ }
+ }
+ // litescene mode using the constructor
+ // @ts-expect-error deprecated https://github.com/Comfy-Org/litegraph.js/issues/639
+ if (this.constructor[`@${property}`])
+ // @ts-expect-error deprecated https://github.com/Comfy-Org/litegraph.js/issues/639
+ info = this.constructor[`@${property}`]
+
+ if (this.constructor.widgets_info?.[property])
+ info = this.constructor.widgets_info[property]
+
+ // litescene mode using the constructor
+ if (!info && this.onGetPropertyInfo) {
+ info = this.onGetPropertyInfo(property)
+ }
+
+ info ||= {}
+ info.type ||= typeof this.properties[property]
+ if (info.widget == 'combo') info.type = 'enum'
+
+ return info
+ }
+
+ /**
+ * Defines a widget inside the node, it will be rendered on top of the node, you can control lots of properties
+ * @param type the widget type
+ * @param name the text to show on the widget
+ * @param value the default value
+ * @param callback function to call when it changes (optionally, it can be the name of the property to modify)
+ * @param options the object that contains special properties of this widget
+ * @returns the created widget object
+ */
+ addWidget<
+ Type extends TWidgetType,
+ TValue extends WidgetTypeMap[Type]['value']
+ >(
+ type: Type,
+ name: string,
+ value: TValue,
+ callback: IBaseWidget['callback'] | string | null,
+ options?: IWidgetOptions | string
+ ): WidgetTypeMap[Type] | IBaseWidget {
+ this.widgets ||= []
+
+ if (!options && callback && typeof callback === 'object') {
+ options = callback
+ callback = null
+ }
+
+ // options can be the property name
+ options ||= {}
+ if (typeof options === 'string') options = { property: options }
+
+ // callback can be the property name
+ if (callback && typeof callback === 'string') {
+ options.property = callback
+ callback = null
+ }
+
+ const w: IBaseWidget & { type: Type } = {
+ // @ts-expect-error - Type casting for widget type property
+ type: type.toLowerCase(),
+ name: name,
+ value: value,
+ callback: typeof callback !== 'function' ? undefined : callback,
+ options,
+ y: 0
+ }
+
+ if (w.options.y !== undefined) {
+ w.y = w.options.y
+ }
+
+ if (!callback && !w.options.callback && !w.options.property) {
+ console.warn(
+ 'LiteGraph addWidget(...) without a callback or property assigned'
+ )
+ }
+ if (type == 'combo' && !w.options.values) {
+ throw "LiteGraph addWidget('combo',...) requires to pass values in options: { values:['red','blue'] }"
+ }
+
+ const widget = this.addCustomWidget(w)
+ this.expandToFitContent()
+ return widget
+ }
+
+ addCustomWidget(
+ custom_widget: TPlainWidget
+ ): TPlainWidget | WidgetTypeMap[TPlainWidget['type']] {
+ this.widgets ||= []
+ const widget = toConcreteWidget(custom_widget, this, false) ?? custom_widget
+ this.widgets.push(widget)
+ return widget
+ }
+
+ addTitleButton(options: LGraphButtonOptions): LGraphButton {
+ this.title_buttons ||= []
+ const button = new LGraphButton(options)
+ this.title_buttons.push(button)
+ return button
+ }
+
+ onTitleButtonClick(button: LGraphButton, canvas: LGraphCanvas): void {
+ // Dispatch event for button click
+ canvas.dispatch('litegraph:node-title-button-clicked', {
+ node: this,
+ button: button
+ })
+ }
+
+ removeWidgetByName(name: string): void {
+ const widget = this.widgets?.find((x) => x.name === name)
+ if (widget) this.removeWidget(widget)
+ }
+
+ removeWidget(widget: IBaseWidget): void {
+ if (!this.widgets)
+ throw new Error('removeWidget called on node without widgets')
+
+ const widgetIndex = this.widgets.indexOf(widget)
+ if (widgetIndex === -1) throw new Error('Widget not found on this node')
+
+ // Clean up slot references to prevent memory leaks
+ if (this.inputs) {
+ for (const input of this.inputs) {
+ if (input._widget === widget) {
+ input._widget = undefined
+ input.widget = undefined
+ }
+ }
+ }
+
+ widget.onRemove?.()
+ this.widgets.splice(widgetIndex, 1)
+ }
+
+ ensureWidgetRemoved(widget: IBaseWidget): void {
+ try {
+ this.removeWidget(widget)
+ } catch (error) {
+ console.error('Failed to remove widget', error)
+ }
+ }
+
+ move(deltaX: number, deltaY: number): void {
+ if (this.pinned) return
+
+ // If Vue nodes mode is enabled, skip LiteGraph's direct position update
+ // The layout store will handle the movement and sync back to LiteGraph
+ if (LiteGraph.vueNodesMode) {
+ // Vue nodes handle their own dragging through the layout store
+ // This prevents the snap-back issue from conflicting position updates
+ return
+ }
+
+ this.pos[0] += deltaX
+ this.pos[1] += deltaY
+ }
+
+ /**
+ * Internal method to measure the node for rendering. Prefer {@link boundingRect} where possible.
+ *
+ * Populates {@link out} with the results in graph space.
+ * Populates {@link _collapsed_width} with the collapsed width if the node is collapsed.
+ * Adjusts for title and collapsed status, but does not call {@link onBounding}.
+ * @param out `x, y, width, height` are written to this array.
+ * @param ctx The canvas context to use for measuring text.
+ */
+ measure(out: Rect, ctx?: CanvasRenderingContext2D): void {
+ const titleMode = this.title_mode
+ const renderTitle =
+ titleMode != TitleMode.TRANSPARENT_TITLE &&
+ titleMode != TitleMode.NO_TITLE
+ const titleHeight = renderTitle ? LiteGraph.NODE_TITLE_HEIGHT : 0
+
+ out[0] = this.pos[0]
+ out[1] = this.pos[1] + -titleHeight
+ if (!this.flags?.collapsed) {
+ out[2] = this.size[0]
+ out[3] = this.size[1] + titleHeight
+ } else {
+ if (ctx) ctx.font = this.innerFontStyle
+ this._collapsed_width = Math.min(
+ this.size[0],
+ ctx
+ ? ctx.measureText(this.getTitle() ?? '').width +
+ LiteGraph.NODE_TITLE_HEIGHT * 2
+ : 0
+ )
+ out[2] = this._collapsed_width || LiteGraph.NODE_COLLAPSED_WIDTH
+ out[3] = LiteGraph.NODE_TITLE_HEIGHT
+ }
+ }
+
+ /**
+ * returns the bounding of the object, used for rendering purposes
+ * @param out {Rect?} [optional] a place to store the output, to free garbage
+ * @param includeExternal {boolean?} [optional] set to true to
+ * include the shadow and connection points in the bounding calculation
+ * @returns the bounding box in format of [topleft_cornerx, topleft_cornery, width, height]
+ */
+ getBounding(out?: Rect, includeExternal?: boolean): Rect {
+ out ||= [0, 0, 0, 0]
+
+ const rect = includeExternal ? this.renderArea : this.boundingRect
+ out[0] = rect[0]
+ out[1] = rect[1]
+ out[2] = rect[2]
+ out[3] = rect[3]
+
+ return out
+ }
+
+ /**
+ * Calculates the render area of this node, populating both {@link boundingRect} and {@link renderArea}.
+ * Called automatically at the start of every frame.
+ */
+ updateArea(ctx?: CanvasRenderingContext2D): void {
+ const bounds = this.#boundingRect
+ this.measure(bounds, ctx)
+ this.onBounding?.(bounds)
+
+ const renderArea = this.#renderArea
+ renderArea.set(bounds)
+ // 4 offset for collapsed node connection points
+ renderArea[0] -= 4
+ renderArea[1] -= 4
+ // Add shadow & left offset
+ renderArea[2] += 6 + 4
+ // Add shadow & top offsets
+ renderArea[3] += 5 + 4
+ }
+
+ /**
+ * checks if a point is inside the shape of a node
+ */
+ isPointInside(x: number, y: number): boolean {
+ return isInRect(x, y, this.boundingRect)
+ }
+
+ /**
+ * Checks if the provided point is inside this node's collapse button area.
+ * @param x X co-ordinate to check
+ * @param y Y co-ordinate to check
+ * @returns true if the x,y point is in the collapse button area, otherwise false
+ */
+ isPointInCollapse(x: number, y: number): boolean {
+ const squareLength = LiteGraph.NODE_TITLE_HEIGHT
+ return isInRectangle(
+ x,
+ y,
+ this.pos[0],
+ this.pos[1] - squareLength,
+ squareLength,
+ squareLength
+ )
+ }
+
+ /**
+ * Returns the input slot at the given position. Uses full 20 height, and approximates the label length.
+ * @param pos The graph co-ordinates to check
+ * @returns The input slot at the given position if found, otherwise `undefined`.
+ */
+ getInputOnPos(pos: Point): INodeInputSlot | undefined {
+ return getNodeInputOnPos(this, pos[0], pos[1])?.input
+ }
+
+ /**
+ * Returns the output slot at the given position. Uses full 20x20 box for the slot.
+ * @param pos The graph co-ordinates to check
+ * @returns The output slot at the given position if found, otherwise `undefined`.
+ */
+ getOutputOnPos(pos: Point): INodeOutputSlot | undefined {
+ return getNodeOutputOnPos(this, pos[0], pos[1])?.output
+ }
+
+ /**
+ * Returns the input or output slot at the given position.
+ *
+ * Tries {@link getNodeInputOnPos} first, then {@link getNodeOutputOnPos}.
+ * @param pos The graph co-ordinates to check
+ * @returns The input or output slot at the given position if found, otherwise `undefined`.
+ */
+ getSlotOnPos(pos: Point): INodeInputSlot | INodeOutputSlot | undefined {
+ if (!isPointInRect(pos, this.boundingRect)) return
+
+ return this.getInputOnPos(pos) ?? this.getOutputOnPos(pos)
+ }
+
+ /**
+ * @deprecated Use {@link getSlotOnPos} instead.
+ * checks if a point is inside a node slot, and returns info about which slot
+ * @param x
+ * @param y
+ * @returns if found the object contains { input|output: slot object, slot: number, link_pos: [x,y] }
+ */
+ getSlotInPosition(x: number, y: number): IFoundSlot | null {
+ // search for inputs
+ const { inputs, outputs } = this
+
+ if (inputs) {
+ for (const [i, input] of inputs.entries()) {
+ const pos = this.getInputPos(i)
+ if (isInRectangle(x, y, pos[0] - 10, pos[1] - 10, 20, 20)) {
+ return { input, slot: i, link_pos: pos }
+ }
+ }
+ }
+
+ if (outputs) {
+ for (const [i, output] of outputs.entries()) {
+ const pos = this.getOutputPos(i)
+ if (isInRectangle(x, y, pos[0] - 10, pos[1] - 10, 20, 20)) {
+ return { output, slot: i, link_pos: pos }
+ }
+ }
+ }
+
+ return null
+ }
+
+ /**
+ * Gets the widget on this node at the given co-ordinates.
+ * @param canvasX X co-ordinate in graph space
+ * @param canvasY Y co-ordinate in graph space
+ * @returns The widget found, otherwise `null`
+ */
+ getWidgetOnPos(
+ canvasX: number,
+ canvasY: number,
+ includeDisabled = false
+ ): IBaseWidget | undefined {
+ const { widgets, pos, size } = this
+ if (!widgets?.length) return
+
+ const x = canvasX - pos[0]
+ const y = canvasY - pos[1]
+ const nodeWidth = size[0]
+
+ for (const widget of widgets) {
+ if (
+ (widget.computedDisabled && !includeDisabled) ||
+ !this.isWidgetVisible(widget)
+ ) {
+ continue
+ }
+
+ const h =
+ widget.computedHeight ??
+ widget.computeSize?.(nodeWidth)[1] ??
+ LiteGraph.NODE_WIDGET_HEIGHT
+
+ const maybeDOMWidget = widget as { margin?: number }
+ const mtop = maybeDOMWidget.margin ?? -2
+ const mbot = maybeDOMWidget.margin ?? 2
+ const mx = maybeDOMWidget.margin ?? 6
+
+ const w = widget.width || nodeWidth
+ if (
+ widget.last_y !== undefined &&
+ isInRectangle(
+ x,
+ y,
+ mx,
+ widget.last_y + mtop,
+ w - 2 * mx,
+ h - mtop - mbot
+ )
+ ) {
+ return widget
+ }
+ }
+ }
+
+ /**
+ * Returns the input slot with a given name (used for dynamic slots), -1 if not found
+ * @param name the name of the slot to find
+ * @param returnObj if the obj itself wanted
+ * @returns the slot (-1 if not found)
+ */
+ findInputSlot(
+ name: string,
+ returnObj?: TReturn
+ ): number
+ findInputSlot(
+ name: string,
+ returnObj?: TReturn
+ ): INodeInputSlot
+ findInputSlot(name: string, returnObj: boolean = false) {
+ const { inputs } = this
+ if (!inputs) return -1
+
+ for (const [i, input] of inputs.entries()) {
+ if (name == input.name) {
+ return !returnObj ? i : input
+ }
+ }
+ return -1
+ }
+
+ /**
+ * returns the output slot with a given name (used for dynamic slots), -1 if not found
+ * @param name the name of the slot to find
+ * @param returnObj if the obj itself wanted
+ * @returns the slot (-1 if not found)
+ */
+ findOutputSlot(
+ name: string,
+ returnObj?: TReturn
+ ): number
+ findOutputSlot(
+ name: string,
+ returnObj?: TReturn
+ ): INodeOutputSlot
+ findOutputSlot(name: string, returnObj: boolean = false) {
+ const { outputs } = this
+ if (!outputs) return -1
+
+ for (const [i, output] of outputs.entries()) {
+ if (name == output.name) {
+ return !returnObj ? i : output
+ }
+ }
+ return -1
+ }
+
+ /**
+ * Finds the first free input slot.
+ * @param optsIn
+ * @returns The index of the first matching slot, the slot itself if returnObj is true, or -1 if not found.
+ */
+ findInputSlotFree(
+ optsIn?: FindFreeSlotOptions & { returnObj?: TReturn }
+ ): number
+ findInputSlotFree(
+ optsIn?: FindFreeSlotOptions & { returnObj?: TReturn }
+ ): INodeInputSlot | -1
+ findInputSlotFree(optsIn?: FindFreeSlotOptions) {
+ return this.#findFreeSlot(this.inputs, optsIn)
+ }
+
+ /**
+ * Finds the first free output slot.
+ * @param optsIn
+ * @returns The index of the first matching slot, the slot itself if returnObj is true, or -1 if not found.
+ */
+ findOutputSlotFree(
+ optsIn?: FindFreeSlotOptions & { returnObj?: TReturn }
+ ): number
+ findOutputSlotFree(
+ optsIn?: FindFreeSlotOptions & { returnObj?: TReturn }
+ ): INodeOutputSlot | -1
+ findOutputSlotFree(optsIn?: FindFreeSlotOptions) {
+ return this.#findFreeSlot(this.outputs, optsIn)
+ }
+
+ /**
+ * Finds the next free slot
+ * @param slots The slots to search, i.e. this.inputs or this.outputs
+ */
+ #findFreeSlot(
+ slots: TSlot[],
+ options?: FindFreeSlotOptions
+ ): TSlot | number {
+ const defaults = {
+ returnObj: false,
+ typesNotAccepted: []
+ }
+ const opts = Object.assign(defaults, options || {})
+ const length = slots?.length
+ if (!(length > 0)) return -1
+
+ for (let i = 0; i < length; ++i) {
+ const slot: TSlot & IGenericLinkOrLinks = slots[i]
+ if (!slot || slot.link || slot.links?.length) continue
+ if (opts.typesNotAccepted?.includes?.(slot.type)) continue
+ return !opts.returnObj ? i : slot
+ }
+ return -1
+ }
+
+ /**
+ * findSlotByType for INPUTS
+ */
+ findInputSlotByType(
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): number
+ findInputSlotByType(
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): INodeInputSlot
+ findInputSlotByType(
+ type: ISlotType,
+ returnObj?: boolean,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ) {
+ return this.#findSlotByType(
+ this.inputs,
+ type,
+ returnObj,
+ preferFreeSlot,
+ doNotUseOccupied
+ )
+ }
+
+ /**
+ * findSlotByType for OUTPUTS
+ */
+ findOutputSlotByType(
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): number
+ findOutputSlotByType(
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): INodeOutputSlot
+ findOutputSlotByType(
+ type: ISlotType,
+ returnObj?: boolean,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ) {
+ return this.#findSlotByType(
+ this.outputs,
+ type,
+ returnObj,
+ preferFreeSlot,
+ doNotUseOccupied
+ )
+ }
+
+ /**
+ * returns the output (or input) slot with a given type, -1 if not found
+ * @param input use inputs instead of outputs
+ * @param type the type of the slot to find
+ * @param returnObj if the obj itself wanted
+ * @param preferFreeSlot if we want a free slot (if not found, will return the first of the type anyway)
+ * @returns the slot (-1 if not found)
+ */
+ findSlotByType(
+ input: TSlot,
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): number
+ findSlotByType(
+ input: TSlot,
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): INodeInputSlot | -1
+ findSlotByType(
+ input: TSlot,
+ type: ISlotType,
+ returnObj?: TReturn,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): INodeOutputSlot | -1
+ findSlotByType(
+ input: boolean,
+ type: ISlotType,
+ returnObj?: boolean,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): number | INodeOutputSlot | INodeInputSlot {
+ return input
+ ? this.#findSlotByType(
+ this.inputs,
+ type,
+ returnObj,
+ preferFreeSlot,
+ doNotUseOccupied
+ )
+ : this.#findSlotByType(
+ this.outputs,
+ type,
+ returnObj,
+ preferFreeSlot,
+ doNotUseOccupied
+ )
+ }
+
+ /**
+ * Finds a matching slot from those provided, returning the slot itself or its index in {@link slots}.
+ * @param slots Slots to search (this.inputs or this.outputs)
+ * @param type Type of slot to look for
+ * @param returnObj If true, returns the slot itself. Otherwise, the index.
+ * @param preferFreeSlot Prefer a free slot, but if none are found, fall back to an occupied slot.
+ * @param doNotUseOccupied Do not fall back to occupied slots.
+ * @see {findSlotByType}
+ * @see {findOutputSlotByType}
+ * @see {findInputSlotByType}
+ * @returns If a match is found, the slot if returnObj is true, otherwise the index. If no matches are found, -1
+ */
+ #findSlotByType(
+ slots: TSlot[],
+ type: ISlotType,
+ returnObj?: boolean,
+ preferFreeSlot?: boolean,
+ doNotUseOccupied?: boolean
+ ): TSlot | number {
+ const length = slots?.length
+ if (!length) return -1
+
+ // Empty string and * match anything (type: 0)
+ if (type == '' || type == '*') type = 0
+ const sourceTypes = String(type).toLowerCase().split(',')
+
+ // Run the search
+ let occupiedSlot: number | TSlot | null = null
+ for (let i = 0; i < length; ++i) {
+ const slot: TSlot & IGenericLinkOrLinks = slots[i]
+ const destTypes =
+ slot.type == '0' || slot.type == '*'
+ ? ['0']
+ : String(slot.type).toLowerCase().split(',')
+
+ for (const sourceType of sourceTypes) {
+ // TODO: Remove _event_ entirely.
+ const source = sourceType == '_event_' ? LiteGraph.EVENT : sourceType
+
+ for (const destType of destTypes) {
+ const dest = destType == '_event_' ? LiteGraph.EVENT : destType
+
+ if (source == dest || source === '*' || dest === '*') {
+ if (preferFreeSlot && (slot.links?.length || slot.link != null)) {
+ // In case we can't find a free slot.
+ occupiedSlot ??= returnObj ? slot : i
+ continue
+ }
+ return returnObj ? slot : i
+ }
+ }
+ }
+ }
+
+ return doNotUseOccupied ? -1 : (occupiedSlot ?? -1)
+ }
+
+ /**
+ * Determines the slot index to connect to when attempting to connect by type.
+ * @param findInputs If true, searches for an input. Otherwise, an output.
+ * @param node The node at the other end of the connection.
+ * @param slotType The type of slot at the other end of the connection.
+ * @param options Search restrictions to adhere to.
+ * @see {connectByType}
+ * @see {connectByTypeOutput}
+ */
+ findConnectByTypeSlot(
+ findInputs: boolean,
+ node: LGraphNode,
+ slotType: ISlotType,
+ options?: ConnectByTypeOptions
+ ): number | undefined {
+ // LEGACY: Old options names
+ if (options && typeof options === 'object') {
+ if ('firstFreeIfInputGeneralInCase' in options)
+ options.wildcardToTyped = !!options.firstFreeIfInputGeneralInCase
+ if ('firstFreeIfOutputGeneralInCase' in options)
+ options.wildcardToTyped = !!options.firstFreeIfOutputGeneralInCase
+ if ('generalTypeInCase' in options)
+ options.typedToWildcard = !!options.generalTypeInCase
+ }
+ const optsDef: ConnectByTypeOptions = {
+ createEventInCase: true,
+ wildcardToTyped: true,
+ typedToWildcard: true
+ }
+ const opts = Object.assign(optsDef, options)
+
+ if (!this.graph) throw new NullGraphError()
+
+ if (node && typeof node === 'number') {
+ const nodeById = this.graph.getNodeById(node)
+ if (!nodeById) return
+
+ node = nodeById
+ }
+ const slot = node.findSlotByType(findInputs, slotType, false, true)
+ if (slot >= 0 && slot !== null) return slot
+
+ // TODO: Remove or reimpl. events. WILL CREATE THE onTrigger IN SLOT
+ if (opts.createEventInCase && slotType == LiteGraph.EVENT) {
+ if (findInputs) return -1
+ if (LiteGraph.do_add_triggers_slots) return node.addOnExecutedOutput()
+ }
+
+ // connect to the first general output slot if not found a specific type and
+ if (opts.typedToWildcard) {
+ const generalSlot = node.findSlotByType(findInputs, 0, false, true, true)
+ if (generalSlot >= 0) return generalSlot
+ }
+ // connect to the first free input slot if not found a specific type and this output is general
+ if (
+ opts.wildcardToTyped &&
+ (slotType == 0 || slotType == '*' || slotType == '')
+ ) {
+ const opt = { typesNotAccepted: [LiteGraph.EVENT] }
+ const nonEventSlot = findInputs
+ ? node.findInputSlotFree(opt)
+ : node.findOutputSlotFree(opt)
+ if (nonEventSlot >= 0) return nonEventSlot
+ }
+ }
+
+ /**
+ * Finds the first free output slot with any of the comma-delimited types in {@link type}.
+ *
+ * If no slots are free, falls back in order to:
+ * - The first free wildcard slot
+ * - The first occupied slot
+ * - The first occupied wildcard slot
+ * @param type The {@link ISlotType type} of slot to find
+ * @returns The index and slot if found, otherwise `undefined`.
+ */
+ findOutputByType(
+ type: ISlotType
+ ): { index: number; slot: INodeOutputSlot } | undefined {
+ return findFreeSlotOfType(
+ this.outputs,
+ type,
+ (output) => !output.links?.length
+ )
+ }
+
+ /**
+ * Finds the first free input slot with any of the comma-delimited types in {@link type}.
+ *
+ * If no slots are free, falls back in order to:
+ * - The first free wildcard slot
+ * - The first occupied slot
+ * - The first occupied wildcard slot
+ * @param type The {@link ISlotType type} of slot to find
+ * @returns The index and slot if found, otherwise `undefined`.
+ */
+ findInputByType(
+ type: ISlotType
+ ): { index: number; slot: INodeInputSlot } | undefined {
+ return findFreeSlotOfType(
+ this.inputs,
+ type,
+ (input) =>
+ input.link == null || !!this.graph?.getLink(input.link)?._dragging
+ )
+ }
+
+ /**
+ * connect this node output to the input of another node BY TYPE
+ * @param slot (could be the number of the slot or the string with the name of the slot)
+ * @param target_node the target node
+ * @param target_slotType the input slot type of the target node
+ * @returns the link_info is created, otherwise null
+ */
+ connectByType(
+ slot: number | string,
+ target_node: LGraphNode,
+ target_slotType: ISlotType,
+ optsIn?: ConnectByTypeOptions
+ ): LLink | null {
+ const slotIndex = this.findConnectByTypeSlot(
+ true,
+ target_node,
+ target_slotType,
+ optsIn
+ )
+ if (slotIndex !== undefined)
+ return this.connect(slot, target_node, slotIndex, optsIn?.afterRerouteId)
+
+ // No compatible slot found - connection not possible
+ return null
+ }
+
+ /**
+ * connect this node input to the output of another node BY TYPE
+ * @param slot (could be the number of the slot or the string with the name of the slot)
+ * @param source_node the target node
+ * @param source_slotType the output slot type of the target node
+ * @returns the link_info is created, otherwise null
+ */
+ connectByTypeOutput(
+ slot: number | string,
+ source_node: LGraphNode,
+ source_slotType: ISlotType,
+ optsIn?: ConnectByTypeOptions
+ ): LLink | null {
+ // LEGACY: Old options names
+ if (typeof optsIn === 'object') {
+ if ('firstFreeIfInputGeneralInCase' in optsIn)
+ optsIn.wildcardToTyped = !!optsIn.firstFreeIfInputGeneralInCase
+ if ('generalTypeInCase' in optsIn)
+ optsIn.typedToWildcard = !!optsIn.generalTypeInCase
+ }
+ const slotIndex = this.findConnectByTypeSlot(
+ false,
+ source_node,
+ source_slotType,
+ optsIn
+ )
+ if (slotIndex !== undefined)
+ return source_node.connect(slotIndex, this, slot, optsIn?.afterRerouteId)
+
+ console.error(
+ '[connectByType]: no way to connect type:',
+ source_slotType,
+ 'to node:',
+ source_node
+ )
+ return null
+ }
+
+ canConnectTo(
+ node: NodeLike,
+ toSlot: INodeInputSlot | SubgraphIO,
+ fromSlot: INodeOutputSlot | SubgraphIO
+ ) {
+ return (
+ this.id !== node.id &&
+ LiteGraph.isValidConnection(fromSlot.type, toSlot.type)
+ )
+ }
+
+ /**
+ * Connect an output of this node to an input of another node
+ * @param slot (could be the number of the slot or the string with the name of the slot)
+ * @param target_node the target node
+ * @param target_slot the input slot of the target node (could be the number of the slot or the string with the name of the slot, or -1 to connect a trigger)
+ * @returns the link_info is created, otherwise null
+ */
+ connect(
+ slot: number | string,
+ target_node: LGraphNode,
+ target_slot: ISlotType,
+ afterRerouteId?: RerouteId
+ ): LLink | null {
+ // Allow legacy API support for searching target_slot by string, without mutating the input variables
+ let targetIndex: number | null
+
+ const { graph, outputs } = this
+ if (!graph) {
+ // could be connected before adding it to a graph
+ // due to link ids being associated with graphs
+ console.error(
+ "Connect: Error, node doesn't belong to any graph. Nodes must be added first to a graph before connecting them."
+ )
+ return null
+ }
+
+ // seek for the output slot
+ if (typeof slot === 'string') {
+ slot = this.findOutputSlot(slot)
+ if (slot == -1) {
+ if (LiteGraph.debug)
+ console.error(`Connect: Error, no slot of name ${slot}`)
+ return null
+ }
+ } else if (!outputs || slot >= outputs.length) {
+ if (LiteGraph.debug)
+ console.error('Connect: Error, slot number not found')
+ return null
+ }
+
+ if (target_node && typeof target_node === 'number') {
+ const nodeById = graph.getNodeById(target_node)
+ if (!nodeById) throw 'target node is null'
+
+ target_node = nodeById
+ }
+ if (!target_node) throw 'target node is null'
+
+ // avoid loopback
+ if (target_node == this) return null
+
+ // you can specify the slot by name
+ if (typeof target_slot === 'string') {
+ targetIndex = target_node.findInputSlot(target_slot)
+ if (targetIndex == -1) {
+ if (LiteGraph.debug)
+ console.error(`Connect: Error, no slot of name ${targetIndex}`)
+ return null
+ }
+ } else if (target_slot === LiteGraph.EVENT) {
+ // TODO: Events
+ if (LiteGraph.do_add_triggers_slots) {
+ target_node.changeMode(LGraphEventMode.ON_TRIGGER)
+ targetIndex = target_node.findInputSlot('onTrigger')
+ } else {
+ return null
+ }
+ } else if (typeof target_slot === 'number') {
+ targetIndex = target_slot
+ } else {
+ targetIndex = 0
+ }
+
+ // Allow target node to change slot
+ if (target_node.onBeforeConnectInput) {
+ // This way node can choose another slot (or make a new one?)
+ const requestedIndex = target_node.onBeforeConnectInput(
+ targetIndex,
+ target_slot
+ )
+ targetIndex = typeof requestedIndex === 'number' ? requestedIndex : null
+ }
+
+ if (
+ targetIndex === null ||
+ !target_node.inputs ||
+ targetIndex >= target_node.inputs.length
+ ) {
+ if (LiteGraph.debug)
+ console.error('Connect: Error, slot number not found')
+ return null
+ }
+
+ const input = target_node.inputs[targetIndex]
+ const output = outputs[slot]
+
+ if (!output) return null
+
+ if (output.links?.length) {
+ if (
+ output.type === LiteGraph.EVENT &&
+ !LiteGraph.allow_multi_output_for_events
+ ) {
+ graph.beforeChange()
+ this.disconnectOutput(slot)
+ }
+ }
+
+ const link = this.connectSlots(output, target_node, input, afterRerouteId)
+ return link ?? null
+ }
+
+ /**
+ * Connect two slots between two nodes
+ * @param output The output slot to connect
+ * @param inputNode The node that the input slot is on
+ * @param input The input slot to connect
+ * @param afterRerouteId The reroute ID to use for the link
+ * @returns The link that was created, or null if the connection was blocked
+ */
+ connectSlots(
+ output: INodeOutputSlot,
+ inputNode: LGraphNode,
+ input: INodeInputSlot,
+ afterRerouteId: RerouteId | undefined
+ ): LLink | null | undefined {
+ const { graph } = this
+ if (!graph) throw new NullGraphError()
+
+ const layoutMutations = useLayoutMutations()
+
+ const outputIndex = this.outputs.indexOf(output)
+ if (outputIndex === -1) {
+ console.warn('connectSlots: output not found')
+ return
+ }
+ const inputIndex = inputNode.inputs.indexOf(input)
+ if (inputIndex === -1) {
+ console.warn('connectSlots: input not found')
+ return
+ }
+
+ // check targetSlot and check connection types
+ if (!LiteGraph.isValidConnection(output.type, input.type)) {
+ this.setDirtyCanvas(false, true)
+ return null
+ }
+
+ // Allow nodes to block connection
+ if (
+ inputNode.onConnectInput?.(
+ inputIndex,
+ output.type,
+ output,
+ this,
+ outputIndex
+ ) === false
+ )
+ return null
+ if (
+ this.onConnectOutput?.(
+ outputIndex,
+ input.type,
+ input,
+ inputNode,
+ inputIndex
+ ) === false
+ )
+ return null
+
+ // if there is something already plugged there, disconnect
+ if (inputNode.inputs[inputIndex]?.link != null) {
+ graph.beforeChange()
+ inputNode.disconnectInput(inputIndex, true)
+ }
+
+ const maybeCommonType =
+ input.type && output.type && commonType(input.type, output.type)
+
+ const link = new LLink(
+ ++graph.state.lastLinkId,
+ maybeCommonType || input.type || output.type,
+ this.id,
+ outputIndex,
+ inputNode.id,
+ inputIndex,
+ afterRerouteId
+ )
+
+ // add to graph links list
+ graph._links.set(link.id, link)
+
+ // Register link in Layout Store for spatial tracking
+ layoutMutations.setSource(LayoutSource.Canvas)
+ layoutMutations.createLink(
+ link.id,
+ this.id,
+ outputIndex,
+ inputNode.id,
+ inputIndex
+ )
+
+ // connect in output
+ output.links ??= []
+ output.links.push(link.id)
+ // connect in input
+ const targetInput = inputNode.inputs[inputIndex]
+ targetInput.link = link.id
+ if (targetInput.widget) {
+ graph.trigger('node:slot-links:changed', {
+ nodeId: inputNode.id,
+ slotType: NodeSlotType.INPUT,
+ slotIndex: inputIndex,
+ connected: true,
+ linkId: link.id
+ })
+ }
+
+ // Reroutes
+ const reroutes = LLink.getReroutes(graph, link)
+ for (const reroute of reroutes) {
+ reroute.linkIds.add(link.id)
+ if (reroute.floating) reroute.floating = undefined
+ reroute._dragging = undefined
+ }
+
+ // If this is the terminus of a floating link, remove it
+ const lastReroute = reroutes.at(-1)
+ if (lastReroute) {
+ for (const linkId of lastReroute.floatingLinkIds) {
+ const link = graph.floatingLinks.get(linkId)
+ if (link?.parentId === lastReroute.id) {
+ graph.removeFloatingLink(link)
+ }
+ }
+ }
+ graph._version++
+
+ // link has been created now, so its updated
+ this.onConnectionsChange?.(
+ NodeSlotType.OUTPUT,
+ outputIndex,
+ true,
+ link,
+ output
+ )
+
+ inputNode.onConnectionsChange?.(
+ NodeSlotType.INPUT,
+ inputIndex,
+ true,
+ link,
+ input
+ )
+
+ this.setDirtyCanvas(false, true)
+ graph.afterChange()
+
+ return link
+ }
+
+ connectFloatingReroute(
+ pos: Point,
+ slot: INodeInputSlot | INodeOutputSlot,
+ afterRerouteId?: RerouteId
+ ): Reroute {
+ const { graph, id } = this
+ if (!graph) throw new NullGraphError()
+
+ // Assertion: It's either there or it isn't.
+ const inputIndex = this.inputs.indexOf(slot as INodeInputSlot)
+ const outputIndex = this.outputs.indexOf(slot as INodeOutputSlot)
+ if (inputIndex === -1 && outputIndex === -1) throw new Error('Invalid slot')
+
+ const slotType = outputIndex === -1 ? 'input' : 'output'
+
+ const reroute = graph.setReroute({
+ pos,
+ parentId: afterRerouteId,
+ linkIds: [],
+ floating: { slotType }
+ })
+
+ const parentReroute = graph.getReroute(afterRerouteId)
+ const fromLastFloatingReroute =
+ parentReroute?.floating?.slotType === 'output'
+
+ // Adding from an output, or a floating reroute that is NOT the tip of an existing floating chain
+ if (afterRerouteId == null || !fromLastFloatingReroute) {
+ const link = new LLink(
+ -1,
+ slot.type,
+ outputIndex === -1 ? -1 : id,
+ outputIndex,
+ inputIndex === -1 ? -1 : id,
+ inputIndex
+ )
+ link.parentId = reroute.id
+ graph.addFloatingLink(link)
+ return reroute
+ }
+
+ // Adding a new floating reroute from the tip of a floating chain.
+ if (!parentReroute)
+ throw new Error('[connectFloatingReroute] Parent reroute not found')
+
+ const link = parentReroute.getFloatingLinks('output')?.[0]
+ if (!link)
+ throw new Error('[connectFloatingReroute] Floating link not found')
+
+ reroute.floatingLinkIds.add(link.id)
+ link.parentId = reroute.id
+ parentReroute.floating = undefined
+ return reroute
+ }
+
+ /**
+ * disconnect one output to an specific node
+ * @param slot (could be the number of the slot or the string with the name of the slot)
+ * @param target_node the target node to which this slot is connected [Optional,
+ * if not target_node is specified all nodes will be disconnected]
+ * @returns if it was disconnected successfully
+ */
+ disconnectOutput(slot: string | number, target_node?: LGraphNode): boolean {
+ if (typeof slot === 'string') {
+ slot = this.findOutputSlot(slot)
+ if (slot == -1) {
+ if (LiteGraph.debug)
+ console.error(`Connect: Error, no slot of name ${slot}`)
+ return false
+ }
+ } else if (!this.outputs || slot >= this.outputs.length) {
+ if (LiteGraph.debug)
+ console.error('Connect: Error, slot number not found')
+ return false
+ }
+
+ // get output slot
+ const output = this.outputs[slot]
+ if (!output) return false
+
+ if (output._floatingLinks) {
+ for (const link of output._floatingLinks) {
+ if (link.hasOrigin(this.id, slot)) {
+ this.graph?.removeFloatingLink(link)
+ }
+ }
+ }
+
+ if (!output.links || output.links.length == 0) return false
+ const { links } = output
+
+ // one of the output links in this slot
+ const graph = this.graph
+ if (!graph) throw new NullGraphError()
+
+ if (target_node) {
+ const target =
+ typeof target_node === 'number'
+ ? graph.getNodeById(target_node)
+ : target_node
+ if (!target) throw 'Target Node not found'
+
+ for (const [i, link_id] of links.entries()) {
+ const link_info = graph._links.get(link_id)
+ if (link_info?.target_id != target.id) continue
+
+ // is the link we are searching for...
+ // remove here
+ links.splice(i, 1)
+ const input = target.inputs[link_info.target_slot]
+ // remove there
+ input.link = null
+ if (input.widget) {
+ graph.trigger('node:slot-links:changed', {
+ nodeId: target.id,
+ slotType: NodeSlotType.INPUT,
+ slotIndex: link_info.target_slot,
+ connected: false,
+ linkId: link_info.id
+ })
+ }
+
+ // remove the link from the links pool
+ link_info.disconnect(graph, 'input')
+ graph._version++
+
+ // link_info hasn't been modified so its ok
+ target.onConnectionsChange?.(
+ NodeSlotType.INPUT,
+ link_info.target_slot,
+ false,
+ link_info,
+ input
+ )
+ this.onConnectionsChange?.(
+ NodeSlotType.OUTPUT,
+ slot,
+ false,
+ link_info,
+ output
+ )
+
+ break
+ }
+ } else {
+ // all the links in this output slot
+ for (const link_id of links) {
+ const link_info = graph._links.get(link_id)
+ if (!link_info) continue
+ if (
+ link_info.target_id === SUBGRAPH_OUTPUT_ID &&
+ graph instanceof Subgraph
+ ) {
+ const targetSlot = graph.outputNode.slots[link_info.target_slot]
+ if (targetSlot) {
+ targetSlot.linkIds.length = 0
+ } else {
+ console.error('Missing subgraphOutput slot when disconnecting link')
+ }
+ }
+
+ const target = graph.getNodeById(link_info.target_id)
+ graph._version++
+
+ if (target) {
+ const input = target.inputs[link_info.target_slot]
+ // remove other side link
+ input.link = null
+ if (input.widget) {
+ graph.trigger('node:slot-links:changed', {
+ nodeId: target.id,
+ slotType: NodeSlotType.INPUT,
+ slotIndex: link_info.target_slot,
+ connected: false,
+ linkId: link_info.id
+ })
+ }
+
+ // link_info hasn't been modified so its ok
+ target.onConnectionsChange?.(
+ NodeSlotType.INPUT,
+ link_info.target_slot,
+ false,
+ link_info,
+ input
+ )
+ }
+ // remove the link from the links pool
+ link_info.disconnect(graph, 'input')
+
+ this.onConnectionsChange?.(
+ NodeSlotType.OUTPUT,
+ slot,
+ false,
+ link_info,
+ output
+ )
+ }
+ output.links = null
+ }
+
+ this.setDirtyCanvas(false, true)
+ return true
+ }
+
+ /**
+ * Disconnect one input
+ * @param slot Input slot index, or the name of the slot
+ * @param keepReroutes If `true`, reroutes will not be garbage collected.
+ * @returns true if disconnected successfully or already disconnected, otherwise false
+ */
+ disconnectInput(slot: number | string, keepReroutes?: boolean): boolean {
+ // Allow search by string
+ if (typeof slot === 'string') {
+ slot = this.findInputSlot(slot)
+ if (slot == -1) {
+ if (LiteGraph.debug)
+ console.error(`Connect: Error, no slot of name ${slot}`)
+ return false
+ }
+ } else if (!this.inputs || slot >= this.inputs.length) {
+ if (LiteGraph.debug) {
+ console.error('Connect: Error, slot number not found')
+ }
+ return false
+ }
+
+ const input = this.inputs[slot]
+ if (!input) {
+ console.error('disconnectInput: input not found', slot, this.inputs)
+ return false
+ }
+
+ const { graph } = this
+ if (!graph) throw new NullGraphError()
+
+ // Break floating links
+ if (input._floatingLinks?.size) {
+ for (const link of input._floatingLinks) {
+ graph.removeFloatingLink(link)
+ }
+ }
+
+ const link_id = this.inputs[slot].link
+ if (link_id != null) {
+ this.inputs[slot].link = null
+ if (input.widget) {
+ graph.trigger('node:slot-links:changed', {
+ nodeId: this.id,
+ slotType: NodeSlotType.INPUT,
+ slotIndex: slot,
+ connected: false,
+ linkId: link_id
+ })
+ }
+
+ // remove other side
+ const link_info = graph._links.get(link_id)
+ if (link_info) {
+ // Let SubgraphInput do the disconnect.
+ if (link_info.origin_id === -10 && 'inputNode' in graph) {
+ graph.inputNode._disconnectNodeInput(this, input, link_info)
+ return true
+ }
+
+ const target_node = graph.getNodeById(link_info.origin_id)
+ if (!target_node) {
+ console.error(
+ 'disconnectInput: output not found',
+ link_info.origin_slot
+ )
+ return false
+ }
+
+ const output = target_node.outputs[link_info.origin_slot]
+ if (!output?.links?.length) {
+ // Output not found - may have been removed
+ return false
+ }
+
+ // search in the inputs list for this link
+ let i = 0
+ for (const l = output.links.length; i < l; i++) {
+ if (output.links[i] == link_id) {
+ output.links.splice(i, 1)
+ break
+ }
+ }
+
+ link_info.disconnect(graph, keepReroutes ? 'output' : undefined)
+ if (graph) graph._version++
+
+ this.onConnectionsChange?.(
+ NodeSlotType.INPUT,
+ slot,
+ false,
+ link_info,
+ input
+ )
+ target_node.onConnectionsChange?.(
+ NodeSlotType.OUTPUT,
+ i,
+ false,
+ link_info,
+ output
+ )
+ }
+ }
+
+ this.setDirtyCanvas(false, true)
+ return true
+ }
+
+ /**
+ * @deprecated Use {@link getInputPos} or {@link getOutputPos} instead.
+ * returns the center of a connection point in canvas coords
+ * @param is_input true if if a input slot, false if it is an output
+ * @param slot_number (could be the number of the slot or the string with the name of the slot)
+ * @param out [optional] a place to store the output, to free garbage
+ * @returns the position
+ */
+ getConnectionPos(is_input: boolean, slot_number: number, out?: Point): Point {
+ out ||= [0, 0]
+
+ const {
+ pos: [nodeX, nodeY],
+ inputs,
+ outputs
+ } = this
+
+ if (this.flags.collapsed) {
+ const w = this._collapsed_width || LiteGraph.NODE_COLLAPSED_WIDTH
+ out[0] = is_input ? nodeX : nodeX + w
+ out[1] = nodeY - LiteGraph.NODE_TITLE_HEIGHT * 0.5
+ return out
+ }
+
+ // weird feature that never got finished
+ if (is_input && slot_number == -1) {
+ out[0] = nodeX + LiteGraph.NODE_TITLE_HEIGHT * 0.5
+ out[1] = nodeY + LiteGraph.NODE_TITLE_HEIGHT * 0.5
+ return out
+ }
+
+ // hard-coded pos
+ const inputPos = inputs?.[slot_number]?.pos
+ const outputPos = outputs?.[slot_number]?.pos
+
+ if (is_input && inputPos) {
+ out[0] = nodeX + inputPos[0]
+ out[1] = nodeY + inputPos[1]
+ return out
+ } else if (!is_input && outputPos) {
+ out[0] = nodeX + outputPos[0]
+ out[1] = nodeY + outputPos[1]
+ return out
+ }
+
+ // default vertical slots
+ const offset = LiteGraph.NODE_SLOT_HEIGHT * 0.5
+ const slotIndex = is_input
+ ? this.#defaultVerticalInputs.indexOf(this.inputs[slot_number])
+ : this.#defaultVerticalOutputs.indexOf(this.outputs[slot_number])
+
+ out[0] = is_input ? nodeX + offset : nodeX + this.size[0] + 1 - offset
+ out[1] =
+ nodeY +
+ (slotIndex + 0.7) * LiteGraph.NODE_SLOT_HEIGHT +
+ (this.constructor.slot_start_y || 0)
+ return out
+ }
+
+ /**
+ * @internal The inputs that are not positioned with absolute coordinates.
+ */
+ get #defaultVerticalInputs() {
+ return this.inputs.filter(
+ (slot) => !slot.pos && !(this.widgets?.length && isWidgetInputSlot(slot))
+ )
+ }
+
+ /**
+ * @internal The outputs that are not positioned with absolute coordinates.
+ */
+ get #defaultVerticalOutputs() {
+ return this.outputs.filter((slot: INodeOutputSlot) => !slot.pos)
+ }
+
+ /**
+ * Get the context needed for slot position calculations
+ * @internal
+ */
+ #getSlotPositionContext(): SlotPositionContext {
+ return {
+ nodeX: this.pos[0],
+ nodeY: this.pos[1],
+ nodeWidth: this.size[0],
+ nodeHeight: this.size[1],
+ collapsed: this.flags.collapsed ?? false,
+ collapsedWidth: this._collapsed_width,
+ slotStartY: this.constructor.slot_start_y,
+ inputs: this.inputs,
+ outputs: this.outputs,
+ widgets: this.widgets
+ }
+ }
+
+ /**
+ * Gets the position of an input slot, in graph co-ordinates.
+ *
+ * This method is preferred over the legacy {@link getConnectionPos} method.
+ * @param slot Input slot index
+ * @returns Position of the input slot
+ */
+ getInputPos(slot: number): Point {
+ return calculateInputSlotPos(this.#getSlotPositionContext(), slot)
+ }
+
+ /**
+ * Gets the position of an input slot, in graph co-ordinates.
+ * @param input The actual node input object
+ * @returns Position of the centre of the input slot in graph co-ordinates.
+ */
+ getInputSlotPos(input: INodeInputSlot): Point {
+ return calculateInputSlotPosFromSlot(this.#getSlotPositionContext(), input)
+ }
+
+ /**
+ * Gets the position of an output slot, in graph co-ordinates.
+ *
+ * This method is preferred over the legacy {@link getConnectionPos} method.
+ * @param outputSlotIndex Output slot index
+ * @returns Position of the output slot
+ */
+ getOutputPos(outputSlotIndex: number): Point {
+ return calculateOutputSlotPos(
+ this.#getSlotPositionContext(),
+ outputSlotIndex
+ )
+ }
+
+ /**
+ * Get slot position using layout tree if available, fallback to node's position * Unified implementation used by both LitegraphLinkAdapter and useLinkLayoutSync
+ * @param slotIndex The slot index
+ * @param isInput Whether this is an input slot
+ * @returns Position of the slot center in graph coordinates
+ */
+ getSlotPosition(slotIndex: number, isInput: boolean): Point {
+ return getSlotPosition(this, slotIndex, isInput)
+ }
+
+ /** @inheritdoc */
+ snapToGrid(snapTo: number): boolean {
+ return this.pinned ? false : snapPoint(this.pos, snapTo)
+ }
+
+ /** @see {@link snapToGrid} */
+ alignToGrid(): void {
+ this.snapToGrid(LiteGraph.CANVAS_GRID_SIZE)
+ }
+
+ /* Console output */
+ trace(msg: string): void {
+ this.console ||= []
+ this.console.push(msg)
+ // @ts-expect-error deprecated
+ if (this.console.length > LGraphNode.MAX_CONSOLE) this.console.shift()
+ }
+
+ /* Forces to redraw or the main canvas (LGraphNode) or the bg canvas (links) */
+ setDirtyCanvas(dirty_foreground: boolean, dirty_background?: boolean): void {
+ this.graph?.canvasAction((c) =>
+ c.setDirty(dirty_foreground, dirty_background)
+ )
+ }
+
+ loadImage(url: string): HTMLImageElement {
+ interface AsyncImageElement extends HTMLImageElement {
+ ready?: boolean
+ }
+
+ const img: AsyncImageElement = new Image()
+ img.src = LiteGraph.node_images_path + url
+ img.ready = false
+
+ const dirty = () => this.setDirtyCanvas(true)
+ img.addEventListener('load', function (this: AsyncImageElement) {
+ this.ready = true
+ dirty()
+ })
+ return img
+ }
+
+ /**
+ * Allows to get onMouseMove and onMouseUp events even if the mouse is out of focus
+ * @deprecated Use {@link LGraphCanvas.pointer} instead.
+ */
+ captureInput(v: boolean): void {
+ warnDeprecated(
+ '[DEPRECATED] captureInput will be removed in a future version. Please use LGraphCanvas.pointer (CanvasPointer) instead.'
+ )
+ if (!this.graph || !this.graph.list_of_graphcanvas) return
+
+ const list = this.graph.list_of_graphcanvas
+
+ for (const c of list) {
+ // releasing somebody elses capture?!
+ if (!v && c.node_capturing_input != this) continue
+
+ // change
+ c.node_capturing_input = v ? this : null
+ }
+ }
+
+ get collapsed() {
+ return !!this.flags.collapsed
+ }
+
+ get collapsible() {
+ return !this.pinned && this.constructor.collapsable !== false
+ }
+
+ /**
+ * Toggle node collapse (makes it smaller on the canvas)
+ */
+ collapse(force?: boolean): void {
+ if (!this.collapsible && !force) return
+ if (!this.graph) throw new NullGraphError()
+ this.graph._version++
+ this.flags.collapsed = !this.flags.collapsed
+ this.setDirtyCanvas(true, true)
+ }
+
+ /**
+ * Toggles advanced mode of the node, showing advanced widgets
+ */
+ toggleAdvanced() {
+ if (!this.widgets?.some((w) => w.advanced)) return
+ if (!this.graph) throw new NullGraphError()
+ this.graph._version++
+ this.showAdvanced = !this.showAdvanced
+ this.expandToFitContent()
+ this.setDirtyCanvas(true, true)
+ }
+
+ get pinned() {
+ return !!this.flags.pinned
+ }
+
+ /**
+ * Prevents the node being accidentally moved or resized by mouse interaction.
+ * Toggles pinned state if no value is provided.
+ */
+ pin(v?: boolean): void {
+ if (!this.graph) throw new NullGraphError()
+
+ this.graph._version++
+ this.flags.pinned = v ?? !this.flags.pinned
+ this.resizable = !this.pinned
+ if (!this.pinned) this.flags.pinned = undefined
+ }
+
+ unpin(): void {
+ this.pin(false)
+ }
+
+ localToScreen(x: number, y: number, dragAndScale: DragAndScale): Point {
+ return [
+ (x + this.pos[0]) * dragAndScale.scale + dragAndScale.offset[0],
+ (y + this.pos[1]) * dragAndScale.scale + dragAndScale.offset[1]
+ ]
+ }
+
+ get width() {
+ return this.collapsed
+ ? this._collapsed_width || LiteGraph.NODE_COLLAPSED_WIDTH
+ : this.size[0]
+ }
+
+ /**
+ * Returns the height of the node, including the title bar.
+ */
+ get height() {
+ return LiteGraph.NODE_TITLE_HEIGHT + this.bodyHeight
+ }
+
+ /**
+ * Returns the height of the node, excluding the title bar.
+ */
+ get bodyHeight() {
+ return this.collapsed ? 0 : this.size[1]
+ }
+
+ drawBadges(ctx: CanvasRenderingContext2D, { gap = 2 } = {}): void {
+ const badgeInstances = this.badges.map((badge) =>
+ badge instanceof LGraphBadge ? badge : badge()
+ )
+ const isLeftAligned = this.badgePosition === BadgePosition.TopLeft
+
+ let currentX = isLeftAligned
+ ? 0
+ : this.width -
+ badgeInstances.reduce(
+ (acc, badge) => acc + badge.getWidth(ctx) + gap,
+ 0
+ )
+ const y = -(LiteGraph.NODE_TITLE_HEIGHT + gap)
+
+ for (const badge of badgeInstances) {
+ badge.draw(ctx, currentX, y - badge.height)
+ currentX += badge.getWidth(ctx) + gap
+ }
+ }
+
+ /**
+ * Renders the node's title bar background
+ */
+ drawTitleBarBackground(
+ ctx: CanvasRenderingContext2D,
+ {
+ scale,
+ title_height = LiteGraph.NODE_TITLE_HEIGHT,
+ low_quality = false
+ }: DrawTitleOptions
+ ): void {
+ const fgcolor = this.renderingColor
+ const shape = this.renderingShape
+ const size = this.renderingSize
+
+ if (this.onDrawTitleBar) {
+ this.onDrawTitleBar(ctx, title_height, size, scale, fgcolor)
+ return
+ }
+
+ if (this.title_mode === TitleMode.TRANSPARENT_TITLE) {
+ return
+ }
+
+ if (this.collapsed) {
+ ctx.shadowColor = LiteGraph.DEFAULT_SHADOW_COLOR
+ }
+
+ ctx.fillStyle = this.constructor.title_color || fgcolor
+ ctx.beginPath()
+
+ if (shape == RenderShape.BOX || low_quality) {
+ ctx.rect(0, -title_height, size[0], title_height)
+ } else if (shape == RenderShape.ROUND || shape == RenderShape.CARD) {
+ ctx.roundRect(
+ 0,
+ -title_height,
+ size[0],
+ title_height,
+ this.collapsed
+ ? [LiteGraph.ROUND_RADIUS]
+ : [LiteGraph.ROUND_RADIUS, LiteGraph.ROUND_RADIUS, 0, 0]
+ )
+ }
+ ctx.fill()
+ ctx.shadowColor = 'transparent'
+ }
+
+ /**
+ * Renders the node's title box, i.e. the dot in front of the title text that
+ * when clicked toggles the node's collapsed state. The term `title box` comes
+ * from the original LiteGraph implementation.
+ */
+ drawTitleBox(
+ ctx: CanvasRenderingContext2D,
+ {
+ scale,
+ low_quality = false,
+ title_height = LiteGraph.NODE_TITLE_HEIGHT,
+ box_size = 10
+ }: DrawTitleBoxOptions
+ ): void {
+ const size = this.renderingSize
+ const shape = this.renderingShape
+
+ if (this.onDrawTitleBox) {
+ this.onDrawTitleBox(ctx, title_height, size, scale)
+ return
+ }
+
+ if (
+ [RenderShape.ROUND, RenderShape.CIRCLE, RenderShape.CARD].includes(shape)
+ ) {
+ if (low_quality) {
+ ctx.fillStyle = 'black'
+ ctx.beginPath()
+ ctx.arc(
+ title_height * 0.5,
+ title_height * -0.5,
+ box_size * 0.5 + 1,
+ 0,
+ Math.PI * 2
+ )
+ ctx.fill()
+ }
+
+ ctx.fillStyle = this.renderingBoxColor
+ if (low_quality) {
+ ctx.fillRect(
+ title_height * 0.5 - box_size * 0.5,
+ title_height * -0.5 - box_size * 0.5,
+ box_size,
+ box_size
+ )
+ } else {
+ ctx.beginPath()
+ ctx.arc(
+ title_height * 0.5,
+ title_height * -0.5,
+ box_size * 0.5,
+ 0,
+ Math.PI * 2
+ )
+ ctx.fill()
+ }
+ } else {
+ if (low_quality) {
+ ctx.fillStyle = 'black'
+ ctx.fillRect(
+ (title_height - box_size) * 0.5 - 1,
+ (title_height + box_size) * -0.5 - 1,
+ box_size + 2,
+ box_size + 2
+ )
+ }
+ ctx.fillStyle = this.renderingBoxColor
+ ctx.fillRect(
+ (title_height - box_size) * 0.5,
+ (title_height + box_size) * -0.5,
+ box_size,
+ box_size
+ )
+ }
+ }
+
+ /**
+ * Renders the node's title text.
+ */
+ drawTitleText(
+ ctx: CanvasRenderingContext2D,
+ {
+ scale,
+ default_title_color,
+ low_quality = false,
+ title_height = LiteGraph.NODE_TITLE_HEIGHT
+ }: DrawTitleTextOptions
+ ): void {
+ const size = this.renderingSize
+ const selected = this.selected
+
+ if (this.onDrawTitleText) {
+ this.onDrawTitleText(
+ ctx,
+ title_height,
+ size,
+ scale,
+ this.titleFontStyle,
+ selected
+ )
+ return
+ }
+
+ // Don't render title text if low quality
+ if (low_quality) {
+ return
+ }
+
+ ctx.font = this.titleFontStyle
+ const rawTitle = this.getTitle() ?? `❌ ${this.type}`
+ const title = String(rawTitle) + (this.pinned ? '📌' : '')
+ if (title) {
+ if (selected) {
+ ctx.fillStyle = LiteGraph.NODE_SELECTED_TITLE_COLOR
+ } else {
+ ctx.fillStyle = this.constructor.title_text_color || default_title_color
+ }
+
+ // Calculate available width for title
+ let availableWidth = size[0] - title_height * 2 // Basic margins
+
+ // Subtract space for title buttons
+ if (this.title_buttons?.length > 0) {
+ let buttonsWidth = 0
+ const savedFont = ctx.font // Save current font
+ for (const button of this.title_buttons) {
+ if (button.visible) {
+ buttonsWidth += button.getWidth(ctx) + 2 // button width + gap
+ }
+ }
+ ctx.font = savedFont // Restore font after button measurements
+ if (buttonsWidth > 0) {
+ buttonsWidth -= 20 // Reduce by empty padding
+ availableWidth -= buttonsWidth
+ }
+ }
+
+ // Truncate title if needed
+ let displayTitle = title
+
+ if (this.collapsed) {
+ // For collapsed nodes, limit to 20 chars as before
+ displayTitle = title.substr(0, 20)
+ } else if (availableWidth > 0) {
+ // For regular nodes, truncate based on available width
+ displayTitle = truncateText(ctx, title, availableWidth)
+ }
+
+ ctx.textAlign = 'left'
+ ctx.fillText(
+ displayTitle,
+ title_height,
+ LiteGraph.NODE_TITLE_TEXT_Y - title_height
+ )
+ }
+ }
+
+ /**
+ * Attempts to gracefully bypass this node in all of its connections by reconnecting all links.
+ *
+ * Each input is checked against each output. This is done on a matching index basis, i.e. input 3 -> output 3.
+ * If there are any input links remaining,
+ * and {@link flags}.{@link INodeFlags.keepAllLinksOnBypass keepAllLinksOnBypass} is `true`,
+ * each input will check for outputs that match, and take the first one that matches
+ * `true`: Try the index matching first, then every input to every output.
+ * `false`: Only matches indexes, e.g. input 3 to output 3.
+ *
+ * If {@link flags}.{@link INodeFlags.keepAllLinksOnBypass keepAllLinksOnBypass} is `undefined`, it will fall back to
+ * the static {@link keepAllLinksOnBypass}.
+ * @returns `true` if any new links were established, otherwise `false`.
+ * @todo Decision: Change API to return array of new links instead?
+ */
+ connectInputToOutput(): boolean | undefined {
+ const { inputs, outputs, graph } = this
+ if (!inputs || !outputs) return
+ if (!graph) throw new NullGraphError()
+
+ const { _links } = graph
+ let madeAnyConnections = false
+
+ // First pass: only match exactly index-to-index
+ for (const [index, input] of inputs.entries()) {
+ if (input.link == null) continue
+
+ const output = outputs[index]
+ if (!output || !LiteGraph.isValidConnection(input.type, output.type))
+ continue
+
+ const inLink = _links.get(input.link)
+ if (!inLink) continue
+ const inNode = graph.getNodeById(inLink?.origin_id)
+ if (!inNode) continue
+
+ bypassAllLinks(output, inNode, inLink, graph)
+ }
+ // Configured to only use index-to-index matching
+ if (!(this.flags.keepAllLinksOnBypass ?? LGraphNode.keepAllLinksOnBypass))
+ return madeAnyConnections
+
+ // Second pass: match any remaining links
+ for (const input of inputs) {
+ if (input.link == null) continue
+
+ const inLink = _links.get(input.link)
+ if (!inLink) continue
+ const inNode = graph.getNodeById(inLink?.origin_id)
+ if (!inNode) continue
+
+ for (const output of outputs) {
+ if (!LiteGraph.isValidConnection(input.type, output.type)) continue
+
+ bypassAllLinks(output, inNode, inLink, graph)
+ break
+ }
+ }
+ return madeAnyConnections
+
+ function bypassAllLinks(
+ output: INodeOutputSlot,
+ inNode: LGraphNode,
+ inLink: LLink,
+ graph: LGraph
+ ) {
+ const outLinks = output.links
+ ?.map((x) => _links.get(x))
+ .filter((x) => !!x)
+ if (!outLinks?.length) return
+
+ for (const outLink of outLinks) {
+ const outNode = graph.getNodeById(outLink.target_id)
+ if (!outNode) continue
+
+ const result = inNode.connect(
+ inLink.origin_slot,
+ outNode,
+ outLink.target_slot,
+ inLink.parentId
+ )
+ madeAnyConnections ||= !!result
+ }
+ }
+ }
+
+ /**
+ * Returns `true` if the widget is visible, otherwise `false`.
+ */
+ isWidgetVisible(widget: IBaseWidget): boolean {
+ const isHidden =
+ this.collapsed || widget.hidden || (widget.advanced && !this.showAdvanced)
+ return !isHidden
+ }
+
+ updateComputedDisabled() {
+ if (!this.widgets) return
+ for (const widget of this.widgets)
+ widget.computedDisabled =
+ widget.disabled || this.getSlotFromWidget(widget)?.link != null
+ }
+
+ drawWidgets(
+ ctx: CanvasRenderingContext2D,
+ { lowQuality = false, editorAlpha = 1 }: DrawWidgetsOptions
+ ): void {
+ if (!this.widgets) return
+
+ const nodeWidth = this.size[0]
+ const { widgets } = this
+ const H = LiteGraph.NODE_WIDGET_HEIGHT
+ const showText = !lowQuality
+ ctx.save()
+ ctx.globalAlpha = editorAlpha
+
+ this.updateComputedDisabled()
+ for (const widget of widgets) {
+ if (!this.isWidgetVisible(widget)) continue
+
+ const { y } = widget
+ const outlineColour = widget.advanced
+ ? LiteGraph.WIDGET_ADVANCED_OUTLINE_COLOR
+ : LiteGraph.WIDGET_OUTLINE_COLOR
+
+ widget.last_y = y
+
+ ctx.strokeStyle = outlineColour
+ ctx.fillStyle = '#222'
+ ctx.textAlign = 'left'
+ if (widget.computedDisabled) ctx.globalAlpha *= 0.5
+ const width = widget.width || nodeWidth
+
+ if (typeof widget.draw === 'function') {
+ widget.draw(ctx, this, width, y, H, lowQuality)
+ } else {
+ toConcreteWidget(widget, this, false)?.drawWidget(ctx, {
+ width,
+ showText
+ })
+ }
+ ctx.globalAlpha = editorAlpha
+ }
+ ctx.restore()
+ }
+
+ /**
+ * When {@link LGraphNode.collapsed} is `true`, this method draws the node's collapsed slots.
+ */
+ drawCollapsedSlots(ctx: CanvasRenderingContext2D): void {
+ // Render the first connected slot only.
+ for (const slot of this.#concreteInputs) {
+ if (slot.link != null) {
+ slot.drawCollapsed(ctx)
+ break
+ }
+ }
+ for (const slot of this.#concreteOutputs) {
+ if (slot.links?.length) {
+ slot.drawCollapsed(ctx)
+ break
+ }
+ }
+ }
+
+ get slots(): (INodeInputSlot | INodeOutputSlot)[] {
+ return [...this.inputs, ...this.outputs]
+ }
+
+ #measureSlot(
+ slot: NodeInputSlot | NodeOutputSlot,
+ slotIndex: number,
+ isInput: boolean
+ ): void {
+ const pos = isInput
+ ? this.getInputPos(slotIndex)
+ : this.getOutputPos(slotIndex)
+
+ slot.boundingRect[0] = pos[0] - LiteGraph.NODE_SLOT_HEIGHT * 0.5
+ slot.boundingRect[1] = pos[1] - LiteGraph.NODE_SLOT_HEIGHT * 0.5
+ slot.boundingRect[2] = slot.isWidgetInputSlot
+ ? BaseWidget.margin
+ : LiteGraph.NODE_SLOT_HEIGHT
+ slot.boundingRect[3] = LiteGraph.NODE_SLOT_HEIGHT
+ }
+
+ #measureSlots(): ReadOnlyRect | null {
+ const slots: (NodeInputSlot | NodeOutputSlot)[] = []
+
+ for (const [slotIndex, slot] of this.#concreteInputs.entries()) {
+ // Unrecognized nodes (Nodes with error) has inputs but no widgets. Treat
+ // converted inputs as normal inputs.
+ /** Widget input slots are handled in {@link layoutWidgetInputSlots} */
+ if (this.widgets?.length && isWidgetInputSlot(slot)) continue
+
+ this.#measureSlot(slot, slotIndex, true)
+ slots.push(slot)
+ }
+ for (const [slotIndex, slot] of this.#concreteOutputs.entries()) {
+ this.#measureSlot(slot, slotIndex, false)
+ slots.push(slot)
+ }
+
+ return slots.length ? createBounds(slots, 0) : null
+ }
+
+ #getMouseOverSlot(slot: INodeSlot): INodeSlot | null {
+ const isInput = isINodeInputSlot(slot)
+ const mouseOverId = this.mouseOver?.[isInput ? 'inputId' : 'outputId'] ?? -1
+ if (mouseOverId === -1) {
+ return null
+ }
+ return isInput ? this.inputs[mouseOverId] : this.outputs[mouseOverId]
+ }
+
+ #isMouseOverSlot(slot: INodeSlot): boolean {
+ return this.#getMouseOverSlot(slot) === slot
+ }
+
+ #isMouseOverWidget(widget: IBaseWidget | undefined): boolean {
+ if (!widget) return false
+ return this.mouseOver?.overWidget === widget
+ }
+
+ /**
+ * Returns the input slot that is associated with the given widget.
+ */
+ getSlotFromWidget(
+ widget: IBaseWidget | undefined
+ ): INodeInputSlot | undefined {
+ if (widget)
+ return this.inputs.find(
+ (slot) => isWidgetInputSlot(slot) && slot.widget.name === widget.name
+ )
+ }
+
+ /**
+ * Returns the widget that is associated with the given input slot.
+ */
+ getWidgetFromSlot(slot: INodeInputSlot): IBaseWidget | undefined {
+ if (!isWidgetInputSlot(slot)) return
+ return this.widgets?.find((w) => w.name === slot.widget.name)
+ }
+
+ /**
+ * Draws the node's input and output slots.
+ */
+ drawSlots(
+ ctx: CanvasRenderingContext2D,
+ { fromSlot, colorContext, editorAlpha, lowQuality }: DrawSlotsOptions
+ ) {
+ for (const slot of [...this.#concreteInputs, ...this.#concreteOutputs]) {
+ const isValidTarget = fromSlot && slot.isValidTarget(fromSlot)
+ const isMouseOverSlot = this.#isMouseOverSlot(slot)
+
+ // change opacity of incompatible slots when dragging a connection
+ const isValid = !fromSlot || isValidTarget
+ const highlight = isValid && isMouseOverSlot
+
+ // Show slot if it's not a widget input slot
+ // or if it's a widget input slot and satisfies one of the following:
+ // - the mouse is over the widget
+ // - the slot is valid during link drop
+ // - the slot is connected
+ if (
+ isMouseOverSlot ||
+ isValidTarget ||
+ !slot.isWidgetInputSlot ||
+ this.#isMouseOverWidget(this.getWidgetFromSlot(slot)) ||
+ slot.isConnected ||
+ slot.alwaysVisible
+ ) {
+ ctx.globalAlpha = isValid ? editorAlpha : 0.4 * editorAlpha
+ slot.draw(ctx, {
+ colorContext,
+ lowQuality,
+ highlight
+ })
+ }
+ }
+ }
+
+ /**
+ * Arranges the node's widgets vertically.
+ * Sets following properties on each widget:
+ * - {@link IBaseWidget.computedHeight}
+ * - {@link IBaseWidget.y}
+ * @param widgetStartY The y-coordinate of the first widget
+ */
+ #arrangeWidgets(widgetStartY: number): void {
+ if (!this.widgets || !this.widgets.length) return
+
+ const bodyHeight = this.bodyHeight
+ const startY =
+ this.widgets_start_y ?? (this.widgets_up ? 0 : widgetStartY) + 2
+
+ let freeSpace = bodyHeight - startY
+
+ // Collect fixed height widgets first
+ let fixedWidgetHeight = 0
+ const growableWidgets: {
+ minHeight: number
+ prefHeight?: number
+ w: IBaseWidget
+ }[] = []
+
+ const visibleWidgets = this.widgets.filter((w) => !w.hidden)
+
+ for (const w of visibleWidgets) {
+ if (w.computeSize) {
+ const height = w.computeSize()[1] + 4
+ w.computedHeight = height
+ fixedWidgetHeight += height
+ } else if (w.computeLayoutSize) {
+ const { minHeight, maxHeight } = w.computeLayoutSize(this)
+ growableWidgets.push({
+ minHeight,
+ prefHeight: maxHeight,
+ w
+ })
+ } else {
+ const height = LiteGraph.NODE_WIDGET_HEIGHT + 4
+ w.computedHeight = height
+ fixedWidgetHeight += height
+ }
+ }
+
+ // Calculate remaining space for DOM widgets
+ freeSpace -= fixedWidgetHeight
+ this.freeWidgetSpace = freeSpace
+
+ // Prepare space requests for distribution
+ const spaceRequests = growableWidgets.map((d) => ({
+ minSize: d.minHeight,
+ maxSize: d.prefHeight
+ }))
+
+ // Distribute space among DOM widgets
+ const allocations = distributeSpace(Math.max(0, freeSpace), spaceRequests)
+
+ // Apply computed heights
+ for (const [i, d] of growableWidgets.entries()) {
+ d.w.computedHeight = allocations[i]
+ }
+
+ // Position widgets
+ let y = startY
+ for (const w of visibleWidgets) {
+ w.y = y
+ y += w.computedHeight ?? 0
+ }
+
+ if (!this.graph) throw new NullGraphError()
+
+ // Grow the node if necessary.
+ // Ref: https://github.com/Comfy-Org/ComfyUI_frontend/issues/2652
+ // TODO: Move the layout logic before drawing of the node shape, so we don't
+ // need to trigger extra round of rendering.
+ if (y > bodyHeight) {
+ this.setSize([this.size[0], y])
+ this.graph.setDirtyCanvas(false, true)
+ }
+ }
+
+ /**
+ * Arranges the layout of the node's widget input slots.
+ */
+ #arrangeWidgetInputSlots(): void {
+ if (!this.widgets) return
+
+ const slotByWidgetName = new Map<
+ string,
+ INodeInputSlot & { index: number }
+ >()
+
+ for (const [i, slot] of this.inputs.entries()) {
+ if (!isWidgetInputSlot(slot)) continue
+
+ slotByWidgetName.set(slot.widget.name, { ...slot, index: i })
+ }
+ if (!slotByWidgetName.size) return
+
+ // Only set custom pos if not using Vue positioning
+ // Vue positioning calculates widget slot positions dynamically
+ if (!LiteGraph.vueNodesMode) {
+ for (const widget of this.widgets) {
+ const slot = slotByWidgetName.get(widget.name)
+ if (!slot) continue
+
+ const actualSlot = this.#concreteInputs[slot.index]
+ const offset = LiteGraph.NODE_SLOT_HEIGHT * 0.5
+ actualSlot.pos = [offset, widget.y + offset]
+ this.#measureSlot(actualSlot, slot.index, true)
+ }
+ } else {
+ // For Vue positioning, just measure the slots without setting pos
+ for (const widget of this.widgets) {
+ const slot = slotByWidgetName.get(widget.name)
+ if (!slot) continue
+
+ this.#measureSlot(this.#concreteInputs[slot.index], slot.index, true)
+ }
+ }
+ }
+
+ /**
+ * @internal Sets the internal concrete slot arrays, ensuring they are instances of
+ * {@link NodeInputSlot} or {@link NodeOutputSlot}.
+ *
+ * A temporary workaround until duck-typed inputs and outputs
+ * have been removed from the ecosystem.
+ */
+ _setConcreteSlots(): void {
+ this.#concreteInputs = this.inputs.map((slot) =>
+ toClass(NodeInputSlot, slot, this)
+ )
+ this.#concreteOutputs = this.outputs.map((slot) =>
+ toClass(NodeOutputSlot, slot, this)
+ )
+ }
+
+ /**
+ * Arranges node elements in preparation for rendering (slots & widgets).
+ */
+ arrange(): void {
+ const slotsBounds = this.#measureSlots()
+ const widgetStartY = slotsBounds
+ ? slotsBounds[1] + slotsBounds[3] - this.pos[1]
+ : 0
+ this.#arrangeWidgets(widgetStartY)
+ this.#arrangeWidgetInputSlots()
+ }
+
+ /**
+ * Draws a progress bar on the node.
+ * @param ctx The canvas context to draw on
+ */
+ drawProgressBar(ctx: CanvasRenderingContext2D): void {
+ if (!this.progress) return
+
+ const originalFillStyle = ctx.fillStyle
+ ctx.fillStyle = 'green'
+ ctx.fillRect(0, 0, this.width * this.progress, 6)
+ ctx.fillStyle = originalFillStyle
+ }
+}
diff --git a/docs/hel-892/serialization-evidence/src__lib__litegraph__src__subgraph__ExecutableNodeDTO.ts b/docs/hel-892/serialization-evidence/src__lib__litegraph__src__subgraph__ExecutableNodeDTO.ts
new file mode 100644
index 00000000..9e9454a8
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__lib__litegraph__src__subgraph__ExecutableNodeDTO.ts
@@ -0,0 +1,408 @@
+import type { LGraph } from '@/lib/litegraph/src/LGraph'
+import type { LGraphNode, NodeId } from '@/lib/litegraph/src/LGraphNode'
+import { InvalidLinkError } from '@/lib/litegraph/src/infrastructure/InvalidLinkError'
+import { NullGraphError } from '@/lib/litegraph/src/infrastructure/NullGraphError'
+import { RecursionError } from '@/lib/litegraph/src/infrastructure/RecursionError'
+import { SlotIndexError } from '@/lib/litegraph/src/infrastructure/SlotIndexError'
+import type {
+ CallbackParams,
+ CallbackReturn,
+ ISlotType
+} from '@/lib/litegraph/src/interfaces'
+import { LGraphEventMode, LiteGraph } from '@/lib/litegraph/src/litegraph'
+
+import type { Subgraph } from './Subgraph'
+import type { SubgraphNode } from './SubgraphNode'
+
+export type ExecutionId = string
+
+/**
+ * Interface describing the data transfer objects used when compiling a graph for execution.
+ */
+export type ExecutableLGraphNode = Omit<
+ ExecutableNodeDTO,
+ 'graph' | 'node' | 'subgraphNode'
+>
+
+/**
+ * The end result of resolving a DTO input.
+ * When a widget value is returned, {@link widgetInfo} is present and {@link origin_slot} is `-1`.
+ */
+type ResolvedInput = {
+ /** DTO for the node that the link originates from. */
+ node: ExecutableLGraphNode
+ /** Full unique execution ID of the node that the link originates from. In the case of a widget value, this is the ID of the subgraph node. */
+ origin_id: ExecutionId
+ /** The slot index of the output on the node that the link originates from. `-1` when widget value is set. */
+ origin_slot: number
+ /** Boxed widget value (e.g. for widgets). If this box is `undefined`, then an input link is connected, and widget values from the subgraph node are ignored. */
+ widgetInfo?: { value: unknown }
+}
+
+/**
+ * Concrete implementation of {@link ExecutableLGraphNode}.
+ * @remarks This is the class that is used to create the data transfer objects for executable nodes.
+ */
+export class ExecutableNodeDTO implements ExecutableLGraphNode {
+ applyToGraph?(
+ ...args: CallbackParams
+ ): CallbackReturn
+
+ /** The graph that this node is a part of. */
+ readonly graph: LGraph | Subgraph
+
+ inputs: { linkId: number | null; name: string; type: ISlotType }[]
+
+ /** Backing field for {@link id}. */
+ #id: ExecutionId
+
+ /**
+ * The path to the actual node through subgraph instances, represented as a list of all subgraph node IDs (instances),
+ * followed by the actual original node ID within the subgraph. Each segment is separated by `:`.
+ *
+ * e.g. `1:2:3`:
+ * - `1` is the node ID of the first subgraph node in the parent workflow
+ * - `2` is the node ID of the second subgraph node in the first subgraph
+ * - `3` is the node ID of the actual node in the subgraph definition
+ */
+ get id() {
+ return this.#id
+ }
+
+ get type() {
+ return this.node.type
+ }
+
+ get title() {
+ return this.node.title
+ }
+
+ get mode() {
+ return this.node.mode
+ }
+
+ get comfyClass() {
+ return this.node.comfyClass
+ }
+
+ get isVirtualNode() {
+ return this.node.isVirtualNode
+ }
+
+ get widgets() {
+ return this.node.widgets
+ }
+
+ get subgraphId() {
+ return this.subgraphNode?.subgraph.id
+ }
+
+ constructor(
+ /** The actual node that this DTO wraps. */
+ readonly node: LGraphNode | SubgraphNode,
+ /** A list of subgraph instance node IDs from the root graph to the containing instance. @see {@link id} */
+ readonly subgraphNodePath: readonly NodeId[],
+ /** A flattened map of all DTOs in this node network. Subgraph instances have been expanded into their inner nodes. */
+ readonly nodesByExecutionId: Map,
+ /** The actual subgraph instance that contains this node, otherwise undefined. */
+ readonly subgraphNode?: SubgraphNode
+ ) {
+ if (!node.graph) throw new NullGraphError()
+
+ // Set the internal ID of the DTO
+ this.#id = [...this.subgraphNodePath, this.node.id].join(':')
+ this.graph = node.graph
+ this.inputs = this.node.inputs.map((x) => ({
+ linkId: x.link,
+ name: x.name,
+ type: x.type
+ }))
+
+ // Only create a wrapper if the node has an applyToGraph method
+ if (this.node.applyToGraph) {
+ this.applyToGraph = (...args) => this.node.applyToGraph?.(...args)
+ }
+ }
+
+ /** Returns either the DTO itself, or the DTOs of the inner nodes of the subgraph. */
+ getInnerNodes(): ExecutableLGraphNode[] {
+ return this.node.isSubgraphNode()
+ ? this.node.getInnerNodes(this.nodesByExecutionId, this.subgraphNodePath)
+ : [this]
+ }
+
+ /**
+ * Resolves the executable node & link IDs for a given input slot.
+ * @param slot The slot index of the input.
+ * @param visited Leave empty unless overriding this method.
+ * A set of unique IDs, used to guard against infinite recursion.
+ * If overriding, ensure that the set is passed on all recursive calls.
+ * @returns The node and the origin ID / slot index of the output.
+ */
+ resolveInput(
+ slot: number,
+ visited = new Set(),
+ type?: ISlotType
+ ): ResolvedInput | undefined {
+ const uniqueId = `${this.subgraphNode?.subgraph.id}:${this.node.id}[I]${slot}`
+ if (visited.has(uniqueId)) {
+ const nodeInfo = `${this.node.id}${this.node.title ? ` (${this.node.title})` : ''}`
+ const pathInfo =
+ this.subgraphNodePath.length > 0
+ ? ` at path ${this.subgraphNodePath.join(':')}`
+ : ''
+ throw new RecursionError(
+ `Circular reference detected while resolving input ${slot} of node ${nodeInfo}${pathInfo}. ` +
+ `This creates an infinite loop in link resolution. UniqueID: [${uniqueId}]`
+ )
+ }
+ visited.add(uniqueId)
+
+ const input = this.inputs.at(slot)
+ if (!input)
+ throw new SlotIndexError(
+ `No input found for flattened id [${this.id}] slot [${slot}]`
+ )
+
+ // Nothing connected
+ if (input.linkId == null) return
+
+ const link = this.graph.getLink(input.linkId)
+ if (!link)
+ throw new InvalidLinkError(
+ `No link found in parent graph for id [${this.id}] slot [${slot}] ${input.name}`
+ )
+
+ const { subgraphNode } = this
+
+ // Link goes up and out of this subgraph
+ if (subgraphNode && link.originIsIoNode) {
+ const subgraphNodeInput = subgraphNode.inputs.at(link.origin_slot)
+ if (!subgraphNodeInput)
+ throw new SlotIndexError(
+ `No input found for slot [${link.origin_slot}] ${input.name}`
+ )
+
+ // Nothing connected
+ const linkId = subgraphNodeInput.link
+ if (linkId == null) {
+ const widget = subgraphNode.getWidgetFromSlot(subgraphNodeInput)
+ if (!widget) return
+
+ // Special case: SubgraphNode widget.
+ return {
+ node: this,
+ origin_id: this.id,
+ origin_slot: -1,
+ widgetInfo: { value: widget.value }
+ }
+ }
+
+ const outerLink = subgraphNode.graph.getLink(linkId)
+ if (!outerLink)
+ throw new InvalidLinkError(
+ `No outer link found for slot [${link.origin_slot}] ${input.name}`
+ )
+
+ const subgraphNodeExecutionId = this.subgraphNodePath.join(':')
+ const subgraphNodeDto = this.nodesByExecutionId.get(
+ subgraphNodeExecutionId
+ )
+ if (!subgraphNodeDto)
+ throw new Error(
+ `No subgraph node DTO found for id [${subgraphNodeExecutionId}]`
+ )
+
+ return subgraphNodeDto.resolveInput(outerLink.target_slot, visited)
+ }
+
+ // Not part of a subgraph; use the original link
+ const outputNode = this.graph.getNodeById(link.origin_id)
+ if (!outputNode)
+ throw new InvalidLinkError(
+ `No input node found for id [${this.id}] slot [${slot}] ${input.name}`
+ )
+
+ const outputNodeExecutionId = [
+ ...this.subgraphNodePath,
+ outputNode.id
+ ].join(':')
+ const outputNodeDto = this.nodesByExecutionId.get(outputNodeExecutionId)
+ if (!outputNodeDto)
+ throw new Error(
+ `No output node DTO found for id [${outputNodeExecutionId}]`
+ )
+
+ return outputNodeDto.resolveOutput(
+ link.origin_slot,
+ type ?? input.type,
+ visited
+ )
+ }
+
+ /**
+ * Determines whether this output is a valid endpoint for a link (non-virtual, non-bypass).
+ * @param slot The slot index of the output.
+ * @param type The type of the input
+ * @param visited A set of unique IDs to guard against infinite recursion. See {@link resolveInput}.
+ * @returns The node and the origin ID / slot index of the output.
+ */
+ resolveOutput(
+ slot: number,
+ type: ISlotType,
+ visited: Set
+ ): ResolvedInput | undefined {
+ const uniqueId = `${this.subgraphNode?.subgraph.id}:${this.node.id}[O]${slot}`
+ if (visited.has(uniqueId)) {
+ const nodeInfo = `${this.node.id}${this.node.title ? ` (${this.node.title})` : ''}`
+ const pathInfo =
+ this.subgraphNodePath.length > 0
+ ? ` at path ${this.subgraphNodePath.join(':')}`
+ : ''
+ throw new RecursionError(
+ `Circular reference detected while resolving output ${slot} of node ${nodeInfo}${pathInfo}. ` +
+ `This creates an infinite loop in link resolution. UniqueID: [${uniqueId}]`
+ )
+ }
+ visited.add(uniqueId)
+
+ // Upstreamed: Bypass nodes are bypassed using the first input with matching type
+ if (this.mode === LGraphEventMode.BYPASS) {
+ // Bypass nodes by finding first input with matching type
+ const matchingIndex = this.#getBypassSlotIndex(slot, type)
+
+ // No input types match - bypass not possible
+ if (matchingIndex === -1) {
+ console.warn(
+ `[ExecutableNodeDTO.resolveOutput] No input types match type [${type}] for id [${this.id}] slot [${slot}]`,
+ this
+ )
+ return
+ }
+
+ return this.resolveInput(matchingIndex, visited)
+ }
+
+ const { node } = this
+ if (node.isSubgraphNode())
+ return this.#resolveSubgraphOutput(slot, type, visited)
+
+ if (node.isVirtualNode) {
+ const virtualLink = this.node.getInputLink(slot)
+ if (virtualLink) {
+ const { inputNode } = virtualLink.resolve(this.graph)
+ if (!inputNode)
+ throw new InvalidLinkError(
+ `Virtual node failed to resolve parent [${this.id}] slot [${slot}]`
+ )
+
+ const inputNodeExecutionId = [
+ ...this.subgraphNodePath,
+ inputNode.id
+ ].join(':')
+ const inputNodeDto = this.nodesByExecutionId.get(inputNodeExecutionId)
+ if (!inputNodeDto)
+ throw new Error(`No input node DTO found for id [${inputNode.id}]`)
+
+ return inputNodeDto.resolveInput(virtualLink.target_slot, visited, type)
+ }
+
+ // Virtual nodes without a matching input should be discarded.
+ return
+ }
+
+ return {
+ node: this,
+ origin_id: this.id,
+ origin_slot: slot
+ }
+ }
+
+ /**
+ * Finds the index of the input slot on this node that matches the given output {@link slot} index.
+ * Used when bypassing nodes.
+ * @param slot The output slot index on this node
+ * @param type The type of the final target input (so type list matches are accurate)
+ * @returns The index of the input slot on this node, otherwise `-1`.
+ */
+ #getBypassSlotIndex(slot: number, type: ISlotType) {
+ const { inputs } = this
+ const oppositeInput = inputs[slot]
+ const outputType = this.node.outputs[slot].type
+
+ // Any type short circuit - match slot ID, fallback to first slot
+ if (type === '*' || type === '') {
+ return inputs.length > slot ? slot : 0
+ }
+
+ // Prefer input with the same slot ID
+ if (
+ oppositeInput &&
+ LiteGraph.isValidConnection(oppositeInput.type, outputType) &&
+ LiteGraph.isValidConnection(oppositeInput.type, type)
+ ) {
+ return slot
+ }
+
+ // Preserve legacy behaviour; use exact match first.
+ const exactMatch = inputs.findIndex((input) => input.type === type)
+ if (exactMatch !== -1) return exactMatch
+
+ // Find first matching slot - prefer exact type
+ return inputs.findIndex(
+ (input) =>
+ LiteGraph.isValidConnection(input.type, outputType) &&
+ LiteGraph.isValidConnection(input.type, type)
+ )
+ }
+
+ /**
+ * Resolves the link inside a subgraph node, from the subgraph IO node to the node inside the subgraph.
+ * @param slot The slot index of the output on the subgraph node.
+ * @param visited A set of unique IDs to guard against infinite recursion. See {@link resolveInput}.
+ * @returns A DTO for the node, and the origin ID / slot index of the output.
+ */
+ #resolveSubgraphOutput(
+ slot: number,
+ type: ISlotType,
+ visited: Set
+ ): ResolvedInput | undefined {
+ const { node } = this
+ const output = node.outputs.at(slot)
+
+ if (!output)
+ throw new SlotIndexError(
+ `No output found for flattened id [${this.id}] slot [${slot}]`
+ )
+ if (!node.isSubgraphNode())
+ throw new TypeError(`Node is not a subgraph node: ${node.id}`)
+
+ // Link inside the subgraph
+ const innerResolved = node.resolveSubgraphOutputLink(slot)
+ if (!innerResolved) return
+
+ const innerNode = innerResolved.outputNode
+ if (!innerNode)
+ throw new Error(
+ `No output node found for id [${this.id}] slot [${slot}] ${output.name}`
+ )
+
+ // Recurse into the subgraph
+ const innerNodeExecutionId = [
+ ...this.subgraphNodePath,
+ node.id,
+ innerNode.id
+ ].join(':')
+ const innerNodeDto = this.nodesByExecutionId.get(innerNodeExecutionId)
+ if (!innerNodeDto)
+ throw new Error(
+ `No inner node DTO found for id [${innerNodeExecutionId}]`
+ )
+
+ return innerNodeDto.resolveOutput(
+ innerResolved.link.origin_slot,
+ type,
+ visited
+ )
+ }
+}
diff --git a/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useBooleanWidget.ts b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useBooleanWidget.ts
new file mode 100644
index 00000000..242afe54
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useBooleanWidget.ts
@@ -0,0 +1,31 @@
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import { isBooleanInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { InputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { ComfyWidgetConstructorV2 } from '@/scripts/widgets'
+
+export const useBooleanWidget = () => {
+ const widgetConstructor: ComfyWidgetConstructorV2 = (
+ node: LGraphNode,
+ inputSpec: InputSpec
+ ) => {
+ if (!isBooleanInputSpec(inputSpec)) {
+ throw new Error(`Invalid input data: ${inputSpec}`)
+ }
+
+ const defaultVal = inputSpec.default ?? false
+ const options = {
+ on: inputSpec.label_on,
+ off: inputSpec.label_off
+ }
+
+ return node.addWidget(
+ 'toggle',
+ inputSpec.name,
+ defaultVal,
+ () => {},
+ options
+ )
+ }
+
+ return widgetConstructor
+}
diff --git a/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useComboWidget.ts b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useComboWidget.ts
new file mode 100644
index 00000000..770d5b9d
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useComboWidget.ts
@@ -0,0 +1,305 @@
+import { ref } from 'vue'
+
+import MultiSelectWidget from '@/components/graph/widgets/MultiSelectWidget.vue'
+import { t } from '@/i18n'
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import { isAssetWidget, isComboWidget } from '@/lib/litegraph/src/litegraph'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+import { useAssetBrowserDialog } from '@/platform/assets/composables/useAssetBrowserDialog'
+import {
+ assetFilenameSchema,
+ assetItemSchema
+} from '@/platform/assets/schemas/assetSchema'
+import { assetService } from '@/platform/assets/services/assetService'
+import { isCloud } from '@/platform/distribution/types'
+import { useSettingStore } from '@/platform/settings/settingStore'
+import type {
+ ComboInputSpec,
+ InputSpec
+} from '@/schemas/nodeDef/nodeDefSchemaV2'
+import { isComboInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import { transformInputSpecV2ToV1 } from '@/schemas/nodeDef/migration'
+import { ComponentWidgetImpl, addWidget } from '@/scripts/domWidget'
+import type { BaseDOMWidget } from '@/scripts/domWidget'
+import type { ComfyWidgetConstructorV2 } from '@/scripts/widgets'
+import { addValueControlWidgets } from '@/scripts/widgets'
+import { useAssetsStore } from '@/stores/assetsStore'
+import { getMediaTypeFromFilename } from '@/utils/formatUtil'
+
+import { useRemoteWidget } from './useRemoteWidget'
+
+const getDefaultValue = (inputSpec: ComboInputSpec) => {
+ if (inputSpec.default) return inputSpec.default
+ if (inputSpec.options?.length) return inputSpec.options[0]
+ if (inputSpec.remote) return 'Loading...'
+ return undefined
+}
+
+// Map node types to expected media types
+const NODE_MEDIA_TYPE_MAP: Record = {
+ LoadImage: 'image',
+ LoadVideo: 'video',
+ LoadAudio: 'audio'
+}
+
+// Map node types to placeholder i18n keys
+const NODE_PLACEHOLDER_MAP: Record = {
+ LoadImage: 'widgets.uploadSelect.placeholderImage',
+ LoadVideo: 'widgets.uploadSelect.placeholderVideo',
+ LoadAudio: 'widgets.uploadSelect.placeholderAudio'
+}
+
+const addMultiSelectWidget = (
+ node: LGraphNode,
+ inputSpec: ComboInputSpec
+): IBaseWidget => {
+ const widgetValue = ref([])
+ const widget = new ComponentWidgetImpl({
+ node,
+ name: inputSpec.name,
+ component: MultiSelectWidget,
+ inputSpec,
+ options: {
+ getValue: () => widgetValue.value,
+ setValue: (value: string[]) => {
+ widgetValue.value = value
+ }
+ }
+ })
+ addWidget(node, widget as BaseDOMWidget)
+ // TODO: Add remote support to multi-select widget
+ // https://github.com/Comfy-Org/ComfyUI_frontend/issues/3003
+ if (inputSpec.control_after_generate) {
+ widget.linkedWidgets = addValueControlWidgets(
+ node,
+ widget,
+ 'fixed',
+ undefined,
+ transformInputSpecV2ToV1(inputSpec)
+ )
+ }
+
+ return widget
+}
+
+const createAssetBrowserWidget = (
+ node: LGraphNode,
+ inputSpec: ComboInputSpec,
+ defaultValue: string | undefined
+): IBaseWidget => {
+ const currentValue = defaultValue
+ const displayLabel = currentValue ?? t('widgets.selectModel')
+ const assetBrowserDialog = useAssetBrowserDialog()
+
+ const widget = node.addWidget(
+ 'asset',
+ inputSpec.name,
+ displayLabel,
+ async function (this: IBaseWidget) {
+ if (!isAssetWidget(widget)) {
+ throw new Error(`Expected asset widget but received ${widget.type}`)
+ }
+ await assetBrowserDialog.show({
+ nodeType: node.comfyClass || '',
+ inputName: inputSpec.name,
+ currentValue: widget.value,
+ onAssetSelected: (asset) => {
+ const validatedAsset = assetItemSchema.safeParse(asset)
+
+ if (!validatedAsset.success) {
+ console.error(
+ 'Invalid asset item:',
+ validatedAsset.error.errors,
+ 'Received:',
+ asset
+ )
+ return
+ }
+
+ const filename = validatedAsset.data.user_metadata?.filename
+ const validatedFilename = assetFilenameSchema.safeParse(filename)
+
+ if (!validatedFilename.success) {
+ console.error(
+ 'Invalid asset filename:',
+ validatedFilename.error.errors,
+ 'for asset:',
+ validatedAsset.data.id
+ )
+ return
+ }
+
+ const oldValue = widget.value
+ this.value = validatedFilename.data
+ node.onWidgetChanged?.(
+ widget.name,
+ validatedFilename.data,
+ oldValue,
+ widget
+ )
+ }
+ })
+ }
+ )
+
+ return widget
+}
+
+const createInputMappingWidget = (
+ node: LGraphNode,
+ inputSpec: ComboInputSpec,
+ defaultValue: string | undefined
+): IBaseWidget => {
+ const assetsStore = useAssetsStore()
+
+ const widget = node.addWidget(
+ 'combo',
+ inputSpec.name,
+ defaultValue ?? '',
+ () => {},
+ {
+ values: [],
+ getOptionLabel: (value?: string | null) => {
+ if (!value) {
+ const placeholderKey =
+ NODE_PLACEHOLDER_MAP[node.comfyClass ?? ''] ??
+ 'widgets.uploadSelect.placeholder'
+ return t(placeholderKey)
+ }
+ return assetsStore.getInputName(value)
+ }
+ }
+ )
+
+ if (assetsStore.inputAssets.length === 0 && !assetsStore.inputLoading) {
+ void assetsStore.updateInputs().then(() => {
+ // edge for users using nodes with 0 prior inputs
+ // force canvas refresh the first time they add an asset
+ // so they see filenames instead of hashes.
+ node.setDirtyCanvas(true, false)
+ })
+ }
+
+ const origOptions = widget.options
+ widget.options = new Proxy(origOptions, {
+ get(target, prop) {
+ if (prop !== 'values') {
+ return target[prop as keyof typeof target]
+ }
+ return assetsStore.inputAssets
+ .filter(
+ (asset) =>
+ getMediaTypeFromFilename(asset.name) ===
+ NODE_MEDIA_TYPE_MAP[node.comfyClass ?? '']
+ )
+ .map((asset) => asset.asset_hash)
+ .filter((hash): hash is string => !!hash)
+ }
+ })
+
+ if (inputSpec.control_after_generate) {
+ if (!isComboWidget(widget)) {
+ throw new Error(`Expected combo widget but received ${widget.type}`)
+ }
+ widget.linkedWidgets = addValueControlWidgets(
+ node,
+ widget,
+ undefined,
+ undefined,
+ transformInputSpecV2ToV1(inputSpec)
+ )
+ }
+
+ return widget
+}
+
+const addComboWidget = (
+ node: LGraphNode,
+ inputSpec: ComboInputSpec
+): IBaseWidget => {
+ const defaultValue = getDefaultValue(inputSpec)
+
+ if (isCloud) {
+ const settingStore = useSettingStore()
+ const isUsingAssetAPI = settingStore.get('Comfy.Assets.UseAssetAPI')
+ const isEligible = assetService.isAssetBrowserEligible(
+ node.comfyClass,
+ inputSpec.name
+ )
+
+ if (isUsingAssetAPI && isEligible) {
+ return createAssetBrowserWidget(node, inputSpec, defaultValue)
+ }
+
+ if (NODE_MEDIA_TYPE_MAP[node.comfyClass ?? '']) {
+ return createInputMappingWidget(node, inputSpec, defaultValue)
+ }
+ }
+
+ // Standard combo widget
+ const widget = node.addWidget(
+ 'combo',
+ inputSpec.name,
+ defaultValue,
+ () => {},
+ {
+ values: inputSpec.options ?? []
+ }
+ )
+
+ if (inputSpec.remote) {
+ if (!isComboWidget(widget)) {
+ throw new Error(`Expected combo widget but received ${widget.type}`)
+ }
+
+ const remoteWidget = useRemoteWidget({
+ remoteConfig: inputSpec.remote,
+ defaultValue,
+ node,
+ widget
+ })
+ if (inputSpec.remote.refresh_button) remoteWidget.addRefreshButton()
+
+ const origOptions = widget.options
+ widget.options = new Proxy(origOptions, {
+ get(target, prop) {
+ // Assertion: Proxy handler passthrough
+ return prop !== 'values'
+ ? target[prop as keyof typeof target]
+ : remoteWidget.getValue()
+ }
+ })
+ }
+
+ if (inputSpec.control_after_generate) {
+ if (!isComboWidget(widget)) {
+ throw new Error(`Expected combo widget but received ${widget.type}`)
+ }
+
+ widget.linkedWidgets = addValueControlWidgets(
+ node,
+ widget,
+ undefined,
+ undefined,
+ transformInputSpecV2ToV1(inputSpec)
+ )
+ }
+
+ return widget
+}
+
+export const useComboWidget = () => {
+ const widgetConstructor: ComfyWidgetConstructorV2 = (
+ node: LGraphNode,
+ inputSpec: InputSpec
+ ) => {
+ if (!isComboInputSpec(inputSpec)) {
+ throw new Error(`Invalid input data: ${inputSpec}`)
+ }
+ return inputSpec.multi_select
+ ? addMultiSelectWidget(node, inputSpec)
+ : addComboWidget(node, inputSpec)
+ }
+
+ return widgetConstructor
+}
diff --git a/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useFloatWidget.ts b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useFloatWidget.ts
new file mode 100644
index 00000000..6595f301
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useFloatWidget.ts
@@ -0,0 +1,95 @@
+import { clamp } from 'es-toolkit/compat'
+
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { INumericWidget } from '@/lib/litegraph/src/types/widgets'
+import { useSettingStore } from '@/platform/settings/settingStore'
+import { isFloatInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { InputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { ComfyWidgetConstructorV2 } from '@/scripts/widgets'
+import { addValueControlWidget } from '@/scripts/widgets'
+import { transformInputSpecV2ToV1 } from '@/schemas/nodeDef/migration'
+
+function onFloatValueChange(this: INumericWidget, v: number) {
+ const round = this.options.round
+ if (round) {
+ const precision =
+ this.options.precision ?? Math.max(0, -Math.floor(Math.log10(round)))
+ const rounded = Math.round(v / round) * round
+ this.value = clamp(
+ Number(rounded.toFixed(precision)),
+ this.options.min ?? -Infinity,
+ this.options.max ?? Infinity
+ )
+ } else {
+ this.value = v
+ }
+}
+
+export const _for_testing = {
+ onFloatValueChange
+}
+
+export const useFloatWidget = () => {
+ const widgetConstructor: ComfyWidgetConstructorV2 = (
+ node: LGraphNode,
+ inputSpec: InputSpec
+ ) => {
+ if (!isFloatInputSpec(inputSpec)) {
+ throw new Error(`Invalid input data: ${inputSpec}`)
+ }
+
+ const settingStore = useSettingStore()
+ const sliderEnabled = !settingStore.get('Comfy.DisableSliders')
+
+ const display_type = inputSpec.display
+ const widgetType =
+ sliderEnabled && display_type == 'slider'
+ ? 'slider'
+ : display_type == 'knob'
+ ? 'knob'
+ : 'number'
+
+ const step = inputSpec.step ?? 0.5
+ const precision =
+ settingStore.get('Comfy.FloatRoundingPrecision') ||
+ Math.max(0, -Math.floor(Math.log10(step)))
+ const enableRounding = !settingStore.get('Comfy.DisableFloatRounding')
+
+ /** Assertion {@link inputSpec.default} */
+ const defaultValue = (inputSpec.default as number | undefined) ?? 0
+ const widget = node.addWidget(
+ widgetType,
+ inputSpec.name,
+ defaultValue,
+ onFloatValueChange,
+ {
+ min: inputSpec.min ?? 0,
+ max: inputSpec.max ?? 2048,
+ round:
+ enableRounding && precision && !inputSpec.round
+ ? Math.pow(10, -precision)
+ : (inputSpec.round as number),
+ /** @deprecated Use step2 instead. The 10x value is a legacy implementation. */
+ step: step * 10.0,
+ step2: step,
+ precision
+ }
+ )
+
+ if (inputSpec.control_after_generate) {
+ const controlWidget = addValueControlWidget(
+ node,
+ widget,
+ 'fixed',
+ undefined,
+ undefined,
+ transformInputSpecV2ToV1(inputSpec)
+ )
+ widget.linkedWidgets = [controlWidget]
+ }
+
+ return widget
+ }
+
+ return widgetConstructor
+}
diff --git a/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useImageUploadWidget.ts b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useImageUploadWidget.ts
new file mode 100644
index 00000000..78f9d0c9
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useImageUploadWidget.ts
@@ -0,0 +1,126 @@
+import { useNodeImage, useNodeVideo } from '@/composables/node/useNodeImage'
+import { useNodeImageUpload } from '@/composables/node/useNodeImageUpload'
+import { useValueTransform } from '@/composables/useValueTransform'
+import { t } from '@/i18n'
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { IComboWidget } from '@/lib/litegraph/src/types/widgets'
+import type { ResultItem, ResultItemType } from '@/schemas/apiSchema'
+import type { InputSpec } from '@/schemas/nodeDefSchema'
+import type { ComfyWidgetConstructor } from '@/scripts/widgets'
+import { useNodeOutputStore } from '@/stores/imagePreviewStore'
+import { isImageUploadInput } from '@/types/nodeDefAugmentation'
+import { createAnnotatedPath } from '@/utils/createAnnotatedPath'
+import { addToComboValues } from '@/utils/litegraphUtil'
+
+const ACCEPTED_IMAGE_TYPES = 'image/png,image/jpeg,image/webp'
+const ACCEPTED_VIDEO_TYPES = 'video/webm,video/mp4'
+
+type InternalFile = string | ResultItem
+type InternalValue = InternalFile | InternalFile[]
+type ExposedValue = string | string[]
+
+const isImageFile = (file: File) => file.type.startsWith('image/')
+const isVideoFile = (file: File) => file.type.startsWith('video/')
+
+const findFileComboWidget = (node: LGraphNode, inputName: string) =>
+ node.widgets!.find((w) => w.name === inputName) as IComboWidget & {
+ value: ExposedValue
+ }
+
+export const useImageUploadWidget = () => {
+ const widgetConstructor: ComfyWidgetConstructor = (
+ node: LGraphNode,
+ inputName: string,
+ inputData: InputSpec
+ ) => {
+ if (!isImageUploadInput(inputData)) {
+ throw new Error(
+ 'Image upload widget requires imageInputName augmentation'
+ )
+ }
+
+ const inputOptions = inputData[1]
+ const { imageInputName, allow_batch, image_folder = 'input' } = inputOptions
+ const folder: ResultItemType | undefined = image_folder
+ const nodeOutputStore = useNodeOutputStore()
+
+ const isAnimated = !!inputOptions.animated_image_upload
+ const isVideo = !!inputOptions.video_upload
+ const accept = isVideo ? ACCEPTED_VIDEO_TYPES : ACCEPTED_IMAGE_TYPES
+ const { showPreview } = isVideo ? useNodeVideo(node) : useNodeImage(node)
+
+ const fileFilter = isVideo ? isVideoFile : isImageFile
+ const fileComboWidget = findFileComboWidget(node, imageInputName)
+ const initialFile = `${fileComboWidget.value}`
+ const formatPath = (value: InternalFile) =>
+ createAnnotatedPath(value, { rootFolder: image_folder })
+
+ const transform = (internalValue: InternalValue): ExposedValue => {
+ if (!internalValue) return initialFile
+ if (Array.isArray(internalValue))
+ return allow_batch
+ ? internalValue.map(formatPath)
+ : formatPath(internalValue[0])
+ return formatPath(internalValue)
+ }
+
+ Object.defineProperty(
+ fileComboWidget,
+ 'value',
+ useValueTransform(transform, initialFile)
+ )
+
+ // Setup file upload handling
+ const { openFileSelection } = useNodeImageUpload(node, {
+ allow_batch,
+ fileFilter,
+ accept,
+ folder,
+ onUploadComplete: (output) => {
+ output.forEach((path) => addToComboValues(fileComboWidget, path))
+
+ // Create a NEW array to ensure Vue reactivity detects the change
+ const newValue = allow_batch ? [...output] : output[0]
+
+ // @ts-expect-error litegraph combo value type does not support arrays yet
+ fileComboWidget.value = newValue
+ fileComboWidget.callback?.(newValue)
+ }
+ })
+
+ // Create the button widget for selecting the files
+ const uploadWidget = node.addWidget(
+ 'button',
+ inputName,
+ 'image',
+ () => openFileSelection(),
+ {
+ serialize: false,
+ canvasOnly: true
+ }
+ )
+ uploadWidget.label = t('g.choose_file_to_upload')
+
+ // Add our own callback to the combo widget to render an image when it changes
+ fileComboWidget.callback = function () {
+ nodeOutputStore.setNodeOutputs(node, fileComboWidget.value, {
+ isAnimated
+ })
+ node.graph?.setDirtyCanvas(true)
+ }
+
+ // On load if we have a value then render the image
+ // The value isn't set immediately so we need to wait a moment
+ // No change callbacks seem to be fired on initial setting of the value
+ requestAnimationFrame(() => {
+ nodeOutputStore.setNodeOutputs(node, fileComboWidget.value, {
+ isAnimated
+ })
+ showPreview({ block: false })
+ })
+
+ return { widget: uploadWidget }
+ }
+
+ return widgetConstructor
+}
diff --git a/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useIntWidget.ts b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useIntWidget.ts
new file mode 100644
index 00000000..0c257c15
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__renderer__extensions__vueNodes__widgets__composables__useIntWidget.ts
@@ -0,0 +1,89 @@
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { INumericWidget } from '@/lib/litegraph/src/types/widgets'
+import { useSettingStore } from '@/platform/settings/settingStore'
+import type { InputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import { isIntInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { ComfyWidgetConstructorV2 } from '@/scripts/widgets'
+import { addValueControlWidget } from '@/scripts/widgets'
+import { transformInputSpecV2ToV1 } from '@/schemas/nodeDef/migration'
+
+function onValueChange(this: INumericWidget, v: number) {
+ // For integers, always round to the nearest step
+ // step === 0 is invalid, assign 1 if options.step is 0
+ const step = this.options.step2 || 1
+
+ if (step === 1) {
+ // Simple case: round to nearest integer
+ this.value = Math.round(v)
+ } else {
+ // Round to nearest multiple of step
+ // First, determine if min value creates an offset
+ const min = this.options.min ?? 0
+ const offset = min % step
+
+ // Round to nearest step, accounting for offset
+ this.value = Math.round((v - offset) / step) * step + offset
+ }
+}
+
+export const _for_testing = {
+ onValueChange
+}
+
+export const useIntWidget = () => {
+ const widgetConstructor: ComfyWidgetConstructorV2 = (
+ node: LGraphNode,
+ inputSpec: InputSpec
+ ) => {
+ if (!isIntInputSpec(inputSpec)) {
+ throw new Error(`Invalid input data: ${inputSpec}`)
+ }
+
+ const settingStore = useSettingStore()
+ const sliderEnabled = !settingStore.get('Comfy.DisableSliders')
+ const display_type = inputSpec.display
+ const widgetType =
+ sliderEnabled && display_type == 'slider'
+ ? 'slider'
+ : display_type == 'knob'
+ ? 'knob'
+ : 'number'
+
+ const step = inputSpec.step ?? 1
+ /** Assertion {@link inputSpec.default} */
+ const defaultValue = (inputSpec.default as number | undefined) ?? 0
+ const widget = node.addWidget(
+ widgetType,
+ inputSpec.name,
+ defaultValue,
+ onValueChange,
+ {
+ min: inputSpec.min ?? 0,
+ max: inputSpec.max ?? 2048,
+ /** @deprecated Use step2 instead. The 10x value is a legacy implementation. */
+ step: step * 10,
+ step2: step,
+ precision: 0
+ }
+ )
+
+ const controlAfterGenerate =
+ inputSpec.control_after_generate ??
+ ['seed', 'noise_seed'].includes(inputSpec.name)
+
+ if (controlAfterGenerate) {
+ const controlWidget = addValueControlWidget(
+ node,
+ widget,
+ 'randomize',
+ undefined,
+ undefined,
+ transformInputSpecV2ToV1(inputSpec)
+ )
+ widget.linkedWidgets = [controlWidget]
+ }
+
+ return widget
+ }
+ return widgetConstructor
+}
diff --git a/docs/hel-892/serialization-evidence/src__scripts__widgets.ts b/docs/hel-892/serialization-evidence/src__scripts__widgets.ts
new file mode 100644
index 00000000..50dabe01
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__scripts__widgets.ts
@@ -0,0 +1,308 @@
+import { t } from '@/i18n'
+import { type LGraphNode, isComboWidget } from '@/lib/litegraph/src/litegraph'
+import type {
+ IBaseWidget,
+ IComboWidget,
+ IStringWidget
+} from '@/lib/litegraph/src/types/widgets'
+import { useSettingStore } from '@/platform/settings/settingStore'
+import { dynamicWidgets } from '@/core/graph/widgets/dynamicWidgets'
+import { useBooleanWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useBooleanWidget'
+import { useChartWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useChartWidget'
+import { useColorWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useColorWidget'
+import { useComboWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useComboWidget'
+import { useFloatWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useFloatWidget'
+import { useGalleriaWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useGalleriaWidget'
+import { useImageCompareWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useImageCompareWidget'
+import { useImageUploadWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useImageUploadWidget'
+import { useIntWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useIntWidget'
+import { useMarkdownWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useMarkdownWidget'
+import { useStringWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useStringWidget'
+import { useTextareaWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useTextareaWidget'
+import { transformInputSpecV1ToV2 } from '@/schemas/nodeDef/migration'
+import type { InputSpec as InputSpecV2 } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { InputSpec } from '@/schemas/nodeDefSchema'
+
+import type { ComfyApp } from './app'
+import './domWidget'
+import './errorNodeWidgets'
+
+export type ComfyWidgetConstructorV2 = (
+ node: LGraphNode,
+ inputSpec: InputSpecV2
+) => IBaseWidget
+
+export type ComfyWidgetConstructor = (
+ node: LGraphNode,
+ inputName: string,
+ inputData: InputSpec,
+ app: ComfyApp,
+ widgetName?: string
+) => { widget: IBaseWidget; minWidth?: number; minHeight?: number }
+
+/**
+ * Transforms a V2 widget constructor to a V1 widget constructor.
+ * @param widgetConstructorV2 The V2 widget constructor to transform.
+ * @returns The transformed V1 widget constructor.
+ */
+const transformWidgetConstructorV2ToV1 = (
+ widgetConstructorV2: ComfyWidgetConstructorV2
+): ComfyWidgetConstructor => {
+ return (node, inputName, inputData) => {
+ const inputSpec = transformInputSpecV1ToV2(inputData, {
+ name: inputName
+ })
+ const widget = widgetConstructorV2(node, inputSpec)
+ return {
+ widget,
+ minWidth: widget.options.minNodeSize?.[0],
+ minHeight: widget.options.minNodeSize?.[1]
+ }
+ }
+}
+
+function controlValueRunBefore() {
+ return useSettingStore().get('Comfy.WidgetControlMode') === 'before'
+}
+
+export function updateControlWidgetLabel(widget: IBaseWidget) {
+ if (controlValueRunBefore()) {
+ widget.label = t('g.control_before_generate')
+ } else {
+ widget.label = t('g.control_after_generate')
+ }
+}
+
+export const IS_CONTROL_WIDGET = Symbol()
+const HAS_EXECUTED = Symbol()
+
+export function addValueControlWidget(
+ node: LGraphNode,
+ targetWidget: IBaseWidget,
+ defaultValue?: string,
+ _values?: unknown,
+ widgetName?: string,
+ inputData?: InputSpec
+): IComboWidget {
+ let name = inputData?.[1]?.control_after_generate
+ if (typeof name !== 'string') {
+ name = widgetName
+ }
+ const widgets = addValueControlWidgets(
+ node,
+ targetWidget,
+ defaultValue ?? 'randomize',
+ {
+ addFilterList: false,
+ controlAfterGenerateName: name
+ },
+ inputData
+ )
+ return widgets[0]
+}
+
+export function addValueControlWidgets(
+ node: LGraphNode,
+ targetWidget: IBaseWidget,
+ defaultValue?: string,
+ options?: Record,
+ inputData?: InputSpec
+): [IComboWidget, ...IStringWidget[]] {
+ if (!defaultValue) defaultValue = 'randomize'
+ if (!options) options = {}
+
+ const getName = (defaultName: string, optionName: string) => {
+ let name = defaultName
+ if (options[optionName]) {
+ name = options[optionName]
+ } else if (typeof inputData?.[1]?.[defaultName] === 'string') {
+ name = inputData?.[1]?.[defaultName]
+ } else if (inputData?.[1]?.control_prefix) {
+ name = inputData?.[1]?.control_prefix + ' ' + name
+ }
+ return name
+ }
+
+ const valueControl = node.addWidget(
+ 'combo',
+ getName('control_after_generate', 'controlAfterGenerateName'),
+ defaultValue,
+ function () {},
+ {
+ values: ['fixed', 'increment', 'decrement', 'randomize'],
+ serialize: false, // Don't include this in prompt.
+ canvasOnly: true
+ }
+ ) as IComboWidget
+
+ valueControl.tooltip =
+ 'Allows the linked widget to be changed automatically, for example randomizing the noise seed.'
+ valueControl[IS_CONTROL_WIDGET] = true
+ updateControlWidgetLabel(valueControl)
+ const widgets: [IComboWidget, ...IStringWidget[]] = [valueControl]
+
+ const isCombo = isComboWidget(targetWidget)
+ let comboFilter: IStringWidget
+ if (isCombo && valueControl.options.values) {
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ valueControl.options.values.push('increment-wrap')
+ }
+ if (isCombo && options.addFilterList !== false) {
+ comboFilter = node.addWidget(
+ 'string',
+ getName('control_filter_list', 'controlFilterListName'),
+ '',
+ function () {},
+ {
+ serialize: false // Don't include this in prompt.
+ }
+ ) as IStringWidget
+ updateControlWidgetLabel(comboFilter)
+ comboFilter.tooltip =
+ "Allows for filtering the list of values when changing the value via the control generate mode. Allows for RegEx matches in the format /abc/ to only filter to values containing 'abc'."
+
+ widgets.push(comboFilter)
+ }
+
+ const applyWidgetControl = () => {
+ var v = valueControl.value
+
+ if (isCombo && v !== 'fixed') {
+ let values = targetWidget.options.values ?? []
+ const filter = comboFilter?.value
+ if (filter) {
+ let check
+ if (filter.startsWith('/') && filter.endsWith('/')) {
+ try {
+ const regex = new RegExp(filter.substring(1, filter.length - 1))
+ check = (item: string) => regex.test(item)
+ } catch (error) {
+ console.error(
+ 'Error constructing RegExp filter for node ' + node.id,
+ filter,
+ error
+ )
+ }
+ }
+ if (!check) {
+ const lower = filter.toLocaleLowerCase()
+ check = (item: string) => item.toLocaleLowerCase().includes(lower)
+ }
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ values = values.filter((item: string) => check(item))
+ if (!values.length && targetWidget.options.values?.length) {
+ console.warn(
+ 'Filter for node ' + node.id + ' has filtered out all items',
+ filter
+ )
+ }
+ }
+ // @ts-expect-error targetWidget.value can be number or string
+ let current_index = values.indexOf(targetWidget.value)
+ let current_length = values.length
+
+ switch (v) {
+ case 'increment':
+ current_index += 1
+ break
+ case 'increment-wrap':
+ current_index += 1
+ if (current_index >= current_length) {
+ current_index = 0
+ }
+ break
+ case 'decrement':
+ current_index -= 1
+ break
+ case 'randomize':
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ current_index = Math.floor(Math.random() * current_length)
+ break
+ default:
+ break
+ }
+ current_index = Math.max(0, current_index)
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ current_index = Math.min(current_length - 1, current_index)
+ if (current_index >= 0) {
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ let value = values[current_index]
+ targetWidget.value = value
+ targetWidget.callback?.(value)
+ }
+ } else {
+ //number
+ let { min = 0, max = 1, step2 = 1 } = targetWidget.options
+ // limit to something that javascript can handle
+ max = Math.min(1125899906842624, max)
+ min = Math.max(-1125899906842624, min)
+ let range = (max - min) / step2
+
+ //adjust values based on valueControl Behaviour
+ switch (v) {
+ case 'fixed':
+ break
+ case 'increment':
+ // @ts-expect-error targetWidget.value can be number or string
+ targetWidget.value += step2
+ break
+ case 'decrement':
+ // @ts-expect-error targetWidget.value can be number or string
+ targetWidget.value -= step2
+ break
+ case 'randomize':
+ targetWidget.value = Math.floor(Math.random() * range) * step2 + min
+ break
+ default:
+ break
+ }
+ /*check if values are over or under their respective
+ * ranges and set them to min or max.*/
+ // @ts-expect-error targetWidget.value can be number or string
+ if (targetWidget.value < min) targetWidget.value = min
+ // @ts-expect-error targetWidget.value can be number or string
+ if (targetWidget.value > max) targetWidget.value = max
+ targetWidget.callback?.(targetWidget.value)
+ }
+ }
+
+ valueControl.beforeQueued = () => {
+ if (controlValueRunBefore()) {
+ // Don't run on first execution
+ if (valueControl[HAS_EXECUTED]) {
+ applyWidgetControl()
+ }
+ }
+ valueControl[HAS_EXECUTED] = true
+ }
+
+ valueControl.afterQueued = () => {
+ if (!controlValueRunBefore()) {
+ applyWidgetControl()
+ }
+ }
+
+ return widgets
+}
+
+export const ComfyWidgets = {
+ INT: transformWidgetConstructorV2ToV1(useIntWidget()),
+ FLOAT: transformWidgetConstructorV2ToV1(useFloatWidget()),
+ BOOLEAN: transformWidgetConstructorV2ToV1(useBooleanWidget()),
+ STRING: transformWidgetConstructorV2ToV1(useStringWidget()),
+ MARKDOWN: transformWidgetConstructorV2ToV1(useMarkdownWidget()),
+ COMBO: transformWidgetConstructorV2ToV1(useComboWidget()),
+ IMAGEUPLOAD: useImageUploadWidget(),
+ COLOR: transformWidgetConstructorV2ToV1(useColorWidget()),
+ IMAGECOMPARE: transformWidgetConstructorV2ToV1(useImageCompareWidget()),
+ CHART: transformWidgetConstructorV2ToV1(useChartWidget()),
+ GALLERIA: transformWidgetConstructorV2ToV1(useGalleriaWidget()),
+ TEXTAREA: transformWidgetConstructorV2ToV1(useTextareaWidget()),
+ ...dynamicWidgets
+} as const
+
+export function isValidWidgetType(
+ key: unknown
+): key is keyof typeof ComfyWidgets {
+ return ComfyWidgets[key as keyof typeof ComfyWidgets] !== undefined
+}
diff --git a/docs/hel-892/serialization-evidence/src__services__litegraphService.ts b/docs/hel-892/serialization-evidence/src__services__litegraphService.ts
new file mode 100644
index 00000000..e7e35458
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__services__litegraphService.ts
@@ -0,0 +1,913 @@
+import _ from 'es-toolkit/compat'
+
+import { downloadFile } from '@/base/common/downloadUtil'
+import { useSelectedLiteGraphItems } from '@/composables/canvas/useSelectedLiteGraphItems'
+import { useSubgraphOperations } from '@/composables/graph/useSubgraphOperations'
+import { useNodeAnimatedImage } from '@/composables/node/useNodeAnimatedImage'
+import { useNodeCanvasImagePreview } from '@/composables/node/useNodeCanvasImagePreview'
+import { useNodeImage, useNodeVideo } from '@/composables/node/useNodeImage'
+import { addWidgetPromotionOptions } from '@/core/graph/subgraph/proxyWidgetUtils'
+import { applyDynamicInputs } from '@/core/graph/widgets/dynamicWidgets'
+import { st, t } from '@/i18n'
+import {
+ LGraphCanvas,
+ LGraphEventMode,
+ LGraphNode,
+ LiteGraph,
+ RenderShape,
+ SubgraphNode,
+ createBounds
+} from '@/lib/litegraph/src/litegraph'
+import type {
+ IContextMenuValue,
+ Point,
+ Subgraph
+} from '@/lib/litegraph/src/litegraph'
+import type {
+ ExportedSubgraphInstance,
+ ISerialisableNodeInput,
+ ISerialisableNodeOutput,
+ ISerialisedNode
+} from '@/lib/litegraph/src/types/serialisation'
+import { useSettingStore } from '@/platform/settings/settingStore'
+import { useToastStore } from '@/platform/updates/common/toastStore'
+import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
+import type { NodeId } from '@/platform/workflow/validation/schemas/workflowSchema'
+import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
+import { useDialogService } from '@/services/dialogService'
+import { transformInputSpecV2ToV1 } from '@/schemas/nodeDef/migration'
+import type {
+ ComfyNodeDef as ComfyNodeDefV2,
+ InputSpec,
+ OutputSpec
+} from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { ComfyNodeDef as ComfyNodeDefV1 } from '@/schemas/nodeDefSchema'
+import { ComfyApp, app } from '@/scripts/app'
+import { isComponentWidget, isDOMWidget } from '@/scripts/domWidget'
+import { $el } from '@/scripts/ui'
+import { useDomWidgetStore } from '@/stores/domWidgetStore'
+import { useExecutionStore } from '@/stores/executionStore'
+import { useNodeOutputStore } from '@/stores/imagePreviewStore'
+import { ComfyNodeDefImpl } from '@/stores/nodeDefStore'
+import { useSubgraphStore } from '@/stores/subgraphStore'
+import { useRightSidePanelStore } from '@/stores/workspace/rightSidePanelStore'
+import { useWidgetStore } from '@/stores/widgetStore'
+import { normalizeI18nKey } from '@/utils/formatUtil'
+import {
+ isImageNode,
+ isVideoNode,
+ migrateWidgetsValues
+} from '@/utils/litegraphUtil'
+import { getOrderedInputSpecs } from '@/workbench/utils/nodeDefOrderingUtil'
+
+import { useExtensionService } from './extensionService'
+import { useMaskEditor } from '@/composables/maskeditor/useMaskEditor'
+
+export interface HasInitialMinSize {
+ _initialMinSize: { width: number; height: number }
+}
+
+export const CONFIG = Symbol()
+export const GET_CONFIG = Symbol()
+
+/**
+ * Service that augments litegraph with ComfyUI specific functionality.
+ */
+export const useLitegraphService = () => {
+ const extensionService = useExtensionService()
+ const toastStore = useToastStore()
+ const widgetStore = useWidgetStore()
+ const canvasStore = useCanvasStore()
+ const { toggleSelectedNodesMode } = useSelectedLiteGraphItems()
+
+ /**
+ * @internal The key for the node definition in the i18n file.
+ */
+ function nodeKey(node: LGraphNode): string {
+ return `nodeDefs.${normalizeI18nKey(node.constructor.nodeData!.name)}`
+ }
+ /**
+ * @internal Add input sockets to the node. (No widget)
+ */
+ function addInputSocket(node: LGraphNode, inputSpec: InputSpec) {
+ const inputName = inputSpec.name
+ const nameKey = `${nodeKey(node)}.inputs.${normalizeI18nKey(inputName)}.name`
+ const widgetConstructor = widgetStore.widgets.get(
+ inputSpec.widgetType ?? inputSpec.type
+ )
+ if (
+ (widgetConstructor && !inputSpec.forceInput) ||
+ applyDynamicInputs(node, inputSpec)
+ )
+ return
+
+ const input = node.addInput(inputName, inputSpec.type, {
+ shape: inputSpec.isOptional ? RenderShape.HollowCircle : undefined,
+ localized_name: st(nameKey, inputName)
+ })
+ input.label ??= inputSpec.display_name
+ }
+ /**
+ * @internal Setup stroke styles for the node under various conditions.
+ */
+ function setupStrokeStyles(node: LGraphNode) {
+ node.strokeStyles['running'] = function (this: LGraphNode) {
+ const nodeId = String(this.id)
+ const nodeLocatorId = useWorkflowStore().nodeIdToNodeLocatorId(nodeId)
+ const state =
+ useExecutionStore().nodeLocationProgressStates[nodeLocatorId]?.state
+ if (state === 'running') {
+ return { color: '#0f0' }
+ }
+ }
+ node.strokeStyles['dragOver'] = function (this: LGraphNode) {
+ if (app.dragOverNode?.id == this.id) {
+ return { color: 'dodgerblue' }
+ }
+ }
+ node.strokeStyles['executionError'] = function (this: LGraphNode) {
+ if (app.lastExecutionError?.node_id == this.id) {
+ return { color: '#f0f', lineWidth: 2 }
+ }
+ }
+ }
+
+ /**
+ * Utility function. Implemented for use with dynamic widgets
+ */
+ function addNodeInput(node: LGraphNode, inputSpec: InputSpec) {
+ addInputSocket(node, inputSpec)
+ addInputWidget(node, inputSpec)
+ }
+
+ /**
+ * @internal Add a widget to the node. For both primitive types and custom widgets
+ * (unless `socketless`), an input socket is also added.
+ */
+ function addInputWidget(node: LGraphNode, inputSpec: InputSpec) {
+ const widgetInputSpec = { ...inputSpec }
+ if (inputSpec.widgetType) {
+ widgetInputSpec.type = inputSpec.widgetType
+ }
+ const inputName = inputSpec.name
+ const nameKey = `${nodeKey(node)}.inputs.${normalizeI18nKey(inputName)}.name`
+ const widgetConstructor = widgetStore.widgets.get(widgetInputSpec.type)
+ if (!widgetConstructor || inputSpec.forceInput) return
+
+ const {
+ widget,
+ minWidth = 1,
+ minHeight = 1
+ } = widgetConstructor(
+ node,
+ inputName,
+ transformInputSpecV2ToV1(widgetInputSpec),
+ app
+ ) ?? {}
+
+ if (widget) {
+ widget.label = st(
+ nameKey,
+ widget.label ?? widgetInputSpec.display_name ?? inputName
+ )
+ widget.options ??= {}
+ Object.assign(widget.options, {
+ advanced: inputSpec.advanced,
+ hidden: inputSpec.hidden
+ })
+ }
+
+ if (!widget?.options?.socketless) {
+ const inputSpecV1 = transformInputSpecV2ToV1(widgetInputSpec)
+ node.addInput(inputName, inputSpec.type, {
+ shape: inputSpec.isOptional ? RenderShape.HollowCircle : undefined,
+ localized_name: st(nameKey, inputName),
+ widget: { name: inputName, [GET_CONFIG]: () => inputSpecV1 }
+ })
+ }
+ const castedNode = node as LGraphNode & HasInitialMinSize
+ castedNode._initialMinSize.width = Math.max(
+ castedNode._initialMinSize.width,
+ minWidth
+ )
+ castedNode._initialMinSize.height = Math.max(
+ castedNode._initialMinSize.height,
+ minHeight
+ )
+ }
+
+ /**
+ * @internal Add inputs to the node.
+ */
+ function addInputs(node: LGraphNode, inputs: Record) {
+ // Use input_order if available to ensure consistent widget ordering
+ //@ts-expect-error was ComfyNode.nodeData as ComfyNodeDefImpl
+ const nodeDefImpl = node.constructor.nodeData as ComfyNodeDefImpl
+ const orderedInputSpecs = getOrderedInputSpecs(nodeDefImpl, inputs)
+
+ // Create sockets and widgets in the determined order
+ for (const inputSpec of orderedInputSpecs) addInputSocket(node, inputSpec)
+ for (const inputSpec of orderedInputSpecs) addInputWidget(node, inputSpec)
+ }
+
+ /**
+ * @internal Add outputs to the node.
+ */
+ function addOutputs(node: LGraphNode, outputs: OutputSpec[]) {
+ for (const output of outputs) {
+ const { name, is_list } = output
+ // TODO: Fix the typing at the node spec level
+ const type = output.type === 'COMFY_MATCHTYPE_V3' ? '*' : output.type
+ const shapeOptions = is_list ? { shape: LiteGraph.GRID_SHAPE } : {}
+ const nameKey = `${nodeKey(node)}.outputs.${output.index}.name`
+ const typeKey = `dataTypes.${normalizeI18nKey(type)}`
+ const outputOptions = {
+ ...shapeOptions,
+ // If the output name is different from the output type, use the output name.
+ // e.g.
+ // - type ("INT"); name ("Positive") => translate name
+ // - type ("FLOAT"); name ("FLOAT") => translate type
+ localized_name: type !== name ? st(nameKey, name) : st(typeKey, name)
+ }
+ node.addOutput(name, type, outputOptions)
+ }
+ }
+
+ /**
+ * @internal Set the initial size of the node.
+ */
+ function setInitialSize(node: LGraphNode) {
+ const s = node.computeSize()
+ // Expand the width a little to fit widget values on screen.
+ const pad =
+ node.widgets?.length &&
+ !useSettingStore().get('LiteGraph.Node.DefaultPadding')
+ const castedNode = node as LGraphNode & HasInitialMinSize
+ s[0] = Math.max(castedNode._initialMinSize.width, s[0] + (pad ? 60 : 0))
+ s[1] = Math.max(castedNode._initialMinSize.height, s[1])
+ node.setSize(s)
+ }
+
+ function registerSubgraphNodeDef(
+ nodeDefV1: ComfyNodeDefV1,
+ subgraph: Subgraph,
+ instanceData: ExportedSubgraphInstance
+ ) {
+ const node = class ComfyNode
+ extends SubgraphNode
+ implements HasInitialMinSize
+ {
+ static comfyClass: string
+ static override title: string
+ static override category: string
+ static nodeData: ComfyNodeDefV1 & ComfyNodeDefV2
+
+ _initialMinSize = { width: 1, height: 1 }
+
+ constructor() {
+ super(app.rootGraph, subgraph, instanceData)
+
+ // Set up event listener for promoted widget registration
+ subgraph.events.addEventListener('widget-promoted', (event) => {
+ const { widget } = event.detail
+ // Only handle DOM widgets
+ if (!isDOMWidget(widget) && !isComponentWidget(widget)) return
+
+ const domWidgetStore = useDomWidgetStore()
+ if (!domWidgetStore.widgetStates.has(widget.id)) {
+ domWidgetStore.registerWidget(widget)
+ // Set initial visibility based on whether the widget's node is in the current graph
+ const widgetState = domWidgetStore.widgetStates.get(widget.id)
+ if (widgetState) {
+ const currentGraph = canvasStore.getCanvas().graph
+ widgetState.visible =
+ currentGraph?.nodes.includes(widget.node) ?? false
+ }
+ }
+ })
+
+ // Set up event listener for promoted widget removal
+ subgraph.events.addEventListener('widget-demoted', (event) => {
+ const { widget } = event.detail
+ // Only handle DOM widgets
+ if (!isDOMWidget(widget) && !isComponentWidget(widget)) return
+
+ const domWidgetStore = useDomWidgetStore()
+ if (domWidgetStore.widgetStates.has(widget.id)) {
+ domWidgetStore.unregisterWidget(widget.id)
+ }
+ })
+
+ setupStrokeStyles(this)
+ addInputs(this, ComfyNode.nodeData.inputs)
+ addOutputs(this, ComfyNode.nodeData.outputs)
+ setInitialSize(this)
+ this.serialize_widgets = true
+ void extensionService.invokeExtensionsAsync('nodeCreated', this)
+ }
+
+ /**
+ * Configure the node from a serialised node. Keep 'name', 'type', 'shape',
+ * and 'localized_name' information from the original node definition.
+ */
+ override configure(data: ISerialisedNode): void {
+ const RESERVED_KEYS = ['name', 'type', 'shape', 'localized_name']
+
+ // Note: input name is unique in a node definition, so we can lookup
+ // input by name.
+ const inputByName = new Map(
+ data.inputs?.map((input) => [input.name, input]) ?? []
+ )
+ // Inputs defined by the node definition.
+ const definedInputNames = new Set(
+ this.inputs.map((input) => input.name)
+ )
+ const definedInputs = this.inputs.map((input) => {
+ const inputData = inputByName.get(input.name)
+ return inputData
+ ? {
+ ...inputData,
+ // Whether the input has associated widget follows the
+ // original node definition.
+ ..._.pick(input, RESERVED_KEYS.concat('widget'))
+ }
+ : input
+ })
+ // Extra inputs that potentially dynamically added by custom js logic.
+ const extraInputs = data.inputs?.filter(
+ (input) => !definedInputNames.has(input.name)
+ )
+ data.inputs = [...definedInputs, ...(extraInputs ?? [])]
+
+ // Note: output name is not unique, so we cannot lookup output by name.
+ // Use index instead.
+ data.outputs = _.zip(this.outputs, data.outputs).map(
+ ([output, outputData]) => {
+ // If there are extra outputs in the serialised node, use them directly.
+ // There are currently custom nodes that dynamically add outputs via
+ // js logic.
+ if (!output) return outputData as ISerialisableNodeOutput
+
+ return outputData
+ ? {
+ ...outputData,
+ ..._.pick(output, RESERVED_KEYS)
+ }
+ : output
+ }
+ )
+
+ data.widgets_values = migrateWidgetsValues(
+ ComfyNode.nodeData.inputs,
+ this.widgets ?? [],
+ data.widgets_values ?? []
+ )
+
+ super.configure(data)
+ }
+ }
+
+ addNodeContextMenuHandler(node)
+ addDrawBackgroundHandler(node)
+ addNodeKeyHandler(node)
+ // Note: Some extensions expects node.comfyClass to be set in
+ // `beforeRegisterNodeDef`.
+ node.prototype.comfyClass = nodeDefV1.name
+ node.comfyClass = nodeDefV1.name
+
+ const nodeDef = new ComfyNodeDefImpl(nodeDefV1)
+ node.nodeData = nodeDef
+ LiteGraph.registerNodeType(subgraph.id, node)
+ // Note: Do not following assignments before `LiteGraph.registerNodeType`
+ // because `registerNodeType` will overwrite the assignments.
+ node.category = nodeDef.category
+ node.skip_list = true
+ node.title = nodeDef.display_name || nodeDef.name
+ }
+
+ async function registerNodeDef(nodeId: string, nodeDefV1: ComfyNodeDefV1) {
+ const node = class ComfyNode
+ extends LGraphNode
+ implements HasInitialMinSize
+ {
+ static comfyClass: string
+ static override title: string
+ static override category: string
+ static nodeData: ComfyNodeDefV1 & ComfyNodeDefV2
+
+ _initialMinSize = { width: 1, height: 1 }
+
+ constructor(title: string) {
+ super(title)
+ setupStrokeStyles(this)
+ addInputs(this, ComfyNode.nodeData.inputs)
+ addOutputs(this, ComfyNode.nodeData.outputs)
+ setInitialSize(this)
+ this.serialize_widgets = true
+
+ // Mark API Nodes yellow by default to distinguish with other nodes.
+ if (ComfyNode.nodeData.api_node) {
+ this.color = LGraphCanvas.node_colors.yellow.color
+ this.bgcolor = LGraphCanvas.node_colors.yellow.bgcolor
+ }
+
+ void extensionService.invokeExtensionsAsync('nodeCreated', this)
+ }
+
+ /**
+ * Configure the node from a serialised node. Keep 'name', 'type', 'shape',
+ * and 'localized_name' information from the original node definition.
+ */
+ override configure(data: ISerialisedNode): void {
+ const RESERVED_KEYS = ['name', 'type', 'shape', 'localized_name']
+
+ // Note: input name is unique in a node definition, so we can lookup
+ // input by name.
+ const inputByName = new Map(
+ data.inputs?.map((input) => [input.name, input]) ?? []
+ )
+ // Inputs defined by the node definition.
+ const definedInputNames = new Set(
+ this.inputs.map((input) => input.name)
+ )
+ const definedInputs = this.inputs.map((input) => {
+ const inputData = inputByName.get(input.name)
+ return inputData
+ ? {
+ ...inputData,
+ // Whether the input has associated widget follows the
+ // original node definition.
+ ..._.pick(input, RESERVED_KEYS.concat('widget'))
+ }
+ : input
+ })
+ // Extra inputs that potentially dynamically added by custom js logic.
+ const extraInputs = data.inputs?.filter(
+ (input) => !definedInputNames.has(input.name)
+ )
+ data.inputs = [...definedInputs, ...(extraInputs ?? [])]
+
+ // Note: output name is not unique, so we cannot lookup output by name.
+ // Use index instead.
+ data.outputs = _.zip(this.outputs, data.outputs).map(
+ ([output, outputData]) => {
+ // If there are extra outputs in the serialised node, use them directly.
+ // There are currently custom nodes that dynamically add outputs via
+ // js logic.
+ if (!output) return outputData as ISerialisableNodeOutput
+
+ return outputData
+ ? {
+ ...outputData,
+ ..._.pick(output, RESERVED_KEYS)
+ }
+ : output
+ }
+ )
+
+ data.widgets_values = migrateWidgetsValues(
+ ComfyNode.nodeData.inputs,
+ this.widgets ?? [],
+ data.widgets_values ?? []
+ )
+
+ super.configure(data)
+ }
+ }
+
+ addNodeContextMenuHandler(node)
+ addDrawBackgroundHandler(node)
+ addNodeKeyHandler(node)
+ // Note: Some extensions expects node.comfyClass to be set in
+ // `beforeRegisterNodeDef`.
+ node.prototype.comfyClass = nodeDefV1.name
+ node.comfyClass = nodeDefV1.name
+ await extensionService.invokeExtensionsAsync(
+ 'beforeRegisterNodeDef',
+ node,
+ nodeDefV1 // Receives V1 NodeDef, and potentially make modifications to it
+ )
+
+ const nodeDef = new ComfyNodeDefImpl(nodeDefV1)
+ node.nodeData = nodeDef
+ LiteGraph.registerNodeType(nodeId, node)
+ // Note: Do not following assignments before `LiteGraph.registerNodeType`
+ // because `registerNodeType` will overwrite the assignments.
+ node.category = nodeDef.category
+ node.title = nodeDef.display_name || nodeDef.name
+ }
+
+ /**
+ * Adds special context menu handling for nodes
+ * e.g. this adds Open Image functionality for nodes that show images
+ * @param {*} node The node to add the menu handler
+ */
+ function addNodeContextMenuHandler(node: typeof LGraphNode) {
+ function getCopyImageOption(img: HTMLImageElement): IContextMenuValue[] {
+ if (typeof window.ClipboardItem === 'undefined') return []
+ return [
+ {
+ content: 'Copy Image',
+ callback: async () => {
+ const url = new URL(img.src)
+ url.searchParams.delete('preview')
+
+ // @ts-expect-error fixme ts strict error
+ const writeImage = async (blob) => {
+ await navigator.clipboard.write([
+ new ClipboardItem({
+ [blob.type]: blob
+ })
+ ])
+ }
+
+ try {
+ const data = await fetch(url)
+ const blob = await data.blob()
+ try {
+ await writeImage(blob)
+ } catch (error) {
+ // Chrome seems to only support PNG on write, convert and try again
+ if (blob.type !== 'image/png') {
+ const canvas = $el('canvas', {
+ width: img.naturalWidth,
+ height: img.naturalHeight
+ }) as HTMLCanvasElement
+ const ctx = canvas.getContext('2d')
+ // @ts-expect-error fixme ts strict error
+ let image
+ if (typeof window.createImageBitmap === 'undefined') {
+ image = new Image()
+ const p = new Promise((resolve, reject) => {
+ // @ts-expect-error fixme ts strict error
+ image.onload = resolve
+ // @ts-expect-error fixme ts strict error
+ image.onerror = reject
+ }).finally(() => {
+ // @ts-expect-error fixme ts strict error
+ URL.revokeObjectURL(image.src)
+ })
+ image.src = URL.createObjectURL(blob)
+ await p
+ } else {
+ image = await createImageBitmap(blob)
+ }
+ try {
+ // @ts-expect-error fixme ts strict error
+ ctx.drawImage(image, 0, 0)
+ canvas.toBlob(writeImage, 'image/png')
+ } finally {
+ // @ts-expect-error fixme ts strict error
+ if (typeof image.close === 'function') {
+ // @ts-expect-error fixme ts strict error
+ image.close()
+ }
+ }
+
+ return
+ }
+ throw error
+ }
+ } catch (error) {
+ toastStore.addAlert(
+ t('toastMessages.errorCopyImage', {
+ // @ts-expect-error fixme ts strict error
+ error: error.message ?? error
+ })
+ )
+ }
+ }
+ }
+ ]
+ }
+
+ node.prototype.getExtraMenuOptions = function (canvas, options) {
+ if (this.imgs) {
+ // If this node has images then we add an open in new tab item
+ let img
+ if (this.imageIndex != null) {
+ // An image is selected so select that
+ img = this.imgs[this.imageIndex]
+ } else if (this.overIndex != null) {
+ // No image is selected but one is hovered
+ img = this.imgs[this.overIndex]
+ }
+ if (img) {
+ options.unshift(
+ {
+ content: 'Open Image',
+ callback: () => {
+ const url = new URL(img.src)
+ url.searchParams.delete('preview')
+ window.open(url, '_blank')
+ }
+ },
+ ...getCopyImageOption(img),
+ {
+ content: 'Save Image',
+ callback: () => {
+ const url = new URL(img.src)
+ url.searchParams.delete('preview')
+ const filename = new URLSearchParams(url.search).get('filename')
+ downloadFile(url.toString(), filename ?? undefined)
+ }
+ }
+ )
+ }
+ }
+
+ options.push({
+ content: 'Bypass',
+ callback: () => {
+ toggleSelectedNodesMode(LGraphEventMode.BYPASS)
+ canvas.setDirty(true, true)
+ }
+ })
+
+ // prevent conflict of clipspace content
+ if (!ComfyApp.clipspace_return_node) {
+ options.push({
+ content: 'Copy (Clipspace)',
+ callback: () => {
+ ComfyApp.copyToClipspace(this)
+ }
+ })
+
+ if (ComfyApp.clipspace != null) {
+ options.push({
+ content: 'Paste (Clipspace)',
+ callback: () => {
+ ComfyApp.pasteFromClipspace(this)
+ }
+ })
+ }
+
+ if (isImageNode(this)) {
+ options.push({
+ content: 'Open in MaskEditor | Image Canvas',
+ callback: () => {
+ useMaskEditor().openMaskEditor(this)
+ }
+ })
+ }
+ }
+ if (this instanceof SubgraphNode) {
+ options.unshift(
+ {
+ content: 'Edit Subgraph Widgets',
+ callback: () => {
+ useRightSidePanelStore().openPanel('subgraph')
+ }
+ },
+ {
+ content: 'Unpack Subgraph',
+ callback: () => {
+ const { unpackSubgraph } = useSubgraphOperations()
+ unpackSubgraph()
+ }
+ }
+ )
+ }
+ const [x, y] = canvas.graph_mouse
+ const overWidget = this.getWidgetOnPos(x, y, true)
+ if (overWidget) {
+ const input = this.inputs.find(
+ (inp) => inp.widget?.name === overWidget.name
+ )
+ if (input)
+ options.unshift({
+ content: `${t('contextMenu.RenameWidget')}: ${overWidget.label ?? overWidget.name}`,
+ callback: async () => {
+ const newLabel = await useDialogService().prompt({
+ title: t('g.rename'),
+ message: t('g.enterNewName') + ':',
+ defaultValue: overWidget.label,
+ placeholder: overWidget.name
+ })
+ if (newLabel === null) return
+ overWidget.label = newLabel || undefined
+ input.label = newLabel || undefined
+ useCanvasStore().canvas?.setDirty(true)
+ }
+ })
+ if (this.graph && !this.graph.isRootGraph) {
+ addWidgetPromotionOptions(options, overWidget, this)
+ }
+ }
+ return []
+ }
+ }
+ function updatePreviews(node: LGraphNode, callback?: () => void) {
+ try {
+ unsafeUpdatePreviews.call(node, callback)
+ } catch (error) {
+ console.error('Error drawing node background', error)
+ }
+ }
+ function unsafeUpdatePreviews(this: LGraphNode, callback?: () => void) {
+ if (this.flags.collapsed) return
+
+ const nodeOutputStore = useNodeOutputStore()
+ const { showAnimatedPreview, removeAnimatedPreview } =
+ useNodeAnimatedImage()
+ const { showCanvasImagePreview, removeCanvasImagePreview } =
+ useNodeCanvasImagePreview()
+
+ const output = nodeOutputStore.getNodeOutputs(this)
+ const preview = nodeOutputStore.getNodePreviews(this)
+
+ const isNewOutput = output && this.images !== output.images
+ const isNewPreview = preview && this.preview !== preview
+
+ if (isNewPreview) this.preview = preview
+ if (isNewOutput) this.images = output.images
+
+ if (isNewOutput || isNewPreview) {
+ this.animatedImages = output?.animated?.find(Boolean)
+
+ const isAnimatedWebp =
+ this.animatedImages &&
+ output?.images?.some((img) => img.filename?.includes('webp'))
+ const isAnimatedPng =
+ this.animatedImages &&
+ output?.images?.some((img) => img.filename?.includes('png'))
+ const isVideo =
+ (this.animatedImages && !isAnimatedWebp && !isAnimatedPng) ||
+ isVideoNode(this)
+ if (isVideo) {
+ useNodeVideo(this, callback).showPreview()
+ } else {
+ useNodeImage(this, callback).showPreview()
+ }
+ }
+
+ // Nothing to do
+ if (!this.imgs?.length) return
+
+ if (this.animatedImages) {
+ removeCanvasImagePreview(this)
+ showAnimatedPreview(this)
+ } else {
+ removeAnimatedPreview(this)
+ showCanvasImagePreview(this)
+ }
+ }
+
+ /**
+ * Adds Custom drawing logic for nodes
+ * e.g. Draws images and handles thumbnail navigation on nodes that output images
+ * @param {*} node The node to add the draw handler
+ */
+ function addDrawBackgroundHandler(node: typeof LGraphNode) {
+ /**
+ * @deprecated No longer needed as we use {@link useImagePreviewWidget}
+ */
+ node.prototype.setSizeForImage = function (this: LGraphNode) {
+ console.warn(
+ 'node.setSizeForImage is deprecated. Now it has no effect. Please remove the call to it.'
+ )
+ }
+ node.prototype.onDrawBackground = function () {
+ updatePreviews(this)
+ }
+ }
+
+ function addNodeKeyHandler(node: typeof LGraphNode) {
+ const origNodeOnKeyDown = node.prototype.onKeyDown
+
+ node.prototype.onKeyDown = function (e) {
+ // @ts-expect-error fixme ts strict error
+ if (origNodeOnKeyDown && origNodeOnKeyDown.apply(this, e) === false) {
+ return false
+ }
+
+ if (this.flags.collapsed || !this.imgs || this.imageIndex === null) {
+ return
+ }
+
+ let handled = false
+
+ if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+ if (e.key === 'ArrowLeft') {
+ // @ts-expect-error fixme ts strict error
+ this.imageIndex -= 1
+ } else if (e.key === 'ArrowRight') {
+ // @ts-expect-error fixme ts strict error
+ this.imageIndex += 1
+ }
+ // @ts-expect-error fixme ts strict error
+ this.imageIndex %= this.imgs.length
+
+ // @ts-expect-error fixme ts strict error
+ if (this.imageIndex < 0) {
+ // @ts-expect-error fixme ts strict error
+ this.imageIndex = this.imgs.length + this.imageIndex
+ }
+ handled = true
+ } else if (e.key === 'Escape') {
+ this.imageIndex = null
+ handled = true
+ }
+
+ if (handled === true) {
+ e.preventDefault()
+ e.stopImmediatePropagation()
+ return false
+ }
+ }
+ }
+
+ function addNodeOnGraph(
+ nodeDef: ComfyNodeDefV1 | ComfyNodeDefV2,
+ options: Record = {}
+ ): LGraphNode {
+ options.pos ??= getCanvasCenter()
+
+ if (nodeDef.name.startsWith(useSubgraphStore().typePrefix)) {
+ const canvas = canvasStore.getCanvas()
+ const bp = useSubgraphStore().getBlueprint(nodeDef.name)
+ const items: object = {
+ nodes: bp.nodes,
+ subgraphs: bp.definitions?.subgraphs
+ }
+ const results = canvas._deserializeItems(items, {
+ position: options.pos
+ })
+ if (!results) throw new Error('Failed to add subgraph blueprint')
+ const node = results.nodes.values().next().value
+ if (!node)
+ throw new Error(
+ 'Subgraph blueprint was added, but failed to resolve a subgraph Node'
+ )
+ return node
+ }
+
+ const node = LiteGraph.createNode(
+ nodeDef.name,
+ nodeDef.display_name,
+ options
+ )
+
+ const graph = useWorkflowStore().activeSubgraph ?? app.graph
+
+ // @ts-expect-error fixme ts strict error
+ graph.add(node)
+ // @ts-expect-error fixme ts strict error
+ return node
+ }
+
+ function getCanvasCenter(): Point {
+ const dpi = Math.max(window.devicePixelRatio ?? 1, 1)
+ const [x, y, w, h] = app.canvas.ds.visible_area
+ return [x + w / dpi / 2, y + h / dpi / 2]
+ }
+
+ function goToNode(nodeId: NodeId) {
+ const graphNode = app.canvas.graph?.getNodeById(nodeId)
+ if (!graphNode) return
+ app.canvas.animateToBounds(graphNode.boundingRect)
+ }
+
+ function ensureBounds(nodes: LGraphNode[]) {
+ for (const node of nodes) {
+ if (!node.boundingRect.every((i) => i === 0)) continue
+ node.updateArea()
+ }
+ }
+
+ /**
+ * Resets the canvas view to the default
+ */
+ function resetView() {
+ const canvas = canvasStore.canvas
+ if (!canvas) return
+
+ canvas.ds.scale = 1
+ canvas.ds.offset = [0, 0]
+ canvas.setDirty(true, true)
+ }
+
+ function fitView() {
+ const canvas = canvasStore.getCanvas()
+ const nodes = canvas.graph?.nodes
+ if (!nodes) return
+ ensureBounds(nodes)
+ const bounds = createBounds(nodes)
+ if (!bounds) return
+
+ canvas.ds.fitToBounds(bounds)
+ canvas.setDirty(true, true)
+ }
+
+ return {
+ registerNodeDef,
+ registerSubgraphNodeDef,
+ addNodeOnGraph,
+ addNodeInput,
+ getCanvasCenter,
+ goToNode,
+ resetView,
+ fitView,
+ updatePreviews
+ }
+}
diff --git a/docs/hel-892/serialization-evidence/src__utils__executionUtil.ts b/docs/hel-892/serialization-evidence/src__utils__executionUtil.ts
new file mode 100644
index 00000000..3f7f982c
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__utils__executionUtil.ts
@@ -0,0 +1,150 @@
+import type {
+ ExecutableLGraphNode,
+ ExecutionId,
+ LGraph
+} from '@/lib/litegraph/src/litegraph'
+import {
+ ExecutableNodeDTO,
+ LGraphEventMode
+} from '@/lib/litegraph/src/litegraph'
+import type {
+ ComfyApiWorkflow,
+ ComfyWorkflowJSON
+} from '@/platform/workflow/validation/schemas/workflowSchema'
+
+import { ExecutableGroupNodeDTO, isGroupNode } from './executableGroupNodeDto'
+import { compressWidgetInputSlots } from './litegraphUtil'
+
+/**
+ * Converts the current graph workflow for sending to the API.
+ * @note Node widgets are updated before serialization to prepare queueing.
+ *
+ * @param graph The graph to convert.
+ * @param options The options for the conversion.
+ * - `sortNodes`: Whether to sort the nodes by execution order.
+ * @returns The workflow and node links
+ */
+export const graphToPrompt = async (
+ graph: LGraph,
+ options: { sortNodes?: boolean } = {}
+): Promise<{ workflow: ComfyWorkflowJSON; output: ComfyApiWorkflow }> => {
+ const { sortNodes = false } = options
+
+ for (const node of graph.computeExecutionOrder(false)) {
+ const innerNodes = node.getInnerNodes
+ ? node.getInnerNodes(new Map())
+ : [node]
+ for (const innerNode of innerNodes) {
+ if (innerNode.isVirtualNode) {
+ innerNode.applyToGraph?.()
+ }
+ }
+ }
+
+ const workflow = graph.serialize({ sortNodes })
+
+ // Remove localized_name from the workflow
+ for (const node of workflow.nodes) {
+ for (const slot of node.inputs ?? []) {
+ delete slot.localized_name
+ }
+ for (const slot of node.outputs ?? []) {
+ delete slot.localized_name
+ }
+ }
+
+ compressWidgetInputSlots(workflow)
+ workflow.extra ??= {}
+ workflow.extra.frontendVersion = __COMFYUI_FRONTEND_VERSION__
+
+ const nodeDtoMap = new Map()
+ for (const node of graph.computeExecutionOrder(false)) {
+ const dto: ExecutableLGraphNode = isGroupNode(node)
+ ? new ExecutableGroupNodeDTO(node, [], nodeDtoMap)
+ : new ExecutableNodeDTO(node, [], nodeDtoMap)
+
+ for (const innerNode of dto.getInnerNodes()) {
+ nodeDtoMap.set(innerNode.id, innerNode)
+ }
+
+ nodeDtoMap.set(dto.id, dto)
+ }
+
+ const output: ComfyApiWorkflow = {}
+ // Process nodes in order of execution
+ for (const node of nodeDtoMap.values()) {
+ // Don't serialize muted nodes
+ if (
+ node.isVirtualNode ||
+ node.mode === LGraphEventMode.NEVER ||
+ node.mode === LGraphEventMode.BYPASS
+ ) {
+ continue
+ }
+
+ const inputs: ComfyApiWorkflow[string]['inputs'] = {}
+ const { widgets } = node
+
+ // Store all widget values
+ if (widgets) {
+ for (const [i, widget] of widgets.entries()) {
+ if (!widget.name || widget.options?.serialize === false) continue
+
+ const widgetValue = widget.serializeValue
+ ? await widget.serializeValue(node, i)
+ : widget.value
+ // By default, Array values are reserved to represent node connections.
+ // We need to wrap the array as an object to avoid the misinterpretation
+ // of the array as a node connection.
+ // The backend automatically unwraps the object to an array during
+ // execution.
+ inputs[widget.name] = Array.isArray(widgetValue)
+ ? {
+ __value__: widgetValue
+ }
+ : widgetValue
+ }
+ }
+
+ // Store all node links
+ for (const [i, input] of node.inputs.entries()) {
+ const resolvedInput = node.resolveInput(i)
+ if (!resolvedInput) continue
+
+ // Resolved to an actual widget value rather than a node connection
+ if (resolvedInput.widgetInfo) {
+ const { value } = resolvedInput.widgetInfo
+ inputs[input.name] = Array.isArray(value) ? { __value__: value } : value
+ continue
+ }
+
+ inputs[input.name] = [
+ String(resolvedInput.origin_id),
+ // @ts-expect-error link.origin_slot is already number.
+ parseInt(resolvedInput.origin_slot)
+ ]
+ }
+
+ output[String(node.id)] = {
+ inputs,
+ // TODO(huchenlei): Filter out all nodes that cannot be mapped to a
+ // comfyClass.
+ class_type: node.comfyClass!,
+ // Ignored by the backend.
+ _meta: {
+ title: node.title
+ }
+ }
+ }
+
+ // Remove inputs connected to removed nodes
+ for (const { inputs } of Object.values(output)) {
+ for (const [i, input] of Object.entries(inputs)) {
+ if (Array.isArray(input) && input.length === 2 && !output[input[0]]) {
+ delete inputs[i]
+ }
+ }
+ }
+
+ return { workflow: workflow as ComfyWorkflowJSON, output }
+}
diff --git a/docs/hel-892/serialization-evidence/src__utils__litegraphUtil.ts b/docs/hel-892/serialization-evidence/src__utils__litegraphUtil.ts
new file mode 100644
index 00000000..898b3ef2
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__utils__litegraphUtil.ts
@@ -0,0 +1,250 @@
+import _ from 'es-toolkit/compat'
+
+import type { ColorOption, LGraph } from '@/lib/litegraph/src/litegraph'
+import {
+ LGraphGroup,
+ LGraphNode,
+ Reroute,
+ isColorable
+} from '@/lib/litegraph/src/litegraph'
+import type {
+ ExportedSubgraph,
+ ISerialisableNodeInput,
+ ISerialisedGraph
+} from '@/lib/litegraph/src/types/serialisation'
+import type {
+ IBaseWidget,
+ IComboWidget
+} from '@/lib/litegraph/src/types/widgets'
+import type { InputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+
+type ImageNode = LGraphNode & { imgs: HTMLImageElement[] | undefined }
+type VideoNode = LGraphNode & {
+ videoContainer: HTMLElement | undefined
+ imgs: HTMLVideoElement[] | undefined
+}
+
+export function isImageNode(node: LGraphNode | undefined): node is ImageNode {
+ if (!node) return false
+ return (
+ node.previewMediaType === 'image' ||
+ (node.previewMediaType !== 'video' && !!node.imgs?.length)
+ )
+}
+
+export function isVideoNode(node: LGraphNode | undefined): node is VideoNode {
+ if (!node) return false
+ return node.previewMediaType === 'video' || !!node.videoContainer
+}
+
+export function isAudioNode(node: LGraphNode | undefined): boolean {
+ return !!node && node.previewMediaType === 'audio'
+}
+
+export function addToComboValues(widget: IComboWidget, value: string) {
+ if (!widget.options) widget.options = { values: [] }
+ if (!widget.options.values) widget.options.values = []
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ if (!widget.options.values.includes(value)) {
+ // @ts-expect-error Combo widget values may be a dictionary or legacy function type
+ widget.options.values.push(value)
+ }
+}
+
+export const isLGraphNode = (item: unknown): item is LGraphNode => {
+ return item instanceof LGraphNode
+}
+
+export const isLGraphGroup = (item: unknown): item is LGraphGroup => {
+ return item instanceof LGraphGroup
+}
+
+export const isReroute = (item: unknown): item is Reroute => {
+ return item instanceof Reroute
+}
+
+/**
+ * Get the color option of all canvas items if they are all the same.
+ * @param items - The items to get the color option of.
+ * @returns The color option of the item.
+ */
+export const getItemsColorOption = (items: unknown[]): ColorOption | null => {
+ const validItems = _.filter(items, isColorable)
+ if (_.isEmpty(validItems)) return null
+
+ const colorOptions = _.map(validItems, (item) => item.getColorOption())
+
+ return _.every(colorOptions, (option) =>
+ _.isEqual(option, _.head(colorOptions))
+ )
+ ? _.head(colorOptions)!
+ : null
+}
+
+export function executeWidgetsCallback(
+ nodes: LGraphNode[],
+ callbackName: 'onRemove' | 'beforeQueued' | 'afterQueued'
+) {
+ for (const node of nodes) {
+ for (const widget of node.widgets ?? []) {
+ widget[callbackName]?.()
+ }
+ }
+}
+
+/**
+ * Since frontend version 1.16, forceInput input is no longer treated
+ * as widget. So we need to remove the dummy widget value serialized
+ * from workflows prior to v1.16.
+ * Ref: https://github.com/Comfy-Org/ComfyUI_frontend/pull/3326
+ *
+ * @param nodeDef the node definition
+ * @param widgets the widgets on the node instance (from node definition)
+ * @param widgetsValues the widgets values to populate the node during configuration
+ * @returns the widgets values without the dummy widget values
+ */
+export function migrateWidgetsValues(
+ inputDefs: Record,
+ widgets: IBaseWidget[],
+ widgetsValues: TWidgetValue[]
+): TWidgetValue[] {
+ const widgetNames = new Set(widgets.map((w) => w.name))
+ const originalWidgetsInputs = Object.values(inputDefs).filter(
+ (input) => widgetNames.has(input.name) || input.forceInput
+ )
+ // Count the number of original widgets inputs.
+ const numOriginalWidgets = _.sum(
+ originalWidgetsInputs.map((input) =>
+ // If the input has control, it will have 2 widgets.
+ input.control_after_generate ||
+ ['seed', 'noise_seed'].includes(input.name)
+ ? 2
+ : 1
+ )
+ )
+
+ if (numOriginalWidgets === widgetsValues?.length) {
+ return _.zip(originalWidgetsInputs, widgetsValues)
+ .filter(([input]) => !input?.forceInput)
+ .map(([_, value]) => value as TWidgetValue)
+ }
+ return widgetsValues
+}
+
+/**
+ * Fix link input slots after loading a graph. Because the node inputs follows
+ * the node definition after 1.16, the node inputs array from previous versions,
+ * might get added items in the middle, which can cause shift to link's slot index.
+ * For example, the node inputs definition is:
+ * "required": {
+ * "input1": ["INT", { forceInput: true }],
+ * "input2": ["MODEL", { forceInput: false }],
+ * "input3": ["MODEL", { forceInput: false }]
+ * }
+ *
+ * previously node inputs array was:
+ * [{name: 'input2'}, {name: 'input3'}, {name: 'input1'}]
+ * because input1 is created as widget first, then convert to input socket after
+ * input 2 and 3.
+ *
+ * Now, the node inputs array just follows the definition order:
+ * [{name: 'input1'}, {name: 'input2'}, {name: 'input3'}]
+ *
+ * We need to update the slot index of corresponding links to match the new
+ * node inputs array order.
+ *
+ * Ref: https://github.com/Comfy-Org/ComfyUI_frontend/issues/3348
+ *
+ * @param graph - The graph to fix links for.
+ */
+export function fixLinkInputSlots(graph: LGraph) {
+ // Note: We can't use forEachNode here because we need access to the graph's
+ // links map at each level. Links are stored in their respective graph/subgraph.
+ for (const node of graph.nodes) {
+ // Fix links for the current node
+ for (const [inputIndex, input] of node.inputs.entries()) {
+ const linkId = input.link
+ if (!linkId) continue
+
+ const link = graph.links.get(linkId)
+ if (!link) continue
+
+ link.target_slot = inputIndex
+ }
+
+ // Recursively fix links in subgraphs
+ if (node.isSubgraphNode?.() && node.subgraph) {
+ fixLinkInputSlots(node.subgraph)
+ }
+ }
+}
+
+/**
+ * Compress widget input slots by removing all unconnected widget input slots.
+ * This should match the serialization format of legacy widget conversion.
+ *
+ * @param graph - The graph to compress widget input slots for.
+ * @throws If an infinite loop is detected.
+ */
+export function compressWidgetInputSlots(graph: ISerialisedGraph) {
+ for (const node of graph.nodes) {
+ node.inputs = node.inputs?.filter(matchesLegacyApi)
+
+ for (const [inputIndex, input] of node.inputs?.entries() ?? []) {
+ if (input.link) {
+ const link = graph.links.find((link) => link[0] === input.link)
+ if (link) {
+ link[4] = inputIndex
+ }
+ }
+ }
+ }
+
+ compressSubgraphWidgetInputSlots(graph.definitions?.subgraphs)
+}
+
+function matchesLegacyApi(input: ISerialisableNodeInput) {
+ return !(input.widget && input.link === null && !input.label)
+}
+
+/**
+ * Duplication to handle the legacy link arrays in the root workflow.
+ * @see compressWidgetInputSlots
+ * @param subgraph The subgraph to compress widget input slots for.
+ */
+function compressSubgraphWidgetInputSlots(
+ subgraphs: ExportedSubgraph[] | undefined,
+ visited = new WeakSet()
+) {
+ if (!subgraphs) return
+
+ for (const subgraph of subgraphs) {
+ if (visited.has(subgraph)) throw new Error('Infinite loop detected')
+ visited.add(subgraph)
+
+ if (subgraph.nodes) {
+ for (const node of subgraph.nodes) {
+ node.inputs = node.inputs?.filter(matchesLegacyApi)
+
+ if (!subgraph.links) continue
+
+ for (const [inputIndex, input] of node.inputs?.entries() ?? []) {
+ if (input.link) {
+ const link = subgraph.links.find((link) => link.id === input.link)
+ if (link) link.target_slot = inputIndex
+ }
+ }
+ }
+ }
+
+ compressSubgraphWidgetInputSlots(subgraph.definitions?.subgraphs, visited)
+ }
+}
+
+export function isLoad3dNode(node: LGraphNode) {
+ return (
+ node &&
+ node.type &&
+ (node.type === 'Load3D' || node.type === 'Load3DAnimation')
+ )
+}
diff --git a/docs/hel-892/serialization-evidence/src__workbench__utils__nodeDefOrderingUtil.ts b/docs/hel-892/serialization-evidence/src__workbench__utils__nodeDefOrderingUtil.ts
new file mode 100644
index 00000000..2a39fa70
--- /dev/null
+++ b/docs/hel-892/serialization-evidence/src__workbench__utils__nodeDefOrderingUtil.ts
@@ -0,0 +1,108 @@
+import type { TWidgetValue } from '@/lib/litegraph/src/litegraph'
+import type { InputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
+import type { ComfyNodeDefImpl } from '@/stores/nodeDefStore'
+
+/**
+ * Gets an ordered array of InputSpec objects based on input_order.
+ * This is designed to work with V2 format used by litegraphService.
+ *
+ * @param nodeDefImpl - The ComfyNodeDefImpl containing both V1 and V2 formats
+ * @param inputs - The V2 format inputs (flat Record)
+ * @returns Array of InputSpec objects in the correct order
+ */
+export function getOrderedInputSpecs(
+ nodeDefImpl: ComfyNodeDefImpl,
+ inputs: Record
+): InputSpec[] {
+ const orderedInputSpecs: InputSpec[] = []
+
+ // If no input_order, return default Object.values order
+ if (!nodeDefImpl.input_order) {
+ return Object.values(inputs)
+ }
+
+ // Process required inputs in specified order
+ if (nodeDefImpl.input_order.required) {
+ for (const name of nodeDefImpl.input_order.required) {
+ const inputSpec = inputs[name]
+ if (inputSpec && !inputSpec.isOptional) {
+ orderedInputSpecs.push(inputSpec)
+ }
+ }
+ }
+
+ // Process optional inputs in specified order
+ if (nodeDefImpl.input_order.optional) {
+ for (const name of nodeDefImpl.input_order.optional) {
+ const inputSpec = inputs[name]
+ if (inputSpec && inputSpec.isOptional) {
+ orderedInputSpecs.push(inputSpec)
+ }
+ }
+ }
+
+ // Add any remaining inputs not specified in input_order
+ const processedNames = new Set(orderedInputSpecs.map((spec) => spec.name))
+ for (const inputSpec of Object.values(inputs)) {
+ if (!processedNames.has(inputSpec.name)) {
+ orderedInputSpecs.push(inputSpec)
+ }
+ }
+
+ return orderedInputSpecs
+}
+
+/**
+ * Reorders widget values based on the input_order to match expected widget order.
+ * This is used when widgets were created in a different order than input_order specifies.
+ *
+ * @param widgetValues - The current widget values array
+ * @param currentWidgetOrder - The current order of widget names
+ * @param inputOrder - The desired order from input_order
+ * @returns Reordered widget values array
+ */
+export function sortWidgetValuesByInputOrder(
+ widgetValues: TWidgetValue[],
+ currentWidgetOrder: string[],
+ inputOrder: string[]
+): TWidgetValue[] {
+ if (!inputOrder || inputOrder.length === 0) {
+ return widgetValues
+ }
+
+ // Create a map of widget name to value
+ const valueMap = new Map()
+ currentWidgetOrder.forEach((name, index) => {
+ if (index < widgetValues.length) {
+ valueMap.set(name, widgetValues[index])
+ }
+ })
+
+ // Reorder based on input_order
+ const reordered: TWidgetValue[] = []
+ const usedNames = new Set()
+
+ // First, add values in the order specified by input_order
+ for (const name of inputOrder) {
+ if (valueMap.has(name)) {
+ reordered.push(valueMap.get(name))
+ usedNames.add(name)
+ }
+ }
+
+ // Then add any remaining values not in input_order
+ for (const [name, value] of valueMap.entries()) {
+ if (!usedNames.has(name)) {
+ reordered.push(value)
+ }
+ }
+
+ // If there are extra values not in the map, append them
+ if (widgetValues.length > currentWidgetOrder.length) {
+ for (let i = currentWidgetOrder.length; i < widgetValues.length; i++) {
+ reordered.push(widgetValues[i])
+ }
+ }
+
+ return reordered
+}