Upload folder using huggingface_hub (part 8)

.gitattributes

@@ -86,3 +86,21 @@ ComfyUI/custom_nodes/koolook/docs/automations/LTX-2.3/audio-lipsync/runs/run-001
 ComfyUI/custom_nodes/koolook/docs/automations/LTX-2.3/audio-lipsync/runs/run-008_bear_2x-fr_audiofile_k-dir_upstream_audio-off/card.png filter=lfs diff=lfs merge=lfs -text
 ComfyUI/custom_nodes/koolook/docs/automations/LTX-2.3/audio-lipsync/runs/run-009_bear_3x-fr_audiofile_k-dir_koolook_audio-off/card.png filter=lfs diff=lfs merge=lfs -text
 ComfyUI/custom_nodes/koolook/docs/designs/sidebar-icon-proposals.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/koolook/web/guide/img/screenshots/auto-save-pre-load.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/koolook/web/guide/img/screenshots/snapshot-transfer-compare.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/koolook/web/guide/img/screenshots/snapshot-transfer-copy-folder.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/koolook/web/guide/img/screenshots/snapshot-transfer-expanded.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/rgthree-comfy/docs/rgthree_advanced.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/rgthree-comfy/docs/rgthree_advanced_metadata.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/rgthree-comfy/docs/rgthree_context.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/custom_nodes/rgthree-comfy/docs/rgthree_context_metadata.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/1.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/1.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/2.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/3.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/4.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/5.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI/input/whatdreamscost/Late[[:space:]]night[[:space:]]trap.mp3 filter=lfs diff=lfs merge=lfs -text
+ComfyUI/models/text_encoders/mmproj-BF16.gguf filter=lfs diff=lfs merge=lfs -text
+ComfyUI/models/unet/ltx-2.3-22b-dev-Q4_K_M.gguf filter=lfs diff=lfs merge=lfs -text
+ComfyUI/output/video/ComfyUI_00001_.mp4 filter=lfs diff=lfs merge=lfs -text

ComfyUI/custom_nodes/koolook/k_easy_wan22_prompt.py

@@ -0,0 +1,120 @@
+import json
+import os
+
+class EasyWan22Prompt:
+    """
+    Wan 2.2 Easy Prompt node for ComfyUI.
+    Loads dynamic inputs from config.json, adds a body text input, and outputs two strings (combined prompt and fields only) plus optional CONDITIONING.
+    Includes an optional CLIP input to encode the combined prompt into CONDITIONING, allowing use as a positive prompt node.
+    """
+    def __init__(self):
+        pass
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        # Get the directory of this script to locate config.json
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        config_path = os.path.join(script_dir, 'config.json')
+
+        # Load the JSON config with error handling
+        try:
+            with open(config_path, 'r') as f:
+                config = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError) as e:
+            print(f"Error loading config.json: {e}. Using dummy config.")
+            config = {
+                "category": "Koolook/Wan_Video",
+                "node_name": "Wan_2.2",
+                "fields": [],
+                "output_type": "STRING"
+            }
+
+        # Build the INPUT_TYPES dict dynamically from config fields
+        input_types = {
+            "required": {},
+            "optional": {
+                "clip": ("CLIP",)
+            }
+        }
+        for field in config['fields']:
+            name = field['name']
+            if field['type'] == 'combo':
+                options = field['options']
+                defaults = {
+                    "default": field.get('default', options[0]),
+                    "lazy": True,
+                    "tooltip": f"Optional Wan 2.2 prompt fragment for {name.replace('_', ' ')}. Choose 'none' to omit it.",
+                }
+                input_types["required"][name] = (options, defaults)
+            elif field['type'] == 'string':
+                defaults = {
+                    "default": field.get('default', ""),
+                    "multiline": True,
+                    "lazy": True,
+                    "tooltip": f"Optional Wan 2.2 prompt text for {name.replace('_', ' ')}.",
+                }
+                input_types["required"][name] = ("STRING", defaults)
+
+        # Add the body text input at the end (appears at the bottom)
+        input_types["required"]["body"] = ("STRING", {
+            "multiline": True,
+            "default": "",
+            "lazy": True,
+            "tooltip": "Main free-text prompt. Appended after selected dropdown fragments.",
+        })
+
+        return input_types
+
+    RETURN_TYPES = ("STRING", "STRING", "CONDITIONING",)
+    RETURN_NAMES = ("combined_prompt", "fields_only", "conditioning",)
+    FUNCTION = "execute"
+    CATEGORY = "Koolook/Wan_Video"
+    OUTPUT_NODE = False
+
+    def check_lazy_status(self, **kwargs):
+        # Evaluate all inputs if needed
+        return list(kwargs.keys())
+
+    def execute(self, body, clip=None, **kwargs):
+        # Collect selected options (values only), excluding body and skipping "none"
+        prompt_parts = [value for key, value in kwargs.items() if value and value != "none"]
+        fields_str = ", ".join(prompt_parts)
+
+        # Combined: fields options + body (with comma if both present)
+        combined = fields_str
+        if body:
+            if combined:
+                combined += ", " + body
+            else:
+                combined = body
+
+        # Conditioning: Encode the combined prompt if clip is provided, else empty list
+        if clip is not None:
+            tokens = clip.tokenize(combined)
+            cond, pooled = clip.encode_from_tokens(tokens, return_pooled=True)
+            conditioning = [[cond, {"pooled_output": pooled}]]
+        else:
+            conditioning = []
+
+        return (combined, fields_str, conditioning,)
+
+    # Optional: IS_CHANGED for re-execution if config changes
+    @classmethod
+    def IS_CHANGED(cls, *args, **kwargs):
+        # Hash the config.json to re-execute if it changes
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        config_path = os.path.join(script_dir, 'config.json')
+        try:
+            with open(config_path, 'rb') as f:
+                return hash(f.read())
+        except FileNotFoundError:
+            return "dummy"
+
+# Individual node mappings
+NODE_CLASS_MAPPINGS = {
+    "EasyWan22Prompt": EasyWan22Prompt
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "EasyWan22Prompt": "Wan 2.2 Easy Prompt (Koolook)"
+}

ComfyUI/custom_nodes/koolook/k_loop_status.py

@@ -0,0 +1,502 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ComfyUI-Koolook - loop status utilities
+# Copyright (C) 2026 ComfyUI-Koolook contributors (kforgelabs).
+
+"""Loop-body status pass-through nodes."""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+from pathlib import Path
+import re
+import threading
+import traceback
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+LOGGER = logging.getLogger(__name__)
+MAX_AUTO_QUEUE_DEPTH = 1000
+DEFAULT_SERVER_URL = "http://127.0.0.1:8188"
+_ACTIVE_QUEUE_KEYS: set[str] = set()
+_ACTIVE_QUEUE_KEYS_LOCK = threading.Lock()
+
+
+class AnyType(str):
+    """ComfyUI wildcard type that compares as compatible with any socket."""
+
+    def __ne__(self, _other):
+        return False
+
+
+ANY_TYPE = AnyType("*")
+
+
+def _format_write_path(filepath: str, frame: int) -> str:
+    text = str(filepath or "").strip()
+    return re.sub(r"%0?(\d*)d", lambda m: f"{frame:0{m.group(1) or '0'}d}", text)
+
+
+def build_status(label: str, index: int, total: int, filepath: str = "") -> str:
+    total = max(1, int(total))
+    frame = int(index)
+    position = max(1, min(total, frame + 1))
+    label = str(label or "loop").strip() or "loop"
+    path = _format_write_path(filepath, frame)
+    if path:
+        return f"{label}: {position}/{total} frame {frame} -> {path}"
+    return f"{label}: {position}/{total} frame {frame}"
+
+
+def infer_index_node_id(prompt: dict | None, unique_id) -> str:
+    if not isinstance(prompt, dict) or unique_id is None:
+        return ""
+    node = prompt.get(str(unique_id))
+    if not isinstance(node, dict):
+        return ""
+    inputs = node.get("inputs")
+    if not isinstance(inputs, dict):
+        return ""
+    link = inputs.get("index")
+    if isinstance(link, (list, tuple)) and link:
+        return str(link[0])
+    return ""
+
+
+_infer_index_node_id = infer_index_node_id
+
+
+def _prompt_has_node(prompt: dict | None, node_id: str) -> bool:
+    return isinstance(prompt, dict) and isinstance(prompt.get(str(node_id)), dict)
+
+
+def _describe_prompt_node(prompt: dict | None, node_id: str) -> str:
+    if not isinstance(prompt, dict):
+        return f"node {node_id}"
+    node = prompt.get(str(node_id))
+    if not isinstance(node, dict):
+        return f"node {node_id}"
+    class_type = str(node.get("class_type") or node.get("type") or "").strip()
+    title = str(node.get("_meta", {}).get("title") or node.get("title") or "").strip()
+    if title and title != class_type:
+        prefix = f"{title} ({class_type})" if class_type else title
+    else:
+        prefix = class_type
+    return f"{prefix} node {node_id}" if prefix else f"node {node_id}"
+
+
+def resolve_index_node_id(
+    prompt: dict | None,
+    unique_id,
+    configured_index_node_id: str,
+    fallback_id: str = "",
+) -> tuple[str, str]:
+    """Pick the frame-index node to advance and a human note about the choice.
+
+    The connected ``index`` input is the authoritative, deterministic source. An
+    explicit ``configured_index_node_id`` that exists in the prompt is honored as
+    a power-user override; otherwise the node feeding the connected ``index``
+    input wins, so a stale or mis-shifted id self-heals. ``fallback_id`` (e.g. a
+    numeric label recovered from a shifted save) is a last resort, used only when
+    nothing else resolves, so it never overrides real wiring. Returns
+    ``("", "")`` when nothing resolves so the caller can raise synchronously with
+    an actionable message.
+    """
+    configured = str(configured_index_node_id or "").strip()
+    inferred = infer_index_node_id(prompt, unique_id)
+    if configured and _prompt_has_node(prompt, configured):
+        return configured, f"using configured {_describe_prompt_node(prompt, configured)}"
+    if inferred:
+        if configured and configured != inferred:
+            return (
+                inferred,
+                "configured index node "
+                f"{configured!r} is not in this prompt; using connected "
+                f"{_describe_prompt_node(prompt, inferred)}",
+            )
+        return inferred, f"using connected {_describe_prompt_node(prompt, inferred)}"
+    if configured:
+        return configured, f"using configured node {configured}"
+    fallback = str(fallback_id or "").strip()
+    if fallback:
+        return fallback, f"using recovered node {fallback}"
+    return "", ""
+
+
+def _as_bool(value) -> bool:
+    """Coerce saved widget values (incl. string booleans) to ``bool``.
+
+    ComfyUI can persist a boolean widget as the string ``"true"``/``"false"``;
+    ``bool("false")`` is truthy, so a naive cast would auto-queue when the user
+    saved the toggle off.
+    """
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def _get_json(url: str, timeout: float = 10) -> dict:
+    _validate_http_url(url)
+    with urllib.request.urlopen(url, timeout=timeout) as response:  # nosec B310
+        body = response.read().decode("utf-8", errors="replace")
+    return json.loads(body) if body else {}
+
+
+def _validate_http_url(url: str) -> None:
+    parsed = urllib.parse.urlsplit(str(url or ""))
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise RuntimeError(f"Only http(s) ComfyUI server URLs are allowed: {url!r}")
+
+
+def _compose_server_url(host: str | None, port) -> str:
+    """Join a detected host/port into a connectable ``http://`` URL.
+
+    ComfyUI's bare ``--listen`` binds to all IPv4 and IPv6 interfaces as a
+    comma-joined host value, so the host is split and any bind-all member means
+    we connect over loopback. IPv6 literals are bracketed so ``urllib`` can parse
+    the ``host:port`` netloc (``::1`` -> ``http://[::1]:port``).
+    """
+    members = [member.strip() for member in str(host or "").split(",") if member.strip()]
+    bind_all = {"0.0.0.0", "::", "*"}  # nosec B104
+    if any(member in bind_all for member in members):
+        host = "127.0.0.1"
+    else:
+        host = members[0] if members else "127.0.0.1"
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    return f"http://{host}:{port}"
+
+
+def _detect_local_server_url() -> str | None:
+    """Best-effort URL of the ComfyUI server hosting this node.
+
+    The node default points at ComfyUI's default port (8188), but installs
+    launched with ``--port`` (or ``--listen``) bind elsewhere — probing the
+    stale default is actively refused and aborts the loop. Prefer the address
+    the running server actually bound to. Returns ``None`` when neither the
+    parsed CLI args nor the running ``PromptServer`` can be inspected (e.g. a
+    headless unit test), so the caller can fall back to the literal default.
+    """
+    port = None
+    host = None
+    try:
+        from comfy.cli_args import args  # type: ignore[import-not-found]
+
+        port = getattr(args, "port", None)
+        host = getattr(args, "listen", None)
+    except Exception:  # pragma: no cover - depends on ComfyUI runtime
+        LOGGER.debug("comfy.cli_args server detection failed", exc_info=True)
+    if not port:
+        try:
+            from server import PromptServer  # type: ignore[import-not-found]
+
+            instance = PromptServer.instance
+            port = port or getattr(instance, "port", None)
+            host = host or getattr(instance, "address", None)
+        except Exception:  # pragma: no cover - depends on ComfyUI runtime
+            LOGGER.debug("PromptServer server detection failed", exc_info=True)
+    if not port:
+        return None
+    return _compose_server_url(host, port)
+
+
+def _resolve_server_url(server_url: str) -> str:
+    """Return the URL to queue against, auto-detecting for the ``auto`` default.
+
+    ``auto`` (the widget default), an empty value, or the legacy baked-in
+    ``DEFAULT_SERVER_URL`` all mean "detect the running server" — replaced with
+    the server's real address when it can be detected, falling back to the
+    default otherwise. Any other value is an explicit URL used verbatim.
+    """
+    server_url = str(server_url or "").strip()
+    if server_url and server_url.lower() != "auto" and server_url != DEFAULT_SERVER_URL:
+        return server_url
+    detected = _detect_local_server_url()
+    if detected and detected != server_url:
+        print(f"[Koolook Loop Status] resolved server_url to {detected}")
+    return detected or DEFAULT_SERVER_URL
+
+
+def _probe_server(server_url: str) -> None:
+    _get_json(f"{server_url.rstrip('/')}/system_stats", timeout=10)
+
+
+def _post_prompt(server_url: str, prompt: dict) -> dict:
+    _validate_http_url(server_url)
+    data = json.dumps({"prompt": prompt}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{server_url.rstrip('/')}/prompt",
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as response:  # nosec B310
+        body = response.read().decode("utf-8", errors="replace")
+    payload = json.loads(body) if body else {}
+    if payload.get("error") or not payload.get("prompt_id"):
+        raise RuntimeError(f"ComfyUI rejected child prompt: {payload}")
+    print(f"[Koolook Loop Status] queued next prompt: {body}")
+    return payload
+
+
+def _abort_marker_path(filepath: str, frame: int) -> Path:
+    expected = Path(_format_write_path(filepath, frame))
+    parent = expected.parent if str(expected.parent) else Path.cwd()
+    return parent / f"_loop_aborted_at_frame_{frame}.txt"
+
+
+def _write_abort_marker(filepath: str, frame: int, exc: BaseException) -> None:
+    marker = _abort_marker_path(filepath, frame)
+    marker.parent.mkdir(parents=True, exist_ok=True)
+    marker.write_text(
+        "Koolook Loop Status failed to queue the next prompt.\n\n"
+        f"Frame: {frame}\n"
+        f"Error: {exc}\n\n"
+        f"{traceback.format_exc()}",
+        encoding="utf-8",
+    )
+    print(f"[Koolook Loop Status] wrote abort marker: {marker}")
+
+
+def _queue_next_prompt(
+    *,
+    prompt: dict,
+    index_node_id: str,
+    next_index: int,
+    server_url: str,
+    queue_key: str,
+    filepath: str,
+    remaining_auto_queue_depth: int,
+) -> None:
+    try:
+        child = copy.deepcopy(prompt)
+        node = child.get(str(index_node_id))
+        if not isinstance(node, dict):
+            raise RuntimeError(f"index node id {index_node_id!r} is not in prompt")
+        inputs = node.setdefault("inputs", {})
+        inputs["value"] = int(next_index)
+        status_node = child.get(str(queue_key.split(":", 1)[0]))
+        if isinstance(status_node, dict):
+            status_inputs = status_node.setdefault("inputs", {})
+            status_inputs["remaining_auto_queue_depth"] = int(remaining_auto_queue_depth)
+        _post_prompt(server_url, child)
+    except Exception as exc:
+        LOGGER.exception("Koolook Loop Status failed to queue next prompt")
+        print(f"[Koolook Loop Status] failed to queue next prompt: {exc}")
+        _write_abort_marker(filepath, next_index, exc)
+    finally:
+        with _ACTIVE_QUEUE_KEYS_LOCK:
+            _ACTIVE_QUEUE_KEYS.discard(queue_key)
+
+
+class KoolookLoopStatus:
+    """Print per-iteration loop progress and pass the value through."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "value": (
+                    ANY_TYPE,
+                    {
+                        "tooltip": "Payload to pass through unchanged while this node reports loop progress.",
+                    },
+                ),
+                "index": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 999999,
+                        "tooltip": "Current zero-based frame index. Wire this from the easy int node that drives the loop.",
+                    },
+                ),
+                "total": (
+                    "INT",
+                    {
+                        "default": 1,
+                        "min": 1,
+                        "max": 100000,
+                        "tooltip": "Total frames/prompts in this loop. Auto-queue stops when index + 1 reaches total.",
+                    },
+                ),
+            },
+            "optional": {
+                "filepath": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Optional sequence path for the printed status line. %04d-style frame tokens are previewed with the current index.",
+                    },
+                ),
+                "label": (
+                    "STRING",
+                    {
+                        "default": "loop",
+                        "multiline": False,
+                        "tooltip": "Short label printed before progress, for example EXR_SAFE or plate_pass.",
+                    },
+                ),
+                "auto_queue_next": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "tooltip": "Queue the next prompt automatically after this frame, advancing the connected index node.",
+                    },
+                ),
+                "index_node_id": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Advanced override for the frame-index node id. Leave blank; the connected index input is normally detected automatically.",
+                    },
+                ),
+                "server_url": (
+                    "STRING",
+                    {
+                        "default": "auto",
+                        "multiline": False,
+                        "tooltip": "ComfyUI server used for auto-queue. Leave auto to detect the running server and port.",
+                    },
+                ),
+                "max_auto_queue_depth": (
+                    "INT",
+                    {
+                        "default": 100,
+                        "min": 1,
+                        "max": MAX_AUTO_QUEUE_DEPTH,
+                        "tooltip": "Safety cap for child prompts this run may chain, preventing accidental runaway loops.",
+                    },
+                ),
+                "remaining_auto_queue_depth": (
+                    "INT",
+                    {
+                        "default": -1,
+                        "min": -1,
+                        "max": MAX_AUTO_QUEUE_DEPTH,
+                        "tooltip": "Internal countdown carried into child prompts. Leave at -1 in normal canvas use.",
+                    },
+                ),
+            },
+            "hidden": {
+                "prompt": "PROMPT",
+                "unique_id": "UNIQUE_ID",
+            },
+        }
+
+    RETURN_TYPES = (ANY_TYPE, "STRING")
+    RETURN_NAMES = ("value", "status")
+    FUNCTION = "report"
+    CATEGORY = "Koolook/Loop"
+
+    def report(
+        self,
+        value,
+        index,
+        total,
+        filepath="",
+        label="loop",
+        auto_queue_next=False,
+        index_node_id="",
+        server_url="auto",
+        max_auto_queue_depth=100,
+        remaining_auto_queue_depth=-1,
+        prompt=None,
+        unique_id=None,
+    ):
+        frame = int(index)
+        total = max(1, int(total))
+        next_index = frame + 1
+        index_node_id = str(index_node_id or "").strip()
+        label = str(label or "").strip()
+        numeric_label_id = ""
+        if not index_node_id and label.isdigit():
+            numeric_label_id = label
+            label = "EXR_SAFE"
+            print(
+                "[Koolook Loop Status] numeric label looks like a node id; using "
+                "EXR_SAFE as the label and keeping the number only as a fallback id"
+            )
+        # The connected `index` input is the authoritative frame-index source: an
+        # explicit index_node_id that exists wins as a power-user override, else
+        # the connected node is used (self-healing a stale/mis-shifted id). A
+        # numeric label is a last-resort fallback that never overrides the wiring.
+        # `index_note` records which node was used.
+        index_node_id, index_note = resolve_index_node_id(
+            prompt, unique_id, index_node_id, fallback_id=numeric_label_id
+        )
+        max_depth = max(1, min(int(max_auto_queue_depth), MAX_AUTO_QUEUE_DEPTH))
+        remaining_depth = int(remaining_auto_queue_depth)
+        if remaining_depth < 0:
+            remaining_depth = max_depth
+        should_queue = _as_bool(auto_queue_next) and next_index < total
+        if should_queue:
+            if total - frame - 1 > max_depth:
+                raise RuntimeError(
+                    f"Refusing to auto-queue {total - frame - 1} remaining prompts; "
+                    f"max_auto_queue_depth is {max_depth}."
+                )
+            if remaining_depth <= 0:
+                raise RuntimeError("Auto-queue depth exhausted before loop completed.")
+            if not isinstance(prompt, dict):
+                raise RuntimeError("Koolook Loop Status needs hidden PROMPT data.")
+            if unique_id is None:
+                raise RuntimeError("Koolook Loop Status needs hidden UNIQUE_ID data.")
+            if not index_node_id:
+                raise RuntimeError("Set index_node_id to the easy int frame index node.")
+            if index_node_id not in prompt:
+                raise RuntimeError(
+                    f"index_node_id {index_node_id!r} is not a node in this workflow. "
+                    "Connect the loop status node's index input to your easy int "
+                    "frame-index node, or set index_node_id to that node's id."
+                )
+            server_url = _resolve_server_url(server_url)
+            if not server_url:
+                raise RuntimeError("Set server_url to the running ComfyUI server.")
+            try:
+                _probe_server(server_url)
+            except (OSError, urllib.error.URLError, TimeoutError) as exc:
+                raise RuntimeError(f"ComfyUI server is not reachable: {server_url}") from exc
+        status = build_status(label or "loop", index, total, filepath)
+        print(f"[Koolook Loop Status] {status}")
+        if should_queue and index_note:
+            print(f"[Koolook Loop Status] {index_note}")
+        if should_queue:
+            queue_key = f"{unique_id or 'loop-status'}:{frame}->{next_index}"
+            queued = False
+            with _ACTIVE_QUEUE_KEYS_LOCK:
+                if queue_key not in _ACTIVE_QUEUE_KEYS:
+                    _ACTIVE_QUEUE_KEYS.add(queue_key)
+                    queued = True
+            if queued:
+                thread = threading.Thread(
+                    target=_queue_next_prompt,
+                    kwargs={
+                        "prompt": prompt,
+                        "index_node_id": index_node_id,
+                        "next_index": next_index,
+                        "server_url": server_url,
+                        "queue_key": queue_key,
+                        "filepath": str(filepath or ""),
+                        "remaining_auto_queue_depth": remaining_depth - 1,
+                    },
+                    daemon=True,
+                )
+                thread.start()
+                print(f"[Koolook Loop Status] queued next index {next_index}/{total - 1}")
+        return (value, status)
+
+
+NODE_CLASS_MAPPINGS = {
+    "Koolook_LoopStatus": KoolookLoopStatus,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "Koolook_LoopStatus": "Koolook Loop Status",
+}

ComfyUI/custom_nodes/koolook/k_publish_contract.py

@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ComfyUI-Koolook - publish contract nodes
+# Copyright (C) 2026 ComfyUI-Koolook contributors (kforgelabs).
+"""Controlled nodes for declaring externally published setup fields."""
+
+from __future__ import annotations
+
+
+INPUT_MODES: tuple[str, ...] = ("EXR", "QT", "Img", "Prompt")
+INPUT_MODE_TO_INDEX = {name: index for index, name in enumerate(INPUT_MODES)}
+
+
+def _resolve_mode_index(mode) -> int:
+    if isinstance(mode, bool):
+        return INPUT_MODE_TO_INDEX["Img"]
+    if isinstance(mode, int) and 0 <= mode < len(INPUT_MODES):
+        return mode
+    text = str(mode).strip()
+    if text.isdigit():
+        index = int(text)
+        if 0 <= index < len(INPUT_MODES):
+            return index
+    return INPUT_MODE_TO_INDEX.get(text, INPUT_MODE_TO_INDEX["Img"])
+
+
+class Koolook_PublishInput:
+    """App-facing setup inputs with stable output names for maintainers."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "mode": (
+                    list(INPUT_MODES),
+                    {
+                        "default": "Img",
+                        "tooltip": "Source mode exposed to the external app. The switch output keeps this mode's stable numeric index.",
+                    },
+                ),
+                "sequence_folder": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Directory path for sequence sources such as EXR or numbered image frames.",
+                    },
+                ),
+                "qt_file": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Full path to one QuickTime/video file, including directory and filename.",
+                    },
+                ),
+                "single_file": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Full path to one still image or single source file.",
+                    },
+                ),
+                "prompt": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Prompt text field for setups that route a text prompt through the published app surface.",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING", "STRING", "STRING", "STRING", "INT")
+    RETURN_NAMES = ("sequence_folder", "qt_file", "single_file", "prompt", "switch")
+    CATEGORY = "Koolook/Publish"
+    FUNCTION = "run"
+    DESCRIPTION = "Declare source inputs for a workflow published to an external app."
+
+    def run(
+        self,
+        mode: str,
+        sequence_folder: str,
+        qt_file: str,
+        single_file: str,
+        prompt: str,
+    ):
+        return (
+            sequence_folder,
+            qt_file,
+            single_file,
+            prompt,
+            _resolve_mode_index(mode),
+        )
+
+
+class Koolook_PublishOutput:
+    """App-facing setup output controls."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "folder": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Destination folder exposed to the external app and wired into downstream writer/path nodes.",
+                    },
+                ),
+                "name": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Base output name exposed to the external app.",
+                    },
+                ),
+                "version": (
+                    "STRING",
+                    {
+                        "default": "1",
+                        "multiline": False,
+                        "tooltip": "Output version token or number exposed to the external app.",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING", "STRING", "STRING")
+    RETURN_NAMES = ("folder", "name", "version")
+    CATEGORY = "Koolook/Publish"
+    FUNCTION = "run"
+    DESCRIPTION = "Declare output folder, name, and version controls for a published setup."
+
+    def run(self, folder: str, name: str, version: str):
+        return (folder, name, version)
+
+
+class Koolook_PublishResult:
+    """Resolved setup result surfaced back to the external app."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "result": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Resolved result path, folder, or status string to show after the external app run finishes.",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("result",)
+    CATEGORY = "Koolook/Publish"
+    FUNCTION = "run"
+    OUTPUT_NODE = True
+    DESCRIPTION = "Report a resolved setup result string back to the published setup runner."
+
+    def run(self, result: str):
+        return {"ui": {"text": [result]}, "result": (result,)}
+
+
+class Koolook_PublishRouter:
+    """Switch-aligned payload router for externally published setup outputs."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "selector": (
+                    "INT",
+                    {
+                        "default": INPUT_MODE_TO_INDEX["Img"],
+                        "min": 0,
+                        "max": len(INPUT_MODES) - 1,
+                        "tooltip": "Switch index from Koolook Publish Input. Published setup runs keep only the matching writer branch.",
+                    },
+                ),
+                "payload": (
+                    "*",
+                    {
+                        "tooltip": "Main workflow payload to send to the switch-aligned writer branches.",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("*", "*", "*", "*")
+    RETURN_NAMES = INPUT_MODES
+    CATEGORY = "Koolook/Publish"
+    FUNCTION = "route"
+    DESCRIPTION = "Route one payload into switch-aligned writer branches for published setup runs."
+
+    def route(self, selector: int, payload):
+        return (payload, payload, payload, payload)
+
+
+NODE_CLASS_MAPPINGS = {
+    "Koolook_PublishInput": Koolook_PublishInput,
+    "Koolook_PublishOutput": Koolook_PublishOutput,
+    "Koolook_PublishResult": Koolook_PublishResult,
+    "Koolook_PublishRouter": Koolook_PublishRouter,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "Koolook_PublishInput": "Koolook Publish Input",
+    "Koolook_PublishOutput": "Koolook Publish Output",
+    "Koolook_PublishResult": "Koolook Publish Result",
+    "Koolook_PublishRouter": "Koolook Publish Router",
+}

ComfyUI/custom_nodes/koolook/k_video_combine.py

@@ -0,0 +1,907 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ComfyUI-Koolook — Easy Video Combine
+# Copyright (C) 2026 ComfyUI-Koolook contributors (kforgelabs).
+#
+# This file is part of ComfyUI-Koolook, licensed under GPL-3.0-or-later.
+# See the LICENSE file at the repo root for the full text.
+#
+# Runtime composition over Kosinkadink/ComfyUI-VideoHelperSuite (GPL-3.0).
+# No VHS source is copied here — Easy_VideoCombine subclasses
+# VHS_VideoCombine and scoped-patches folder_paths.get_save_image_path
+# for the duration of one combine_video() call, letting upstream's
+# encoder run untouched while the output is redirected to an absolute
+# path on disk. If VHS isn't installed alongside Koolook, the node is
+# simply not registered.
+#
+# The os.path.isabs(filename_prefix) discrimination pattern is borrowed
+# from spacepxl/ComfyUI-HQ-Image-Save's SaveEXR (MIT) — same idea: one
+# field carries both relative (sandboxed) and absolute (direct) paths
+# so no new pin is needed on the canvas. See forks/THIRD_PARTY.md for
+# the full attribution + change log.
+"""Path-aware Video Combine for ComfyUI-Koolook.
+
+Exposes ``Easy_VideoCombine`` (display name *Easy Video Combine
+(Koolook)*, category ``Koolook/Video``). Identical to VHS's
+``Video Combine`` except an absolute ``filename_prefix`` writes
+directly to that location, and an optional ``create_path_if_missing``
+toggle controls whether the parent directory is auto-created.
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import re
+from pathlib import Path
+from typing import Optional, Tuple
+
+try:
+    from .koolook_versioning import (
+        is_auto_version,
+        next_version_token,
+        resolve_version_token,
+    )
+except ImportError:  # pragma: no cover - standalone (pytest / tooling)
+    from koolook_versioning import (
+        is_auto_version,
+        next_version_token,
+        resolve_version_token,
+    )
+
+try:
+    import folder_paths  # ComfyUI core; always present at runtime.
+    _KOLOOK_VIDEO_FORMATS_DIR = Path(__file__).resolve().parent / "video_formats"
+    if _KOLOOK_VIDEO_FORMATS_DIR.exists():
+        _paths, _exts = folder_paths.folder_names_and_paths.get(
+            "VHS_video_formats",
+            ((), {".json"}),
+        )
+        _format_path = str(_KOLOOK_VIDEO_FORMATS_DIR)
+        if _format_path not in _paths:
+            folder_paths.folder_names_and_paths["VHS_video_formats"] = (
+                tuple(_paths) + (_format_path,),
+                set(_exts) | {".json"},
+            )
+
+    # Reach the VHS VideoCombine class through ComfyUI's global node
+    # registry rather than `from videohelpersuite.nodes import ...`.
+    # VHS uses relative imports internally (`from .logger import ...`,
+    # `from .utils import ...`) which only resolve correctly when VHS
+    # is loaded through ComfyUI's custom-node loader, not through a
+    # plain absolute import. The global registry is the documented
+    # cross-pack interface — ComfyUI populates it as each pack loads,
+    # and Koolook loads after VHS in every install we've seen because
+    # `comfyui-videohelpersuite` sorts before `koolook` (and even an
+    # uppercase `ComfyUI-VideoHelperSuite` sorts before
+    # `ComfyUI-Koolook` if both are present). If for some reason VHS
+    # isn't loaded yet, the lookup returns None and we self-skip with
+    # a clear message.
+    import nodes as _comfy_nodes_module
+    _VHS_VideoCombine = _comfy_nodes_module.NODE_CLASS_MAPPINGS.get("VHS_VideoCombine")
+    if _VHS_VideoCombine is None:
+        raise RuntimeError(
+            "VHS_VideoCombine not present in ComfyUI's NODE_CLASS_MAPPINGS "
+            "at Koolook load time. Either ComfyUI-VideoHelperSuite isn't "
+            "installed, or it loaded after Koolook (unexpected — check "
+            "custom_nodes folder names)."
+        )
+    _VHS_AVAILABLE = True
+    _VHS_IMPORT_ERROR: Optional[BaseException] = None
+except (ImportError, RuntimeError) as _exc:
+    _VHS_AVAILABLE = False
+    _VHS_IMPORT_ERROR = _exc
+    _VHS_VideoCombine = None  # type: ignore[assignment]
+
+
+def _resolve_abs_target(
+    filename_prefix: str,
+    create_path_if_missing: bool,
+) -> Optional[Tuple[str, str]]:
+    """Discriminate relative vs absolute ``filename_prefix``.
+
+    Returns ``None`` when the prefix is relative — caller should let
+    upstream's sandboxed flow handle it unchanged. Returns
+    ``(abs_dir, abs_basename)`` when the prefix is absolute; upstream's
+    counter pattern will append ``"_<counter:05>.<ext>"`` to
+    ``abs_basename`` inside ``abs_dir``.
+
+    Raises ``FileNotFoundError`` if the parent directory does not exist
+    and ``create_path_if_missing`` is ``False`` — a typo in a render
+    path should surface as a clear error, not silently spawn a stray
+    directory tree. Raises ``ValueError`` if the absolute prefix has no
+    filename component (e.g. a bare drive root like ``"C:\\"``).
+    """
+    if not os.path.isabs(filename_prefix):
+        return None
+
+    normed = os.path.normpath(filename_prefix)
+    if os.path.isdir(normed):
+        abs_dir = normed
+        abs_base = os.path.basename(normed.rstrip("/\\"))
+        if abs_base == "":
+            raise ValueError(
+                f"filename_prefix '{filename_prefix}' is an absolute directory "
+                f"but has no usable folder name for the filename root."
+            )
+        return abs_dir, abs_base
+
+    abs_dir = os.path.dirname(normed)
+    abs_base = os.path.basename(normed)
+
+    if abs_base == "":
+        raise ValueError(
+            f"filename_prefix '{filename_prefix}' is an absolute path but "
+            f"has no filename component. Append a filename root, e.g. "
+            f"'{normed.rstrip(os.sep)}{os.sep}clipname'."
+        )
+
+    if not os.path.exists(abs_dir):
+        if create_path_if_missing:
+            os.makedirs(abs_dir, exist_ok=True)
+        else:
+            raise FileNotFoundError(
+                f"Directory does not exist: {abs_dir}. Enable "
+                f"'create_path_if_missing' on the Easy Video Combine node "
+                f"to auto-create it."
+            )
+
+    return abs_dir, abs_base
+
+
+_SENTINEL_STRINGS = ("undefined", "null", "none")
+
+
+def _normalize_text_input(value) -> str:
+    """Coerce a ComfyUI STRING widget value to a clean Python string.
+
+    ComfyUI's frontend has a long-running quirk: when a STRING input
+    with an empty default sits untouched, the value sometimes arrives
+    at the backend as the literal string ``"undefined"`` (or ``"null"``
+    / ``"None"``) instead of ``""``. Treating those as valid input
+    causes nonsensical ``undefined/`` subdirectories on disk.
+
+    Also defends against:
+    - Surrounding quotes (users paste paths from Explorer with quotes).
+    - Trailing whitespace including newlines (WAS Text Multiline can
+      leave a trailing newline when the user pressed Enter at the end).
+    - Embedded sentinel components separated by a newline (a multi-line
+      Text Multiline node with a second sentinel-looking line).
+
+    Any sentinel string (case-insensitive, post-strip) becomes ``""``;
+    everything else is the cleaned value.
+    """
+    if value is None:
+        return ""
+    s = str(value).strip().strip('"').strip("'").strip()
+    # If a newline split the value across lines, take the first
+    # non-empty non-sentinel line.
+    if "\n" in s or "\r" in s:
+        for line in s.replace("\r", "\n").split("\n"):
+            line = line.strip()
+            if line and line.lower() not in _SENTINEL_STRINGS:
+                s = line
+                break
+        else:
+            s = ""
+    if s.lower() in _SENTINEL_STRINGS:
+        return ""
+    return s
+
+
+def _normalize_bool_input(value, default: bool = False) -> bool:
+    """Coerce ComfyUI widget values to a real bool.
+
+    This is intentionally stricter than Python truthiness. A corrupted
+    saved workflow can shift a format-widget value such as ``"hq"`` into
+    the ``pingpong`` slot; ``bool("hq")`` would enable ping-pong and
+    double the video. Unknown strings fall back to ``default``.
+    """
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, (int, float)):
+        return bool(value)
+    s = str(value).strip().lower()
+    if s in ("true", "1", "yes", "on"):
+        return True
+    if s in ("false", "0", "no", "off", ""):
+        return False
+    return default
+
+
+def _strip_sentinel_components(path: str) -> str:
+    """Remove any path component that's exactly a sentinel string.
+
+    Belt-and-suspenders defense: if anything upstream of us managed
+    to inject ``undefined`` / ``null`` / ``None`` as a path component
+    (despite the per-field normalization above), drop it before the
+    path reaches the filesystem. Preserves the rest of the path,
+    including the drive root on Windows.
+
+    Returns the path unchanged if no sentinels found, so this is a
+    cheap pass for the common case.
+    """
+    if not path:
+        return path
+    # Split on whichever separator is present, defaulting to os.sep.
+    sep = "\\" if "\\" in path else "/"
+    parts = path.split(sep)
+    cleaned = [
+        p for p in parts
+        if p == "" or p.lower() not in _SENTINEL_STRINGS
+    ]
+    if len(cleaned) == len(parts):
+        return path
+    return sep.join(cleaned)
+
+
+def _compose_prefix(filename_prefix: str, output_directory: str) -> str:
+    """Combine ``output_directory`` + ``filename_prefix`` into one path-prefix.
+
+    When ``output_directory`` is empty, ``filename_prefix`` is returned
+    unchanged — it retains the overloaded "relative-or-absolute prefix"
+    semantics for back-compat with users who like the one-field flow.
+
+    When ``output_directory`` is set, only the basename of
+    ``filename_prefix`` becomes the filename root (any path components
+    the user accidentally typed there are stripped, so they can change
+    the name without re-typing the directory). The directory keeps its
+    shape (absolute or relative), so the downstream
+    :func:`_resolve_abs_target` discrimination still works on the
+    composed prefix.
+    """
+    if not output_directory:
+        return filename_prefix
+    name_root = os.path.basename(filename_prefix.rstrip("/\\")) or "AnimateDiff"
+    clean_dir = output_directory.rstrip("/\\")
+    return clean_dir + os.sep + name_root
+
+
+def _display_format_name(format_name: str) -> str:
+    """Hide the JSON suffix VHS exposes for external Koolook presets."""
+    if format_name.startswith("video/koolook-") and format_name.endswith(".json"):
+        return format_name[:-5]
+    return format_name
+
+
+def _runtime_format_name(format_name: str) -> str:
+    """Map cleaned Koolook display names back to VHS's external file names."""
+    if format_name.startswith("video/koolook-") and not format_name.endswith(".json"):
+        return format_name + ".json"
+    return format_name
+
+
+def _metadata_sidecar_path(output_files: list[str]) -> Optional[str]:
+    """Pick the JSON sidecar path from VHS's output file list."""
+    if not output_files:
+        return None
+    return os.path.splitext(output_files[0])[0] + ".json"
+
+
+def _add_metadata_json_sidecar(
+    result,
+    metadata_payload: dict,
+    save_metadata_json: bool,
+    save_metadata_png: bool,
+):
+    """Write a workflow metadata JSON next to VHS's output and return result."""
+    if not save_metadata_json or not isinstance(result, dict):
+        return result
+    try:
+        output_files = result.get("result", ((None, []),))[0][1]
+        if not isinstance(output_files, list):
+            return result
+        json_path = _metadata_sidecar_path(output_files)
+        if not json_path:
+            return result
+        Path(json_path).write_text(
+            json.dumps(metadata_payload, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        if save_metadata_png:
+            output_files.append(json_path)
+        elif output_files and output_files[0].lower().endswith(".png"):
+            output_files[0] = json_path
+        else:
+            output_files.insert(0, json_path)
+        ui = result.get("ui", {})
+        gifs = ui.get("gifs", [])
+        if gifs and isinstance(gifs[0], dict) and gifs[0].get("workflow", "").endswith(".png"):
+            gifs[0]["workflow"] = os.path.basename(json_path)
+    except Exception as exc:
+        print(f"[Easy_VideoCombine] metadata JSON sidecar skipped: {exc!r}")
+    return result
+
+
+def _remove_audio_suffix_from_result(result, keep_silent_intermediate: bool):
+    """Rename VHS's final ``-audio`` mux output to the clean base name."""
+    if keep_silent_intermediate or not isinstance(result, dict):
+        return result
+    try:
+        output_files = result.get("result", ((None, []),))[0][1]
+        if not isinstance(output_files, list) or not output_files:
+            return result
+        final_path = Path(output_files[-1])
+        if final_path.stem.endswith("-audio"):
+            clean_path = final_path.with_name(final_path.stem[:-6] + final_path.suffix)
+            if clean_path.exists() and clean_path != final_path:
+                clean_path.unlink()
+            final_path.replace(clean_path)
+            output_files[-1] = str(clean_path)
+            ui = result.get("ui", {})
+            gifs = ui.get("gifs", [])
+            if gifs and isinstance(gifs[0], dict):
+                gifs[0]["filename"] = clean_path.name
+                gifs[0]["fullpath"] = str(clean_path)
+        output_files[:] = [
+            path for path in output_files
+            if not isinstance(path, str) or os.path.exists(path)
+        ]
+        deduped = []
+        for path in output_files:
+            if path not in deduped:
+                deduped.append(path)
+        output_files[:] = deduped
+    except Exception as exc:
+        print(f"[Easy_VideoCombine] audio suffix cleanup skipped: {exc!r}")
+    return result
+
+
+# VHS appends a zero-padded counter to every output (e.g. ``clip_00001.mp4``).
+# Strict-version mode strips it so the filename is exactly ``<root>_<token>``.
+_COUNTER_RE = re.compile(r"_\d{5}$")
+
+
+def _build_sidecar_workflow(prompt, extra_pnginfo, creation_time):
+    """Build the JSON sidecar as a **drag-loadable ComfyUI workflow**.
+
+    ComfyUI restores a workflow from the litegraph graph at the TOP LEVEL of
+    the JSON (``nodes`` / ``links`` / ``last_node_id`` ...). That graph is
+    carried in ``extra_pnginfo['workflow']``, so we write it directly —
+    dropping the sidecar onto the canvas reloads the graph, exactly like
+    ComfyUI's own "Save". ``CreationTime`` is tucked into the graph's
+    ``extra`` so it is preserved without breaking loadability.
+
+    Falls back to ``{CreationTime, prompt}`` when no litegraph graph is
+    available (e.g. the headless / API ``/prompt`` path, which carries only
+    the API-format prompt, not a positioned graph) so the sidecar is never
+    empty — just not drag-loadable in that case.
+    """
+    workflow = extra_pnginfo.get("workflow") if isinstance(extra_pnginfo, dict) else None
+    if isinstance(workflow, dict) and "nodes" in workflow:
+        graph = dict(workflow)
+        extra = dict(graph.get("extra") or {})
+        extra.setdefault("CreationTime", creation_time)
+        graph["extra"] = extra
+        return graph
+    payload = {"CreationTime": creation_time}
+    if prompt is not None:
+        payload["prompt"] = prompt
+    return payload
+
+
+def _append_version_to_prefix(prefix: str, token: str) -> str:
+    """Suffix the path-prefix's filename root with ``_<token>``.
+
+    ``effective_prefix`` always ends in a filename component at the call site
+    (``_compose_prefix`` guarantees a name root, never a bare directory), so the
+    token attaches directly to the end — e.g. ``E:/renders/clip`` ->
+    ``E:/renders/clip_v001``.
+    """
+    if not token:
+        return prefix
+    return f"{prefix}_{token}"
+
+
+def _auto_version_scan_target(effective_prefix: str) -> tuple[str, str]:
+    """Return ``(directory, name)`` matching where VHS will write the prefix."""
+    name = os.path.basename(effective_prefix.rstrip("/\\"))
+    directory = os.path.dirname(effective_prefix)
+    if os.path.isabs(effective_prefix):
+        return directory, name
+    output_root = folder_paths.get_output_directory()
+    return os.path.normpath(os.path.join(output_root, directory)), name
+
+
+def _coerce_version_input(raw):
+    """Defend the ``version`` field against a stale boolean.
+
+    Removing the old ``keep_silent_intermediate`` BOOLEAN widget shifts a saved
+    workflow's stored value into the new same-position ``version`` STRING slot
+    (widgets serialize by index — see docs/maintainers/node-versioning.md). A
+    leftover bool would otherwise become the literal token ``"False"`` / ``"True"``
+    and silently force strict mode (``clip_False.mp4``). Treat any boolean — or
+    its string form — as "no version" so old workflows fall back to the legacy
+    counter, exactly as before.
+    """
+    if isinstance(raw, bool):
+        return ""
+    if str(raw).strip().lower() in ("true", "false"):
+        return ""
+    return raw
+
+
+def _write_sidecar(json_path: str, metadata_payload: dict) -> bool:
+    """Write the metadata JSON sidecar to ``json_path``. True on success."""
+    try:
+        Path(json_path).write_text(
+            json.dumps(metadata_payload, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        return True
+    except Exception as exc:
+        print(f"[Easy_VideoCombine] metadata JSON sidecar skipped: {exc!r}")
+        return False
+
+
+def _strip_counter_path(path_str: str, enable_overwrite: bool) -> str:
+    """Rename a rendered video to drop VHS's trailing ``_NNNNN`` counter.
+
+    Collision: if the counter-free name already exists and ``enable_overwrite``
+    is False, keep the counter (return the original path) so nothing is
+    clobbered; if True, replace it. Returns the resulting path string.
+    """
+    p = Path(path_str)
+    stripped = _COUNTER_RE.sub("", p.stem)
+    if stripped == p.stem:
+        return path_str
+    candidate = p.with_name(stripped + p.suffix)
+    if candidate == p:
+        return path_str
+    if candidate.exists():
+        if not enable_overwrite:
+            print(
+                f"[Easy_VideoCombine] {candidate.name} exists; kept counter "
+                f"suffix to avoid overwrite (enable_overwrite to replace)."
+            )
+            return path_str
+        candidate.unlink()
+        print(f"[Easy_VideoCombine] replaced existing {candidate.name}.")
+    p.replace(candidate)
+    return str(candidate)
+
+
+def _finalize_strict_version_output(
+    result,
+    enable_overwrite: bool,
+    metadata_payload: dict,
+    save_metadata_json: bool,
+    save_metadata_png: bool = False,
+):
+    """Strict-version finalize: strip VHS's ``_NNNNN`` counter from the final
+    video so the name is exactly ``<root>_<token>.<ext>``, align a kept
+    metadata PNG to the same stem, and write the JSON sidecar beside them.
+
+    Collision is handled in :func:`_strip_counter_path` (lossless unless
+    ``enable_overwrite``); the sidecar always matches the video's final name.
+    """
+    if not isinstance(result, dict):
+        return result
+    try:
+        output_files = result.get("result", ((None, []),))[0][1]
+        if not isinstance(output_files, list) or not output_files:
+            return result
+
+        new_video = _strip_counter_path(output_files[-1], enable_overwrite)
+        if new_video != output_files[-1]:
+            output_files[-1] = new_video
+            ui = result.get("ui", {})
+            gifs = ui.get("gifs", [])
+            if gifs and isinstance(gifs[0], dict):
+                gifs[0]["filename"] = os.path.basename(new_video)
+                gifs[0]["fullpath"] = new_video
+        video_stem_path = os.path.splitext(new_video)[0]
+
+        # Keep the metadata PNG (when requested) under the video's stem so the
+        # PNG/JSON/video trio share one name; otherwise it's dropped below.
+        if (
+            save_metadata_png
+            and isinstance(output_files[0], str)
+            and output_files[0].lower().endswith(".png")
+            and output_files[0] != new_video
+        ):
+            png = Path(output_files[0])
+            aligned = png.with_name(os.path.basename(video_stem_path) + png.suffix)
+            if aligned != png:
+                try:
+                    if aligned.exists():
+                        aligned.unlink()
+                    png.replace(aligned)
+                    output_files[0] = str(aligned)
+                except OSError as exc:
+                    print(f"[Easy_VideoCombine] metadata PNG rename skipped: {exc!r}")
+
+        if save_metadata_json:
+            json_path = video_stem_path + ".json"
+            if _write_sidecar(json_path, metadata_payload):
+                if save_metadata_png:
+                    if json_path not in output_files:
+                        output_files.append(json_path)
+                elif (
+                    isinstance(output_files[0], str)
+                    and output_files[0].lower().endswith(".png")
+                ):
+                    output_files[0] = json_path
+                elif json_path not in output_files:
+                    output_files.insert(0, json_path)
+                ui = result.get("ui", {})
+                gifs = ui.get("gifs", [])
+                if (
+                    gifs
+                    and isinstance(gifs[0], dict)
+                    and str(gifs[0].get("workflow", "")).endswith(".png")
+                ):
+                    gifs[0]["workflow"] = os.path.basename(json_path)
+    except Exception as exc:
+        print(f"[Easy_VideoCombine] strict-version finalize skipped: {exc!r}")
+    return result
+
+
+def _finalize_output(
+    result,
+    version_token: str,
+    enable_overwrite: bool,
+    metadata_payload: dict,
+    save_metadata_json: bool,
+    save_metadata_png: bool,
+):
+    """Route to strict-version finalize (token set -> counter stripped) or the
+    legacy sidecar attach (token empty -> VHS counter kept)."""
+    if version_token:
+        return _finalize_strict_version_output(
+            result, enable_overwrite, metadata_payload, save_metadata_json, save_metadata_png
+        )
+    return _add_metadata_json_sidecar(
+        result, metadata_payload, save_metadata_json, save_metadata_png
+    )
+
+
+_VIDEO_OUTPUT_EXTENSIONS = {
+    ".avi",
+    ".gif",
+    ".m4v",
+    ".mkv",
+    ".mov",
+    ".mp4",
+    ".webm",
+}
+
+
+def _final_video_path_from_result(result) -> str:
+    """Return the final video path from VHS's mixed output-file list.
+
+    VHS/Koolook sidecars can sit before or after the rendered clip. If more
+    than one video-like path appears, the later one is treated as final because
+    VHS appends muxed/renamed outputs after earlier intermediates.
+    """
+    if not isinstance(result, dict):
+        return ""
+    try:
+        output_files = result.get("result", ((None, []),))[0][1]
+    except (IndexError, TypeError):
+        return ""
+    if not isinstance(output_files, list):
+        return ""
+    string_paths = [path for path in output_files if isinstance(path, str)]
+    for path in reversed(string_paths):
+        if Path(path).suffix.lower() in _VIDEO_OUTPUT_EXTENSIONS:
+            return path
+    return string_paths[-1] if string_paths else ""
+
+
+def _final_json_path_from_result(result, video_path: str = "") -> str:
+    """Return the JSON sidecar path from VHS/Koolook's output-file list.
+
+    Normal combine runs include the JSON in ``result``. The video-stem fallback
+    matches Koolook's current sidecar convention and is only for defensive
+    best-effort output when upstream omits the JSON path from the list.
+    """
+    if isinstance(result, dict):
+        try:
+            output_files = result.get("result", ((None, []),))[0][1]
+        except (IndexError, TypeError):
+            output_files = []
+        if isinstance(output_files, list):
+            for path in output_files:
+                if isinstance(path, str) and Path(path).suffix.lower() == ".json":
+                    return os.path.normpath(path)
+    if video_path:
+        return os.path.splitext(os.path.normpath(video_path))[0] + ".json"
+    return ""
+
+
+def _video_path_parts(path: str) -> Tuple[str, str, str]:
+    """Return ``(full_path, directory, filename)`` for loader wiring."""
+    if not path:
+        return ("", "", "")
+    normed = os.path.normpath(path)
+    return (normed, os.path.dirname(normed), os.path.basename(normed))
+
+
+def _append_video_path_outputs(result):
+    """Append clean string outputs without disturbing VHS's original output."""
+    video_path, video_directory, video_name = _video_path_parts(_final_video_path_from_result(result))
+    json_path = _final_json_path_from_result(result, video_path)
+    if not isinstance(result, dict):
+        return {
+            "result": (result, video_path, video_directory, video_name, json_path),
+        }
+    existing = result.get("result", tuple())
+    if not isinstance(existing, tuple):
+        existing = (existing,)
+    result["result"] = existing + (video_path, video_directory, video_name, json_path)
+    return result
+
+
+if _VHS_AVAILABLE:
+    class Easy_VideoCombine(_VHS_VideoCombine):
+        """Video Combine variant with absolute-path output."""
+
+        CATEGORY = "Koolook/Video"
+        DESCRIPTION = "Video Combine variant with absolute-path output."
+        RETURN_TYPES = tuple(getattr(_VHS_VideoCombine, "RETURN_TYPES", ("VHS_FILENAMES",))) + (
+            "STRING",
+            "STRING",
+            "STRING",
+            "STRING",
+        )
+        RETURN_NAMES = tuple(getattr(_VHS_VideoCombine, "RETURN_NAMES", ("Filenames",))) + (
+            "video_path",
+            "video_directory",
+            "video_name",
+            "json_path",
+        )
+
+        @classmethod
+        def INPUT_TYPES(cls):
+            types = _VHS_VideoCombine.INPUT_TYPES()
+            format_options, format_config = types["required"]["format"]
+            cleaned_format_options = []
+            cleaned_format_widgets = {}
+            format_widgets = dict(format_config.get("formats", {}))
+            for option in format_options:
+                cleaned = _display_format_name(option)
+                cleaned_format_options.append(cleaned)
+                if option in format_widgets:
+                    cleaned_format_widgets[cleaned] = format_widgets[option]
+            for option, widgets in format_widgets.items():
+                cleaned_format_widgets.setdefault(_display_format_name(option), widgets)
+            format_options = cleaned_format_options
+            format_config = {**format_config, "formats": cleaned_format_widgets}
+            if "video/ProRes" in format_options:
+                types["required"]["format"] = (
+                    format_options,
+                    {**format_config, "default": "video/ProRes"},
+                )
+            types["required"]["filename_prefix"] = (
+                "STRING",
+                {
+                    "default": "AnimateDiff",
+                    "tooltip": "Filename root. Counter and extension are appended.",
+                },
+            )
+            # Upstream VHS uses save_output to choose ComfyUI output/ vs temp/.
+            # Easy_VideoCombine is an explicit file-writer, and absolute-path
+            # mode ignores that distinction, so hiding it avoids a misleading
+            # toggle while preserving the persistent-output behavior.
+            types["required"].pop("save_output", None)
+            types["optional"]["output_directory"] = (
+                "STRING",
+                {
+                    "default": "",
+                    "tooltip": "Absolute or relative output directory.",
+                },
+            )
+            types["optional"]["create_path_if_missing"] = (
+                "BOOLEAN",
+                {
+                    "default": False,
+                    "tooltip": "Auto-create the output directory if missing.",
+                },
+            )
+            types["optional"]["save_metadata_png"] = (
+                "BOOLEAN",
+                {
+                    "default": False,
+                    "tooltip": "Save the first-frame PNG with embedded workflow metadata.",
+                },
+            )
+            types["optional"]["save_metadata_json"] = (
+                "BOOLEAN",
+                {
+                    "default": True,
+                    "tooltip": "Save workflow metadata as a JSON sidecar.",
+                },
+            )
+            types["optional"]["version"] = (
+                "STRING",
+                {
+                    "default": "",
+                    "tooltip": (
+                        "Strict version token (e.g. 'v001'), typically wired "
+                        "from a global version node. When set, the output is "
+                        "named exactly <prefix>_<version>.<ext> with NO automatic "
+                        "_NNNNN counter. Leave empty to keep VHS's automatic "
+                        "counter (the casual default)."
+                    ),
+                },
+            )
+            types["optional"]["enable_overwrite"] = (
+                "BOOLEAN",
+                {
+                    "default": False,
+                    "tooltip": (
+                        "Strict-version mode only. If the versioned filename "
+                        "already exists: on = replace it; off = keep VHS's "
+                        "counter for this render so nothing is overwritten."
+                    ),
+                },
+            )
+            return types
+
+        def combine_video(self, *args, **kwargs):
+            # Defensive normalization — the frontend occasionally sends
+            # the literal string "undefined" for STRING widgets with
+            # empty defaults. Coerce those to "" before any path
+            # composition so we never create an `undefined/` subdir.
+            filename_prefix = _normalize_text_input(
+                kwargs.get("filename_prefix", "AnimateDiff")
+            ) or "AnimateDiff"
+            kwargs["filename_prefix"] = filename_prefix
+            output_directory = _normalize_text_input(
+                kwargs.pop("output_directory", "")
+            )
+            kwargs["pingpong"] = _normalize_bool_input(
+                kwargs.get("pingpong", False),
+                default=False,
+            )
+            if "format" in kwargs:
+                kwargs["format"] = _runtime_format_name(kwargs["format"])
+            kwargs["save_output"] = True
+            create_path_if_missing = _normalize_bool_input(
+                kwargs.pop("create_path_if_missing", False),
+                default=False,
+            )
+            save_metadata_png = _normalize_bool_input(
+                kwargs.pop("save_metadata_png", False),
+                default=False,
+            )
+            save_metadata_json = _normalize_bool_input(
+                kwargs.pop("save_metadata_json", True),
+                default=True,
+            )
+            keep_silent_intermediate = _normalize_bool_input(
+                kwargs.pop("keep_silent_intermediate", False),
+                default=False,
+            )
+            enable_overwrite = _normalize_bool_input(
+                kwargs.pop("enable_overwrite", False),
+                default=False,
+            )
+            # Strict versioning: a wired/typed token replaces VHS's automatic
+            # _NNNNN counter with a deterministic <prefix>_<token>.<ext> name.
+            # Empty -> the counter stays (the casual, non-professional default).
+            # The token is resolved below, once the output dir + name root are
+            # known (so `auto`/`next` can scan that folder).
+            raw_version = _coerce_version_input(kwargs.pop("version", ""))
+            metadata_payload = _build_sidecar_workflow(
+                kwargs.get("prompt"),
+                kwargs.get("extra_pnginfo"),
+                datetime.datetime.now().isoformat(" ")[:19],
+            )
+
+            # Inject VHS's hidden extra_options flags so upstream handles
+            # metadata PNG and silent-intermediate cleanup according to
+            # Koolook's explicit toggles. Copy extra_pnginfo before mutating
+            # so other nodes referencing the same dict aren't affected.
+            extra_pnginfo = dict(kwargs.get("extra_pnginfo") or {})
+            workflow = dict(extra_pnginfo.get("workflow") or {})
+            extra = dict(workflow.get("extra") or {})
+            extra["VHS_MetadataImage"] = bool(save_metadata_png)
+            extra["VHS_KeepIntermediate"] = bool(keep_silent_intermediate)
+            workflow["extra"] = extra
+            extra_pnginfo["workflow"] = workflow
+            kwargs["extra_pnginfo"] = extra_pnginfo
+
+            # Split-mode: directory + name combined into one effective
+            # prefix that the existing isabs discrimination handles
+            # uniformly. When output_directory is empty this is a no-op.
+            effective_prefix = _compose_prefix(filename_prefix, output_directory)
+            # Belt-and-suspenders: drop any sentinel components that
+            # slipped past per-field normalization (e.g. a path that
+            # already carried `\undefined\` as a literal segment).
+            effective_prefix = _strip_sentinel_components(effective_prefix)
+            # Resolve the version token now that the output dir + name root are
+            # known. `auto`/`next` scans that directory for existing
+            # <name>_vNNN outputs and picks the next free one; otherwise the
+            # typed/wired token is used verbatim.
+            if is_auto_version(raw_version):
+                scan_dir, scan_name = _auto_version_scan_target(effective_prefix)
+                version_token = next_version_token(
+                    scan_dir,
+                    scan_name,
+                )
+            else:
+                version_token = resolve_version_token(raw_version)
+            # Strict versioning bakes the token into the filename root; VHS
+            # then appends its counter, which _finalize_output strips back off.
+            if version_token:
+                effective_prefix = _append_version_to_prefix(effective_prefix, version_token)
+            if effective_prefix != filename_prefix:
+                kwargs["filename_prefix"] = effective_prefix
+                filename_prefix = effective_prefix
+
+            target = _resolve_abs_target(filename_prefix, create_path_if_missing)
+            if target is None:
+                result = super().combine_video(*args, **kwargs)
+                result = _remove_audio_suffix_from_result(
+                    result,
+                    keep_silent_intermediate,
+                )
+                result = _finalize_output(
+                    result,
+                    version_token,
+                    enable_overwrite,
+                    metadata_payload,
+                    save_metadata_json,
+                    save_metadata_png,
+                )
+                return _append_video_path_outputs(result)
+
+            abs_dir, abs_base = target
+
+            # VHS calls folder_paths.get_save_image_path() exactly once
+            # in combine_video(). Patch it to return our absolute target
+            # so the rest of upstream's pipeline (counter scan, metadata
+            # PNG, ffmpeg encode, audio mux, batch manager) writes into
+            # abs_dir/abs_base_*. The patch is scoped to one super() call
+            # and restored in finally to guarantee no leak on exception.
+            #
+            # Concurrency note: ComfyUI executes nodes sequentially within
+            # a workflow and serializes workflows at the prompt level, so
+            # no other node observes the patched function during the call.
+            original_get_save_path = folder_paths.get_save_image_path
+
+            def patched_get_save_path(prefix, output_dir, *_a, **_kw):
+                # VHS expects:
+                # (full_output_folder, filename, counter_seed, subfolder, prefix)
+                # Upstream re-scans full_output_folder for the real
+                # counter, so counter_seed (0) is ignored. subfolder=""
+                # makes the UI preview tile bypass the relative-to-
+                # output-dir link Comfy builds for the /view endpoint.
+                return (abs_dir, abs_base, 0, "", abs_base)
+
+            try:
+                folder_paths.get_save_image_path = patched_get_save_path
+                result = super().combine_video(*args, **kwargs)
+                result = _remove_audio_suffix_from_result(
+                    result,
+                    keep_silent_intermediate,
+                )
+                result = _finalize_output(
+                    result,
+                    version_token,
+                    enable_overwrite,
+                    metadata_payload,
+                    save_metadata_json,
+                    save_metadata_png,
+                )
+                return _append_video_path_outputs(result)
+            finally:
+                folder_paths.get_save_image_path = original_get_save_path
+
+    NODE_CLASS_MAPPINGS = {"Easy_VideoCombine": Easy_VideoCombine}
+    NODE_DISPLAY_NAME_MAPPINGS = {"Easy_VideoCombine": "Easy Video Combine (Koolook)"}
+else:
+    print(
+        f"[Koolook] Easy_VideoCombine skipped: "
+        f"ComfyUI-VideoHelperSuite not importable ({_VHS_IMPORT_ERROR}). "
+        f"Install VHS from ComfyUI-Manager to enable this node."
+    )
+    NODE_CLASS_MAPPINGS = {}
+    NODE_DISPLAY_NAME_MAPPINGS = {}
+
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

ComfyUI/custom_nodes/koolook/k_video_load.py

@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ComfyUI-Koolook - Easy Load Video
+# Copyright (C) 2026 ComfyUI-Koolook contributors (kforgelabs).
+#
+# Runtime composition over Kosinkadink/ComfyUI-VideoHelperSuite (GPL-3.0).
+# No VHS source is copied here. Easy_LoadVideo subclasses VHS_LoadVideoPath
+# and composes a split input_path + video filename into the path string that
+# upstream already knows how to load.
+"""Path-aware Video Helper Suite loader for ComfyUI-Koolook."""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+try:
+    import folder_paths  # ComfyUI core; present at runtime.
+    import nodes as _comfy_nodes_module
+
+    _VHS_LoadVideoPath = _comfy_nodes_module.NODE_CLASS_MAPPINGS.get("VHS_LoadVideoPath")
+    if _VHS_LoadVideoPath is None:
+        raise RuntimeError(
+            "VHS_LoadVideoPath not present in ComfyUI's NODE_CLASS_MAPPINGS "
+            "at Koolook load time. Either ComfyUI-VideoHelperSuite isn't "
+            "installed, or it loaded after Koolook."
+        )
+    # VHS LoadVideoPath wraps the shared decoder with path validation that
+    # rejects absolute/local handoff paths. Existing local videos can use the
+    # same shared decoder directly; fail loudly if a future VHS refactor moves it.
+    _VHS_LOAD_VIDEO_FN = _VHS_LoadVideoPath.load_video.__globals__.get("load_video")
+    if _VHS_LOAD_VIDEO_FN is None:
+        raise RuntimeError("VHS shared load_video function not found.")
+    _VHS_AVAILABLE = True
+    _VHS_IMPORT_ERROR: Optional[BaseException] = None
+except (ImportError, RuntimeError) as _exc:
+    _VHS_AVAILABLE = False
+    _VHS_IMPORT_ERROR = _exc
+    _VHS_LoadVideoPath = None  # type: ignore[assignment]
+    _VHS_LOAD_VIDEO_FN = None
+
+
+# Returned by _compose_input_video_path when input_path is an existing folder
+# with no filename -- typically the unselected branch of an upstream mode switch
+# (e.g. an EXR sequence dir handed to the video loader). load_video turns this
+# into an empty, correctly-shaped result instead of crashing the whole prompt.
+EMPTY_BRANCH_SENTINEL = "\x00__koolook_empty_video_branch__"
+
+_SENTINEL_STRINGS = ("undefined", "null", "none")
+_VIDEO_EXTENSIONS = {
+    ".avi",
+    ".gif",
+    ".m4v",
+    ".mkv",
+    ".mov",
+    ".mp4",
+    ".webm",
+}
+
+
+def _normalize_text_input(value) -> str:
+    """Coerce a ComfyUI STRING widget value to a clean Python string."""
+    if value is None:
+        return ""
+    s = str(value).strip().strip('"').strip("'").strip()
+    if "\n" in s or "\r" in s:
+        for line in s.replace("\r", "\n").split("\n"):
+            line = line.strip()
+            if line and line.lower() not in _SENTINEL_STRINGS:
+                s = line
+                break
+        else:
+            s = ""
+    if s.lower() in _SENTINEL_STRINGS:
+        return ""
+    return s
+
+
+def _clean_text_lines(value) -> list[str]:
+    """Return non-empty, non-sentinel lines from a connected text widget."""
+    if value is None:
+        return []
+    s = str(value).strip().strip('"').strip("'").strip()
+    lines = []
+    for line in s.replace("\r", "\n").split("\n"):
+        line = line.strip().strip('"').strip("'").strip()
+        if line and line.lower() not in _SENTINEL_STRINGS:
+            lines.append(line)
+    return lines
+
+
+def _input_root() -> str:
+    try:
+        return folder_paths.get_input_directory()
+    except Exception:
+        return os.getcwd()
+
+
+def _basename_any_sep(path: str) -> str:
+    return path.rstrip("/\\").replace("\\", "/").rsplit("/", 1)[-1]
+
+
+def _looks_like_video_file(path: str) -> bool:
+    return os.path.splitext(_basename_any_sep(path))[1].lower() in _VIDEO_EXTENSIONS
+
+
+def _strip_outer_quotes(path: str) -> str:
+    return path.strip().strip('"').strip("'").strip()
+
+
+def _is_existing_local_video_path(path: str) -> bool:
+    clean = _strip_outer_quotes(path)
+    return _looks_like_video_file(clean) and os.path.isfile(clean)
+
+
+def _input_path_is_existing_dir(path: str, input_root: str | None = None) -> bool:
+    """True when ``path`` resolves to a real directory on disk.
+
+    Absolute dirs are checked directly; relative dirs are rooted under ComfyUI's
+    input directory, matching how the loader resolves relative paths elsewhere.
+    """
+    candidate = _existing_local_path_candidate(path, input_root)
+    return bool(candidate) and os.path.isdir(candidate)
+
+
+def _existing_local_path_candidate(path: str, input_root: str | None = None) -> str:
+    clean = _strip_outer_quotes(path)
+    if not clean:
+        return ""
+    if os.path.isabs(clean):
+        return os.path.normpath(clean)
+    root = input_root if input_root is not None else _input_root()
+    return os.path.normpath(os.path.join(root, clean))
+
+
+def _normalize_path_input(value, input_root: str | None = None) -> str:
+    """Normalize a path input while preserving wrapped full paths.
+
+    Multiline text can mean either "directory + filename" or a single path
+    wrapped by a text node. Prefer candidates that exist on disk, then candidates
+    that at least look like video files, and otherwise keep the first line.
+    """
+    lines = _clean_text_lines(value)
+    if not lines:
+        return ""
+    if len(lines) == 1:
+        return lines[0]
+
+    joined_text = "".join(lines)
+    joined_path = os.path.join(lines[0].rstrip("/\\"), *lines[1:])
+    candidates = [joined_text, joined_path]
+
+    for candidate in candidates:
+        resolved = _existing_local_path_candidate(candidate, input_root)
+        if os.path.isfile(resolved):
+            return candidate
+
+    for candidate in candidates:
+        if _looks_like_video_file(candidate):
+            return candidate
+
+    return lines[0]
+
+
+def _compose_input_video_path(
+    video: str,
+    input_path: str,
+    input_root: str | None = None,
+) -> str:
+    """Resolve split ``input_path`` + ``video`` into one loader path.
+
+    Empty ``input_path`` is pass-through, so users can still paste a full path
+    or URL into ``video`` exactly like upstream VHS_LoadVideoPath.
+
+    When ``input_path`` is set, ``video`` is treated as a filename field:
+    path components are stripped, then the name is joined under the directory.
+    Absolute directories are used directly; relative directories are rooted in
+    ComfyUI's input directory.
+
+    If ``input_path`` itself points at a video file and ``video`` is empty,
+    that full file path is passed through. This lets
+    ``Easy_VideoCombine.video_path`` wire directly into ``input_path``. If a
+    multiline text node wraps that path, the lines are joined back together
+    before validation/loading.
+
+    When ``input_path`` is empty and ``video`` contains multiple non-empty
+    lines, the first line is treated as the directory and the second as the
+    filename; later lines are ignored. This matches connected text blocks that
+    package a path/name pair for loader handoff.
+    """
+    raw_video_lines = _clean_text_lines(video)
+    input_path = _normalize_path_input(input_path, input_root)
+    if not input_path and len(raw_video_lines) >= 2:
+        input_path = raw_video_lines[0]
+        video = raw_video_lines[1]
+    else:
+        video = _normalize_text_input(video)
+    if not input_path:
+        return video
+
+    clean_dir = input_path.rstrip("/\\")
+    if not video and _looks_like_video_file(clean_dir):
+        if os.path.isabs(clean_dir):
+            return os.path.normpath(clean_dir)
+        root = input_root if input_root is not None else _input_root()
+        return os.path.normpath(os.path.join(root, clean_dir))
+
+    name = _basename_any_sep(video) or video
+    if not name:
+        # input_path is a directory with no filename. If that folder actually
+        # exists it is almost always the unselected branch of an upstream mode
+        # switch -- e.g. an EXR sequence dir routed into the video loader. Signal
+        # a graceful empty so the loader returns nothing instead of crashing the
+        # whole prompt (a lenient sequence loader would just ignore it). A path
+        # that does not exist is a genuine mistake and still raises.
+        if _input_path_is_existing_dir(clean_dir, input_root):
+            return EMPTY_BRANCH_SENTINEL
+        raise ValueError("video must include a filename when input_path is set.")
+
+    if os.path.isabs(clean_dir):
+        return os.path.normpath(os.path.join(clean_dir, name))
+
+    root = input_root if input_root is not None else _input_root()
+    return os.path.normpath(os.path.join(root, clean_dir, name))
+
+
+def _empty_value_for_type(type_name: str):
+    """Build an empty, correctly-typed output value for a VHS return slot.
+
+    ``torch`` is imported lazily so the path-composition logic stays importable
+    (and unit-testable) without torch installed; it is always present at runtime
+    inside ComfyUI.
+    """
+    name = str(type_name)
+    if name in ("IMAGE", "MASK", "LATENT"):
+        import torch
+
+        if name == "IMAGE":
+            return torch.zeros((1, 64, 64, 3), dtype=torch.float32)
+        if name == "MASK":
+            return torch.zeros((1, 64, 64), dtype=torch.float32)
+        return {"samples": torch.zeros((1, 4, 8, 8), dtype=torch.float32)}
+    if name == "AUDIO":
+        import torch
+
+        return {"waveform": torch.zeros((1, 2, 1), dtype=torch.float32), "sample_rate": 44100}
+    if name == "INT":
+        return 0
+    if name == "FLOAT":
+        return 0.0
+    if name == "STRING":
+        return ""
+    if name == "VHS_VIDEOINFO":
+        return {}
+    return None
+
+
+def _empty_load_video_result(return_types) -> tuple:
+    return tuple(_empty_value_for_type(t) for t in return_types)
+
+
+if _VHS_AVAILABLE:
+    class Easy_LoadVideo(_VHS_LoadVideoPath):
+        """VHS Load Video Path variant with split directory + filename fields."""
+
+        CATEGORY = "Koolook/Video"
+        DESCRIPTION = "Load Video variant with split input path and filename fields."
+
+        @classmethod
+        def INPUT_TYPES(cls):
+            types = _VHS_LoadVideoPath.INPUT_TYPES()
+            required = dict(types.get("required", {}))
+            required.pop("video", None)
+            types["required"] = {
+                "input_path": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "tooltip": (
+                            "Folder containing the video. Absolute paths load "
+                            "directly; relative paths start at ComfyUI's input folder."
+                        ),
+                    },
+                ),
+                "video": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "tooltip": "Video filename, or a full path/URL when input_path is empty.",
+                    },
+                ),
+                **required,
+            }
+            return types
+
+        def load_video(self, *args, **kwargs):
+            composed = _compose_input_video_path(
+                kwargs.get("video", ""),
+                kwargs.pop("input_path", ""),
+            )
+            if composed == EMPTY_BRANCH_SENTINEL:
+                # Unselected branch (existing folder, no filename): return an
+                # empty, correctly-shaped result so the prompt does not crash.
+                print(
+                    "[Easy_LoadVideo] input_path resolved to an existing folder "
+                    "with no video filename; returning an empty branch result. "
+                    "If this is the selected video branch, set the video filename."
+                )
+                return _empty_load_video_result(self.RETURN_TYPES)
+            kwargs["video"] = composed
+            if _is_existing_local_video_path(kwargs["video"]):
+                kwargs["video"] = _strip_outer_quotes(kwargs["video"])
+                return _VHS_LOAD_VIDEO_FN(*args, **kwargs)
+            return super().load_video(*args, **kwargs)
+
+        @classmethod
+        def IS_CHANGED(cls, video, input_path="", **kwargs):
+            resolved = _compose_input_video_path(video, input_path)
+            if resolved == EMPTY_BRANCH_SENTINEL:
+                return EMPTY_BRANCH_SENTINEL
+            return _VHS_LoadVideoPath.IS_CHANGED(resolved, **kwargs)
+
+        @classmethod
+        def VALIDATE_INPUTS(cls, video, input_path="", **kwargs):
+            # Linked inputs are unresolved during ComfyUI validation; execution
+            # receives the real value after the upstream text node runs.
+            if video is None or input_path is None:
+                return True
+            resolved = _compose_input_video_path(video, input_path)
+            # An existing-folder branch validates fine; it degrades to empty at
+            # run time rather than blocking the whole prompt.
+            if resolved == EMPTY_BRANCH_SENTINEL:
+                return True
+            if _is_existing_local_video_path(resolved):
+                return True
+            return _VHS_LoadVideoPath.VALIDATE_INPUTS(resolved)
+
+    NODE_CLASS_MAPPINGS = {"Easy_LoadVideo": Easy_LoadVideo}
+    NODE_DISPLAY_NAME_MAPPINGS = {"Easy_LoadVideo": "Easy Load Video (Koolook)"}
+else:
+    print(
+        f"[Koolook] Easy_LoadVideo skipped: "
+        f"ComfyUI-VideoHelperSuite not importable ({_VHS_IMPORT_ERROR}). "
+        f"Install VHS from ComfyUI-Manager to enable this node."
+    )
+    NODE_CLASS_MAPPINGS = {}
+    NODE_DISPLAY_NAME_MAPPINGS = {}
+
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

ComfyUI/custom_nodes/koolook/koolook_install_guard.py

@@ -0,0 +1,146 @@
+"""Duplicate-install detection (#162).
+
+The Comfy Registry / ComfyUI-Manager install path creates
+``custom_nodes/koolook/`` (derived from ``[project].name`` in our
+``pyproject.toml``), while a ``git clone`` checkout typically lands as
+``custom_nodes/ComfyUI-Koolook/``. A user who has both — common when a
+Manager install gets shadowed by a dev clone — boots ComfyUI with two
+parallel Koolook plugins. Both register the same ``/koolook/presets/*``
+server routes, the same Kforge Labs sidebar tab, and write to the same
+``/userdata/koolook_workflows.json`` file. The late-loaded plugin
+silently overwrites the early loader's state and the user's workflow
+store corrupts invisibly.
+
+This module is the detection + resolution layer. It is intentionally
+free of ComfyUI / aiohttp imports so it can be unit-tested with just
+the standard library — see ``tests/test_install_guard.py``.
+
+Resolution strategy: pick the alphabetically-first folder name as the
+winner. Deterministic across all installs (so both copies agree on the
+outcome without needing to coordinate at runtime), independent of
+ComfyUI's load order. The non-winning install registers nothing — no
+nodes, no routes, no sidebar — and prints a critical message naming
+both paths so the user can resolve the duplicate manually.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def detect_duplicate_koolook_installs(here: Path) -> list[Path]:
+    """Return every sibling directory under ``here.parent`` that also
+    contains a ``koolook_routes.py`` marker file (and is not ``here``).
+
+    The marker file is unique to Koolook installs; a sibling Comfy
+    custom node that happens to share a folder name won't match. The
+    list is sorted by folder name (case-insensitive) so the order is
+    stable for log output and for ``pick_winning_install``.
+    """
+    parent = here.parent
+    siblings: list[Path] = []
+    try:
+        entries = list(parent.iterdir())
+    except OSError:
+        # ``custom_nodes/`` unreadable — would also break the rest of
+        # ComfyUI. Fall through to "no siblings detected"; the duplicate
+        # symptom this guard catches only manifests when sibling
+        # iteration works in the first place.
+        return siblings
+    for entry in entries:
+        try:
+            if entry == here or not entry.is_dir():
+                continue
+            if (entry / "koolook_routes.py").is_file():
+                siblings.append(entry)
+        except OSError:
+            # A sibling we can't stat into (restrictive perms, a broken
+            # mount, a special dir) is not our concern — skip it rather
+            # than let one unreadable neighbour raise PermissionError up
+            # into ``__init__.py`` and abort the whole plugin import. A
+            # real duplicate always carries a readable ``koolook_routes.py``.
+            continue
+    siblings.sort(key=lambda p: p.name.lower())
+    return siblings
+
+
+def read_pyproject_version(install_dir: Path) -> str:
+    """Best-effort extract of the ``version = "..."`` line from a
+    sibling's ``pyproject.toml``. Returns ``"?"`` when the file is
+    missing or unparseable — the critical log is still useful with
+    just the paths.
+
+    Deliberately a manual scan instead of ``tomllib`` to avoid pulling
+    a Python 3.11+ requirement into the install-time guard. The format
+    is regular enough that a one-line ``startswith("version")`` parser
+    is robust to the few real-world variations (single vs double quotes,
+    spaces around ``=``).
+    """
+    pyproj = install_dir / "pyproject.toml"
+    if not pyproj.is_file():
+        return "?"
+    try:
+        for line in pyproj.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            # Match ``version = "..."`` and ``version="..."`` but not
+            # ``versioning = "..."`` or other near-collisions.
+            if not stripped.startswith("version"):
+                continue
+            after_keyword = stripped[len("version"):].lstrip()
+            if not after_keyword.startswith("="):
+                continue
+            value = after_keyword[1:].strip()
+            # Strip a trailing inline comment (``# ...``) before the
+            # quote-stripping in case a pyproject.toml gets clever.
+            if " #" in value:
+                value = value.split(" #", 1)[0].rstrip()
+            return value.strip('"').strip("'")
+    except (OSError, ValueError):
+        # OSError: unreadable file. ValueError (incl. UnicodeDecodeError):
+        # a non-UTF-8 / binary pyproject.toml. Either way the version is
+        # simply unknown — degrade to "?", never raise into the import.
+        pass
+    return "?"
+
+
+def pick_winning_install(here: Path, siblings: list[Path]) -> Path:
+    """Alphabetical-by-folder-name resolution. Stable across both
+    installs so neither needs to coordinate at runtime; the loser
+    figures out it's the loser by comparing this result against its
+    own ``__file__``."""
+    return sorted([here, *siblings], key=lambda p: p.name.lower())[0]
+
+
+def build_duplicate_report(here: Path, siblings: list[Path]) -> tuple[bool, str]:
+    """Produce the critical-log message for a duplicate-install
+    situation. Returns ``(is_winning, message)`` where ``is_winning``
+    is ``True`` when ``here`` was the alphabetically-first folder.
+
+    Pure function — no I/O. Caller decides where to surface the message
+    (``print()`` in ``__init__.py``, a logger in a test, etc.).
+    """
+    winner = pick_winning_install(here, siblings)
+    is_winning = winner == here
+    here_version = read_pyproject_version(here)
+    sibling_lines = "\n".join(
+        f"    - {s} (version: {read_pyproject_version(s)})"
+        for s in siblings
+    )
+    header = (
+        "[Koolook] CRITICAL: duplicate ComfyUI-Koolook installations detected.\n"
+        f"  This install: {here} (version: {here_version})\n"
+        f"  Other install(s):\n{sibling_lines}\n"
+        f"  Active install (alphabetical winner): {winner}\n"
+        "  Both copies register the same /koolook/presets/* routes, the same\n"
+        "  Kforge Labs sidebar tab, and write to the same\n"
+        "  /userdata/koolook_workflows.json file. Running both silently\n"
+        "  corrupts your workflow store on every restart. Remove one of\n"
+        "  the directories above and restart ComfyUI."
+    )
+    if is_winning:
+        return True, header
+    return False, (
+        header + "\n"
+        f"[Koolook] this install ({here.name}) is the non-winning duplicate; "
+        "skipping node + route registration. Only the winning install above "
+        "will serve Kforge Labs this session."
+    )

ComfyUI/custom_nodes/koolook/koolook_routes.py

@@ -0,0 +1,1161 @@
+"""HTTP routes for the Kforge Labs preset library.
+
+Exposes ``/koolook/presets/*`` endpoints over ComfyUI's aiohttp server. The
+preset directory is configurable via the ``KFORGELABS_PRESETS`` env var; if
+unset, falls back to ``<comfyui-userdata>/koolook-presets/`` so users who
+don't care about cross-machine sharing get a sensible default.
+
+Endpoints:
+    GET    /koolook/presets/info
+    GET    /koolook/presets/list
+    GET    /koolook/presets/file?name=<name>
+    POST   /koolook/presets/file?name=<name>
+    DELETE /koolook/presets/file?name=<name>
+
+Path-traversal protection: filenames are restricted to a whitelist
+``^[A-Za-z0-9 _.()\\-]+\\.json$``. Anything else returns 400. We enforce at
+the server boundary so the client cannot smuggle ``../`` or absolute paths
+even if the JS layer is compromised.
+
+The configured directory is auto-created on first save (parent must already
+exist — for facility shares mounted via NFS/SMB the mount point itself
+must be present before saves succeed).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import string
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from aiohttp import web
+
+try:
+    from .koolook_setups import (
+        DEFAULT_SETUPS_FILENAME,
+        DEFAULT_SETUPS_SUBDIR,
+        FileSetupStorage,
+        PublishedSetupRegistry,
+        SAMPLE_SETUPS_PATH,
+        default_storage_path,
+    )
+    from .koolook_setup_runner import (
+        AiohttpComfyClient,
+        InMemorySetupRunStore,
+        PublishedSetupRunner,
+        SetupRunError,
+    )
+except ImportError:  # pragma: no cover - standalone test/import context
+    from koolook_setups import (
+        DEFAULT_SETUPS_FILENAME,
+        DEFAULT_SETUPS_SUBDIR,
+        FileSetupStorage,
+        PublishedSetupRegistry,
+        SAMPLE_SETUPS_PATH,
+        default_storage_path,
+    )
+    from koolook_setup_runner import (
+        AiohttpComfyClient,
+        InMemorySetupRunStore,
+        PublishedSetupRunner,
+        SetupRunError,
+    )
+
+ENV_VAR = "KFORGELABS_PRESETS"
+DEFAULT_SUBDIR = "koolook-presets"
+SETTINGS_FILENAME = "koolook-settings.json"
+SETTINGS_KEY_LIBRARY_PATH = "libraryPath"
+
+# Single-segment filename, ending in `.json`. No path separators, no `..`,
+# no leading dot. Allows letters, digits, spaces, and a small set of safe
+# punctuation (underscore, period, parentheses, hyphen).
+_FILENAME_RE = re.compile(r"^[A-Za-z0-9 _.()\-]+\.json$")
+
+# Same charset as filenames but without the `.json` extension — for the
+# optional `dir` query param that scopes preset operations into a per-preset
+# auto-save subfolder (`<preset>_autosave/`). Single segment only; no path
+# separators (otherwise the symlink-escape check would have to scan multiple
+# levels). The library structure is deliberately one level deep.
+_DIRNAME_RE = re.compile(r"^[A-Za-z0-9 _.()\-]+$")
+
+# Filenames the list endpoint should hide from the user-facing Load list.
+# Currently used to suppress legacy flat-file autosaves left over from the
+# previous autosave layout, in case a user has already accumulated some
+# before upgrading to the per-preset-subfolder layout. Cheap defensive
+# filter; can be removed in a future major if we choose to migrate.
+_HIDDEN_LIST_PREFIXES = ("_autosave_",)
+_WEB_DIR = Path(__file__).resolve().parent / "web"
+_REPO_ROOT = Path(__file__).resolve().parent
+_GITHUB_RELEASES_URL = "https://github.com/malkuthro/ComfyUI-Koolook/releases"
+_GITHUB_LATEST_RELEASE_API_URL = (
+    "https://api.github.com/repos/malkuthro/ComfyUI-Koolook/releases/latest"
+)
+
+
+def _read_pack_version() -> str:
+    """Read the installed Koolook pack version from ``pyproject.toml``.
+
+    Kept local and dependency-free so the ComfyUI runtime does not need package
+    metadata installed. Returns ``"unknown"`` if the file is unavailable or
+    malformed; the frontend treats that as "do not show update notice".
+    """
+    try:
+        text = (_REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    except OSError:
+        return "unknown"
+    match = re.search(r'(?m)^\s*version\s*=\s*["\']([^"\']+)["\']', text)
+    return match.group(1).strip() if match else "unknown"
+
+
+def _latest_autosave_mtime(autosave_dir: Path, named_mtime: float) -> float | None:
+    """Returns the newest recovery-file mtime inside ``autosave_dir`` if
+    strictly newer than ``named_mtime``, else ``None``.
+
+    Scans ``periodic.json`` and every ``pre_load_*.json``. Powers the Load
+    dialog's "newer auto-save available" affordance — the dialog needs to
+    surface the freshest recovery file regardless of which mechanism wrote
+    it (the periodic timer vs. an explicit pre-load capture).
+    """
+    newest: float | None = None
+    try:
+        st = (autosave_dir / "periodic.json").stat()
+        newest = st.st_mtime
+    except OSError:
+        pass
+    try:
+        for entry in autosave_dir.iterdir():
+            if not entry.is_file():
+                continue
+            if not entry.name.startswith("pre_load_") or not entry.name.endswith(".json"):
+                continue
+            try:
+                pst = entry.stat()
+            except OSError:
+                continue
+            if newest is None or pst.st_mtime > newest:
+                newest = pst.st_mtime
+    except OSError:
+        pass
+    if newest is not None and newest > named_mtime:
+        return newest
+    return None
+
+
+def _resolve_default_dir() -> Path:
+    """Resolve the default preset directory under ComfyUI's user folder.
+
+    Uses ``folder_paths.get_user_directory()`` (provided by ComfyUI core)
+    so we don't hardcode the userdata layout — a custom-installed Comfy
+    with a non-standard user dir still gets a sensible default.
+    """
+    try:
+        import folder_paths
+
+        user_dir = folder_paths.get_user_directory()
+        return Path(user_dir) / DEFAULT_SUBDIR
+    except Exception:  # pragma: no cover - fallback for unusual setups
+        return Path.cwd() / "user" / "default" / DEFAULT_SUBDIR
+
+
+def _settings_file_path() -> Path:
+    """Returns the path to ``koolook-settings.json`` under ComfyUI's user dir.
+
+    The settings file is per-install (so each ComfyUI on a workstation has
+    its own preferred library path). Stored as JSON with shape:
+        { "libraryPath": "<absolute-path-or-empty>" }
+    """
+    try:
+        import folder_paths
+
+        return Path(folder_paths.get_user_directory()) / SETTINGS_FILENAME
+    except Exception:  # pragma: no cover
+        return Path.cwd() / "user" / "default" / SETTINGS_FILENAME
+
+
+def _read_settings() -> dict:
+    """Read the settings JSON. Returns ``{}`` if missing or unreadable.
+
+    Soft-failure on read: the in-UI Settings panel can still rewrite a
+    fresh file even if the existing one is corrupt, and the rest of the
+    plugin continues to function (just falls through to env var / default).
+    """
+    path = _settings_file_path()
+    try:
+        if not path.is_file():
+            return {}
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_settings(data: dict) -> None:
+    """Persist the settings JSON atomically.
+
+    Writes to ``<settings>.tmp`` then ``os.replace`` to the final name —
+    so an interrupted process or concurrent write can't leave a truncated
+    file that ``_read_settings`` would silently revert to ``{}`` on next
+    load (silently dropping the user's saved ``libraryPath``).
+
+    Raises ``web.HTTPInternalServerError`` on failure.
+    """
+    path = _settings_file_path()
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        os.replace(str(tmp_path), str(path))
+    except OSError as exc:
+        # Best-effort cleanup of the tmp file so it doesn't accumulate.
+        try:
+            if tmp_path.exists():
+                tmp_path.unlink()
+        except OSError:
+            pass
+        raise web.HTTPInternalServerError(
+            reason=f"Could not write settings file: {exc}"
+        ) from exc
+
+
+def _configured_dir() -> tuple[Path, str]:
+    """Return ``(dir_path, source)`` where source is one of
+    ``"settings"``, ``"env"``, ``"default"``.
+
+    Resolution order (highest priority first):
+      1. ``libraryPath`` field in the settings file (set via Settings panel)
+      2. ``KFORGELABS_PRESETS`` env var (deployment / facility config)
+      3. Built-in default ``<comfyui-userdata>/koolook-presets/``
+
+    Reads each source on every call rather than caching at module-load,
+    so a Settings panel save or a relauncher with a new env value picks
+    up immediately.
+    """
+    settings = _read_settings()
+    settings_path = settings.get(SETTINGS_KEY_LIBRARY_PATH, "")
+    if isinstance(settings_path, str) and settings_path.strip():
+        return Path(settings_path.strip()).expanduser(), "settings"
+    env = os.environ.get(ENV_VAR, "").strip()
+    if env:
+        return Path(env).expanduser(), "env"
+    return _resolve_default_dir(), "default"
+
+
+def _published_setups_path() -> Path:
+    """Storage path for published setups: a sibling of the configured snapshot
+    library, so they follow the same ``libraryPath`` / ``KFORGELABS_PRESETS``
+    location instead of a fixed user-dir folder (issue #227)."""
+    base, _ = _configured_dir()
+    return base.parent / DEFAULT_SETUPS_SUBDIR / DEFAULT_SETUPS_FILENAME
+
+
+def _migrate_legacy_published_setups(legacy: Path, target: Path) -> None:
+    """One-time, non-destructive copy of a pre-relocation registry from the old
+    fixed user-dir path (``legacy``) to ``target`` when ``target`` has none
+    yet. Leaves ``legacy`` in place; logs and swallows copy failures so a
+    permission hiccup can't take down setup serving.
+
+    The copy goes through a temp file + atomic ``os.replace`` (same pattern as
+    ``FileSetupStorage.save_setups``) so an interrupted run can never leave a
+    partial ``setups.json`` at ``target`` — a partial file would otherwise
+    shadow the intact legacy registry on every later boot."""
+    if target == legacy or target.exists() or not legacy.is_file():
+        return
+    tmp_name = None
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp_fd, tmp_name = tempfile.mkstemp(
+            prefix=f"{target.stem}.",
+            suffix=".tmp",
+            dir=str(target.parent),
+        )
+        os.close(tmp_fd)
+        shutil.copy2(legacy, tmp_name)
+        os.replace(tmp_name, target)
+        tmp_name = None
+        print(f"[Koolook] migrated published setups: {legacy} -> {target}")
+    except OSError as exc:
+        print(f"[Koolook] could not migrate published setups from {legacy}: {exc}")
+    finally:
+        if tmp_name and os.path.exists(tmp_name):
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+
+
+def _valid_setups_registry_file(path: Path) -> bool:
+    """True when ``path`` parses as a published-setups document (a bare list or
+    a ``{"setups": [...]}`` mapping — the shapes ``FileSetupStorage`` accepts).
+    Used to decide whether a relocated registry file is trustworthy: existence
+    alone is not proof a migration completed."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if isinstance(raw, dict):
+        raw = raw.get("setups", [])
+    return isinstance(raw, list)
+
+
+def _default_published_setup_registry() -> PublishedSetupRegistry:
+    """Default registry factory — stores beside the snapshot library and
+    migrates any legacy user-dir registry on first use.
+
+    Primary selection is corruption-aware: if migration could not produce the
+    new file, or the file at the new path exists but does not parse while the
+    legacy file is intact, keep reading the legacy file in place — neither the
+    bundled-sample fallback nor an empty catalog may mask real, stranded
+    setups. The unreadable file is left untouched as evidence."""
+    target = _published_setups_path()
+    legacy = default_storage_path()
+    _migrate_legacy_published_setups(legacy, target)
+    primary = target
+    if target != legacy and legacy.is_file():
+        if not target.exists():
+            primary = legacy
+        elif not _valid_setups_registry_file(target) and _valid_setups_registry_file(legacy):
+            print(
+                f"[Koolook] relocated published-setups file at {target} is "
+                f"unreadable; serving intact legacy registry {legacy} instead"
+            )
+            primary = legacy
+    return PublishedSetupRegistry(
+        FileSetupStorage(primary, fallback_path=SAMPLE_SETUPS_PATH)
+    )
+
+
+def _browse_roots() -> list[Path]:
+    """Return filesystem roots the in-app browser can start from."""
+    if os.name == "nt":
+        roots = []
+        for letter in string.ascii_uppercase:
+            root = Path(f"{letter}:\\")
+            if root.exists():
+                roots.append(root)
+        return roots
+    return [Path("/")]
+
+
+def _browse_start_path(raw_path: str) -> Path:
+    """Resolve the requested browse path or fall back to the library dir."""
+    if raw_path:
+        return Path(raw_path).expanduser()
+
+    base, _ = _configured_dir()
+    if base.exists():
+        return base
+    if base.parent.exists():
+        return base.parent
+    try:
+        return Path.home()
+    except RuntimeError:  # pragma: no cover - unusual host config
+        return Path.cwd()
+
+
+def _list_child_dirs(path: Path) -> list[dict]:
+    out = []
+    for entry in path.iterdir():
+        try:
+            if not entry.is_dir():
+                continue
+            if entry.name == "_unsaved_autosave" or entry.name.endswith("_autosave"):
+                continue
+            out.append({"name": entry.name, "path": str(entry)})
+        except OSError:
+            continue
+    out.sort(key=lambda r: r["name"].lower())
+    return out
+
+
+def _list_child_files(path: Path) -> list[dict]:
+    """List child *.json files in ``path``.
+
+    Powers the folder picker's "yes, this is the folder I expected"
+    affordance (mockup section 6) — files are rendered greyed so the user
+    can visually confirm the listing without selecting one. Restricted to
+    JSON because the picker is exclusively used to choose a snapshot
+    library folder; surfacing non-snapshot files would be misleading
+    (they cannot become preset library content).
+    """
+    out = []
+    for entry in path.iterdir():
+        try:
+            if not entry.is_file():
+                continue
+            if not entry.name.lower().endswith(".json"):
+                continue
+        except OSError:
+            continue
+        out.append({"name": entry.name})
+    out.sort(key=lambda r: r["name"].lower())
+    return out
+
+
+def _validate_new_dir_name(name: object) -> str:
+    """Validate a user-created folder name for the browse picker."""
+    if not isinstance(name, str):
+        raise web.HTTPBadRequest(reason="Folder name must be a string.")
+    cleaned = name.strip()
+    if (
+        not cleaned
+        or cleaned in {".", ".."}
+        or "/" in cleaned
+        or "\\" in cleaned
+        or "\x00" in cleaned
+    ):
+        raise web.HTTPBadRequest(reason="Folder name must be a single folder segment.")
+    return cleaned
+
+
+def _validate_filename(name: object) -> str:
+    """Whitelist the filename or raise 400.
+
+    Returning the validated string is convenient for direct
+    ``base / _validate_filename(...)`` use at call sites.
+    """
+    if not isinstance(name, str) or not _FILENAME_RE.match(name):
+        raise web.HTTPBadRequest(
+            reason=(
+                "Invalid filename. Allowed characters: letters, digits, "
+                "space, underscore, period, parentheses, hyphen. Must end "
+                "in .json."
+            )
+        )
+    return name
+
+
+def _validate_dirname(name: str) -> str:
+    """Whitelist a single-segment subfolder name or raise 400.
+
+    Same charset as filenames but without the `.json` extension. Used by
+    the autosave subfolder routing — a request with ``?dir=<x>`` lands its
+    file inside ``<library>/<x>/`` instead of the library root.
+    """
+    if not isinstance(name, str) or not _DIRNAME_RE.match(name):
+        raise web.HTTPBadRequest(
+            reason=(
+                "Invalid dir. Allowed characters: letters, digits, space, "
+                "underscore, period, parentheses, hyphen. No path "
+                "separators, no extension."
+            )
+        )
+    return name
+
+
+def _resolve_within_base(base: Path, name: str) -> Path:
+    """Compute ``base / name`` and verify the resolved path stays under
+    ``base`` after symlinks are followed. Defense-in-depth against a
+    symlink planted inside the configured library dir (plausible on a
+    facility shared mount with weak permissions) redirecting reads/writes
+    off-share.
+
+    Raises ``web.HTTPBadRequest`` on any escape (broken or hostile symlink).
+    Returns the joined path on success — note this is the un-resolved path
+    so the caller can still see the intended filename in error messages,
+    but the ``is_relative_to`` check has already been applied to the
+    resolved form.
+    """
+    file_path = base / name
+    try:
+        resolved_file = file_path.resolve(strict=False)
+        resolved_base = base.resolve(strict=False)
+    except OSError as exc:
+        raise web.HTTPInternalServerError(
+            reason=f"Could not resolve preset path: {exc}"
+        ) from exc
+    try:
+        resolved_file.relative_to(resolved_base)
+    except ValueError as exc:
+        raise web.HTTPBadRequest(
+            reason=(
+                "Preset path escapes the library directory (likely a symlink "
+                "planted in the library). Refusing to proceed."
+            )
+        ) from exc
+    return file_path
+
+
+def _resolve_target(lib_base: Path, subdir: str, name: str) -> tuple[Path, Path]:
+    """Resolve ``lib_base[/subdir]/name`` for a preset operation, with the
+    symlink-escape check grounded at ``lib_base`` (NOT at the subdir) so a
+    hostile symlink inside an auto-save subfolder can't redirect writes
+    outside the library.
+
+    Returns ``(target_dir, file_path)`` — the caller may need ``target_dir``
+    to mkdir before writing. ``file_path`` is the un-resolved join, same as
+    ``_resolve_within_base``.
+
+    Raises ``web.HTTPBadRequest`` on escape, ``web.HTTPInternalServerError``
+    on resolution failure.
+    """
+    if subdir:
+        target_dir = lib_base / subdir
+    else:
+        target_dir = lib_base
+    file_path = target_dir / name
+    try:
+        resolved_file = file_path.resolve(strict=False)
+        resolved_lib = lib_base.resolve(strict=False)
+    except OSError as exc:
+        raise web.HTTPInternalServerError(
+            reason=f"Could not resolve preset path: {exc}"
+        ) from exc
+    try:
+        resolved_file.relative_to(resolved_lib)
+    except ValueError as exc:
+        raise web.HTTPBadRequest(
+            reason=(
+                "Preset path escapes the library directory (likely a symlink "
+                "planted in the library or subfolder). Refusing to proceed."
+            )
+        ) from exc
+    return target_dir, file_path
+
+
+def _open_dir_in_file_manager(target_dir: Path) -> None:
+    """Open ``target_dir`` in the OS file manager. Shared by the snapshot
+    and published-setup reveal routes. Raises ``web.HTTPNotFound`` when the
+    directory is absent and ``web.HTTPInternalServerError`` if the launcher
+    cannot start. Subprocess args are passed list-form (no shell), so a
+    controlled path can't trigger shell-metacharacter interpretation.
+    """
+    if not target_dir.exists() or not target_dir.is_dir():
+        raise web.HTTPNotFound(reason=f"Path does not exist on disk: {target_dir}")
+    try:
+        if sys.platform == "darwin":
+            subprocess.Popen(["open", str(target_dir)])
+        elif sys.platform == "win32":
+            subprocess.Popen(["explorer.exe", str(target_dir)])
+        else:
+            subprocess.Popen(["xdg-open", str(target_dir)])
+    except OSError as exc:
+        raise web.HTTPInternalServerError(
+            reason=f"Could not open path in file manager: {exc}"
+        ) from exc
+
+
+def register_routes(routes, setup_registry_factory=None, setup_runner_factory=None) -> None:
+    """Attach the preset endpoints to the given aiohttp ``RouteTableDef``.
+
+    Called once from ``__init__.py`` at custom-node load time. Splitting
+    registration from the route handlers keeps this file unit-testable
+    without an aiohttp app fixture.
+    """
+    if setup_registry_factory is None:
+        setup_registry_factory = _default_published_setup_registry
+    run_store = InMemorySetupRunStore()
+
+    def _default_setup_runner(request, registry: PublishedSetupRegistry) -> PublishedSetupRunner:
+        base_url = f"{request.scheme}://{request.host}"
+        return PublishedSetupRunner(registry, AiohttpComfyClient(base_url), run_store)
+
+    def _setup_runner(request, registry: PublishedSetupRegistry):
+        if setup_runner_factory is not None:
+            return setup_runner_factory()
+        return _default_setup_runner(request, registry)
+
+    def _log_setup_diagnostics(registry: PublishedSetupRegistry) -> None:
+        for diagnostic in registry.diagnostics:
+            print(f"[Koolook] published setup skipped: {diagnostic}")
+
+    def _web_asset_response(filename: str, content_type: str):
+        path = _WEB_DIR / filename
+        try:
+            return web.Response(
+                text=path.read_text(encoding="utf-8"),
+                content_type=content_type,
+                # These assets are dev-synced in place; without no-store the
+                # browser caches them and keeps running stale JS/HTML after an
+                # update, which looks like "the fix didn't land". Always revalidate.
+                headers={"Cache-Control": "no-store"},
+            )
+        except OSError as exc:
+            raise web.HTTPNotFound(reason=f"Koolook web asset '{filename}' not found.") from exc
+
+    @routes.get("/koolook/setup_runner_simulator.html")
+    async def setup_runner_simulator_html(_request):
+        return _web_asset_response("setup_runner_simulator.html", "text/html")
+
+    @routes.get("/koolook/setup_runner_simulator.js")
+    async def setup_runner_simulator_js(_request):
+        return _web_asset_response("setup_runner_simulator.js", "application/javascript")
+
+    @routes.get("/koolook/api/version")
+    async def get_koolook_version(_request):
+        return web.json_response(
+            {
+                "version": _read_pack_version(),
+                "releasesUrl": _GITHUB_RELEASES_URL,
+                "latestReleaseApiUrl": _GITHUB_LATEST_RELEASE_API_URL,
+            }
+        )
+
+    @routes.get("/koolook/api/setups")
+    async def list_published_setups(_request):
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        rows = registry.listSetups()
+        _log_setup_diagnostics(registry)
+        return web.json_response(rows)
+
+    @routes.get("/koolook/api/setups/{setup_id}")
+    async def get_published_setup(request):
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        setup_id = request.match_info["setup_id"]
+        setup = registry.getSetup(setup_id)
+        _log_setup_diagnostics(registry)
+        if setup is None:
+            raise web.HTTPNotFound(reason=f"Published setup '{setup_id}' not found.")
+        return web.json_response(setup)
+
+    @routes.post("/koolook/api/setups")
+    async def publish_setup(request):
+        try:
+            payload = await request.json()
+        except Exception as exc:
+            return web.json_response(
+                {"ok": False, "errors": [f"Body must be JSON: {exc}"]},
+                status=400,
+            )
+        if not isinstance(payload, dict):
+            return web.json_response(
+                {"ok": False, "errors": ["Body must be a JSON object."]},
+                status=400,
+            )
+
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        result = registry.publishSetup(
+            visualGraph=payload.get("visualGraph"),
+            metadata=payload.get("metadata"),
+            inputContract=payload.get("inputContract"),
+            outputContract=payload.get("outputContract"),
+            source=payload.get("source"),
+            apiPrompt=payload.get("apiPrompt"),
+        )
+        if not result.valid:
+            return web.json_response(
+                {"ok": False, "errors": result.diagnostics},
+                status=400,
+            )
+        response = {"ok": True, "setup": result.setup}
+        storage_path = registry.storage_path
+        if storage_path is not None:
+            response["storagePath"] = str(storage_path)
+        return web.json_response(response)
+
+    @routes.post("/koolook/api/setups/{setup_id}/run")
+    async def run_published_setup(request):
+        try:
+            payload = await request.json()
+        except Exception as exc:
+            return web.json_response(
+                {"ok": False, "errors": [f"Body must be JSON: {exc}"]},
+                status=400,
+            )
+        if not isinstance(payload, dict):
+            return web.json_response(
+                {"ok": False, "errors": ["Body must be a JSON object."]},
+                status=400,
+            )
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        runner = _setup_runner(request, registry)
+        try:
+            result = await runner.runSetup(
+                request.match_info["setup_id"],
+                payload.get("inputs", {}),
+            )
+        except SetupRunError as exc:
+            return web.json_response(
+                {"ok": False, "errors": exc.errors},
+                status=exc.status_code,
+            )
+        return web.json_response({"ok": True, "run": result})
+
+    @routes.get("/koolook/api/runs/{run_id}")
+    async def get_published_setup_run(request):
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        runner = _setup_runner(request, registry)
+        try:
+            result = await runner.getRun(request.match_info["run_id"])
+        except SetupRunError as exc:
+            return web.json_response(
+                {"ok": False, "errors": exc.errors},
+                status=exc.status_code,
+            )
+        return web.json_response({"ok": True, "run": result})
+
+    @routes.get("/koolook/presets/info")
+    async def info(_request):
+        base, source = _configured_dir()
+        exists = base.exists() and base.is_dir()
+        writable = exists and os.access(str(base), os.W_OK)
+        return web.json_response(
+            {
+                "path": str(base),
+                "source": source,           # "settings" | "env" | "default"
+                "isDefault": source == "default",
+                "envVar": ENV_VAR,
+                "exists": exists,
+                "writable": writable,
+            }
+        )
+
+    @routes.get("/koolook/presets/settings")
+    async def get_settings(_request):
+        """Return the saved-in-UI library path (if any) plus the resolved
+        path the server actually uses right now. The UI's Settings dialog
+        renders the saved value as the editable field and the resolved
+        value as the read-only "currently in effect" line."""
+        settings = _read_settings()
+        saved = settings.get(SETTINGS_KEY_LIBRARY_PATH, "")
+        if not isinstance(saved, str):
+            saved = ""
+        resolved, source = _configured_dir()
+        return web.json_response(
+            {
+                "savedLibraryPath": saved,
+                "resolvedPath": str(resolved),
+                "source": source,
+                "envVar": ENV_VAR,
+            }
+        )
+
+    @routes.get("/koolook/presets/browse")
+    async def browse_dirs(request):
+        """List child directories for the Settings dialog's path picker.
+
+        With ``?files=1`` also returns child ``*.json`` files — used by the
+        redesigned folder picker (issue #137, mockup section 6) to render a
+        greyed "this is the folder I expected" affordance below the
+        directories. Default response shape stays directory-only so any
+        existing callers (legacy Settings dialog) continue to work
+        unchanged.
+
+        The selected path is still saved through the existing settings
+        endpoint, so the library-path resolution and write checks stay
+        centralized.
+        """
+        path = _browse_start_path(request.query.get("path", "").strip())
+        include_files = request.query.get("files", "").strip() in {"1", "true", "yes"}
+        try:
+            resolved = path.resolve(strict=False)
+        except OSError as exc:
+            raise web.HTTPBadRequest(reason=f"Could not resolve path: {exc}") from exc
+        if not resolved.exists() or not resolved.is_dir():
+            raise web.HTTPBadRequest(reason=f"Directory does not exist: {resolved}")
+
+        parent = resolved.parent if resolved.parent != resolved else None
+        roots = [{"name": str(root), "path": str(root)} for root in _browse_roots()]
+        try:
+            dirs = _list_child_dirs(resolved)
+            files = _list_child_files(resolved) if include_files else []
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not list directories: {exc}"
+            ) from exc
+        body = {
+            "path": str(resolved),
+            "parentPath": str(parent) if parent else "",
+            "roots": roots,
+            "dirs": dirs,
+        }
+        if include_files:
+            body["files"] = files
+        return web.json_response(body)
+
+    @routes.post("/koolook/presets/browse/new-folder")
+    async def create_browse_dir(request):
+        """Create one child folder under the current browse location.
+
+        Threat model: this picker is intentionally filesystem-wide so users
+        can choose a snapshot library outside the current Koolook library.
+        The route's boundary is the ComfyUI process OS user, not the preset
+        library root. We still reject multi-segment names and symlink escapes
+        relative to the selected parent so a request cannot turn "create this
+        child folder here" into "create something elsewhere."
+        """
+        try:
+            payload = await request.json()
+        except Exception as exc:
+            raise web.HTTPBadRequest(reason=f"Body must be JSON: {exc}") from exc
+        if not isinstance(payload, dict):
+            raise web.HTTPBadRequest(reason="Body must be a JSON object.")
+
+        parent = _browse_start_path(str(payload.get("parentPath", "")).strip())
+        name = _validate_new_dir_name(payload.get("name", ""))
+        try:
+            resolved_parent = parent.resolve(strict=False)
+        except OSError as exc:
+            raise web.HTTPBadRequest(reason=f"Could not resolve parent: {exc}") from exc
+        if not resolved_parent.exists() or not resolved_parent.is_dir():
+            raise web.HTTPBadRequest(reason=f"Parent folder does not exist: {resolved_parent}")
+
+        child = resolved_parent / name
+        try:
+            resolved_child = child.resolve(strict=False)
+        except OSError as exc:
+            raise web.HTTPBadRequest(reason=f"Could not resolve new folder: {exc}") from exc
+        try:
+            resolved_child.relative_to(resolved_parent)
+        except ValueError as exc:
+            raise web.HTTPBadRequest(reason="New folder escapes the selected parent.") from exc
+        if resolved_child.exists():
+            raise web.HTTPBadRequest(reason=f"Folder already exists: {resolved_child}")
+
+        try:
+            child.mkdir()
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not create folder: {exc}"
+            ) from exc
+        return web.json_response({"path": str(child)})
+
+    @routes.post("/koolook/presets/settings")
+    async def post_settings(request):
+        """Persist a saved library path. Body is JSON ``{libraryPath: <str>}``.
+
+        Empty string or missing field clears the override (the server then
+        falls back to env-var or the built-in default).
+        """
+        try:
+            payload = await request.json()
+        except Exception as exc:
+            raise web.HTTPBadRequest(
+                reason=f"Settings body must be JSON: {exc}"
+            ) from exc
+        if not isinstance(payload, dict):
+            raise web.HTTPBadRequest(reason="Settings body must be a JSON object.")
+        new_path = payload.get(SETTINGS_KEY_LIBRARY_PATH, "")
+        if not isinstance(new_path, str):
+            raise web.HTTPBadRequest(
+                reason=f"`{SETTINGS_KEY_LIBRARY_PATH}` must be a string."
+            )
+        new_path = new_path.strip()
+        # Read-modify-write so unrelated keys (future settings) survive.
+        existing = _read_settings()
+        if new_path:
+            existing[SETTINGS_KEY_LIBRARY_PATH] = new_path
+        else:
+            # Empty string = clear the override; remove the key entirely
+            # so the resolution chain falls through cleanly to env / default.
+            existing.pop(SETTINGS_KEY_LIBRARY_PATH, None)
+        _write_settings(existing)
+        # Echo the new resolved state so the UI can update without a refetch.
+        resolved, source = _configured_dir()
+        return web.json_response(
+            {
+                "savedLibraryPath": new_path,
+                "resolvedPath": str(resolved),
+                "source": source,
+            }
+        )
+
+    @routes.get("/koolook/presets/list")
+    async def list_presets(request):
+        """List preset files. With ``?dir=<x>`` lists files inside that
+        subfolder (used by autosave management); without dir, lists root
+        and HIDES anything matching ``_HIDDEN_LIST_PREFIXES`` (legacy flat
+        autosaves) plus any subdirectories (the per-preset autosave folders
+        — those should never appear in the user-facing Load list).
+        """
+        base, _is_default = _configured_dir()
+        subdir_q = request.query.get("dir", "").strip()
+        if subdir_q:
+            _validate_dirname(subdir_q)
+            target_dir, _ = _resolve_target(base, subdir_q, "_listing.json")
+            target_dir = target_dir  # named for clarity
+        else:
+            target_dir = base
+        if not target_dir.exists() or not target_dir.is_dir():
+            return web.json_response([])
+        out = []
+        try:
+            for entry in target_dir.iterdir():
+                if not entry.is_file() or not entry.name.lower().endswith(".json"):
+                    continue
+                # Only filter legacy autosave flat files at the LIBRARY ROOT.
+                # Inside autosave subfolders we want to see everything (so
+                # the rotation pruner can list + delete its own files).
+                if not subdir_q and any(
+                    entry.name.startswith(p) for p in _HIDDEN_LIST_PREFIXES
+                ):
+                    continue
+                try:
+                    stat = entry.stat()
+                except OSError:
+                    continue
+                row = {
+                    "name": entry.name,
+                    "mtime": stat.st_mtime,
+                    "size": stat.st_size,
+                }
+                # Library-root rows only: scan the matching
+                # `<base>_autosave/` subfolder for the newest recovery file
+                # (``periodic.json`` and every ``pre_load_*.json``) and
+                # surface its mtime when strictly newer than the named
+                # file. Powers the Load dialog's inline "Newer auto-save
+                # available — restore?" affordance — the autosave UX needs
+                # the system to proactively offer the recovery copy when
+                # the user's last manual save is stale, rather than
+                # burying it inside the Recovery disclosure. Issue #137:
+                # before this we only considered ``periodic.json``, which
+                # missed cases where the user's most recent Load wrote a
+                # fresher ``pre_load_*.json`` snapshot. A handful of stats
+                # per row, no reads — still cheap on large libraries.
+                if not subdir_q:
+                    base_name = entry.name[: -len(".json")]
+                    autosave_dir = target_dir / f"{base_name}_autosave"
+                    newest = _latest_autosave_mtime(autosave_dir, stat.st_mtime)
+                    if newest is not None:
+                        row["latestAutosaveMtime"] = newest
+                out.append(row)
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not list preset library: {exc}"
+            ) from exc
+        # Sort alphabetical (case-insensitive) at the server so every client
+        # sees the same order regardless of filesystem iteration order.
+        out.sort(key=lambda r: r["name"].lower())
+        return web.json_response(out)
+
+    @routes.get("/koolook/presets/autosaves/list")
+    async def list_autosaves(_request):
+        """Walk every ``*_autosave/`` subdir (and ``_unsaved_autosave/``)
+        under the library and return a flat list of recovery snapshot
+        files. Powers the Load dialog's recovery section so a user can
+        restore from a pre-load or periodic auto-save without leaving
+        the UI.
+
+        Why a dedicated endpoint instead of recursing the existing
+        ``list``? The user-facing list MUST hide subdirs (otherwise the
+        Load list gets cluttered with autosave files that aren't
+        directly user-restorable). This endpoint is the explicit "show
+        me everything in autosave folders" API — separated cleanly so
+        the boundary is grep-able and adding more subdir-scoped views
+        later (timeline / cross-preset comparison / etc.) doesn't have
+        to push more flags into the main list endpoint.
+
+        Sort: subdir alphabetical, then mtime descending within each
+        subdir (newest recovery point first — matches what users
+        expect when scanning for "the file just before I broke things").
+        """
+        base, _ = _configured_dir()
+        if not base.exists() or not base.is_dir():
+            return web.json_response([])
+        out = []
+        try:
+            for subdir_entry in base.iterdir():
+                if not subdir_entry.is_dir():
+                    continue
+                subdir_name = subdir_entry.name
+                # Match the autosave naming convention exactly so a user-
+                # created subdirectory called "my random folder" isn't
+                # treated as a recovery source.
+                is_unsaved = subdir_name == "_unsaved_autosave"
+                is_named = subdir_name.endswith("_autosave") and len(subdir_name) > len("_autosave")
+                if not (is_unsaved or is_named):
+                    continue
+                for f in subdir_entry.iterdir():
+                    if not f.is_file() or not f.name.lower().endswith(".json"):
+                        continue
+                    try:
+                        stat = f.stat()
+                    except OSError:
+                        continue
+                    out.append(
+                        {
+                            "dir": subdir_name,
+                            "name": f.name,
+                            "mtime": stat.st_mtime,
+                            "size": stat.st_size,
+                        }
+                    )
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not list autosave folders: {exc}"
+            ) from exc
+        out.sort(key=lambda r: (r["dir"].lower(), -r["mtime"]))
+        return web.json_response(out)
+
+    @routes.get("/koolook/presets/file")
+    async def get_preset(request):
+        """Serve preset JSON for ``?name=<name>[&dir=<subdir>]``; HEAD
+        short-circuits before the file read.
+
+        aiohttp's ``add_get`` auto-registers a HEAD route by default. We
+        can't opt out via ``allow_head=False`` because ComfyUI's
+        mirror-to-/api code in ``server.py`` blindly forwards
+        ``RouteDef.kwargs`` into ``RouteTableDef.route(method, path)
+        (handler, **kwargs)`` whose inner closure rejects unknown
+        kwargs, crashing startup. So this single handler owns both
+        methods, branching on ``request.method`` so a ``presetExists``
+        HEAD probe doesn't have to read multi-MB JSON over
+        Dropbox/iCloud/NFS-mounted libraries just to answer 200/404.
+        """
+        name = _validate_filename(request.query.get("name"))
+        subdir = request.query.get("dir", "").strip()
+        if subdir:
+            _validate_dirname(subdir)
+        base, _ = _configured_dir()
+        _, file_path = _resolve_target(base, subdir, name)
+        if not file_path.is_file():
+            raise web.HTTPNotFound(reason=f"Preset '{name}' not found.")
+        if request.method == "HEAD":
+            return web.Response(status=200)
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not read preset: {exc}"
+            ) from exc
+        return web.Response(text=content, content_type="application/json")
+
+    @routes.post("/koolook/presets/file")
+    async def post_preset(request):
+        name = _validate_filename(request.query.get("name"))
+        subdir = request.query.get("dir", "").strip()
+        if subdir:
+            _validate_dirname(subdir)
+        base, _ = _configured_dir()
+        if not base.parent.exists():
+            raise web.HTTPInternalServerError(
+                reason=(
+                    f"Preset library parent directory does not exist: "
+                    f"{base.parent}. Create it (or fix the {ENV_VAR} env "
+                    f"var) and retry."
+                )
+            )
+        target_dir, file_path = _resolve_target(base, subdir, name)
+        try:
+            target_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not create preset directory: {exc}"
+            ) from exc
+        body = await request.read()
+        # Atomic write — `tempfile.mkstemp` opens a uniquely-named temp
+        # file inside the already-validated `target_dir` using
+        # `O_CREAT | O_EXCL` semantics, then `os.replace` swaps it onto
+        # the final name. A crash or dropped connection mid-write can
+        # no longer truncate the existing good file: readers see either
+        # the old or the new content, never a half-written byte stream.
+        #
+        # Why mkstemp instead of a fixed `<file>.json.tmp` name? An
+        # attacker (or accidental user) with write access to the library
+        # could plant `<file>.json.tmp` as a symlink pointing outside
+        # the library. A naive `Path.write_bytes` would FOLLOW that
+        # symlink — past the path-traversal guard — and write the
+        # request body to wherever the symlink pointed, before
+        # `os.replace` swapped the symlink off. `mkstemp` defeats that
+        # in two ways: (1) `O_EXCL` aborts if anything (including a
+        # symlink) already exists at the chosen name, and (2) the name
+        # itself is random so the attacker can't pre-plant anything
+        # there. The `.tmp` suffix keeps the transient file invisible
+        # to `/koolook/presets/list` and `/koolook/presets/autosaves/list`
+        # (both filter to `.json`).
+        try:
+            tmp_fd, tmp_name = tempfile.mkstemp(
+                prefix=f"{file_path.stem}.",
+                suffix=".tmp",
+                dir=str(target_dir),
+            )
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not create preset temp file: {exc}"
+            ) from exc
+        try:
+            with os.fdopen(tmp_fd, "wb") as f:
+                f.write(body)
+            os.replace(tmp_name, str(file_path))
+        except OSError as exc:
+            try:
+                if os.path.exists(tmp_name):
+                    os.unlink(tmp_name)
+            except OSError:
+                pass
+            raise web.HTTPInternalServerError(
+                reason=f"Could not write preset: {exc}"
+            ) from exc
+        return web.json_response({"ok": True, "name": name, "dir": subdir})
+
+    @routes.delete("/koolook/presets/file")
+    async def delete_preset(request):
+        name = _validate_filename(request.query.get("name"))
+        subdir = request.query.get("dir", "").strip()
+        if subdir:
+            _validate_dirname(subdir)
+        base, _ = _configured_dir()
+        _, file_path = _resolve_target(base, subdir, name)
+        if not file_path.is_file():
+            raise web.HTTPNotFound(reason=f"Preset '{name}' not found.")
+        try:
+            file_path.unlink()
+        except OSError as exc:
+            raise web.HTTPInternalServerError(
+                reason=f"Could not delete preset: {exc}"
+            ) from exc
+        return web.json_response({"ok": True, "name": name, "dir": subdir})
+
+    @routes.post("/koolook/presets/reveal")
+    async def reveal_preset_folder(request):
+        """Open the preset library (or an autosave subfolder) in the OS
+        file manager. Optional ``?dir=<subdir>`` deep-links to a
+        per-preset autosave folder so the Recovery section can drop the
+        user inside the right `<preset>_autosave/` directory.
+
+        Path-traversal is grounded at the configured library base via
+        ``_resolve_target``; subdir names go through ``_validate_dirname``.
+        Subprocess args are passed list-form (no shell), so a controlled
+        path can't trigger shell-metacharacter interpretation even if a
+        future check loosens the dirname charset.
+        """
+        base, _ = _configured_dir()
+        subdir_q = request.query.get("dir", "").strip()
+        if subdir_q:
+            _validate_dirname(subdir_q)
+            target_dir, _ = _resolve_target(base, subdir_q, "_listing.json")
+        else:
+            target_dir = base
+        _open_dir_in_file_manager(target_dir)
+        return web.json_response({"ok": True, "path": str(target_dir)})
+
+    @routes.post("/koolook/api/setups/reveal")
+    async def reveal_published_setup_folder(_request):
+        """Open the published-setups directory (where ``Publish setup``
+        writes ``setups.json``) in the OS file manager. Distinct from the
+        snapshot-library reveal above: the publish success card's Open
+        folder action must land in the registry folder, not the snapshot
+        library.
+        """
+        registry: PublishedSetupRegistry = setup_registry_factory()
+        storage_path = registry.storage_path
+        if storage_path is None:
+            raise web.HTTPNotFound(
+                reason="Published setup storage path is unavailable."
+            )
+        target_dir = storage_path.parent
+        _open_dir_in_file_manager(target_dir)
+        return web.json_response({"ok": True, "path": str(target_dir)})
+
+
+def install() -> bool:
+    """Hook the routes into ComfyUI's running PromptServer.
+
+    Returns ``True`` on success, ``False`` if PromptServer wasn't reachable
+    (very early import, headless test, etc.). The caller logs the failure
+    so the rest of Koolook still loads — the snapshot feature just won't
+    work in that session.
+    """
+    try:
+        from server import PromptServer  # type: ignore[import-not-found]
+    except Exception:
+        return False
+    try:
+        register_routes(PromptServer.instance.routes)
+    except Exception as exc:  # pragma: no cover - defensive
+        print(f"[Koolook] failed to register preset routes: {exc}")
+        return False
+    return True

ComfyUI/custom_nodes/koolook/koolook_setup_runner.py

@@ -0,0 +1,1010 @@
+"""Execution boundary for published Koolook workflow setups."""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    from .koolook_setups import PublishedSetupRegistry
+except ImportError:  # pragma: no cover - standalone test/import context
+    from koolook_setups import PublishedSetupRegistry
+
+
+class SetupRunError(Exception):
+    """API-facing setup runner error with stable HTTP status semantics."""
+
+    def __init__(self, status_code: int, errors: list[str]) -> None:
+        super().__init__("; ".join(errors))
+        self.status_code = status_code
+        self.errors = errors
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    run_id: str
+    setup_id: str
+    prompt_id: str
+    status: str
+    inputs: dict[str, Any]
+
+
+class InMemorySetupRunStore:
+    """Small run-id mapping store for a running ComfyUI process."""
+
+    def __init__(self) -> None:
+        self._next_id = 1
+        self._records: dict[str, RunRecord] = {}
+
+    def create(self, *, setup_id: str, prompt_id: str, inputs: dict[str, Any] | None = None) -> RunRecord:
+        run_id = f"run-{self._next_id:06d}"
+        self._next_id += 1
+        record = RunRecord(
+            run_id=run_id,
+            setup_id=setup_id,
+            prompt_id=prompt_id,
+            status="queued",
+            inputs=deepcopy(inputs) if isinstance(inputs, dict) else {},
+        )
+        self._records[run_id] = record
+        return record
+
+    def get(self, run_id: str) -> RunRecord | None:
+        return self._records.get(run_id)
+
+
+class AiohttpComfyClient:
+    """HTTP adapter for the managed ComfyUI server."""
+
+    def __init__(self, base_url: str) -> None:
+        self._base_url = base_url.rstrip("/")
+
+    async def queue_prompt(self, prompt: dict) -> dict:
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(f"{self._base_url}/prompt", json={"prompt": prompt}) as response:
+                try:
+                    payload = await response.json()
+                except Exception:
+                    payload = {"error": await response.text()}
+                if response.status >= 400:
+                    detail = payload.get("error") if isinstance(payload, dict) else payload
+                    raise SetupRunError(
+                        502,
+                        [f"ComfyUI queue request failed with HTTP {response.status}: {detail}"],
+                    )
+                return payload if isinstance(payload, dict) else {}
+
+    async def get_history(self, prompt_id: str) -> dict:
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.get(f"{self._base_url}/history/{prompt_id}") as response:
+                try:
+                    payload = await response.json()
+                except Exception:
+                    payload = {"error": await response.text()}
+                if response.status >= 400:
+                    detail = payload.get("error") if isinstance(payload, dict) else payload
+                    raise SetupRunError(
+                        502,
+                        [f"ComfyUI history request failed with HTTP {response.status}: {detail}"],
+                    )
+                return payload if isinstance(payload, dict) else {}
+
+    async def get_queue(self) -> dict:
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.get(f"{self._base_url}/queue") as response:
+                try:
+                    payload = await response.json()
+                except Exception:
+                    payload = {"error": await response.text()}
+                if response.status >= 400:
+                    detail = payload.get("error") if isinstance(payload, dict) else payload
+                    raise SetupRunError(
+                        502,
+                        [f"ComfyUI queue status request failed with HTTP {response.status}: {detail}"],
+                    )
+                return payload if isinstance(payload, dict) else {}
+
+
+class PublishedSetupRunner:
+    """Runs callable published setups without exposing ComfyUI internals."""
+
+    def __init__(
+        self,
+        registry: PublishedSetupRegistry,
+        comfy_client: Any,
+        run_store: InMemorySetupRunStore | None = None,
+    ) -> None:
+        self._registry = registry
+        self._comfy_client = comfy_client
+        self._run_store = run_store or InMemorySetupRunStore()
+
+    async def runSetup(self, setup_id: str, inputs: dict[str, Any]) -> dict[str, Any]:
+        setup = self._registry.getSetup(setup_id)
+        if setup is None:
+            raise SetupRunError(404, [f"Published setup '{setup_id}' not found."])
+        if not isinstance(inputs, dict):
+            raise SetupRunError(400, ["inputs must be a JSON object"])
+
+        api_prompt = setup.get("apiPrompt")
+        if not isinstance(api_prompt, dict) or setup.get("validation", {}).get("status") != "valid":
+            raise SetupRunError(400, [f"Published setup '{setup_id}' is not callable."])
+
+        prompt = deepcopy(api_prompt)
+        input_fields = _declared_input_fields(setup)
+        errors = _validate_run_inputs(input_fields, inputs)
+        errors.extend(_validate_execution_map_inputs(setup, inputs))
+        if errors:
+            raise SetupRunError(400, errors)
+
+        for key, value in inputs.items():
+            field = input_fields[key]
+            target = field["target"]
+            prompt[str(target["node"])]["inputs"][str(target["input"])] = _prompt_value_for_field(field, value)
+
+        mapped_prompt = _prune_prompt_for_execution_map(setup, prompt, inputs)
+        prompt = (
+            mapped_prompt
+            if mapped_prompt is not None
+            else _prune_prompt_for_selected_app_results(setup, prompt, inputs)
+        )
+
+        try:
+            queued = await self._comfy_client.queue_prompt(prompt)
+        except SetupRunError:
+            raise
+        except Exception as exc:
+            raise SetupRunError(502, [f"ComfyUI queue request failed: {exc}"]) from exc
+
+        prompt_id = queued.get("prompt_id") if isinstance(queued, dict) else None
+        if not isinstance(prompt_id, str) or not prompt_id:
+            raise SetupRunError(502, ["ComfyUI queue response did not include prompt_id"])
+
+        record = self._run_store.create(setup_id=setup_id, prompt_id=prompt_id, inputs=inputs)
+        return {"runId": record.run_id, "promptId": record.prompt_id, "status": record.status}
+
+    async def getRun(self, run_id: str) -> dict[str, Any]:
+        record = self._run_store.get(run_id)
+        if record is None:
+            raise SetupRunError(404, [f"Koolook run '{run_id}' not found."])
+
+        setup = self._registry.getSetup(record.setup_id)
+        if setup is None:
+            raise SetupRunError(404, [f"Published setup '{record.setup_id}' not found."])
+
+        try:
+            history = await self._comfy_client.get_history(record.prompt_id)
+        except SetupRunError:
+            raise
+        except Exception as exc:
+            raise SetupRunError(502, [f"ComfyUI history request failed: {exc}"]) from exc
+
+        history_entry = history.get(record.prompt_id) if isinstance(history, dict) else None
+        if isinstance(history_entry, dict):
+            status = _status_from_history(history_entry)
+            return {
+                "runId": record.run_id,
+                "setupId": record.setup_id,
+                "promptId": record.prompt_id,
+                "status": status,
+                "comfyStatus": history_entry.get("status", {}),
+                "outputs": _summarize_outputs(
+                    setup,
+                    history_entry.get("outputs", {}),
+                    record.inputs,
+                    _history_prompt(history_entry),
+                ),
+            }
+
+        try:
+            queue = await self._comfy_client.get_queue()
+        except SetupRunError:
+            raise
+        except Exception as exc:
+            raise SetupRunError(502, [f"ComfyUI queue status request failed: {exc}"]) from exc
+        return {
+            "runId": record.run_id,
+            "setupId": record.setup_id,
+            "promptId": record.prompt_id,
+            "status": _status_from_queue(record.prompt_id, queue),
+            "outputs": [],
+        }
+
+
+def _declared_input_fields(setup: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    fields: dict[str, dict[str, Any]] = {}
+    for field in setup.get("inputContract", {}).get("inputs", []):
+        if not isinstance(field, dict):
+            continue
+        key = field.get("key")
+        target = field.get("target")
+        if isinstance(key, str) and key and isinstance(target, dict):
+            fields[key] = field
+    app = setup.get("setupSurface", {}).get("app", {})
+    if isinstance(app, dict):
+        for field in app.get("inputs", []):
+            if not isinstance(field, dict):
+                continue
+            key = field.get("key")
+            target = field.get("target")
+            if isinstance(key, str) and key and isinstance(target, dict):
+                fields.setdefault(key, field)
+        for field in app.get("outputs", []):
+            if not isinstance(field, dict):
+                continue
+            key = field.get("key")
+            target = field.get("target")
+            if isinstance(key, str) and key and isinstance(target, dict):
+                fields.setdefault(key, field)
+        switch = app.get("switch")
+        if isinstance(switch, dict):
+            key = switch.get("key")
+            target = switch.get("target")
+            if isinstance(key, str) and key and isinstance(target, dict):
+                fields.setdefault(key, switch)
+    return fields
+
+
+def _validate_run_inputs(input_fields: dict[str, dict[str, Any]], inputs: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    for key in inputs:
+        if key not in input_fields:
+            errors.append(f"input '{key}' is not declared by this setup")
+            continue
+        field = input_fields[key]
+        if field.get("key") == "switch" and _switch_option_value(field, inputs[key]) is None:
+            errors.append(_switch_value_error(key, field))
+    for key, field in input_fields.items():
+        if field.get("required") is True and key not in inputs:
+            errors.append(f"required input '{key}' is missing")
+    return errors
+
+
+def _prompt_value_for_field(field: dict[str, Any], value: Any) -> Any:
+    if field.get("key") != "switch":
+        return value
+    selected_value = _switch_option_value(field, value)
+    for option in field.get("options", []):
+        if not isinstance(option, dict):
+            continue
+        if option.get("value") == selected_value and isinstance(option.get("label"), str):
+            return option["label"]
+    return value
+
+
+def _switch_option_value(switch: dict[str, Any], selected: Any) -> int | None:
+    if isinstance(selected, bool):
+        return None
+    for option in switch.get("options", []):
+        if not isinstance(option, dict):
+            continue
+        value = option.get("value")
+        if isinstance(value, bool) or not isinstance(value, int):
+            continue
+        if selected == value:
+            return value
+        if isinstance(selected, str) and (selected == str(value) or selected == option.get("label")):
+            return value
+    return None
+
+
+def _switch_value_error(key: str, switch: dict[str, Any]) -> str:
+    choices: list[str] = []
+    for option in switch.get("options", []):
+        if not isinstance(option, dict):
+            continue
+        value = option.get("value")
+        label = option.get("label")
+        if isinstance(value, bool) or not isinstance(value, int):
+            continue
+        choices.append(f"{value} ({label})" if isinstance(label, str) and label else str(value))
+    if choices:
+        return f"input '{key}' must be one of: {', '.join(choices)}"
+    return f"input '{key}' has no valid switch options"
+
+
+def _status_from_history(history_entry: dict[str, Any]) -> str:
+    status = history_entry.get("status")
+    if not isinstance(status, dict):
+        return "succeeded"
+    status_text = str(status.get("status_str", "")).lower()
+    if status.get("completed") is True and status_text not in {"error", "failed", "failure"}:
+        return "succeeded"
+    return "failed"
+
+
+def _status_from_queue(prompt_id: str, queue: Any) -> str:
+    if not isinstance(queue, dict):
+        return "lost"
+    if _queue_contains_prompt(queue.get("queue_running", []), prompt_id):
+        return "running"
+    if _queue_contains_prompt(queue.get("queue_pending", []), prompt_id):
+        return "queued"
+    return "lost"
+
+
+def _queue_contains_prompt(entries: Any, prompt_id: str) -> bool:
+    if not isinstance(entries, list):
+        return False
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("prompt_id") == prompt_id:
+            return True
+        if isinstance(entry, list) and prompt_id in entry:
+            return True
+    return False
+
+
+def _summarize_outputs(
+    setup: dict[str, Any],
+    raw_outputs: Any,
+    run_inputs: dict[str, Any] | None = None,
+    history_prompt: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    output_items = _flatten_history_outputs(raw_outputs)
+    summaries = []
+    for output in setup.get("outputContract", {}).get("outputs", []):
+        if not isinstance(output, dict):
+            continue
+        summaries.append(
+            {
+                "key": output.get("key", ""),
+                "label": output.get("label", output.get("key", "")),
+                "type": output.get("type", ""),
+                "items": [
+                    item
+                    for item in output_items
+                    if _history_output_matches_contract(item, str(output.get("type", "")))
+                ],
+            }
+        )
+    summaries.extend(_summarize_app_surface_outputs(setup, output_items, run_inputs or {}, history_prompt))
+    return summaries
+
+
+def _summarize_app_surface_outputs(
+    setup: dict[str, Any],
+    output_items: list[dict[str, Any]],
+    run_inputs: dict[str, Any],
+    history_prompt: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    app = setup.get("setupSurface", {}).get("app", {})
+    if not isinstance(app, dict):
+        return []
+    summaries: list[dict[str, Any]] = []
+    for field_type, fields in (("output", app.get("outputs")), ("result", app.get("results"))):
+        if not isinstance(fields, list):
+            continue
+        for field in fields:
+            if not isinstance(field, dict):
+                continue
+            target = field.get("target")
+            target_node = str(target.get("node")) if isinstance(target, dict) else ""
+            items = [
+                item
+                for item in output_items
+                if target_node and item.get("nodeId") == target_node
+            ]
+            if field_type == "result" and not items:
+                items = _selected_switch_result_items(setup, field, output_items, run_inputs)
+            if field_type == "result" and not items and history_prompt is not None:
+                items = _execution_map_writer_result_items(setup, history_prompt, run_inputs)
+            summary = {
+                "key": field.get("key", ""),
+                "label": field.get("label", field.get("key", "")),
+                "type": field_type,
+                "visible": field.get("visible", True),
+                "target": target if isinstance(target, dict) else {},
+                "default": field.get("default"),
+                "items": items,
+            }
+            summaries.append(summary)
+    return summaries
+
+
+def _history_prompt(history_entry: dict[str, Any]) -> dict[str, Any] | None:
+    prompt_record = history_entry.get("prompt")
+    if (
+        isinstance(prompt_record, list)
+        and len(prompt_record) >= 3
+        and isinstance(prompt_record[2], dict)
+    ):
+        return prompt_record[2]
+    return None
+
+
+def _execution_map_writer_result_items(
+    setup: dict[str, Any],
+    prompt: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> list[dict[str, Any]]:
+    writer_nodes = _selected_execution_map_writer_nodes(setup, run_inputs)
+    items: list[dict[str, Any]] = []
+    for writer_node in writer_nodes:
+        node = prompt.get(writer_node)
+        if not isinstance(node, dict):
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        value = _resolve_prompt_value(prompt, inputs.get("filepath"))
+        if isinstance(value, str) and value:
+            items.append({"nodeId": writer_node, "kind": "text", "value": value})
+    return items
+
+
+def _selected_execution_map_writer_nodes(
+    setup: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> list[str]:
+    execution_map = setup.get("executionMap")
+    if not isinstance(execution_map, dict) or execution_map.get("version") != 1:
+        return []
+    routers = execution_map.get("routers")
+    if not isinstance(routers, list):
+        return []
+    out: list[str] = []
+    for router in routers:
+        if not isinstance(router, dict):
+            continue
+        selected_value = _execution_map_selected_value(setup, router, run_inputs)
+        branches = router.get("branches")
+        branch = branches.get(str(selected_value)) if isinstance(branches, dict) else None
+        writer_nodes = branch.get("writerNodes") if isinstance(branch, dict) else None
+        if isinstance(writer_nodes, list):
+            out.extend(str(node_id) for node_id in writer_nodes)
+    return list(dict.fromkeys(out))
+
+
+def _selected_switch_result_items(
+    setup: dict[str, Any],
+    result_field: dict[str, Any],
+    output_items: list[dict[str, Any]],
+    run_inputs: dict[str, Any],
+) -> list[dict[str, Any]]:
+    selected_branch = _selected_result_branch_ref(setup, result_field, run_inputs)
+    if selected_branch is None:
+        return []
+    selected_node = str(selected_branch[0])
+    return [item for item in output_items if item.get("nodeId") == selected_node]
+
+
+def _prune_prompt_for_execution_map(
+    setup: dict[str, Any],
+    prompt: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> dict[str, Any] | None:
+    execution_map = setup.get("executionMap")
+    if not isinstance(execution_map, dict) or execution_map.get("version") != 1:
+        return None
+    routers = execution_map.get("routers")
+    if not isinstance(routers, list):
+        return None
+
+    roots: set[str] = set()
+    for router in routers:
+        if not isinstance(router, dict):
+            continue
+        router_node = str(router.get("node", ""))
+        selected_value = _execution_map_selected_value(setup, router, run_inputs)
+        if selected_value is None:
+            continue
+        branches = router.get("branches")
+        branch = branches.get(str(selected_value)) if isinstance(branches, dict) else None
+        if not isinstance(branch, dict):
+            continue
+        writer_nodes = branch.get("writerNodes")
+        if isinstance(writer_nodes, list):
+            roots.update(str(node_id) for node_id in writer_nodes if str(node_id) in prompt)
+        if not writer_nodes and router_node in prompt:
+            roots.add(router_node)
+    if not roots:
+        return None
+
+    return _prune_prompt_from_roots(
+        prompt,
+        roots,
+        _selected_app_switches(setup, prompt, run_inputs),
+    )
+
+
+def _execution_map_selected_value(
+    setup: dict[str, Any],
+    router: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> int | None:
+    key = router.get("switchKey")
+    app = setup.get("setupSurface", {}).get("app", {})
+    switch = app.get("switch") if isinstance(app, dict) else None
+    if isinstance(switch, dict) and switch.get("key") == key:
+        return _selected_switch_value(switch, run_inputs)
+    selected = run_inputs.get(key) if isinstance(key, str) else None
+    if isinstance(selected, bool):
+        return None
+    if isinstance(selected, int):
+        return selected
+    if isinstance(selected, str) and selected.isdigit():
+        return int(selected)
+    return None
+
+
+def _validate_execution_map_inputs(setup: dict[str, Any], run_inputs: dict[str, Any]) -> list[str]:
+    execution_map = setup.get("executionMap")
+    if not isinstance(execution_map, dict) or execution_map.get("version") != 1:
+        return []
+    routers = execution_map.get("routers")
+    if not isinstance(routers, list):
+        return []
+    api_prompt = setup.get("apiPrompt")
+    prompt_node_ids = set(api_prompt) if isinstance(api_prompt, dict) else set()
+    app = setup.get("setupSurface", {}).get("app", {})
+    switch = app.get("switch") if isinstance(app, dict) else None
+    errors: list[str] = []
+    for router in routers:
+        if not isinstance(router, dict):
+            continue
+        selected_value = _execution_map_selected_value(setup, router, run_inputs)
+        key = router.get("switchKey")
+        if selected_value is None:
+            if isinstance(switch, dict) and switch.get("key") == key and isinstance(key, str):
+                if key not in run_inputs:
+                    errors.append(_switch_value_error(key, switch))
+            elif isinstance(key, str):
+                errors.append(f"input '{key}' must select a valid execution branch")
+            continue
+        branches = router.get("branches")
+        if not isinstance(branches, dict) or str(selected_value) not in branches:
+            errors.append(f"input '{key}' selects branch {selected_value}, but this setup has no execution branch for it")
+            continue
+        branch = branches.get(str(selected_value))
+        writer_nodes = branch.get("writerNodes") if isinstance(branch, dict) else None
+        if isinstance(writer_nodes, list) and writer_nodes:
+            missing_writer_nodes = [
+                str(node_id)
+                for node_id in writer_nodes
+                if str(node_id) not in prompt_node_ids
+            ]
+            if missing_writer_nodes:
+                errors.append(
+                    f"execution map branch {selected_value} for switch '{key}' references "
+                    f"writer node(s) not present in the prompt: {', '.join(missing_writer_nodes)}"
+                )
+        elif not writer_nodes and str(router.get("node", "")) not in prompt_node_ids:
+            errors.append(
+                f"execution map branch {selected_value} for switch '{key}' has no writer nodes "
+                "and its router node is not present in the prompt"
+            )
+    return errors
+
+
+def _prune_prompt_for_selected_app_results(
+    setup: dict[str, Any],
+    prompt: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> dict[str, Any]:
+    result_switches = _selected_result_switches(setup, prompt, run_inputs)
+    if not result_switches:
+        return prompt
+    selected_switches = _selected_app_switches(setup, prompt, run_inputs)
+
+    roots = {
+        node_id
+        for node_id, _selected_value in result_switches.values()
+        if node_id in prompt
+    }
+    for field in _app_result_fields(setup):
+        target = field.get("target")
+        if isinstance(target, dict) and str(target.get("node")) in prompt:
+            roots.add(str(target["node"]))
+
+    selected_branch_nodes = {
+        str(prompt[switch_node_id]["inputs"][f"value{selected_value}"][0])
+        for switch_node_id, (_node_id, selected_value) in result_switches.items()
+        if (
+            switch_node_id in prompt
+            and isinstance(prompt[switch_node_id], dict)
+            and isinstance(prompt[switch_node_id].get("inputs"), dict)
+            and _is_api_ref(prompt[switch_node_id]["inputs"].get(f"value{selected_value}"))
+        )
+    }
+    roots.update(
+        _selected_output_descendant_roots(
+            prompt,
+            selected_branch_nodes,
+            _setup_output_surface_node_ids(setup),
+        )
+    )
+    if not roots:
+        return prompt
+
+    return _prune_prompt_from_roots(prompt, roots, selected_switches)
+
+
+def _prune_prompt_from_roots(
+    prompt: dict[str, Any],
+    roots: set[str],
+    selected_switches: dict[str, tuple[str, int]],
+) -> dict[str, Any]:
+    keep: set[str] = set()
+
+    def visit(node_id: str) -> None:
+        if node_id in keep or node_id not in prompt:
+            return
+        keep.add(node_id)
+        node = prompt.get(node_id)
+        if not isinstance(node, dict):
+            return
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            return
+        selected_value = selected_switches.get(node_id, (None, None))[1]
+        for input_name, value in inputs.items():
+            if (
+                selected_value is not None
+                and input_name.startswith("value")
+                and input_name != f"value{selected_value}"
+            ):
+                continue
+            for ref in _api_refs(value):
+                visit(str(ref[0]))
+
+    for root in roots:
+        visit(root)
+    if not keep:
+        return prompt
+    pruned = {node_id: deepcopy(node) for node_id, node in prompt.items() if node_id in keep}
+    for node_id, (_switch_node_id, selected_value) in selected_switches.items():
+        node = pruned.get(node_id)
+        if not isinstance(node, dict):
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        node["inputs"] = {
+            key: value
+            for key, value in inputs.items()
+            if not key.startswith("value") or key == f"value{selected_value}"
+        }
+    return pruned
+
+
+def _selected_result_switches(
+    setup: dict[str, Any],
+    api_prompt: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> dict[str, tuple[str, int]]:
+    app = setup.get("setupSurface", {}).get("app", {})
+    if not isinstance(app, dict):
+        return {}
+    switch = app.get("switch")
+    if not isinstance(switch, dict):
+        return {}
+    selected_value = _selected_switch_value(switch, run_inputs)
+    if selected_value is None:
+        return {}
+    selected: dict[str, tuple[str, int]] = {}
+    for field in _app_result_fields(setup):
+        result_node_id = _result_switch_node_id(setup, field, run_inputs, api_prompt)
+        if result_node_id is not None:
+            selected[result_node_id] = (result_node_id, selected_value)
+    return selected
+
+
+def _selected_app_switches(
+    setup: dict[str, Any],
+    api_prompt: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> dict[str, tuple[str, int]]:
+    app = setup.get("setupSurface", {}).get("app", {})
+    if not isinstance(app, dict):
+        return {}
+    switch = app.get("switch")
+    if not isinstance(switch, dict):
+        return {}
+    switch_target = switch.get("target")
+    if not isinstance(switch_target, dict):
+        return {}
+    selected_value = _selected_switch_value(switch, run_inputs)
+    if selected_value is None:
+        return {}
+
+    selected: dict[str, tuple[str, int]] = {}
+    for node_id, node in api_prompt.items():
+        if not isinstance(node, dict):
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        selector_ref = _switch_selector_ref(inputs)
+        if not _selector_matches_switch_target(selector_ref, switch_target, api_prompt):
+            continue
+        if _is_api_ref(inputs.get(f"value{selected_value}")):
+            selected[str(node_id)] = (str(node_id), selected_value)
+    return selected
+
+
+def _selected_output_descendant_roots(
+    api_prompt: dict[str, Any],
+    selected_branch_nodes: set[str],
+    output_surface_node_ids: set[str],
+) -> set[str]:
+    if not selected_branch_nodes or not output_surface_node_ids:
+        return set()
+    children_by_node = _prompt_children_by_node(api_prompt)
+    roots: set[str] = set()
+    seen: set[str] = set()
+    pending = list(selected_branch_nodes)
+    while pending:
+        node_id = pending.pop()
+        if node_id in seen:
+            continue
+        seen.add(node_id)
+        for child_id in children_by_node.get(node_id, set()):
+            if child_id in output_surface_node_ids and child_id not in selected_branch_nodes:
+                roots.add(child_id)
+            pending.append(child_id)
+    return roots
+
+
+def _prompt_children_by_node(api_prompt: dict[str, Any]) -> dict[str, set[str]]:
+    children: dict[str, set[str]] = {}
+    for node_id, node in api_prompt.items():
+        if not isinstance(node, dict):
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        for value in inputs.values():
+            for ref in _api_refs(value):
+                children.setdefault(str(ref[0]), set()).add(str(node_id))
+    return children
+
+
+def _setup_output_surface_node_ids(setup: dict[str, Any]) -> set[str]:
+    setup_surface = setup.get("setupSurface", {})
+    if not isinstance(setup_surface, dict):
+        return set()
+    output_ids: set[str] = set()
+    outputs = setup_surface.get("outputs")
+    if not isinstance(outputs, list):
+        return output_ids
+    for group in outputs:
+        if not isinstance(group, dict) or not isinstance(group.get("nodes"), list):
+            continue
+        for node in group["nodes"]:
+            if isinstance(node, dict) and node.get("id") is not None:
+                output_ids.add(str(node["id"]))
+    return output_ids
+
+
+def _app_result_fields(setup: dict[str, Any]) -> list[dict[str, Any]]:
+    app = setup.get("setupSurface", {}).get("app", {})
+    if not isinstance(app, dict) or not isinstance(app.get("results"), list):
+        return []
+    return [field for field in app["results"] if isinstance(field, dict)]
+
+
+def _result_switch_node_id(
+    setup: dict[str, Any],
+    result_field: dict[str, Any],
+    run_inputs: dict[str, Any],
+    api_prompt: dict[str, Any] | None = None,
+) -> str | None:
+    app = setup.get("setupSurface", {}).get("app", {})
+    if not isinstance(app, dict):
+        return None
+    switch = app.get("switch")
+    if not isinstance(switch, dict):
+        return None
+    selected_value = _selected_switch_value(switch, run_inputs)
+    if selected_value is None:
+        return None
+
+    api_prompt = api_prompt if isinstance(api_prompt, dict) else setup.get("apiPrompt")
+    if not isinstance(api_prompt, dict):
+        return None
+    target = result_field.get("target")
+    if not isinstance(target, dict):
+        return None
+    result_node = api_prompt.get(str(target.get("node")))
+    if not isinstance(result_node, dict):
+        return None
+    result_inputs = result_node.get("inputs")
+    if not isinstance(result_inputs, dict):
+        return None
+    result_ref = result_inputs.get(str(target.get("input")))
+    if not _is_api_ref(result_ref):
+        return None
+
+    switch_node_id = str(result_ref[0])
+    switch_node = api_prompt.get(switch_node_id)
+    if not isinstance(switch_node, dict):
+        return None
+    switch_inputs = switch_node.get("inputs")
+    if not isinstance(switch_inputs, dict):
+        return None
+    selector_ref = _switch_selector_ref(switch_inputs)
+    switch_target = switch.get("target")
+    if isinstance(switch_target, dict) and not _selector_matches_switch_target(
+        selector_ref,
+        switch_target,
+        api_prompt,
+    ):
+        return None
+    if not _is_api_ref(switch_inputs.get(f"value{selected_value}")):
+        return None
+    return switch_node_id
+
+
+def _selected_result_branch_ref(
+    setup: dict[str, Any],
+    result_field: dict[str, Any],
+    run_inputs: dict[str, Any],
+) -> list[Any] | None:
+    api_prompt = setup.get("apiPrompt")
+    if not isinstance(api_prompt, dict):
+        return None
+    switch_node_id = _result_switch_node_id(setup, result_field, run_inputs, api_prompt)
+    if switch_node_id is None:
+        return None
+    switch_node = api_prompt.get(switch_node_id)
+    if not isinstance(switch_node, dict):
+        return None
+    switch_inputs = switch_node.get("inputs")
+    if not isinstance(switch_inputs, dict):
+        return None
+    switch = setup.get("setupSurface", {}).get("app", {}).get("switch")
+    selected_value = _selected_switch_value(switch, run_inputs) if isinstance(switch, dict) else None
+    if selected_value is None:
+        return None
+    branch_ref = switch_inputs.get(f"value{selected_value}")
+    return branch_ref if _is_api_ref(branch_ref) else None
+
+
+def _selected_switch_value(switch: dict[str, Any], run_inputs: dict[str, Any]) -> int | None:
+    key = switch.get("key")
+    selected = run_inputs.get(key) if isinstance(key, str) and key in run_inputs else switch.get("default")
+    return _switch_option_value(switch, selected)
+
+
+def _selector_matches_switch_target(selector_ref: Any, switch_target: dict[str, Any], api_prompt: dict[str, Any]) -> bool:
+    if not _is_api_ref(selector_ref):
+        return False
+    source_node_id = str(selector_ref[0])
+    target_node_id = str(switch_target.get("node"))
+    if source_node_id != target_node_id:
+        return False
+    source_node = api_prompt.get(source_node_id)
+    if not isinstance(source_node, dict):
+        return False
+    outputs = _publish_input_output_slots(source_node)
+    return outputs.get("switch") == int(selector_ref[1])
+
+
+def _switch_selector_ref(switch_inputs: dict[str, Any]) -> Any:
+    if "select" in switch_inputs:
+        return switch_inputs.get("select")
+    return switch_inputs.get("index")
+
+
+def _publish_input_output_slots(api_node: dict[str, Any]) -> dict[str, int]:
+    if api_node.get("class_type") != "Koolook_PublishInput":
+        return {}
+    return {
+        "sequence_folder": 0,
+        "qt_file": 1,
+        "single_file": 2,
+        "prompt": 3,
+        "switch": 4,
+    }
+
+
+def _resolve_prompt_value(prompt: dict[str, Any], value: Any) -> Any:
+    if not _is_api_ref(value):
+        return value
+    node_id = str(value[0])
+    output_index = int(value[1])
+    node = prompt.get(node_id)
+    if not isinstance(node, dict):
+        return None
+    class_type = node.get("class_type")
+    inputs = node.get("inputs")
+    if not isinstance(inputs, dict):
+        return None
+    if class_type == "Koolook_PublishOutput":
+        values = (
+            inputs.get("folder"),
+            inputs.get("name"),
+            inputs.get("version"),
+        )
+        return values[output_index] if output_index < len(values) else None
+    if class_type == "EasyAIPipeline":
+        if "WRITE_file_path" in inputs:
+            values = (
+                inputs.get("WRITE_file_path"),
+                inputs.get("output_name", ""),
+                inputs.get("version_string", ""),
+                inputs.get("output_directory", ""),
+                inputs.get("shot_duration", 0),
+                inputs.get("seed_value", 0),
+                inputs.get("shot_name", ""),
+            )
+            return values[output_index] if output_index < len(values) else None
+        resolved_inputs = {
+            key: _resolve_prompt_value(prompt, input_value)
+            for key, input_value in inputs.items()
+        }
+        try:
+            try:
+                from .k_ai_pipeline import build_pipeline_outputs
+            except ImportError:  # pragma: no cover - standalone test/import context
+                from k_ai_pipeline import build_pipeline_outputs
+
+            values = build_pipeline_outputs(
+                **resolved_inputs,
+                create_directory=False,
+                check_overwrite=False,
+            )
+        except Exception:
+            return None
+        return values[output_index] if output_index < len(values) else None
+    return None
+
+
+def _is_api_ref(value: Any) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) == 2
+        and isinstance(value[0], (str, int))
+        and not isinstance(value[1], bool)
+        and isinstance(value[1], int)
+    )
+
+
+def _api_refs(value: Any) -> list[list[Any]]:
+    if _is_api_ref(value):
+        return [value]
+    if isinstance(value, dict):
+        refs: list[list[Any]] = []
+        for child in value.values():
+            refs.extend(_api_refs(child))
+        return refs
+    if isinstance(value, list):
+        refs = []
+        for child in value:
+            refs.extend(_api_refs(child))
+        return refs
+    return []
+
+
+def _flatten_history_outputs(raw_outputs: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw_outputs, dict):
+        return []
+    items: list[dict[str, Any]] = []
+    for node_id, node_outputs in raw_outputs.items():
+        if not isinstance(node_outputs, dict):
+            continue
+        for kind, values in node_outputs.items():
+            if not isinstance(values, list):
+                continue
+            for value in values:
+                item = {"nodeId": str(node_id), "kind": str(kind)}
+                if isinstance(value, dict):
+                    item.update(value)
+                else:
+                    item["value"] = value
+                items.append(item)
+    return items
+
+
+def _history_output_matches_contract(item: dict[str, Any], contract_type: str) -> bool:
+    kind = str(item.get("kind", "")).lower()
+    if contract_type == "video":
+        return kind in {"video", "videos", "animated"}
+    if contract_type == "image":
+        return kind in {"image", "images"}
+    return True

ComfyUI/custom_nodes/koolook/koolook_setups.py

@@ -0,0 +1,2032 @@
+"""Published workflow setup registry boundary.
+
+This module owns the server-side shape for externally callable Koolook
+setups. Callers use this boundary instead of reading sidebar workflow or
+snapshot storage directly.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import math
+import os
+from pathlib import Path
+import re
+import tempfile
+from typing import Any
+
+
+DEFAULT_SETUPS_SUBDIR = "koolook-published-setups"
+DEFAULT_SETUPS_FILENAME = "setups.json"
+SAMPLE_SETUPS_PATH = (
+    Path(__file__).resolve().parent / "web" / "published_setups_sample.json"
+)
+SUPPORTED_SCHEMA_VERSION = 1
+SETUP_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+VALIDATION_STATUSES = {"valid", "draft", "invalid"}
+PUBLISH_INPUT_CLASS = "Koolook_PublishInput"
+PUBLISH_OUTPUT_CLASS = "Koolook_PublishOutput"
+PUBLISH_RESULT_CLASS = "Koolook_PublishResult"
+PUBLISH_ROUTER_CLASS = "Koolook_PublishRouter"
+VISUAL_ONLY_API_NODE_TYPES = {"Label (rgthree)", "Note"}
+SINK_ONLY_API_NODE_TYPES = {"SetNode"}
+PUBLISH_INPUT_FIELDS = (
+    ("sequence_folder", "Sequence folder", True),
+    ("qt_file", "QT file", True),
+    ("single_file", "Single file", True),
+)
+# The prompt is an always-on field, independent of the EXR/QT/Img source switch
+# (an external user picks a source AND can describe the shot). The author's
+# prompt-widget text becomes a placeholder hint; the submitted default is empty
+# so an untouched hint is never sent as the real prompt. Mirror of the JS in
+# web/sidebar/published_surface.js -- keep the two in sync.
+PUBLISH_PROMPT_HELP = "Describe the shot in one simple line: subject + action + setting."
+PUBLISH_INPUT_MODES = (
+    (0, "EXR", "sequence_folder"),
+    (1, "QT", "qt_file"),
+    (2, "Img", "single_file"),
+    (3, "Prompt", "prompt"),
+)
+PUBLISH_OUTPUT_FIELDS = (
+    ("folder", "Output folder", True),
+    ("name", "Output name", True),
+    ("version", "Version", True),
+)
+PUBLISH_RESULT_FIELDS = (
+    ("result", "Result", True),
+)
+WIDGET_ONLY_INPUTS_BY_CLASS = {
+    "Text Multiline": ("text",),
+    "Koolook_PublishInput": ("mode", "sequence_folder", "qt_file", "single_file", "prompt"),
+    "Koolook_PublishOutput": ("folder", "name", "version"),
+    "Koolook_PublishResult": ("result",),
+    "Koolook_PublishRouter": (),
+    "EasyAIPipeline": (
+        "shot_duration",
+        "seed_value",
+        "instruction",
+        "base_directory_path",
+        "extension",
+        "shot_name",
+        "ai_method",
+        "version",
+        "disable_versioning",
+        "enable_overwrite",
+        "no_subfolders",
+    ),
+}
+WIDGET_ONLY_INPUT_DEFAULTS = {
+    "EasyAIPipeline": {
+        "no_subfolders": False,
+    },
+}
+
+REQUIRED_SETUP_KEYS = (
+    "schemaVersion",
+    "id",
+    "version",
+    "updatedAt",
+    "metadata",
+    "visualGraph",
+    "apiPrompt",
+    "inputContract",
+    "outputContract",
+    "source",
+    "validation",
+)
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    valid: bool
+    setup: dict[str, Any]
+    diagnostics: list[str]
+
+
+@dataclass(frozen=True)
+class ApiPromptConversionResult:
+    api_prompt: dict[str, Any] | None
+    diagnostics: list[str]
+
+
+class StaticSetupStorage:
+    """In-memory setup storage adapter for tests and seeded fixtures."""
+
+    def __init__(self, records: list[dict[str, Any]]) -> None:
+        self._records = records
+        self.diagnostics: list[str] = []
+
+    def load_setups(self) -> list[dict[str, Any]]:
+        return list(self._records)
+
+    def save_setups(self, records: list[dict[str, Any]]) -> None:
+        self._records = list(records)
+
+
+class FileSetupStorage:
+    """JSON-file storage adapter for published setup records."""
+
+    def __init__(self, path: Path, fallback_path: Path | None = None) -> None:
+        self.path = path
+        self.fallback_path = fallback_path
+        self.diagnostics: list[str] = []
+
+    def load_setups(self) -> list[dict[str, Any]]:
+        self.diagnostics = []
+        path = self.path
+        if not path.is_file() and self.fallback_path is not None:
+            path = self.fallback_path
+            self.diagnostics.append(
+                f"{self.path}: missing; using bundled sample {self.fallback_path}"
+            )
+        if not path.is_file():
+            return []
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            self.diagnostics.append(f"{path}: could not read published setups: {exc}")
+            return []
+        if isinstance(raw, dict):
+            raw = raw.get("setups", [])
+        if not isinstance(raw, list):
+            self.diagnostics.append(
+                f"{path}: published setup storage must be a list or {{setups: [...]}}"
+            )
+            return []
+        return [item for item in raw if isinstance(item, dict)]
+
+    def load_primary_setups(self) -> list[dict[str, Any]]:
+        self.diagnostics = []
+        if not self.path.is_file():
+            return []
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            self.diagnostics.append(f"{self.path}: could not read published setups: {exc}")
+            return []
+        if isinstance(raw, dict):
+            raw = raw.get("setups", [])
+        if not isinstance(raw, list):
+            self.diagnostics.append(
+                f"{self.path}: published setup storage must be a list or {{setups: [...]}}"
+            )
+            return []
+        return [item for item in raw if isinstance(item, dict)]
+
+    def save_setups(self, records: list[dict[str, Any]]) -> None:
+        self.diagnostics = []
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"setups": records}
+        tmp_fd, tmp_name = tempfile.mkstemp(
+            prefix=f"{self.path.stem}.",
+            suffix=".tmp",
+            dir=str(self.path.parent),
+        )
+        try:
+            with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+                json.dump(payload, f, indent=2)
+                f.write("\n")
+            os.replace(tmp_name, self.path)
+        except OSError:
+            try:
+                if os.path.exists(tmp_name):
+                    os.unlink(tmp_name)
+            except OSError:
+                pass
+            raise
+
+
+class PublishedSetupRegistry:
+    """Read-only registry facade for published setup catalog consumers."""
+
+    def __init__(self, storage: StaticSetupStorage | FileSetupStorage) -> None:
+        self._storage = storage
+        self.diagnostics: list[str] = []
+
+    @property
+    def storage_path(self) -> Path | None:
+        """Filesystem path of the backing ``setups.json`` when the storage
+        adapter is file-backed; ``None`` for in-memory storage. Lets callers
+        surface where a publish landed without reaching into the adapter."""
+        path = getattr(self._storage, "path", None)
+        return path if isinstance(path, Path) else None
+
+    def _valid_setups(self) -> list[dict[str, Any]]:
+        self.diagnostics = []
+        out: list[dict[str, Any]] = []
+        for raw in self._storage.load_setups():
+            result = validate_setup(raw)
+            if result.valid:
+                out.append(result.setup)
+                continue
+            setup_id = raw.get("id", "<unknown>") if isinstance(raw, dict) else "<unknown>"
+            for diagnostic in result.diagnostics:
+                self.diagnostics.append(f"{setup_id}: {diagnostic}")
+        self.diagnostics.extend(getattr(self._storage, "diagnostics", []))
+        out.sort(key=lambda setup: str(setup["metadata"]["title"]).lower())
+        return out
+
+    def listSetups(self) -> list[dict[str, Any]]:
+        return [_catalog_summary(setup) for setup in self._valid_setups()]
+
+    def getSetup(self, setup_id: str) -> dict[str, Any] | None:
+        for setup in self._valid_setups():
+            if setup["id"] == setup_id:
+                return setup
+        return None
+
+    def publishSetup(
+        self,
+        *,
+        visualGraph: Any,
+        metadata: Any,
+        inputContract: Any,
+        outputContract: Any,
+        source: Any,
+        apiPrompt: Any = None,
+    ) -> ValidationResult:
+        diagnostics = []
+        for name, value in (
+            ("visualGraph", visualGraph),
+            ("metadata", metadata),
+            ("inputContract", inputContract),
+            ("outputContract", outputContract),
+            ("source", source),
+        ):
+            if not isinstance(value, dict):
+                diagnostics.append(f"{name} must be an object")
+        if diagnostics:
+            return ValidationResult(False, {}, diagnostics)
+
+        if apiPrompt is None:
+            conversion = _convert_visual_graph_to_api_prompt(visualGraph)
+            if conversion.diagnostics:
+                return ValidationResult(False, {}, conversion.diagnostics)
+            api_prompt = conversion.api_prompt
+        elif isinstance(apiPrompt, dict):
+            api_prompt = deepcopy(apiPrompt)
+        else:
+            return ValidationResult(False, {}, ["apiPrompt must be an object when present"])
+        surface_geometry_diagnostics = []
+        if _uses_group_authored_surface(inputContract, outputContract):
+            surface_geometry_diagnostics = _validate_setup_surface_geometry(visualGraph)
+        if surface_geometry_diagnostics:
+            return ValidationResult(False, {}, surface_geometry_diagnostics)
+        setup = _build_draft_setup(
+            visualGraph=visualGraph,
+            apiPrompt=api_prompt,
+            metadata=metadata,
+            inputContract=inputContract,
+            outputContract=outputContract,
+            source=source,
+        )
+        result = validate_setup(setup)
+        diagnostics = list(result.diagnostics)
+        if result.valid:
+            setup = result.setup
+        diagnostics.extend(_validate_contract_targets(visualGraph, inputContract))
+        diagnostics.extend(_validate_api_prompt_contract_targets(setup.get("apiPrompt"), inputContract))
+        diagnostics.extend(_validate_setup_surface(setup, inputContract, outputContract))
+        if diagnostics:
+            return ValidationResult(False, {}, diagnostics)
+
+        load_for_write = getattr(self._storage, "load_primary_setups", self._storage.load_setups)
+        records = [
+            existing
+            for existing in load_for_write()
+            if existing.get("id") != setup["id"]
+        ]
+        records.append(setup)
+        self._storage.save_setups(records)
+        return ValidationResult(True, setup, [])
+
+
+def validate_setup(value: Any) -> ValidationResult:
+    """Validate one published setup object through the public schema boundary."""
+    diagnostics: list[str] = []
+    if not isinstance(value, dict):
+        return ValidationResult(False, {}, ["setup must be a JSON object"])
+    setup = deepcopy(value)
+
+    for key in REQUIRED_SETUP_KEYS:
+        if key not in value:
+            diagnostics.append(f"missing required field: {key}")
+
+    if diagnostics:
+        return ValidationResult(False, {}, diagnostics)
+
+    _validate_scalar(setup, "id", str, diagnostics)
+    if isinstance(setup.get("id"), str) and not SETUP_ID_RE.match(setup["id"]):
+        diagnostics.append("id must be stable URL-safe text")
+    _validate_scalar(setup, "schemaVersion", int, diagnostics)
+    if setup.get("schemaVersion") != SUPPORTED_SCHEMA_VERSION:
+        diagnostics.append(
+            f"unsupported schemaVersion: {setup.get('schemaVersion')}; "
+            f"expected {SUPPORTED_SCHEMA_VERSION}"
+        )
+    _validate_scalar(setup, "version", (int, str), diagnostics)
+    _validate_iso_timestamp(setup.get("updatedAt"), diagnostics)
+    _validate_metadata(setup.get("metadata"), diagnostics)
+    _validate_mapping(setup.get("visualGraph"), "visualGraph", diagnostics)
+    if setup.get("apiPrompt") is not None:
+        _validate_mapping(setup.get("apiPrompt"), "apiPrompt", diagnostics)
+        if isinstance(setup.get("visualGraph"), dict) and isinstance(setup.get("apiPrompt"), dict):
+            conversion = None
+            if _api_prompt_needs_visual_normalization(setup["apiPrompt"], setup["visualGraph"]):
+                conversion = _convert_visual_graph_to_api_prompt(setup["visualGraph"])
+            if conversion is not None and conversion.diagnostics:
+                diagnostics.extend(conversion.diagnostics)
+            elif conversion is not None and conversion.api_prompt is not None:
+                setup["apiPrompt"] = conversion.api_prompt
+    _validate_contract(setup.get("inputContract"), "inputContract", "inputs", diagnostics)
+    _validate_contract(setup.get("outputContract"), "outputContract", "outputs", diagnostics)
+    _validate_persisted_setup_surface(setup, diagnostics)
+    _validate_source(setup.get("source"), diagnostics)
+    _validate_validation(setup.get("validation"), diagnostics)
+    if (
+        isinstance(setup.get("validation"), dict)
+        and setup["validation"].get("status") == "valid"
+        and setup.get("apiPrompt") is None
+    ):
+        diagnostics.append("validation.status valid requires apiPrompt")
+
+    return ValidationResult(
+        valid=not diagnostics,
+        setup=setup if not diagnostics else {},
+        diagnostics=diagnostics,
+    )
+
+
+def _build_draft_setup(
+    *,
+    visualGraph: dict[str, Any],
+    apiPrompt: dict[str, Any] | None,
+    metadata: dict[str, Any],
+    inputContract: dict[str, Any],
+    outputContract: dict[str, Any],
+    source: dict[str, Any],
+) -> dict[str, Any]:
+    title = metadata.get("title", "")
+    setup_id = metadata.get("id", "")
+    setup_surface = _infer_setup_surface(visualGraph)
+    setup = {
+        "schemaVersion": SUPPORTED_SCHEMA_VERSION,
+        "id": setup_id,
+        "version": 1,
+        "updatedAt": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "metadata": {
+            "title": title,
+            "description": metadata.get("description", ""),
+            "category": metadata.get("category", ""),
+            "tags": metadata.get("tags", []),
+            "previewImage": metadata.get("previewImage", ""),
+        },
+        "visualGraph": visualGraph,
+        "apiPrompt": apiPrompt,
+        "inputContract": inputContract,
+        "outputContract": outputContract,
+        "setupSurface": setup_surface,
+        "source": source,
+        "validation": {
+            "status": "valid" if apiPrompt is not None else "draft",
+            "diagnostics": [] if apiPrompt is not None else ["API prompt conversion pending."],
+        },
+    }
+    execution_map = _build_execution_map(setup)
+    if execution_map is not None:
+        setup["executionMap"] = execution_map
+    return setup
+
+
+def _infer_setup_surface(visual_graph: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "sourceInputs": _nodes_in_named_groups(visual_graph, "Koolook Input"),
+        "outputs": _nodes_in_named_groups(visual_graph, "Koolook Output"),
+        "controls": [],
+        "app": _infer_app_surface(visual_graph),
+    }
+
+
+def _infer_app_surface(visual_graph: dict[str, Any]) -> dict[str, Any]:
+    input_nodes = _nodes_in_group(visual_graph, "Koolook Input")
+    output_nodes = _nodes_in_group(visual_graph, "Koolook Output")
+    input_node = _first_node_of_type(input_nodes, PUBLISH_INPUT_CLASS)
+    output_node = _first_node_of_type(output_nodes, PUBLISH_OUTPUT_CLASS)
+    result_node = _first_node_of_type(output_nodes, PUBLISH_RESULT_CLASS)
+    inputs = _publish_input_fields(input_node)
+    prompt = _publish_prompt_field(input_node)
+    if prompt is not None:
+        inputs.append(prompt)
+    outputs = _publish_output_fields(output_node)
+    app: dict[str, Any] = {
+        "inputs": inputs,
+        "outputs": outputs,
+        "results": _publish_result_fields(result_node),
+    }
+    if input_node is not None:
+        app["switch"] = _publish_input_switch(input_node, inputs)
+    return app
+
+
+def _first_node_of_type(
+    nodes: list[dict[str, Any]],
+    class_type: str,
+) -> dict[str, Any] | None:
+    for node in nodes:
+        if node.get("type") == class_type:
+            return node
+    return None
+
+
+def _publish_input_fields(node: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if node is None:
+        return []
+    return [
+        {
+            "key": key,
+            "label": label,
+            "visible": visible,
+            "target": {
+                "node": str(node.get("id")),
+                "input": key,
+            },
+            "default": _app_widget_value(node, key),
+        }
+        for key, label, visible in PUBLISH_INPUT_FIELDS
+    ]
+
+
+def _publish_output_fields(node: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if node is None:
+        return []
+    return [
+        {
+            "key": key,
+            "label": label,
+            "visible": visible,
+            "target": {
+                "node": str(node.get("id")),
+                "input": key,
+            },
+            "default": _app_widget_value(node, key),
+        }
+        for key, label, visible in PUBLISH_OUTPUT_FIELDS
+    ]
+
+
+def _publish_result_fields(node: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if node is None:
+        return []
+    return [
+        {
+            "key": key,
+            "label": label,
+            "visible": visible,
+            "target": {
+                "node": str(node.get("id")),
+                "input": key,
+            },
+            "default": _app_widget_value(node, key),
+        }
+        for key, label, visible in PUBLISH_RESULT_FIELDS
+    ]
+
+
+def _publish_prompt_field(node: dict[str, Any] | None) -> dict[str, Any] | None:
+    if node is None:
+        return None
+    hint = _app_widget_value(node, "prompt")
+    return {
+        "key": "prompt",
+        "label": "Prompt",
+        "visible": True,
+        "standalone": True,
+        "multiline": True,
+        "target": {"node": str(node.get("id")), "input": "prompt"},
+        "default": "",
+        "placeholder": hint if isinstance(hint, str) else "",
+        "help": PUBLISH_PROMPT_HELP,
+    }
+
+
+def _publish_input_switch(
+    node: dict[str, Any],
+    inputs: list[dict[str, Any]],
+) -> dict[str, Any]:
+    inputs_by_key = {item["key"]: item for item in inputs}
+    return {
+        "key": "switch",
+        "label": "Input type",
+        "visible": True,
+        "target": {"node": str(node.get("id")), "input": "mode"},
+        "default": _publish_input_mode_index(_app_widget_value(node, "mode")),
+        "options": [
+            {
+                "value": value,
+                "label": label,
+                # Standalone fields (e.g. the always-on prompt) are not source
+                # modes, so they never appear as a switch option.
+                "visible": bool(inputs_by_key.get(input_key, {}).get("visible"))
+                and not inputs_by_key.get(input_key, {}).get("standalone"),
+                "input": input_key,
+            }
+            for value, label, input_key in PUBLISH_INPUT_MODES
+        ],
+    }
+
+
+def _publish_input_mode_index(value: Any) -> int:
+    if isinstance(value, int):
+        return value
+    for mode_value, label, _input_key in PUBLISH_INPUT_MODES:
+        if str(value).strip().lower() == label.lower():
+            return mode_value
+    return 2
+
+
+def _build_execution_map(setup: dict[str, Any]) -> dict[str, Any] | None:
+    api_prompt = setup.get("apiPrompt")
+    if not isinstance(api_prompt, dict):
+        return None
+    app = setup.get("setupSurface", {}).get("app", {})
+    switch = app.get("switch") if isinstance(app, dict) else None
+    switch_target = switch.get("target") if isinstance(switch, dict) else None
+    if not isinstance(switch_target, dict):
+        return None
+    output_surface_ids = _setup_output_surface_node_ids(setup)
+    if not output_surface_ids:
+        return None
+    routers: list[dict[str, Any]] = []
+    for node_id, node in api_prompt.items():
+        if not isinstance(node, dict) or node.get("class_type") != PUBLISH_ROUTER_CLASS:
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        selector_ref = inputs.get("selector")
+        payload_ref = inputs.get("payload")
+        if not _api_ref_matches_target_output(selector_ref, switch_target, api_prompt, "switch"):
+            continue
+        branches: dict[str, dict[str, Any]] = {}
+        for value, label, _input_key in PUBLISH_INPUT_MODES:
+            branches[str(value)] = {
+                "label": label,
+                "output": value,
+                "writerNodes": _writer_nodes_for_router_output(
+                    api_prompt,
+                    str(node_id),
+                    value,
+                    output_surface_ids,
+                ),
+            }
+        router: dict[str, Any] = {
+            "node": str(node_id),
+            "switchKey": str(switch.get("key", "switch")),
+            "selector": {"node": str(selector_ref[0]), "output": int(selector_ref[1])},
+            "branches": branches,
+        }
+        if _is_api_ref(payload_ref):
+            router["payload"] = {"node": str(payload_ref[0]), "output": int(payload_ref[1])}
+        routers.append(router)
+    if not routers:
+        return None
+    routers.sort(key=lambda item: item["node"])
+    return {"version": 1, "routers": routers}
+
+
+def _writer_nodes_for_router_output(
+    api_prompt: dict[str, Any],
+    router_node_id: str,
+    router_output: int,
+    output_surface_ids: set[str],
+) -> list[str]:
+    children = _prompt_children_by_ref(api_prompt)
+    out: list[str] = []
+    seen: set[str] = set()
+    pending = list(children.get((router_node_id, router_output), []))
+    while pending:
+        node_id = pending.pop(0)
+        if node_id in seen:
+            continue
+        seen.add(node_id)
+        if node_id in output_surface_ids and node_id != router_node_id:
+            out.append(node_id)
+        for child_ids in _children_for_node(children, node_id):
+            pending.extend(child_ids)
+    return sorted(dict.fromkeys(out))
+
+
+def _children_for_node(
+    children: dict[tuple[str, int], list[str]],
+    node_id: str,
+) -> list[list[str]]:
+    return [
+        child_ids
+        for (source_node_id, _source_slot), child_ids in children.items()
+        if source_node_id == node_id
+    ]
+
+
+def _prompt_children_by_ref(api_prompt: dict[str, Any]) -> dict[tuple[str, int], list[str]]:
+    children: dict[tuple[str, int], list[str]] = {}
+    for node_id, node in api_prompt.items():
+        if not isinstance(node, dict):
+            continue
+        inputs = node.get("inputs")
+        if not isinstance(inputs, dict):
+            continue
+        for value in inputs.values():
+            for ref in _api_refs(value):
+                children.setdefault((str(ref[0]), int(ref[1])), []).append(str(node_id))
+    return children
+
+
+def _setup_output_surface_node_ids(setup: dict[str, Any]) -> set[str]:
+    surface = setup.get("setupSurface")
+    if not isinstance(surface, dict) or not isinstance(surface.get("outputs"), list):
+        return set()
+    out: set[str] = set()
+    for group in surface["outputs"]:
+        if not isinstance(group, dict) or not isinstance(group.get("nodes"), list):
+            continue
+        for node in group["nodes"]:
+            if isinstance(node, dict) and node.get("id") is not None:
+                out.add(str(node["id"]))
+    return out
+
+
+def _api_ref_matches_target_output(
+    value: Any,
+    target: dict[str, Any],
+    api_prompt: dict[str, Any],
+    output_name: str,
+) -> bool:
+    if not _is_api_ref(value):
+        return False
+    node_id = str(value[0])
+    if node_id != str(target.get("node")):
+        return False
+    node = api_prompt.get(node_id)
+    if not isinstance(node, dict):
+        return False
+    return _publish_input_output_slots(node).get(output_name) == int(value[1])
+
+
+def _publish_input_output_slots(api_node: dict[str, Any]) -> dict[str, int]:
+    if api_node.get("class_type") != PUBLISH_INPUT_CLASS:
+        return {}
+    return {
+        "sequence_folder": 0,
+        "qt_file": 1,
+        "single_file": 2,
+        "prompt": 3,
+        "switch": 4,
+    }
+
+
+def _is_api_ref(value: Any) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) == 2
+        and isinstance(value[0], (str, int))
+        and not isinstance(value[1], bool)
+        and isinstance(value[1], int)
+    )
+
+
+def _api_refs(value: Any) -> list[list[Any]]:
+    if _is_api_ref(value):
+        return [value]
+    if isinstance(value, dict):
+        refs: list[list[Any]] = []
+        for child in value.values():
+            refs.extend(_api_refs(child))
+        return refs
+    if isinstance(value, list):
+        refs = []
+        for child in value:
+            refs.extend(_api_refs(child))
+        return refs
+    return []
+
+
+def _app_widget_value(node: dict[str, Any], key: str) -> Any:
+    widget_values = node.get("widgets_values")
+    if isinstance(widget_values, dict):
+        return widget_values.get(key)
+    if isinstance(widget_values, list):
+        widget_names = WIDGET_ONLY_INPUTS_BY_CLASS.get(str(node.get("type")), ())
+        for index, name in enumerate(widget_names):
+            if name == key and index < len(widget_values):
+                return widget_values[index]
+    return None
+
+
+def _validate_setup_surface(
+    setup: dict[str, Any],
+    input_contract: dict[str, Any],
+    output_contract: dict[str, Any],
+) -> list[str]:
+    if not _uses_group_authored_surface(input_contract, output_contract):
+        return []
+    surface = setup.get("setupSurface")
+    diagnostics: list[str] = []
+    if not isinstance(surface, dict) or not surface.get("sourceInputs"):
+        diagnostics.append("setupSurface.sourceInputs requires a non-empty Koolook Input group")
+    if not isinstance(surface, dict) or not surface.get("outputs"):
+        diagnostics.append("setupSurface.outputs requires a non-empty Koolook Output group")
+    return diagnostics
+
+
+def _validate_persisted_setup_surface(
+    setup: dict[str, Any],
+    diagnostics: list[str],
+) -> None:
+    surface = setup.get("setupSurface")
+    input_contract = setup.get("inputContract")
+    output_contract = setup.get("outputContract")
+    group_authored = (
+        isinstance(input_contract, dict)
+        and isinstance(output_contract, dict)
+        and _uses_group_authored_surface(input_contract, output_contract)
+    )
+    if surface is None:
+        if group_authored:
+            diagnostics.append("setupSurface must be a JSON object for group-authored setups")
+        return
+    if not isinstance(surface, dict):
+        diagnostics.append("setupSurface must be a JSON object")
+        return
+    for key in ("sourceInputs", "outputs", "controls"):
+        if key in surface and not isinstance(surface[key], list):
+            diagnostics.append(f"setupSurface.{key} must be a list")
+    if group_authored:
+        if not isinstance(surface.get("sourceInputs"), list) or not surface["sourceInputs"]:
+            diagnostics.append("setupSurface.sourceInputs requires a non-empty Koolook Input group")
+        if not isinstance(surface.get("outputs"), list) or not surface["outputs"]:
+            diagnostics.append("setupSurface.outputs requires a non-empty Koolook Output group")
+    for key in ("sourceInputs", "outputs", "controls"):
+        items = surface.get(key)
+        if isinstance(items, list):
+            _validate_surface_entries(items, f"setupSurface.{key}", diagnostics)
+    if "app" in surface:
+        _validate_surface_app(
+            surface["app"],
+            "setupSurface.app",
+            diagnostics,
+            setup.get("visualGraph"),
+            setup.get("apiPrompt"),
+        )
+
+
+def _validate_surface_entries(
+    entries: list[Any],
+    path: str,
+    diagnostics: list[str],
+) -> None:
+    for entry_index, entry in enumerate(entries):
+        entry_path = f"{path}[{entry_index}]"
+        if not isinstance(entry, dict):
+            diagnostics.append(f"{entry_path} must be a JSON object")
+            continue
+        if not isinstance(entry.get("group"), str) or not entry["group"].strip():
+            diagnostics.append(f"{entry_path}.group must be non-empty text")
+        nodes = entry.get("nodes")
+        if not isinstance(nodes, list):
+            diagnostics.append(f"{entry_path}.nodes must be a list")
+            continue
+        for node_index, node in enumerate(nodes):
+            node_path = f"{entry_path}.nodes[{node_index}]"
+            if not isinstance(node, dict):
+                diagnostics.append(f"{node_path} must be a JSON object")
+                continue
+            for field in ("id", "type", "title"):
+                if not isinstance(node.get(field), str) or not node[field].strip():
+                    diagnostics.append(f"{node_path}.{field} must be non-empty text")
+
+
+def _validate_surface_app(
+    app: Any,
+    path: str,
+    diagnostics: list[str],
+    visual_graph: Any,
+    api_prompt: Any,
+) -> None:
+    if not isinstance(app, dict):
+        diagnostics.append(f"{path} must be a JSON object")
+        return
+    node_by_id = _visual_node_index(visual_graph)
+    api_prompt = api_prompt if isinstance(api_prompt, dict) else None
+    input_keys: set[str] = set()
+    for key in ("inputs", "outputs", "results"):
+        value = app.get(key)
+        if value is None:
+            continue
+        if not isinstance(value, list):
+            diagnostics.append(f"{path}.{key} must be a list")
+            continue
+        keys = _validate_surface_app_fields(
+            value,
+            f"{path}.{key}",
+            diagnostics,
+            node_by_id,
+            api_prompt,
+        )
+        if key == "inputs":
+            input_keys = keys
+    if "switch" in app:
+        _validate_surface_app_switch(
+            app["switch"],
+            f"{path}.switch",
+            diagnostics,
+            node_by_id,
+            api_prompt,
+            input_keys,
+        )
+
+
+def _validate_surface_app_fields(
+    fields: list[Any],
+    path: str,
+    diagnostics: list[str],
+    node_by_id: dict[str, dict[str, Any]],
+    api_prompt: dict[str, Any] | None,
+) -> set[str]:
+    keys: set[str] = set()
+    for field_index, field in enumerate(fields):
+        field_path = f"{path}[{field_index}]"
+        if not isinstance(field, dict):
+            diagnostics.append(f"{field_path} must be a JSON object")
+            continue
+        _validate_non_empty_text(field.get("key"), f"{field_path}.key", diagnostics)
+        if isinstance(field.get("key"), str) and field["key"].strip():
+            keys.add(field["key"])
+        _validate_non_empty_text(field.get("label"), f"{field_path}.label", diagnostics)
+        if "visible" in field and not isinstance(field["visible"], bool):
+            diagnostics.append(f"{field_path}.visible must be a boolean")
+        _validate_surface_app_target(
+            field.get("target"),
+            f"{field_path}.target",
+            diagnostics,
+            node_by_id,
+            api_prompt,
+        )
+    return keys
+
+
+def _validate_surface_app_switch(
+    switch: Any,
+    path: str,
+    diagnostics: list[str],
+    node_by_id: dict[str, dict[str, Any]],
+    api_prompt: dict[str, Any] | None,
+    input_keys: set[str],
+) -> None:
+    if not isinstance(switch, dict):
+        diagnostics.append(f"{path} must be a JSON object")
+        return
+    _validate_non_empty_text(switch.get("key"), f"{path}.key", diagnostics)
+    _validate_non_empty_text(switch.get("label"), f"{path}.label", diagnostics)
+    if "visible" in switch and not isinstance(switch["visible"], bool):
+        diagnostics.append(f"{path}.visible must be a boolean")
+    _validate_surface_app_target(
+        switch.get("target"),
+        f"{path}.target",
+        diagnostics,
+        node_by_id,
+        api_prompt,
+    )
+    default = switch.get("default")
+    if default is not None and (isinstance(default, bool) or not isinstance(default, int)):
+        diagnostics.append(f"{path}.default must be an integer")
+    options = switch.get("options")
+    if not isinstance(options, list):
+        diagnostics.append(f"{path}.options must be a list")
+        return
+    for option_index, option in enumerate(options):
+        option_path = f"{path}.options[{option_index}]"
+        if not isinstance(option, dict):
+            diagnostics.append(f"{option_path} must be a JSON object")
+            continue
+        if isinstance(option.get("value"), bool) or not isinstance(option.get("value"), int):
+            diagnostics.append(f"{option_path}.value must be an integer")
+        _validate_non_empty_text(option.get("label"), f"{option_path}.label", diagnostics)
+        _validate_non_empty_text(option.get("input"), f"{option_path}.input", diagnostics)
+        if (
+            isinstance(option.get("input"), str)
+            and option["input"].strip()
+            and input_keys
+            and option["input"] not in input_keys
+        ):
+            diagnostics.append(f"{option_path}.input must match a setupSurface.app.inputs key")
+        if "visible" in option and not isinstance(option["visible"], bool):
+            diagnostics.append(f"{option_path}.visible must be a boolean")
+
+
+def _validate_surface_app_target(
+    target: Any,
+    path: str,
+    diagnostics: list[str],
+    node_by_id: dict[str, dict[str, Any]],
+    api_prompt: dict[str, Any] | None,
+) -> None:
+    if not isinstance(target, dict):
+        diagnostics.append(f"{path} must be a JSON object")
+        return
+    _validate_non_empty_text(target.get("node"), f"{path}.node", diagnostics)
+    _validate_non_empty_text(target.get("input"), f"{path}.input", diagnostics)
+    node_id = target.get("node")
+    input_name = target.get("input")
+    if not isinstance(node_id, str) or not node_id.strip():
+        return
+    if not isinstance(input_name, str) or not input_name.strip():
+        return
+    node = node_by_id.get(node_id)
+    if node is None:
+        diagnostics.append(f"{path}.node not found in visualGraph")
+        return
+    if not _visual_node_has_input(node, input_name):
+        diagnostics.append(f"{path}.input not found in visualGraph node")
+    if api_prompt is None:
+        return
+    api_node = api_prompt.get(node_id)
+    if not isinstance(api_node, dict):
+        diagnostics.append(f"{path}.node not found in apiPrompt")
+        return
+    api_inputs = api_node.get("inputs")
+    if not isinstance(api_inputs, dict) or input_name not in api_inputs:
+        diagnostics.append(f"{path}.input not found in apiPrompt")
+
+
+def _validate_non_empty_text(value: Any, path: str, diagnostics: list[str]) -> None:
+    if not isinstance(value, str) or not value.strip():
+        diagnostics.append(f"{path} must be non-empty text")
+
+
+def _visual_node_index(visual_graph: Any) -> dict[str, dict[str, Any]]:
+    nodes = visual_graph.get("nodes") if isinstance(visual_graph, dict) else None
+    if not isinstance(nodes, list):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        node_id = node.get("id")
+        if node_id is not None:
+            out[str(node_id)] = node
+    return out
+
+
+def _visual_node_has_input(node: dict[str, Any], input_name: str) -> bool:
+    inputs = node.get("inputs")
+    if isinstance(inputs, list) and any(
+        isinstance(port, dict) and str(port.get("name", "")) == input_name
+        for port in inputs
+    ):
+        return True
+    class_type = node.get("type")
+    widget_names = WIDGET_ONLY_INPUTS_BY_CLASS.get(str(class_type), ())
+    return input_name in widget_names
+
+
+def _uses_group_authored_surface(
+    input_contract: dict[str, Any],
+    output_contract: dict[str, Any],
+) -> bool:
+    inputs = input_contract.get("inputs")
+    outputs = output_contract.get("outputs")
+    return inputs == [] and outputs == []
+
+
+def _nodes_in_named_groups(visual_graph: dict[str, Any], group_title: str) -> list[dict[str, Any]]:
+    groups = _nodes_in_group_sections(visual_graph, group_title)
+    return [
+        {"group": group_title, "nodes": [_surface_node_summary(node) for node in group_nodes]}
+        for group_nodes in groups
+        if group_nodes
+    ]
+
+
+def _nodes_in_group(visual_graph: dict[str, Any], group_title: str) -> list[dict[str, Any]]:
+    groups = _nodes_in_group_sections(visual_graph, group_title)
+    return [node for group_nodes in groups for node in group_nodes]
+
+
+def _nodes_in_group_sections(
+    visual_graph: dict[str, Any],
+    group_title: str,
+) -> list[list[dict[str, Any]]]:
+    groups = visual_graph.get("groups")
+    nodes = visual_graph.get("nodes")
+    if not isinstance(groups, list) or not isinstance(nodes, list):
+        return []
+
+    node_rects = [
+        (node, _rect_from_node(node))
+        for node in nodes
+        if isinstance(node, dict)
+    ]
+    out: list[list[dict[str, Any]]] = []
+    for group in groups:
+        if not isinstance(group, dict) or group.get("title") != group_title:
+            continue
+        group_rect = _rect_from_group(group)
+        group_nodes = [
+            node
+            for node, node_rect in node_rects
+            if _rects_overlap(group_rect, node_rect)
+        ]
+        if group_nodes:
+            out.append(sorted(group_nodes, key=lambda node: (_rect_from_node(node)["y"], _rect_from_node(node)["x"])))
+    return out
+
+
+def _validate_setup_surface_geometry(visual_graph: dict[str, Any]) -> list[str]:
+    diagnostics: list[str] = []
+    groups = visual_graph.get("groups")
+    if isinstance(groups, list):
+        for group_index, group in enumerate(groups):
+            if not isinstance(group, dict) or group.get("title") not in {"Koolook Input", "Koolook Output"}:
+                continue
+            bounding = group.get("bounding")
+            pos = group.get("pos")
+            size = group.get("size")
+            if bounding is not None:
+                if (
+                    not isinstance(bounding, list)
+                    or len(bounding) < 4
+                    or not all(_is_number(value) for value in bounding[:4])
+                ):
+                    diagnostics.append(
+                        f"visualGraph.groups[{group_index}].bounding must contain numeric "
+                        "x, y, width, height"
+                    )
+                continue
+            if pos is not None or size is not None:
+                if (
+                    not isinstance(pos, list)
+                    or len(pos) < 2
+                    or not all(_is_number(value) for value in pos[:2])
+                    or not isinstance(size, list)
+                    or len(size) < 2
+                    or not all(_is_number(value) for value in size[:2])
+                ):
+                    diagnostics.append(
+                        f"visualGraph.groups[{group_index}].pos/size must contain numeric "
+                        "x, y, width, height"
+                    )
+                continue
+            diagnostics.append(
+                f"visualGraph.groups[{group_index}] must define bounding or pos/size "
+                "for setup surface inference"
+            )
+    nodes = visual_graph.get("nodes")
+    if isinstance(nodes, list):
+        for node_index, node in enumerate(nodes):
+            if not isinstance(node, dict):
+                continue
+            pos = node.get("pos")
+            if pos is not None and (
+                not isinstance(pos, list)
+                or len(pos) < 2
+                or not all(_is_number(value) for value in pos[:2])
+            ):
+                diagnostics.append(
+                    f"visualGraph.nodes[{node_index}].pos must contain numeric x and y "
+                    "for setup surface inference"
+                )
+            size = node.get("size")
+            if size is not None and (
+                not isinstance(size, list)
+                or len(size) < 2
+                or not all(_is_number(value) for value in size[:2])
+            ):
+                diagnostics.append(
+                    f"visualGraph.nodes[{node_index}].size must contain numeric width and height "
+                    "for setup surface inference"
+                )
+    return diagnostics
+
+
+def _surface_node_summary(node: dict[str, Any]) -> dict[str, str]:
+    node_type = node.get("type")
+    node_title = node.get("title")
+    return {
+        "id": str(node.get("id")),
+        "type": node_type if isinstance(node_type, str) else "",
+        "title": node_title if isinstance(node_title, str) and node_title else (
+            node_type if isinstance(node_type, str) else str(node.get("id"))
+        ),
+    }
+
+
+def _rect_from_group(group: dict[str, Any]) -> dict[str, float] | None:
+    bounding = group.get("bounding")
+    if isinstance(bounding, list) and len(bounding) >= 4:
+        return {
+            "x": _number_or_default(bounding[0], 0),
+            "y": _number_or_default(bounding[1], 0),
+            "w": _number_or_default(bounding[2], 0),
+            "h": _number_or_default(bounding[3], 0),
+        }
+    pos = group.get("pos")
+    size = group.get("size")
+    if isinstance(pos, list) and isinstance(size, list) and len(pos) >= 2 and len(size) >= 2:
+        return {
+            "x": _number_or_default(pos[0], 0),
+            "y": _number_or_default(pos[1], 0),
+            "w": _number_or_default(size[0], 0),
+            "h": _number_or_default(size[1], 0),
+        }
+    return None
+
+
+def _rect_from_node(node: dict[str, Any]) -> dict[str, float] | None:
+    pos = node.get("pos")
+    if not isinstance(pos, list) or len(pos) < 2:
+        return None
+    size = node.get("size")
+    if not isinstance(size, list) or len(size) < 2:
+        size = [200, 100]
+    return {
+        "x": _number_or_default(pos[0], 0),
+        "y": _number_or_default(pos[1], 0),
+        "w": _number_or_default(size[0], 200),
+        "h": _number_or_default(size[1], 100),
+    }
+
+
+def _rects_overlap(a: dict[str, float] | None, b: dict[str, float] | None) -> bool:
+    if not a or not b or a["w"] <= 0 or a["h"] <= 0 or b["w"] <= 0 or b["h"] <= 0:
+        return False
+    return (
+        a["x"] < b["x"] + b["w"]
+        and a["x"] + a["w"] > b["x"]
+        and a["y"] < b["y"] + b["h"]
+        and a["y"] + a["h"] > b["y"]
+    )
+
+
+def _number_or_default(value: Any, default: float) -> float:
+    return value if isinstance(value, int | float) else default
+
+
+def _is_number(value: Any) -> bool:
+    return not isinstance(value, bool) and isinstance(value, int | float) and math.isfinite(value)
+
+
+def _convert_visual_graph_to_api_prompt(visual_graph: dict[str, Any]) -> ApiPromptConversionResult:
+    nodes = visual_graph.get("nodes")
+    if not isinstance(nodes, list):
+        return ApiPromptConversionResult(None, ["visualGraph.nodes must be a list"])
+    links = _visual_link_index(visual_graph.get("links"))
+    if links.diagnostics:
+        return ApiPromptConversionResult(None, links.diagnostics)
+
+    node_indexes_by_id: dict[str, int] = {}
+    node_ids = set[str]()
+    for node_index, node in enumerate(nodes):
+        if not isinstance(node, dict):
+            return ApiPromptConversionResult(None, [f"visualGraph.nodes[{node_index}] must be an object"])
+        node_id = node.get("id")
+        class_type = node.get("type")
+        if node_id is None or not isinstance(class_type, str) or not class_type.strip():
+            return ApiPromptConversionResult(
+                None,
+                [f"visualGraph.nodes[{node_index}].type must be non-empty text"],
+            )
+        node_id_key = str(node_id)
+        previous_node_index = node_indexes_by_id.get(node_id_key)
+        if previous_node_index is not None:
+            return ApiPromptConversionResult(
+                None,
+                [
+                    f"visualGraph.nodes[{node_index}].id duplicates "
+                    f"visualGraph.nodes[{previous_node_index}].id"
+                ],
+            )
+        node_indexes_by_id[node_id_key] = node_index
+        node_ids.add(node_id_key)
+
+    node_by_id = {str(node["id"]): node for node in nodes}
+    subgraphs_by_id = _subgraph_definitions_by_id(visual_graph)
+    api_prompt: dict[str, Any] = {}
+    subgraph_output_refs: dict[str, dict[int, Any]] = {}
+    skipped_node_ids: set[str] = set()
+    expanded_node_ids: set[str] = set()
+    diagnostics: list[str] = []
+
+    def resolve_outer_link(link_id: Any, seen: set[str] | None = None) -> Any:
+        link_id_key = str(link_id)
+        seen = set() if seen is None else seen
+        if link_id_key in seen:
+            diagnostics.append(f"visualGraph.links[{link_id_key}] has a reroute cycle")
+            return None
+        seen.add(link_id_key)
+        link = links.links.get(link_id_key)
+        if link is None:
+            diagnostics.append(f"visualGraph.links[{link_id_key}] is missing")
+            return None
+        origin_id = str(link["origin_id"])
+        if _is_module_sentinel_id(link["origin_id"]):
+            diagnostics.append(f"visualGraph.links[{link_id_key}] uses unsupported module graph sentinel node")
+            return None
+        if not _is_non_negative_int(link["origin_slot"]):
+            diagnostics.append(
+                f"visualGraph.links[{link_id_key}].origin_slot must be a non-negative integer"
+            )
+            return None
+        origin_slot = int(link["origin_slot"])
+        origin_node = node_by_id.get(origin_id)
+        if origin_node is None:
+            diagnostics.append(f"visualGraph.links[{link_id_key}].origin_id not found in visualGraph")
+            return None
+        if origin_node.get("type") == "Reroute":
+            reroute_input = _first_linked_input(origin_node)
+            if reroute_input is None:
+                diagnostics.append(f"visualGraph.nodes[{node_indexes_by_id[origin_id]}] Reroute is unconnected")
+                return None
+            return resolve_outer_link(reroute_input, seen)
+        if origin_id in subgraph_output_refs:
+            ref = subgraph_output_refs[origin_id].get(origin_slot)
+            if ref is None:
+                diagnostics.append(
+                    f"visualGraph.links[{link_id_key}] references missing subgraph output {origin_slot}"
+                )
+            return ref
+        if origin_id in skipped_node_ids or origin_id in expanded_node_ids:
+            diagnostics.append(
+                f"visualGraph.links[{link_id_key}] references non-executable node {origin_id}"
+            )
+            return None
+        return [origin_id, origin_slot]
+
+    def add_node_api(
+        *,
+        node: dict[str, Any],
+        node_index: int,
+        node_id_key: str,
+        class_type: str,
+        link_resolver,
+    ) -> None:
+        node_inputs = node.get("inputs")
+        if node_inputs is None:
+            node_inputs = []
+        elif not isinstance(node_inputs, list):
+            diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must be a list when present")
+            return
+
+        raw_widget_values = node.get("widgets_values")
+        widget_values_by_name = raw_widget_values if isinstance(raw_widget_values, dict) else {}
+        widget_values = raw_widget_values if isinstance(raw_widget_values, list) else []
+        if not widget_values and not widget_values_by_name:
+            widget_values = _proxy_widget_values_from_subgraph(visual_graph, node)
+        widget_index = 0
+        api_inputs: dict[str, Any] = {}
+        for input_index, input_port in enumerate(node_inputs):
+            if not isinstance(input_port, dict):
+                diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must contain objects")
+                return
+            name = input_port.get("name")
+            if not isinstance(name, str) or not name.strip():
+                if class_type != "Reroute" or not isinstance(name, str):
+                    diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must have named ports")
+                    return
+            link_id = input_port.get("link")
+            if link_id is not None:
+                link = links.links.get(str(link_id))
+                if link is not None and link["target_id"] is not None and str(link["target_id"]) != node_id_key:
+                    diagnostics.append(
+                        f"visualGraph.links[{link_id}].target does not match "
+                        f"visualGraph.nodes[{node_index}].inputs[{input_index}]"
+                    )
+                    return
+                if (
+                    link is not None
+                    and link["target_slot"] is not None
+                    and (
+                        not _is_non_negative_int(link["target_slot"])
+                        or int(link["target_slot"]) != input_index
+                    )
+                ):
+                    diagnostics.append(
+                        f"visualGraph.links[{link_id}].target does not match "
+                        f"visualGraph.nodes[{node_index}].inputs[{input_index}]"
+                    )
+                    return
+                resolved = link_resolver(link_id)
+                if resolved is None:
+                    return
+                api_inputs[name] = resolved
+                continue
+            widget = input_port.get("widget")
+            if isinstance(widget, dict):
+                if name in widget_values_by_name:
+                    api_inputs[name] = widget_values_by_name[name]
+                    continue
+                if widget_index >= len(widget_values):
+                    diagnostics.append(
+                        f"visualGraph.nodes[{node_index}].widgets_values is missing a value "
+                        f"for input {name}"
+                    )
+                    return
+                api_inputs[name] = widget_values[widget_index]
+                widget_index += 1
+
+        if not node_inputs:
+            widget_only_diagnostics = _apply_widget_only_inputs(
+                class_type,
+                widget_values,
+                api_inputs,
+                node_index,
+            )
+            diagnostics.extend(widget_only_diagnostics)
+            if widget_only_diagnostics:
+                return
+        api_prompt[node_id_key] = {"class_type": class_type, "inputs": api_inputs}
+
+    def expand_subgraph_node(node: dict[str, Any], node_index: int) -> None:
+        node_id_key = str(node["id"])
+        subgraph = subgraphs_by_id.get(str(node["type"]))
+        if subgraph is None:
+            return
+        subgraph_links = _visual_link_index(subgraph.get("links"))
+        if subgraph_links.diagnostics:
+            diagnostics.extend(subgraph_links.diagnostics)
+            return
+        subgraph_nodes = subgraph.get("nodes")
+        if not isinstance(subgraph_nodes, list):
+            diagnostics.append(f"visualGraph.definitions.subgraphs[{node['type']}].nodes must be a list")
+            return
+        subgraph_inputs = subgraph.get("inputs")
+        if not isinstance(subgraph_inputs, list):
+            subgraph_inputs = []
+        subgraph_nodes_by_id = {
+            str(subgraph_node.get("id")): subgraph_node
+            for subgraph_node in subgraph_nodes
+            if isinstance(subgraph_node, dict) and subgraph_node.get("id") is not None
+        }
+        wrapper_inputs = _api_inputs_for_wrapper_node(
+            visual_graph,
+            node,
+            node_index,
+            links,
+            resolve_outer_link,
+            diagnostics,
+        )
+        skipped_internal_ids: set[str] = set()
+        for internal_node in subgraph_nodes:
+            if not isinstance(internal_node, dict):
+                continue
+            internal_id = str(internal_node.get("id"))
+            if _should_omit_api_node(internal_node):
+                skipped_internal_ids.add(internal_id)
+
+        def resolve_subgraph_link(link_id: Any, seen: set[str] | None = None) -> Any:
+            link_id_key = str(link_id)
+            seen = set() if seen is None else seen
+            if link_id_key in seen:
+                diagnostics.append(f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}] has a reroute cycle")
+                return None
+            seen.add(link_id_key)
+            link = subgraph_links.links.get(link_id_key)
+            if link is None:
+                diagnostics.append(f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}] is missing")
+                return None
+            origin_id = link["origin_id"]
+            if not _is_non_negative_int(link["origin_slot"]):
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}].origin_slot "
+                    "must be a non-negative integer"
+                )
+                return None
+            origin_slot = int(link["origin_slot"])
+            if _is_module_sentinel_id(origin_id):
+                if int(origin_id) != -10:
+                    diagnostics.append(
+                        f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}] "
+                        "uses unsupported module graph sentinel node"
+                    )
+                    return None
+                if origin_slot >= len(subgraph_inputs):
+                    diagnostics.append(
+                        f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}] "
+                        "references missing subgraph input"
+                    )
+                    return None
+                input_name = subgraph_inputs[origin_slot].get("name")
+                if not isinstance(input_name, str) or input_name not in wrapper_inputs:
+                    return None
+                return wrapper_inputs[input_name]
+            origin_id_key = str(origin_id)
+            origin_node = subgraph_nodes_by_id.get(origin_id_key)
+            if origin_node is None:
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}].origin_id not found"
+                )
+                return None
+            if origin_node.get("type") == "Reroute":
+                reroute_input = _first_linked_input(origin_node)
+                if reroute_input is None:
+                    diagnostics.append(
+                        f"visualGraph.definitions.subgraphs[{node['type']}].nodes[{origin_id_key}] Reroute is unconnected"
+                    )
+                    return None
+                return resolve_subgraph_link(reroute_input, seen)
+            if origin_id_key in skipped_internal_ids:
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].links[{link_id_key}] "
+                    f"references non-executable node {origin_id_key}"
+                )
+                return None
+            return [f"{node_id_key}:{origin_id_key}", origin_slot]
+
+        for internal_index, internal_node in enumerate(subgraph_nodes):
+            if not isinstance(internal_node, dict):
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].nodes[{internal_index}] must be an object"
+                )
+                return
+            internal_class_type = internal_node.get("type")
+            internal_id = internal_node.get("id")
+            if internal_id is None or not isinstance(internal_class_type, str) or not internal_class_type.strip():
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].nodes[{internal_index}].type "
+                    "must be non-empty text"
+                )
+                return
+            if str(internal_class_type) in subgraphs_by_id:
+                diagnostics.append(
+                    f"visualGraph.definitions.subgraphs[{node['type']}].nodes[{internal_index}] "
+                    "nested subgraphs are not supported"
+                )
+                return
+            if str(internal_id) in skipped_internal_ids:
+                continue
+            add_node_api(
+                node=internal_node,
+                node_index=node_index,
+                node_id_key=f"{node_id_key}:{internal_id}",
+                class_type=internal_class_type,
+                link_resolver=resolve_subgraph_link,
+            )
+            if diagnostics:
+                return
+
+        output_refs: dict[int, Any] = {}
+        for link_id, link in subgraph_links.links.items():
+            if not _is_module_sentinel_id(link["target_id"]) or int(link["target_id"]) != -20:
+                continue
+            target_slot = link.get("target_slot")
+            if not _is_non_negative_int(target_slot):
+                continue
+            ref = resolve_subgraph_link(link_id)
+            if ref is not None:
+                output_refs[int(target_slot)] = ref
+        subgraph_output_refs[node_id_key] = output_refs
+        expanded_node_ids.add(node_id_key)
+
+    for node_index, node in enumerate(nodes):
+        node_id_key = str(node["id"])
+        class_type = node["type"]
+        if _should_omit_api_node(node):
+            skipped_node_ids.add(node_id_key)
+            continue
+        if class_type == "Reroute":
+            skipped_node_ids.add(node_id_key)
+            continue
+        if class_type in subgraphs_by_id:
+            expand_subgraph_node(node, node_index)
+            if diagnostics:
+                return ApiPromptConversionResult(None, diagnostics)
+            continue
+        add_node_api(
+            node=node,
+            node_index=node_index,
+            node_id_key=node_id_key,
+            class_type=class_type,
+            link_resolver=resolve_outer_link,
+        )
+        if diagnostics:
+            return ApiPromptConversionResult(None, diagnostics)
+
+    return ApiPromptConversionResult(api_prompt, diagnostics)
+
+
+def _api_inputs_for_wrapper_node(
+    visual_graph: dict[str, Any],
+    node: dict[str, Any],
+    node_index: int,
+    links: VisualLinkIndex,
+    link_resolver,
+    diagnostics: list[str],
+) -> dict[str, Any]:
+    node_inputs = node.get("inputs")
+    if node_inputs is None:
+        return {}
+    if not isinstance(node_inputs, list):
+        diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must be a list when present")
+        return {}
+    raw_widget_values = node.get("widgets_values")
+    widget_values_by_name = raw_widget_values if isinstance(raw_widget_values, dict) else {}
+    widget_values = raw_widget_values if isinstance(raw_widget_values, list) else []
+    widget_index = 0
+    values: dict[str, Any] = {}
+    for input_index, input_port in enumerate(node_inputs):
+        if not isinstance(input_port, dict):
+            diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must contain objects")
+            return values
+        name = input_port.get("name")
+        if not isinstance(name, str) or not name.strip():
+            diagnostics.append(f"visualGraph.nodes[{node_index}].inputs must have named ports")
+            return values
+        link_id = input_port.get("link")
+        if link_id is not None:
+            link = links.links.get(str(link_id))
+            if link is not None and link["target_id"] is not None and str(link["target_id"]) != str(node.get("id")):
+                diagnostics.append(
+                    f"visualGraph.links[{link_id}].target does not match "
+                    f"visualGraph.nodes[{node_index}].inputs[{input_index}]"
+                )
+                return values
+            resolved = link_resolver(link_id)
+            if resolved is not None:
+                values[name] = resolved
+            continue
+        widget = input_port.get("widget")
+        if not isinstance(widget, dict):
+            continue
+        if name in widget_values_by_name:
+            values[name] = widget_values_by_name[name]
+            continue
+        if widget_index < len(widget_values):
+            values[name] = widget_values[widget_index]
+        widget_index += 1
+    proxy_values = _proxy_widget_values_from_subgraph(visual_graph, node)
+    proxy_index = 0
+    for input_port in node_inputs:
+        if proxy_index >= len(proxy_values) or not isinstance(input_port, dict):
+            continue
+        name = input_port.get("name")
+        if isinstance(name, str) and name not in values and input_port.get("widget"):
+            values[name] = proxy_values[proxy_index]
+        if input_port.get("widget"):
+            proxy_index += 1
+    return values
+
+
+def _api_prompt_needs_visual_normalization(
+    api_prompt: dict[str, Any],
+    visual_graph: dict[str, Any],
+) -> bool:
+    subgraph_ids = set(_subgraph_definitions_by_id(visual_graph))
+    for node in api_prompt.values():
+        if not isinstance(node, dict):
+            continue
+        class_type = node.get("class_type")
+        if not isinstance(class_type, str):
+            continue
+        if class_type == "Reroute":
+            return True
+        if class_type in VISUAL_ONLY_API_NODE_TYPES:
+            return True
+        if class_type in SINK_ONLY_API_NODE_TYPES:
+            return True
+        if class_type in subgraph_ids:
+            return True
+    return False
+
+
+def _subgraph_definitions_by_id(visual_graph: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    definitions = visual_graph.get("definitions")
+    if not isinstance(definitions, dict):
+        return {}
+    subgraphs = definitions.get("subgraphs")
+    if not isinstance(subgraphs, list):
+        return {}
+    return {
+        str(subgraph.get("id")): subgraph
+        for subgraph in subgraphs
+        if isinstance(subgraph, dict) and subgraph.get("id") is not None
+    }
+
+
+def _should_omit_api_node(node: dict[str, Any]) -> bool:
+    class_type = str(node.get("type", ""))
+    if class_type in VISUAL_ONLY_API_NODE_TYPES:
+        return True
+    if class_type in SINK_ONLY_API_NODE_TYPES:
+        return not _node_has_linked_outputs(node)
+    return False
+
+
+def _node_has_linked_outputs(node: dict[str, Any]) -> bool:
+    outputs = node.get("outputs")
+    if not isinstance(outputs, list):
+        return False
+    for output in outputs:
+        if not isinstance(output, dict):
+            continue
+        links = output.get("links")
+        if isinstance(links, list) and links:
+            return True
+    return False
+
+
+def _first_linked_input(node: dict[str, Any]) -> Any | None:
+    node_inputs = node.get("inputs")
+    if not isinstance(node_inputs, list):
+        return None
+    for input_port in node_inputs:
+        if not isinstance(input_port, dict):
+            continue
+        link_id = input_port.get("link")
+        if link_id is not None:
+            return link_id
+    return None
+
+
+def _apply_widget_only_inputs(
+    class_type: str,
+    widget_values: list[Any],
+    api_inputs: dict[str, Any],
+    node_index: int,
+) -> list[str]:
+    if api_inputs:
+        return []
+    widget_names = WIDGET_ONLY_INPUTS_BY_CLASS.get(class_type)
+    if not widget_names:
+        return []
+    defaults = WIDGET_ONLY_INPUT_DEFAULTS.get(class_type, {})
+    diagnostics: list[str] = []
+    for index, name in enumerate(widget_names):
+        if index < len(widget_values):
+            value = widget_values[index]
+            if name == "no_subfolders" and not isinstance(value, bool):
+                value = defaults.get(name, False)
+            api_inputs[name] = value
+        elif name in defaults:
+            api_inputs[name] = defaults[name]
+        else:
+            diagnostics.append(
+                f"visualGraph.nodes[{node_index}].widgets_values is missing a value "
+                f"for widget-only input {name}"
+            )
+    return diagnostics
+
+
+def _proxy_widget_values_from_subgraph(
+    visual_graph: dict[str, Any],
+    node: dict[str, Any],
+) -> list[Any]:
+    properties = node.get("properties")
+    if not isinstance(properties, dict):
+        return []
+    proxy_widgets = properties.get("proxyWidgets")
+    if not isinstance(proxy_widgets, list):
+        return []
+    subgraph = _subgraph_definition(visual_graph, str(node.get("type", "")))
+    if subgraph is None:
+        return []
+    subgraph_nodes = subgraph.get("nodes")
+    if not isinstance(subgraph_nodes, list):
+        return []
+
+    nodes_by_id = {
+        str(subgraph_node.get("id")): subgraph_node
+        for subgraph_node in subgraph_nodes
+        if isinstance(subgraph_node, dict) and subgraph_node.get("id") is not None
+    }
+    values: list[Any] = []
+    for proxy_widget in proxy_widgets:
+        if not isinstance(proxy_widget, list) or len(proxy_widget) < 2:
+            continue
+        source_node = nodes_by_id.get(str(proxy_widget[0]))
+        widget_name = proxy_widget[1]
+        if not isinstance(source_node, dict) or not isinstance(widget_name, str):
+            continue
+        found, value = _node_widget_value(source_node, widget_name)
+        if found:
+            values.append(value)
+    return values
+
+
+def _subgraph_definition(
+    visual_graph: dict[str, Any],
+    subgraph_id: str,
+) -> dict[str, Any] | None:
+    definitions = visual_graph.get("definitions")
+    if not isinstance(definitions, dict):
+        return None
+    subgraphs = definitions.get("subgraphs")
+    if not isinstance(subgraphs, list):
+        return None
+    for subgraph in subgraphs:
+        if isinstance(subgraph, dict) and subgraph.get("id") == subgraph_id:
+            return subgraph
+    return None
+
+
+def _node_widget_value(
+    node: dict[str, Any],
+    widget_name: str,
+) -> tuple[bool, Any]:
+    inputs = node.get("inputs")
+    widget_values = node.get("widgets_values")
+    if not isinstance(inputs, list) or not isinstance(widget_values, list):
+        return False, None
+
+    widget_index = 0
+    for input_port in inputs:
+        if not isinstance(input_port, dict):
+            continue
+        widget = input_port.get("widget")
+        if not isinstance(widget, dict):
+            continue
+        if widget.get("name") == widget_name:
+            if widget_index >= len(widget_values):
+                return False, None
+            return True, widget_values[widget_index]
+        widget_index += 1
+    return False, None
+
+
+@dataclass(frozen=True)
+class VisualLinkIndex:
+    links: dict[str, dict[str, Any]]
+    diagnostics: list[str]
+
+
+def _visual_link_index(value: Any) -> VisualLinkIndex:
+    links: dict[str, dict[str, Any]] = {}
+    if not isinstance(value, list):
+        return VisualLinkIndex(links, [])
+    link_indexes_by_id: dict[str, int] = {}
+    for link_index, item in enumerate(value):
+        if isinstance(item, dict):
+            link_id = item.get("id")
+            origin_id = item.get("origin_id")
+            origin_slot = item.get("origin_slot")
+            target_id = item.get("target_id")
+            target_slot = item.get("target_slot")
+        elif isinstance(item, list) and len(item) >= 5:
+            link_id = item[0]
+            origin_id = item[1]
+            origin_slot = item[2]
+            target_id = item[3]
+            target_slot = item[4]
+        elif isinstance(item, list) and len(item) >= 3:
+            link_id = item[0]
+            origin_id = item[1]
+            origin_slot = item[2]
+            target_id = None
+            target_slot = None
+        else:
+            continue
+        if link_id is None or origin_id is None or origin_slot is None:
+            continue
+        link_id_key = str(link_id)
+        previous_link_index = link_indexes_by_id.get(link_id_key)
+        if previous_link_index is not None:
+            return VisualLinkIndex(
+                links,
+                [
+                    f"visualGraph.links[{link_index}].id duplicates "
+                    f"visualGraph.links[{previous_link_index}].id"
+                ],
+            )
+        link_indexes_by_id[link_id_key] = link_index
+        links[link_id_key] = {
+            "origin_id": origin_id,
+            "origin_slot": origin_slot,
+            "target_id": target_id,
+            "target_slot": target_slot,
+        }
+    return VisualLinkIndex(links, [])
+
+
+def _is_module_sentinel_id(value: Any) -> bool:
+    try:
+        return int(value) < 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _is_non_negative_int(value: Any) -> bool:
+    return isinstance(value, int) and value >= 0
+
+
+def _validate_contract_targets(
+    visual_graph: dict[str, Any],
+    input_contract: dict[str, Any],
+) -> list[str]:
+    diagnostics: list[str] = []
+    nodes = visual_graph.get("nodes") if isinstance(visual_graph, dict) else None
+    node_by_id: dict[str, dict[str, Any]] = {}
+    if isinstance(nodes, list):
+        for node in nodes:
+            if not isinstance(node, dict):
+                continue
+            node_id = node.get("id")
+            if node_id is not None:
+                node_by_id[str(node_id)] = node
+    inputs = input_contract.get("inputs") if isinstance(input_contract, dict) else None
+    if not isinstance(inputs, list):
+        return diagnostics
+    for index, item in enumerate(inputs):
+        if not isinstance(item, dict):
+            continue
+        target = item.get("target")
+        if not isinstance(target, dict):
+            continue
+        node_id = str(target.get("node", ""))
+        input_name = str(target.get("input", ""))
+        node = node_by_id.get(node_id)
+        if node is None:
+            diagnostics.append(
+                f"inputContract.inputs[{index}].target.node not found in visualGraph"
+            )
+            continue
+        node_inputs = node.get("inputs")
+        if not isinstance(node_inputs, list):
+            continue
+        if not any(
+            isinstance(port, dict) and str(port.get("name", "")) == input_name
+            for port in node_inputs
+        ):
+            diagnostics.append(
+                f"inputContract.inputs[{index}].target.input not found in visualGraph node"
+            )
+    return diagnostics
+
+
+def _validate_api_prompt_contract_targets(
+    api_prompt: dict[str, Any] | None,
+    input_contract: dict[str, Any],
+) -> list[str]:
+    diagnostics: list[str] = []
+    if api_prompt is None:
+        return diagnostics
+    inputs = input_contract.get("inputs") if isinstance(input_contract, dict) else None
+    if not isinstance(inputs, list):
+        return diagnostics
+    for index, item in enumerate(inputs):
+        if not isinstance(item, dict):
+            continue
+        target = item.get("target")
+        if not isinstance(target, dict):
+            continue
+        node_id = str(target.get("node", ""))
+        input_name = str(target.get("input", ""))
+        api_node = api_prompt.get(node_id)
+        if not isinstance(api_node, dict):
+            diagnostics.append(
+                f"inputContract.inputs[{index}].target.node not found in generated apiPrompt"
+            )
+            continue
+        api_inputs = api_node.get("inputs")
+        if not isinstance(api_inputs, dict) or input_name not in api_inputs:
+            diagnostics.append(
+                f"inputContract.inputs[{index}].target.input not found in generated apiPrompt"
+            )
+    return diagnostics
+
+
+def default_storage_path() -> Path:
+    try:
+        import folder_paths
+
+        user_dir = folder_paths.get_user_directory()
+        return Path(user_dir) / DEFAULT_SETUPS_SUBDIR / DEFAULT_SETUPS_FILENAME
+    except Exception:  # pragma: no cover - fallback for non-Comfy contexts
+        return Path.cwd() / "user" / "default" / DEFAULT_SETUPS_SUBDIR / DEFAULT_SETUPS_FILENAME
+
+
+def default_registry() -> PublishedSetupRegistry:
+    return PublishedSetupRegistry(
+        FileSetupStorage(default_storage_path(), fallback_path=SAMPLE_SETUPS_PATH)
+    )
+
+
+def _validate_scalar(
+    mapping: dict[str, Any],
+    key: str,
+    expected_type: type | tuple[type, ...],
+    diagnostics: list[str],
+) -> None:
+    if not isinstance(mapping.get(key), expected_type):
+        diagnostics.append(f"{key} has invalid type")
+
+
+def _validate_mapping(value: Any, path: str, diagnostics: list[str]) -> None:
+    if not isinstance(value, dict):
+        diagnostics.append(f"{path} must be a JSON object")
+
+
+def _validate_iso_timestamp(value: Any, diagnostics: list[str]) -> None:
+    if not isinstance(value, str):
+        diagnostics.append("updatedAt must be an ISO timestamp")
+        return
+    normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        datetime.fromisoformat(normalized)
+    except ValueError:
+        diagnostics.append("updatedAt must be an ISO timestamp")
+
+
+def _validate_metadata(value: Any, diagnostics: list[str]) -> None:
+    if not isinstance(value, dict):
+        diagnostics.append("metadata must be a JSON object")
+        return
+    if not isinstance(value.get("title"), str) or not value["title"].strip():
+        diagnostics.append("metadata.title must be non-empty text")
+    if "description" in value and not isinstance(value["description"], str):
+        diagnostics.append("metadata.description must be text")
+    if "category" in value and not isinstance(value["category"], str):
+        diagnostics.append("metadata.category must be text")
+    if "tags" in value and not _is_string_list(value["tags"]):
+        diagnostics.append("metadata.tags must be a list of text")
+    if "previewImage" in value and not isinstance(value["previewImage"], str):
+        diagnostics.append("metadata.previewImage must be text")
+
+
+def _validate_contract(value: Any, path: str, items_key: str, diagnostics: list[str]) -> None:
+    if not isinstance(value, dict):
+        diagnostics.append(f"{path} must be a JSON object")
+        return
+    items = value.get(items_key)
+    if not isinstance(items, list):
+        diagnostics.append(f"{path}.{items_key} must be a list")
+        return
+    for index, item in enumerate(items):
+        item_path = f"{path}.{items_key}[{index}]"
+        if not isinstance(item, dict):
+            diagnostics.append(f"{item_path} must be a JSON object")
+            continue
+        for key in ("key", "type"):
+            if not isinstance(item.get(key), str) or not item[key].strip():
+                diagnostics.append(f"{item_path}.{key} must be non-empty text")
+        if "label" in item and not isinstance(item["label"], str):
+            diagnostics.append(f"{item_path}.label must be text")
+        if "required" in item and not isinstance(item["required"], bool):
+            diagnostics.append(f"{item_path}.required must be true or false")
+        if path == "inputContract":
+            target = item.get("target")
+            if not isinstance(target, dict):
+                diagnostics.append(f"{item_path}.target must be a JSON object")
+            else:
+                for key in ("node", "input"):
+                    if not isinstance(target.get(key), str) or not target[key].strip():
+                        diagnostics.append(f"{item_path}.target.{key} must be non-empty text")
+
+
+def _validate_source(value: Any, diagnostics: list[str]) -> None:
+    if not isinstance(value, dict):
+        diagnostics.append("source must be a JSON object")
+        return
+    for key in ("kind", "path"):
+        if not isinstance(value.get(key), str) or not value[key].strip():
+            diagnostics.append(f"source.{key} must be non-empty text")
+
+
+def _validate_validation(value: Any, diagnostics: list[str]) -> None:
+    if not isinstance(value, dict):
+        diagnostics.append("validation must be a JSON object")
+        return
+    if value.get("status") not in VALIDATION_STATUSES:
+        diagnostics.append("validation.status must be valid, draft, or invalid")
+    if "diagnostics" in value and not _is_string_list(value["diagnostics"]):
+        diagnostics.append("validation.diagnostics must be a list of text")
+
+
+def _is_string_list(value: Any) -> bool:
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+def _catalog_summary(setup: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": setup["id"],
+        "version": setup["version"],
+        "updatedAt": setup["updatedAt"],
+        "metadata": setup["metadata"],
+        "validation": setup["validation"],
+        "inputSummary": [
+            {
+                "key": item["key"],
+                "label": item.get("label", item["key"]),
+                "type": item["type"],
+                "required": bool(item.get("required", False)),
+            }
+            for item in setup["inputContract"].get("inputs", [])
+        ],
+        "outputSummary": [
+            {
+                "key": item["key"],
+                "label": item.get("label", item["key"]),
+                "type": item["type"],
+            }
+            for item in setup["outputContract"].get("outputs", [])
+        ],
+    }

ComfyUI/custom_nodes/koolook/koolook_versioning.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ComfyUI-Koolook — shared version-token helpers.
+# Copyright (C) 2026 ComfyUI-Koolook contributors (kforgelabs).
+#
+# This file is part of ComfyUI-Koolook, licensed under GPL-3.0-or-later.
+# See the LICENSE file at the repo root for the full text.
+"""Single source of truth for Koolook's ``vNNN`` output-versioning convention.
+
+Both ``EasyAIPipeline`` and ``Easy_VideoCombine`` stamp a version token into
+their output paths/filenames. Centralising the rule here keeps the token
+identical across every node so a single "global version" source (a wired
+STRING from one interface node) propagates consistently.
+
+Two entry points:
+
+- :func:`normalize_version_token` — clean a wired/typed STRING into a safe
+  single filename component (or ``""``).
+- :func:`resolve_version_token` — apply the full precedence rule used by
+  nodes that also carry a legacy INT ``version`` widget.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+# Same frontend-quirk sentinels the node modules already defend against: an
+# untouched STRING widget can arrive at the backend as the literal string
+# "undefined" / "null" / "None" instead of "".
+_SENTINEL_STRINGS = ("undefined", "null", "none")
+
+# Typed into a version field to request filesystem auto-detection of the next
+# free version instead of a literal token. Nodes detect this and call
+# ``next_version_token`` with their own output directory + name.
+_AUTO_VERSION_TOKENS = ("auto", "next")
+
+
+def is_auto_version(value) -> bool:
+    """True when a version field requests auto-detection (``auto`` / ``next``)."""
+    return normalize_version_token(value).lower() in _AUTO_VERSION_TOKENS
+
+
+def normalize_version_token(value) -> str:
+    """Clean a wired/typed version string into a safe single token.
+
+    Returns ``""`` for empty / whitespace-only / sentinel input. Otherwise
+    the value is used **verbatim** — ``v001``, ``final``, ``take_3`` all pass
+    through unchanged — after defensive cleanup:
+
+    - control characters (newline/CR/tab) stripped (Text Multiline can leak a
+      stray paragraph break),
+    - surrounding whitespace and a matched pair of surrounding quotes removed
+      (Explorer "Copy as path" style pastes),
+    - frontend sentinels (``undefined``/``null``/``none``) collapsed to ``""``,
+    - path separators flattened to ``_`` — a version token is a single
+      filename component and must never introduce a subfolder.
+    """
+    if value is None:
+        return ""
+    s = str(value).replace("\r", "").replace("\n", "").replace("\t", "").strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
+        s = s[1:-1].strip()
+    if s.lower() in _SENTINEL_STRINGS:
+        return ""
+    # A version token names one path component, never a path of its own.
+    return s.replace("/", "_").replace("\\", "_")
+
+
+def resolve_version_token(version, disable_versioning: bool = False) -> str:
+    """Resolve the version token to stamp into a path/filename.
+
+    One field, whether typed into the widget or wired in as a STRING:
+
+    - ``disable_versioning`` true   -> ``""`` (the master off-switch).
+    - empty / sentinel              -> ``""``.
+    - a bare integer (``"2"``)      -> ``"v002"`` (back-compat with the old
+      INT widget, and a convenience when typing a number).
+    - anything else (``"v001"``,
+      ``"final"``, a wired token)   -> used **verbatim**.
+    """
+    if disable_versioning:
+        return ""
+    token = normalize_version_token(version)
+    if not token:
+        return ""
+    if token.isdigit():
+        return f"v{int(token):03d}"
+    return token
+
+
+def next_version_token(
+    directory,
+    name,
+    version_prefix: str = "v",
+    padding: int = 3,
+    start: int = 1,
+) -> str:
+    """Return the next free ``<prefix>NNN`` token for ``name`` in ``directory``.
+
+    Scans ``directory`` for entries (files *and* subfolders) of the form
+    ``<name>_<prefix><digits>`` -- e.g. ``bearMask_v002.png``,
+    ``bearMask_v002.0001.exr``, or a ``bearMask_v003/`` sequence folder -- and
+    returns the highest detected version plus one, zero-padded to ``padding``.
+
+    A missing or empty directory (or no matching entries) yields ``start``
+    (default ``v001``). Permission errors and other unexpected filesystem
+    failures surface to the caller so a broken output mount cannot silently
+    become ``v001``. Matching is on the **exact** base name, so a different
+    shot's versions never bump this one. An empty ``name`` matches bare
+    ``<prefix>NNN`` tokens. Whatever follows the digits (extension, frame
+    number, ``_suffix``) is ignored.
+    """
+    prefix = normalize_version_token(version_prefix) or "v"
+    try:
+        pad = max(1, int(padding))
+    except (TypeError, ValueError):
+        pad = 3
+    try:
+        start_int = int(start)
+    except (TypeError, ValueError):
+        start_int = 1
+
+    base = normalize_version_token(name)
+    lead = f"{re.escape(base)}_" if base else ""
+    pattern = re.compile(rf"^{lead}{re.escape(prefix)}(\d+)")
+
+    highest: int | None = None
+    try:
+        entries = os.listdir(directory) if directory else []
+    except FileNotFoundError:
+        entries = []
+    for entry in entries:
+        match = pattern.match(entry)
+        if match:
+            value = int(match.group(1))
+            highest = value if highest is None else max(highest, value)
+
+    nxt = start_int if highest is None else highest + 1
+    return f"{prefix}{nxt:0{pad}d}"

ComfyUI/custom_nodes/koolook/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "koolook"
+description = "This repository provides custom nodes for ComfyUI tailored for VFX and AI image/video generation workflows"
+version = "0.4.4"
+license = {file = "LICENSE"} 
+# classifiers = [
+#     # For OS-independent nodes (works on all operating systems)
+#     "Operating System :: OS Independent",
+#
+#     # OR for OS-specific nodes, specify the supported systems:
+#     "Operating System :: Microsoft :: Windows",  # Windows specific
+#     "Operating System :: POSIX :: Linux",  # Linux specific
+#     "Operating System :: MacOS",  # macOS specific
+#
+#     # GPU Accelerator support. Pick the ones that are supported by your extension.
+#     "Environment :: GPU :: NVIDIA CUDA",    # NVIDIA CUDA support
+#     "Environment :: GPU :: AMD ROCm",       # AMD ROCm support
+#     "Environment :: GPU :: Intel Arc",      # Intel Arc support
+#     "Environment :: NPU :: Huawei Ascend",  # Huawei Ascend support
+#     "Environment :: GPU :: Apple Metal",    # Apple Metal support
+# ]
+
+
+[project.urls]
+Repository = "https://github.com/malkuthro/ComfyUI-Koolook"
+#  Used by Comfy Registry https://registry.comfy.org
+Documentation = "https://www.kforgelabs.com/comfyui-projects/comfyui-koolook/"
+"Bug Tracker" = "https://github.com/malkuthro/ComfyUI-Koolook/issues"
+
+[tool.comfy]
+PublisherId = "kforgelabs"
+DisplayName = "ComfyUI-Koolook"
+Icon = ""
+includes = []
+# "requires-comfyui" = ">=1.0.0"  # ComfyUI version compatibility
+
+[tool.ruff]
+extend-exclude = [".venv", "forks", "upscaler_FIX", "nuke_CAM_exporter"]
+
+[tool.setuptools]
+py-modules = [
+    "k_ai_pipeline",
+    "k_easy_image_batch",
+    "k_easy_pattern",
+    "k_easy_resize",
+    "k_easy_track",
+    "k_easy_wan22_prompt",
+    "k_loop_status",
+    "k_video_combine",
+    "k_video_load",
+    "koolook_install_guard",
+    "koolook_routes",
+    "koolook_setups",
+    "koolook_versioning",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"k_easy_resize.py" = ["F841"]
+
+[tool.pytest.ini_options]
+# ``testpaths`` scopes discovery to ``tests/``. ``pythonpath`` makes the repo
+# root importable so tests can ``import koolook_routes`` without an editable
+# install. ``importmode=importlib`` avoids the legacy ``sys.path.prepend``
+# import dance so re-running individual files works cleanly.
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = ["--import-mode=importlib"]
+
+[project.optional-dependencies]
+# Test deps for ``pytest`` runs. CI mirrors this list directly because this
+# ComfyUI custom node is not installed as a package in the workflow.
+# Locally use ``.venv/bin/pip install -e '.[test]'`` from the repo root.
+# ``aiohttp`` is a runtime dep of ``koolook_routes`` and must be importable
+# even when only a pure helper is under test. The lower bound is pinned to
+# the CVE-2026-54273..54280 fix line (>=3.14.1) so the declared range can't
+# resolve a vulnerable aiohttp; the lock (constraints-test.txt) matches.
+test = ["pytest>=8", "aiohttp>=3.14.1", "pip-audit>=2.7", "Pillow>=10"]

ComfyUI/custom_nodes/koolook/scripts/bootstrap_test_env.ps1

@@ -0,0 +1,80 @@
+# Bootstrap a repo-local .venv with the LOCKED, AUDITED test dependency set.
+#
+#   * Reproducible -- installs against constraints-test.txt when present (a
+#     pinned resolve of `.[test]` + its full transitive closure). Pass
+#     -Relock (with -Force) to re-resolve and rewrite that lock; commit the
+#     diff as the dependency-change review surface.
+#   * Verified -- runs pip-audit after install; a known CVE fails the
+#     bootstrap (exit 1). Pass -NoAudit to skip (e.g. offline).
+#   * Idempotent -- no-op if .venv already exists. Pass -Force to recreate.
+#
+# Usage: scripts\bootstrap_test_env.ps1 [-Force] [-Relock] [-NoAudit]
+
+param(
+    [switch]$Force,
+    [switch]$Relock,
+    [switch]$NoAudit
+)
+$ErrorActionPreference = "Stop"
+
+$Constraints = "constraints-test.txt"
+
+if (Test-Path .venv) {
+    if (-not $Force) {
+        if ($Relock) {
+            Write-Host "-Relock requires -Force (the lock is rewritten from a fresh resolve); nothing was changed."
+        }
+        Write-Host ".venv already exists. Pass -Force to recreate."
+        exit 0
+    }
+    Write-Host "Removing existing .venv ..."
+    Remove-Item -Recurse -Force .venv
+}
+
+Write-Host "Creating .venv ..."
+python -m venv .venv
+
+Write-Host "Upgrading pip + setuptools ..."
+.\.venv\Scripts\python -m pip install --quiet --upgrade pip setuptools
+
+if ((Test-Path $Constraints) -and (-not $Relock)) {
+    Write-Host "Installing project + test extras (locked via $Constraints) ..."
+    .\.venv\Scripts\python -m pip install --quiet -e ".[test]" -c $Constraints
+} else {
+    Write-Host "Resolving + installing project + test extras ..."
+    .\.venv\Scripts\python -m pip install --quiet -e ".[test]"
+    Write-Host "Writing locked set to $Constraints ..."
+    @'
+# Locked test dependency set for ComfyUI-Koolook.
+#
+# Pinned resolve of the `[test]` extras in pyproject.toml plus their full
+# transitive closure. The bootstrap scripts install with `-c
+# constraints-test.txt`, so every fresh .venv is reproducible and
+# pip-audit-verifiable.
+#
+# DO NOT hand-edit the version pins. To change the set: edit the `[test]`
+# extras in pyproject.toml, then regenerate this file with
+#   bash scripts/bootstrap_test_env.sh --force --relock   (POSIX)
+#   scripts\bootstrap_test_env.ps1 -Force -Relock         (Windows)
+# and commit the diff -- that diff is the dependency-change review surface.
+#
+'@ | Out-File -Encoding ascii $Constraints
+    .\.venv\Scripts\python -m pip list --format=freeze --exclude pip --exclude setuptools --exclude wheel --exclude koolook | Out-File -Encoding ascii -Append $Constraints
+}
+
+if (-not $NoAudit) {
+    Write-Host "Auditing installed set (pip-audit) ..."
+    .\.venv\Scripts\pip-audit --skip-editable
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "BLOCKER: pip-audit did not pass -- a known vulnerability was found,"
+        Write-Host "or the audit could not complete. Review the output above."
+        Write-Host "To bootstrap anyway (e.g. offline), re-run with -NoAudit."
+        exit 1
+    }
+    Write-Host "pip-audit: no known vulnerabilities."
+}
+
+Write-Host ""
+Write-Host "Test env ready. Run tests with:"
+Write-Host "  .\.venv\Scripts\python -m pytest"

ComfyUI/custom_nodes/koolook/scripts/bootstrap_test_env.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Bootstrap a repo-local .venv with the LOCKED, AUDITED test dependency set.
+#
+#   * Reproducible -- installs against constraints-test.txt when present (a
+#     pinned resolve of `.[test]` + its full transitive closure). Pass
+#     --relock (with --force) to re-resolve and rewrite that lock; commit
+#     the diff as the dependency-change review surface.
+#   * Verified -- runs pip-audit after install; a known CVE fails the
+#     bootstrap (exit 1). Pass --no-audit to skip (e.g. offline).
+#   * Idempotent -- no-op if .venv already exists. Pass --force to recreate.
+#
+# Usage: bash scripts/bootstrap_test_env.sh [--force] [--relock] [--no-audit]
+
+set -euo pipefail
+
+FORCE=""
+RELOCK=""
+AUDIT="1"
+for arg in "$@"; do
+    case "$arg" in
+        --force)    FORCE="1" ;;
+        --relock)   RELOCK="1" ;;
+        --no-audit) AUDIT="" ;;
+        *) echo "Unknown argument: $arg" >&2
+           echo "Usage: bash scripts/bootstrap_test_env.sh [--force] [--relock] [--no-audit]" >&2
+           exit 2 ;;
+    esac
+done
+
+CONSTRAINTS="constraints-test.txt"
+
+PYTHON_BIN="${PYTHON:-}"
+if [ -z "$PYTHON_BIN" ]; then
+    if command -v python3 >/dev/null 2>&1; then
+        PYTHON_BIN="python3"
+    elif command -v python >/dev/null 2>&1; then
+        PYTHON_BIN="python"
+    else
+        echo "Could not find python3 or python on PATH." >&2
+        exit 1
+    fi
+fi
+
+if [ -d .venv ]; then
+    if [ -z "$FORCE" ]; then
+        if [ -n "$RELOCK" ]; then
+            echo "--relock requires --force (the lock is rewritten from a fresh resolve); nothing was changed." >&2
+        fi
+        echo ".venv already exists. Pass --force to recreate."
+        exit 0
+    fi
+    echo "Removing existing .venv ..."
+    rm -rf .venv
+fi
+
+echo "Creating .venv ..."
+"$PYTHON_BIN" -m venv .venv
+
+echo "Upgrading pip + setuptools ..."
+.venv/bin/python -m pip install --quiet --upgrade pip setuptools
+
+if [ -f "$CONSTRAINTS" ] && [ -z "$RELOCK" ]; then
+    echo "Installing project + test extras (locked via $CONSTRAINTS) ..."
+    .venv/bin/python -m pip install --quiet -e '.[test]' -c "$CONSTRAINTS"
+else
+    echo "Resolving + installing project + test extras ..."
+    .venv/bin/python -m pip install --quiet -e '.[test]'
+    echo "Writing locked set to $CONSTRAINTS ..."
+    cat > "$CONSTRAINTS" <<'EOF'
+# Locked test dependency set for ComfyUI-Koolook.
+#
+# Pinned resolve of the `[test]` extras in pyproject.toml plus their full
+# transitive closure. The bootstrap scripts install with `-c
+# constraints-test.txt`, so every fresh .venv is reproducible and
+# pip-audit-verifiable.
+#
+# DO NOT hand-edit the version pins. To change the set: edit the `[test]`
+# extras in pyproject.toml, then regenerate this file with
+#   bash scripts/bootstrap_test_env.sh --force --relock   (POSIX)
+#   scripts\bootstrap_test_env.ps1 -Force -Relock         (Windows)
+# and commit the diff -- that diff is the dependency-change review surface.
+#
+EOF
+    .venv/bin/python -m pip list --format=freeze --exclude pip --exclude setuptools --exclude wheel --exclude koolook >> "$CONSTRAINTS"
+fi
+
+if [ -n "$AUDIT" ]; then
+    echo "Auditing installed set (pip-audit) ..."
+    if .venv/bin/pip-audit --skip-editable; then
+        echo "pip-audit: no known vulnerabilities."
+    else
+        echo "" >&2
+        echo "BLOCKER: pip-audit did not pass -- a known vulnerability was found," >&2
+        echo "or the audit could not complete. Review the output above." >&2
+        echo "To bootstrap anyway (e.g. offline), re-run with --no-audit." >&2
+        exit 1
+    fi
+fi
+
+echo ""
+echo "Test env ready. Run tests with:"
+echo "  .venv/bin/python -m pytest"

ComfyUI/custom_nodes/koolook/scripts/loop_audio.config.json

@@ -0,0 +1,60 @@
+{
+  "_doc": "Settings consumed by scripts/loop_audio.py. Underscore-prefixed keys are ignored by the loader and may carry inline documentation (same convention as the LTXDirector relay_overrides widget). Schema definitions live in docs/reference/glossary.md > 'Loop config (per-module)'.",
+
+  "job_name": "audio-lipsync",
+  "_job_name": "Human-readable identifier for this iteration loop. Surfaces in chat reports and card titles.",
+
+  "module_path": "docs/automations/LTX-2.3/audio-lipsync",
+  "_module_path": "Module root, relative to the repo root. The runs/ subfolder under this path is where snapshot folders + log.md live.",
+
+  "comfyui_workflows_subpath": "user/default/workflows",
+  "_comfyui_workflows_subpath": "Path within the ComfyUI install where the maintainer's workflow JSONs live. The ComfyUI install root is derived from KOLOOK_COMFYUI_DEV_PATH (walk up two levels from custom_nodes/<koolook>). Override by setting KOLOOK_COMFYUI_WORKFLOWS_DIR in .env.",
+
+  "workflow_pattern": "LTX-23-audio_tests*.json",
+  "_workflow_pattern": "Glob picked from the workflows dir. Newest mtime wins. Should match the 'Setup name' the maintainer pins on the canvas.",
+
+  "skip_filename_substring": "loop",
+  "_skip_filename_substring": "Any JSON whose stem contains this substring (case-insensitive) is excluded — these are post-card outputs, never iteration inputs. Convention matches scripts/make_card.py.",
+
+  "tracked_multilines": {
+    "working_folder": [
+      "global [ path ] - working folder",
+      "working_folder",
+      "working folder"
+    ],
+    "name": [
+      "global [ base name ]",
+      "name"
+    ],
+    "relay_overrides": [
+      "relay_overrides"
+    ],
+    "overlay - info": [
+      "overlay - info"
+    ],
+    "overlay - feedback": [
+      "overlay - feedback"
+    ]
+  },
+  "_tracked_multilines": "Semantic capture keys mapped to prioritized lowercase title substrings. Matching is case-insensitive and treats underscores as spaces, so old titles and the v02 GLOBAL labels can coexist. For each key, earlier aliases win when multiple Text Multiline titles match.",
+
+  "tracked_setup_variables": {
+    "input_path_exr": [
+      "input path [ exr ]"
+    ],
+    "version": [
+      "global [ version ]",
+      "version [ global ]"
+    ],
+    "run_offset": [
+      "global [ run offset ]"
+    ]
+  },
+  "_tracked_setup_variables": "Additional setup-card variables captured into notes.md for audit. Aliases are exact normalized title matches. Reads source value nodes only (Text Multiline and Primitive*), not GetNode/SetNode relay plumbing. The BASE note is a checklist/reminder, not a value, so derived BASE facts are calculated by the script instead. GLOBAL [ run ] is calculated inside the workflow from version + run offset; the capture records the inputs instead of reimplementing that graph math.",
+
+  "fork_to_track": "forks/whatdreamscost_koolook/versions/v1_3_9",
+  "_fork_to_track": "Repo-relative path of the fork files this module iterates on. Recorded in patch_state.txt of each run snapshot + diffed for the 'fork dir status' line.",
+
+  "render_card": true,
+  "_render_card": "When true, loop_audio.py invokes scripts/make_card_audio.render_audio_card at end-of-snapshot, writing card.png into the new run-NNN_ folder and copying it to the external cards folder as <Output name>_runNNN_card.png. Set false to skip the PIL dependency."
+}

ComfyUI/custom_nodes/koolook/scripts/loop_audio.py

@@ -0,0 +1,1630 @@
+#!/usr/bin/env python3
+"""
+``loop-audio`` — record one iteration of the LTX 2.3 audio-lipsync loop.
+
+End-to-end automation for one render cycle: locate the workflow the
+maintainer just saved inside ComfyUI, snapshot the workflow JSON +
+relay-overrides + fork state + notes into a numbered ``runs/run-NNN_``
+folder under this module, render the audio-lipsync card alongside, and
+append a row to ``runs/log.md``. No manual steps.
+
+Settings — *which* module, *which* workflow filename to look for,
+*which* multiline titles to extract, *which* fork dir to pin — all live
+in :file:`loop_audio.config.json` next to this script. Edit the config,
+not the Python, when the convention shifts.
+
+USER-INITIATED ONLY. Same rule as ``dev-sync`` and ``dev-sync-audio``
+(see project ``CLAUDE.md``). Trigger phrase: ``loop-audio``.
+
+Discovery chain:
+
+  KOLOOK_COMFYUI_DEV_PATH ── walk up two levels ──► <ComfyUI>/
+      └── <comfyui_workflows_subpath from config> ── glob workflow_pattern ──►
+                  newest mtime (excluding skip_filename_substring) ──► workflow.json
+
+Snapshot folder layout (always created):
+
+  <module_path>/runs/run-NNN_<auto-label>/
+    ├── runNNN_workflow.json copy of the workflow at submission
+    ├── relay_overrides.txt  RELAY_OVERRIDES multiline body
+    ├── patch_state.txt      MAIN sha + last dev-sync-audio + fork-dir status
+    ├── metadata.json        structured run/setup/director/repo metadata
+    ├── notes.md             feedback + scores + mechanical interp
+    └── card.png             when render_card=true in config
+
+Plus one row appended to <module_path>/runs/log.md.
+
+Usage:
+
+  python scripts/loop_audio.py
+  python scripts/loop_audio.py --dry-run
+  python scripts/loop_audio.py --label <override>
+  python scripts/loop_audio.py --no-log
+  python scripts/loop_audio.py --no-card
+  python scripts/loop_audio.py --workflow <explicit-path>
+  python scripts/loop_audio.py --config <explicit-config-path>
+
+Exit codes:
+
+  0  snapshot landed (or would have, in --dry-run)
+  2  KOLOOK_COMFYUI_DEV_PATH unset / ComfyUI workflows dir missing / config missing
+  3  no workflow matching the configured pattern
+  4  config JSON malformed
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tomllib
+from datetime import date
+from pathlib import Path
+from typing import Any, Optional
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_CONFIG_PATH = Path(__file__).resolve().with_suffix(".config.json")
+
+
+# --------------------------------------------------------------------------
+# Config — read once into a small dataclass-ish dict. Underscore-prefixed
+# keys are ignored (same convention as the LTXDirector relay_overrides
+# widget — keeps inline documentation co-located with the values).
+# --------------------------------------------------------------------------
+
+
+REQUIRED_CONFIG_KEYS = (
+    "job_name",
+    "module_path",
+    "comfyui_workflows_subpath",
+    "workflow_pattern",
+    "skip_filename_substring",
+    "tracked_multilines",
+    "fork_to_track",
+    "render_card",
+)
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        print(
+            f"Config not found: {path}\n"
+            f"Each loop script defaults to <script>.config.json beside it; "
+            f"pass --config to point elsewhere.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as exc:
+        print(f"Malformed config {path}: {exc}", file=sys.stderr)
+        sys.exit(4)
+    if not isinstance(raw, dict):
+        print(f"Config root must be an object: {path}", file=sys.stderr)
+        sys.exit(4)
+    cfg = {k: v for k, v in raw.items() if not k.startswith("_")}
+    missing = [k for k in REQUIRED_CONFIG_KEYS if k not in cfg]
+    if missing:
+        print(
+            f"Config {path} is missing required keys: {missing}",
+            file=sys.stderr,
+        )
+        sys.exit(4)
+    return cfg
+
+
+# --------------------------------------------------------------------------
+# .env loader (minimal — same shape as scripts/sync_to_dev.py's helper).
+# --------------------------------------------------------------------------
+
+
+def load_dotenv(env_path: Path) -> None:
+    if not env_path.exists():
+        return
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def find_dotenv() -> Optional[Path]:
+    """Find .env starting at this worktree; fall back to the main repo
+    root via git's common-dir when running from a worktree. Mirrors
+    scripts/make_card.py so both scripts behave the same when invoked
+    from a fresh worktree where the maintainer hasn't copied the .env
+    over yet."""
+    direct = REPO_ROOT / ".env"
+    if direct.exists():
+        return direct
+    git_marker = REPO_ROOT / ".git"
+    if not git_marker.is_file():
+        return None
+    try:
+        content = git_marker.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not content.startswith("gitdir:"):
+        return None
+    gitdir = Path(content.split(":", 1)[1].strip())
+    if "worktrees" not in gitdir.parts:
+        return None
+    idx = gitdir.parts.index("worktrees")
+    main_repo_root = Path(*gitdir.parts[:idx]).parent
+    candidate = main_repo_root / ".env"
+    return candidate if candidate.exists() else None
+
+
+# --------------------------------------------------------------------------
+# Workflow discovery — turn config + env into a concrete JSON path.
+# --------------------------------------------------------------------------
+
+
+def resolve_workflows_dir(cfg: dict[str, Any]) -> Path:
+    """``KOLOOK_COMFYUI_WORKFLOWS_DIR`` wins when set (lets the maintainer
+    point the loop at any workflow library). Otherwise derive
+    ``<ComfyUI>/<comfyui_workflows_subpath from config>`` from
+    ``KOLOOK_COMFYUI_DEV_PATH`` by walking up two levels from the
+    ``custom_nodes/<koolook>`` leaf."""
+    override = os.environ.get("KOLOOK_COMFYUI_WORKFLOWS_DIR")
+    if override:
+        p = Path(override).expanduser()
+        if not p.is_dir():
+            print(
+                f"KOLOOK_COMFYUI_WORKFLOWS_DIR points at a non-dir: {p}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        return p
+
+    dev = os.environ.get("KOLOOK_COMFYUI_DEV_PATH")
+    if not dev:
+        print(
+            "Neither KOLOOK_COMFYUI_WORKFLOWS_DIR nor "
+            "KOLOOK_COMFYUI_DEV_PATH is set in .env. Set one (see .env.example).",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    leaf = Path(dev).expanduser()
+    workflows = leaf.parent.parent / cfg["comfyui_workflows_subpath"]
+    if not workflows.is_dir():
+        print(
+            f"Workflows dir not found: {workflows}\n"
+            f"(derived from KOLOOK_COMFYUI_DEV_PATH={dev} + "
+            f"config.comfyui_workflows_subpath={cfg['comfyui_workflows_subpath']})",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    return workflows
+
+
+def find_workflow(workflows_dir: Path, cfg: dict[str, Any]) -> Path:
+    skip = cfg["skip_filename_substring"].lower()
+    candidates = [
+        p for p in workflows_dir.glob(cfg["workflow_pattern"])
+        if skip not in p.stem.lower()
+    ]
+    if not candidates:
+        print(
+            f"No workflow JSON matching {cfg['workflow_pattern']!r} in "
+            f"{workflows_dir}",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+    return max(candidates, key=lambda p: p.stat().st_mtime)
+
+
+# --------------------------------------------------------------------------
+# Workflow content extraction.
+# --------------------------------------------------------------------------
+
+
+DIRECTOR_TYPE = "LTXDirector__koolook"
+LEGACY_DIRECTOR_TYPES = ("LTXDirector__koolook_v1_3_2",)
+UPSTREAM_DIRECTOR_TYPE = "LTXDirector"
+DIRECTOR_TYPES = (DIRECTOR_TYPE, *LEGACY_DIRECTOR_TYPES, UPSTREAM_DIRECTOR_TYPE)
+KOOLOOK_UPSTREAM_PIN = (
+    REPO_ROOT
+    / "forks"
+    / "whatdreamscost_koolook"
+    / "versions"
+    / "v1_3_9"
+    / "UPSTREAM_PIN.yaml"
+)
+
+# Koolook Director widget order — verified empirically against saved
+# workflow JSON. The Comfy frontend serialises widgets in their original
+# (upstream) order even after the Koolook fork reordered them in the
+# schema; the only new widget — `relay_overrides` — is appended at the
+# end. So the saved widgets_values matches the legacy LTXDirector order
+# plus one extra slot.
+#
+# MIRROR: this dict is also documented in
+# docs/automations/LTX-2.3/audio-lipsync/reading-graph.schema.yaml under
+# `source_families.director_node.widget_order` (and indirectly under
+# `state_dict.director_derived`). Update both when this dict changes,
+# or the YAML drifts silently.
+DIRECTOR_WIDX = {
+    "global_prompt":    0,
+    "duration_frames":  1,
+    "duration_seconds": 2,
+    "timeline_data":    3,
+    "local_prompts":    4,
+    "segment_lengths":  5,
+    "epsilon":          6,
+    "guide_strength":   7,
+    "use_custom_audio": 8,
+    "frame_rate":       9,
+    "display_mode":     10,
+    "custom_width":     11,
+    "custom_height":    12,
+    "resize_method":    13,
+    "divisible_by":     14,
+    "img_compression":  15,
+    "relay_overrides":  16,
+}
+
+
+def _normalize_title(s: str) -> str:
+    return " ".join(s.replace("_", " ").lower().split())
+
+
+def _normalize_capture_key(s: str) -> str:
+    return s.strip().lower()
+
+
+def _normalize_alias_map(
+    tracked_titles: list[str] | dict[str, Any],
+) -> dict[str, list[str]]:
+    if isinstance(tracked_titles, dict):
+        out: dict[str, list[str]] = {}
+        for key, aliases in tracked_titles.items():
+            if isinstance(aliases, str):
+                alias_list = [aliases]
+            else:
+                alias_list = list(aliases or [])
+            out[_normalize_capture_key(str(key))] = [
+                _normalize_title(str(alias))
+                for alias in alias_list
+                if str(alias).strip()
+            ]
+        return out
+    return {
+        _normalize_capture_key(str(needle)): [_normalize_title(str(needle))]
+        for needle in tracked_titles
+    }
+
+
+def normalize_tracked_multilines(
+    tracked_titles: list[str] | dict[str, Any],
+) -> dict[str, list[str]]:
+    """Return semantic capture keys mapped to title aliases.
+
+    Older configs used a flat list where key == title substring. Newer
+    configs use {"semantic_key": ["preferred title", "fallback title"]}.
+    """
+    return _normalize_alias_map(tracked_titles)
+
+
+def extract_multilines(
+    nodes: list[dict], tracked_titles: list[str] | dict[str, Any]
+) -> dict[str, list[str]]:
+    """Collect bodies by semantic key.
+
+    The canvas legitimately ships duplicates for some keys — working-folder
+    paths can have a project-mount and a local-mirror copy, for example — so
+    we keep all hits and let the caller pick which to use. Alias lists are
+    priority ordered; if two aliases for the same semantic key match
+    different nodes, preferred aliases appear first in the captured list.
+    """
+    tracked = normalize_tracked_multilines(tracked_titles)
+    captured: dict[str, list[tuple[int, int, str]]] = {
+        key: [] for key in tracked
+    }
+    candidates: list[tuple[int, int, str, str]] = []
+    for key, aliases in tracked.items():
+        for priority, alias in enumerate(aliases):
+            # Sort longest-first within the same priority so a future short
+            # alias cannot shadow a more specific one.
+            candidates.append((priority, -len(alias), key, alias))
+    candidates.sort()
+
+    for order, n in enumerate(nodes):
+        if n.get("type") != "Text Multiline":
+            continue
+        title = _normalize_title(n.get("title") or "")
+        body = (n.get("widgets_values") or [""])[0] or ""
+        for priority, _, key, alias in candidates:
+            if alias in title:
+                captured[key].append((priority, order, body))
+                break
+    return {
+        key: [body for _, _, body in sorted(values)]
+        for key, values in captured.items()
+    }
+
+
+SETUP_VALUE_NODE_TYPES = {
+    "Text Multiline",
+    "PrimitiveBoolean",
+    "PrimitiveFloat",
+    "PrimitiveInt",
+    "PrimitiveString",
+}
+
+
+def node_widget_value(n: dict) -> str:
+    values = n.get("widgets_values")
+    if values is None:
+        return ""
+    if isinstance(values, list):
+        if not values:
+            return ""
+        value = values[0]
+    else:
+        value = values
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return str(value)
+
+
+def extract_setup_variables(
+    nodes: list[dict], tracked_titles: list[str] | dict[str, Any]
+) -> dict[str, list[str]]:
+    """Collect setup-card variable values from source nodes.
+
+    This deliberately ignores GetNode/SetNode relay plumbing. For v02,
+    version/run are PrimitiveInt nodes while the other setup values are
+    Text Multiline nodes.
+    """
+    tracked = _normalize_alias_map(tracked_titles)
+    captured: dict[str, list[tuple[int, int, str]]] = {
+        key: [] for key in tracked
+    }
+    candidates: list[tuple[int, int, str, str]] = []
+    for key, aliases in tracked.items():
+        for priority, alias in enumerate(aliases):
+            candidates.append((priority, -len(alias), key, alias))
+    candidates.sort()
+
+    for order, n in enumerate(nodes):
+        if n.get("type") not in SETUP_VALUE_NODE_TYPES:
+            continue
+        title = _normalize_title(n.get("title") or "")
+        value = node_widget_value(n)
+        for priority, _, key, alias in candidates:
+            if alias == title:
+                captured[key].append((priority, order, value))
+                break
+    return {
+        key: [value for _, _, value in sorted(values)]
+        for key, values in captured.items()
+    }
+
+
+def first_multiline(ml: dict[str, list[str]], needle: str) -> str:
+    return (ml.get(needle) or [""])[0]
+
+
+def _parse_int(value: str) -> Optional[int]:
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def widget_value_by_name(node: dict, name: str, default: Any = "") -> Any:
+    values = node.get("widgets_values")
+    if isinstance(values, dict):
+        value = values.get(name)
+        return default if value is None else value
+    if not isinstance(values, list):
+        return default
+
+    index = 0
+    for inp in node.get("inputs") or []:
+        if not isinstance(inp, dict) or "widget" not in inp:
+            continue
+        widget = inp.get("widget") or {}
+        widget_name = widget.get("name") if isinstance(widget, dict) else None
+        if widget_name == name and index < len(values):
+            value = values[index]
+            return default if value is None else value
+        index += 1
+    return default
+
+
+def output_suffix_from_workflow(nodes: list[dict]) -> str:
+    """Best-effort QuickTime suffix from the active VideoCombine format.
+
+    The OUT settings group builds the name stem from the base name plus
+    format suffix; the combine node then appends the version. If the
+    format is unclear, h264 is the current setup default.
+    """
+    for n in nodes:
+        if n.get("type") != "Easy_VideoCombine":
+            continue
+        fmt = str(widget_value_by_name(n, "format") or "")
+        values = n.get("widgets_values")
+        if not fmt and isinstance(values, list) and len(values) > 3:
+            fmt = str(values[3] or "")
+        fmt_l = fmt.lower()
+        if "prores" in fmt_l:
+            return "ProRes"
+        if "h264" in fmt_l or "mp4" in fmt_l:
+            return "h264"
+    return "h264"
+
+
+def expected_output_tracking(
+    nodes: list[dict],
+    multilines: dict[str, list[str]],
+    setup_variables: dict[str, list[str]],
+) -> dict[str, str]:
+    """Expected external render target for the current setup.
+
+    This deliberately uses the current setup variables rather than
+    ``easy showAnything`` readouts, which may still contain the previous
+    ComfyUI render's filenames.
+    """
+    folder = pick_existing_path(multilines.get("working_folder") or [])
+    base_name = first_multiline(multilines, "name").strip()
+    version = _parse_int(first_multiline(setup_variables, "version"))
+    suffix = output_suffix_from_workflow(nodes)
+    stem_parts = [part for part in (base_name, suffix) if part]
+    stem = "_".join(stem_parts)
+    version_tag = f"v{version:03d}" if version is not None else ""
+    if stem and version_tag:
+        stem = f"{stem}_{version_tag}"
+    return {
+        "folder": folder,
+        "name": stem,
+        "version_tag": version_tag,
+        "format_suffix": suffix,
+    }
+
+
+def delivery_card_filename(
+    output_tracking: dict[str, str],
+    run_number: Optional[int] = None,
+) -> Optional[str]:
+    name = (output_tracking.get("name") or "").strip()
+    if not name:
+        return None
+    if run_number is not None:
+        return f"{name}_run{run_number:03d}_card.png"
+    return f"{name}_card.png"
+
+
+def delivery_card_path(
+    output_tracking: dict[str, str],
+    run_number: Optional[int] = None,
+) -> Optional[Path]:
+    folder = (output_tracking.get("folder") or "").strip()
+    filename = delivery_card_filename(output_tracking, run_number)
+    if not folder or not filename:
+        return None
+    return Path(folder) / "cards" / filename
+
+
+def copy_delivery_card(
+    card_path: Path,
+    output_tracking: dict[str, str],
+    run_number: Optional[int] = None,
+    *,
+    overwrite: bool = False,
+) -> str:
+    delivery_path = delivery_card_path(output_tracking, run_number)
+    if delivery_path is None:
+        return "(not configured)"
+    try:
+        delivery_path.parent.mkdir(parents=True, exist_ok=True)
+        if delivery_path.exists() and not overwrite:
+            return f"exists (left in place: {delivery_path})"
+        shutil.copy2(card_path, delivery_path)
+    except OSError as exc:
+        return f"failed ({exc})"
+    return str(delivery_path)
+
+
+def scrub_path_for_metadata(value: str) -> str:
+    """Store a portable fingerprint instead of full workstation paths."""
+    raw = str(value or "").strip()
+    if not raw:
+        return ""
+    if re.match(r"^[A-Za-z]:[/\\]", raw) or raw.startswith(("/", "\\\\")):
+        digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+        tail = Path(raw.replace("\\", "/")).name or "(folder)"
+        return f"{tail} [path-sha256:{digest}]"
+    return raw
+
+
+def _scrub_path_fragments(value: str) -> str:
+    def repl(match: re.Match[str]) -> str:
+        return scrub_path_for_metadata(match.group(0))
+
+    value = re.sub(
+        r"(?<![A-Za-z])(?:[A-Za-z]:[/\\]{1,2}|\\\\)[^\"'`,\]\s<>]+",
+        repl,
+        value,
+    )
+    return re.sub(r"<PROJECTS>/[^\"'`,\]\s<>]+", "<PROJECTS>/[path-redacted]", value)
+
+
+def sanitize_workflow_for_archive(value: Any) -> Any:
+    """Redact absolute workstation paths before committing workflow snapshots."""
+    if isinstance(value, dict):
+        return {
+            key: sanitize_workflow_for_archive(item)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [sanitize_workflow_for_archive(item) for item in value]
+    if isinstance(value, str):
+        stripped = value.strip()
+        if re.match(r"^[A-Za-z]:[/\\]", stripped) or stripped.startswith(("/", "\\\\")):
+            redacted = scrub_path_for_metadata(stripped)
+            if value != stripped:
+                return value.replace(stripped, redacted)
+            return redacted
+        return _scrub_path_fragments(value)
+    return value
+
+
+def write_archived_workflow(wf: dict[str, Any], path: Path) -> None:
+    sanitized = sanitize_workflow_for_archive(wf)
+    path.write_text(
+        json.dumps(sanitized, ensure_ascii=False, separators=(",", ":")) + "\n",
+        encoding="utf-8",
+    )
+
+
+def pick_existing_path(candidates: list[str]) -> str:
+    """Pick the first candidate that resolves to a real directory on
+    this machine. Falls back to the first non-empty candidate so the
+    path still appears on the card even if its drive isn't mounted
+    here (worktree-on-N, render-target-on-W, etc.)."""
+    for c in candidates:
+        cleaned = c.strip().strip('"\'').rstrip("/\\")
+        if cleaned and Path(cleaned).is_dir():
+            return cleaned
+    for c in candidates:
+        cleaned = c.strip().strip('"\'').rstrip("/\\")
+        if cleaned:
+            return cleaned
+    return ""
+
+
+def wrap_path(path: str, max_chars: int = 40) -> list[str]:
+    """Wrap a filesystem path onto multiple lines, breaking only on
+    `/` or `\\` separators so directory names stay whole. Used by the
+    card renderer so long mount paths don't bleed past the card edge."""
+    if not path:
+        return [""]
+    raw = path.replace("/", "\\")
+    parts = [p for p in raw.split("\\") if p]
+    if not parts:
+        return [path]
+    lines: list[str] = []
+    cur = ""
+    for i, p in enumerate(parts):
+        token = p + ("\\" if i < len(parts) - 1 else "")
+        if cur and len(cur) + len(token) > max_chars:
+            lines.append(cur)
+            cur = token
+        else:
+            cur = cur + token
+    if cur:
+        lines.append(cur)
+    return lines
+
+
+def _source_node_for_link(
+    link_id: Optional[int],
+    nodes_by_id: dict[int, dict],
+    links_by_id: dict[int, list],
+    *,
+    seen: Optional[set[int]] = None,
+) -> Optional[dict]:
+    if link_id is None:
+        return None
+    if seen is None:
+        seen = set()
+    if link_id in seen:
+        return None
+    seen.add(link_id)
+    link = links_by_id.get(link_id)
+    if not link or len(link) < 3:
+        return None
+    origin = nodes_by_id.get(int(link[1]))
+    if not origin:
+        return None
+    if origin.get("type") == "Reroute":
+        inputs = origin.get("inputs") or []
+        if inputs:
+            return _source_node_for_link(
+                inputs[0].get("link"), nodes_by_id, links_by_id, seen=seen
+            )
+    return origin
+
+
+def extract_director(nodes: list[dict], links: Optional[list] = None) -> Optional[dict]:
+    """Return the active Director node dict (or None).
+
+    Prefer the Director that feeds an ``LTXDirectorGuide.guide_data`` input.
+    A/B comparison canvases can keep both upstream and Koolook Directors on
+    the graph; canvas presence alone is not enough. If no active guide wiring
+    is visible, fall back to the old Koolook-first selection.
+    """
+    if links:
+        nodes_by_id = {int(n["id"]): n for n in nodes if "id" in n}
+        links_by_id = {int(link[0]): link for link in links if link}
+        for guide in (n for n in nodes if n.get("type") == "LTXDirectorGuide"):
+            for inp in guide.get("inputs") or []:
+                if inp.get("name") != "guide_data":
+                    continue
+                source = _source_node_for_link(
+                    inp.get("link"), nodes_by_id, links_by_id
+                )
+                if source and source.get("type") in DIRECTOR_TYPES:
+                    return source
+    for dtype in DIRECTOR_TYPES:
+        for n in nodes:
+            if n.get("type") == dtype:
+                return n
+    return None
+
+
+def director_type(node: Optional[dict]) -> str:
+    return node.get("type") if node else "(missing)"
+
+
+def director_flavor(node: Optional[dict]) -> str:
+    dtype = director_type(node)
+    if dtype in (DIRECTOR_TYPE, *LEGACY_DIRECTOR_TYPES):
+        return "Koolook"
+    if dtype == UPSTREAM_DIRECTOR_TYPE:
+        return "Original upstream"
+    return "(missing)"
+
+
+def detect_upstream_whatdreamscost_version() -> str:
+    """Return the installed upstream WhatDreamsCost version, if available."""
+    dev = os.environ.get("KOLOOK_COMFYUI_DEV_PATH", "")
+    if not dev:
+        return ""
+    custom_nodes = Path(dev).expanduser().parent
+    pyproject = custom_nodes / "WhatDreamsCost-ComfyUI" / "pyproject.toml"
+    if not pyproject.is_file():
+        return ""
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8-sig"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return ""
+    version = data.get("project", {}).get("version", "")
+    return str(version).strip()
+
+
+def detect_koolook_whatdreamscost_pin() -> str:
+    """Return the Koolook fork's pinned upstream version tag."""
+    if not KOOLOOK_UPSTREAM_PIN.is_file():
+        return ""
+    try:
+        for line in KOOLOOK_UPSTREAM_PIN.read_text(encoding="utf-8").splitlines():
+            match = re.match(r'\s*source_ref:\s*"?(v[0-9]+(?:\.[0-9]+)+)', line)
+            if match:
+                return match.group(1)
+    except OSError:
+        return ""
+    version_dir = KOOLOOK_UPSTREAM_PIN.parent.name
+    if version_dir.startswith("v"):
+        return version_dir.replace("_", ".")
+    return ""
+
+
+def director_pin_tag(
+    node: Optional[dict],
+    upstream_whatdreamscost_version: str = "",
+) -> str:
+    dtype = director_type(node)
+    if dtype in (DIRECTOR_TYPE, *LEGACY_DIRECTOR_TYPES):
+        return detect_koolook_whatdreamscost_pin() or "(unknown Koolook pin)"
+    if dtype == UPSTREAM_DIRECTOR_TYPE:
+        if upstream_whatdreamscost_version:
+            return f"v{upstream_whatdreamscost_version}"
+        return "(unknown upstream pin)"
+    return "(missing)"
+
+
+def is_koolook_director(node: Optional[dict]) -> bool:
+    return director_type(node) in (DIRECTOR_TYPE, *LEGACY_DIRECTOR_TYPES)
+
+
+def director_widget(node: Optional[dict], key: str) -> Any:
+    if not node:
+        return None
+    wv = node.get("widgets_values") or []
+    idx = DIRECTOR_WIDX.get(key)
+    if isinstance(wv, dict):
+        named = widget_value_by_name(node, key, default=None)
+        if named is not None:
+            return named
+    if director_type(node) in DIRECTOR_TYPES and isinstance(wv, list):
+        if idx is not None and idx < len(wv):
+            return wv[idx]
+        return None
+    named = widget_value_by_name(node, key, default=None)
+    if named is not None:
+        return named
+    if isinstance(wv, list) and idx is not None and idx < len(wv):
+        return wv[idx]
+    if idx is None or idx >= len(wv):
+        return None
+    return wv[idx]
+
+
+def display_numeric_widget(value: Any, label: str = "unknown") -> str:
+    """Render numeric Director widgets without accepting stale booleans."""
+    if isinstance(value, bool) or value is None:
+        return f"(unknown {label})"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value).strip()
+    if not text:
+        return f"(unknown {label})"
+    try:
+        float(text)
+    except ValueError:
+        return f"(unknown {label})"
+    return text
+
+
+def metadata_numeric_widget(value: Any) -> Any:
+    """Store numeric Director widgets without bool-as-number coercion."""
+    if isinstance(value, bool) or value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return value
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        parsed = float(text)
+    except ValueError:
+        return None
+    return int(parsed) if parsed.is_integer() else parsed
+
+
+def is_input_wired(node: Optional[dict], input_name: str) -> Optional[bool]:
+    """True iff a named input socket on the Director has a non-null
+    link. None when the node or input isn't found."""
+    if not node:
+        return None
+    for inp in node.get("inputs") or []:
+        if inp.get("name") == input_name:
+            return inp.get("link") is not None
+    return None
+
+
+def linked_input_value(
+    nodes: list[dict],
+    links: list,
+    target_node: Optional[dict],
+    input_name: str,
+) -> str:
+    """Return the value feeding a linked input socket, not a nearby note.
+
+    This keeps card/log state aligned with execution: a multiline
+    ``RELAY_OVERRIDES`` note only counts when its value is actually wired into
+    the active Director input. Reroutes and simple display/pass-through nodes
+    are followed one hop chain at a time so tidy canvas plumbing still works.
+    """
+    if not target_node:
+        return ""
+    input_link = None
+    for inp in target_node.get("inputs") or []:
+        if inp.get("name") == input_name:
+            input_link = inp.get("link")
+            break
+    if input_link is None:
+        return ""
+
+    nodes_by_id = {n.get("id"): n for n in nodes}
+    links_by_id = {link[0]: link for link in links if isinstance(link, list) and link}
+    current_link = input_link
+    seen: set[int] = set()
+    while current_link is not None and current_link not in seen:
+        seen.add(current_link)
+        link = links_by_id.get(current_link)
+        if not link or len(link) < 3:
+            return ""
+        source = nodes_by_id.get(link[1])
+        if not source:
+            return ""
+        source_type = source.get("type")
+        if source_type in {"Reroute", "easy showAnything"}:
+            source_inputs = source.get("inputs") or []
+            current_link = source_inputs[0].get("link") if source_inputs else None
+            continue
+        return node_widget_value(source)
+    return ""
+
+
+def active_relay_overrides(
+    nodes: list[dict],
+    links: list,
+    director_node: Optional[dict],
+) -> str:
+    if not is_koolook_director(director_node):
+        return ""
+    return linked_input_value(nodes, links, director_node, "relay_overrides")
+
+
+def _coerce_segment_numeric(seg: dict) -> dict:
+    """Coerce a timeline segment's numeric fields (start, length,
+    trimStart) to int. The upstream Director itself does this
+    defensively at ltx_director.py:232-234 — the saved JSON sometimes
+    contains string values for these fields, and downstream
+    arithmetic (`start / fps`, `<` comparisons) breaks silently
+    without coercion. Failures collapse to 0 so a malformed segment
+    can't crash the loop."""
+    out = dict(seg)
+    for k in ("start", "length", "trimStart"):
+        if k in out:
+            try:
+                out[k] = int(float(out[k]))
+            except (TypeError, ValueError):
+                print(
+                    f"WARNING: timeline segment {k}={out[k]!r} is not numeric; "
+                    "using 0 for loop/card extraction.",
+                    file=sys.stderr,
+                )
+                out[k] = 0
+    return out
+
+
+def parse_timeline(director_node: Optional[dict]) -> dict[str, list]:
+    """Parse the timeline_data JSON widget into a dict of segments +
+    audioSegments. Both default to empty lists on any error so the
+    rest of the pipeline can iterate without further guards.
+
+    Per-segment numeric fields are coerced via _coerce_segment_numeric
+    so downstream arithmetic stays type-safe regardless of what shape
+    the Comfy frontend saved into the JSON."""
+    raw = director_widget(director_node, "timeline_data") or ""
+    if not raw:
+        return {"segments": [], "audioSegments": []}
+    try:
+        tl = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"segments": [], "audioSegments": []}
+    if not isinstance(tl, dict):
+        return {"segments": [], "audioSegments": []}
+    return {
+        "segments": [
+            _coerce_segment_numeric(s)
+            for s in (tl.get("segments") or [])
+            if isinstance(s, dict)
+        ],
+        "audioSegments": [
+            _coerce_segment_numeric(s)
+            for s in (tl.get("audioSegments") or [])
+            if isinstance(s, dict)
+        ],
+    }
+
+
+def derive_audio_state(
+    director_node: Optional[dict], timeline: dict[str, list]
+) -> str:
+    """Reduce director presence plus three structural audio signals —
+    audio_vae wiring, use_custom_audio toggle, audioSegments count — to one label that
+    mirrors how the Director would actually behave at runtime
+    (see forks/.../ltx_director.py: audio_vae None gates everything;
+    then use_custom_audio chooses between the encoded path and the
+    empty/model-gen path).
+
+    Five distinct outcomes — "(no director)" is split off so a
+    missing-director workflow doesn't get the same label as a
+    director-present-but-VAE-unwired one, which silently collapsed
+    pre-fix because is_input_wired(None, …) also returns None."""
+    if director_node is None:
+        return "(no director)"
+    vae_wired = is_input_wired(director_node, "audio_vae")
+    use_custom = director_widget(director_node, "use_custom_audio")
+    audio_segs = timeline.get("audioSegments") or []
+    # vae_wired can be None (input socket missing from this node's
+    # schema, e.g. an older workflow before audio_vae existed) OR
+    # False (socket present but unwired). Both functionally mean
+    # "no audio latent produced", so collapse them here — but only
+    # AFTER the director-missing case has been split off above.
+    if not vae_wired:
+        return "off (no VAE)"
+    if use_custom is True:
+        return "custom" if audio_segs else "custom (empty)"
+    return "model-gen"
+
+
+def video_segment_has_audio(video_seg: dict, audio_segs: list[dict]) -> bool:
+    """Does an audioSegments[] entry overlap this video segment's time
+    range? Matches how _build_combined_audio aligns the audio waveform
+    onto the global timeline."""
+    v_start = video_seg.get("start", 0)
+    v_end = v_start + video_seg.get("length", 0)
+    for a in audio_segs:
+        a_start = a.get("start", 0)
+        a_end = a_start + a.get("length", 0)
+        if a_start < v_end and a_end > v_start:
+            return True
+    return False
+
+
+def segment_prompt_mode(segments: list[dict]) -> str:
+    """Classify whether timeline segments share one prompt or vary.
+
+    This is a structural prompt check only. It normalizes whitespace but
+    does not inspect prompt meaning, so it stays inside the card's source
+    rule: Director timeline JSON in, small capture label out.
+    """
+    if not segments:
+        return "none"
+    prompts = [
+        " ".join(str(seg.get("prompt") or "").split())
+        for seg in segments
+    ]
+    if any(not prompt for prompt in prompts):
+        return "missing"
+    if len(prompts) == 1:
+        return "single"
+    return "same" if len(set(prompts)) == 1 else "per-segment"
+
+
+SCORE_PAT = re.compile(
+    r"^\s*(?P<axis>motion|sync|sharp(?:ness)?)\s*[:=]?\s*"
+    r"(?P<n>\d+)(?:\s*/\s*5)?\s*$",
+    re.IGNORECASE,
+)
+
+
+def parse_feedback(body: str) -> tuple[dict[str, Optional[int]], list[str]]:
+    scores: dict[str, Optional[int]] = {
+        "motion": None, "sync": None, "sharp": None,
+    }
+    text_lines: list[str] = []
+    for line in body.splitlines():
+        m = SCORE_PAT.match(line)
+        if m:
+            axis = m.group("axis").lower()
+            axis = "sharp" if axis.startswith("sharp") else axis
+            scores[axis] = int(m.group("n"))
+        elif line.strip():
+            text_lines.append(line.strip())
+    return scores, text_lines
+
+
+# --------------------------------------------------------------------------
+# Repo / fork state.
+# --------------------------------------------------------------------------
+
+
+def short_sha() -> str:
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=str(REPO_ROOT),
+            capture_output=True, text=True, timeout=2,
+        )
+        return r.stdout.strip() if r.returncode == 0 else "unknown"
+    except (OSError, subprocess.TimeoutExpired):
+        return "unknown"
+
+
+def fork_dir_status(fork_rel: str) -> str:
+    try:
+        r = subprocess.run(
+            ["git", "status", "--short", "--", fork_rel],
+            cwd=str(REPO_ROOT),
+            capture_output=True, text=True, timeout=3,
+        )
+        if r.returncode != 0:
+            return f"(git status failed: {r.stderr.strip()[:80]})"
+        return r.stdout.strip() or "clean (matches HEAD)"
+    except (OSError, subprocess.TimeoutExpired):
+        return "(git unreachable)"
+
+
+def read_dev_build_json() -> dict[str, str]:
+    dev = os.environ.get("KOLOOK_COMFYUI_DEV_PATH", "")
+    if not dev:
+        return {}
+    p = Path(dev) / "web" / "_dev_build.json"
+    if not p.is_file():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+# --------------------------------------------------------------------------
+# Run folder naming.
+# --------------------------------------------------------------------------
+
+
+def next_run_number(runs_dir: Path) -> int:
+    if not runs_dir.is_dir():
+        return 1
+    nums: list[int] = []
+    for child in runs_dir.iterdir():
+        if not child.is_dir() or not child.name.startswith("run-"):
+            continue
+        m = re.match(r"run-(\d+)", child.name)
+        if m:
+            nums.append(int(m.group(1)))
+    log_path = runs_dir / "log.md"
+    if log_path.is_file():
+        try:
+            for line in log_path.read_text(encoding="utf-8").splitlines():
+                m = re.match(r"\|\s*(\d{3,})\s*\|", line)
+                if m:
+                    nums.append(int(m.group(1)))
+        except OSError:
+            pass
+    return max(nums) + 1 if nums else 1
+
+
+_LABEL_BAD = re.compile(r"[^a-z0-9._-]+")
+
+
+def autogen_label(
+    name: str,
+    director_node: Optional[dict],
+    relay_overrides_raw: str,
+) -> str:
+    slug = _LABEL_BAD.sub("-", name.lower()).strip("-") or "unnamed"
+    dtype = director_type(director_node)
+    if dtype == UPSTREAM_DIRECTOR_TYPE:
+        director_tag = "upstream"
+    elif is_koolook_director(director_node):
+        director_tag = "koolook"
+    else:
+        director_tag = "missing"
+    use_custom = director_widget(director_node, "use_custom_audio")
+    audio_tag = "audio-on" if use_custom is True else "audio-off"
+    knob_tag = ""
+    if relay_overrides_raw.strip():
+        try:
+            opts = json.loads(relay_overrides_raw)
+            if isinstance(opts, dict) and "video_strength" in opts:
+                knob_tag = f"_vstr{opts['video_strength']}"
+        except (json.JSONDecodeError, TypeError):
+            pass
+    label = f"{slug}_{director_tag}_{audio_tag}{knob_tag}"
+    if len(label) > 60:
+        label = label[:60].rstrip("-_")
+    return label
+
+
+# --------------------------------------------------------------------------
+# Snapshot artifact writers.
+# --------------------------------------------------------------------------
+
+
+def render_relay_overrides_txt(
+    raw: str, director_node: Optional[dict]
+) -> str:
+    body = raw.strip() if raw and raw.strip() else "(empty — upstream defaults)"
+    missing_note = ""
+    if director_node is None:
+        missing_note = (
+            "\n\n# WARNING: no supported LTXDirector node found in "
+            "the workflow — the relay_overrides value above isn't being "
+            "consumed by anything. Add the Koolook Director to make it active.\n"
+        )
+    elif not is_koolook_director(director_node):
+        missing_note = (
+            "\n\n# NOTE: this value is INERT for this render — the Director "
+            f"node in the workflow is upstream `{director_type(director_node)}`, "
+            "which has no `relay_overrides` input. Swap to "
+            "`LTXDirector__koolook` to make this active.\n"
+        )
+    return f"{body}\n{missing_note}"
+
+
+def render_patch_state(build: dict[str, str], fork_status: str) -> str:
+    return (
+        f"# Fork state at submission\n\n"
+        f"MAIN SHA              : {short_sha()}\n"
+        f"Last dev-sync-audio   : {build.get('commit', '(no _dev_build.json)')}"
+        f"  ({build.get('synced_at', '?')})\n"
+        f"Sync scope tag        : {build.get('scope', '(none)')}\n"
+        f"Sync worktree         : {build.get('worktree', '?')}\n"
+        f"Fork dir status       : {fork_status}\n"
+    )
+
+
+def card_metadata(
+    nnn: int,
+    label: str,
+    wf_path: Path,
+    multilines: dict[str, list[str]],
+    setup_variables: dict[str, list[str]],
+    output_tracking: dict[str, str],
+    director_node: Optional[dict],
+    timeline: dict[str, list],
+    audio_src: str,
+    build: dict[str, str],
+    fork_status: str,
+    upstream_whatdreamscost_version: str,
+) -> dict[str, Any]:
+    segments = timeline.get("segments") or []
+    audio_segments = timeline.get("audioSegments") or []
+    setup_input_path = first_multiline(setup_variables, "input_path_exr")
+    output_folder = output_tracking.get("folder", "")
+    return {
+        "schema": "koolook.audio_loop.card_metadata.v1",
+        "run": {
+            "capture_number": f"{nnn:03d}",
+            "label": label,
+            "date": date.today().isoformat(),
+            "workflow": f"run{nnn:03d}_workflow.json",
+            "source_workflow": wf_path.name,
+            "archived_workflow": f"run{nnn:03d}_workflow.json",
+            "setup_name": wf_path.stem,
+        },
+        "setup": {
+            "base_name": first_multiline(multilines, "name").strip(),
+            "working_folder": scrub_path_for_metadata(output_folder),
+            "input_path_exr": scrub_path_for_metadata(setup_input_path),
+            "global_version": first_multiline(setup_variables, "version"),
+            "global_run_offset": first_multiline(setup_variables, "run_offset"),
+            "relay_overrides": first_multiline(multilines, "relay_overrides").strip(),
+        },
+        "output": {
+            "folder": scrub_path_for_metadata(output_folder),
+            "name": output_tracking.get("name", ""),
+            "version_tag": output_tracking.get("version_tag", ""),
+            "format_suffix": output_tracking.get("format_suffix", ""),
+        },
+        "director": {
+            "type": director_type(director_node),
+            "flavor": director_flavor(director_node),
+            "pin_tag": director_pin_tag(
+                director_node, upstream_whatdreamscost_version
+            ),
+            "upstream_whatdreamscost_version": upstream_whatdreamscost_version,
+            "audio_src": audio_src,
+            "epsilon": director_widget(director_node, "epsilon"),
+            "duration_frames": director_widget(director_node, "duration_frames"),
+            "duration_seconds": director_widget(director_node, "duration_seconds"),
+            "frame_rate": metadata_numeric_widget(
+                director_widget(director_node, "frame_rate")
+            ),
+            "segment_prompt_mode": segment_prompt_mode(segments),
+            "video_segments": len(segments),
+            "audio_segments": len(audio_segments),
+        },
+        "repo": repo_metadata_from_build(build, fork_status),
+    }
+
+
+def repo_metadata_from_build(build: dict[str, str], fork_status: str) -> dict[str, str]:
+    return {
+        "main_sha": short_sha(),
+        "sync_script": "sync_to_dev_audio.py",
+        "last_dev_sync_audio": build.get("commit", ""),
+        "last_dev_sync_at": build.get("synced_at", ""),
+        "sync_scope_tag": build.get("scope", ""),
+        "sync_worktree": build.get("worktree", ""),
+        "fork_dir_status": fork_status,
+    }
+
+
+def parse_dev_sync_audio_line(value: str) -> tuple[str, str]:
+    """Split 'sha  (date)' patch_state text into schema fields."""
+    raw = str(value or "").strip()
+    match = re.match(r"(.+?)\s+\(([^()]*)\)\s*$", raw)
+    if not match:
+        return raw, ""
+    return match.group(1).strip(), match.group(2).strip()
+
+
+def _notes_value(value: str) -> str:
+    cleaned = value.strip()
+    if not cleaned:
+        return "`(missing)`"
+    if "\n" not in cleaned:
+        return f"`{cleaned}`"
+    indented = "\n".join(f"  {line}" for line in cleaned.splitlines())
+    return f"\n{indented}"
+
+
+def render_setup_variables_md(
+    nnn: int,
+    wf_path: Path,
+    multilines: dict[str, list[str]],
+    setup_variables: dict[str, list[str]],
+    director_node: Optional[dict],
+    timeline: dict[str, list],
+    output_tracking: dict[str, str],
+    *,
+    commit_sha: str = "",
+) -> str:
+    segments = timeline.get("segments") or []
+    audio_segs = timeline.get("audioSegments") or []
+    dur_f = director_widget(director_node, "duration_frames")
+    dur_s = director_widget(director_node, "duration_seconds")
+    fps = display_numeric_widget(
+        director_widget(director_node, "frame_rate"), "fps"
+    )
+    epsilon = director_widget(director_node, "epsilon")
+    relay_overrides = first_multiline(multilines, "relay_overrides")
+    if relay_overrides.strip() and not is_koolook_director(director_node):
+        relay_overrides = (
+            f"{relay_overrides} (inert: active Director is upstream LTXDirector)"
+        )
+    upstream_whatdreamscost_version = detect_upstream_whatdreamscost_version()
+    rows = [
+        ("Capture run number", f"{nnn:03d} (from runs folder/log)"),
+        ("Setup name", wf_path.stem),
+        ("Image segments", f"{len(segments)} video / {len(audio_segs)} audio"),
+        ("Prompts / similarity", segment_prompt_mode(segments)),
+        ("Commit No.", commit_sha or short_sha()),
+        ("LTX-Director (flavour)", director_flavor(director_node)),
+        (
+            "Director pin tag",
+            director_pin_tag(director_node, upstream_whatdreamscost_version),
+        ),
+        ("Audio src", derive_audio_state(director_node, timeline)),
+        ("epsilon", "" if epsilon is None else str(epsilon)),
+        ("Duration", f"{dur_f} frames @ {fps} fps ({dur_s} sec)"),
+        ("RELAY_OVERRIDES", relay_overrides),
+        (
+            "GLOBAL [ path ] - working folder",
+            scrub_path_for_metadata(first_multiline(multilines, "working_folder")),
+        ),
+        ("GLOBAL [ base name ]", first_multiline(multilines, "name")),
+        (
+            "INPUT Path [ EXR ]",
+            scrub_path_for_metadata(first_multiline(setup_variables, "input_path_exr")),
+        ),
+        ("GLOBAL [ version ]", first_multiline(setup_variables, "version")),
+        ("GLOBAL [ run offset ]", first_multiline(setup_variables, "run_offset")),
+        ("Output folder", scrub_path_for_metadata(output_tracking.get("folder", ""))),
+        ("Output name", output_tracking.get("name", "")),
+        ("OVERLAY - INFO", "(captured verbatim above)"),
+        ("OVERLAY - FEEDBACK", "(captured verbatim above)"),
+    ]
+    body = "\n".join(
+        f"- {label}: {_notes_value(value)}" for label, value in rows
+    )
+    return f"## SETUP variables (captured)\n\n{body}\n\n"
+
+
+def render_notes_md(
+    nnn: int,
+    wf_path: Path,
+    multilines: dict[str, list[str]],
+    setup_variables: dict[str, list[str]],
+    director_node: Optional[dict],
+    timeline: dict[str, list],
+    audio_src: str,
+    info_body: str,
+    feedback_lines: list[str],
+    scores: dict[str, Optional[int]],
+    output_tracking: dict[str, str],
+    *,
+    commit_sha: str = "",
+) -> str:
+    """Notes pulled exclusively from the two source families the card
+    is allowed to read: the OVERLAY-* multilines and the active
+    Director node. No widget-scraping of BasicScheduler / KSamplerSelect /
+    RandomNoise / CFGGuider — those don't define what this loop sweeps."""
+    info_indented = (
+        "\n".join(
+            f"    {line}" if line else ""
+            for line in info_body.splitlines()
+        )
+        if info_body.strip()
+        else "    (none)"
+    )
+    feedback_body = "\n".join(feedback_lines) if feedback_lines else "(none)"
+    scores_line = " · ".join(
+        f"{k}: {v if v is not None else '?'}/5"
+        for k, v in scores.items()
+    )
+
+    if director_node is None:
+        director_kind = (
+            "**missing** — no `LTXDirector__koolook` node on the "
+            "canvas; this render didn't run through the Koolook fork."
+        )
+    elif not is_koolook_director(director_node):
+        director_kind = (
+            f"**upstream** `{director_type(director_node)}` "
+            "(Koolook variant NOT wired — relay_overrides + per-segment "
+            "sigma are INERT this render)"
+        )
+    else:
+        director_kind = (
+            f"{director_flavor(director_node)} (`{director_type(director_node)}`)"
+        )
+
+    epsilon = director_widget(director_node, "epsilon")
+    dur_f = director_widget(director_node, "duration_frames")
+    dur_s = director_widget(director_node, "duration_seconds")
+    fps = display_numeric_widget(
+        director_widget(director_node, "frame_rate"), "fps"
+    )
+    segments = timeline.get("segments") or []
+    audio_segs = timeline.get("audioSegments") or []
+    prompt_mode = segment_prompt_mode(segments)
+
+    return (
+        f"# Run notes\n\n"
+        f"## Maintainer feedback (OVERLAY - FEEDBACK, verbatim)\n\n"
+        f"{feedback_body}\n\n"
+        f"**Scores:** {scores_line}\n\n"
+        f"## OVERLAY - INFO (verbatim)\n\n"
+        f"{info_indented}\n\n"
+        f"{render_setup_variables_md(nnn, wf_path, multilines, setup_variables, director_node, timeline, output_tracking, commit_sha=commit_sha)}"
+        f"## Director node — structural state\n\n"
+        f"- Variant: {director_kind}\n"
+        f"- Audio src: {audio_src}\n"
+        f"- ε (epsilon): {epsilon!r}\n"
+        f"- Duration: {dur_f} frames @ {fps} fps ({dur_s} sec)\n"
+        f"- Segments: {len(segments)} video / "
+        f"{len(audio_segs)} audio\n"
+        f"- Segment prompt mode: {prompt_mode}\n"
+    )
+
+
+def render_log_row(
+    nnn: int,
+    director_node: Optional[dict],
+    relay_overrides_raw: str,
+    audio_src: str,
+    timeline: dict[str, list],
+    scores: dict[str, Optional[int]],
+    feedback_lines: list[str],
+) -> str:
+    """Rolling-table row aligned with the card's data-source rule —
+    multilines + active Director only. Scheduler/sampler columns are
+    deliberately absent (they aren't what this loop sweeps)."""
+    director_cell = director_type(director_node)
+    relay_cell = (
+        f"`{relay_overrides_raw.strip()}`"
+        if relay_overrides_raw.strip()
+        else "(empty → defaults)"
+    )
+    segments = timeline.get("segments") or []
+    audio_segments = timeline.get("audioSegments") or []
+    seg_cell = f"{len(segments)}v/{len(audio_segments)}a"
+    # `or '?'` would map a legitimate 0/5 to '?' because 0 is falsy;
+    # explicit None-check preserves the score the maintainer typed.
+    # Parallels render_audio_card._s(): the log uses bare digits, while
+    # the card uses N/5 labels.
+    def _score(v: Optional[int]) -> str:
+        return str(v) if v is not None else "?"
+    score_cell = (
+        f"M{_score(scores.get('motion'))}·S{_score(scores.get('sync'))}·"
+        f"Sh{_score(scores.get('sharp'))}"
+    )
+    notes_cell = (
+        " ".join(feedback_lines)[:120] if feedback_lines else "(none)"
+    ).replace("|", "\\|")
+    return (
+        f"| {nnn:03d} | {date.today().isoformat()} | `{director_cell}` "
+        f"| {relay_cell} | {audio_src} | {seg_cell} "
+        f"| {score_cell} | {notes_cell} |\n"
+    )
+
+
+# --------------------------------------------------------------------------
+# Driver.
+# --------------------------------------------------------------------------
+
+
+def _build_state_for_card(
+    nnn: int, label: str, wf_path: Path,
+    multilines: dict[str, list[str]],
+    output_tracking: dict[str, str],
+    metadata: dict[str, Any],
+    director_node: Optional[dict],
+    timeline: dict[str, list],
+    audio_src: str,
+    scores: dict[str, Optional[int]], feedback_lines: list[str],
+) -> dict[str, Any]:
+    """Card state — strict subset matching the agreed source families:
+    five tracked multilines + the active Director node's own values.
+    No git, no _dev_build.json, no scheduler scrape.
+
+    Director's duration_frames / duration_seconds widgets are NOT
+    included — the card dropped the Duration row in favour of
+    per-segment time ranges, and notes.md reads them straight from
+    `director_node` via `director_widget`. Keeping them out of state
+    prevents the consumed-but-unused asymmetry the review caught."""
+    return {
+        "run_number": nnn,
+        "run_label": label,
+        "date": date.today().isoformat(),
+        "workflow_name": f"run{nnn:03d}_workflow.json",
+        "source_workflow_name": wf_path.name,
+        "name": first_multiline(multilines, "name").strip() or "(unnamed)",
+        "relay_overrides_raw": first_multiline(multilines, "relay_overrides"),
+        "info_body": first_multiline(multilines, "overlay - info").rstrip(),
+        "feedback_lines": feedback_lines,
+        "scores": scores,
+        "work_folder": pick_existing_path(
+            multilines.get("working_folder") or []
+        ),
+        "output_folder": output_tracking.get("folder", ""),
+        "output_name": output_tracking.get("name", ""),
+        "metadata": metadata,
+        "director_node": director_node,
+        "director_variant": director_type(director_node),
+        "director_flavor": director_flavor(director_node),
+        "director_pin_tag": (metadata.get("director") or {}).get("pin_tag", ""),
+        "audio_src": audio_src,
+        "epsilon": director_widget(director_node, "epsilon"),
+        "frame_rate": metadata_numeric_widget(
+            director_widget(director_node, "frame_rate")
+        ),
+        "segments": timeline.get("segments") or [],
+        "audio_segments": timeline.get("audioSegments") or [],
+        "segment_prompt_mode": segment_prompt_mode(
+            timeline.get("segments") or []
+        ),
+    }
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--config", type=Path, default=DEFAULT_CONFIG_PATH,
+                   help="Loop config JSON (default: alongside this script).")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Print what would be captured. No files written.")
+    p.add_argument("--label", default=None,
+                   help="Override the auto-generated run label suffix.")
+    p.add_argument("--no-log", action="store_true",
+                   help="Skip the log.md row append.")
+    p.add_argument("--no-card", action="store_true",
+                   help="Skip the card render even if config.render_card is true.")
+    p.add_argument("--workflow", type=Path, default=None,
+                   help="Explicit workflow JSON path (skip auto-discover).")
+    args = p.parse_args()
+
+    cfg = load_config(args.config)
+    env_file = find_dotenv()
+    if env_file is not None:
+        load_dotenv(env_file)
+
+    module_dir = REPO_ROOT / cfg["module_path"]
+    runs_dir = module_dir / "runs"
+    log_path = runs_dir / "log.md"
+
+    if args.workflow:
+        wf_path = args.workflow.expanduser().resolve()
+        if not wf_path.is_file():
+            print(f"workflow not found: {wf_path}", file=sys.stderr)
+            return 3
+    else:
+        wf_path = find_workflow(resolve_workflows_dir(cfg), cfg)
+
+    with wf_path.open(encoding="utf-8-sig") as f:
+        wf = json.load(f)
+    nodes = wf.get("nodes") or []
+
+    multilines = extract_multilines(nodes, cfg["tracked_multilines"])
+    setup_variables = extract_setup_variables(
+        nodes, cfg.get("tracked_setup_variables", {})
+    )
+    output_tracking = expected_output_tracking(nodes, multilines, setup_variables)
+    director_node = extract_director(nodes, wf.get("links") or [])
+    timeline = parse_timeline(director_node)
+    audio_src = derive_audio_state(director_node, timeline)
+    scores, feedback_lines = parse_feedback(
+        first_multiline(multilines, "overlay - feedback")
+    )
+
+    name = first_multiline(multilines, "name").strip()
+    relay_overrides_raw = active_relay_overrides(
+        nodes, wf.get("links") or [], director_node
+    )
+    active_multilines = dict(multilines)
+    active_multilines["relay_overrides"] = [relay_overrides_raw]
+    info_body = first_multiline(multilines, "overlay - info").rstrip()
+    label = args.label or autogen_label(
+        name, director_node, relay_overrides_raw
+    )
+    nnn = next_run_number(runs_dir)
+    run_dir = runs_dir / f"run-{nnn:03d}_{label}"
+    build = read_dev_build_json()
+    fork_status = fork_dir_status(cfg["fork_to_track"])
+    upstream_whatdreamscost_version = detect_upstream_whatdreamscost_version()
+    metadata = card_metadata(
+        nnn, label, wf_path, active_multilines, setup_variables, output_tracking,
+        director_node, timeline, audio_src, build, fork_status,
+        upstream_whatdreamscost_version,
+    )
+
+    # Two-line chat-report header (matches dev-sync convention).
+    print(f"{short_sha()} - {REPO_ROOT.name}")
+    print(
+        f"loop-{cfg['job_name']} run-{nnn:03d}  workflow={wf_path.name}  "
+        f"director={director_type(director_node)}  "
+        f"audio={audio_src}"
+    )
+
+    if args.dry_run:
+        print(f"  (dry-run) would write: {run_dir.relative_to(REPO_ROOT)}")
+        print(f"  (dry-run) would append row to: {log_path.relative_to(REPO_ROOT)}")
+        return 0
+
+    run_dir.mkdir(parents=True, exist_ok=False)
+    write_archived_workflow(wf, run_dir / f"run{nnn:03d}_workflow.json")
+    (run_dir / "relay_overrides.txt").write_text(
+        render_relay_overrides_txt(relay_overrides_raw, director_node),
+        encoding="utf-8",
+    )
+    (run_dir / "patch_state.txt").write_text(
+        render_patch_state(build, fork_status),
+        encoding="utf-8",
+    )
+    (run_dir / "metadata.json").write_text(
+        json.dumps(metadata, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    (run_dir / "notes.md").write_text(
+        render_notes_md(
+            nnn, wf_path, active_multilines, setup_variables,
+            director_node, timeline, audio_src,
+            info_body, feedback_lines, scores, output_tracking,
+        ),
+        encoding="utf-8",
+    )
+
+    card_status = "skipped"
+    delivery_status = "skipped"
+    if cfg["render_card"] and not args.no_card:
+        try:
+            sys.path.insert(0, str(Path(__file__).resolve().parent))
+            from make_card_audio import render_audio_card  # type: ignore[import-not-found]
+
+            state = _build_state_for_card(
+                nnn, label, wf_path,
+                active_multilines, output_tracking, metadata, director_node, timeline,
+                audio_src, scores, feedback_lines,
+            )
+            card_path = render_audio_card(state, run_dir / "card.png")
+            card_status = "rendered"
+            delivery_status = copy_delivery_card(card_path, output_tracking, nnn)
+        except ImportError as exc:
+            card_status = f"skipped ({exc})"
+        except OSError as exc:
+            card_status = f"failed ({exc})"
+
+    if not args.no_log:
+        row = render_log_row(
+            nnn, director_node, relay_overrides_raw, audio_src,
+            timeline, scores, feedback_lines,
+        )
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(row)
+
+    print(f"  wrote:  {run_dir.relative_to(REPO_ROOT)}")
+    print(f"  card:   {card_status}")
+    print(f"  card delivery: {delivery_status}")
+    if not args.no_log:
+        print(f"  logged: {log_path.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/make_card.py

@@ -0,0 +1,801 @@
+"""Render an experiment-tracking card PNG from a ComfyUI workflow JSON.
+
+Usage:
+    python scripts/make_card.py <workflow.json> [output.png]
+
+Reads the LTX Director run/base context from the workflow JSON, paints a
+self-contained card matching the look of
+docs/investigations/experiments/combined-card.html, and writes it to PNG.
+
+PNG can then be loaded into a ComfyUI workflow via a LoadImage node and
+composited alongside the rendered video, or dropped straight into an NLE.
+
+Tested against LTX_Director_4k_v0[1-3].json.
+"""
+from __future__ import annotations
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+
+
+def _load_dotenv(env_path: Path) -> None:
+    """Minimal `.env` loader. Mirrors scripts/sync_to_dev.py — no python-dotenv dep."""
+    if not env_path.exists():
+        return
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def _find_dotenv() -> Path | None:
+    """Find .env in the current worktree first, then fall back to the main repo
+    root (resolved via git's common-dir) when running from a worktree.
+    Returns the first existing .env found, or None."""
+    repo_root = Path(__file__).resolve().parent.parent
+    direct = repo_root / ".env"
+    if direct.exists():
+        return direct
+    # Try the main repo root via git's common-dir.
+    git_marker = repo_root / ".git"
+    common_dir = None
+    if git_marker.is_file():
+        # Worktree marker file contains: "gitdir: <path-to>/<main>/.git/worktrees/<name>"
+        try:
+            content = git_marker.read_text(encoding="utf-8").strip()
+            if content.startswith("gitdir:"):
+                gitdir = Path(content.split(":", 1)[1].strip())
+                # walk up from .git/worktrees/<name>/ to find <main repo>/
+                if "worktrees" in gitdir.parts:
+                    idx = gitdir.parts.index("worktrees")
+                    common_dir = Path(*gitdir.parts[:idx])  # ends at <main>/.git
+                    main_root = common_dir.parent
+                    candidate = main_root / ".env"
+                    if candidate.exists():
+                        return candidate
+        except Exception:
+            pass
+    return None
+
+
+# Resolve repo root and load .env once on import — same pattern as sync_to_dev.py.
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_env_file = _find_dotenv()
+if _env_file is not None:
+    _load_dotenv(_env_file)
+
+# ---------- palette + geometry (kept in sync with combined-card.html) ----------
+W            = 540           # slim vertical card — sits beside a video
+PAD_X        = 28
+PAD_TOP      = 28
+PAD_BOTTOM   = 28
+# Palette mirrored from docs/designs/snapshot-dialogs.html
+BG_OUTER     = (14, 14, 14)      # --bg
+BG_CARD      = (21, 21, 21)      # --panel
+BG_SECTION   = (26, 26, 31)      # --panel-soft  (each section gets this)
+BORDER       = (48, 47, 47)      # --border
+BORDER_STR   = (79, 79, 84)      # --border-strong
+TEXT         = (249, 250, 251)   # --text
+MUTED        = (143, 149, 156)   # --muted
+DIM          = (200, 204, 209)   # close to --text but slightly down
+HEADER_GREY  = (201, 204, 209)   # snapshot dialog H2 colour
+ACCENT_RUN   = (255, 184, 77)    # --amber  (PHASE 1 / changeable)
+ACCENT_BASE  = (109, 180, 255)   # --sky    (frozen base)
+ACCENT_OUT   = (123, 207, 128)   # --green  (post-render)
+NOTE_BG      = (12, 12, 12)
+RADIUS       = 14
+SECTION_RADIUS = 8
+
+# ---------- font loading ----------
+WIN_FONTS = Path(r"C:/Windows/Fonts")
+def load_font(filenames: list[str], size: int) -> ImageFont.FreeTypeFont:
+    for fn in filenames:
+        for p in (WIN_FONTS / fn, Path("/Library/Fonts") / fn, Path("/usr/share/fonts") / fn):
+            if p.exists():
+                return ImageFont.truetype(str(p), size)
+    return ImageFont.load_default()
+
+F_TITLE = load_font(["segoeuib.ttf", "Arial Bold.ttf"], 28)
+F_SUB   = load_font(["segoeui.ttf",  "Arial.ttf"],      17)
+F_H2    = load_font(["segoeuib.ttf", "Arial Bold.ttf"], 16)
+F_TAG     = load_font(["segoeuib.ttf", "Arial Bold.ttf"], 12)   # FEEDBACK / OUTCOME sub-labels
+F_SECTION = load_font(["segoeuib.ttf", "Arial Bold.ttf"], 17)   # main section titles (PHASE 1 etc.)
+F_MONO  = load_font(["consola.ttf",  "Menlo.ttc", "DejaVuSansMono.ttf"], 19)
+F_NOTE  = load_font(["segoeuii.ttf", "Arial Italic.ttf"], 18)
+
+# ---------- workflow extraction ----------
+VIDEO_EXTS = (".mp4", ".mov", ".mkv", ".webm", ".avi")
+LOG_NAME   = "iterations.md"
+AI_SUBDIR  = "_AI"    # AI-managed artifacts live here, separate from user content
+CARD_NAME  = "card.png"
+# Files containing this marker (case-insensitive) in their basename are
+# post-loop outputs (the card already composited with the video) — skip
+# them in auto-discovery so the script never picks its own output as input.
+SKIP_MARKER = "loop"
+
+def _is_loop_output(p: Path) -> bool:
+    return SKIP_MARKER in p.stem.lower()
+LOG_HEADER = (
+    "# LTX Director — iterations log\n\n"
+    "Append-only. Newest at bottom. Generated by `scripts/make_card.py`.\n\n"
+    "| # | When | Run | Format | Denoise | JSON | Video | Δ from base | Feedback |\n"
+    "| - | ---- | --- | ------ | ------- | ---- | ----- | ----------- | -------- |\n"
+)
+
+
+def log_iteration(folder: Path, json_path: Path, data: dict) -> None:
+    """Append one row to <folder>/_AI/iterations.md. Dedupe by (json filename + json mtime).
+    Markdown table — newest at bottom. Creates the file + the _AI subdir on first call."""
+    ai_dir = folder / AI_SUBDIR
+    ai_dir.mkdir(exist_ok=True)
+    log_path = ai_dir / LOG_NAME
+    json_mtime = json_path.stat().st_mtime
+    json_mtime_iso = time.strftime("%Y-%m-%d %H:%M", time.localtime(json_mtime))
+    fingerprint = f"{json_path.name}@{int(json_mtime)}"
+
+    existing = ""
+    last_fp = ""
+    next_idx = 1
+    if log_path.exists():
+        existing = log_path.read_text(encoding="utf-8")
+        rows = [ln for ln in existing.splitlines()
+                if ln.startswith("| ") and not ln.startswith("| -")
+                and not ln.startswith("| #")]
+        next_idx = len(rows) + 1
+        if rows:
+            # last row's hidden HTML-comment fingerprint, if present
+            tail_comment_re = re.compile(r"<!--fp:([^>]+)-->")
+            for ln in reversed(rows):
+                m = tail_comment_re.search(ln)
+                if m:
+                    last_fp = m.group(1)
+                    break
+
+    if last_fp == fingerprint:
+        # Same JSON, same mtime — already logged. Skip.
+        return
+
+    def trunc(s, n):
+        s = (s or "").replace("\n", " ").strip()
+        return (s[: n - 1] + "…") if len(s) > n else s
+
+    row = (
+        f"| {next_idx} "
+        f"| {json_mtime_iso} "
+        f"| {data.get('run_label', '?')} "
+        f"| {data.get('format', '?')} "
+        f"| {data.get('denoise', '?')} "
+        f"| `{json_path.name}` "
+        f"| `{data.get('render_output', '—')}` "
+        f"| {trunc(data.get('note', ''), 40)} "
+        f"| {trunc(data.get('feedback', ''), 40)} "
+        f"|<!--fp:{fingerprint}-->\n"
+    )
+
+    if not existing:
+        log_path.write_text(LOG_HEADER + row, encoding="utf-8")
+    else:
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(row)
+
+
+def load_workflow(path: Path) -> dict:
+    """Load a ComfyUI workflow JSON. Accepts two formats:
+       1. raw editor JSON (top-level 'nodes' + 'links' keys), or
+       2. metadata bundle ({"CreationTime": ..., "prompt": ..., "workflow": {...}})
+          — the format ComfyUI writes alongside saved outputs.
+    """
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if "nodes" in raw:
+        return raw
+    if "workflow" in raw and isinstance(raw["workflow"], dict) and "nodes" in raw["workflow"]:
+        return raw["workflow"]
+    raise SystemExit(f"Unrecognised JSON format in {path} — no 'nodes' key found.")
+
+def find_newest_video(folder: Path):
+    """Return (Path, mtime) for the newest video file in folder, or (None, None).
+    Skips files marked as loop outputs (see SKIP_MARKER)."""
+    candidates = [p for p in folder.iterdir()
+                  if p.is_file()
+                  and p.suffix.lower() in VIDEO_EXTS
+                  and not _is_loop_output(p)]
+    if not candidates:
+        return None, None
+    best = max(candidates, key=lambda p: p.stat().st_mtime)
+    return best, best.stat().st_mtime
+
+
+def find_comfyui_log_path():
+    """Resolve the ComfyUI log path. Priority:
+      1. `KOLOOK_COMFYUI_LOG` env var (explicit override).
+      2. Inferred from `KOLOOK_COMFYUI_DEV_PATH` — the dev path points at
+         `<comfyui-root>/custom_nodes/<koolook>`, so the log sits at
+         `<comfyui-root>/user/comfyui.log`.
+    Returns Path or None."""
+    override = os.environ.get("KOLOOK_COMFYUI_LOG", "").strip()
+    if override:
+        p = Path(override)
+        return p if p.exists() else None
+    dev = os.environ.get("KOLOOK_COMFYUI_DEV_PATH", "").strip()
+    if not dev:
+        return None
+    candidate = Path(dev).parent.parent / "user" / "comfyui.log"
+    return candidate if candidate.exists() else None
+
+
+_LOG_DUR_PATTERNS = [
+    # "Prompt executed in 18.21 seconds"
+    (re.compile(r"Prompt executed in ([\d.]+) seconds"),
+     lambda m: float(m.group(1))),
+    # "Prompt executed in 00:10:33"
+    (re.compile(r"Prompt executed in (\d+):(\d+):(\d+)"),
+     lambda m: int(m.group(1)) * 3600 + int(m.group(2)) * 60 + int(m.group(3))),
+]
+
+
+def render_time_from_log(log_path: Path):
+    """Return the duration of the most recent render that actually wrote
+    frames. Locates the latest `saving images: 100%` line in the Comfy log
+    and pairs it with the next `Prompt executed in X` line — that's the
+    completed EXR-producing render. Skips trivial follow-up prompts that
+    happen between the render finishing and the user invoking /make-card.
+    Returns duration in seconds, or None."""
+    if not log_path or not log_path.exists():
+        return None
+    text = log_path.read_text(encoding="utf-8", errors="replace")
+    saves = list(re.finditer(r"saving images: 100%", text))
+    if not saves:
+        return None
+    after = saves[-1].end()
+    candidates = []
+    for pat, to_seconds in _LOG_DUR_PATTERNS:
+        m = pat.search(text, after)
+        if m:
+            candidates.append((m.start(), to_seconds(m)))
+    if not candidates:
+        return None
+    # Take the first 'Prompt executed in X' line after the save (smallest start).
+    candidates.sort(key=lambda x: x[0])
+    return candidates[0][1]
+
+
+def exr_sequence_duration(folder: Path):
+    """Return (duration_seconds, version_dir_name) for the most recent EXR
+    sequence in the working folder. Treats render time as the wall-clock
+    span between the first and last frame in the version subdirectory of
+    the newest EXR — accurate even when the JSON is saved after rendering.
+    Returns (None, None) if no EXR sequence is found."""
+    all_exrs = list(folder.rglob("*.exr"))
+    if not all_exrs:
+        return None, None
+    newest = max(all_exrs, key=lambda p: p.stat().st_mtime)
+    seq_dir = newest.parent
+    seq_mtimes = sorted(p.stat().st_mtime for p in seq_dir.glob("*.exr"))
+    if len(seq_mtimes) < 2:
+        return None, seq_dir.name
+    return seq_mtimes[-1] - seq_mtimes[0], seq_dir.name
+
+def fmt_duration(seconds: float) -> str:
+    s = int(round(seconds))
+    if s < 60:
+        return f"{s}s"
+    m, s = divmod(s, 60)
+    if m < 60:
+        return f"{m}m {s:02d}s"
+    h, m = divmod(m, 60)
+    return f"{h}h {m:02d}m"
+
+def find(wf, t):
+    return [n for n in wf["nodes"] if n.get("type") == t]
+
+def widgets(n): return n.get("widgets_values", []) or []
+
+def resolve_input(wf, node, name):
+    """Return the upstream node feeding a named input, or None."""
+    links = {link[0]: link for link in wf["links"]}
+    by_id = {n["id"]: n for n in wf["nodes"]}
+    for inp in node.get("inputs", []) or []:
+        if inp.get("name") == name and inp.get("link") is not None:
+            link = links.get(inp["link"])
+            if link:
+                return by_id.get(link[1])
+    return None
+
+def follow_setnode(wf, getnode):
+    """GetNode -> the value-producing source via SetNode of the same variable."""
+    var = widgets(getnode)[0] if widgets(getnode) else None
+    if not var:
+        return None
+    for n in wf["nodes"]:
+        if n.get("type") == "SetNode" and widgets(n)[:1] == [var]:
+            # SetNode's incoming link is the actual value source
+            links = {link[0]: link for link in wf["links"]}
+            by_id = {n["id"]: n for n in wf["nodes"]}
+            for inp in n.get("inputs", []) or []:
+                if inp.get("link") is not None:
+                    link = links.get(inp["link"])
+                    if link:
+                        src = by_id.get(link[1])
+                        # If it's a switch, resolve the selected value
+                        if src and src.get("type") == "easy anythingIndexSwitch":
+                            idx_node = resolve_input(wf, src, "index")
+                            idx = widgets(idx_node)[0] if idx_node and widgets(idx_node) else 0
+                            val_node = resolve_input(wf, src, f"value{idx}")
+                            return val_node
+                        return src
+    return None
+
+def res_label(w, h):
+    return {(3744,2112):"4K", (3840,2160):"4K", (2560,1440):"2K",
+            (1920,1080):"HD", (1280,720):"HD"}.get((w,h), f"{w}x{h}")
+
+def extract(wf):
+    """Pull every field we need to draw the card."""
+    d = find(wf, "LTXDirector")[0]
+    dw = widgets(d)
+    # LTXDirector widget order (verified in v01-v03):
+    #  0 global_prompt, 1 dur_frames, 2 dur_sec, 3 timeline_data, 4 local_prompts,
+    #  5 segment_lengths, 6 epsilon, 7 guide_strength, 8 use_custom_audio,
+    #  9 frame_rate, 10 display_mode, 11 custom_width, 12 custom_height,
+    # 13 resize_method, 14 divisible_by, 15 img_compression
+    epsilon         = dw[6]
+    seg_lengths_str = dw[5]
+    fps             = dw[9]
+    use_custom_aud  = dw[8]
+    dur_frames      = dw[1]
+    dur_seconds     = dw[2]
+
+    # custom_width / height may be widget value OR fed by GetNode chain
+    cw = resolve_input(wf, d, "custom_width")
+    ch = resolve_input(wf, d, "custom_height")
+    if cw and cw.get("type") == "GetNode":
+        cw = follow_setnode(wf, cw)
+    if ch and ch.get("type") == "GetNode":
+        ch = follow_setnode(wf, ch)
+    width  = widgets(cw)[0] if cw and widgets(cw) else dw[11]
+    height = widgets(ch)[0] if ch and widgets(ch) else dw[12]
+
+    # parse timeline_data segments
+    try:
+        tl = json.loads(dw[3]) if dw[3] else {}
+        segments = tl.get("segments", [])
+    except Exception:
+        segments = []
+    seg_lengths = [int(x.strip()) for x in seg_lengths_str.split(",") if x.strip()]
+
+    # phase 1 chain — first BasicScheduler with denoise == 1.0, else first one
+    schedulers = find(wf, "BasicScheduler")
+    p1 = next((s for s in schedulers if widgets(s)[2] == 1), schedulers[0] if schedulers else None)
+    sched_name, steps, denoise = (widgets(p1) if p1 else ("?", "?", "?"))
+
+    # Director Guide scale_by per phase — pick the one fed by LTXDirector (phase 1)
+    guides = find(wf, "LTXDirectorGuide")
+    p1_guide = None
+    for g in guides:
+        latent_src = resolve_input(wf, g, "latent")
+        if latent_src and latent_src.get("type") == "LTXDirector":
+            p1_guide = g
+            break
+    if p1_guide is None and guides:
+        p1_guide = guides[0]
+    mult = widgets(p1_guide)[0] if p1_guide else "?"
+
+    # Pull three named Text Multiline nodes from the workflow:
+    #   - "OVERLAY - INFO" (or any title containing INFO)       -> base notes (Δ from baseline)
+    #   - "OVERLAY - FEEDBACK" / "FEEDBACK" / "OBSERVATIONS"     -> video feedback + scores
+    #   - "Working_Folder_PATH" / "OUT_working_folder"           -> authoritative output folder
+    note, feedback, work_folder = "", "", ""
+    for n in wf["nodes"]:
+        if n.get("type") != "Text Multiline":
+            continue
+        title = (n.get("title") or "").upper()
+        ws = widgets(n)
+        if not (ws and isinstance(ws[0], str)):
+            continue
+        text = ws[0]
+        if not note and ("INFO" in title or ("OVERLAY" in title and "FEEDBACK" not in title)):
+            for marker in ("BASE (notes):", "BASE:"):
+                if marker in text:
+                    note = text.split(marker, 1)[1].strip()
+                    break
+        if not feedback and ("FEEDBACK" in title or "OBSERVATION" in title or "VIDEO" in title):
+            feedback = text.strip()
+        if not work_folder and ("WORKING_FOLDER" in title or "WORK_FOLDER" in title
+                                 or "OUT_WORKING" in title or "WORKING-FOLDER" in title):
+            work_folder = text.strip().strip("\"' ").rstrip("\\/")
+
+    # Parse scores out of the feedback text. Pattern: "motion: 4/5" / "sync 3" / "sharpness: 5/5".
+    scores = {"motion": None, "sync": None, "sharp": None}
+    feedback_lines = []
+    score_re = re.compile(
+        r"^\s*(motion|sync|sharp(?:ness)?|sharpness)\s*[:=]?\s*(\d+)\s*(?:/\s*\d+)?\s*$",
+        re.IGNORECASE,
+    )
+    for line in feedback.splitlines():
+        m = score_re.match(line)
+        if m:
+            key = m.group(1).lower()
+            if key.startswith("sharp"):
+                key = "sharp"
+            scores[key] = int(m.group(2))
+        elif line.strip():
+            feedback_lines.append(line.rstrip())
+    feedback = "\n".join(feedback_lines).strip()
+
+    # model stack
+    ckpt = (widgets(find(wf, "CheckpointLoaderSimple")[0]) if find(wf, "CheckpointLoaderSimple") else [""])[0]
+    lora_nodes = find(wf, "LoraLoaderModelOnly")
+    lora = ""
+    if lora_nodes:
+        lw = widgets(lora_nodes[0])
+        lora_name = lw[0].replace("\\", "/").split("/")[-1].replace(".safetensors", "")
+        lora_strength = lw[1] if len(lw) > 1 else ""
+        lora = f"{lora_name} @ {lora_strength}"
+    clip_nodes = find(wf, "DualCLIPLoader")
+    clip = ""
+    if clip_nodes:
+        cw_ = widgets(clip_nodes[0])
+        clip = cw_[0].replace("\\", "/").split("/")[-1].replace(".safetensors", "")
+    vaes = find(wf, "VAELoaderKJ")
+    video_vae = audio_vae = ""
+    for v in vaes:
+        n = widgets(v)[0].replace(".safetensors", "")
+        if "video" in n:
+            video_vae = n
+        elif "audio" in n:
+            audio_vae = n
+
+    # seed
+    rn = find(wf, "RandomNoise")
+    seed = widgets(rn[0])[0] if rn else "?"
+
+    return {
+        "format": res_label(width, height),
+        "resolution": f"{width} × {height}",
+        "mult": mult,
+        "scheduler": sched_name,
+        "steps": steps,
+        "denoise": denoise,
+        "note": note,
+        "feedback": feedback,
+        "scores": scores,
+        "work_folder_from_wf": work_folder,
+        "epsilon": epsilon,
+        "seed": seed,
+        "fps": fps,
+        "dur_frames": dur_frames,
+        "dur_seconds": dur_seconds,
+        "segments": segments,
+        "seg_lengths": seg_lengths,
+        "use_custom_audio": use_custom_aud,
+        "ckpt": Path(ckpt).name.replace(".safetensors", ""),
+        "lora": lora,
+        "clip": Path(clip).name,
+        "video_vae": video_vae,
+        "audio_vae": audio_vae,
+    }
+
+# ---------- drawing helpers ----------
+def draw_kv_row(draw, x, y, key, val, key_w):
+    draw.text((x, y), key, font=F_MONO, fill=MUTED)
+    draw.text((x + key_w, y), str(val), font=F_MONO, fill=TEXT)
+    return y + 26
+
+def draw_h2(draw, x, y, label, color):
+    draw.text((x, y), label.upper(), font=F_H2, fill=color)
+    return y + 30
+
+def wrap_text(text, max_chars):
+    """Naive word-wrap to fit max_chars per line."""
+    out = []
+    for raw_line in text.split("\n"):
+        if not raw_line.strip():
+            out.append("")
+            continue
+        words, cur = raw_line.split(), ""
+        for w in words:
+            if len(cur) + len(w) + 1 <= max_chars:
+                cur = (cur + " " + w).strip()
+            else:
+                if cur:
+                    out.append(cur)
+                cur = w
+        if cur:
+            out.append(cur)
+    return out
+
+def draw_text_box(draw, x, y, width, label, content, accent, max_lines=3):
+    """Draw a left-accented note box with a header label + wrapped content lines."""
+    char_per_line = 42
+    lines = wrap_text(content, char_per_line)[:max_lines]
+    box_h = 26 + 22 * max(1, len(lines)) + 14
+    draw.rounded_rectangle(
+        [x - 12, y, x + width, y + box_h],
+        radius=4, fill=NOTE_BG,
+    )
+    draw.rectangle([x - 12, y, x - 8, y + box_h], fill=accent)
+    draw.text((x + 4, y + 8), label, font=F_H2, fill=accent)
+    line_y = y + 34
+    for line in lines:
+        draw.text((x + 4, line_y), line, font=F_NOTE, fill=DIM)
+        line_y += 22
+    return y + box_h + 4
+
+def draw_section(draw, x, y, width, accent, label, body_lines_height,
+                  bg=BG_SECTION, border=BORDER):
+    """Draw a section panel header + return (content_x, content_y, content_w, end_y).
+    Body content is drawn by the caller starting at (content_x, content_y)."""
+    HEADER_H = 36
+    section_h = HEADER_H + body_lines_height + 14
+    draw.rounded_rectangle(
+        [x, y, x + width, y + section_h],
+        radius=SECTION_RADIUS, fill=bg, outline=border, width=1,
+    )
+    # header label — bigger, no side bar, accent colour
+    draw.text((x + 14, y + 10), label.upper(), font=F_SECTION, fill=accent)
+    return x + 14, y + HEADER_H, width - 28, y + section_h + 10
+
+def section_body_rows(num_rows, extra=0):
+    """Pixel height needed for N kv rows plus optional extra padding."""
+    return num_rows * 26 + extra
+
+def render(data: dict, out_path: Path) -> None:
+    # Oversized canvas; crop after laying out.
+    canvas_h = 2000
+    img = Image.new("RGB", (W, canvas_h), BG_OUTER)
+    draw = ImageDraw.Draw(img)
+
+    inset = 18
+    # outer card
+    draw.rounded_rectangle(
+        [inset, inset, W - inset, canvas_h - inset],
+        radius=RADIUS, fill=BG_CARD, outline=BORDER, width=1,
+    )
+
+    x = inset + PAD_X
+    y = inset + PAD_TOP
+    inner_w = W - 2 * inset - 2 * PAD_X
+
+    # ---------- HEADER ----------
+    import datetime
+    today = datetime.date.today().isoformat()
+    ver = data.get("run_label", "?")
+    stage_label = "single-stage" if data.get("denoise", 1) == 1 else "two-stage"
+    res_label = data.get("format", "")
+    title_line = f"Run {ver or '?'} — {stage_label} {res_label}".strip()
+    sub_line = f"{today} · {data.get('json_name', '')}"
+    draw.text((x, y), title_line, font=F_TITLE, fill=TEXT)
+    y += 38
+    draw.text((x, y), sub_line, font=F_SUB, fill=MUTED)
+    y += 30
+    # hairline divider under header
+    draw.line([(x, y), (x + inner_w, y)], fill=BORDER, width=1)
+    y += 18
+
+    key_w = 122
+
+    # ---------- PHASE 1 ----------
+    body_h = section_body_rows(5)
+    cx, cy, cw, end_y = draw_section(draw, x, y, inner_w, ACCENT_RUN, "Phase 1", body_h)
+    cy = draw_kv_row(draw, cx, cy, "Format",    f"{data['format']} · {data['resolution']}", key_w)
+    cy = draw_kv_row(draw, cx, cy, "Mult",      data["mult"],       key_w)
+    cy = draw_kv_row(draw, cx, cy, "Scheduler", data["scheduler"],  key_w)
+    cy = draw_kv_row(draw, cx, cy, "Steps",     data["steps"],      key_w)
+    cy = draw_kv_row(draw, cx, cy, "Denoise",   data["denoise"],    key_w)
+    y = end_y
+
+    # ---------- BASE NOTES ----------
+    note_text = data["note"] or "(no changes)"
+    note_lines = wrap_text(note_text, 42)[:4]
+    body_h = max(28, 24 * len(note_lines)) + 4
+    cx, cy, cw, end_y = draw_section(draw, x, y, inner_w, ACCENT_RUN,
+                                       "Base · notes (Δ this run)", body_h)
+    for line in note_lines:
+        draw.text((cx, cy), line, font=F_NOTE, fill=DIM)
+        cy += 24
+    y = end_y
+
+    # ---------- BASE · LOCKED ----------
+    body_h = section_body_rows(5)
+    cx, cy, cw, end_y = draw_section(draw, x, y, inner_w, ACCENT_BASE, "Base · locked", body_h)
+    cy = draw_kv_row(draw, cx, cy, "Sampler",   "euler",                        key_w)
+    cy = draw_kv_row(draw, cx, cy, "CFG",       "1.0",                          key_w)
+    cy = draw_kv_row(draw, cx, cy, "Seed",      f"{data['seed']} (fixed)",       key_w)
+    cy = draw_kv_row(draw, cx, cy, "epsilon",   data["epsilon"],                 key_w)
+    cy = draw_kv_row(draw, cx, cy, "Audio src", "model-gen"
+                    if not data["use_custom_audio"] else "custom",               key_w)
+    y = end_y
+
+    # ---------- BASE · SCENE ----------
+    seg_rows = min(len(data["segments"]), 6)
+    body_h = section_body_rows(2 + seg_rows, extra=4)
+    cx, cy, cw, end_y = draw_section(draw, x, y, inner_w, ACCENT_BASE, "Base · scene", body_h)
+    cy = draw_kv_row(draw, cx, cy, "Duration",
+                    f"{data['dur_frames']} f · {data['dur_seconds']} s @ {data['fps']} fps", key_w)
+    cy = draw_kv_row(draw, cx, cy, "Segments",
+                    f"{len(data['segments'])} × {data['seg_lengths'][0] if data['seg_lengths'] else '?'} f", key_w)
+    for i, seg in enumerate(data["segments"][:seg_rows]):
+        start_s = seg.get("start", 0) / data["fps"]
+        end_s = (seg.get("start", 0) + seg.get("length", 0)) / data["fps"]
+        has_prompt = "[x]" if seg.get("prompt") else "[ ]"
+        has_audio  = "[x]" if "Audio:" in (seg.get("prompt") or "") else "[ ]"
+        has_kf     = "[x]" if seg.get("imageFile") else "[ ]"
+        all_set = (has_prompt == has_audio == has_kf == "[x]")
+        fill_col = ACCENT_OUT if all_set else TEXT
+        draw.text((cx, cy), f"{i+1})", font=F_MONO, fill=ACCENT_BASE)
+        draw.text((cx + 32, cy), f"{start_s:.0f}-{end_s:.0f}s", font=F_MONO, fill=DIM)
+        draw.text((cx + 110, cy), f"P{has_prompt}  A{has_audio}  K{has_kf}",
+                  font=F_MONO, fill=fill_col)
+        cy += 26
+    y = end_y
+
+    # ---------- POST-RENDER ----------
+    feedback_text = data["feedback"] or "(add observations)"
+    feedback_lines = wrap_text(feedback_text, 42)[:5]
+    body_h = (
+        section_body_rows(2)              # render time + output
+        + 8                                # spacer
+        + 20                               # FEEDBACK sublabel
+        + max(24, 22 * len(feedback_lines))
+        + 14                               # spacer before outcome
+        + 20                               # OUTCOME sublabel
+        + 26                               # outcome scores row
+    )
+    cx, cy, cw, end_y = draw_section(draw, x, y, inner_w, ACCENT_OUT, "Post-render", body_h)
+    cy = draw_kv_row(draw, cx, cy, "Render time", data.get("render_duration", "?"), key_w)
+    cy = draw_kv_row(draw, cx, cy, "Output",      data.get("render_output", "?")[:36], key_w)
+    cy += 8
+
+    # FEEDBACK sublabel + body
+    draw.text((cx, cy), "FEEDBACK", font=F_TAG, fill=ACCENT_OUT)
+    cy += 20
+    for line in feedback_lines:
+        draw.text((cx, cy), line, font=F_NOTE, fill=DIM)
+        cy += 22
+    cy += 6
+
+    # OUTCOME sublabel + scores (auto-filled from FEEDBACK parsing)
+    draw.text((cx, cy), "OUTCOME", font=F_TAG, fill=ACCENT_OUT)
+    cy += 20
+    s = data.get("scores", {}) or {}
+    def _s(v): return f"{v}/5" if v is not None else "?/5"
+    draw.text((cx, cy),
+              f"Motion {_s(s.get('motion'))}     Sync {_s(s.get('sync'))}     Sharp {_s(s.get('sharp'))}",
+              font=F_MONO, fill=TEXT)
+    y = end_y
+
+    # ---------- final crop ----------
+    final_h = y + PAD_BOTTOM + inset
+    final = Image.new("RGB", (W, final_h), BG_OUTER)
+    draw2 = ImageDraw.Draw(final)
+    draw2.rounded_rectangle(
+        [inset, inset, W - inset, final_h - inset],
+        radius=RADIUS, fill=BG_CARD, outline=BORDER, width=1,
+    )
+    content = img.crop((inset + 1, inset + 1, W - inset - 1, final_h - inset - 1))
+    final.paste(content, (inset + 1, inset + 1))
+    final.save(out_path)
+    print(f"wrote {out_path} ({W}×{final_h})")
+
+# ---------- CLI ----------
+def _autodiscover_json() -> Path:
+    """Find the newest *.json in $KOLOOK_AUTOMATIONS_WORK_DIR. Fails clearly."""
+    folder = os.environ.get("KOLOOK_AUTOMATIONS_WORK_DIR", "").strip()
+    if not folder:
+        raise SystemExit(
+            "KOLOOK_AUTOMATIONS_WORK_DIR not set. Add it to `.env` (see `.env.example`) "
+            "or pass the JSON path explicitly: `make_card.py <workflow.json>`."
+        )
+    p = Path(folder)
+    if not p.is_dir():
+        raise SystemExit(f"KOLOOK_AUTOMATIONS_WORK_DIR does not exist on disk: {p}")
+    candidates = sorted(
+        (j for j in p.glob("*.json") if not _is_loop_output(j)),
+        key=lambda x: x.stat().st_mtime,
+        reverse=True,
+    )
+    if not candidates:
+        raise SystemExit(f"No *.json files found in {p}. Export a workflow from ComfyUI first.")
+    return candidates[0]
+
+
+def main():
+    if len(sys.argv) >= 2:
+        wf_path = Path(sys.argv[1])
+    else:
+        wf_path = _autodiscover_json()
+        print(f"auto-discovered: {wf_path}")
+    wf = load_workflow(wf_path)
+    data = extract(wf)
+    data["json_name"] = wf_path.name
+    data["json_stem"] = wf_path.stem
+
+    # Output folder priority (first existing wins):
+    #   1. Working_Folder_PATH Text Multiline inside the workflow JSON.
+    #   2. KOLOOK_AUTOMATIONS_WORK_DIR env var (from .env).
+    #   3. The JSON's own parent directory.
+    candidates = []
+    wf_folder = data.get("work_folder_from_wf") or ""
+    if wf_folder:
+        candidates.append(("Working_Folder_PATH node", Path(wf_folder)))
+    env_folder = os.environ.get("KOLOOK_AUTOMATIONS_WORK_DIR", "").strip()
+    if env_folder:
+        candidates.append(("KOLOOK_AUTOMATIONS_WORK_DIR", Path(env_folder)))
+    candidates.append(("JSON parent directory", wf_path.parent))
+
+    folder = None
+    for label, p in candidates:
+        try:
+            p = p.resolve()
+        except Exception:
+            continue
+        if p.is_dir():
+            folder = p
+            break
+    if folder is None:
+        # Last-resort fallback — use the unresolved JSON parent.
+        folder = wf_path.parent
+
+    # Output path: stable filename in the _AI subfolder of the working folder.
+    # Keeps managed artifacts (card.png + iterations.md) separated from user
+    # content (JSONs, MP4s) so the maintainer can wipe one without the other.
+    if len(sys.argv) > 2:
+        out_path = Path(sys.argv[2])
+    else:
+        ai_dir = folder / AI_SUBDIR
+        ai_dir.mkdir(exist_ok=True)
+        out_path = ai_dir / CARD_NAME
+    video, vmtime = find_newest_video(folder)
+    # Render duration priority:
+    #   1. ComfyUI's own `Prompt executed in X` log line — authoritative
+    #      wall-time for the model run. Skips trivial follow-up prompts.
+    #   2. EXR sequence first-to-last-frame span.
+    #   3. JSON-vs-MP4 mtime delta (last resort).
+    # Disk mtimes alone are unreliable: ComfyUI writes JSON + MP4 together
+    # at end-of-render, and the maintainer often assembles MP4s separately.
+    json_mtime = wf_path.stat().st_mtime
+    log_path = find_comfyui_log_path()
+    log_duration = render_time_from_log(log_path) if log_path else None
+    if log_duration:
+        data["render_duration"] = fmt_duration(log_duration) + " (Comfy log)"
+        data["render_log_path"] = str(log_path)
+    else:
+        exr_span, exr_version = exr_sequence_duration(folder)
+        if exr_span is not None and exr_span > 0:
+            suffix = f" ({exr_version})" if exr_version else ""
+            data["render_duration"] = fmt_duration(exr_span) + suffix
+        elif video is not None:
+            # Fall back to MP4 mtime delta only if no EXRs are present.
+            same_stem = video.stem.startswith(wf_path.stem) or wf_path.stem.startswith(video.stem)
+            delta = vmtime - json_mtime
+            if same_stem:
+                data["render_duration"] = "—"
+            elif delta >= 0:
+                data["render_duration"] = fmt_duration(delta)
+            else:
+                data["render_duration"] = "pending"
+        else:
+            data["render_duration"] = "pending"
+
+    data["render_output"] = video.name if video is not None else "(no video yet)"
+
+    # run_label: prefer v01/v04 style, else fall back to ComfyUI sequence number
+    stem = wf_path.stem
+    m = re.search(r"(?:^|[_\-])v(\d{1,4})(?:[_\-]|$)", stem)
+    if m:
+        data["run_label"] = f"v{m.group(1)}"
+    else:
+        m = re.search(r"_(\d{4,6})(?:_|$)", stem)
+        data["run_label"] = f"#{int(m.group(1))}" if m else "?"
+
+    render(data, out_path)
+    log_iteration(folder, wf_path, data)
+
+if __name__ == "__main__":
+    main()

ComfyUI/custom_nodes/koolook/scripts/make_card_audio.py

@@ -0,0 +1,831 @@
+#!/usr/bin/env python3
+"""
+Audio-lipsync card renderer — vertical PIL card scoped to the
+``docs/automations/LTX-2.3/audio-lipsync/`` iteration loop.
+
+Sibling to ``scripts/make_card.py`` (base-1step). Shares palette,
+font fallback chain, and section primitives so the two families read
+as a set, but the data sources are deliberately narrower:
+
+Two — and only two — source families feed this card:
+
+  1. The five ``Text Multiline`` nodes tracked by the loop config
+     (name / relay_overrides / overlay - info / overlay - feedback /
+     working_folder).
+  2. The active ``LTXDirector`` node's own widget values and
+     input-socket wiring (Koolook for modified runs, upstream original
+     for A/B comparison; epsilon, frame_rate, timeline_data segments +
+     audioSegments, use_custom_audio toggle, audio_vae link state).
+
+Notably absent: BasicScheduler / KSamplerSelect / RandomNoise /
+CFGGuider widget scrapes, ``_dev_build.json`` fork-state, ``git status``
+output. Those don't define what this loop sweeps. Adding them would
+push the card into showing values the maintainer's curated multiline
+notes don't claim to summarise.
+
+Card sections (top to bottom):
+
+  HEADER            run-NNN — {name} · date · job · workflow filename
+  KNOB STATE        relay_overrides (the per-render knob)
+  BASE / RUN        source workflow · copied-from workflow · working folder
+  DIRECTOR READINGS Director · pin tag · epsilon · Audio src
+  SEGMENTS          segment list with time ranges + coverage rows
+  POST-RENDER       feedback body + outcome scores
+
+Two entry points:
+
+1. From loop_audio.py at end-of-snapshot:
+
+       from scripts.make_card_audio import render_audio_card
+       render_audio_card(state, run_dir / "card.png")
+
+2. Standalone, against an existing run folder (re-render after a
+   layout tweak):
+
+       python scripts/make_card_audio.py <run_dir>
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from PIL import Image, ImageDraw, ImageFont
+from PIL.PngImagePlugin import PngInfo
+
+
+# --------------------------------------------------------------------------
+# Palette + geometry — kept in lockstep with scripts/make_card.py.
+# --------------------------------------------------------------------------
+
+W            = 540
+PAD_X        = 28
+PAD_TOP      = 28
+PAD_BOTTOM   = 28
+BG_OUTER     = (14, 14, 14)
+BG_CARD      = (21, 21, 21)
+BG_SECTION   = (26, 26, 31)
+BORDER       = (48, 47, 47)
+TEXT         = (249, 250, 251)
+MUTED        = (143, 149, 156)
+DIM          = (200, 204, 209)
+ACCENT_RUN   = (255, 184, 77)    # amber  — per-render knob state
+ACCENT_BASE  = (109, 180, 255)   # sky    — locked / scene
+ACCENT_OUT   = (123, 207, 128)   # green  — post-render outcome
+NOTE_BG      = (12, 12, 12)
+RADIUS       = 14
+SECTION_RADIUS = 8
+
+
+# --------------------------------------------------------------------------
+# Fonts — same fallback chain + same sizes as scripts/make_card.py.
+# --------------------------------------------------------------------------
+
+WIN_FONTS = Path(r"C:/Windows/Fonts")
+
+
+def _load_font(filenames: list[str], size: int) -> ImageFont.FreeTypeFont:
+    for fn in filenames:
+        for p in (WIN_FONTS / fn, Path("/Library/Fonts") / fn,
+                  Path("/usr/share/fonts") / fn):
+            if p.exists():
+                try:
+                    return ImageFont.truetype(str(p), size)
+                except OSError:
+                    continue
+    return ImageFont.load_default()
+
+
+F_TITLE   = _load_font(["segoeuib.ttf", "Arial Bold.ttf"], 28)
+F_SUB     = _load_font(["segoeui.ttf",  "Arial.ttf"],      17)
+F_H2      = _load_font(["segoeuib.ttf", "Arial Bold.ttf"], 16)
+F_TAG     = _load_font(["segoeuib.ttf", "Arial Bold.ttf"], 12)
+F_SECTION = _load_font(["segoeuib.ttf", "Arial Bold.ttf"], 17)
+F_MONO    = _load_font(["consola.ttf",  "Menlo.ttc", "DejaVuSansMono.ttf"], 19)
+F_NOTE    = _load_font(["segoeuii.ttf", "Arial Italic.ttf"], 18)
+
+
+# --------------------------------------------------------------------------
+# Drawing primitives — copied 1:1 from scripts/make_card.py.
+# --------------------------------------------------------------------------
+
+
+def _wrap_text(text: str, max_chars: int, keep_blank_lines: bool = False) -> list[str]:
+    out: list[str] = []
+    for raw_line in text.split("\n"):
+        if not raw_line.strip():
+            if keep_blank_lines:
+                out.append("")
+            continue
+        words = raw_line.split()
+        cur = ""
+        for w in words:
+            if len(cur) + len(w) + 1 <= max_chars:
+                cur = (cur + " " + w).strip()
+            else:
+                if cur:
+                    out.append(cur)
+                cur = w
+        if cur:
+            out.append(cur)
+    return out
+
+
+def _draw_kv_row(
+    draw: ImageDraw.ImageDraw, x: int, y: int,
+    key: str, val: str, key_w: int, max_w: int | None = None,
+) -> int:
+    draw.text((x, y), key, font=F_MONO, fill=MUTED)
+    value = str(val)
+    if max_w is not None:
+        value = _trim_middle_to_width(draw, value, F_MONO, max_w)
+    draw.text((x + key_w, y), value, font=F_MONO, fill=TEXT)
+    return y + 26
+
+
+def _trim_to_width(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    font: ImageFont.FreeTypeFont,
+    max_w: int,
+) -> str:
+    if draw.textbbox((0, 0), text, font=font)[2] <= max_w:
+        return text
+    ellipsis = "..."
+    lo = 0
+    hi = len(text)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        candidate = text[:mid].rstrip() + ellipsis
+        if draw.textbbox((0, 0), candidate, font=font)[2] <= max_w:
+            lo = mid
+        else:
+            hi = mid - 1
+    return text[:lo].rstrip() + ellipsis
+
+
+def _trim_middle_to_width(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    font: ImageFont.FreeTypeFont,
+    max_w: int,
+) -> str:
+    if draw.textbbox((0, 0), text, font=font)[2] <= max_w:
+        return text
+    ellipsis = "..."
+    keep_tail = min(18, max(8, len(text) // 3))
+    tail = text[-keep_tail:]
+    lo = 0
+    hi = max(0, len(text) - keep_tail)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        candidate = text[:mid].rstrip("_- ") + ellipsis + tail
+        if draw.textbbox((0, 0), candidate, font=font)[2] <= max_w:
+            lo = mid
+        else:
+            hi = mid - 1
+    return text[:lo].rstrip("_- ") + ellipsis + tail
+
+
+def _draw_text_box(
+    draw: ImageDraw.ImageDraw, x: int, y: int, width: int,
+    label: str, content: str, accent: tuple[int, int, int],
+    max_lines: int = 4, char_per_line: int = 42,
+    keep_blank_lines: bool = False,
+) -> int:
+    """Left-accented note block — colored 4-px bar on the left, label
+    in the accent colour, italic body text."""
+    lines = _wrap_text(content, char_per_line, keep_blank_lines=keep_blank_lines)[:max_lines]
+    box_h = 28 + 22 * max(1, len(lines)) + 14
+    draw.rounded_rectangle(
+        [x, y, x + width, y + box_h],
+        radius=SECTION_RADIUS, fill=BG_SECTION, outline=BORDER, width=1,
+    )
+    draw.text((x + 12, y + 8), label.upper(), font=F_H2, fill=accent)
+    line_y = y + 36
+    for line in lines:
+        draw.text((x + 12, line_y), line, font=F_NOTE, fill=DIM)
+        line_y += 22
+    return y + box_h + 10
+
+
+def _draw_header_box(
+    draw: ImageDraw.ImageDraw,
+    x: int,
+    y: int,
+    width: int,
+    run_line: str,
+    module_name: str,
+    name_line: str,
+) -> int:
+    box_h = 118
+    draw.rounded_rectangle(
+        [x, y, x + width, y + box_h],
+        radius=SECTION_RADIUS, fill=BG_SECTION, outline=BORDER, width=1,
+    )
+    tx = x + 14
+    ty = y + 14
+    run_id, _, run_date = run_line.partition(" - ")
+    draw.text((tx, ty), run_id, font=F_H2, fill=ACCENT_RUN)
+    run_w = draw.textbbox((0, 0), run_id + "  ", font=F_H2)[2]
+    if run_date:
+        draw.text((tx + run_w, ty), run_date, font=F_SUB, fill=MUTED)
+    ty += 27
+    module_label = "Module:"
+    draw.text((tx, ty), module_label, font=F_SUB, fill=ACCENT_BASE)
+    label_w = draw.textbbox((0, 0), module_label + " ", font=F_SUB)[2]
+    draw.text((tx + label_w, ty), module_name, font=F_SUB, fill=TEXT)
+    ty += 31
+    draw.text((tx, ty), name_line, font=F_TITLE, fill=TEXT)
+    return y + box_h + 10
+
+
+def _draw_section(
+    draw: ImageDraw.ImageDraw, x: int, y: int, width: int,
+    accent: tuple[int, int, int], label: str, body_h: int,
+    bg: tuple[int, int, int] = BG_SECTION,
+    border: tuple[int, int, int] = BORDER,
+) -> tuple[int, int, int, int]:
+    """Subtle panel with an accent-coloured uppercase label at the top.
+    Returns (content_x, content_y, content_w, end_y) so the caller
+    stacks rows directly underneath."""
+    HEADER_H = 36
+    section_h = HEADER_H + body_h + 14
+    draw.rounded_rectangle(
+        [x, y, x + width, y + section_h],
+        radius=SECTION_RADIUS, fill=bg, outline=border, width=1,
+    )
+    draw.text((x + 14, y + 10), label.upper(), font=F_SECTION, fill=accent)
+    return x + 14, y + HEADER_H, width - 28, y + section_h + 10
+
+
+def _section_body_rows(num_rows: int, extra: int = 0) -> int:
+    return num_rows * 26 + extra
+
+
+def _draw_score_chip(
+    draw: ImageDraw.ImageDraw,
+    x: int,
+    y: int,
+    width: int,
+    label: str,
+    value: Any,
+) -> None:
+    draw.rounded_rectangle(
+        [x, y, x + width, y + 50],
+        radius=6, fill=BG_CARD, outline=BORDER, width=1,
+    )
+    label_w = draw.textbbox((0, 0), label, font=F_TAG)[2]
+    draw.text((x + (width - label_w) // 2, y + 7), label, font=F_TAG, fill=ACCENT_OUT)
+    score = f"{value}/5" if value is not None else "?/5"
+    score_w = draw.textbbox((0, 0), score, font=F_MONO)[2]
+    draw.text((x + (width - score_w) // 2, y + 24), score, font=F_MONO, fill=TEXT)
+
+
+# --------------------------------------------------------------------------
+# Renderer — pure state-in / PNG-out. The ``state`` dict is built by
+# loop_audio._build_state_for_card. All values come from the two source
+# families documented at the top of this module.
+# --------------------------------------------------------------------------
+
+
+# Shared helpers live in loop_audio so the renderer and extractor agree
+# byte-for-byte on path-wrapping rules and audio-overlap geometry.
+# Importing here keeps the standalone CLI working (it adds scripts/ to
+# sys.path before invoking render_audio_card).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from loop_audio import (  # type: ignore[import-not-found]  # noqa: E402
+    copy_delivery_card,
+    video_segment_has_audio,
+    metadata_numeric_widget,
+    parse_dev_sync_audio_line,
+    repo_metadata_from_build,
+    render_notes_md,
+    scrub_path_for_metadata,
+    wrap_path,
+)
+
+
+def _audio_source_label(audio_src: str) -> str:
+    labels = {
+        "custom": "custom audio ON",
+        "custom (empty)": "custom audio ON (empty)",
+        "model-gen": "model audio",
+        "off (no VAE)": "audio OFF",
+        "(no director)": "no director",
+    }
+    return labels.get(audio_src, audio_src)
+
+
+def _read_existing_metadata(run_dir: Path) -> dict[str, Any]:
+    path = run_dir / "metadata.json"
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _preserved_run_date(run_dir: Path, existing_metadata: dict[str, Any]) -> str:
+    existing_date = (existing_metadata.get("run") or {}).get("date", "")
+    if isinstance(existing_date, str) and existing_date.strip():
+        return existing_date.strip()
+    wf = next(run_dir.glob("run*_workflow.json"), None)
+    if wf is not None:
+        try:
+            from datetime import datetime
+            return datetime.fromtimestamp(wf.stat().st_mtime).date().isoformat()
+        except OSError:
+            pass
+    from datetime import date
+    return date.today().isoformat()
+
+
+def render_audio_card(state: dict[str, Any], out_path: Path) -> Path:
+    """Render the audio-lipsync card PNG. ``state`` keys consumed:
+
+      run_number, run_label, date, workflow_name
+      name, relay_overrides_raw, info_body, feedback_lines, scores,
+      work_folder, output_folder, output_name
+      director_variant, director_flavor, audio_src, epsilon, frame_rate,
+      segments, audio_segments, segment_prompt_mode
+    """
+    name              = state.get("name") or "(unnamed)"
+    relay             = (state.get("relay_overrides_raw") or "").strip()
+    info_body         = (state.get("info_body") or "").rstrip()
+    feedback_lines    = state.get("feedback_lines") or []
+    scores            = state.get("scores") or {}
+    work_folder       = state.get("work_folder") or ""
+    output_folder     = state.get("output_folder") or ""
+    output_name       = state.get("output_name") or ""
+    metadata          = state.get("metadata") or {}
+    director_variant  = state.get("director_variant") or "(missing)"
+    director_flavor   = state.get("director_flavor") or director_variant
+    director_pin_tag  = state.get("director_pin_tag") or (
+        (metadata.get("director") or {}).get("pin_tag", "")
+    )
+    audio_src         = state.get("audio_src") or "?"
+    epsilon           = state.get("epsilon")
+    fps               = state.get("frame_rate")
+    segments          = state.get("segments") or []
+    audio_segs        = state.get("audio_segments") or []
+    prompt_mode       = state.get("segment_prompt_mode") or "none"
+    run_meta          = metadata.get("run") or {}
+    # NOTE: duration_frames / duration_seconds intentionally not read here
+    # — the dropped "Duration" row used them; segment time ranges convey
+    # the same info now. They stay in the state dict for notes.md.
+
+    canvas_h = 2400
+    img = Image.new("RGB", (W, canvas_h), BG_OUTER)
+    draw = ImageDraw.Draw(img)
+    inset = 18
+    draw.rounded_rectangle(
+        [inset, inset, W - inset, canvas_h - inset],
+        radius=RADIUS, fill=BG_CARD, outline=BORDER, width=1,
+    )
+    x = inset + PAD_X
+    y = inset + PAD_TOP
+    inner_w = W - 2 * inset - 2 * PAD_X
+    # Wider key column so multi-word labels (relay_overrides, Working
+    # folder) don't collide with their values.
+    key_w = 178
+
+    # ----- HEADER -----
+    module_name = state.get("module_name") or "audio-lipsync"
+    run_line = f"Run {state['run_number']:03d} - {state['date']}"
+    name_line = _trim_to_width(draw, str(name), F_TITLE, inner_w)
+    y = _draw_header_box(draw, x, y, inner_w, run_line, module_name, name_line)
+
+    # ----- BASE / RUN -----
+    path_lines = wrap_path(work_folder, max_chars=40) if work_folder else []
+    output_lines = wrap_path(output_folder, max_chars=40) if output_folder else []
+    body_h = 0
+    if output_name:
+        body_h += 52
+    source_workflow = state.get("source_workflow_name") or run_meta.get("workflow")
+    if source_workflow:
+        source_workflow = str(Path(str(source_workflow)).with_suffix(""))
+    source_workflow_lines = (
+        wrap_path(str(source_workflow), max_chars=40) if source_workflow else []
+    )
+    if source_workflow_lines:
+        body_h += 26 + 26 * len(source_workflow_lines) + 4
+    if path_lines:
+        body_h += 26 + 26 * len(path_lines) + 4
+    if output_lines:
+        body_h += 26 + 26 * len(output_lines) + 4
+    cx, cy, cw, end_y = _draw_section(
+        draw, x, y, inner_w, ACCENT_BASE, "Base / run", body_h,
+    )
+    if source_workflow_lines:
+        draw.text((cx, cy), "Copied from", font=F_MONO, fill=MUTED)
+        cy += 26
+        for line in source_workflow_lines:
+            draw.text((cx + 12, cy), line, font=F_MONO, fill=TEXT)
+            cy += 26
+        cy += 4
+    if output_name:
+        draw.text((cx, cy), "Output name", font=F_MONO, fill=MUTED)
+        cy += 26
+        draw.text(
+            (cx + 12, cy),
+            _trim_middle_to_width(draw, output_name, F_MONO, cw - 12),
+            font=F_MONO,
+            fill=TEXT,
+        )
+        cy += 26
+    if path_lines:
+        draw.text((cx, cy), "Working folder", font=F_MONO, fill=MUTED)
+        cy += 26
+        for line in path_lines:
+            draw.text((cx + 12, cy), line, font=F_MONO, fill=TEXT)
+            cy += 26
+    if output_lines:
+        draw.text((cx, cy), "Output folder", font=F_MONO, fill=MUTED)
+        cy += 26
+        for line in output_lines:
+            draw.text((cx + 12, cy), line, font=F_MONO, fill=TEXT)
+            cy += 26
+    y = end_y
+
+    # ----- DIRECTOR READINGS -----
+    seg_rows = min(len(segments), 6)
+    indent_seg = 18
+    director_rows = 5 if epsilon is not None else 4
+    body_h = 26 * director_rows + 26 * 3 + 26 * seg_rows + 8 + 26 * 3 + 4
+    cx, cy, cw, end_y = _draw_section(
+        draw, x, y, inner_w, ACCENT_BASE, "Director readings", body_h,
+    )
+    cy = _draw_kv_row(
+        draw, cx, cy, "Director", str(director_flavor),
+        key_w, cw - key_w,
+    )
+    cy = _draw_kv_row(
+        draw, cx, cy, "Pin tag",
+        _trim_middle_to_width(draw, str(director_pin_tag), F_MONO, cw - key_w),
+        key_w, cw - key_w,
+    )
+    if epsilon is not None:
+        cy = _draw_kv_row(draw, cx, cy, "epsilon", str(epsilon), key_w)
+    cy = _draw_kv_row(draw, cx, cy, "Audio", _audio_source_label(audio_src), key_w)
+    cy = _draw_kv_row(draw, cx, cy, "Frame rate", str(fps or "?"), key_w)
+    cy = _draw_kv_row(draw, cx, cy, "Image segments", f"({len(segments)})", key_w)
+    cy = _draw_kv_row(draw, cx, cy, "Audio segments", f"({len(audio_segs)})", key_w)
+    cy = _draw_kv_row(draw, cx, cy, "Prompt mode", prompt_mode, key_w)
+
+    visible = segments[:seg_rows]
+    all_have_prompt = bool(visible) and all((s.get("prompt") or "") for s in visible)
+    all_have_audio = bool(visible) and all(
+        video_segment_has_audio(s, audio_segs) for s in visible
+    )
+    all_have_keyframe = bool(visible) and all(s.get("imageFile") for s in visible)
+
+    for i, seg in enumerate(visible):
+        start = seg.get("start", 0)
+        length = seg.get("length", 0)
+        prompt = seg.get("prompt") or ""
+        has_p = bool(prompt)
+        has_a = video_segment_has_audio(seg, audio_segs)
+        has_k = bool(seg.get("imageFile"))
+        header_col = ACCENT_OUT if (has_p and has_a and has_k) else ACCENT_BASE
+        if fps:
+            start_s = start / fps
+            end_s = (start + length) / fps
+            header = f"{i+1}) {start_s:.0f} to {end_s:.0f} seconds"
+        else:
+            header = f"{i+1}) frames {start}-{start + length} (no fps)"
+        draw.text((cx + indent_seg, cy), header, font=F_MONO, fill=header_col)
+        cy += 26
+    cy += 8
+
+    for label, present in (
+        ("Prompt", all_have_prompt),
+        ("Audio", all_have_audio),
+        ("Keyframe", all_have_keyframe),
+    ):
+        mark = "[x]" if present else "[ ]"
+        mark_col = ACCENT_OUT if present else MUTED
+        draw.text((cx, cy), label, font=F_MONO, fill=MUTED)
+        draw.text((cx + key_w, cy), mark, font=F_MONO, fill=mark_col)
+        cy += 26
+    y = end_y
+
+    # ----- AMBER NOTES -----
+    relay_disp = relay if relay else "(empty -> defaults)"
+    if relay and director_variant == "LTXDirector":
+        relay_disp = f"{relay}\n\nINERT: active Director is upstream LTXDirector."
+    y = _draw_text_box(
+        draw, x, y, inner_w, "Knob state",
+        relay_disp, ACCENT_RUN, max_lines=6, char_per_line=42,
+        keep_blank_lines=True,
+    )
+    note_text = info_body if info_body.strip() else "(no note this render)"
+    y = _draw_text_box(
+        draw, x, y, inner_w, "Base notes",
+        note_text, ACCENT_RUN, max_lines=18, char_per_line=42,
+        keep_blank_lines=True,
+    )
+
+    # ----- POST-RENDER (green) — FEEDBACK + OUTCOME -----
+    feedback_text = "\n".join(feedback_lines) if feedback_lines else "(no feedback)"
+    fb_lines = _wrap_text(feedback_text, 42)[:6]
+    body_h = (20 + max(24, 22 * len(fb_lines)) + 14 + 20 + 50)
+    cx, cy, cw, end_y = _draw_section(
+        draw, x, y, inner_w, ACCENT_OUT, "Post-render", body_h,
+    )
+    draw.text((cx, cy), "FEEDBACK", font=F_TAG, fill=ACCENT_OUT)
+    cy += 20
+    for line in fb_lines:
+        draw.text((cx, cy), line, font=F_NOTE, fill=DIM)
+        cy += 22
+    cy += 6
+    draw.text((cx, cy), "OUTCOME", font=F_TAG, fill=ACCENT_OUT)
+    cy += 20
+
+    gap = 8
+    chip_w = (cw - 2 * gap) // 3
+    for idx, (label, key) in enumerate((
+        ("Motion", "motion"),
+        ("Sync", "sync"),
+        ("Sharp", "sharp"),
+    )):
+        _draw_score_chip(
+            draw, cx + idx * (chip_w + gap), cy,
+            chip_w, label, scores.get(key),
+        )
+    y = end_y
+
+    # ----- crop to actual content + save -----
+    final_h = y + PAD_BOTTOM + inset
+    img = img.crop((0, 0, W, final_h))
+    out_draw = ImageDraw.Draw(img)
+    out_draw.rounded_rectangle(
+        [inset, inset, W - inset, final_h - inset],
+        radius=RADIUS, outline=BORDER, width=1,
+    )
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    pnginfo = None
+    metadata = state.get("metadata")
+    if metadata:
+        pnginfo = PngInfo()
+        pnginfo.add_text(
+            "koolook_audio_loop",
+            json.dumps(metadata, ensure_ascii=False, sort_keys=True),
+        )
+    img.save(str(out_path), pnginfo=pnginfo)
+    return out_path
+
+
+# --------------------------------------------------------------------------
+# Standalone CLI — re-render a card from an existing run folder.
+# --------------------------------------------------------------------------
+
+
+def _rebuild_state_from_run_dir(run_dir: Path) -> dict[str, Any]:
+    """Reconstruct the loop_audio state dict from an on-disk run
+    folder. Reads the run's frozen runNNN_workflow.json and walks it through
+    the same extraction helpers loop_audio.py uses live."""
+    from loop_audio import (  # type: ignore[import-not-found]
+        active_relay_overrides,
+        derive_audio_state, detect_upstream_whatdreamscost_version,
+        director_flavor, director_pin_tag, director_type, director_widget,
+        expected_output_tracking, extract_director, extract_multilines,
+        extract_setup_variables, find_dotenv,
+        first_multiline, load_config, load_dotenv,
+        parse_feedback, parse_timeline, pick_existing_path,
+        segment_prompt_mode,
+        DEFAULT_CONFIG_PATH,
+    )
+
+    name_parts = run_dir.name.split("_", 1)
+    m = re.match(r"run-(\d+)$", name_parts[0])
+    nnn = int(m.group(1)) if m else 0
+    label = name_parts[1] if len(name_parts) > 1 else ""
+    tagged_workflow = run_dir / f"run{nnn:03d}_workflow.json"
+    wf_path = tagged_workflow if tagged_workflow.is_file() else run_dir / "workflow.json"
+    if not wf_path.is_file():
+        print(f"missing run workflow JSON in {run_dir}", file=sys.stderr)
+        sys.exit(2)
+    with wf_path.open(encoding="utf-8-sig") as f:
+        wf = json.load(f)
+    nodes = wf.get("nodes") or []
+
+    # Load env so any env-var lookups inside the helpers (none right
+    # now, but a defensive match for make_card.py's pattern) work.
+    env_file = find_dotenv()
+    if env_file is not None:
+        load_dotenv(env_file)
+
+    cfg = load_config(DEFAULT_CONFIG_PATH)
+    multilines = extract_multilines(nodes, cfg["tracked_multilines"])
+    setup_variables = extract_setup_variables(
+        nodes, cfg.get("tracked_setup_variables", {})
+    )
+    output_tracking = expected_output_tracking(nodes, multilines, setup_variables)
+    director_node = extract_director(nodes, wf.get("links") or [])
+    timeline = parse_timeline(director_node)
+    audio_src = derive_audio_state(director_node, timeline)
+    relay_overrides_raw = active_relay_overrides(
+        nodes, wf.get("links") or [], director_node
+    )
+    active_multilines = dict(multilines)
+    active_multilines["relay_overrides"] = [relay_overrides_raw]
+    upstream_whatdreamscost_version = detect_upstream_whatdreamscost_version()
+    pin_tag = director_pin_tag(director_node, upstream_whatdreamscost_version)
+    existing_metadata = _read_existing_metadata(run_dir)
+    run_date = _preserved_run_date(run_dir, existing_metadata)
+    scores, feedback_lines = parse_feedback(
+        first_multiline(multilines, "overlay - feedback")
+    )
+    patch_meta: dict[str, str] = {}
+    patch_path = run_dir / "patch_state.txt"
+    if patch_path.is_file():
+        for line in patch_path.read_text(encoding="utf-8").splitlines():
+            if ":" not in line:
+                continue
+            key, value = line.split(":", 1)
+            patch_meta[key.strip()] = value.strip()
+    last_dev_sync_audio, last_dev_sync_at = parse_dev_sync_audio_line(
+        patch_meta.get("Last dev-sync-audio", "")
+    )
+    repo_build = {
+        "commit": last_dev_sync_audio,
+        "synced_at": last_dev_sync_at,
+        "scope": patch_meta.get("Sync scope tag", ""),
+        "worktree": patch_meta.get("Sync worktree", ""),
+    }
+    source_workflow_name = ""
+    notes_path = run_dir / "notes.md"
+    if notes_path.is_file():
+        for line in notes_path.read_text(encoding="utf-8").splitlines():
+            match = re.match(r"- Setup name:\s+`([^`]+)`", line)
+            if match:
+                source_workflow_name = f"{match.group(1)}.json"
+                break
+
+    workflow_name = wf_path.name
+    state = {
+        "run_number": nnn,
+        "run_label": label,
+        "date": run_date,
+        "workflow_name": workflow_name,
+        "source_workflow_name": source_workflow_name,
+        "name": first_multiline(multilines, "name").strip() or "(unnamed)",
+        "relay_overrides_raw": relay_overrides_raw,
+        "info_body": first_multiline(multilines, "overlay - info").rstrip(),
+        "feedback_lines": feedback_lines,
+        "scores": scores,
+        "work_folder": pick_existing_path(
+            multilines.get("working_folder") or []
+        ),
+        "output_folder": output_tracking.get("folder", ""),
+        "output_name": output_tracking.get("name", ""),
+        "output_tracking": output_tracking,
+        "metadata": {
+            "schema": "koolook.audio_loop.card_metadata.v1",
+            "source": "rebuilt from frozen run folder",
+            "run": {
+                "capture_number": f"{nnn:03d}",
+                "label": label,
+                "date": run_date,
+                "workflow": workflow_name,
+                "source_workflow": source_workflow_name,
+                "archived_workflow": workflow_name,
+                "setup_name": (
+                    Path(source_workflow_name).stem
+                    if source_workflow_name else wf_path.stem
+                ),
+            },
+            "setup": {
+                "base_name": first_multiline(multilines, "name").strip(),
+                "working_folder": scrub_path_for_metadata(output_tracking.get("folder", "")),
+                "input_path_exr": scrub_path_for_metadata(
+                    first_multiline(setup_variables, "input_path_exr")
+                ),
+                "global_version": first_multiline(setup_variables, "version"),
+                "global_run_offset": first_multiline(setup_variables, "run_offset"),
+                "relay_overrides": relay_overrides_raw.strip(),
+            },
+            "output": {
+                **output_tracking,
+                "folder": scrub_path_for_metadata(output_tracking.get("folder", "")),
+            },
+            "director": {
+                "type": director_type(director_node),
+                "flavor": director_flavor(director_node),
+                "pin_tag": pin_tag,
+                "upstream_whatdreamscost_version": upstream_whatdreamscost_version,
+                "audio_src": audio_src,
+                "epsilon": director_widget(director_node, "epsilon"),
+                "duration_frames": director_widget(director_node, "duration_frames"),
+                "duration_seconds": director_widget(director_node, "duration_seconds"),
+                "frame_rate": metadata_numeric_widget(
+                    director_widget(director_node, "frame_rate")
+                ),
+                "segment_prompt_mode": segment_prompt_mode(
+                    timeline.get("segments") or []
+                ),
+                "video_segments": len(timeline.get("segments") or []),
+                "audio_segments": len(timeline.get("audioSegments") or []),
+            },
+            "repo": {
+                **repo_metadata_from_build(
+                    repo_build,
+                    patch_meta.get("Fork dir status", ""),
+                ),
+                "main_sha": patch_meta.get("MAIN SHA", ""),
+            },
+        },
+        "director_node": director_node,
+        "director_variant": director_type(director_node),
+        "director_flavor": director_flavor(director_node),
+        "director_pin_tag": pin_tag,
+        "audio_src": audio_src,
+        "epsilon": director_widget(director_node, "epsilon"),
+        "frame_rate": metadata_numeric_widget(
+            director_widget(director_node, "frame_rate")
+        ),
+        "segments": timeline.get("segments") or [],
+        "audio_segments": timeline.get("audioSegments") or [],
+        "segment_prompt_mode": segment_prompt_mode(
+            timeline.get("segments") or []
+        ),
+    }
+    state["notes_md"] = render_notes_md(
+        nnn,
+        Path(source_workflow_name) if source_workflow_name else wf_path,
+        active_multilines,
+        setup_variables,
+        director_node,
+        timeline,
+        audio_src,
+        state["info_body"],
+        feedback_lines,
+        scores,
+        output_tracking,
+        commit_sha=patch_meta.get("MAIN SHA", ""),
+    )
+    return state
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("run_dir", type=Path)
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument(
+        "--no-delivery",
+        action="store_true",
+        help="Skip copying the rendered card to the external cards folder.",
+    )
+    args = p.parse_args()
+
+    run_dir = args.run_dir.expanduser().resolve()
+    if not run_dir.is_dir():
+        print(f"run folder not found: {run_dir}", file=sys.stderr)
+        return 2
+
+    # sys.path already pointed at scripts/ by the module-level import of
+    # wrap_path/video_segment_has_audio above; no need to repeat it here.
+    state = _rebuild_state_from_run_dir(run_dir)
+
+    out = run_dir / "card.png"
+    if args.dry_run:
+        print(f"(dry-run) would write: {out}")
+        return 0
+    render_audio_card(state, out)
+    metadata_path = run_dir / "metadata.json"
+    notes_path = run_dir / "notes.md"
+    metadata_path.write_text(
+        json.dumps(
+            state.get("metadata") or {},
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        ) + "\n",
+        encoding="utf-8",
+    )
+    notes_path.write_text(state.get("notes_md") or "", encoding="utf-8")
+    if args.no_delivery:
+        delivery_status = "(skipped)"
+    else:
+        delivery_status = copy_delivery_card(
+            out,
+            state.get("output_tracking") or {},
+            state.get("run_number"),
+            overwrite=True,
+        )
+    print(f"wrote: {out}")
+    print(f"wrote: {metadata_path}")
+    print(f"wrote: {notes_path}")
+    print(f"delivered: {delivery_status}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/make_silent_wav.py

@@ -0,0 +1,98 @@
+"""Write a silent WAV file for LTX-2.3 (and other audio-required) graphs.
+
+Usage:
+    python scripts/make_silent_wav.py [outfile] [--seconds N]
+                                      [--rate HZ] [--channels N]
+
+Produces a stereo, 44.1 kHz, 16-bit silent track by default — the same
+waveform format ComfyUI's AUDIO type expects, i.e. what the LTX Director
+generates internally (`torch.zeros((1, 2, samples))` @ 44100). Drop the
+output into ComfyUI's `input/` folder and load it with the stock
+`LoadAudio` node when you need to satisfy a required AUDIO input but have
+no real audio to feed.
+
+Make it at least as long as your clip; LTX will trim/loop to fit.
+
+Examples:
+    # 10s silent.wav in the current folder (defaults)
+    python scripts/make_silent_wav.py
+
+    # 30s, written straight into a ComfyUI input dir
+    python scripts/make_silent_wav.py "C:/ComfyUI/input/silent.wav" --seconds 30
+
+Exit codes:
+    0  File written.
+    2  Bad arguments.
+
+stdlib only, no third-party dependencies.
+"""
+from __future__ import annotations
+import argparse
+import sys
+import wave
+from pathlib import Path
+
+
+def make_silent_wav(
+    path: Path, seconds: float, rate: int, channels: int, sampwidth: int = 2
+) -> int:
+    """Write `seconds` of silence to `path`. Returns the byte count written."""
+    frames = int(round(seconds * rate))
+    data = b"\x00" * (frames * channels * sampwidth)
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(channels)
+        w.setsampwidth(sampwidth)
+        w.setframerate(rate)
+        w.writeframes(data)
+    return len(data)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "outfile",
+        nargs="?",
+        default="silent.wav",
+        help="Output path (default: silent.wav in the current folder).",
+    )
+    parser.add_argument(
+        "--seconds",
+        type=float,
+        default=10.0,
+        help="Duration in seconds; make it >= your clip length (default: 10).",
+    )
+    parser.add_argument(
+        "--rate",
+        type=int,
+        default=44100,
+        help="Sample rate in Hz (default: 44100 — what LTX expects).",
+    )
+    parser.add_argument(
+        "--channels",
+        type=int,
+        default=2,
+        help="Channel count: 2=stereo, 1=mono (default: 2).",
+    )
+    args = parser.parse_args(argv)
+
+    if args.seconds <= 0:
+        parser.error("--seconds must be positive")
+    if args.rate <= 0:
+        parser.error("--rate must be positive")
+    if args.channels not in (1, 2):
+        parser.error("--channels must be 1 or 2")
+
+    out = Path(args.outfile)
+    if out.parent and not out.parent.exists():
+        parser.error(f"output directory does not exist: {out.parent}")
+
+    written = make_silent_wav(out, args.seconds, args.rate, args.channels)
+    print(
+        f"Wrote {out} — {args.seconds:g}s, {args.rate} Hz, "
+        f"{args.channels}ch, 16-bit ({written:,} bytes of silence)."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/run_loop_demo_api_test.py

@@ -0,0 +1,227 @@
+"""Run the loop demo against a local ComfyUI server.
+
+This is a repo-local validation harness for
+`docs/automations/loop-demo/LOOP_demo_pipeline.json`. It submits an API-format version
+of the queue-controller demo graph to a running ComfyUI server and verifies
+that four EXR files are written across four prompt executions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+def _validate_http_url(url: str) -> None:
+    parsed = urllib.parse.urlsplit(str(url or ""))
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise RuntimeError(f"Only http(s) ComfyUI server URLs are allowed: {url!r}")
+
+
+def _post_json(url: str, payload: dict) -> dict:
+    _validate_http_url(url)
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:  # nosec B310
+        return json.load(response)
+
+
+def _get_json(url: str, timeout: float = 15) -> dict:
+    _validate_http_url(url)
+    with urllib.request.urlopen(url, timeout=timeout) as response:  # nosec B310
+        return json.load(response)
+
+
+def _assert_inside(parent: Path, child: Path) -> None:
+    parent = parent.resolve()
+    child = child.resolve()
+    if parent != child and parent not in child.parents:
+        raise RuntimeError(f"Refusing to touch path outside repo: {child}")
+
+
+def _dump_server_debug(server: str) -> None:
+    for endpoint in ("queue", "history?max_items=20"):
+        try:
+            payload = _get_json(f"{server}/{endpoint}", timeout=10)
+        except Exception as exc:
+            print(f"Could not read /{endpoint}: {exc}")
+            continue
+        print(f"/{endpoint}:")
+        print(json.dumps(payload, indent=2)[:8000])
+
+
+def build_prompt(output_base: Path) -> dict:
+    """Build the API prompt equivalent of the current loop demo.
+
+    The canvas workflow contains a ComfyUI subgraph node. The API prompt below
+    flattens that demo subgraph to its current single inner node,
+    `EasyResize_Koolook`, so the prompt can be submitted directly to `/prompt`.
+    """
+    return {
+        "12": {"class_type": "easy int", "inputs": {"value": 4}},
+        "10": {
+            "class_type": "Text Multiline",
+            "inputs": {"text": str(output_base) + "\\"},
+        },
+        "9": {
+            "class_type": "Easy_Pattern",
+            "inputs": {
+                "batch_size": ["12", 0],
+                "width": 512,
+                "height": 512,
+                "bg_color_mode": "Custom",
+                "show_text": True,
+                "text_color_mode": "White",
+                "start_from": 1,
+                "step": 1,
+                "font_size": 256,
+                "position": "center",
+                "zero_pad": 0,
+                "bg_color": "#C71585",
+                "text_color": "#FFFFFF",
+                "prefix": "",
+                "suffix": "",
+            },
+        },
+        "8": {
+            "class_type": "EasyAIPipeline",
+            "inputs": {
+                "shot_duration": 81,
+                "seed_value": 453453453,
+                "instruction": "Place your base folder path in the FIELD below",
+                "base_directory_path": ["10", 0],
+                "extension": ".%04d.exr",
+                "shot_name": "faceLoop",
+                "ai_method": "",
+                "version": "1",
+                "disable_versioning": False,
+                "enable_overwrite": False,
+                "no_subfolders": True,
+            },
+        },
+        "22": {"class_type": "easy int", "inputs": {"value": 0}},
+        "3": {
+            "class_type": "ImageFromBatch",
+            "inputs": {"image": ["9", 0], "batch_index": ["22", 0], "length": 1},
+        },
+        "19": {
+            "class_type": "EasyResize_Koolook",
+            "inputs": {
+                "image": ["3", 0],
+                "base_on": "Width",
+                "base_size": 512,
+                "aspect_ratio": "16:9",
+                "divisible_by": 32,
+                "upscale_method": "nearest-exact",
+                "keep_proportion": "stretch",
+                "crop_position": "center",
+                "pad_color_mode": "Black",
+                "panel_color_mode": "Black",
+                "device": "cpu",
+                "pad_color": "0, 0, 0",
+                "panel_color": "0, 0, 0",
+                "invert_composed_MASK": False,
+            },
+        },
+        "21": {
+            "class_type": "Koolook_LoopStatus",
+            "inputs": {
+                "value": ["19", 0],
+                "index": ["22", 0],
+                "total": ["12", 0],
+                "filepath": ["8", 0],
+                "label": "EXR_SAFE",
+                "auto_queue_next": True,
+                "index_node_id": "22",
+                "server_url": "http://127.0.0.1:8188",
+                "max_auto_queue_depth": 100,
+                "remaining_auto_queue_depth": -1,
+            },
+        },
+        "4": {
+            "class_type": "SaveEXRFrames",
+            "inputs": {
+                "images": ["21", 0],
+                "filepath": ["8", 0],
+                "tonemap": "linear",
+                "start_frame": ["22", 0],
+                "overwrite": True,
+                "save_workflow": "none",
+            },
+        },
+    }
+
+
+def run(server: str, output_base: Path, repo_root: Path) -> int:
+    _assert_inside(repo_root, output_base)
+    run_output = output_base / f"run-{int(time.time() * 1000)}"
+    _assert_inside(repo_root, run_output)
+    run_output.mkdir(parents=True, exist_ok=True)
+
+    system = _get_json(f"{server}/system_stats")
+    print(f"ComfyUI {system['system']['comfyui_version']} at {server}")
+
+    payload = {
+        "prompt": build_prompt(run_output.resolve()),
+        "client_id": "koolook-loop-test",
+    }
+    try:
+        queued = _post_json(f"{server}/prompt", payload)
+    except urllib.error.HTTPError as exc:
+        print(exc.read().decode("utf-8", errors="replace"))
+        return 1
+
+    prompt_id = queued["prompt_id"]
+    print(f"queued {prompt_id}")
+    for _ in range(240):
+        time.sleep(0.5)
+        history = _get_json(f"{server}/history/{prompt_id}")
+        if prompt_id in history:
+            status = history[prompt_id].get("status", {})
+            print(json.dumps(status, indent=2))
+            if status.get("status_str") != "success":
+                return 1
+            break
+    else:
+        print("Timed out waiting for ComfyUI history.")
+        return 1
+
+    files = []
+    for _ in range(240):
+        files = sorted(run_output.rglob("*.exr"))
+        if len(files) >= 4:
+            break
+        time.sleep(0.5)
+    for file in files:
+        print(file)
+    if len(files) != 4:
+        print(f"Expected 4 EXRs, found {len(files)}.")
+        _dump_server_debug(server)
+        return 1
+    print("OK: wrote 4 EXR frames.")
+    return 0
+
+
+def main() -> int:
+    repo_root = Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--server", default="http://127.0.0.1:8188")
+    parser.add_argument(
+        "--output-base",
+        type=Path,
+        default=repo_root / ".tmp" / "comfy-loop-test-output",
+    )
+    args = parser.parse_args()
+    return run(args.server.rstrip("/"), args.output_base, repo_root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ComfyUI/custom_nodes/koolook/scripts/sync_to_dev.py

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+"""
+Copy runtime-relevant Koolook files into a live ComfyUI custom_nodes
+folder so a fix can be tested without a tag-and-publish round-trip.
+
+USER-INITIATED ONLY. This script overwrites a live ComfyUI install.
+Agents must NEVER run it automatically - not after a commit, not after
+a PR merge or ship-pr, not at session end, not from any "task complete"
+cleanup. The maintainer typically has multiple parallel sessions across
+worktrees, and an unsolicited sync from one silently destroys what
+another is reviewing. See project CLAUDE.md `dev-sync` section for the
+full policy. Run only on the explicit user trigger phrase.
+
+The target path is read from the KOLOOK_COMFYUI_DEV_PATH environment
+variable (loaded from `.env` at the repo root if present). The variable
+is intentionally kept out of the committed tree - see `.env.example`.
+
+`KOLOOK_COMFYUI_DEV_PATH` should point at the eventual Koolook
+subdirectory inside `custom_nodes/`, NOT at the `custom_nodes/` parent.
+Target ``custom_nodes/koolook/`` — that's where ComfyUI-Manager and the
+Comfy Registry install (derived from ``[project].name`` in
+``pyproject.toml``), so dev-sync overwrites the Manager install in place.
+Targeting ``custom_nodes/ComfyUI-Koolook/`` instead spawns a parallel
+install; ``__init__.py``'s duplicate-install guard logs a critical
+message and disables the non-winning copy (issue #162).
+
+Example layouts:
+    macOS:   /Volumes/Data/ComfyUI/custom_nodes/koolook
+    Windows: C:/ComfyUI_portable/ComfyUI/custom_nodes/koolook
+
+Usage:
+    python scripts/sync_to_dev.py            # copy files
+    python scripts/sync_to_dev.py --dry-run  # show what would copy
+    python scripts/sync_to_dev.py --init     # first-run: create the
+                                             # target folder if missing
+                                             # (parent custom_nodes/ must
+                                             # already exist), then sync
+
+After copying Python files, restart ComfyUI manually so custom-node modules
+are re-imported. This script only copies files.
+
+Exit codes:
+    0  success
+    2  KOLOOK_COMFYUI_DEV_PATH unset, parent missing, or target missing
+       (without --init)
+    3  --init refused: parent is not an existing directory or doesn't
+       resemble a ComfyUI custom_nodes/ folder
+
+This script never reaches outside the repo, never deletes anything in
+the source, and only touches paths under the configured target. It does
+overwrite files in the target - that's the point.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _get_short_sha() -> str | None:
+    """Best-effort short commit SHA of the source tree being synced.
+    Returns ``None`` if git isn't reachable or the call fails - the
+    summary line just omits the SHA in that case.
+    """
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=str(REPO_ROOT),
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+        if r.returncode == 0:
+            sha = r.stdout.strip()
+            if sha:
+                return sha
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def _get_worktree_name() -> str:
+    """Returns the basename of the source tree being synced - useful when
+    the maintainer is running multiple parallel ComfyUI installs and
+    needs to know which checkout fed the most recent sync.
+
+    For a worktree at ``.../ComfyUI-Koolook/.claude/worktrees/foo`` this
+    returns ``foo``; for the main repo at ``.../ComfyUI-Koolook`` it
+    returns ``ComfyUI-Koolook``. Either is informative enough to
+    disambiguate."""
+    return REPO_ROOT.name
+
+
+def build_line() -> str:
+    """Composes the two-piece header line consumed by the chat-report
+    convention defined in project CLAUDE.md:
+
+        <short-sha> - <worktree-name>
+
+    SHA falls back to ``unknown`` if git is unreachable (we always need
+    SOMETHING in slot 1 - the line shape is part of the convention).
+    Worktree name comes from ``REPO_ROOT.name`` and is always present.
+
+    Public - consumed by scoped per-module wrappers like
+    ``sync_to_dev_audio.py`` so every dev-sync variant emits the same
+    chat-report header.
+    """
+    sha = _get_short_sha() or "unknown"
+    return f"{sha} - {_get_worktree_name()}"
+
+
+# Backwards-compatible alias (the function was private until the audio
+# wrapper landed). Drop after the next release cycle once we're sure no
+# downstream caller imports the underscore name.
+_build_line = build_line
+
+
+def write_build_info(target: Path, scope: str | None) -> None:
+    """Drop a tiny JSON next to the sidebar JS so the in-browser footer
+    can render `dev <sha> * <time>` (and an italic <scope> on a second
+    line) - same identifier the chat report quotes, but visible in the
+    running ComfyUI itself. Absent on registry installs (the file is
+    only written by this dev script), so the footer stays empty there.
+
+    Best-effort: missing git -> omit `commit` field; no `--scope` -> omit
+    `scope`; the timestamp alone is still useful for the maintainer to
+    eyeball "did my last sync land in this browser tab?\""""
+    info: dict[str, str] = {
+        "synced_at": datetime.now().strftime("%Y-%m-%d %H:%M"),
+        "worktree": _get_worktree_name(),
+    }
+    sha = _get_short_sha()
+    if sha:
+        info["commit"] = sha
+    if scope:
+        info["scope"] = scope
+    out = target / "web" / "_dev_build.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(info, indent=2) + "\n", encoding="utf-8")
+
+# Files / dirs ComfyUI loads at runtime, plus the package metadata ComfyUI
+# Manager reads when showing the installed custom-node version. Anything
+# outside this list (CI, docs, .claude/, .github/, .cursor/, CHANGELOG, LICENSE,
+# README, fork manifest YAML, etc.) does not affect what ComfyUI executes or
+# how the dev install is identified, and is intentionally skipped.
+RUNTIME_PATHS: tuple[str, ...] = (
+    "pyproject.toml",
+    "__init__.py",
+    "config.json",
+    "k_ai_pipeline.py",
+    "k_easy_image_batch.py",
+    "k_easy_pattern.py",
+    "k_easy_resize.py",
+    "k_easy_track.py",
+    "k_easy_utility.py",
+    "k_easy_wan22_prompt.py",
+    "k_loop_status.py",
+    "k_publish_contract.py",
+    "k_video_combine.py",
+    "k_video_load.py",
+    "koolook_install_guard.py",
+    "koolook_routes.py",
+    "koolook_setup_runner.py",
+    "koolook_setups.py",
+    "koolook_versioning.py",
+    "forks",
+    "video_formats",
+    "web",
+)
+
+# When copying directories, exclude these subpaths - they are dev-only
+# metadata that ComfyUI doesn't need and which can churn unnecessarily.
+DIR_EXCLUDES: tuple[str, ...] = (
+    "__pycache__",
+    "UPSTREAM_PIN.yaml",
+    "THIRD_PARTY.md",
+    "forks_manifest.yaml",
+    "README.md",
+)
+
+
+def load_dotenv(env_path: Path) -> None:
+    """Minimal `.env` loader. No dependency on python-dotenv."""
+    if not env_path.exists():
+        return
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        # Don't overwrite anything already in the environment.
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def _ignore(_dir: str, names: list[str]) -> list[str]:
+    return [n for n in names if n in DIR_EXCLUDES]
+
+
+def sync(
+    target: Path,
+    dry_run: bool,
+    verbose: bool,
+    paths: tuple[str, ...] = RUNTIME_PATHS,
+) -> int:
+    """Copy each entry in ``paths`` (relative to the repo root) to the
+    matching subpath under ``target``. Directories are recursively
+    copied with ``DIR_EXCLUDES`` filtered out and the previous dest
+    subtree removed first; files are overwritten in place.
+
+    The optional ``paths`` argument lets scoped wrappers (e.g.
+    ``sync_to_dev_audio.py``) reuse this function with a smaller set -
+    just the subtree their automation module touches. The default is
+    the full ``RUNTIME_PATHS`` (every file ComfyUI loads at runtime).
+    """
+    copied = 0
+    for rel in paths:
+        src = REPO_ROOT / rel
+        if not src.exists():
+            continue
+        dst = target / rel
+        if dry_run:
+            if verbose:
+                print(f"would copy: {rel}")
+            copied += 1
+            continue
+        if src.is_dir():
+            if dst.exists():
+                shutil.rmtree(dst)
+            shutil.copytree(src, dst, ignore=_ignore)
+        else:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+        if verbose:
+            print(f"copied: {rel}")
+        copied += 1
+    return copied
+
+
+def _looks_like_custom_nodes(parent: Path) -> bool:
+    """Heuristic: parent is named `custom_nodes` OR sits inside a
+    directory named `ComfyUI`. A bit conservative - saves the user from
+    a `KOLOOK_COMFYUI_DEV_PATH` typo that would otherwise create a fresh
+    `ComfyUI-Koolook/` somewhere unexpected on disk."""
+    if parent.name == "custom_nodes":
+        return True
+    grandparent = parent.parent
+    return grandparent.name.lower() == "comfyui" and parent.is_dir()
+
+
+def ensure_target(target: Path, init: bool) -> int | None:
+    """Validate the target. Returns an exit code (2 or 3) on error,
+    or None on success (with target now guaranteed to exist as a dir)."""
+    if target.exists():
+        if not target.is_dir():
+            print(f"target is not a directory: {target}", file=sys.stderr)
+            return 2
+        return None
+    # Target is missing.
+    if not init:
+        print(
+            f"target does not exist: {target}\n"
+            f"first time on this machine? re-run with --init to create it.",
+            file=sys.stderr,
+        )
+        return 2
+    parent = target.parent
+    if not parent.exists() or not parent.is_dir():
+        print(
+            f"--init refused: parent does not exist: {parent}\n"
+            f"check KOLOOK_COMFYUI_DEV_PATH - the *parent* (typically a "
+            f"ComfyUI custom_nodes/ folder) must already be in place.",
+            file=sys.stderr,
+        )
+        return 3
+    if not _looks_like_custom_nodes(parent):
+        print(
+            f"--init refused: parent doesn't look like a ComfyUI "
+            f"custom_nodes/ folder: {parent}\n"
+            f"expected the parent to be named 'custom_nodes' or to sit "
+            f"inside a 'ComfyUI' directory. If this really is your "
+            f"ComfyUI install, create the target manually with "
+            f"`mkdir -p \"{target}\"` and re-run without --init.",
+            file=sys.stderr,
+        )
+        return 3
+    target.mkdir(parents=False, exist_ok=False)
+    print(f"created target: {target}")
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be copied without touching the target.",
+    )
+    parser.add_argument(
+        "--init",
+        action="store_true",
+        help=(
+            "Create the target directory if it doesn't exist. The parent "
+            "(typically a ComfyUI custom_nodes/ folder) must already be "
+            "in place. Use on first-run only."
+        ),
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help=(
+            "Print each file/dir as it's copied. Default output is just "
+            "the one-line build summary."
+        ),
+    )
+    parser.add_argument(
+        "--scope",
+        type=str,
+        default=None,
+        help=(
+            "Short (<=10 word) description of what this build is about - "
+            "the same scope summary that goes in the chat report's second "
+            "line. Persisted in `web/_dev_build.json` and rendered in the "
+            "Kforge Labs sidebar footer (italic, second line, below the "
+            "`dev <sha> * <time>` identifier) so the maintainer can "
+            "correlate live ComfyUI state with chat history when juggling "
+            "multiple parallel worktree sessions. Optional - when absent, "
+            "the footer renders just identifier + timestamp."
+        ),
+    )
+    args = parser.parse_args()
+
+    load_dotenv(REPO_ROOT / ".env")
+
+    target_str = os.environ.get("KOLOOK_COMFYUI_DEV_PATH")
+    if not target_str:
+        print(
+            "KOLOOK_COMFYUI_DEV_PATH not set. Add it to .env "
+            "(see .env.example).",
+            file=sys.stderr,
+        )
+        return 2
+
+    target = Path(target_str).expanduser()
+    err = ensure_target(target, init=args.init)
+    if err is not None:
+        return err
+
+    n = sync(target, dry_run=args.dry_run, verbose=args.verbose)
+    verb = "would sync" if args.dry_run else "synced"
+    # Two-line summary - see project CLAUDE.md `dev-sync` section for the
+    # chat-report convention that consumes this output. Header first so
+    # the maintainer's eye lands on the build identifier before the
+    # mechanical sync details.
+    print(build_line())
+    print(f"{verb} {n} entries -> {target}")
+    if not args.dry_run:
+        write_build_info(target, args.scope)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/sync_to_dev_audio.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""
+Scoped variant of ``dev-sync`` for the LTX 2.3 audio-lipsync automation.
+
+Copies only what that automation's iteration loop touches:
+
+    - forks/whatdreamscost_koolook/    the Koolook fork of LTXDirector +
+                                       its modified prompt_relay + the
+                                       verbatim-vendored patches.py
+    - __init__.py                      root loader (registers the fork's
+                                       node mappings; needs to be re-synced
+                                       when the fork's NODE_CLASS_MAPPINGS
+                                       set changes)
+    - web/whatdreamscost_koolook/      Director timeline-editor extension
+    - web/koolook_draft_guard.js       global Comfy draft-quota guard
+                                       (formerly embedded in the Director
+                                       extension; shipped so a scoped sync
+                                       never strands a guard-less install)
+
+It also ships ``koolook_install_guard.py`` + ``koolook_versioning.py`` — the
+loader gates ``__init__.py`` imports at load — so a scoped sync never leaves
+the loader pointing at a module the target lacks (#198 / #183).
+
+Everything else in the live install - ``forks/radiance_koolook/``, the
+root ``k_*.py`` nodes, unrelated ``web/`` assets, ``video_formats/`` -
+is left untouched.
+
+USER-INITIATED ONLY. Same rule as plain ``dev-sync`` (see project
+``CLAUDE.md`` -> ``dev-sync`` section). Never run automatically:
+
+  * after a commit
+  * after a PR merge or ``/ship-pr``
+  * at session end / wrap-up
+  * on hook completion or "task complete" cleanup
+  * from any agent skill that doesn't explicitly require it
+
+Run only on the explicit user trigger phrase ``dev-sync-audio`` (or
+``copy audio fork``, ``sync audio``, etc.). The maintainer typically has
+multiple parallel sessions across worktrees; an unsolicited sync from one
+silently destroys what another is reviewing.
+
+The target path comes from ``KOLOOK_COMFYUI_DEV_PATH`` in ``.env`` -
+identical to plain ``dev-sync``. No new env var.
+
+Usage:
+    python scripts/sync_to_dev_audio.py
+    python scripts/sync_to_dev_audio.py --dry-run
+    python scripts/sync_to_dev_audio.py --scope "vstr=10 trial"
+
+Exit codes mirror ``sync_to_dev.py`` exactly:
+    0  success
+    2  KOLOOK_COMFYUI_DEV_PATH unset or target missing without --init
+    3  --init refused
+
+After copying Python files, restart ComfyUI manually so custom nodes are
+re-imported. This scoped sync only copies files.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+# Reuse the dev-sync infrastructure for the .env loader, target validation,
+# and chat-report shape. This scoped wrapper differs only in which paths get
+# copied, and it never tries to manage the running ComfyUI process.
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+import sync_to_dev as _dev  # noqa: E402
+
+
+AUDIO_PATHS: tuple[str, ...] = (
+    "__init__.py",
+    # __init__.py imports these at load, before any node group, and a missing
+    # gate is catastrophic (not per-group-guarded): the install guard's
+    # absolute-import fallback raises uncaught, and the koolook_versioning
+    # context probe mislabels its ImportError as a non-Comfy context and
+    # registers nothing. Ship them with __init__.py so a scoped sync never
+    # leaves the loader pointing at a module the target lacks (#198 / #183).
+    "koolook_install_guard.py",
+    "koolook_versioning.py",
+    "forks/whatdreamscost_koolook",
+    "web/whatdreamscost_koolook",
+    # The Comfy draft-quota guard used to be embedded in the Director web
+    # extension above; it is global now. Ship it with every scoped audio
+    # sync so replacing web/whatdreamscost_koolook/ can never leave a dev
+    # install without the guard.
+    "web/koolook_draft_guard.js",
+)
+
+STALE_AUDIO_PATHS: tuple[str, ...] = (
+    "web/whatdreamscost_koolook_v1_3_2",
+)
+
+
+def target_is_repo_root(target: Path) -> bool:
+    """Return True when the configured dev target is this source repo."""
+    try:
+        return target.resolve() == _dev.REPO_ROOT.resolve()
+    except OSError:
+        return False
+
+
+def remove_stale_paths(target: Path, *, dry_run: bool, verbose: bool) -> int:
+    """Remove old audio-sync paths that were renamed.
+
+    The v1.3.9 upgrade moved the Director web extension from a versioned
+    folder to a stable one. Existing dev installs can still have the old
+    folder on disk, causing ComfyUI to load two timeline extensions for
+    legacy workflows. Keep this scoped to explicit known paths.
+    """
+    removed = 0
+    for rel in STALE_AUDIO_PATHS:
+        stale = target / rel
+        if not stale.exists() and not stale.is_symlink():
+            continue
+        if dry_run:
+            if verbose:
+                print(f"would remove stale: {rel}")
+            removed += 1
+            continue
+        if stale.is_symlink() or stale.is_file():
+            stale.unlink()
+        elif stale.is_dir():
+            shutil.rmtree(stale)
+        else:
+            stale.unlink()
+        if verbose:
+            print(f"removed stale: {rel}")
+        removed += 1
+    return removed
+
+
+def _find_dotenv() -> Path | None:
+    direct = _dev.REPO_ROOT / ".env"
+    if direct.exists():
+        return direct
+    git_marker = _dev.REPO_ROOT / ".git"
+    if not git_marker.is_file():
+        return None
+    try:
+        content = git_marker.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not content.startswith("gitdir:"):
+        return None
+    gitdir = Path(content.split(":", 1)[1].strip())
+    if "worktrees" not in gitdir.parts:
+        return None
+    idx = gitdir.parts.index("worktrees")
+    main_repo_root = Path(*gitdir.parts[:idx]).parent
+    candidate = main_repo_root / ".env"
+    return candidate if candidate.exists() else None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be copied without touching the target.",
+    )
+    parser.add_argument(
+        "--init",
+        action="store_true",
+        help=(
+            "Create the target directory if it doesn't exist. The parent "
+            "(typically a ComfyUI custom_nodes/ folder) must already be "
+            "in place. Use on first-run only."
+        ),
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Print each file/dir as it's copied.",
+    )
+    parser.add_argument(
+        "--scope",
+        type=str,
+        default="audio-lipsync fork edit",
+        help=(
+            "Short (<=10 word) description for the chat report's second line "
+            "and the in-browser footer in `web/_dev_build.json`. Defaults to "
+            "'audio-lipsync fork edit' so the build identifier always names "
+            "this module even when the maintainer doesn't pass a scope."
+        ),
+    )
+    args = parser.parse_args()
+
+    env_path = _find_dotenv()
+    if env_path is not None:
+        _dev.load_dotenv(env_path)
+
+    target_str = os.environ.get("KOLOOK_COMFYUI_DEV_PATH")
+    if not target_str:
+        print(
+            "KOLOOK_COMFYUI_DEV_PATH not set. Add it to .env (see .env.example).",
+            file=sys.stderr,
+        )
+        return 2
+
+    target = Path(target_str).expanduser()
+    if target_is_repo_root(target):
+        print(
+            "KOLOOK_COMFYUI_DEV_PATH points at this source repo; refusing dev-sync.",
+            file=sys.stderr,
+        )
+        return 2
+
+    err = _dev.ensure_target(target, init=args.init)
+    if err is not None:
+        return err
+
+    n = _dev.sync(
+        target,
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+        paths=AUDIO_PATHS,
+    )
+    removed = remove_stale_paths(target, dry_run=args.dry_run, verbose=args.verbose)
+    verb = "would sync" if args.dry_run else "synced"
+    print(_dev.build_line())
+    stale_note = f"; removed {removed} stale" if removed else ""
+    print(f"{verb} {n} entries{stale_note} -> {target}  (dev-sync-audio)")
+    if not args.dry_run:
+        _dev.write_build_info(target, args.scope)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/validate_workflow.py

@@ -0,0 +1,298 @@
+"""Validate a ComfyUI workflow JSON for internal consistency.
+
+Usage:
+    python scripts/validate_workflow.py <workflow.json> [--quiet]
+
+Checks performed:
+- The file parses as JSON.
+- Every link referenced by node inputs/outputs is declared in the top-level
+  `links` table.
+- Every entry in the `links` table is referenced by both endpoints (no
+  orphans).
+- For each link, the source/destination nodes and slots exist and the slot
+  type matches the declared link type.
+- `last_node_id >= max(node ids)` and `last_link_id >= max(link ids)`.
+- No duplicate node IDs or link IDs.
+
+Exit codes:
+    0  All checks passed.
+    1  Problems found (printed to stderr).
+    2  File not found or not valid JSON.
+
+This catches the class of bugs that come from hand-editing workflow JSONs
+(e.g. when an agent re-wires a graph to build a slim variant). Run it after
+any non-trivial edit before re-loading the workflow into ComfyUI — Comfy's
+loader will sometimes silently drop or mis-wire the bad parts, producing a
+graph that looks fine but behaves wrong.
+
+stdlib only, no third-party dependencies.
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _sanitize_slots(
+    node: dict, key: str, problems: list[str]
+) -> list[dict]:
+    """Return a list-of-dicts view of node[key], appending a problem for any
+    malformed entry. Non-list `node[key]` → reported and treated as empty.
+    Non-dict entries → reported and dropped.
+    """
+    slots = node.get(key)
+    if slots is None:
+        return []
+    if not isinstance(slots, list):
+        problems.append(
+            f"node {node.get('id')!r}: {key!r} must be a list, got {type(slots).__name__}"
+        )
+        return []
+    cleaned: list[dict] = []
+    for j, slot in enumerate(slots):
+        if not isinstance(slot, dict):
+            problems.append(
+                f"node {node.get('id')!r}: {key}[{j}] must be an object, got {type(slot).__name__}"
+            )
+            continue
+        cleaned.append(slot)
+    return cleaned
+
+
+def _slot_type_matches(slot_type, link_type) -> bool:
+    """ComfyUI wildcard sockets (`*`) accept any concrete link type."""
+    return slot_type == link_type or slot_type == "*"
+
+
+def validate(data) -> list[str]:
+    """Return a list of problem strings; empty list means OK.
+
+    Defensive: every shape assumption is guarded so that malformed-but-valid
+    JSON produces problem lines, never an uncaught exception. Top-level not
+    being an object is the only short-circuit return (nothing else is safe
+    to do without a dict).
+    """
+    problems: list[str] = []
+
+    # Top-level must be a JSON object.
+    if not isinstance(data, dict):
+        return [
+            f"top-level JSON must be an object, got {type(data).__name__}"
+        ]
+
+    # `nodes` and `links` arrays — must be lists; non-list reported and skipped.
+    raw_nodes = data.get("nodes") or []
+    if not isinstance(raw_nodes, list):
+        problems.append(
+            f"'nodes' must be a list, got {type(raw_nodes).__name__}"
+        )
+        raw_nodes = []
+
+    raw_links = data.get("links") or []
+    if not isinstance(raw_links, list):
+        problems.append(
+            f"'links' must be a list, got {type(raw_links).__name__}"
+        )
+        raw_links = []
+
+    # Filter to well-shaped node entries, recording each bad one.
+    nodes: list[dict] = []
+    for i, n in enumerate(raw_nodes):
+        if not isinstance(n, dict):
+            problems.append(
+                f"nodes[{i}]: must be an object, got {type(n).__name__}"
+            )
+            continue
+        nodes.append(n)
+
+    # Filter to well-shaped link entries. Each must be a 6-element list.
+    links: list[list] = []
+    for i, link in enumerate(raw_links):
+        if not isinstance(link, list):
+            problems.append(
+                f"links[{i}]: must be a list of 6 elements, got {type(link).__name__}"
+            )
+            continue
+        if len(link) != 6:
+            problems.append(
+                f"links[{i}]: malformed — expected 6 elements "
+                f"[id, src, src_slot, dst, dst_slot, type], got {len(link)}"
+            )
+            continue
+        links.append(link)
+
+    # Pre-sanitize each node's inputs/outputs into list-of-dict views so
+    # downstream code can index safely. Caches per-node so problems aren't
+    # double-reported when a node is touched by multiple links.
+    sanitized_io: dict[int, dict[str, list[dict]]] = {}
+    for n in nodes:
+        sanitized_io[id(n)] = {
+            "inputs": _sanitize_slots(n, "inputs", problems),
+            "outputs": _sanitize_slots(n, "outputs", problems),
+        }
+
+    # Duplicate IDs (over good entries).
+    node_ids = [n.get("id") for n in nodes]
+    link_ids = [link[0] for link in links]
+    dup_nodes = sorted({i for i in node_ids if node_ids.count(i) > 1})
+    dup_links = sorted({i for i in link_ids if link_ids.count(i) > 1})
+    if dup_nodes:
+        problems.append(f"Duplicate node IDs: {dup_nodes}")
+    if dup_links:
+        problems.append(f"Duplicate link IDs: {dup_links}")
+
+    # Header counters should bound observed IDs (Comfy uses these to assign
+    # the next id when adding nodes; if they lag, the next add can collide).
+    int_node_ids = [i for i in node_ids if isinstance(i, int)]
+    int_link_ids = [i for i in link_ids if isinstance(i, int)]
+    if int_node_ids:
+        last_node_id = data.get("last_node_id", -1)
+        if not isinstance(last_node_id, int) or last_node_id < max(int_node_ids):
+            problems.append(
+                f"last_node_id={last_node_id!r} < max(node id)={max(int_node_ids)}"
+            )
+    if int_link_ids:
+        last_link_id = data.get("last_link_id", -1)
+        if not isinstance(last_link_id, int) or last_link_id < max(int_link_ids):
+            problems.append(
+                f"last_link_id={last_link_id!r} < max(link id)={max(int_link_ids)}"
+            )
+
+    # Cross-reference link declarations vs node IO references.
+    declared = set(int_link_ids)
+    referenced: set[int] = set()
+    for n in nodes:
+        io = sanitized_io[id(n)]
+        for inp in io["inputs"]:
+            link_val = inp.get("link")
+            if isinstance(link_val, int):
+                referenced.add(link_val)
+        for out in io["outputs"]:
+            out_links = out.get("links") or []
+            if not isinstance(out_links, list):
+                problems.append(
+                    f"node {n.get('id')!r}: output.links must be a list, "
+                    f"got {type(out_links).__name__}"
+                )
+                continue
+            for lk in out_links:
+                if isinstance(lk, int):
+                    referenced.add(lk)
+
+    for missing in sorted(referenced - declared):
+        problems.append(
+            f"link {missing}: referenced by a node but not in the links table"
+        )
+    for orphan in sorted(declared - referenced):
+        problems.append(
+            f"link {orphan}: declared in the links table but unused by any node"
+        )
+
+    # Per-link endpoint validation.
+    # Build node_by_id over int ids only — non-int ids can't match a link's
+    # src/dst (which are ints in the link tuple), and treating them as keys
+    # would mask bad data.
+    node_by_id = {n.get("id"): n for n in nodes if isinstance(n.get("id"), int)}
+    for link in links:
+        lid, src, src_slot, dst, dst_slot, ltype = link
+        src_node = node_by_id.get(src)
+        dst_node = node_by_id.get(dst)
+        if src_node is None:
+            problems.append(f"link {lid}: src node {src!r} missing")
+            continue
+        if dst_node is None:
+            problems.append(f"link {lid}: dst node {dst!r} missing")
+            continue
+        src_outs = sanitized_io[id(src_node)]["outputs"]
+        dst_ins = sanitized_io[id(dst_node)]["inputs"]
+
+        # Slot index bounds + type checks.
+        if not isinstance(src_slot, int) or src_slot < 0 or src_slot >= len(src_outs):
+            problems.append(
+                f"link {lid}: src slot {src_slot!r} out of bounds on node {src} "
+                f"(has {len(src_outs)} outputs)"
+            )
+        elif not _slot_type_matches(src_outs[src_slot].get("type"), ltype):
+            problems.append(
+                f"link {lid}: src type mismatch — link declares {ltype!r}, "
+                f"slot is {src_outs[src_slot].get('type')!r}"
+            )
+        if not isinstance(dst_slot, int) or dst_slot < 0 or dst_slot >= len(dst_ins):
+            problems.append(
+                f"link {lid}: dst slot {dst_slot!r} out of bounds on node {dst} "
+                f"(has {len(dst_ins)} inputs)"
+            )
+        elif not _slot_type_matches(dst_ins[dst_slot].get("type"), ltype):
+            problems.append(
+                f"link {lid}: dst type mismatch — link declares {ltype!r}, "
+                f"slot is {dst_ins[dst_slot].get('type')!r}"
+            )
+
+        # Endpoint cross-check: node IO must reference this link id symmetrically.
+        if isinstance(src_slot, int) and 0 <= src_slot < len(src_outs):
+            out_links = src_outs[src_slot].get("links") or []
+            if isinstance(out_links, list) and lid not in out_links:
+                problems.append(
+                    f"link {lid}: missing from node {src} output[{src_slot}].links={out_links}"
+                )
+        if isinstance(dst_slot, int) and 0 <= dst_slot < len(dst_ins):
+            in_link = dst_ins[dst_slot].get("link")
+            if in_link != lid:
+                problems.append(
+                    f"link {lid}: node {dst} input[{dst_slot}].link={in_link} "
+                    f"does not match"
+                )
+
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__.splitlines()[0],
+    )
+    parser.add_argument(
+        "path",
+        type=Path,
+        help="Path to the workflow JSON file.",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress the OK summary; only print problems.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.path.exists():
+        print(f"error: file not found: {args.path}", file=sys.stderr)
+        return 2
+
+    try:
+        data = json.loads(args.path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"error: {args.path.name}: JSON parse error: {exc}", file=sys.stderr)
+        return 2
+
+    problems = validate(data)
+    if problems:
+        print(
+            f"FAIL: {args.path.name} ({len(problems)} problem(s))",
+            file=sys.stderr,
+        )
+        for p in problems:
+            print(f"  - {p}", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(
+            f"OK: {args.path.name} — "
+            f"{len(data.get('nodes') or [])} nodes, "
+            f"{len(data.get('links') or [])} links, "
+            f"{len(data.get('groups') or [])} groups"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ComfyUI/custom_nodes/koolook/scripts/watch_cards.py

@@ -0,0 +1,95 @@
+"""Watch the make-card working folder; auto-render a card whenever a JSON
+is added or saved.
+
+Usage:
+    python scripts/watch_cards.py              # uses .claude/skills/make-card/work-folder.txt
+    python scripts/watch_cards.py <folder>     # override
+    python scripts/watch_cards.py --interval 1 # poll every 1 s (default 2)
+
+Run it once in a terminal at the start of a session and forget about it.
+Each time ComfyUI (or you) drops a new workflow JSON into the folder, a
+matching `<stem>_card.png` is rendered next to it within a couple of
+seconds. Skips JSONs whose card is already up to date.
+
+Stop with Ctrl+C.
+"""
+from __future__ import annotations
+import sys
+import time
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+MAKE_CARD = ROOT / "scripts" / "make_card.py"
+DEFAULT_CFG = ROOT / ".claude" / "skills" / "make-card" / "work-folder.txt"
+PYTHON_EXE = sys.executable or "python"
+
+
+def resolve_folder(argv: list[str]) -> Path:
+    args = [a for a in argv if not a.startswith("-")]
+    if args:
+        return Path(args[0]).expanduser().resolve()
+    if DEFAULT_CFG.exists():
+        return Path(DEFAULT_CFG.read_text(encoding="utf-8").strip()).resolve()
+    raise SystemExit(f"No folder argument and no config at {DEFAULT_CFG}")
+
+
+def needs_render(json_path: Path) -> Path | None:
+    """Return the target PNG path if it's missing or older than the JSON.
+    Target lives in <working folder>/_AI/card.png — matches make_card.py."""
+    ai_dir = json_path.parent / "_AI"
+    png = ai_dir / "card.png"
+    if not png.exists() or png.stat().st_mtime < json_path.stat().st_mtime:
+        return png
+    return None
+
+
+def render(json_path: Path, png_path: Path) -> bool:
+    print(f"[{time.strftime('%H:%M:%S')}] rendering {json_path.name} ...", flush=True)
+    # Let make_card.py compute its own output path (writes to _AI/card.png).
+    # Passing only the JSON keeps the watcher and the script in lockstep.
+    r = subprocess.run(
+        [PYTHON_EXE, str(MAKE_CARD), str(json_path)],
+        capture_output=True, text=True,
+    )
+    if r.returncode == 0:
+        print(f"  -> {png_path.relative_to(png_path.parent.parent)}", flush=True)
+        return True
+    print(f"  !! make_card.py failed (rc={r.returncode})\n{r.stderr}", flush=True)
+    return False
+
+
+def main():
+    interval = 2.0
+    if "--interval" in sys.argv:
+        i = sys.argv.index("--interval")
+        interval = float(sys.argv[i + 1])
+    folder = resolve_folder(sys.argv[1:])
+    if not folder.is_dir():
+        raise SystemExit(f"Folder does not exist: {folder}")
+
+    print(f"watching {folder}  (every {interval}s, Ctrl+C to stop)", flush=True)
+    seen_mtimes: dict[Path, float] = {}
+    # Skip post-loop outputs — the user's composited card+video saves a
+    # JSON with "loop" in its name; treating it as input would feed the
+    # script its own output.
+    SKIP_MARKER = "loop"
+    try:
+        while True:
+            for json_path in folder.glob("*.json"):
+                if SKIP_MARKER in json_path.stem.lower():
+                    continue
+                mtime = json_path.stat().st_mtime
+                if seen_mtimes.get(json_path) == mtime:
+                    continue
+                target = needs_render(json_path)
+                if target is not None:
+                    render(json_path, target)
+                seen_mtimes[json_path] = mtime
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        print("\nstopped.", flush=True)
+
+
+if __name__ == "__main__":
+    main()

ComfyUI/custom_nodes/koolook/tests/forks/test_whatdreamscost_audio_transcript.py

@@ -0,0 +1,167 @@
+"""Tests for Koolook's Director-level audio transcript hook."""
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+
+def _install_import_stubs(monkeypatch):
+    class _ComfyNode:
+        pass
+
+    class _IoStub(types.SimpleNamespace):
+        def Custom(self, name):
+            return name
+
+        def __getattr__(self, _name):
+            return types.SimpleNamespace(
+                Input=lambda *args, **kwargs: None,
+                Output=lambda *args, **kwargs: None,
+            )
+
+    comfy = types.ModuleType("comfy")
+    comfy.model_management = types.ModuleType("comfy.model_management")
+    comfy.ldm = types.ModuleType("comfy.ldm")
+    comfy.ldm.modules = types.ModuleType("comfy.ldm.modules")
+    comfy.ldm.modules.attention = types.ModuleType("comfy.ldm.modules.attention")
+
+    comfy_api = types.ModuleType("comfy_api")
+    comfy_api.latest = types.ModuleType("comfy_api.latest")
+    comfy_api.latest.io = _IoStub(
+        ComfyNode=_ComfyNode,
+        NodeOutput=lambda *args: args,
+        Schema=lambda *args, **kwargs: None,
+    )
+
+    torch = types.ModuleType("torch")
+    torch.Tensor = object
+    torch.float32 = object()
+    numpy = types.ModuleType("numpy")
+    numpy.float32 = object()
+    pil = types.ModuleType("PIL")
+    pil.Image = object()
+    monkeypatch.setitem(sys.modules, "torch", torch)
+    monkeypatch.setitem(sys.modules, "numpy", numpy)
+    monkeypatch.setitem(sys.modules, "PIL", pil)
+    monkeypatch.setitem(sys.modules, "PIL.Image", pil.Image)
+    monkeypatch.setitem(sys.modules, "av", types.ModuleType("av"))
+    monkeypatch.setitem(sys.modules, "folder_paths", types.ModuleType("folder_paths"))
+    monkeypatch.setitem(sys.modules, "comfy", comfy)
+    monkeypatch.setitem(sys.modules, "comfy.model_management", comfy.model_management)
+    monkeypatch.setitem(sys.modules, "comfy.ldm", comfy.ldm)
+    monkeypatch.setitem(sys.modules, "comfy.ldm.modules", comfy.ldm.modules)
+    monkeypatch.setitem(sys.modules, "comfy.ldm.modules.attention", comfy.ldm.modules.attention)
+    monkeypatch.setitem(sys.modules, "comfy_api", comfy_api)
+    monkeypatch.setitem(sys.modules, "comfy_api.latest", comfy_api.latest)
+
+
+def _load_director(monkeypatch):
+    _install_import_stubs(monkeypatch)
+    repo_root = Path(__file__).resolve().parents[2]
+    version_dir = repo_root / "forks" / "whatdreamscost_koolook" / "versions" / "v1_3_9"
+    package_names = [
+        ("forks", repo_root / "forks"),
+        ("forks.whatdreamscost_koolook", repo_root / "forks" / "whatdreamscost_koolook"),
+        ("forks.whatdreamscost_koolook.versions", repo_root / "forks" / "whatdreamscost_koolook" / "versions"),
+        ("forks.whatdreamscost_koolook.versions.v1_3_9", version_dir),
+    ]
+    for name, path in package_names:
+        package = types.ModuleType(name)
+        package.__path__ = [str(path)]
+        monkeypatch.setitem(sys.modules, name, package)
+
+    module_name = "forks.whatdreamscost_koolook.versions.v1_3_9.ltx_director"
+    spec = importlib.util.spec_from_file_location(module_name, version_dir / "ltx_director.py")
+    assert spec and spec.loader
+    director = importlib.util.module_from_spec(spec)
+    monkeypatch.setitem(sys.modules, module_name, director)
+    spec.loader.exec_module(director)
+    return director
+
+
+def test_audio_transcript_json_preserves_existing_timeline_segments(monkeypatch):
+    director = _load_director(monkeypatch)
+    transcript = {
+        "phrases": [
+            {"start": 0.0, "end": 0.5, "text": "What?"},
+            {"start": 1.06, "end": 1.74, "text": "What's going on?"},
+            {"start": 1.96, "end": 2.82, "text": "This is made by AI."},
+        ]
+    }
+    timeline_data, local_prompts, segment_lengths = director._apply_audio_transcript_json(
+        json.dumps(
+            {
+                "segments": [
+                    {
+                        "id": "old",
+                        "type": "image",
+                        "start": 0,
+                        "length": 120,
+                        "imageFile": "bear.png",
+                        "prompt": "old prompt",
+                    }
+                ],
+                "audioSegments": [{"id": "audio_001", "audioFile": "line.mp3"}],
+            }
+        ),
+        "old local",
+        "120",
+        json.dumps(transcript),
+        duration_frames=120,
+        frame_rate=24.0,
+    )
+
+    timeline = json.loads(timeline_data)
+    assert segment_lengths == "12,13,17,5,21,52"
+    assert 'says "What?"' in local_prompts
+    assert 'says "What\'s going on?"' in local_prompts
+    assert 'says "This is made by AI."' in local_prompts
+    assert timeline["audioSegments"] == [{"id": "audio_001", "audioFile": "line.mp3"}]
+    assert timeline["segments"] == [
+        {
+            "id": "old",
+            "type": "image",
+            "start": 0,
+            "length": 120,
+            "imageFile": "bear.png",
+            "prompt": "old prompt",
+        }
+    ]
+
+
+def test_audio_transcript_json_builds_segments_when_timeline_has_none(monkeypatch):
+    director = _load_director(monkeypatch)
+    transcript = {"phrases": [{"start": 0.0, "end": 0.5, "text": "What?"}]}
+
+    timeline_data, local_prompts, segment_lengths = director._apply_audio_transcript_json(
+        json.dumps({"audioSegments": [{"id": "audio_001", "audioFile": "line.mp3"}]}),
+        "old local",
+        "120",
+        json.dumps(transcript),
+        duration_frames=24,
+        frame_rate=24.0,
+    )
+
+    timeline = json.loads(timeline_data)
+    assert segment_lengths == "12,12"
+    assert 'says "What?"' in local_prompts
+    assert [segment["start"] for segment in timeline["segments"]] == [0, 12]
+
+
+def test_audio_transcript_json_rejects_empty_phrases(monkeypatch):
+    director = _load_director(monkeypatch)
+
+    with pytest.raises(ValueError, match="phrases must not be empty"):
+        director._apply_audio_transcript_json(
+            "{}",
+            "",
+            "",
+            json.dumps({"phrases": []}),
+            duration_frames=24,
+            frame_rate=24.0,
+        )

ComfyUI/custom_nodes/koolook/tests/forks/test_whatdreamscost_v1_3_2_relay_overrides.py

@@ -0,0 +1,216 @@
+"""Tests for the LTXDirector ``relay_overrides`` widget parser.
+
+These guard the failure modes flagged in the PR #178 verified review
+(H1 — values were never type-checked; H2 — malformed JSON silently fell
+back to upstream defaults and polluted A/B iteration logs). The parser
+lives in
+``forks/whatdreamscost_koolook/versions/v1_3_2/_relay_overrides.py`` —
+deliberately stdlib-only so we can import it here without pulling in
+ComfyUI's ``comfy_api`` runtime (which the rest of ``ltx_director.py``
+needs and which can't run inside pytest).
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+from pathlib import Path
+
+import pytest
+
+
+# Load the parser module by file path. We avoid the normal package import
+# (``from forks.whatdreamscost_koolook... import ...``) because walking
+# into that package triggers ``forks/whatdreamscost_koolook/versions/
+# v1_3_2/__init__.py``, which imports ``ltx_director`` → ``comfy_api`` —
+# ComfyUI-only and unavailable inside pytest. The parser module itself
+# is pure stdlib + logging, so loading it in isolation is fine.
+_RELAY_PATH = (
+    Path(__file__).resolve().parents[2]
+    / "forks"
+    / "whatdreamscost_koolook"
+    / "versions"
+    / "v1_3_2"
+    / "_relay_overrides.py"
+)
+_spec = importlib.util.spec_from_file_location(
+    "whatdreamscost_v1_3_2_relay_overrides", _RELAY_PATH
+)
+_mod = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_mod)
+
+RELAY_OVERRIDE_KEYS = _mod.RELAY_OVERRIDE_KEYS
+parse_relay_overrides = _mod.parse_relay_overrides
+
+
+# ---------------------------------------------------------------------------
+# Silent fallback: only the empty/whitespace case should return None.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("blank", ["", "   ", "\n", "\t \n"])
+def test_empty_or_whitespace_means_use_upstream_defaults(blank):
+    assert parse_relay_overrides(blank) is None
+
+
+# ---------------------------------------------------------------------------
+# Happy path: known knobs with numeric values get coerced to float.
+# ---------------------------------------------------------------------------
+
+
+def test_single_known_knob():
+    out = parse_relay_overrides('{"video_strength": 10.0}')
+    assert out == {"video_strength": 10.0}
+    assert isinstance(out["video_strength"], float)
+
+
+def test_all_known_knobs():
+    payload = {
+        "video_strength": 2.5,
+        "video_window_scale": 0.7,
+        "audio_strength": 0.5,
+        "audio_window_scale": 1.2,
+        "audio_epsilon": 0.001,
+    }
+    assert parse_relay_overrides(json.dumps(payload)) == payload
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ('{"video_strength": 10}', 10.0),         # int coerced to float
+        ('{"video_strength": "10"}', 10.0),       # numeric string coerced
+        ('{"video_strength": "10.5"}', 10.5),     # decimal string coerced
+        ('{"video_strength": 1e2}', 100.0),       # scientific notation
+        ('{"video_strength": -1.5}', -1.5),       # negatives flow through
+    ],
+)
+def test_numeric_values_are_coerced_to_float(raw, expected):
+    out = parse_relay_overrides(raw)
+    assert out == {"video_strength": expected}
+    assert isinstance(out["video_strength"], float)
+
+
+# ---------------------------------------------------------------------------
+# Comment keys: underscore-prefixed entries are silently dropped.
+# ---------------------------------------------------------------------------
+
+
+def test_underscore_prefixed_keys_are_dropped_silently(caplog):
+    raw = '{"_doc": "trial 3", "_owner": "daisy", "video_strength": 5}'
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides(raw)
+    assert out == {"video_strength": 5.0}
+    # No warning was emitted for the comment keys.
+    assert "unknown keys" not in caplog.text
+
+
+def test_only_comment_keys_returns_none():
+    assert parse_relay_overrides('{"_doc": "no overrides yet"}') is None
+
+
+# ---------------------------------------------------------------------------
+# Unknown keys: warn-and-drop, don't silently misroute the operator's
+# typo into the default-render bucket.
+# ---------------------------------------------------------------------------
+
+
+def test_unknown_key_logs_warning_and_drops_it(caplog):
+    raw = '{"viedo_strength": 10, "video_strength": 2.5}'
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides(raw)
+    assert out == {"video_strength": 2.5}
+    assert "unknown keys" in caplog.text.lower()
+    assert "viedo_strength" in caplog.text
+
+
+def test_only_unknown_keys_returns_none(caplog):
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides('{"bogus": 1, "also_bogus": 2}')
+    assert out is None
+    assert "unknown keys" in caplog.text.lower()
+
+
+# ---------------------------------------------------------------------------
+# H2 — malformed JSON / non-object JSON must raise (not silently use
+# upstream defaults, which previously polluted A/B comparisons).
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '{"video_strength":10.0',     # missing closing brace
+        '{"video_strength": 10,}',    # trailing comma
+        '{video_strength: 10}',       # unquoted key
+        "not json at all",
+    ],
+)
+def test_malformed_json_raises(raw):
+    with pytest.raises(ValueError, match="not valid JSON"):
+        parse_relay_overrides(raw)
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '[1, 2, 3]',                  # array
+        '"video_strength"',           # string
+        "42",                         # number
+        "true",                       # bool
+        "null",                       # null
+    ],
+)
+def test_non_object_json_raises(raw):
+    with pytest.raises(ValueError, match="must be a JSON object"):
+        parse_relay_overrides(raw)
+
+
+# ---------------------------------------------------------------------------
+# H1 — a known knob with a non-numeric value must raise at parse time,
+# not blow up deep inside the sampler arithmetic.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '{"video_strength": "ten"}',
+        '{"video_strength": true}',
+        '{"video_strength": null}',
+        '{"video_strength": [1, 2]}',
+        '{"video_strength": {"nested": 1}}',
+        '{"audio_epsilon": "very small"}',
+    ],
+)
+def test_non_numeric_known_knob_raises(raw):
+    with pytest.raises(ValueError, match="must be a number"):
+        parse_relay_overrides(raw)
+
+
+def test_error_message_names_offending_knob_and_shows_example():
+    """The error message must let the operator fix the widget without
+    consulting upstream Prompt-Relay source."""
+    with pytest.raises(ValueError) as exc:
+        parse_relay_overrides('{"video_window_scale": "narrow"}')
+    msg = str(exc.value)
+    assert "video_window_scale" in msg
+    assert "Example:" in msg
+
+
+# ---------------------------------------------------------------------------
+# Allowlist sanity: documented keys match implementation.
+# ---------------------------------------------------------------------------
+
+
+def test_documented_knob_set_matches_implementation():
+    """If anyone adds a knob in build_segments without updating the
+    allowlist, this test fails — preventing silent typos-disguised-as-
+    knobs that the H1 fix is meant to catch."""
+    assert RELAY_OVERRIDE_KEYS == {
+        "video_strength": float,
+        "video_window_scale": float,
+        "audio_strength": float,
+        "audio_window_scale": float,
+        "audio_epsilon": float,
+    }

ComfyUI/custom_nodes/koolook/tests/forks/test_whatdreamscost_v1_3_9_relay_overrides.py

@@ -0,0 +1,236 @@
+"""Tests for the LTXDirector ``relay_overrides`` widget parser.
+
+These guard the failure modes flagged in the PR #185 verified review
+(H1 — values were never type-checked; H2 — malformed JSON silently fell
+back to upstream defaults and polluted A/B iteration logs). The parser
+lives in
+``forks/whatdreamscost_koolook/versions/v1_3_9/_relay_overrides.py`` —
+deliberately stdlib-only so we can import it here without pulling in
+ComfyUI's ``comfy_api`` runtime (which the rest of ``ltx_director.py``
+needs and which can't run inside pytest).
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+from pathlib import Path
+
+import pytest
+
+
+# Load the parser module by file path. We avoid the normal package import
+# (``from forks.whatdreamscost_koolook... import ...``) because walking
+# into that package triggers ``forks/whatdreamscost_koolook/versions/
+# v1_3_9/__init__.py``, which imports ``ltx_director`` → ``comfy_api`` —
+# ComfyUI-only and unavailable inside pytest. The parser module itself
+# is pure stdlib + logging, so loading it in isolation is fine.
+_RELAY_PATH = (
+    Path(__file__).resolve().parents[2]
+    / "forks"
+    / "whatdreamscost_koolook"
+    / "versions"
+    / "v1_3_9"
+    / "_relay_overrides.py"
+)
+_spec = importlib.util.spec_from_file_location(
+    "whatdreamscost_v1_3_9_relay_overrides", _RELAY_PATH
+)
+_mod = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_mod)
+
+RELAY_OVERRIDE_KEYS = _mod.RELAY_OVERRIDE_KEYS
+parse_relay_overrides = _mod.parse_relay_overrides
+
+
+# ---------------------------------------------------------------------------
+# Silent fallback: only the empty/whitespace case should return None.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("blank", ["", "   ", "\n", "\t \n"])
+def test_empty_or_whitespace_means_use_upstream_defaults(blank):
+    assert parse_relay_overrides(blank) is None
+
+
+# ---------------------------------------------------------------------------
+# Happy path: known knobs with numeric values get coerced to float.
+# ---------------------------------------------------------------------------
+
+
+def test_single_known_knob():
+    out = parse_relay_overrides('{"video_strength": 10.0}')
+    assert out == {"video_strength": 10.0}
+    assert isinstance(out["video_strength"], float)
+
+
+def test_all_known_knobs():
+    payload = {
+        "video_strength": 2.5,
+        "video_window_scale": 0.7,
+        "audio_strength": 0.5,
+        "audio_window_scale": 1.2,
+        "audio_epsilon": 0.001,
+    }
+    assert parse_relay_overrides(json.dumps(payload)) == payload
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ('{"video_strength": 10}', 10.0),         # int coerced to float
+        ('{"video_strength": "10"}', 10.0),       # numeric string coerced
+        ('{"video_strength": "10.5"}', 10.5),     # decimal string coerced
+        ('{"video_strength": 1e2}', 100.0),       # scientific notation
+        ('{"video_strength": -1.5}', -1.5),       # negatives flow through
+    ],
+)
+def test_numeric_values_are_coerced_to_float(raw, expected):
+    out = parse_relay_overrides(raw)
+    assert out == {"video_strength": expected}
+    assert isinstance(out["video_strength"], float)
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "video_strength: 10.0",
+        '"video_strength": 10.0',
+        "video_strength = 10.0",
+        "{\nvideo_strength: 10.0,\nvideo_window_scale: 0.75\n}",
+    ],
+)
+def test_text_multiline_key_value_blocks_are_accepted(raw):
+    out = parse_relay_overrides(raw)
+    assert out["video_strength"] == 10.0
+
+
+def test_stacked_json_objects_are_merged():
+    raw = '{"video_strength": 10.0}\n{"video_window_scale": 0.75}'
+    assert parse_relay_overrides(raw) == {
+        "video_strength": 10.0,
+        "video_window_scale": 0.75,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Comment keys: underscore-prefixed entries are silently dropped.
+# ---------------------------------------------------------------------------
+
+
+def test_underscore_prefixed_keys_are_dropped_silently(caplog):
+    raw = '{"_doc": "trial 3", "_owner": "daisy", "video_strength": 5}'
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides(raw)
+    assert out == {"video_strength": 5.0}
+    # No warning was emitted for the comment keys.
+    assert "unknown keys" not in caplog.text
+
+
+def test_only_comment_keys_returns_none():
+    assert parse_relay_overrides('{"_doc": "no overrides yet"}') is None
+
+
+# ---------------------------------------------------------------------------
+# Unknown keys: warn-and-drop, don't silently misroute the operator's
+# typo into the default-render bucket.
+# ---------------------------------------------------------------------------
+
+
+def test_unknown_key_logs_warning_and_drops_it(caplog):
+    raw = '{"viedo_strength": 10, "video_strength": 2.5}'
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides(raw)
+    assert out == {"video_strength": 2.5}
+    assert "unknown keys" in caplog.text.lower()
+    assert "viedo_strength" in caplog.text
+
+
+def test_only_unknown_keys_returns_none(caplog):
+    with caplog.at_level(logging.WARNING):
+        out = parse_relay_overrides('{"bogus": 1, "also_bogus": 2}')
+    assert out is None
+    assert "unknown keys" in caplog.text.lower()
+
+
+# ---------------------------------------------------------------------------
+# H2 — malformed JSON / non-object JSON must raise (not silently use
+# upstream defaults, which previously polluted A/B comparisons).
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '{"video_strength":10.0',     # missing closing brace
+        "not json at all",
+    ],
+)
+def test_malformed_json_raises(raw):
+    with pytest.raises(ValueError, match="not valid JSON or a supported"):
+        parse_relay_overrides(raw)
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '[1, 2, 3]',                  # array
+        '"video_strength"',           # string
+        "42",                         # number
+        "true",                       # bool
+        "null",                       # null
+    ],
+)
+def test_non_object_json_raises(raw):
+    with pytest.raises(ValueError, match="must be a JSON object"):
+        parse_relay_overrides(raw)
+
+
+# ---------------------------------------------------------------------------
+# H1 — a known knob with a non-numeric value must raise at parse time,
+# not blow up deep inside the sampler arithmetic.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '{"video_strength": "ten"}',
+        '{"video_strength": true}',
+        '{"video_strength": null}',
+        '{"video_strength": [1, 2]}',
+        '{"video_strength": {"nested": 1}}',
+        '{"audio_epsilon": "very small"}',
+    ],
+)
+def test_non_numeric_known_knob_raises(raw):
+    with pytest.raises(ValueError, match="must be a number"):
+        parse_relay_overrides(raw)
+
+
+def test_error_message_names_offending_knob_and_shows_example():
+    """The error message must let the operator fix the widget without
+    consulting upstream Prompt-Relay source."""
+    with pytest.raises(ValueError) as exc:
+        parse_relay_overrides('{"video_window_scale": "narrow"}')
+    msg = str(exc.value)
+    assert "video_window_scale" in msg
+    assert "Example:" in msg
+
+
+# ---------------------------------------------------------------------------
+# Allowlist sanity: documented keys match implementation.
+# ---------------------------------------------------------------------------
+
+
+def test_documented_knob_set_matches_implementation():
+    """If anyone adds a knob in build_segments without updating the
+    allowlist, this test fails — preventing silent typos-disguised-as-
+    knobs that the H1 fix is meant to catch."""
+    assert RELAY_OVERRIDE_KEYS == {
+        "video_strength": float,
+        "video_window_scale": float,
+        "audio_strength": float,
+        "audio_window_scale": float,
+        "audio_epsilon": float,
+    }

ComfyUI/custom_nodes/koolook/tests/js/test_ai_pipeline_preview.mjs

@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+const sourcePath = path.join(repoRoot, "web", "ai_pipeline.js");
+const source = fs.readFileSync(sourcePath, "utf8")
+  .replace(/^import .*;\r?\n/gm, "");
+
+const registeredExtensions = [];
+const context = {
+  bulletproofStringWidget(widget, fallback = "") {
+    if (!widget) return;
+    if (widget.value == null) widget.value = fallback;
+    else if (typeof widget.value !== "string") widget.value = String(widget.value);
+  },
+  app: {
+    graph: null,
+    registerExtension(extension) {
+      registeredExtensions.push(extension);
+    },
+  },
+  ComfyWidgets: {
+    STRING(node) {
+      const previewWidget = {
+        value: "",
+        inputEl: { readOnly: false, style: {} },
+      };
+      node.widgets.push(previewWidget);
+      return {
+        widget: previewWidget,
+      };
+    },
+  },
+  globalThis: {},
+};
+context.globalThis = context;
+
+vm.runInNewContext(source, context, { filename: sourcePath });
+
+const extension = registeredExtensions.find((entry) => entry.name === "koolook.ai_pipeline");
+assert.ok(extension, "AI pipeline extension should register");
+
+function widget(name, value) {
+  return { name, value, inputEl: { readOnly: false, style: {} } };
+}
+
+function makeGraph(nodes, links) {
+  return {
+    _nodes: nodes,
+    _links: Object.fromEntries(links.map((link) => [link.id, link])),
+    getLink(id) {
+      return this._links[id] ?? null;
+    },
+    getNodeById(id) {
+      return this._nodes.find((node) => node.id === id) ?? null;
+    },
+  };
+}
+
+function makePipelineNode(graph) {
+  const buttons = [];
+  return {
+    graph,
+    widgets: [
+      widget("shot_duration", 81),
+      widget("seed_value", 453453453),
+      widget("instruction", "Place your base folder path in the FIELD below"),
+      widget("base_directory_path", "e:/G-Drive-BaconX/Jobs/Jeep_Animals/ComfyUI_LTX23"),
+      widget("extension", ".%04d.exr"),
+      widget("shot_name", "stale_widget_name"),
+      widget("ai_method", ""),
+      widget("version", "001"),
+      widget("disable_versioning", false),
+      widget("enable_overwrite", false),
+      widget("no_subfolders", false),
+    ],
+    inputs: [
+      { name: "shot_duration", link: null, widget: { name: "shot_duration" } },
+      { name: "seed_value", link: null, widget: { name: "seed_value" } },
+      { name: "instruction", link: null, widget: { name: "instruction" } },
+      { name: "base_directory_path", link: null, widget: { name: "base_directory_path" } },
+      { name: "extension", link: null, widget: { name: "extension" } },
+      { name: "shot_name", link: 13, widget: { name: "shot_name" } },
+      { name: "ai_method", link: null, widget: { name: "ai_method" } },
+      { name: "version", link: 14, widget: { name: "version" } },
+      { name: "disable_versioning", link: null, widget: { name: "disable_versioning" } },
+      { name: "enable_overwrite", link: null, widget: { name: "enable_overwrite" } },
+      { name: "no_subfolders", link: null, widget: { name: "no_subfolders" } },
+    ],
+    outputs: [],
+    addWidget(type, name, value, callback) {
+      const button = { type, name, value, callback };
+      buttons.push(button);
+      return button;
+    },
+    setDirtyCanvas() {},
+    buttons,
+  };
+}
+
+const namePart = {
+  id: 1,
+  type: "Text Multiline",
+  widgets_values: ["Bear_3x-FR_w.Audio"],
+  outputs: [{ name: "STRING", type: "STRING", links: [11] }],
+};
+const suffixPart = {
+  id: 2,
+  type: "Text Multiline",
+  widgets_values: ["EXR"],
+  outputs: [{ name: "STRING", type: "STRING", links: [12] }],
+};
+const concat = {
+  id: 3,
+  type: "Text Concatenate",
+  widgets_values: ["_", "true"],
+  inputs: [
+    { name: "text_a", type: "STRING", link: 11 },
+    { name: "text_b", type: "STRING", link: 12 },
+    { name: "text_c", type: "STRING", link: null },
+    { name: "text_d", type: "STRING", link: null },
+  ],
+  outputs: [{ name: "STRING", type: "STRING", links: [13] }],
+};
+const versionSource = {
+  id: 4,
+  type: "Text Multiline",
+  widgets_values: ["003"],
+  outputs: [{ name: "STRING", type: "STRING", links: [14] }],
+};
+
+const graph = makeGraph(
+  [namePart, suffixPart, concat, versionSource],
+  [
+    { id: 11, origin_id: 1, origin_slot: 0, target_id: 3, target_slot: 0, type: "STRING" },
+    { id: 12, origin_id: 2, origin_slot: 0, target_id: 3, target_slot: 1, type: "STRING" },
+    { id: 13, origin_id: 3, origin_slot: 0, target_id: 99, target_slot: 5, type: "STRING" },
+    { id: 14, origin_id: 4, origin_slot: 0, target_id: 99, target_slot: 7, type: "STRING" },
+  ],
+);
+context.app.graph = graph;
+
+function previewFilePath() {
+  const nodeType = function EasyAIPipelineNode() {};
+  extension.beforeRegisterNodeDef(nodeType, { name: "EasyAIPipeline" });
+  const node = makePipelineNode(graph);
+  nodeType.prototype.onNodeCreated.call(node);
+  const button = node.buttons.find((entry) => entry.name === "Get output file path");
+  assert.ok(button, "preview file-path button should exist");
+  button.callback();
+  return node.widgets.find((entry) => entry.inputEl?.readOnly && entry.inputEl?.style?.height === "100px").value;
+}
+
+const expected = "e:/G-Drive-BaconX/Jobs/Jeep_Animals/ComfyUI_LTX23/Bear_3x-FR_w.Audio_EXR/v003/Bear_3x-FR_w.Audio_EXR_v003.%04d.exr";
+
+const first = previewFilePath();
+const second = previewFilePath();
+
+assert.equal(first, expected);
+assert.equal(second, expected);
+assert.ok(!first.includes("/_/"), "Text Concatenate delimiter must not replace the shot name");
+assert.ok(!first.includes("__"), "empty fields must not multiply underscores");
+assert.ok(!first.includes("vv003"), "already-normalized version tokens must not get an extra v");
+
+{
+  const publishOutput = {
+    id: 10,
+    type: "Koolook_PublishOutput",
+    widgets: [
+      widget("folder", "/Volumes/Data/G-Drive-BaconX/Jobs/OndtBlod/001_0035/ai/publish-OUT"),
+      widget("name", "publish-OUT"),
+      widget("version", "1"),
+    ],
+    outputs: [
+      { name: "folder", type: "STRING", links: [30] },
+      { name: "name", type: "STRING", links: [] },
+      { name: "version", type: "STRING", links: [] },
+    ],
+  };
+  const reroute = {
+    id: 11,
+    type: "Reroute",
+    inputs: [{ name: "", type: "STRING", link: 30 }],
+    outputs: [{ name: "", type: "STRING", links: [31] }],
+  };
+  const publishGraph = makeGraph(
+    [publishOutput, reroute],
+    [
+      { id: 30, origin_id: 10, origin_slot: 0, target_id: 11, target_slot: 0, type: "STRING" },
+      { id: 31, origin_id: 11, origin_slot: 0, target_id: 99, target_slot: 3, type: "STRING" },
+    ],
+  );
+  context.app.graph = publishGraph;
+
+  const nodeType = function EasyAIPipelineNode() {};
+  extension.beforeRegisterNodeDef(nodeType, { name: "EasyAIPipeline" });
+  const node = makePipelineNode(publishGraph);
+  node.inputs.find((input) => input.name === "base_directory_path").link = 31;
+  node.inputs.find((input) => input.name === "shot_name").link = null;
+  node.inputs.find((input) => input.name === "version").link = null;
+  node.widgets.find((entry) => entry.name === "shot_name").value = "mask";
+  node.widgets.find((entry) => entry.name === "version").value = "1";
+  node.widgets.find((entry) => entry.name === "no_subfolders").value = true;
+  nodeType.prototype.onNodeCreated.call(node);
+  const button = node.buttons.find((entry) => entry.name === "Get output directory path");
+  assert.ok(button, "preview directory button should exist");
+  button.callback();
+
+  const preview = node.widgets.find((entry) => entry.inputEl?.readOnly && entry.inputEl?.style?.height === "100px").value;
+  assert.equal(
+    preview,
+    "/Volumes/Data/G-Drive-BaconX/Jobs/OndtBlod/001_0035/ai/publish-OUT/v001",
+  );
+}

ComfyUI/custom_nodes/koolook/tests/js/test_draft_guard.mjs

@@ -0,0 +1,373 @@
+// Behavior tests for web/koolook_draft_guard.js — the generation-agnostic
+// guard around ComfyUI's browser-side workflow draft storage.
+//
+// Black-box: each scenario builds a fake quota-enforcing localStorage,
+// seeds it with draft keys from one or more storage generations, loads the
+// guard source in an isolated vm context (which runs the boot prune and
+// installs the setItem wrapper, exactly like a real page load), then
+// asserts on the resulting storage state / thrown errors / toasts.
+//
+// Storage generations modelled here (see the guard's header comment):
+//   V1  unsuffixed   Comfy.Workflow.Drafts / Comfy.Workflow.DraftOrder
+//   V1  per-workspace ...Drafts:<ws> / ...DraftOrder:<ws>
+//   V2  (1.44+)      Comfy.Workflow.DraftIndex.v2:<ws> + Comfy.Workflow.Draft.v2:<ws>:<hash>
+//
+// Run: node tests/js/test_draft_guard.mjs
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+const sourcePath = path.join(repoRoot, "web", "koolook_draft_guard.js");
+const source = fs.readFileSync(sourcePath, "utf8");
+
+const V1_DRAFTS = "Comfy.Workflow.Drafts";
+const V1_ORDER = "Comfy.Workflow.DraftOrder";
+const v2Index = (ws) => `Comfy.Workflow.DraftIndex.v2:${ws}`;
+const v2Payload = (ws, hash) => `Comfy.Workflow.Draft.v2:${ws}:${hash}`;
+
+function makeLocalStorage(initialQuota = Infinity) {
+  const map = new Map();
+  let quota = initialQuota;
+  const used = () => {
+    let total = 0;
+    for (const [k, v] of map) total += k.length + v.length;
+    return total;
+  };
+  return {
+    getItem(k) {
+      k = String(k);
+      return map.has(k) ? map.get(k) : null;
+    },
+    setItem(k, v) {
+      k = String(k);
+      v = String(v);
+      const current = map.has(k) ? k.length + map.get(k).length : 0;
+      if (used() - current + k.length + v.length > quota) {
+        throw new DOMException("Simulated quota exceeded", "QuotaExceededError");
+      }
+      map.set(k, v);
+    },
+    removeItem(k) {
+      map.delete(String(k));
+    },
+    key(i) {
+      return [...map.keys()][i] ?? null;
+    },
+    get length() {
+      return map.size;
+    },
+    __map: map,
+    __used: used,
+    __setQuota(n) {
+      quota = n;
+    },
+  };
+}
+
+function loadGuard(store, { toasts = [], warns = [], context = null } = {}) {
+  const ctx = context ?? {
+    localStorage: store,
+    DOMException,
+    setTimeout: () => 0,
+    document: {
+      createElement: () => ({ textContent: "", style: {}, remove() {} }),
+      body: { appendChild: (el) => toasts.push(el.textContent) },
+    },
+    console: {
+      warn: (...args) => warns.push(args.map(String).join(" ")),
+      log() {},
+      error() {},
+    },
+  };
+  ctx.globalThis = ctx;
+  vm.runInNewContext(source, ctx, { filename: sourcePath });
+  return ctx;
+}
+
+function seedV1(store, suffix, entries) {
+  const drafts = {};
+  const order = [];
+  for (const [p, data, updatedAt] of entries) {
+    drafts[p] = { data, updatedAt, name: p, isTemporary: false };
+    order.push(p);
+  }
+  store.setItem(V1_DRAFTS + suffix, JSON.stringify(drafts));
+  store.setItem(V1_ORDER + suffix, JSON.stringify(order));
+}
+
+function seedV2(store, ws, entries) {
+  const index = { v: 2, updatedAt: 1, order: [], entries: {} };
+  for (const [hash, data, updatedAt] of entries) {
+    index.order.push(hash);
+    index.entries[hash] = { name: hash, isTemporary: false, updatedAt, path: `workflows/${hash}.json` };
+    store.setItem(v2Payload(ws, hash), JSON.stringify({ data, updatedAt }));
+  }
+  store.setItem(v2Index(ws), JSON.stringify(index));
+}
+
+function v1Paths(store, suffix = "") {
+  const raw = store.getItem(V1_DRAFTS + suffix);
+  return raw === null ? null : Object.keys(JSON.parse(raw));
+}
+
+// ---------------------------------------------------------------------------
+// S1: wrapper installs once; a second load (stale copy scenario) is a no-op.
+{
+  const store = makeLocalStorage();
+  const nativeSetItem = store.setItem;
+  const ctx = loadGuard(store);
+  assert.notEqual(store.setItem, nativeSetItem, "setItem should be wrapped after load");
+  const firstWrapper = store.setItem;
+  loadGuard(store, { context: ctx });
+  assert.equal(store.setItem, firstWrapper, "second install must not re-wrap (sentinel)");
+}
+
+// ---------------------------------------------------------------------------
+// S2: quota error on a NON-draft key is rethrown untouched; no draft evicted.
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [["wf-a", "x".repeat(200), 10]]);
+  const toasts = [];
+  loadGuard(store, { toasts });
+  store.__setQuota(store.__used() + 50);
+  assert.throws(
+    () => store.setItem("koolook.workflows.fallback.v1", "y".repeat(5000)),
+    (err) => err instanceof DOMException && err.name === "QuotaExceededError",
+    "non-draft quota error must propagate",
+  );
+  assert.deepEqual(v1Paths(store), ["wf-a"], "draft entries must not be touched");
+  assert.equal(toasts.length, 0, "no toast for non-draft failures");
+}
+
+// ---------------------------------------------------------------------------
+// S3: the live bug — a V2 payload write is rescued by evicting old V1 drafts.
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [
+    ["wf-old", "x".repeat(300), 10],
+    ["wf-new", "y".repeat(300), 20],
+  ]);
+  seedV2(store, "personal", [["aaaa1111", "z".repeat(100), 30]]);
+  const toasts = [];
+  loadGuard(store, { toasts });
+
+  const key = v2Payload("personal", "bbbb2222");
+  const value = JSON.stringify({ data: "w".repeat(220), updatedAt: 40 });
+  store.__setQuota(store.__used() + key.length + value.length - 1);
+
+  store.setItem(key, value); // must not throw
+  assert.equal(store.getItem(key), value, "new V2 payload must be written");
+  assert.deepEqual(v1Paths(store), ["wf-new"], "oldest V1 draft must be evicted first");
+  assert.ok(
+    store.getItem(v2Payload("personal", "aaaa1111")) !== null,
+    "newer V2 payload must survive",
+  );
+  assert.equal(toasts.length, 1, "one rescue toast per page session");
+  assert.match(toasts[0], /removed the oldest/i);
+}
+
+// ---------------------------------------------------------------------------
+// S4: eviction picks the OLDEST draft across generations (V2 older than V1).
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [["wf-v1", "x".repeat(150), 100]]);
+  seedV2(store, "personal", [
+    ["old00001", "a".repeat(150), 50],
+    ["new00001", "b".repeat(150), 200],
+  ]);
+  loadGuard(store);
+
+  const key = v2Payload("personal", "cccc3333");
+  const value = JSON.stringify({ data: "c".repeat(60), updatedAt: 300 });
+  store.__setQuota(store.__used() + key.length + value.length - 1);
+
+  store.setItem(key, value);
+  assert.equal(store.getItem(v2Payload("personal", "old00001")), null, "oldest (V2, age 50) evicted");
+  assert.deepEqual(v1Paths(store), ["wf-v1"], "younger V1 draft survives");
+  assert.ok(store.getItem(v2Payload("personal", "new00001")) !== null, "younger V2 payload survives");
+  const index = JSON.parse(store.getItem(v2Index("personal")));
+  assert.ok(!index.order.includes("old00001"), "V2 index order drops the evicted hash");
+  assert.ok(!("old00001" in index.entries), "V2 index entries drop the evicted hash");
+}
+
+// ---------------------------------------------------------------------------
+// S5: boot prune deletes suffixed-V1 families superseded by a V2 index,
+//     keeps families that are still that workspace's only draft store.
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [["wf-root", "r".repeat(50), 5]]);
+  seedV1(store, ":wsA", [["wf-a", "a".repeat(50), 5]]);
+  seedV2(store, "wsA", [["aaaa0001", "p".repeat(50), 6]]);
+  seedV1(store, ":wsB", [["wf-b", "b".repeat(50), 5]]);
+  loadGuard(store);
+
+  assert.equal(store.getItem(V1_DRAFTS + ":wsA"), null, "migrated V1 family is dead weight");
+  assert.equal(store.getItem(V1_ORDER + ":wsA"), null, "migrated V1 order key removed too");
+  assert.notEqual(store.getItem(V1_DRAFTS + ":wsB"), null, "unmigrated workspace keeps its V1 family");
+  assert.deepEqual(v1Paths(store), ["wf-root"], "unsuffixed V1 family untouched");
+  assert.notEqual(store.getItem(v2Index("wsA")), null, "V2 index untouched");
+}
+
+// ---------------------------------------------------------------------------
+// S6: boot prune drops oversized entries (per-entry cap) in both generations.
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [
+    ["wf-huge", "h".repeat(800_000), 10],
+    ["wf-ok", "o".repeat(100), 20],
+  ]);
+  seedV2(store, "personal", [
+    ["huge0001", "H".repeat(800_000), 10],
+    ["fine0001", "f".repeat(100), 20],
+  ]);
+  loadGuard(store);
+
+  assert.deepEqual(v1Paths(store), ["wf-ok"], "oversized V1 entry dropped, sibling kept");
+  assert.equal(store.getItem(v2Payload("personal", "huge0001")), null, "oversized V2 payload dropped");
+  assert.notEqual(store.getItem(v2Payload("personal", "fine0001")), null, "small V2 payload kept");
+}
+
+// ---------------------------------------------------------------------------
+// S7: boot prune enforces the total draft budget, oldest first.
+{
+  const store = makeLocalStorage();
+  seedV2(store, "personal", [
+    ["aged0001", "a".repeat(700_000), 1],
+    ["aged0002", "b".repeat(700_000), 2],
+    ["aged0003", "c".repeat(700_000), 3],
+  ]);
+  const warns = [];
+  loadGuard(store, { warns });
+
+  assert.equal(store.getItem(v2Payload("personal", "aged0001")), null, "oldest payload evicted");
+  assert.notEqual(store.getItem(v2Payload("personal", "aged0002")), null, "second-oldest survives");
+  assert.notEqual(store.getItem(v2Payload("personal", "aged0003")), null, "newest survives");
+  assert.ok(
+    warns.some((w) => w.includes("[Koolook draft-guard]")),
+    "prune logs what it did",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// S8: a corrupt draft key is removed without touching other generations.
+{
+  const store = makeLocalStorage();
+  store.setItem(V1_DRAFTS, "{not json");
+  store.setItem(V1_ORDER, "[]");
+  seedV2(store, "personal", [["good0001", "g".repeat(100), 10]]);
+  loadGuard(store);
+
+  assert.equal(store.getItem(V1_DRAFTS), null, "corrupt V1 blob removed");
+  assert.equal(store.getItem(V1_ORDER), null, "its order twin removed");
+  assert.notEqual(store.getItem(v2Payload("personal", "good0001")), null, "V2 untouched");
+}
+
+// ---------------------------------------------------------------------------
+// S9a: unknown future draft keys are NOT evicted while structured candidates
+//      remain...
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [
+    ["wf-old", "x".repeat(300), 10],
+    ["wf-new", "y".repeat(300), 20],
+  ]);
+  store.setItem("Comfy.Workflow.DraftCache.v3:future", "F".repeat(120));
+  loadGuard(store);
+
+  const key = v2Payload("personal", "dddd4444");
+  const value = JSON.stringify({ data: "d".repeat(80), updatedAt: 99 });
+  store.__setQuota(store.__used() + key.length + value.length - 1);
+  store.setItem(key, value);
+
+  assert.notEqual(store.getItem("Comfy.Workflow.DraftCache.v3:future"), null, "future key kept");
+  assert.deepEqual(v1Paths(store), ["wf-new"], "structured candidate evicted instead");
+}
+
+// S9b: ...but ARE evicted as a last resort, so a future frontend rename
+//      cannot brick draft saves again.
+{
+  const store = makeLocalStorage();
+  store.setItem("Comfy.Workflow.DraftCache.v3:future", "F".repeat(400));
+  loadGuard(store);
+
+  const key = v2Payload("personal", "eeee5555");
+  const value = JSON.stringify({ data: "e".repeat(200), updatedAt: 99 });
+  store.__setQuota(store.__used() + key.length + value.length - 1);
+  store.setItem(key, value);
+
+  assert.equal(store.getItem("Comfy.Workflow.DraftCache.v3:future"), null, "future key evicted last-resort");
+  assert.equal(store.getItem(key), value, "write rescued");
+}
+
+// ---------------------------------------------------------------------------
+// S10: when nothing can be evicted, the original quota error propagates and
+//      the user gets the "still full" toast.
+{
+  const store = makeLocalStorage();
+  store.setItem("someone.elses.data", "Z".repeat(500));
+  const toasts = [];
+  loadGuard(store, { toasts });
+  store.__setQuota(store.__used() + 20);
+
+  const key = v2Payload("personal", "ffff6666");
+  assert.throws(
+    () => store.setItem(key, "f".repeat(100)),
+    (err) => err instanceof DOMException && err.name === "QuotaExceededError",
+    "unrescuable write rethrows the quota error",
+  );
+  // A second failing write in the same session still throws but must NOT
+  // re-toast — otherwise a genuinely-full origin gets per-edit toast spam.
+  assert.throws(
+    () => store.setItem(key, "f".repeat(100)),
+    (err) => err instanceof DOMException && err.name === "QuotaExceededError",
+    "repeat unrescuable write still rethrows",
+  );
+  assert.equal(
+    toasts.filter((t) => /still full/i.test(t)).length,
+    1,
+    "still-full toast is latched once per session",
+  );
+  assert.notEqual(store.getItem("someone.elses.data"), null, "non-draft data never touched");
+}
+
+// ---------------------------------------------------------------------------
+// S11: a pre-set sentinel (older guard copy already installed) skips the
+//      wrapper but the boot prune still runs.
+{
+  const store = makeLocalStorage();
+  store.__koolookDraftQuotaGuardInstalled = true;
+  const nativeSetItem = store.setItem;
+  seedV1(store, ":wsA", [["wf-a", "a".repeat(50), 5]]);
+  seedV2(store, "wsA", [["aaaa0001", "p".repeat(50), 6]]);
+  loadGuard(store);
+
+  assert.equal(store.setItem, nativeSetItem, "wrapper must not double-install");
+  assert.equal(store.getItem(V1_DRAFTS + ":wsA"), null, "boot prune still runs");
+}
+
+// ---------------------------------------------------------------------------
+// S12: when the failing write IS a draft container (V1 blob growing), prefer
+//      freeing OTHER keys — rewriting the target key smaller cannot help,
+//      because the retry overwrites it with the same big value anyway.
+{
+  const store = makeLocalStorage();
+  seedV1(store, "", [["wf-keep", "k".repeat(200), 5]]); // older than the V2 entry
+  seedV2(store, "personal", [["gggg7777", "g".repeat(200), 50]]);
+  loadGuard(store);
+
+  const grown = JSON.stringify({
+    "wf-keep": { data: "k".repeat(200), updatedAt: 5, name: "wf-keep", isTemporary: false },
+    "wf-added": { data: "n".repeat(120), updatedAt: 60, name: "wf-added", isTemporary: false },
+  });
+  const delta = grown.length - store.getItem(V1_DRAFTS).length;
+  store.__setQuota(store.__used() + delta - 1);
+
+  store.setItem(V1_DRAFTS, grown);
+  assert.equal(store.getItem(V1_DRAFTS), grown, "grown V1 blob written intact");
+  assert.equal(store.getItem(v2Payload("personal", "gggg7777")), null, "space freed from another key");
+}
+
+console.log("test_draft_guard.mjs: all scenarios passed");

ComfyUI/custom_nodes/koolook/tests/js/test_update_check.mjs

@@ -0,0 +1,89 @@
+// Behavior tests for the sidebar update-available check.
+
+import assert from "node:assert/strict";
+import path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+const updateCheck = await import(
+  `file:///${path.join(repoRoot, "web", "sidebar", "update_check.js").replaceAll("\\", "/")}`
+);
+
+function jsonResponse(body, ok = true) {
+  return {
+    ok,
+    async json() {
+      return body;
+    },
+  };
+}
+
+assert.equal(updateCheck.compareSemver("0.4.1", "0.4.0"), 1);
+assert.equal(updateCheck.compareSemver("v0.4.0", "0.4.0"), 0);
+assert.equal(updateCheck.compareSemver("0.3.9", "0.4.0"), -1);
+assert.equal(updateCheck.compareSemver("0.4.0", "0.4.0-rc.1"), 1);
+assert.equal(updateCheck.compareSemver("not-a-version", "0.4.0"), 0);
+
+{
+  const calls = [];
+  const update = await updateCheck.checkForUpdate(async (url) => {
+    calls.push(String(url));
+    if (calls.length === 1) {
+      assert.ok(calls[0].startsWith("/koolook/api/version?_="));
+      return jsonResponse({
+        version: "0.4.0",
+        latestReleaseApiUrl: "https://api.example.test/latest",
+      });
+    }
+    assert.equal(url, "https://api.example.test/latest");
+    return jsonResponse({
+      tag_name: "v0.4.1",
+      html_url: "https://github.com/malkuthro/ComfyUI-Koolook/releases/tag/v0.4.1",
+    });
+  });
+  assert.deepEqual(update, {
+    current: "0.4.0",
+    latest: "0.4.1",
+    url: "https://github.com/malkuthro/ComfyUI-Koolook/releases/tag/v0.4.1",
+  });
+}
+
+{
+  let calls = 0;
+  const update = await updateCheck.checkForUpdate(async () => {
+    calls += 1;
+    if (calls === 1) return jsonResponse({ version: "0.4.0" });
+    return jsonResponse({
+      tag_name: "v0.4.1",
+      html_url: "https://github.example.test/releases/v0.4.1",
+    });
+  });
+  assert.deepEqual(update, {
+    current: "0.4.0",
+    latest: "0.4.1",
+    url: "https://github.com/malkuthro/ComfyUI-Koolook/releases/tag/v0.4.1",
+  });
+}
+
+{
+  const update = await updateCheck.checkForUpdate(async () => jsonResponse({ version: "0.4.0" }));
+  assert.equal(update, null);
+}
+
+{
+  let calls = 0;
+  const update = await updateCheck.checkForUpdate(async () => {
+    calls += 1;
+    if (calls === 1) return jsonResponse({ version: "0.4.0" });
+    return jsonResponse({ tag_name: "v0.4.0", html_url: "https://example.test/current" });
+  });
+  assert.equal(update, null);
+}
+
+{
+  const update = await updateCheck.checkForUpdate(async () => {
+    throw new Error("offline");
+  });
+  assert.equal(update, null);
+}
+
+console.log("test_update_check.mjs: all scenarios passed");

ComfyUI/custom_nodes/koolook/tests/nodes/test_easy_ai_pipeline.py

@@ -0,0 +1,773 @@
+"""Path-input hardening for ``EasyAIPipeline.generate_pipeline``.
+
+The base directory widget accepts whatever the user pastes, and real users
+paste in wildly different shapes: Windows Explorer's address bar ends paths
+in ``\\``, ``Shift+Right-click → Copy as path`` wraps the result in ``"..."``,
+Linux/Mac habits append ``/``, sloppy copy-paste leaves stray whitespace,
+and so on.
+
+Every variation has to land in the same canonical ``output_directory``. If
+a trailing separator leaks through, some downstream save nodes split on
+``/``, stringify the empty tail as ``"undefined"``, and write into
+``…/undefined/…`` on disk — a phantom folder that the user never asked
+for. These tests pin both the pure ``_normalize_base_path`` helper and the
+end-to-end ``generate_pipeline`` behavior so the bug can't regress.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from k_ai_pipeline import (
+    EasyAIPipeline,
+    _normalize_base_path,
+    _normalize_text_input,
+    _sanitize_segment,
+    _strip_sentinel_components,
+    _strip_control_chars,
+)
+
+
+# ---------------------------------------------------------------------------
+# _normalize_base_path — pure helper, no filesystem dependency
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeBasePath:
+    def test_clean_input_unchanged(self):
+        assert _normalize_base_path("n:\\foo\\bar") == "n:\\foo\\bar"
+        assert _normalize_base_path("/home/user/proj") == "/home/user/proj"
+
+    def test_trailing_backslash_stripped(self):
+        assert _normalize_base_path("n:\\foo\\bar\\") == "n:\\foo\\bar"
+
+    def test_trailing_forward_slash_stripped(self):
+        assert _normalize_base_path("/n/foo/bar/") == "/n/foo/bar"
+
+    def test_multiple_trailing_separators_stripped(self):
+        assert _normalize_base_path("n:\\foo\\bar\\\\") == "n:\\foo\\bar"
+        assert _normalize_base_path("/n/foo/bar///") == "/n/foo/bar"
+
+    def test_mixed_trailing_separators_stripped(self):
+        """A path can end in a mix of forward and backward slashes if the
+        user copy-pasted from two different sources."""
+        assert _normalize_base_path("n:/foo/bar\\/\\") == "n:/foo/bar"
+
+    def test_surrounding_whitespace_stripped(self):
+        assert _normalize_base_path("  n:\\foo\\bar  ") == "n:\\foo\\bar"
+
+    def test_surrounding_double_quotes_stripped(self):
+        """``Shift+Right-click → Copy as path`` in Windows Explorer wraps
+        the result in double quotes."""
+        assert _normalize_base_path('"n:\\foo\\bar"') == "n:\\foo\\bar"
+
+    def test_surrounding_single_quotes_stripped(self):
+        assert _normalize_base_path("'n:/foo/bar'") == "n:/foo/bar"
+
+    def test_quotes_and_inner_trailing_separator_combined(self):
+        """A user might paste a quote-wrapped path that also carries the
+        Explorer trailing backslash — both layers should peel off."""
+        assert _normalize_base_path('"n:\\foo\\bar\\"') == "n:\\foo\\bar"
+        assert _normalize_base_path('  "n:/foo/bar/"  ') == "n:/foo/bar"
+
+    def test_drive_root_preserved(self):
+        """``C:\\`` (drive root) must NOT collapse to ``C:`` — the latter
+        means "current directory on C: drive", not the drive root itself.
+        Same for ``n:/``."""
+        assert _normalize_base_path("C:\\") == "C:\\"
+        assert _normalize_base_path("n:/") == "n:/"
+
+    def test_unmatched_quotes_passed_through(self):
+        """Only strip quotes when BOTH ends match. A single dangling quote
+        is probably part of the path, not a wrapper."""
+        assert _normalize_base_path('"n:\\foo') == '"n:\\foo'
+        assert _normalize_base_path("n:\\foo'") == "n:\\foo'"
+        assert _normalize_base_path("\"n:\\foo'") == "\"n:\\foo'"
+
+    def test_empty_string_passes_through(self):
+        assert _normalize_base_path("") == ""
+        assert _normalize_base_path("   ") == ""
+
+
+# ---------------------------------------------------------------------------
+# _normalize_text_input - sentinel strings from ComfyUI widgets
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeTextInput:
+    def test_empty_inputs(self):
+        assert _normalize_text_input("") == ""
+        assert _normalize_text_input("   ") == ""
+        assert _normalize_text_input(None) == ""
+
+    def test_frontend_sentinel_strings_become_empty(self):
+        assert _normalize_text_input("undefined") == ""
+        assert _normalize_text_input("Undefined") == ""
+        assert _normalize_text_input("UNDEFINED") == ""
+        assert _normalize_text_input("null") == ""
+        assert _normalize_text_input("None") == ""
+        assert _normalize_text_input("  undefined  ") == ""
+
+    def test_real_values_pass_through(self):
+        assert _normalize_text_input("LTX-Director-2K") == "LTX-Director-2K"
+        assert _normalize_text_input("undefined_path") == "undefined_path"
+        assert _normalize_text_input("my_null_clip") == "my_null_clip"
+
+
+class TestStripSentinelComponents:
+    def test_strips_exact_sentinel_path_component(self):
+        assert _strip_sentinel_components("n:/base/undefined/shot") == "n:/base/shot"
+        assert _strip_sentinel_components("n:\\base\\undefined\\shot") == "n:\\base\\shot"
+
+    def test_strips_other_frontend_sentinels(self):
+        assert _strip_sentinel_components("n:/base/null/shot") == "n:/base/shot"
+        assert _strip_sentinel_components("n:/base/None/shot") == "n:/base/shot"
+
+    def test_keeps_real_substring_values(self):
+        assert _strip_sentinel_components("n:/base/undefined_path/shot") == "n:/base/undefined_path/shot"
+        assert _strip_sentinel_components("n:/base/my_null_clip/shot") == "n:/base/my_null_clip/shot"
+
+
+# ---------------------------------------------------------------------------
+# generate_pipeline — end-to-end behavior with realistic inputs
+# ---------------------------------------------------------------------------
+
+
+def _run(base_directory_path: str, **overrides):
+    """Run ``EasyAIPipeline.generate_pipeline`` with sensible defaults and
+    return ``(file_path, output_name, version_string, output_directory)``,
+    which is what the bug-area assertions actually care about."""
+    defaults = dict(
+        shot_duration=81,
+        seed_value=453453453,
+        instruction="(ignored)",
+        base_directory_path=base_directory_path,
+        extension=".%04d.exr",
+        shot_name="LTX-Director-2k_base",
+        ai_method="",
+        version=1,
+        disable_versioning=True,
+        enable_overwrite=False,
+        no_subfolders=False,
+    )
+    defaults.update(overrides)
+    result = EasyAIPipeline().generate_pipeline(**defaults)
+    file_path, output_name, version_string, output_directory = result[:4]
+    return file_path, output_name, version_string, output_directory
+
+
+# Variations the user might realistically paste into the widget. Each must
+# canonicalise to the same output_directory as the bare ``{base}`` form.
+PASTE_VARIANTS = [
+    "{base}",                # clean
+    "{base}\\",              # Explorer address-bar trailing backslash
+    "{base}/",               # POSIX trailing slash
+    "{base}\\\\",            # accidental double backslash
+    "{base}//",              # accidental double forward slash
+    "{base}\\/",             # mixed trailing separators
+    "  {base}  ",            # sloppy whitespace
+    "  {base}\\  ",          # whitespace + trailing backslash
+    '"{base}"',              # Shift+Right-click → Copy as path
+    '"{base}\\"',            # quoted AND trailing backslash
+    "'{base}'",              # single-quoted
+]
+
+
+@pytest.mark.parametrize("variant", PASTE_VARIANTS)
+def test_output_directory_canonical_across_paste_variations(tmp_path: Path, variant: str):
+    """No matter how the user pastes the base path, ``output_directory``
+    must be identical to the clean-input form. This is the contract that
+    prevents downstream save nodes from receiving subtly different paths
+    based on irrelevant whitespace/quoting/trailing-slash differences."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, _, _, out = _run(variant.format(base=base))
+
+    expected = f"{canonical}/LTX-Director-2k_base"
+    assert out == expected, f"variant={variant!r} produced {out!r}, expected {expected!r}"
+
+
+@pytest.mark.parametrize("variant", PASTE_VARIANTS)
+def test_output_directory_never_has_trailing_separator(tmp_path: Path, variant: str):
+    """Belt-and-suspenders: regardless of which variation the user pastes,
+    ``output_directory`` (slot 3 of the returns tuple) must never end with
+    ``/`` or ``\\``. A trailing separator here is exactly what triggers the
+    downstream ``undefined/`` phantom-folder bug."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    _, _, _, out = _run(variant.format(base=base))
+
+    assert not out.endswith(("/", "\\")), f"variant={variant!r} → {out!r}"
+
+
+@pytest.mark.parametrize("variant", PASTE_VARIANTS)
+def test_write_file_path_clean_across_paste_variations(tmp_path: Path, variant: str):
+    """``WRITE_file_path`` (slot 0) is the string downstream savers actually
+    consume. It must never contain ``//``, ``undefined``, or a trailing
+    separator regardless of how the base was pasted."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    file_path, _, _, _ = _run(variant.format(base=base))
+
+    assert "//" not in file_path, f"variant={variant!r} → {file_path!r}"
+    assert "undefined" not in file_path, f"variant={variant!r} → {file_path!r}"
+    assert not file_path.endswith(("/", "\\")), f"variant={variant!r} → {file_path!r}"
+    assert file_path.endswith(".%04d.exr"), f"variant={variant!r} → {file_path!r}"
+
+
+def test_no_subfolders_also_canonicalises_trailing(tmp_path: Path):
+    """With ``no_subfolders=True``, ``output_directory`` IS the (normalised)
+    base path. The trailing-sep strip must still apply, otherwise no-subfolders
+    mode would still leak ``undefined/`` downstream."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, _, _, with_slash = _run(f"{base}\\", no_subfolders=True)
+    _, _, _, without_slash = _run(str(base), no_subfolders=True)
+
+    assert with_slash == without_slash == canonical
+
+
+def test_trailing_base_with_undefined_shot_name_does_not_create_phantom_folder():
+    """Exact maintainer regression: trailing separator on the base path plus
+    a frontend sentinel in shot_name used to yield
+    base/undefined/LTX-Director-2K/... instead of base/LTX-Director-2K/....
+    """
+    base = r"n:\TRK_sync_BIG_N\JOBS\baconx\Jeep_Animals\bear\ComfyUI-working-folder"
+
+    file_path, name, _, output_directory = _run(
+        base + "\\",
+        shot_name="undefined",
+        ai_method="LTX-Director-2K",
+        disable_versioning=True,
+        no_subfolders=False,
+    )
+
+    expected_dir = "n:/TRK_sync_BIG_N/JOBS/baconx/Jeep_Animals/bear/ComfyUI-working-folder/LTX-Director-2K"
+    assert output_directory == expected_dir
+    assert name == "LTX-Director-2K.%04d.exr"
+    assert file_path == f"{expected_dir}/LTX-Director-2K.%04d.exr"
+    assert "/undefined/" not in file_path
+
+
+def test_undefined_component_in_backend_base_path_is_stripped():
+    """When base_directory_path is connected, the backend may receive the
+    executed upstream value rather than the visible widget value the preview
+    button can inspect. Strip sentinel components from the whole path too.
+    """
+    base = "n:/TRK_sync_BIG_N/JOBS/baconx/Jeep_Animals/bear/ComfyUI-working-folder/undefined"
+
+    file_path, name, _, output_directory = _run(
+        base,
+        shot_name="LTX-Director-2K",
+        ai_method="",
+        version=1,
+        disable_versioning=False,
+        no_subfolders=False,
+    )
+
+    expected_dir = "n:/TRK_sync_BIG_N/JOBS/baconx/Jeep_Animals/bear/ComfyUI-working-folder/LTX-Director-2K/v001"
+    assert output_directory == expected_dir
+    assert name == "LTX-Director-2K_v001.%04d.exr"
+    assert file_path == f"{expected_dir}/LTX-Director-2K_v001.%04d.exr"
+
+
+def test_blank_ai_method_yields_no_dangling_underscore(tmp_path: Path):
+    """Companion regression for the same session's fix — verifies the
+    empty-piece filter so ``ai_method=""`` doesn't produce ``shot_.exr``."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    _, name, _, _ = _run(str(base), shot_name="shot", ai_method="", extension=".exr")
+
+    assert name == "shot.exr"
+
+
+def test_blank_ai_method_with_versioning_skips_double_underscore(tmp_path: Path):
+    """Same rule with versioning on: a blank ``ai_method`` between
+    ``shot_name`` and ``vNNN`` must not produce ``shot__v003.exr``."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    _, name, _, _ = _run(
+        str(base), shot_name="shot", ai_method="",
+        version=3, disable_versioning=False, extension=".exr",
+    )
+
+    assert name == "shot_v003.exr"
+
+
+def test_blank_ai_method_does_not_create_phantom_subfolder(tmp_path: Path):
+    """With ``ai_method`` blank and subfolders enabled, the directory chain
+    is just ``base/shot_name`` — no empty middle level."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, _, _, out = _run(str(base), shot_name="shot", ai_method="")
+
+    assert out == f"{canonical}/shot"
+
+
+# ---------------------------------------------------------------------------
+# _sanitize_segment — path-escape regression coverage
+# ---------------------------------------------------------------------------
+#
+# os.path.join('n:/safe', '/oops') returns '/oops' (or 'C:/oops' on Windows) —
+# its 'last absolute path wins' rule means an absolute-looking shot_name or
+# ai_method could escape the user's intended base_directory_path entirely.
+# A reviewer caught this regression in PR #156 (the original lstrip('/') was
+# dropped during the refactor). These tests pin the sanitizer so it can't
+# come back.
+
+
+class TestSanitizeSegment:
+    def test_clean_input_unchanged(self):
+        assert _sanitize_segment("shot_v1") == "shot_v1"
+        assert _sanitize_segment("RTX-upscale") == "RTX-upscale"
+
+    def test_leading_forward_slash_stripped(self):
+        assert _sanitize_segment("/oops") == "oops"
+
+    def test_leading_backslash_stripped(self):
+        assert _sanitize_segment("\\oops") == "oops"
+
+    def test_multiple_leading_separators_stripped(self):
+        assert _sanitize_segment("///oops") == "oops"
+        assert _sanitize_segment("\\\\\\oops") == "oops"
+        assert _sanitize_segment("/\\/oops") == "oops"
+
+    def test_drive_prefix_handled(self):
+        """Drive-like prefixes are stripped on every host so browser preview
+        and backend runtime agree. ``base_directory_path`` still preserves
+        drive roots; this only applies to joined path segments."""
+        assert _sanitize_segment("C:/Windows") == "Windows"
+        assert _sanitize_segment("C:\\Windows") == "Windows"
+
+    def test_empty_string_passes_through(self):
+        assert _sanitize_segment("") == ""
+
+    def test_only_separators_collapses_to_empty(self):
+        assert _sanitize_segment("///") == ""
+        assert _sanitize_segment("\\") == ""
+
+
+@pytest.mark.parametrize("malicious", [
+    "/oops",
+    "\\oops",
+    "C:/Windows/junk",
+    "/etc/passwd",
+])
+def test_absolute_shot_name_cannot_escape_base(tmp_path: Path, malicious: str):
+    """The reviewer-flagged blocker in PR #156: absolute ``shot_name`` values
+    used to leak through ``os.path.join`` and replace the base path entirely.
+    After ``_sanitize_segment`` they get stripped down to relative form, so
+    ``output_directory`` stays under the user's intended base."""
+    base = tmp_path / "safe"
+    base.mkdir()
+    canonical_base = str(base).replace("\\", "/")
+
+    _, _, _, out = _run(str(base), shot_name=malicious)
+
+    assert out.startswith(canonical_base), (
+        f"shot_name={malicious!r} escaped base — out={out!r}, base={canonical_base!r}"
+    )
+
+
+@pytest.mark.parametrize("malicious", [
+    "/oops",
+    "\\oops",
+    "C:/Windows/junk",
+    "/etc/passwd",
+])
+def test_absolute_ai_method_cannot_escape_base(tmp_path: Path, malicious: str):
+    """Same escape vector through ``ai_method`` (the middle segment). The
+    sanitizer applies symmetrically."""
+    base = tmp_path / "safe"
+    base.mkdir()
+    canonical_base = str(base).replace("\\", "/")
+
+    _, _, _, out = _run(str(base), shot_name="shot", ai_method=malicious)
+
+    assert out.startswith(canonical_base), (
+        f"ai_method={malicious!r} escaped base — out={out!r}, base={canonical_base!r}"
+    )
+
+
+def test_absolute_shot_name_does_not_leak_into_filename(tmp_path: Path):
+    """The filename builder uses the sanitized segments too, so a leading
+    separator can't produce ``/shot_v001.exr`` (which on some platforms is
+    interpreted as a path, on others is just an invalid filename)."""
+    base = tmp_path / "safe"
+    base.mkdir()
+
+    file_path, name, _, _ = _run(str(base), shot_name="/oops")
+
+    assert not name.startswith(("/", "\\")), f"filename leaked separator: {name!r}"
+    assert "/oops" not in name, f"filename retained absolute prefix: {name!r}"
+
+
+def test_drive_prefixed_shot_name_matches_frontend_preview_on_all_hosts(tmp_path: Path):
+    """Regression for PR #156 review: JS preview always strips ``C:`` from
+    shot_name/ai_method segments. Python must do the same even on POSIX hosts
+    or the preview and runtime paths diverge for the same workflow."""
+    base = tmp_path / "safe"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    file_path, name, _, output_directory = _run(
+        str(base),
+        shot_name="C:/Windows",
+        ai_method="v2v",
+        version=1,
+        disable_versioning=False,
+        extension=".exr",
+    )
+
+    assert output_directory == f"{canonical}/Windows/v2v/v001"
+    assert name == "Windows_v2v_v001.exr"
+    assert file_path == f"{canonical}/Windows/v2v/v001/Windows_v2v_v001.exr"
+
+
+def test_no_subfolders_flattens_embedded_separators_in_shot_name(tmp_path: Path):
+    """Real-world maintainer report: chained EasyAIPipeline workflow where the
+    upstream node feeds ``shot_name = "job/shot"``. With ``no_subfolders=true``,
+    embedded separators used to silently re-create subfolders via the filename
+    concat — output was ``base/job/shot.ext`` instead of the flat ``base/<flat>.ext``
+    the toggle promises. After fix: separators in shot_name flatten to ``_`` in
+    the filename, while the directory stays at ``base`` (toggle honored)."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    file_path, name, _, output_directory = _run(
+        str(base),
+        shot_name="ComfyUI-working-folder/LTX-Director-2K",
+        no_subfolders=True,
+    )
+
+    assert output_directory == canonical, f"no_subfolders=True should keep dir=base; got {output_directory!r}"
+    assert name == "ComfyUI-working-folder_LTX-Director-2K.%04d.exr", f"unexpected name: {name!r}"
+    assert "/" not in name and "\\" not in name, f"separator in filename: {name!r}"
+    assert file_path == f"{canonical}/ComfyUI-working-folder_LTX-Director-2K.%04d.exr"
+
+
+def test_filename_never_contains_path_separators(tmp_path: Path):
+    """Belt-and-suspenders: regardless of toggle state or input, the filename
+    portion of WRITE_file_path must never contain `/` or `\\` — those are
+    invalid in filenames on every OS. Subfolder semantics live in the
+    directory portion, not the filename."""
+    base = tmp_path / "safe"
+    base.mkdir()
+
+    for cfg in [
+        dict(shot_name="Project/v1", ai_method="", no_subfolders=True),
+        dict(shot_name="Project/v1", ai_method="", no_subfolders=False),
+        dict(shot_name="a/b/c", ai_method="d/e", no_subfolders=True),
+        dict(shot_name="a/b/c", ai_method="d/e", no_subfolders=False),
+        dict(shot_name="back\\slash", ai_method="", no_subfolders=True),
+    ]:
+        file_path, name, _, _ = _run(str(base), **cfg)
+        assert "/" not in name and "\\" not in name, (
+            f"separator leaked into filename for cfg={cfg!r}: name={name!r}"
+        )
+
+
+def test_no_subfolders_false_still_uses_slashes_as_subfolders(tmp_path: Path):
+    """With ``no_subfolders=False`` (default), embedded slashes in shot_name
+    intentionally become nested subfolders — this is how users organize
+    output into project/shot hierarchies. The filename stays flat regardless."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, name, _, output_directory = _run(
+        str(base),
+        shot_name="Project/v1",
+        ai_method="upscale",
+        version=3, disable_versioning=False,
+        no_subfolders=False,
+    )
+
+    assert output_directory == f"{canonical}/Project/v1/upscale/v003"
+    assert name == "Project_v1_upscale_v003.%04d.exr"
+
+
+def test_no_subfolders_true_with_versioning_keeps_version_folder(tmp_path: Path):
+    """Maintainer-clarified behavior for ``no_subfolders=True``: shot_name and
+    ai_method drop out of the directory path entirely (they only appear in
+    the filename), but the version folder (``v###``) IS still added when
+    ``disable_versioning`` is off. Versioned outputs stay organised under
+    ``base/v###/`` even with the toggle on."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    file_path, name, _, output_directory = _run(
+        str(base),
+        shot_name="shot",
+        ai_method="upscale",
+        version=5, disable_versioning=False,
+        no_subfolders=True,
+    )
+
+    assert output_directory == f"{canonical}/v005", (
+        f"Expected base/v005 (only version folder); got {output_directory!r}"
+    )
+    # Filename still gets all the pieces joined with underscores
+    assert name == "shot_upscale_v005.%04d.exr"
+    assert file_path == f"{canonical}/v005/shot_upscale_v005.%04d.exr"
+
+
+def test_no_subfolders_true_without_versioning_is_flat_base(tmp_path: Path):
+    """Companion to the above: ``no_subfolders=True`` + ``disable_versioning=True``
+    means truly flat output — just ``base/<filename>``, no subfolders at all."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, name, _, output_directory = _run(
+        str(base),
+        shot_name="shot",
+        ai_method="upscale",
+        version=5, disable_versioning=True,
+        no_subfolders=True,
+    )
+
+    assert output_directory == canonical
+    assert name == "shot_upscale.%04d.exr"
+
+
+# ---------------------------------------------------------------------------
+# Control-char stripping — newlines from upstream Text Multiline widgets
+# ---------------------------------------------------------------------------
+#
+# An upstream node (e.g. WAS's `Text Multiline`) can feed strings that contain
+# embedded newlines / tabs / carriage returns. Those can't legally appear in
+# any filesystem path — they'd silently break the actual file save, and the
+# preview widget rendered them as visually broken multi-line output. Strip
+# at the helper level so they never reach the path build.
+
+
+class TestStripControlChars:
+    def test_strips_newline(self):
+        assert _strip_control_chars("foo\nbar") == "foobar"
+
+    def test_strips_carriage_return(self):
+        assert _strip_control_chars("foo\rbar") == "foobar"
+
+    def test_strips_tab(self):
+        assert _strip_control_chars("foo\tbar") == "foobar"
+
+    def test_strips_all_mixed(self):
+        assert _strip_control_chars("foo\r\n\tbar\nbaz") == "foobarbaz"
+
+    def test_preserves_spaces(self):
+        """Spaces are valid in path segments; only newline/CR/tab get stripped."""
+        assert _strip_control_chars("foo bar") == "foo bar"
+
+    def test_empty_passes_through(self):
+        assert _strip_control_chars("") == ""
+
+
+def test_shot_name_with_embedded_newline_does_not_break_path(tmp_path: Path):
+    """The maintainer-reported case: upstream feeds shot_name with a stray
+    newline (e.g. paragraph break in a Text Multiline). Pre-fix, this leaked
+    through to the preview AND would have broken the save with a literal
+    line-break in the path. Fix: _sanitize_segment strips control chars at
+    the source."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    file_path, name, _, output_directory = _run(
+        str(base),
+        shot_name="ComfyUI-working-folder/LTX-Director-2K\n_0",
+        no_subfolders=True,
+    )
+
+    assert "\n" not in file_path, f"newline leaked into file_path: {file_path!r}"
+    assert "\n" not in name, f"newline leaked into name: {name!r}"
+    assert "\n" not in output_directory, f"newline leaked into output_directory: {output_directory!r}"
+
+
+def test_base_path_with_embedded_newline_normalised(tmp_path: Path):
+    """Same defense at the base_directory_path layer — Text Multiline
+    sometimes appends a trailing \\n that survived the previous fix."""
+    base = tmp_path / "bear"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, _, _, output_directory = _run(
+        f"{base}\n",
+        shot_name="shot",
+        no_subfolders=True,
+    )
+
+    assert "\n" not in output_directory
+    assert output_directory == canonical
+
+
+def test_extension_with_embedded_newline_stripped(tmp_path: Path):
+    """Extension is the third path-bound string input; stray newlines there
+    were also leaking into the filename."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    _, name, _, _ = _run(
+        str(base),
+        shot_name="shot",
+        extension=".exr\n",
+    )
+
+    assert "\n" not in name
+    assert name == "shot.exr"
+
+
+@pytest.mark.parametrize("dirty,expected", [
+    (".%04d.exr ",   ".%04d.exr"),   # trailing space
+    (" .%04d.exr",   ".%04d.exr"),   # leading space
+    (" .%04d.exr ",  ".%04d.exr"),   # both
+    (".%04d .exr",   ".%04d.exr"),   # internal space
+    (".%04d.exr\t",  ".%04d.exr"),   # trailing tab
+    (".%04d.exr\xa0", ".%04d.exr"),  # non-breaking space (common copy-paste invisible char)
+])
+def test_extension_whitespace_stripped(tmp_path: Path, dirty: str, expected: str):
+    """Maintainer-reported: ComfyUI-HQ-Image-Save's ``save_images`` validates
+    via ``os.path.splitext(filepath)[1].lower() != '.exr'``. A single trailing
+    space on the extension widget made splitext return ``.exr `` (with space),
+    which failed the strict equality and aborted the save. Extension must have
+    NO whitespace at all (internal or surrounding) — it's a strict suffix
+    field, not a label."""
+    base = tmp_path / "bear"
+    base.mkdir()
+
+    _, name, _, _ = _run(str(base), shot_name="shot", extension=dirty)
+
+    assert name == f"shot{expected}", f"dirty={dirty!r}: got name={name!r}"
+    # And the HQ-Image-Save check would pass:
+    import os
+    assert os.path.splitext(name)[1].lower() == ".exr"
+
+
+@pytest.mark.parametrize("dirty,clean", [
+    ("  shot  ", "shot"),       # surrounding spaces
+    ("shot\t",   "shot"),       # trailing tab
+    ("\tshot",   "shot"),       # leading tab
+])
+def test_shot_name_surrounding_whitespace_stripped(tmp_path: Path, dirty: str, clean: str):
+    """Surrounding whitespace on shot_name (from sloppy upstream feeds) used
+    to leak into the path and filename. ``_sanitize_segment`` now strips
+    surrounding whitespace as well as control chars."""
+    base = tmp_path / "safe"
+    base.mkdir()
+    canonical = str(base).replace("\\", "/")
+
+    _, name, _, output_directory = _run(str(base), shot_name=dirty, no_subfolders=False)
+
+    assert name == f"{clean}.%04d.exr"
+    assert output_directory == f"{canonical}/{clean}"
+
+
+# ---------------------------------------------------------------------------
+# version — single STRING field (typed, or wired from a global version node)
+# ---------------------------------------------------------------------------
+#
+# The version field is a STRING: a bare number becomes vNNN (back-compat with
+# the old integer widget), any other token is used verbatim, and
+# disable_versioning is the master off-switch. A global version node wires
+# straight into this one field — there is no second input.
+
+
+class TestStringVersionField:
+    def test_string_token_used_verbatim(self, tmp_path: Path):
+        """A non-numeric token like ``final`` passes through verbatim into BOTH
+        output_directory and filename — not coerced into vNNN."""
+        base = tmp_path / "bear"
+        base.mkdir()
+        canonical = str(base).replace("\\", "/")
+
+        file_path, name, version_string, output_directory = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version="final", disable_versioning=False,
+        )
+
+        assert version_string == "final"
+        assert output_directory == f"{canonical}/shot/final"
+        assert name == "shot_final.exr"
+        assert file_path == f"{canonical}/shot/final/shot_final.exr"
+
+    def test_explicit_vnnn_token_used_verbatim(self, tmp_path: Path):
+        base = tmp_path / "bear"
+        base.mkdir()
+        canonical = str(base).replace("\\", "/")
+
+        _, name, version_string, output_directory = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version="v007", disable_versioning=False,
+        )
+
+        assert version_string == "v007"
+        assert output_directory == f"{canonical}/shot/v007"
+        assert name == "shot_v007.exr"
+
+    def test_bare_number_becomes_vnnn(self, tmp_path: Path):
+        """Convenience + back-compat: a bare integer string formats as vNNN."""
+        base = tmp_path / "bear"
+        base.mkdir()
+
+        _, name, version_string, _ = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version="2", disable_versioning=False,
+        )
+
+        assert version_string == "v002"
+        assert name == "shot_v002.exr"
+
+    def test_integer_value_still_supported(self, tmp_path: Path):
+        """A pre-existing workflow stored version as an INT; it arrives as a
+        number and must still format as vNNN despite the INT->STRING change."""
+        base = tmp_path / "bear"
+        base.mkdir()
+
+        _, name, version_string, _ = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version=5, disable_versioning=False,
+        )
+
+        assert version_string == "v005"
+        assert name == "shot_v005.exr"
+
+    def test_disable_versioning_is_master_off(self, tmp_path: Path):
+        """disable_versioning drops the version regardless of the field value."""
+        base = tmp_path / "bear"
+        base.mkdir()
+        canonical = str(base).replace("\\", "/")
+
+        _, name, version_string, output_directory = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version="v007", disable_versioning=True,
+        )
+
+        assert version_string == ""
+        assert output_directory == f"{canonical}/shot"
+        assert name == "shot.exr"
+
+    def test_empty_version_yields_no_token(self, tmp_path: Path):
+        base = tmp_path / "bear"
+        base.mkdir()
+        canonical = str(base).replace("\\", "/")
+
+        _, name, version_string, output_directory = _run(
+            str(base), shot_name="shot", ai_method="", extension=".exr",
+            version="", disable_versioning=False,
+        )
+
+        assert version_string == ""
+        assert output_directory == f"{canonical}/shot"
+        assert name == "shot.exr"

ComfyUI/custom_nodes/koolook/tests/nodes/test_easy_image_batch.py

@@ -0,0 +1,575 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Tests for ``easy_ImageBatch`` insert modes and schema.
+
+The node imports ``torch`` at module load, but its *planners*
+(``plan_offset_placements`` for insert placement, ``plan_source_base_fill``
+for the insert-over-source background) are pure Python and never touch torch
+— they just compute which frame lands at which output index. CI installs
+only ``pytest`` / ``aiohttp`` / ``Pillow`` (no torch), so we stub the module
+to import the node torch-free and test the placement logic directly.
+"""
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+# Must run before importing the node module (its top-level ``import torch``).
+# ``setdefault`` keeps a real torch if one happens to be installed.
+sys.modules.setdefault("torch", types.ModuleType("torch"))
+
+# Enrich the stub with the handful of constructors ``create_batch`` uses so the
+# *behaviour* (layer compositing, tie-break, passthrough) can be exercised
+# torch-free — not just the pure planners. ``_FakeTensor`` wraps a flat list of
+# frame-identity tags, so a test can assert *which* frame landed at each output
+# index. Skipped automatically if a real torch is installed.
+_torch = sys.modules["torch"]
+_FAKE_TORCH = not hasattr(_torch, "__version__")
+if _FAKE_TORCH:
+    class _FakeTensor:
+        """Minimal stand-in: a list of opaque per-frame tags + an H/W/C shape."""
+
+        def __init__(self, data, hwc=(2, 2, 3)):
+            self._data = list(data)
+            self._hwc = tuple(hwc)
+            self.device = "cpu"
+            self.dtype = "float32"
+
+        @property
+        def shape(self):
+            return (len(self._data),) + self._hwc
+
+        def __len__(self):
+            return len(self._data)
+
+        def __getitem__(self, key):
+            if isinstance(key, int):
+                return self._data[key]
+            if isinstance(key, slice):
+                return _FakeTensor(self._data[key], self._hwc)
+            if isinstance(key, (list, tuple)):
+                return _FakeTensor([self._data[i] for i in key], self._hwc)
+            raise TypeError(key)
+
+        def __setitem__(self, key, value):
+            if isinstance(key, int):
+                self._data[key] = value
+            else:
+                raise TypeError(key)
+
+        def __rsub__(self, other):  # 1.0 - alpha; identity is fine for these tests
+            return self
+
+    def _fake_full(shape, fill_value, device=None, dtype=None):
+        return _FakeTensor([("placeholder", fill_value)] * shape[0], shape[1:])
+
+    def _fake_ones(shape, device=None, dtype=None):
+        return _FakeTensor([1.0] * shape[0], shape[1:])
+
+    _torch.float32 = "float32"
+    _torch.full = _fake_full
+    _torch.ones = _fake_ones
+else:  # pragma: no cover - real torch present, skip the integration tests
+    _FakeTensor = None
+
+_GRAY = ("placeholder", 0.5)  # what _fake_full tags an unfilled frame with
+
+
+def _source(n):
+    """A fake source_batch whose frame k (0-based) is the tag ``f"src{k+1}"``."""
+    return _FakeTensor([f"src{k + 1}" for k in range(n)])
+
+
+requires_fake_torch = pytest.mark.skipif(
+    not _FAKE_TORCH, reason="behaviour tests rely on the fake-tensor stub"
+)
+
+from k_easy_image_batch import (  # noqa: E402  (import after stub)
+    easy_ImageBatch,
+    parse_frame_tokens,
+    plan_offset_placements,
+    plan_slot_overwrites,
+    plan_source_base_fill,
+)
+
+
+def _frames(plan):
+    """VFX frame numbers placed, in order."""
+    return [vfx for _src, _out, vfx in plan.placements]
+
+
+def test_basic_offset_maps_packed_frames_to_listed_positions():
+    # 5 processed frames, list 1,10,19,30,40, full 41-frame window (cut=1).
+    plan = plan_offset_placements([1, 10, 19, 30, 40], source_count=5, total_frames=41, cut_start_frame=1)
+    assert plan.placements == [
+        (0, 0, 1),
+        (1, 9, 10),
+        (2, 18, 19),
+        (3, 29, 30),
+        (4, 39, 40),
+    ]
+    assert plan.outside_cut == []
+    assert plan.unused_source == 0
+    assert plan.missing_positions == []
+
+
+def test_pairing_is_by_ascending_position_not_list_order():
+    # Out-of-order list still pairs source[0] -> lowest position, etc., so it
+    # round-trips with selected_frames (which is emitted ascending).
+    plan = plan_offset_placements([40, 1, 19], source_count=3, total_frames=41, cut_start_frame=1)
+    assert _frames(plan) == [1, 19, 40]
+    assert [src for src, _out, _vfx in plan.placements] == [0, 1, 2]
+
+
+def test_more_source_frames_than_positions_reports_unused():
+    plan = plan_offset_placements([1, 10, 19], source_count=5, total_frames=41, cut_start_frame=1)
+    assert _frames(plan) == [1, 10, 19]
+    assert plan.unused_source == 2
+    assert plan.missing_positions == []
+
+
+def test_fewer_source_frames_than_positions_reports_missing():
+    plan = plan_offset_placements([1, 10, 19, 30], source_count=2, total_frames=41, cut_start_frame=1)
+    assert _frames(plan) == [1, 10]
+    assert plan.unused_source == 0
+    assert plan.missing_positions == [19, 30]
+
+
+def test_positions_outside_cut_window_are_dropped():
+    # output index = vfx - cut_start_frame; window [0, 20).
+    # frame 1 -> -9 (out), 15 -> 5 (in), 40 -> 30 (out).
+    plan = plan_offset_placements([1, 15, 40], source_count=3, total_frames=20, cut_start_frame=10)
+    assert _frames(plan) == [15]
+    assert plan.outside_cut == [1, 40]
+
+
+def test_duplicate_positions_are_deduped():
+    plan = plan_offset_placements([10, 10, 19], source_count=3, total_frames=41, cut_start_frame=1)
+    assert _frames(plan) == [10, 19]
+
+
+def test_empty_position_list_places_nothing():
+    plan = plan_offset_placements([], source_count=5, total_frames=41, cut_start_frame=1)
+    assert plan.placements == []
+    assert plan.unused_source == 5
+
+
+def test_cut_start_offsets_output_indices():
+    # cut_start_frame=41: frame 41 -> idx 0, 63 -> idx 22.
+    plan = plan_offset_placements([41, 63], source_count=2, total_frames=81, cut_start_frame=41)
+    assert plan.placements == [(0, 0, 41), (1, 22, 63)]
+
+
+def test_source_base_fill_full_window_maps_one_to_one():
+    # cut_start=1: output i -> source i (source_batch[0] is VFX frame 1).
+    placements, fallback = plan_source_base_fill(total_frames=5, cut_start_frame=1, base_len=10)
+    assert placements == [(0, 0), (1, 1), (2, 2), (3, 3), (4, 4)]
+    assert fallback == 0
+
+
+def test_source_base_fill_offsets_with_cut_start():
+    # cut_start=41: output 0 -> source 40 (VFX frame 41), etc.
+    placements, fallback = plan_source_base_fill(total_frames=3, cut_start_frame=41, base_len=121)
+    assert placements == [(0, 40), (1, 41), (2, 42)]
+    assert fallback == 0
+
+
+def test_source_base_fill_beyond_source_falls_back_to_placeholder():
+    # base only covers 2 frames; the remaining 3 cut frames stay placeholder.
+    placements, fallback = plan_source_base_fill(total_frames=5, cut_start_frame=1, base_len=2)
+    assert placements == [(0, 0), (1, 1)]
+    assert fallback == 3
+
+
+def test_source_base_fill_cut_starts_past_source_end():
+    # Cut window starts beyond the source entirely → all placeholder.
+    placements, fallback = plan_source_base_fill(total_frames=4, cut_start_frame=50, base_len=10)
+    assert placements == []
+    assert fallback == 4
+
+
+def test_slot_overwrites_basic_placement():
+    # image1 @ VFX frame 4, cut_start 1 -> output index 3.
+    placements, outside = plan_slot_overwrites([(0, 4)], total_frames=24, cut_start_frame=1)
+    assert placements == [(0, 3, 4)]
+    assert outside == []
+
+
+def test_slot_overwrites_higher_slot_wins_collision():
+    # image1 (idx 0) and image3 (idx 2) both target VFX frame 10 -> the
+    # higher-numbered slot wins, one winner per output index.
+    placements, outside = plan_slot_overwrites(
+        [(0, 10), (2, 10)], total_frames=24, cut_start_frame=1
+    )
+    assert placements == [(2, 9, 10)]
+    assert outside == []
+
+
+def test_slot_overwrites_higher_slot_wins_regardless_of_input_order():
+    # Same collision, supplied highest-first: result must still pick image3.
+    placements, _ = plan_slot_overwrites(
+        [(2, 10), (0, 10)], total_frames=24, cut_start_frame=1
+    )
+    assert placements == [(2, 9, 10)]
+
+
+def test_slot_overwrites_outside_cut_reported():
+    # cut_start 10: frame 2 -> output -8 (outside); frame 15 -> 5 (in).
+    placements, outside = plan_slot_overwrites(
+        [(0, 2), (1, 15)], total_frames=20, cut_start_frame=10
+    )
+    assert placements == [(1, 5, 15)]
+    assert outside == [2]
+
+
+def test_slot_overwrites_cut_start_offsets_output_indices():
+    placements, _ = plan_slot_overwrites(
+        [(0, 41), (1, 63)], total_frames=81, cut_start_frame=41
+    )
+    assert placements == [(0, 0, 41), (1, 22, 63)]
+
+
+def test_slot_overwrites_sorted_by_output_index():
+    # Distinct frames, ascending by output index regardless of slot order.
+    placements, _ = plan_slot_overwrites(
+        [(0, 20), (1, 5)], total_frames=24, cut_start_frame=1
+    )
+    assert [out for _s, out, _v in placements] == [4, 19]
+
+
+def test_slot_overwrites_empty_input_places_nothing():
+    placements, outside = plan_slot_overwrites([], total_frames=10, cut_start_frame=1)
+    assert placements == []
+    assert outside == []
+
+
+def test_input_types_exposes_keyframes_insert_with_tooltip():
+    spec = easy_ImageBatch.INPUT_TYPES()
+    assert "keyframes_insert" in spec["optional"], "insert-mode input must be declared"
+    # `keyframe_batch` is retained as a deprecated alias so workflows saved on
+    # v0.4.1/v0.4.2 keep loading.
+    assert "keyframe_batch" in spec["optional"]
+    assert "deprecated" in spec["optional"]["keyframe_batch"][1]["tooltip"].lower()
+    entry = spec["optional"]["keyframes_insert"]
+    assert entry[0] == "IMAGE"
+    tooltip = entry[1]["tooltip"].lower()
+    assert "insert" in tooltip
+    assert "source_frames" in tooltip
+
+
+def test_input_types_exposes_width_height_fallback_at_end():
+    spec = easy_ImageBatch.INPUT_TYPES()
+    # Fallback-only and declared OPTIONAL so they append to the END of the
+    # widget list — keeping positional widgets_values of older saved workflows
+    # aligned (inserting them earlier shifts placeholder_color/source_frames).
+    for key in ("width", "height"):
+        assert key in spec["optional"], f"{key} fallback widget must be optional"
+        assert key not in spec["required"]
+        assert spec["optional"][key][0] == "INT"
+        assert spec["optional"][key][1]["default"] == 512
+    # They must be the last two optional keys (= last two widgets).
+    assert list(spec["optional"])[-2:] == ["width", "height"]
+
+
+def test_registration_exports_unchanged():
+    from k_easy_image_batch import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+
+    assert NODE_CLASS_MAPPINGS["easy_ImageBatch"] is easy_ImageBatch
+    assert NODE_DISPLAY_NAME_MAPPINGS["easy_ImageBatch"] == "Easy Image Batch (Koolook)"
+
+
+# --- Behaviour (layer compositing) tests, run against the fake-tensor stub ---
+
+
+@requires_fake_torch
+def test_select_slot_overwrites_list_pick_at_same_frame():
+    # source pick at frame 5 AND image1 wired at frame 5 -> the slot wins.
+    node = easy_ImageBatch()
+    image_batch, _alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5",
+        image1_frame=5, source_batch=_source(24), image1=_FakeTensor(["slotA"]),
+    )
+    assert image_batch[4] == "slotA"   # output index 4 == VFX frame 5
+    assert frames == "5"
+    assert len(selected) == 1
+
+
+@requires_fake_torch
+def test_select_higher_slot_wins_at_same_frame():
+    # image1 and image2 both target frame 10 -> the higher-numbered slot wins.
+    node = easy_ImageBatch()
+    image_batch, _alpha, _sel, _frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=10, image1=_FakeTensor(["slot1"]),
+        image2=_FakeTensor(["slot2"]), image2_frame=10,
+    )
+    assert image_batch[9] == "slot2"
+
+
+@requires_fake_torch
+def test_insert_slot_composites_on_top_of_inserts():
+    # Inserts ins1/ins2/ins3 land at frames 5/7/20; image1 @ frame 5 wins there.
+    node = easy_ImageBatch()
+    image_batch, _alpha, _sel, _frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5 7 20",
+        image1_frame=5, keyframes_insert=_FakeTensor(["ins1", "ins2", "ins3"]),
+        image1=_FakeTensor(["slotA"]),
+    )
+    assert image_batch[4] == "slotA"   # slot beats the insert at frame 5
+    assert image_batch[6] == "ins2"    # other inserts untouched
+    assert image_batch[19] == "ins3"
+
+
+@requires_fake_torch
+def test_select_empty_list_passes_source_through_with_no_phantom_picks():
+    # EXE 2: source connected, empty list, no slots wired (defaults 5/9/13/17).
+    # Whole batch is the source passthrough; nothing is "placed".
+    node = easy_ImageBatch()
+    image_batch, _alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=5, source_batch=_source(24),
+        image2_frame=9, image3_frame=13, image4_frame=17,
+    )
+    assert [image_batch[i] for i in range(24)] == [f"src{k + 1}" for k in range(24)]
+    assert frames == ""        # background is never counted as placed
+    assert len(selected) == 0
+
+
+@requires_fake_torch
+def test_select_nonempty_list_ignores_unwired_slot_defaults():
+    # EXE 3: only the listed picks are placed; the unwired slots' default
+    # imageN_frame values (9/13/17) do NOT pull phantom frames from source.
+    node = easy_ImageBatch()
+    image_batch, _alpha, _sel, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5 8 20",
+        image1_frame=5, source_batch=_source(24),
+        image2_frame=9, image3_frame=13, image4_frame=17,
+    )
+    assert frames == "5, 8, 20"
+    assert image_batch[4] == "src5"
+    assert image_batch[7] == "src8"
+    assert image_batch[19] == "src20"
+    assert image_batch[8] == _GRAY    # frame 9 stays placeholder, no phantom pick
+
+
+@requires_fake_torch
+def test_selected_image_batch_is_picks_plus_slots_slots_win_overlap():
+    # selected_image_batch = union of multiline picks AND slot overwrites,
+    # ascending by frame, with the slot winning where they overlap.
+    node = easy_ImageBatch()
+    _img, _alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5 8",
+        image1_frame=5, source_batch=_source(24),
+        image1=_FakeTensor(["slotA"]),          # overlaps the pick at frame 5
+        image2=_FakeTensor(["slotB"]), image2_frame=12,  # slot-only position
+    )
+    assert frames == "5, 8, 12"
+    assert [selected[i] for i in range(len(selected))] == ["slotA", "src8", "slotB"]
+
+
+@requires_fake_torch
+def test_selected_image_batch_includes_inserts_and_slots_in_insert_mode():
+    # Same rule under insert mode: selected = inserts + slot overwrites.
+    node = easy_ImageBatch()
+    _img, _alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5 7 20",
+        image1_frame=4, keyframes_insert=_FakeTensor(["ins1", "ins2", "ins3"]),
+        image1=_FakeTensor(["slotA"]),          # slot-only position at frame 4
+    )
+    assert frames == "4, 5, 7, 20"
+    assert [selected[i] for i in range(len(selected))] == ["slotA", "ins1", "ins2", "ins3"]
+
+
+# --- Feature: range syntax in the frame list (parse_frame_tokens) ---
+
+
+def test_parse_frame_tokens_expands_inclusive_ranges():
+    values, bad = parse_frame_tokens("1-5, 7, 9, 14-17")
+    assert values == [1, 2, 3, 4, 5, 7, 9, 14, 15, 16, 17]
+    assert bad == []
+
+
+def test_parse_frame_tokens_mixed_separators():
+    values, bad = parse_frame_tokens("1-3 7\n10")
+    assert values == [1, 2, 3, 7, 10]
+    assert bad == []
+
+
+def test_parse_frame_tokens_single_value_range():
+    values, bad = parse_frame_tokens("7-7")
+    assert values == [7]
+    assert bad == []
+
+
+def test_parse_frame_tokens_descending_range_is_bad():
+    values, bad = parse_frame_tokens("5-1, 8")
+    assert values == [8]
+    assert bad == ["5-1"]
+
+
+def test_parse_frame_tokens_non_integer_tokens_are_bad():
+    values, bad = parse_frame_tokens("3, foo, 5-x, 9")
+    assert values == [3, 9]
+    assert bad == ["foo", "5-x"]
+
+
+@requires_fake_torch
+def test_select_accepts_range_syntax_in_list():
+    node = easy_ImageBatch()
+    _img, _alpha, _sel, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="1-3, 5",
+        image1_frame=4, source_batch=_source(24),
+    )
+    assert frames == "1, 2, 3, 5"
+
+
+@requires_fake_torch
+def test_insert_accepts_range_syntax_in_positions():
+    node = easy_ImageBatch()
+    _img, _alpha, _sel, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5-7",
+        image1_frame=4, keyframes_insert=_FakeTensor(["a", "b", "c"]),
+    )
+    assert frames == "5, 6, 7"
+
+
+# --- Feature: passthrough shorter than output -> keep + gap-as-selection ---
+
+
+@requires_fake_torch
+def test_passthrough_shorter_source_keeps_covered_and_selects_gap():
+    # source = 17 frames, output = 24: frames 1-17 are kept (alpha 0/black),
+    # frames 18-24 are the gap (alpha 1/white) and become the selection.
+    node = easy_ImageBatch()
+    image_batch, alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=4, source_batch=_source(17),
+    )
+    # image: 1-17 source, 18-24 placeholder
+    assert image_batch[16] == "src17"
+    assert image_batch[17] == _GRAY
+    # alpha (inpaint): covered black (0.0), gap white (1.0)
+    assert alpha[0] == 0.0 and alpha[16] == 0.0
+    assert alpha[17] == 1.0 and alpha[23] == 1.0
+    # selection = the gap frames 18..24 (to inpaint)
+    assert frames == "18, 19, 20, 21, 22, 23, 24"
+    assert len(selected) == 7
+    assert selected[0] == _GRAY
+
+
+@requires_fake_torch
+def test_passthrough_full_coverage_selects_nothing():
+    # source >= output: no gap -> alpha all black (kept), selection empty.
+    node = easy_ImageBatch()
+    image_batch, alpha, selected, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=4, source_batch=_source(24),
+    )
+    assert [image_batch[i] for i in range(24)] == [f"src{k + 1}" for k in range(24)]
+    assert alpha[0] == 0.0 and alpha[23] == 0.0
+    assert frames == ""
+    assert len(selected) == 0
+
+
+@requires_fake_torch
+def test_passthrough_slot_in_gap_counts_as_kept_not_gap():
+    # A slot filling a gap frame becomes kept content, excluded from the
+    # inpaint selection.
+    node = easy_ImageBatch()
+    _img, alpha, _sel, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=20, source_batch=_source(17), image1=_FakeTensor(["slotA"]),
+    )
+    assert alpha[19] == 0.0                      # frame 20 filled by slot -> kept
+    assert frames == "18, 19, 21, 22, 23, 24"    # gap excludes frame 20
+
+
+@requires_fake_torch
+def test_passthrough_gap_with_cut_start_offset():
+    # cut_start=41, total=10 -> output is VFX 41..50. source has 45 frames, so
+    # VFX 41..45 are covered (output 0..4) and 46..50 are the gap.
+    node = easy_ImageBatch()
+    image_batch, alpha, _sel, frames = node.create_batch(
+        total_frames=10, cut_start_frame=41, placeholder_color="Gray",
+        invert_alpha=False, source_frames="",
+        image1_frame=4, source_batch=_source(45),
+    )
+    assert image_batch[0] == "src41" and image_batch[4] == "src45"
+    assert image_batch[5] == _GRAY                       # VFX 46 = gap
+    assert alpha[0] == 0.0 and alpha[4] == 0.0           # covered kept
+    assert alpha[5] == 1.0 and alpha[9] == 1.0           # gap to inpaint
+    assert frames == "46, 47, 48, 49, 50"                # gap selection
+
+
+# --- Review-round fixes: deprecated alias + input guards ---
+
+
+def test_parse_frame_tokens_rejects_overlong_range():
+    values, bad = parse_frame_tokens("1-99999999, 7")
+    assert values == [7]
+    assert bad == ["1-99999999"]
+
+
+def test_parse_frame_tokens_allows_large_bounded_range():
+    values, bad = parse_frame_tokens("1-100")
+    assert len(values) == 100 and bad == []
+
+
+def test_parse_frame_tokens_range_span_boundary():
+    # exactly _MAX_RANGE_SPAN (8192) frames is allowed; one more is rejected.
+    ok, bad = parse_frame_tokens("1-8192")
+    assert len(ok) == 8192 and bad == []
+    over, bad_over = parse_frame_tokens("1-8193")
+    assert over == [] and bad_over == ["1-8193"]
+
+
+@requires_fake_torch
+def test_keyframe_batch_alias_routes_to_insert_mode():
+    # A workflow saved with the deprecated alias still behaves like an insert.
+    node = easy_ImageBatch()
+    _img, _alpha, _sel, frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5 7 20",
+        image1_frame=4, keyframe_batch=_FakeTensor(["a", "b", "c"]),
+    )
+    assert frames == "5, 7, 20"
+
+
+@requires_fake_torch
+def test_keyframes_insert_wins_over_deprecated_alias():
+    node = easy_ImageBatch()
+    _img, _alpha, selected, _frames = node.create_batch(
+        total_frames=24, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="5",
+        image1_frame=4,
+        keyframes_insert=_FakeTensor(["new"]), keyframe_batch=_FakeTensor(["old"]),
+    )
+    assert selected[0] == "new"
+
+
+@requires_fake_torch
+def test_nonempty_list_without_image_source_warns_and_returns_clean(capsys):
+    # source_frames set but no source_batch / imageN -> clean placeholder batch,
+    # with a warning that the list was ignored (no silent drop).
+    node = easy_ImageBatch()
+    image_batch, _alpha, selected, frames = node.create_batch(
+        total_frames=5, cut_start_frame=1, placeholder_color="Gray",
+        invert_alpha=False, source_frames="2 3",
+        image1_frame=4, width=8, height=8,
+    )
+    assert len(image_batch) == 5
+    assert frames == "" and len(selected) == 0
+    assert "source_frames is set but no image source" in capsys.readouterr().out

ComfyUI/custom_nodes/koolook/tests/nodes/test_easy_utility.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Tests for Easy_Utility — the dispatchable converter node."""
+from __future__ import annotations
+
+import pytest
+
+from k_easy_utility import Easy_Utility
+
+
+@pytest.fixture
+def node():
+    return Easy_Utility()
+
+
+@pytest.mark.parametrize(
+    "int_value,prefix,pad_width,expected",
+    [
+        (1, "v", 3, "v001"),
+        (0, "v", 3, "v000"),
+        (42, "v", 3, "v042"),
+        (999, "v", 3, "v999"),
+        (1000, "v", 3, "v1000"),  # widens past pad_width when needed
+        (5, "", 2, "05"),  # no prefix
+        (7, "shot_", 4, "shot_0007"),
+        (1, "v", 0, "v1"),  # pad_width=0 → no padding
+    ],
+)
+def test_int_to_padded_string(node, int_value, prefix, pad_width, expected):
+    (out,) = node.run("int_to_padded_string", int_value, prefix, pad_width)
+    assert out == expected
+
+
+def test_unknown_mode_returns_stringified_int(node):
+    (out,) = node.run("nonexistent_mode", 42, "v", 3)
+    assert out == "42"
+
+
+def test_registration_exports():
+    from k_easy_utility import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+
+    assert "Easy_Utility" in NODE_CLASS_MAPPINGS
+    assert NODE_CLASS_MAPPINGS["Easy_Utility"] is Easy_Utility
+    assert NODE_DISPLAY_NAME_MAPPINGS["Easy_Utility"] == "Easy Utility (Koolook)"
+
+
+def test_widget_defaults_produce_bare_padded_digits():
+    """Default widget values should yield ``001`` (no prefix) — the
+    EasyAIPipeline / Easy_VideoCombine consumers add ``v`` themselves
+    via ``koolook_versioning.resolve_version_token``."""
+    spec = Easy_Utility.INPUT_TYPES()["required"]
+    defaults = {name: opts[1]["default"] for name, opts in spec.items()}
+    n = Easy_Utility()
+    (out,) = n.run(**defaults)
+    assert out == "001"

ComfyUI/custom_nodes/koolook/tests/nodes/test_easy_video_combine.py

@@ -0,0 +1,594 @@
+"""Tests for Easy_VideoCombine's absolute-path discrimination.
+
+The full VHS encode pipeline needs ffmpeg + torch + a live ComfyUI
+process to exercise meaningfully, so we don't drive ``combine_video()``
+end-to-end here. The behavior worth pinning at unit-test scope is the
+relative-vs-absolute branch and the ``create_path_if_missing`` toggle —
+both live in the pure helper :func:`_resolve_abs_target`, which doesn't
+need VHS to be installed.
+
+Importing ``k_video_combine`` works regardless of VHS availability: the
+module's top-level try/except shape leaves ``_resolve_abs_target``
+defined either way (only the class registration is gated).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+import k_video_combine
+from k_video_combine import (
+    _add_metadata_json_sidecar,
+    _append_video_path_outputs,
+    _append_version_to_prefix,
+    _auto_version_scan_target,
+    _build_sidecar_workflow,
+    _coerce_version_input,
+    _compose_prefix,
+    _display_format_name,
+    _final_json_path_from_result,
+    _final_video_path_from_result,
+    _finalize_strict_version_output,
+    _metadata_sidecar_path,
+    _normalize_bool_input,
+    _normalize_text_input,
+    _remove_audio_suffix_from_result,
+    _resolve_abs_target,
+    _runtime_format_name,
+    _video_path_parts,
+)
+from k_video_load import _compose_input_video_path
+
+
+def test_relative_prefix_returns_none() -> None:
+    """Relative prefixes are upstream's domain — helper signals passthrough."""
+    assert _resolve_abs_target("AnimateDiff", create_path_if_missing=False) is None
+    assert _resolve_abs_target("renders/clip01", create_path_if_missing=True) is None
+    # A path with `..` is still relative — sandbox stays in force.
+    assert _resolve_abs_target("../escape", create_path_if_missing=False) is None
+
+
+def test_absolute_prefix_existing_dir(tmp_path: Path) -> None:
+    """Absolute prefix with existing parent returns (dir, basename)."""
+    prefix = str(tmp_path / "clipname")
+    result = _resolve_abs_target(prefix, create_path_if_missing=False)
+
+    assert result is not None
+    abs_dir, abs_base = result
+    assert Path(abs_dir) == tmp_path
+    assert abs_base == "clipname"
+
+
+def test_absolute_prefix_missing_dir_raises_when_create_off(tmp_path: Path) -> None:
+    """Missing parent + create_path_if_missing=False -> FileNotFoundError.
+
+    A typo in a render path should fail loudly, not silently spawn
+    directories the user didn't intend.
+    """
+    prefix = str(tmp_path / "nested" / "deeper" / "clip")
+
+    with pytest.raises(FileNotFoundError, match="Directory does not exist"):
+        _resolve_abs_target(prefix, create_path_if_missing=False)
+
+    assert not (tmp_path / "nested").exists()  # No silent mkdir.
+
+
+def test_absolute_prefix_missing_dir_created_when_toggled(tmp_path: Path) -> None:
+    """Missing parent + create_path_if_missing=True -> mkdir + resolve."""
+    parent = tmp_path / "nested" / "deeper"
+    prefix = str(parent / "clip")
+
+    result = _resolve_abs_target(prefix, create_path_if_missing=True)
+
+    assert result is not None
+    abs_dir, abs_base = result
+    assert parent.exists()
+    assert Path(abs_dir) == parent
+    assert abs_base == "clip"
+
+
+def test_absolute_prefix_with_trailing_separator(tmp_path: Path) -> None:
+    """Existing directory paths work with a final slash."""
+    renders_dir = tmp_path / "renders"
+    renders_dir.mkdir()
+    prefix = str(renders_dir) + os.sep
+
+    result = _resolve_abs_target(prefix, create_path_if_missing=False)
+
+    assert result is not None
+    abs_dir, abs_base = result
+    assert Path(abs_dir) == renders_dir
+    assert abs_base == "renders"
+
+
+def test_absolute_existing_directory_without_trailing_separator(tmp_path: Path) -> None:
+    """Pasted directory paths work with or without a final slash."""
+    renders_dir = tmp_path / "renders"
+    renders_dir.mkdir()
+
+    result = _resolve_abs_target(str(renders_dir), create_path_if_missing=False)
+
+    assert result is not None
+    abs_dir, abs_base = result
+    assert Path(abs_dir) == renders_dir
+    assert abs_base == "renders"
+
+
+def test_absolute_prefix_with_no_filename_component_raises(tmp_path: Path) -> None:
+    """An absolute path with empty basename has no filename root to
+    append the counter to — surface as a clear ValueError instead of
+    silently writing files named ``_00001.mp4``."""
+    root = tmp_path.anchor  # "/" on POSIX, "C:\\" on Windows.
+    assert os.path.isabs(root)
+
+    with pytest.raises(ValueError, match="no usable folder name"):
+        _resolve_abs_target(root, create_path_if_missing=False)
+
+
+# =============================================================================
+# _compose_prefix: split-mode output_directory + filename_prefix.
+# =============================================================================
+
+def test_compose_empty_output_directory_passes_through() -> None:
+    """No output_directory -> filename_prefix returned unchanged."""
+    assert _compose_prefix("AnimateDiff", "") == "AnimateDiff"
+    assert _compose_prefix("E:/renders/clip", "") == "E:/renders/clip"
+
+
+def test_compose_absolute_directory_with_name() -> None:
+    """Absolute output_directory + name -> joined absolute prefix."""
+    composed = _compose_prefix("clip_v003", "E:/renders/shot01")
+    assert composed == "E:/renders/shot01" + os.sep + "clip_v003"
+
+
+def test_compose_relative_directory_with_name() -> None:
+    """Relative output_directory + name -> joined relative prefix.
+
+    Stays relative so the downstream isabs discrimination passes it
+    through to upstream's sandbox.
+    """
+    composed = _compose_prefix("clip", "shots/v003")
+    assert composed == "shots/v003" + os.sep + "clip"
+    assert not os.path.isabs(composed)
+
+
+def test_compose_strips_path_components_from_filename_prefix() -> None:
+    """When output_directory is set, only the basename of filename_prefix
+    becomes the file root — users can change the name without retyping
+    the directory."""
+    composed = _compose_prefix("subdir/clip_v003", "E:/renders/shot01")
+    assert composed == "E:/renders/shot01" + os.sep + "clip_v003"
+
+
+def test_compose_trims_trailing_separator_from_directory() -> None:
+    """Trailing slashes on output_directory don't double-up in the join."""
+    composed_unix = _compose_prefix("clip", "E:/renders/shot01/")
+    composed_win = _compose_prefix("clip", "E:\\renders\\shot01\\")
+    assert composed_unix == "E:/renders/shot01" + os.sep + "clip"
+    assert composed_win == "E:\\renders\\shot01" + os.sep + "clip"
+
+
+def test_compose_empty_name_falls_back_to_default() -> None:
+    """If filename_prefix's basename is empty (e.g. user typed just '/'),
+    fall back to AnimateDiff rather than producing a path ending in
+    just a separator."""
+    composed = _compose_prefix("/", "E:/renders/shot01")
+    assert composed == "E:/renders/shot01" + os.sep + "AnimateDiff"
+
+
+# =============================================================================
+# _normalize_text_input: guard against the ComfyUI frontend "undefined" quirk.
+# A STRING widget left untouched can arrive at the backend as the literal
+# string "undefined" (or "null" / "None") instead of an empty value.
+# Without normalization that would slip into _compose_prefix and produce a
+# nonsensical `undefined/` subdirectory on disk.
+# =============================================================================
+
+def test_normalize_empty_inputs() -> None:
+    assert _normalize_text_input("") == ""
+    assert _normalize_text_input("   ") == ""
+    assert _normalize_text_input(None) == ""
+
+
+def test_normalize_undefined_sentinel_strings() -> None:
+    """All case variants of the frontend-quirk strings become empty."""
+    assert _normalize_text_input("undefined") == ""
+    assert _normalize_text_input("Undefined") == ""
+    assert _normalize_text_input("UNDEFINED") == ""
+    assert _normalize_text_input("null") == ""
+    assert _normalize_text_input("None") == ""
+    assert _normalize_text_input("  undefined  ") == ""
+
+
+def test_normalize_passes_through_real_values() -> None:
+    assert _normalize_text_input("E:/renders/shot01") == "E:/renders/shot01"
+    assert _normalize_text_input("clip_v003") == "clip_v003"
+    # Substring matches don't trigger — only exact match (post-strip).
+    assert _normalize_text_input("undefined_path") == "undefined_path"
+    assert _normalize_text_input("my_null_clip") == "my_null_clip"
+
+
+def test_normalize_prevents_undefined_subdir_in_compose() -> None:
+    """Regression test for the bug: output_directory='undefined' was
+    being treated as a real directory, producing an `undefined/`
+    subfolder when the user typed an absolute path in filename_prefix."""
+    normalized_dir = _normalize_text_input("undefined")
+    composed = _compose_prefix("E:/renders/clip_v003", normalized_dir)
+    # With normalization, no output_directory -> filename_prefix passes through.
+    assert composed == "E:/renders/clip_v003"
+    assert "undefined" not in composed
+
+
+# =============================================================================
+# _normalize_bool_input: guard against dynamic widget restore drift.
+# If format-specific widgets are restored by position instead of by name, a
+# value like "hq" can land in pingpong. Python truthiness would treat that as
+# True and VHS would double the video by ping-ponging the frame sequence.
+# =============================================================================
+
+def test_normalize_bool_input_known_values() -> None:
+    assert _normalize_bool_input(True) is True
+    assert _normalize_bool_input(False) is False
+    assert _normalize_bool_input("true") is True
+    assert _normalize_bool_input("1") is True
+    assert _normalize_bool_input("on") is True
+    assert _normalize_bool_input("false") is False
+    assert _normalize_bool_input("0") is False
+    assert _normalize_bool_input("off") is False
+    assert _normalize_bool_input("") is False
+
+
+def test_normalize_bool_input_unknown_string_uses_default() -> None:
+    assert _normalize_bool_input("hq", default=False) is False
+    assert _normalize_bool_input("hq", default=True) is True
+
+
+def test_metadata_sidecar_path_replaces_vhs_png_sidecar(tmp_path: Path) -> None:
+    png = tmp_path / "clip_00001.png"
+    assert _metadata_sidecar_path([str(png)]) == str(tmp_path / "clip_00001.json")
+
+
+def test_add_metadata_json_sidecar_replaces_disabled_png_entry(tmp_path: Path) -> None:
+    png = tmp_path / "clip_00001.png"
+    mp4 = tmp_path / "clip_00001.mp4"
+    result = {
+        "ui": {"gifs": [{"workflow": png.name}]},
+        "result": ((True, [str(png), str(mp4)]),),
+    }
+
+    out = _add_metadata_json_sidecar(
+        result,
+        {"prompt": {"1": {"class_type": "Example"}}},
+        save_metadata_json=True,
+        save_metadata_png=False,
+    )
+
+    json_path = tmp_path / "clip_00001.json"
+    assert json_path.exists()
+    assert out["result"][0][1] == [str(json_path), str(mp4)]
+    assert out["ui"]["gifs"][0]["workflow"] == json_path.name
+
+
+def test_remove_audio_suffix_renames_final_and_drops_missing_intermediate(tmp_path: Path) -> None:
+    png = tmp_path / "clip_00001.png"
+    silent = tmp_path / "clip_00001.mp4"
+    audio = tmp_path / "clip_00001-audio.mp4"
+    png.write_text("png")
+    audio.write_text("video")
+    result = {
+        "ui": {"gifs": [{"filename": audio.name, "fullpath": str(audio)}]},
+        "result": ((True, [str(png), str(silent), str(audio)]),),
+    }
+
+    out = _remove_audio_suffix_from_result(result, keep_silent_intermediate=False)
+
+    clean = tmp_path / "clip_00001.mp4"
+    assert clean.exists()
+    assert not audio.exists()
+    assert out["result"][0][1] == [str(png), str(clean)]
+    assert out["ui"]["gifs"][0]["filename"] == clean.name
+    assert out["ui"]["gifs"][0]["fullpath"] == str(clean)
+
+
+def test_remove_audio_suffix_replaces_silent_intermediate(tmp_path: Path) -> None:
+    silent = tmp_path / "clip_00001.mp4"
+    audio = tmp_path / "clip_00001-audio.mp4"
+    silent.write_bytes(b"silent")
+    audio.write_bytes(b"with_audio")
+    result = {
+        "ui": {"gifs": [{"filename": audio.name, "fullpath": str(audio)}]},
+        "result": ((True, [str(silent), str(audio)]),),
+    }
+
+    out = _remove_audio_suffix_from_result(result, keep_silent_intermediate=False)
+
+    assert silent.exists()
+    assert silent.read_bytes() == b"with_audio"
+    assert not audio.exists()
+    assert out["result"][0][1] == [str(silent)]
+    assert out["ui"]["gifs"][0]["filename"] == silent.name
+    assert out["ui"]["gifs"][0]["fullpath"] == str(silent)
+
+
+def test_koolook_format_display_hides_json_suffix() -> None:
+    assert _display_format_name("video/koolook-ASTRA-h264.json") == "video/koolook-ASTRA-h264"
+    assert _display_format_name("video/ProRes") == "video/ProRes"
+
+
+def test_koolook_format_runtime_restores_json_suffix() -> None:
+    assert _runtime_format_name("video/koolook-ASTRA-h264") == "video/koolook-ASTRA-h264.json"
+    assert _runtime_format_name("video/ProRes") == "video/ProRes"
+
+
+# =============================================================================
+# Strict versioning: a wired/typed version token replaces VHS's _NNNNN counter
+# with a deterministic <root>_<token>.<ext> name (the "professional" mode the
+# maintainer asked for). Empty token keeps the legacy counter.
+# =============================================================================
+
+def test_append_version_to_filename_root() -> None:
+    assert _append_version_to_prefix("AnimateDiff", "v001") == "AnimateDiff_v001"
+    assert _append_version_to_prefix("E:/renders/clip", "v001") == "E:/renders/clip_v001"
+    assert _append_version_to_prefix("E:\\renders\\clip", "v001") == "E:\\renders\\clip_v001"
+
+
+def test_append_version_no_token_is_noop() -> None:
+    assert _append_version_to_prefix("clip", "") == "clip"
+
+
+def test_auto_version_scan_target_for_relative_prefix_uses_comfy_output_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    output_dir = tmp_path / "comfy-output"
+    monkeypatch.setattr(
+        k_video_combine,
+        "folder_paths",
+        type("FolderPaths", (), {"get_output_directory": staticmethod(lambda: str(output_dir))}),
+        raising=False,
+    )
+
+    scan_dir, name = _auto_version_scan_target("AnimateDiff")
+
+    assert Path(scan_dir) == output_dir
+    assert name == "AnimateDiff"
+
+
+def test_auto_version_scan_target_for_relative_subfolder_uses_comfy_output_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    output_dir = tmp_path / "comfy-output"
+    monkeypatch.setattr(
+        k_video_combine,
+        "folder_paths",
+        type("FolderPaths", (), {"get_output_directory": staticmethod(lambda: str(output_dir))}),
+        raising=False,
+    )
+
+    scan_dir, name = _auto_version_scan_target("renders/AnimateDiff")
+
+    assert Path(scan_dir) == output_dir / "renders"
+    assert name == "AnimateDiff"
+
+
+def test_auto_version_scan_target_does_not_fallback_to_cwd(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fail_output_dir():
+        raise RuntimeError("output directory unavailable")
+
+    monkeypatch.setattr(
+        k_video_combine,
+        "folder_paths",
+        type("FolderPaths", (), {"get_output_directory": staticmethod(fail_output_dir)}),
+        raising=False,
+    )
+
+    with pytest.raises(RuntimeError, match="output directory unavailable"):
+        _auto_version_scan_target("AnimateDiff")
+
+
+def test_strict_version_strips_counter_and_writes_matching_sidecar(tmp_path: Path) -> None:
+    """The headline contract: <root>_v001_00001.mp4 -> <root>_v001.mp4 with a
+    matching <root>_v001.json beside it."""
+    video = tmp_path / "clip_v001_00001.mp4"
+    video.write_bytes(b"render")
+    result = {
+        "ui": {"gifs": [{"filename": video.name, "fullpath": str(video)}]},
+        "result": ((True, [str(video)]),),
+    }
+
+    out = _finalize_strict_version_output(
+        result,
+        enable_overwrite=False,
+        metadata_payload={"CreationTime": "t", "prompt": {"1": {}}},
+        save_metadata_json=True,
+    )
+
+    clean = tmp_path / "clip_v001.mp4"
+    sidecar = tmp_path / "clip_v001.json"
+    assert clean.exists() and not video.exists()
+    assert sidecar.exists()
+    files = out["result"][0][1]
+    assert files[-1] == str(clean)
+    assert str(sidecar) in files
+    assert out["ui"]["gifs"][0]["filename"] == clean.name
+
+
+def test_strict_version_keeps_counter_on_collision_without_overwrite(tmp_path: Path) -> None:
+    """Lossless default: re-rendering an existing version keeps the counter so
+    the prior file is never clobbered; the sidecar matches the kept name."""
+    existing = tmp_path / "clip_v001.mp4"
+    existing.write_bytes(b"old")
+    video = tmp_path / "clip_v001_00002.mp4"
+    video.write_bytes(b"new")
+    result = {"result": ((True, [str(video)]),)}
+
+    out = _finalize_strict_version_output(
+        result,
+        enable_overwrite=False,
+        metadata_payload={"CreationTime": "t"},
+        save_metadata_json=True,
+    )
+
+    assert existing.read_bytes() == b"old"
+    assert video.exists()
+    assert (tmp_path / "clip_v001_00002.json").exists()
+    assert out["result"][0][1][-1] == str(video)
+
+
+def test_strict_version_replaces_on_collision_with_overwrite(tmp_path: Path) -> None:
+    """Deterministic by opt-in: enable_overwrite replaces the existing version."""
+    existing = tmp_path / "clip_v001.mp4"
+    existing.write_bytes(b"old")
+    video = tmp_path / "clip_v001_00002.mp4"
+    video.write_bytes(b"new")
+    result = {"result": ((True, [str(video)]),)}
+
+    out = _finalize_strict_version_output(
+        result,
+        enable_overwrite=True,
+        metadata_payload={"CreationTime": "t"},
+        save_metadata_json=True,
+    )
+
+    clean = tmp_path / "clip_v001.mp4"
+    assert clean.read_bytes() == b"new"
+    assert not video.exists()
+    assert out["result"][0][1][-1] == str(clean)
+
+
+def test_sidecar_is_drag_loadable_workflow_on_canvas() -> None:
+    """Canvas run: the sidecar IS the litegraph graph at top level, so dropping
+    it into ComfyUI reloads the workflow (not a metadata wrapper)."""
+    wf = {"last_node_id": 5, "nodes": [{"id": 1}], "links": []}
+    out = _build_sidecar_workflow({"1": {"class_type": "X"}}, {"workflow": wf}, "2026-05-29 01:00:00")
+    assert out["nodes"] == [{"id": 1}]
+    assert out["links"] == []
+    assert out["last_node_id"] == 5
+    assert out["extra"]["CreationTime"] == "2026-05-29 01:00:00"
+
+
+def test_sidecar_preserves_existing_workflow_extra() -> None:
+    wf = {"nodes": [], "extra": {"foo": "bar"}}
+    out = _build_sidecar_workflow(None, {"workflow": wf}, "t")
+    assert out["extra"] == {"foo": "bar", "CreationTime": "t"}
+
+
+def test_sidecar_falls_back_when_no_graph_available() -> None:
+    """Headless/API: no litegraph graph -> keep prompt + timestamp so the
+    sidecar is never empty (just not drag-loadable in that case)."""
+    out = _build_sidecar_workflow({"1": {"class_type": "X"}}, None, "2026-05-29 01:00:00")
+    assert out == {"CreationTime": "2026-05-29 01:00:00", "prompt": {"1": {"class_type": "X"}}}
+
+
+def test_sidecar_empty_inputs_still_timestamped() -> None:
+    out = _build_sidecar_workflow(None, None, "2026-05-29 01:00:00")
+    assert out == {"CreationTime": "2026-05-29 01:00:00"}
+
+
+def test_coerce_version_input_drops_stale_boolean() -> None:
+    """Back-compat guard: the removed keep_silent_intermediate BOOL must never
+    become a version token via the positional widget shift."""
+    assert _coerce_version_input(False) == ""
+    assert _coerce_version_input(True) == ""
+    assert _coerce_version_input("false") == ""
+    assert _coerce_version_input("True") == ""
+    assert _coerce_version_input("v001") == "v001"
+    assert _coerce_version_input("") == ""
+
+
+def test_strict_version_with_metadata_png_aligns_and_keeps_png(tmp_path: Path) -> None:
+    """strict + save_metadata_png: the PNG is renamed to the video's stem and
+    kept (not dropped), so video/png/json share one name."""
+    png = tmp_path / "clip_v001_00001.png"
+    png.write_bytes(b"img")
+    video = tmp_path / "clip_v001_00001.mp4"
+    video.write_bytes(b"vid")
+    result = {
+        "ui": {"gifs": [{"workflow": png.name}]},
+        "result": ((True, [str(png), str(video)]),),
+    }
+
+    out = _finalize_strict_version_output(
+        result,
+        enable_overwrite=False,
+        metadata_payload={"CreationTime": "t"},
+        save_metadata_json=True,
+        save_metadata_png=True,
+    )
+
+    files = out["result"][0][1]
+    assert (tmp_path / "clip_v001.mp4").exists()
+    assert (tmp_path / "clip_v001.png").exists()
+    assert (tmp_path / "clip_v001.json").exists()
+    assert str(tmp_path / "clip_v001.mp4") in files
+    assert str(tmp_path / "clip_v001.png") in files
+    assert str(tmp_path / "clip_v001.json") in files
+
+
+def test_final_video_path_prefers_video_over_sidecars(tmp_path: Path) -> None:
+    png = tmp_path / "clip_v001.png"
+    video = tmp_path / "clip_v001.mp4"
+    json_path = tmp_path / "clip_v001.json"
+    result = {"result": ((True, [str(png), str(video), str(json_path)]),)}
+
+    assert _final_video_path_from_result(result) == str(video)
+
+
+def test_final_json_path_reads_sidecar_from_output_list(tmp_path: Path) -> None:
+    video = tmp_path / "clip_v001.mp4"
+    json_path = tmp_path / "clip_v001.json"
+    result = {"result": ((True, [str(json_path), str(video)]),)}
+
+    assert _final_json_path_from_result(result, str(video)) == os.path.normpath(str(json_path))
+
+
+def test_final_json_path_falls_back_to_video_stem(tmp_path: Path) -> None:
+    video = tmp_path / "clip_v001.mp4"
+
+    assert _final_json_path_from_result({"result": ((True, [str(video)]),)}, str(video)) == str(
+        tmp_path / "clip_v001.json"
+    )
+
+
+def test_video_path_parts_returns_loader_friendly_strings(tmp_path: Path) -> None:
+    video = tmp_path / "clip_v001.mp4"
+
+    full_path, directory, name = _video_path_parts(str(video))
+
+    assert full_path == os.path.normpath(str(video))
+    assert directory == os.path.normpath(str(tmp_path))
+    assert name == "clip_v001.mp4"
+
+
+def test_append_video_path_outputs_preserves_original_filenames_output(tmp_path: Path) -> None:
+    video = tmp_path / "clip_v001.mp4"
+    json_path = tmp_path / "clip_v001.json"
+    result = {"ui": {"gifs": []}, "result": ((True, [str(json_path), str(video)]),)}
+
+    out = _append_video_path_outputs(result)
+
+    assert out["result"][0] == (True, [str(json_path), str(video)])
+    assert out["result"][1:] == (
+        os.path.normpath(str(video)),
+        os.path.normpath(str(tmp_path)),
+        "clip_v001.mp4",
+        os.path.normpath(str(json_path)),
+    )
+
+
+def test_combine_clean_outputs_round_trip_into_easy_load_video(tmp_path: Path) -> None:
+    video = tmp_path / "clip_v001.mp4"
+    json_path = tmp_path / "clip_v001.json"
+    result = {"result": ((True, [str(json_path), str(video)]),)}
+
+    out = _append_video_path_outputs(result)
+    video_path, video_directory, video_name, sidecar_path = out["result"][1:]
+
+    assert sidecar_path == os.path.normpath(str(json_path))
+    assert _compose_input_video_path(video_name, video_directory) == video_path
+    assert _compose_input_video_path(video_path, "") == video_path

ComfyUI/custom_nodes/koolook/tests/nodes/test_easy_video_load.py

@@ -0,0 +1,372 @@
+"""Tests for Easy_LoadVideo's split input path composition."""
+from __future__ import annotations
+
+import importlib
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+import k_video_load
+from k_video_load import (
+    EMPTY_BRANCH_SENTINEL,
+    _compose_input_video_path,
+    _is_existing_local_video_path,
+    _normalize_path_input,
+    _normalize_text_input,
+)
+
+
+def test_empty_input_path_passes_video_through() -> None:
+    assert _compose_input_video_path("E:/plates/shot01.mp4", "") == "E:/plates/shot01.mp4"
+    assert _compose_input_video_path("https://example.test/clip.mp4", "") == "https://example.test/clip.mp4"
+
+
+def test_empty_input_path_accepts_directory_and_filename_lines() -> None:
+    root = Path.cwd().anchor
+    absolute_dir = str(Path(root) / "projects" / "shot01")
+    composed = _compose_input_video_path(
+        f"{absolute_dir}\nplate_main.mp4",
+        "",
+    )
+    assert Path(composed) == Path(absolute_dir) / "plate_main.mp4"
+
+
+def test_absolute_input_path_joins_filename() -> None:
+    # Use a real tmp_path so the absolute-path branch is platform-neutral.
+    root = Path.cwd().anchor
+    absolute_dir = str(Path(root) / "projects" / "shot01")
+    composed = _compose_input_video_path(
+        "plate_main.mp4",
+        absolute_dir,
+    )
+    assert Path(composed) == Path(absolute_dir) / "plate_main.mp4"
+
+
+def test_input_path_accepts_full_video_path_when_video_empty() -> None:
+    root = Path.cwd().anchor
+    video_path = str(Path(root) / "projects" / "shot01" / "plate_main.mp4")
+
+    assert Path(_compose_input_video_path("", video_path)) == Path(video_path)
+
+
+def test_existing_local_video_path_detection(tmp_path: Path) -> None:
+    video = tmp_path / "plate_main.mp4"
+    video.write_bytes(b"fake")
+
+    assert _is_existing_local_video_path(str(video)) is True
+    assert _is_existing_local_video_path(str(tmp_path / "plate_main.json")) is False
+    assert _is_existing_local_video_path(str(tmp_path / "missing.mp4")) is False
+
+
+def test_relative_input_path_accepts_full_video_path_when_video_empty(tmp_path: Path) -> None:
+    composed = _compose_input_video_path(
+        "",
+        "shots/shot01/plate_main.mp4",
+        input_root=str(tmp_path),
+    )
+    assert Path(composed) == tmp_path / "shots" / "shot01" / "plate_main.mp4"
+
+
+def test_wrapped_full_video_path_in_input_path_rejoins_before_loading(tmp_path: Path) -> None:
+    folder = tmp_path / "Runs-Audio-File"
+    folder.mkdir()
+    video = folder / "Bear_2x-FR_AudioFile_K-Dir_h264_v002.mp4"
+    video.write_bytes(b"fake")
+    wrapped = str(video).replace("Runs-Audio-File", "Runs-Audio-\nFile")
+
+    composed = _compose_input_video_path("", wrapped)
+
+    assert Path(composed) == video
+
+
+def test_input_path_accepts_directory_and_filename_lines_when_video_empty(tmp_path: Path) -> None:
+    video = tmp_path / "plate_main.mp4"
+    video.write_bytes(b"fake")
+
+    composed = _compose_input_video_path("", f"{tmp_path}\nplate_main.mp4")
+
+    assert Path(composed) == video
+
+
+def test_normalize_path_input_prefers_existing_wrapped_path(tmp_path: Path) -> None:
+    folder = tmp_path / "Runs-Audio-File"
+    folder.mkdir()
+    video = folder / "clip.mov"
+    video.write_bytes(b"fake")
+
+    assert _normalize_path_input(str(video).replace("Runs-Audio-File", "Runs-Audio-\nFile")) == str(video)
+
+
+def test_relative_input_path_roots_under_comfy_input_dir(tmp_path: Path) -> None:
+    composed = _compose_input_video_path(
+        "plate_main.mp4",
+        "shots/shot01",
+        input_root=str(tmp_path),
+    )
+    assert Path(composed) == tmp_path / "shots" / "shot01" / "plate_main.mp4"
+
+
+def test_input_path_strips_video_path_components(tmp_path: Path) -> None:
+    composed = _compose_input_video_path(
+        "accidental/subdir/plate_main.mp4",
+        "shots/shot01",
+        input_root=str(tmp_path),
+    )
+    assert Path(composed) == tmp_path / "shots" / "shot01" / "plate_main.mp4"
+
+
+def test_input_path_strips_windows_video_path_components(tmp_path: Path) -> None:
+    composed = _compose_input_video_path(
+        "accidental\\subdir\\plate_main.mp4",
+        "shots/shot01",
+        input_root=str(tmp_path),
+    )
+    assert Path(composed) == tmp_path / "shots" / "shot01" / "plate_main.mp4"
+
+
+def test_input_path_requires_filename() -> None:
+    # A non-existent path with no filename is a genuine mistake and still errors.
+    with pytest.raises(ValueError, match="video must include a filename"):
+        _compose_input_video_path("", "/no/such/projects/shot01")
+
+
+def test_existing_directory_input_path_degrades_to_empty_sentinel(tmp_path: Path) -> None:
+    # A real folder (e.g. an EXR sequence dir) handed to the video loader is the
+    # unselected branch of an upstream mode switch. Instead of crashing the whole
+    # prompt, _compose_input_video_path signals a graceful empty so the loader can
+    # return nothing rather than raise -- mirroring how lenient sequence loaders
+    # ignore a wrong-type path.
+    seq_dir = tmp_path / "exr_seq"
+    seq_dir.mkdir()
+    assert _compose_input_video_path("", str(seq_dir)) == EMPTY_BRANCH_SENTINEL
+
+
+def test_relative_existing_directory_input_path_degrades(tmp_path: Path) -> None:
+    (tmp_path / "shots" / "shot01").mkdir(parents=True)
+    assert (
+        _compose_input_video_path("", "shots/shot01", input_root=str(tmp_path))
+        == EMPTY_BRANCH_SENTINEL
+    )
+
+
+def test_normalize_text_input_handles_frontend_sentinels() -> None:
+    assert _normalize_text_input("undefined") == ""
+    assert _normalize_text_input("None") == ""
+    assert _normalize_text_input("  plate_main.mp4\nundefined") == "plate_main.mp4"
+
+
+def test_easy_load_video_calls_vhs_loader_directly_for_existing_full_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    calls = []
+
+    def fake_shared_loader(**kwargs):
+        calls.append(kwargs)
+        return ("loaded", kwargs["video"])
+
+    class FakeVHSLoadVideoPath:
+        @classmethod
+        def INPUT_TYPES(cls):
+            return {
+                "required": {
+                    "video": ("STRING", {}),
+                    "force_rate": ("FLOAT", {}),
+                },
+                "optional": {},
+            }
+
+        def load_video(self, **kwargs):
+            raise AssertionError("strict VHS LoadVideoPath.load_video should be bypassed")
+
+        @classmethod
+        def IS_CHANGED(cls, video, **kwargs):
+            return video
+
+        @classmethod
+        def VALIDATE_INPUTS(cls, video):
+            return f"strict validator rejected {video}"
+
+    FakeVHSLoadVideoPath.load_video.__globals__["load_video"] = fake_shared_loader
+    fake_nodes = types.SimpleNamespace(
+        NODE_CLASS_MAPPINGS={"VHS_LoadVideoPath": FakeVHSLoadVideoPath}
+    )
+    fake_folder_paths = types.SimpleNamespace(get_input_directory=lambda: str(tmp_path))
+    monkeypatch.setitem(sys.modules, "nodes", fake_nodes)
+    monkeypatch.setitem(sys.modules, "folder_paths", fake_folder_paths)
+    loaded = importlib.reload(k_video_load)
+
+    video = tmp_path / "plate_main.mp4"
+    video.write_bytes(b"fake")
+    result = loaded.Easy_LoadVideo().load_video(
+        input_path=str(video),
+        video="",
+        force_rate=0,
+    )
+
+    assert result == ("loaded", str(video))
+    assert calls[-1]["video"] == str(video)
+    assert loaded.Easy_LoadVideo.VALIDATE_INPUTS("", str(video)) is True
+
+    monkeypatch.delitem(sys.modules, "nodes")
+    monkeypatch.delitem(sys.modules, "folder_paths")
+    importlib.reload(k_video_load)
+
+
+def test_easy_load_video_validation_defers_when_input_path_is_linked(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    calls = []
+
+    class FakeVHSLoadVideoPath:
+        @classmethod
+        def INPUT_TYPES(cls):
+            return {"required": {"video": ("STRING", {})}, "optional": {}}
+
+        def load_video(self, **kwargs):
+            return ("loaded", kwargs["video"])
+
+        @classmethod
+        def IS_CHANGED(cls, video, **kwargs):
+            return video
+
+        @classmethod
+        def VALIDATE_INPUTS(cls, video):
+            calls.append(video)
+            return f"strict validator rejected {video}"
+
+    FakeVHSLoadVideoPath.load_video.__globals__["load_video"] = lambda **kwargs: (
+        "loaded",
+        kwargs["video"],
+    )
+    fake_nodes = types.SimpleNamespace(
+        NODE_CLASS_MAPPINGS={"VHS_LoadVideoPath": FakeVHSLoadVideoPath}
+    )
+    fake_folder_paths = types.SimpleNamespace(get_input_directory=lambda: str(tmp_path))
+    monkeypatch.setitem(sys.modules, "nodes", fake_nodes)
+    monkeypatch.setitem(sys.modules, "folder_paths", fake_folder_paths)
+    loaded = importlib.reload(k_video_load)
+
+    assert loaded.Easy_LoadVideo.VALIDATE_INPUTS(
+        video="",
+        input_path=None,
+        force_rate=0,
+        custom_width=0,
+        custom_height=0,
+        frame_load_cap=0,
+        skip_first_frames=0,
+        select_every_nth=1,
+        format="AnimateDiff",
+        unique_id="627",
+    ) is True
+    assert calls == []
+
+    monkeypatch.delitem(sys.modules, "nodes")
+    monkeypatch.delitem(sys.modules, "folder_paths")
+    importlib.reload(k_video_load)
+
+
+def test_easy_load_video_rejoins_wrapped_input_path_before_direct_vhs_loader(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    calls = []
+
+    def fake_shared_loader(**kwargs):
+        calls.append(kwargs)
+        return ("loaded", kwargs["video"])
+
+    class FakeVHSLoadVideoPath:
+        @classmethod
+        def INPUT_TYPES(cls):
+            return {"required": {"video": ("STRING", {})}, "optional": {}}
+
+        def load_video(self, **kwargs):
+            raise AssertionError("strict VHS LoadVideoPath.load_video should be bypassed")
+
+        @classmethod
+        def IS_CHANGED(cls, video, **kwargs):
+            return video
+
+        @classmethod
+        def VALIDATE_INPUTS(cls, video):
+            return f"strict validator rejected {video}"
+
+    FakeVHSLoadVideoPath.load_video.__globals__["load_video"] = fake_shared_loader
+    fake_nodes = types.SimpleNamespace(
+        NODE_CLASS_MAPPINGS={"VHS_LoadVideoPath": FakeVHSLoadVideoPath}
+    )
+    fake_folder_paths = types.SimpleNamespace(get_input_directory=lambda: str(tmp_path))
+    monkeypatch.setitem(sys.modules, "nodes", fake_nodes)
+    monkeypatch.setitem(sys.modules, "folder_paths", fake_folder_paths)
+    loaded = importlib.reload(k_video_load)
+
+    folder = tmp_path / "Runs-Audio-File"
+    folder.mkdir()
+    video = folder / "Bear_2x-FR_AudioFile_K-Dir_h264_v002.mp4"
+    video.write_bytes(b"fake")
+    wrapped = str(video).replace("Runs-Audio-File", "Runs-Audio-\nFile")
+
+    result = loaded.Easy_LoadVideo().load_video(input_path=wrapped, video="")
+
+    assert result == ("loaded", str(video))
+    assert calls[-1]["video"] == str(video)
+
+    monkeypatch.delitem(sys.modules, "nodes")
+    monkeypatch.delitem(sys.modules, "folder_paths")
+    importlib.reload(k_video_load)
+
+
+def test_easy_load_video_returns_empty_result_for_existing_directory(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    # When the loader is handed an existing folder (the unselected EXR branch of
+    # an upstream switch), it must return an empty, correctly-shaped result
+    # instead of raising -- so the dead branch never crashes the prompt.
+    class FakeVHSLoadVideoPath:
+        RETURN_TYPES = ("IMAGE", "INT", "AUDIO", "VHS_VIDEOINFO")
+
+        @classmethod
+        def INPUT_TYPES(cls):
+            return {"required": {"video": ("STRING", {})}, "optional": {}}
+
+        def load_video(self, **kwargs):
+            raise AssertionError("loader must not run for an empty/unselected branch")
+
+    FakeVHSLoadVideoPath.load_video.__globals__["load_video"] = lambda **kwargs: (
+        _ for _ in ()
+    ).throw(AssertionError("shared loader must not run for an empty branch"))
+    fake_nodes = types.SimpleNamespace(
+        NODE_CLASS_MAPPINGS={"VHS_LoadVideoPath": FakeVHSLoadVideoPath}
+    )
+    fake_folder_paths = types.SimpleNamespace(get_input_directory=lambda: str(tmp_path))
+    fake_torch = types.SimpleNamespace(
+        zeros=lambda *shape, **kw: ("zeros", shape),
+        float32="float32",
+    )
+    monkeypatch.setitem(sys.modules, "nodes", fake_nodes)
+    monkeypatch.setitem(sys.modules, "folder_paths", fake_folder_paths)
+    monkeypatch.setitem(sys.modules, "torch", fake_torch)
+    loaded = importlib.reload(k_video_load)
+
+    seq_dir = tmp_path / "exr_seq"
+    seq_dir.mkdir()
+    result = loaded.Easy_LoadVideo().load_video(input_path=str(seq_dir), video="")
+    captured = capsys.readouterr()
+
+    assert isinstance(result, tuple) and len(result) == 4
+    assert result[0] == ("zeros", ((1, 64, 64, 3),))  # empty IMAGE (shape passed as one arg)
+    assert result[1] == 0  # frame_count
+    assert result[2]["sample_rate"] == 44100  # empty AUDIO
+    assert result[3] == {}  # empty VHS_VIDEOINFO
+    assert "existing folder with no video filename" in captured.out
+
+    monkeypatch.delitem(sys.modules, "nodes")
+    monkeypatch.delitem(sys.modules, "folder_paths")
+    monkeypatch.delitem(sys.modules, "torch")
+    importlib.reload(k_video_load)

ComfyUI/custom_nodes/koolook/tests/nodes/test_koolook_versioning.py

@@ -0,0 +1,67 @@
+"""Unit tests for the shared ``koolook_versioning`` helpers.
+
+These pin the single source of truth for the ``vNNN`` convention shared by
+``EasyAIPipeline`` and ``Easy_VideoCombine``. The load-bearing contract is
+that a wired/typed version STRING wins verbatim over the legacy INT widget
+and over ``disable_versioning`` — that's what lets one "global version"
+source drive every node consistently.
+"""
+from __future__ import annotations
+
+from koolook_versioning import normalize_version_token, resolve_version_token
+
+
+class TestNormalizeVersionToken:
+    def test_empty_and_none(self):
+        assert normalize_version_token("") == ""
+        assert normalize_version_token("   ") == ""
+        assert normalize_version_token(None) == ""
+
+    def test_sentinels_become_empty(self):
+        assert normalize_version_token("undefined") == ""
+        assert normalize_version_token("Undefined") == ""
+        assert normalize_version_token("NULL") == ""
+        assert normalize_version_token("None") == ""
+
+    def test_verbatim_values_pass_through(self):
+        assert normalize_version_token("v001") == "v001"
+        assert normalize_version_token("final") == "final"
+        assert normalize_version_token("take_3") == "take_3"
+        # A substring match of a sentinel must NOT trigger.
+        assert normalize_version_token("v_undefined_3") == "v_undefined_3"
+
+    def test_surrounding_whitespace_and_quotes_stripped(self):
+        assert normalize_version_token("  v002  ") == "v002"
+        assert normalize_version_token('"v002"') == "v002"
+        assert normalize_version_token("'v002'") == "v002"
+
+    def test_control_chars_stripped(self):
+        assert normalize_version_token("v0\n01") == "v001"
+        assert normalize_version_token("v001\t") == "v001"
+
+    def test_path_separators_flattened(self):
+        assert normalize_version_token("v001/extra") == "v001_extra"
+        assert normalize_version_token("a\\b") == "a_b"
+
+
+class TestResolveVersionToken:
+    def test_disable_versioning_is_master_off(self):
+        assert resolve_version_token("v007", disable_versioning=True) == ""
+        assert resolve_version_token("5", disable_versioning=True) == ""
+
+    def test_empty_or_sentinel_returns_empty(self):
+        assert resolve_version_token("") == ""
+        assert resolve_version_token("   ") == ""
+        assert resolve_version_token("undefined") == ""
+
+    def test_bare_number_becomes_vnnn(self):
+        # Back-compat with the old INT widget + convenience when typing.
+        assert resolve_version_token("3") == "v003"
+        assert resolve_version_token("12") == "v012"
+        # A saved workflow's stored INT arrives as a number, not a string.
+        assert resolve_version_token(5) == "v005"
+
+    def test_token_used_verbatim(self):
+        assert resolve_version_token("v001") == "v001"
+        assert resolve_version_token("final") == "final"
+        assert resolve_version_token("v2_take3") == "v2_take3"

ComfyUI/custom_nodes/koolook/tests/nodes/test_loop_status.py

@@ -0,0 +1,512 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Tests for the loop status pass-through node."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+
+import pytest
+
+import k_loop_status
+from k_loop_status import (
+    DEFAULT_SERVER_URL,
+    KoolookLoopStatus,
+    _post_prompt,
+    _resolve_server_url,
+    build_status,
+    infer_index_node_id,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clear_active_queue_keys():
+    """Reset the module-global auto-queue dedup set between tests."""
+    k_loop_status._ACTIVE_QUEUE_KEYS.clear()
+    yield
+    k_loop_status._ACTIVE_QUEUE_KEYS.clear()
+
+
+def test_build_status_formats_one_based_position_and_frame_path():
+    assert (
+        build_status("write", 2, 4, "N:/out/frame.%04d.exr")
+        == "write: 3/4 frame 2 -> N:/out/frame.0002.exr"
+    )
+
+
+def test_build_status_formats_other_padded_frame_patterns():
+    assert (
+        build_status("write", 12, 20, "N:/out/frame.%05d.exr")
+        == "write: 13/20 frame 12 -> N:/out/frame.00012.exr"
+    )
+
+
+def test_report_prints_status_and_passes_value_through(capsys):
+    value = object()
+    node = KoolookLoopStatus()
+
+    out_value, status = node.report(
+        value,
+        index=0,
+        total=4,
+        filepath="N:/out/frame.%04d.exr",
+        label="EXR_SAFE",
+    )
+
+    assert out_value is value
+    assert status == "EXR_SAFE: 1/4 frame 0 -> N:/out/frame.0000.exr"
+    assert "[Koolook Loop Status] EXR_SAFE: 1/4" in capsys.readouterr().out
+
+
+def test_registration_exports():
+    from k_loop_status import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+
+    assert NODE_CLASS_MAPPINGS["Koolook_LoopStatus"] is KoolookLoopStatus
+    assert NODE_DISPLAY_NAME_MAPPINGS["Koolook_LoopStatus"] == "Koolook Loop Status"
+
+
+def test_input_types_include_queue_controller_settings():
+    optional = KoolookLoopStatus.INPUT_TYPES()["optional"]
+    hidden = KoolookLoopStatus.INPUT_TYPES()["hidden"]
+
+    assert "auto_queue_next" in optional
+    assert "index_node_id" in optional
+    assert "server_url" in optional
+    assert "max_auto_queue_depth" in optional
+    assert "remaining_auto_queue_depth" in optional
+    assert hidden["prompt"] == "PROMPT"
+
+
+def test_infers_index_node_id_from_connected_index_input():
+    prompt = {"21": {"inputs": {"index": ["22", 0]}}}
+
+    assert infer_index_node_id(prompt, "21") == "22"
+
+
+def test_numeric_label_is_treated_as_shifted_index_node_id(capsys):
+    node = KoolookLoopStatus()
+
+    _value, status = node.report(
+        "image",
+        0,
+        4,
+        label="22",
+        auto_queue_next=False,
+    )
+
+    assert status == "EXR_SAFE: 1/4 frame 0"
+    assert "[Koolook Loop Status] EXR_SAFE: 1/4" in capsys.readouterr().out
+
+
+def test_depth_guard_raises_before_status_print(capsys):
+    node = KoolookLoopStatus()
+
+    with pytest.raises(RuntimeError, match="Refusing to auto-queue"):
+        node.report(
+            "image",
+            0,
+            5,
+            auto_queue_next=True,
+            index_node_id="22",
+            max_auto_queue_depth=2,
+            prompt={"21": {"inputs": {}}},
+        )
+
+    assert "[Koolook Loop Status]" not in capsys.readouterr().out
+
+
+def test_resolve_server_url_keeps_custom_value(monkeypatch):
+    monkeypatch.setattr(
+        k_loop_status, "_detect_local_server_url", lambda: "http://127.0.0.1:9999"
+    )
+
+    assert _resolve_server_url("http://10.0.0.5:7000") == "http://10.0.0.5:7000"
+
+
+def test_resolve_server_url_overrides_default_with_detected_port(monkeypatch):
+    monkeypatch.setattr(
+        k_loop_status, "_detect_local_server_url", lambda: "http://127.0.0.1:8000"
+    )
+
+    assert _resolve_server_url(DEFAULT_SERVER_URL) == "http://127.0.0.1:8000"
+    assert _resolve_server_url("") == "http://127.0.0.1:8000"
+
+
+def test_resolve_server_url_falls_back_to_default_when_undetectable(monkeypatch):
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", lambda: None)
+
+    assert _resolve_server_url(DEFAULT_SERVER_URL) == DEFAULT_SERVER_URL
+
+
+def test_resolve_server_url_blank_falls_back_to_default_when_undetectable(monkeypatch):
+    """Blank input must behave like the default when detection is unavailable."""
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", lambda: None)
+
+    assert _resolve_server_url("") == DEFAULT_SERVER_URL
+
+
+def test_resolve_server_url_auto_triggers_detection(monkeypatch):
+    """The `auto` sentinel (the widget default) auto-detects, case-insensitively."""
+    monkeypatch.setattr(
+        k_loop_status, "_detect_local_server_url", lambda: "http://127.0.0.1:8000"
+    )
+
+    assert _resolve_server_url("auto") == "http://127.0.0.1:8000"
+    assert _resolve_server_url("AUTO") == "http://127.0.0.1:8000"
+    assert _resolve_server_url("  auto  ") == "http://127.0.0.1:8000"
+
+
+def test_resolve_server_url_auto_falls_back_to_default_when_undetectable(monkeypatch):
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", lambda: None)
+
+    assert _resolve_server_url("auto") == DEFAULT_SERVER_URL
+
+
+def test_server_url_widget_defaults_to_auto():
+    optional = KoolookLoopStatus.INPUT_TYPES()["optional"]
+
+    assert optional["server_url"][1]["default"] == "auto"
+
+
+def test_compose_server_url_brackets_ipv6_literal():
+    assert k_loop_status._compose_server_url("::1", 8000) == "http://[::1]:8000"
+    assert (
+        k_loop_status._compose_server_url("2001:db8::1", 8000)
+        == "http://[2001:db8::1]:8000"
+    )
+    # Idempotent: an already-bracketed literal must not be double-bracketed.
+    assert k_loop_status._compose_server_url("[::1]", 8000) == "http://[::1]:8000"
+
+
+def test_compose_server_url_ipv6_result_passes_validation():
+    """A bracketed IPv6 URL must parse through the pre-queue validator."""
+    url = k_loop_status._compose_server_url("::1", 8000)
+
+    k_loop_status._validate_http_url(url)  # must not raise
+    assert urllib.parse.urlsplit(url).port == 8000
+
+
+def test_compose_server_url_remaps_bind_all_to_localhost():
+    assert k_loop_status._compose_server_url("0.0.0.0", 8000) == "http://127.0.0.1:8000"  # nosec B104
+    assert k_loop_status._compose_server_url("::", 8000) == "http://127.0.0.1:8000"
+    # ComfyUI's bare `--listen` is the comma-joined "all IPv4 and IPv6" value.
+    assert (
+        k_loop_status._compose_server_url("0.0.0.0,::", 8000)  # nosec B104
+        == "http://127.0.0.1:8000"
+    )
+    # Order-independent: a bind-all member anywhere in the list routes to loopback.
+    assert (
+        k_loop_status._compose_server_url("::,0.0.0.0", 8000)  # nosec B104
+        == "http://127.0.0.1:8000"
+    )
+    # No bind-all member: the first concrete host is used verbatim.
+    assert (
+        k_loop_status._compose_server_url("10.0.0.5,192.168.1.9", 8000)
+        == "http://10.0.0.5:8000"
+    )
+
+
+def test_compose_server_url_keeps_ipv4_hostname_and_defaults_blank():
+    assert k_loop_status._compose_server_url("127.0.0.1", 8000) == "http://127.0.0.1:8000"
+    assert k_loop_status._compose_server_url("localhost", 8000) == "http://localhost:8000"
+    assert k_loop_status._compose_server_url("", 8000) == "http://127.0.0.1:8000"
+
+
+def test_probe_uses_detected_port_not_stale_default(monkeypatch):
+    """Auto-queue on a non-default port must probe the running server."""
+    monkeypatch.setattr(
+        k_loop_status, "_detect_local_server_url", lambda: "http://127.0.0.1:8000"
+    )
+    probed = {}
+    monkeypatch.setattr(
+        k_loop_status, "_probe_server", lambda url: probed.update(url=url)
+    )
+    # Don't actually spawn the queue thread; we only care about the probe target.
+    class _NoopThread:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def start(self):
+            pass
+
+    monkeypatch.setattr(k_loop_status.threading, "Thread", _NoopThread)
+
+    node = KoolookLoopStatus()
+    node.report(
+        "image",
+        0,
+        4,
+        auto_queue_next=True,
+        index_node_id="22",
+        server_url=DEFAULT_SERVER_URL,
+        prompt={"21": {"inputs": {}}, "22": {"inputs": {}}},
+        unique_id="21",
+    )
+
+    assert probed["url"] == "http://127.0.0.1:8000"
+
+
+def test_status_only_does_not_resolve_server_url(monkeypatch):
+    """With auto-queue off, the node must not detect/probe the server URL."""
+    called = {"detect": False}
+
+    def _flag_detect():
+        called["detect"] = True
+        return None
+
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", _flag_detect)
+
+    KoolookLoopStatus().report("image", 0, 4, auto_queue_next=False)
+
+    assert called["detect"] is False
+
+
+def test_stale_index_node_id_self_heals_from_connected_index(monkeypatch):
+    """A shifted index_node_id like '0' falls back to the connected index node."""
+    monkeypatch.setattr(
+        k_loop_status, "_detect_local_server_url", lambda: "http://127.0.0.1:8000"
+    )
+    monkeypatch.setattr(k_loop_status, "_probe_server", lambda url: None)
+    captured = {}
+
+    class _NoopThread:
+        def __init__(self, *args, **kwargs):
+            captured.update(kwargs.get("kwargs", {}))
+
+        def start(self):
+            pass
+
+    monkeypatch.setattr(k_loop_status.threading, "Thread", _NoopThread)
+
+    prompt = {
+        "21": {"inputs": {"index": ["22", 0]}},
+        "22": {"inputs": {"value": 0}},
+    }
+    _value, status = KoolookLoopStatus().report(
+        "image",
+        0,
+        4,
+        auto_queue_next=True,
+        index_node_id="0",
+        prompt=prompt,
+        unique_id="21",
+    )
+
+    assert status.startswith("loop: 1/4")
+    assert captured["index_node_id"] == "22"
+
+
+def test_unknown_index_node_id_raises_synchronously():
+    """An index_node_id with no matching node and no connection fails up front."""
+    node = KoolookLoopStatus()
+
+    with pytest.raises(RuntimeError, match="is not a node in this workflow"):
+        node.report(
+            "image",
+            0,
+            4,
+            auto_queue_next=True,
+            index_node_id="0",
+            prompt={"21": {"inputs": {}}},
+            unique_id="21",
+        )
+
+
+def test_as_bool_coerces_saved_string_booleans():
+    assert k_loop_status._as_bool("true") is True
+    assert k_loop_status._as_bool(" True ") is True
+    assert k_loop_status._as_bool("1") is True
+    assert k_loop_status._as_bool("yes") is True
+    assert k_loop_status._as_bool("on") is True
+    assert k_loop_status._as_bool("false") is False
+    assert k_loop_status._as_bool("no") is False
+    assert k_loop_status._as_bool("off") is False
+    assert k_loop_status._as_bool("0") is False
+    assert k_loop_status._as_bool("") is False
+    assert k_loop_status._as_bool(True) is True
+    assert k_loop_status._as_bool(0) is False
+
+
+def test_resolve_index_node_id_prefers_configured_when_present():
+    prompt = {"543": {"class_type": "easy int", "inputs": {"value": 0}}}
+
+    node_id, note = k_loop_status.resolve_index_node_id(prompt, "21", "543")
+
+    assert node_id == "543"
+    assert "using configured easy int node 543" in note
+
+
+def test_resolve_index_node_id_falls_back_from_stale_manual_id():
+    prompt = {
+        "21": {"inputs": {"index": ["543", 0]}},
+        "543": {"class_type": "easy int", "inputs": {"value": 0}},
+    }
+
+    node_id, note = k_loop_status.resolve_index_node_id(prompt, "21", "22")
+
+    assert node_id == "543"
+    assert "configured index node '22' is not in this prompt" in note
+    assert "easy int node 543" in note
+
+
+def test_resolve_index_node_id_infers_when_blank():
+    prompt = {"21": {"inputs": {"index": ["543", 0]}}, "543": {"inputs": {}}}
+
+    node_id, note = k_loop_status.resolve_index_node_id(prompt, "21", "")
+
+    assert node_id == "543"
+    assert note.startswith("using connected")
+
+
+def test_resolve_index_node_id_returns_empty_when_unresolvable():
+    assert k_loop_status.resolve_index_node_id({"21": {"inputs": {}}}, "21", "") == ("", "")
+
+
+def test_describe_prompt_node_without_class_type_is_not_doubled():
+    assert k_loop_status._describe_prompt_node({"22": {"inputs": {}}}, "22") == "node 22"
+    assert (
+        k_loop_status._describe_prompt_node({"22": {"_meta": {"title": "Frame"}}}, "22")
+        == "Frame node 22"
+    )
+
+
+def test_resolve_index_node_id_fallback_does_not_override_connected():
+    """A recovered numeric label is last-resort; the connected wire still wins."""
+    prompt = {
+        "21": {"inputs": {"index": ["543", 0]}},
+        "543": {"class_type": "easy int", "inputs": {"value": 0}},
+        "22": {"class_type": "easy int", "inputs": {"value": 0}},
+    }
+
+    node_id, note = k_loop_status.resolve_index_node_id(prompt, "21", "", fallback_id="22")
+
+    assert node_id == "543"
+    assert "connected easy int node 543" in note
+
+
+def test_resolve_index_node_id_uses_fallback_when_nothing_else_resolves():
+    node_id, note = k_loop_status.resolve_index_node_id(None, None, "", fallback_id="22")
+
+    assert node_id == "22"
+    assert "recovered node 22" in note
+
+
+def test_numeric_label_does_not_override_connected_index(monkeypatch):
+    """User scenario: a node id stuck in `label` must not beat the wired index."""
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", lambda: None)
+    monkeypatch.setattr(k_loop_status, "_probe_server", lambda url: None)
+    captured = {}
+
+    class _NoopThread:
+        def __init__(self, *args, **kwargs):
+            captured.update(kwargs.get("kwargs", {}))
+
+        def start(self):
+            pass
+
+    monkeypatch.setattr(k_loop_status.threading, "Thread", _NoopThread)
+
+    prompt = {
+        "21": {"inputs": {"index": ["543", 0]}},
+        "543": {"class_type": "easy int", "inputs": {"value": 0}},
+        "22": {"class_type": "easy int", "inputs": {"value": 0}},
+    }
+    _value, status = KoolookLoopStatus().report(
+        "image",
+        0,
+        2,
+        label="22",
+        auto_queue_next=True,
+        prompt=prompt,
+        unique_id="21",
+    )
+
+    assert captured["index_node_id"] == "543"
+    assert status.startswith("EXR_SAFE: 1/2")
+
+
+def test_resolve_index_node_id_explicit_override_beats_connected_wire():
+    """An explicit, valid index_node_id is a power-user override and wins over the wire."""
+    prompt = {
+        "21": {"inputs": {"index": ["543", 0]}},
+        "543": {"class_type": "easy int", "inputs": {"value": 0}},
+        "99": {"class_type": "easy int", "inputs": {"value": 0}},
+    }
+
+    node_id, note = k_loop_status.resolve_index_node_id(prompt, "21", "99")
+
+    assert node_id == "99"
+    assert "using configured easy int node 99" in note
+
+
+def test_string_false_auto_queue_does_not_queue():
+    """A saved 'false' string must not auto-queue (bool('false') is truthy)."""
+    node = KoolookLoopStatus()
+
+    _value, status = node.report(
+        "image",
+        0,
+        4,
+        auto_queue_next="false",
+        index_node_id="22",
+        prompt={"21": {"inputs": {}}},
+        unique_id="21",
+    )
+
+    assert status == "loop: 1/4 frame 0"
+
+
+def test_string_true_auto_queue_logs_detected_index_node(monkeypatch, capsys):
+    """Saved 'true' enables auto-queue; the chosen index node class/id is logged."""
+    monkeypatch.setattr(k_loop_status, "_detect_local_server_url", lambda: None)
+    monkeypatch.setattr(k_loop_status, "_probe_server", lambda url: None)
+    captured = {}
+
+    class _NoopThread:
+        def __init__(self, *args, **kwargs):
+            captured.update(kwargs.get("kwargs", {}))
+
+        def start(self):
+            pass
+
+    monkeypatch.setattr(k_loop_status.threading, "Thread", _NoopThread)
+
+    prompt = {
+        "21": {"inputs": {"index": ["543", 0]}},
+        "543": {"class_type": "easy int", "inputs": {"value": 0}},
+    }
+    _value, status = KoolookLoopStatus().report(
+        "image",
+        0,
+        2,
+        auto_queue_next="true",
+        index_node_id="22",
+        prompt=prompt,
+        unique_id="21",
+    )
+
+    assert status.startswith("loop: 1/2")
+    assert captured["index_node_id"] == "543"
+    assert "easy int node 543" in capsys.readouterr().out
+
+
+def test_post_prompt_rejects_error_payload(monkeypatch):
+    class Response:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_args):
+            return False
+
+        def read(self):
+            return json.dumps({"error": "bad prompt"}).encode("utf-8")
+
+    monkeypatch.setattr("urllib.request.urlopen", lambda *_args, **_kwargs: Response())
+
+    with pytest.raises(RuntimeError, match="rejected child prompt"):
+        _post_prompt("http://127.0.0.1:8188", {})
+
+
+def test_post_prompt_rejects_non_http_url():
+    with pytest.raises(RuntimeError, match=r"Only http\(s\)"):
+        _post_prompt("file:///tmp/comfy.sock", {})

ComfyUI/custom_nodes/koolook/tests/nodes/test_next_version.py

@@ -0,0 +1,104 @@
+"""Tests for filesystem-aware output version auto-detection."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from koolook_versioning import next_version_token
+
+
+def test_missing_directory_returns_start(tmp_path: Path) -> None:
+    missing = tmp_path / "does_not_exist"
+    assert next_version_token(str(missing), "bearMask") == "v001"
+
+
+def test_empty_directory_returns_start(tmp_path: Path) -> None:
+    assert next_version_token(str(tmp_path), "bearMask") == "v001"
+
+
+def test_unreadable_directory_error_is_not_hidden(monkeypatch: pytest.MonkeyPatch) -> None:
+    def blocked(_directory):
+        raise PermissionError("no access")
+
+    monkeypatch.setattr("koolook_versioning.os.listdir", blocked)
+
+    with pytest.raises(PermissionError, match="no access"):
+        next_version_token("blocked-output", "bearMask")
+
+
+def test_next_after_existing_versioned_files(tmp_path: Path) -> None:
+    (tmp_path / "bearMask_v001.png").write_bytes(b"x")
+    (tmp_path / "bearMask_v002.png").write_bytes(b"x")
+    assert next_version_token(str(tmp_path), "bearMask") == "v003"
+
+
+def test_next_ignores_other_names(tmp_path: Path) -> None:
+    (tmp_path / "bearMask_v005.png").write_bytes(b"x")
+    (tmp_path / "otherShot_v009.png").write_bytes(b"x")
+    # Exact base-name match only -- otherShot must not bump bearMask.
+    assert next_version_token(str(tmp_path), "bearMask") == "v006"
+
+
+def test_next_matches_versioned_subfolders(tmp_path: Path) -> None:
+    (tmp_path / "bearMask_v003").mkdir()
+    (tmp_path / "bearMask_v007").mkdir()
+    assert next_version_token(str(tmp_path), "bearMask") == "v008"
+
+
+def test_next_handles_exr_sequence_names(tmp_path: Path) -> None:
+    (tmp_path / "bearMask_v002.0001.exr").write_bytes(b"x")
+    (tmp_path / "bearMask_v002.0002.exr").write_bytes(b"x")
+    assert next_version_token(str(tmp_path), "bearMask") == "v003"
+
+
+def test_padding_and_prefix_are_configurable(tmp_path: Path) -> None:
+    (tmp_path / "clip_take2.mov").write_bytes(b"x")
+    assert (
+        next_version_token(str(tmp_path), "clip", version_prefix="take", padding=1)
+        == "take3"
+    )
+
+
+def test_empty_name_matches_bare_version_tokens(tmp_path: Path) -> None:
+    (tmp_path / "v004.png").write_bytes(b"x")
+    assert next_version_token(str(tmp_path), "") == "v005"
+
+
+def test_is_auto_version_detects_keywords() -> None:
+    from koolook_versioning import is_auto_version
+
+    for yes in ("auto", "AUTO", " next ", "Next", '"auto"'):
+        assert is_auto_version(yes) is True
+    for no in ("", "v001", "3", "final", "automatic", None):
+        assert is_auto_version(no) is False
+
+
+def test_ai_pipeline_auto_version_picks_next(tmp_path: Path) -> None:
+    from k_ai_pipeline import build_pipeline_outputs
+
+    # Existing version folders v001/v002 under the base (no_subfolders mode).
+    (tmp_path / "v001").mkdir()
+    (tmp_path / "v002").mkdir()
+    out = build_pipeline_outputs(
+        81, 1, "", str(tmp_path), ".png", "bearMask", "", "auto",
+        False, False, True,
+        create_directory=False, check_overwrite=False,
+    )
+    file_path, name, version_str = out[0], out[1], out[2]
+    assert version_str == "v003"
+    assert name == "bearMask_v003.png"
+    assert file_path.endswith("/v003/bearMask_v003.png")
+
+
+def test_ai_pipeline_auto_version_first_run_is_v001(tmp_path: Path) -> None:
+    from k_ai_pipeline import build_pipeline_outputs
+
+    out = build_pipeline_outputs(
+        81, 1, "", str(tmp_path), ".png", "bearMask", "", "auto",
+        False, False, True,
+        create_directory=False, check_overwrite=False,
+    )
+    assert out[2] == "v001"
+
+

ComfyUI/custom_nodes/koolook/tests/nodes/test_publish_contract.py

@@ -0,0 +1,93 @@
+"""Koolook publish contract nodes."""
+
+from __future__ import annotations
+
+from k_publish_contract import (
+    Koolook_PublishInput,
+    Koolook_PublishOutput,
+    Koolook_PublishResult,
+    Koolook_PublishRouter,
+    NODE_CLASS_MAPPINGS,
+    NODE_DISPLAY_NAME_MAPPINGS,
+)
+
+
+def test_publish_contract_nodes_register() -> None:
+    assert NODE_CLASS_MAPPINGS["Koolook_PublishInput"] is Koolook_PublishInput
+    assert NODE_CLASS_MAPPINGS["Koolook_PublishOutput"] is Koolook_PublishOutput
+    assert NODE_CLASS_MAPPINGS["Koolook_PublishResult"] is Koolook_PublishResult
+    assert NODE_CLASS_MAPPINGS["Koolook_PublishRouter"] is Koolook_PublishRouter
+    assert NODE_DISPLAY_NAME_MAPPINGS["Koolook_PublishInput"] == "Koolook Publish Input"
+    assert NODE_DISPLAY_NAME_MAPPINGS["Koolook_PublishOutput"] == "Koolook Publish Output"
+    assert NODE_DISPLAY_NAME_MAPPINGS["Koolook_PublishResult"] == "Koolook Publish Result"
+    assert NODE_DISPLAY_NAME_MAPPINGS["Koolook_PublishRouter"] == "Koolook Publish Router"
+
+
+def test_publish_input_exposes_stable_fields_and_switch_output() -> None:
+    spec = Koolook_PublishInput.INPUT_TYPES()["required"]
+
+    assert list(spec) == ["mode", "sequence_folder", "qt_file", "single_file", "prompt"]
+    assert spec["mode"][0] == ["EXR", "QT", "Img", "Prompt"]
+    assert Koolook_PublishInput.RETURN_NAMES == (
+        "sequence_folder",
+        "qt_file",
+        "single_file",
+        "prompt",
+        "switch",
+    )
+
+    result = Koolook_PublishInput().run(
+        mode="Img",
+        sequence_folder="/seq",
+        qt_file="/movie.mov",
+        single_file="/image.png",
+        prompt="hidden",
+    )
+
+    assert result == ("/seq", "/movie.mov", "/image.png", "hidden", 2)
+
+
+def test_publish_input_accepts_published_numeric_switch_values() -> None:
+    node = Koolook_PublishInput()
+
+    assert node.run(0, "/seq", "/movie.mov", "/image.png", "hidden")[-1] == 0
+    assert node.run("1", "/seq", "/movie.mov", "/image.png", "hidden")[-1] == 1
+    assert node.run(2, "/seq", "/movie.mov", "/image.png", "hidden")[-1] == 2
+    assert node.run("3", "/seq", "/movie.mov", "/image.png", "hidden")[-1] == 3
+
+
+def test_publish_output_exposes_stable_fields() -> None:
+    spec = Koolook_PublishOutput.INPUT_TYPES()["required"]
+
+    assert list(spec) == ["folder", "name", "version"]
+    assert Koolook_PublishOutput.RETURN_NAMES == ("folder", "name", "version")
+    assert Koolook_PublishOutput().run(
+        folder="/out",
+        name="mask",
+        version="1",
+    ) == ("/out", "mask", "1")
+
+
+def test_publish_result_exposes_resolved_result() -> None:
+    spec = Koolook_PublishResult.INPUT_TYPES()["required"]
+
+    assert list(spec) == ["result"]
+    assert Koolook_PublishResult.RETURN_NAMES == ("result",)
+    assert Koolook_PublishResult.OUTPUT_NODE is True
+    assert Koolook_PublishResult().run(result="/out/mask_v001.png") == {
+        "ui": {"text": ["/out/mask_v001.png"]},
+        "result": ("/out/mask_v001.png",),
+    }
+
+
+def test_publish_router_exposes_switch_aligned_payload_outputs() -> None:
+    spec = Koolook_PublishRouter.INPUT_TYPES()["required"]
+
+    assert list(spec) == ["selector", "payload"]
+    assert Koolook_PublishRouter.RETURN_NAMES == ("EXR", "QT", "Img", "Prompt")
+    assert Koolook_PublishRouter().route(selector=2, payload="pixels") == (
+        "pixels",
+        "pixels",
+        "pixels",
+        "pixels",
+    )

ComfyUI/custom_nodes/koolook/tests/scripts/test_bootstrap_constraints.py

@@ -0,0 +1,108 @@
+"""Guards on the locked test dependency set (``constraints-test.txt``).
+
+The bootstrap scripts install the test extras against this pinned lock, so
+every fresh ``.venv`` is reproducible and ``pip-audit``-verifiable. These
+tests fail loudly if the lock drifts out of sync with the ``[test]`` extras
+declared in ``pyproject.toml`` (e.g. an extra was added without re-locking).
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - Python < 3.11 fallback
+    import tomli as tomllib
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CONSTRAINTS = REPO_ROOT / "constraints-test.txt"
+PYPROJECT = REPO_ROOT / "pyproject.toml"
+
+
+def _canonical(name: str) -> str:
+    """PEP 503 normalised distribution name."""
+    return re.sub(r"[-_.]+", "-", name).strip().lower()
+
+
+def _pinned_names() -> dict[str, str]:
+    """Map canonical distribution name -> exact version from the lock."""
+    pins: dict[str, str] = {}
+    for raw in CONSTRAINTS.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        assert "==" in line, f"constraint not pinned with '==': {line!r}"
+        name, version = line.split("==", 1)
+        pins[_canonical(name)] = version.strip()
+    return pins
+
+
+def _test_extra_names() -> list[str]:
+    data = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    extras = data["project"]["optional-dependencies"]["test"]
+    return [_canonical(re.split(r"[<>=!~;\[ ]", spec, maxsplit=1)[0]) for spec in extras]
+
+
+def test_constraints_file_exists_and_nonempty():
+    assert CONSTRAINTS.is_file(), "constraints-test.txt is missing"
+    assert _pinned_names(), "constraints-test.txt has no pinned entries"
+
+
+def test_no_editable_or_self_package_leaked():
+    text = CONSTRAINTS.read_text(encoding="utf-8")
+    assert "-e " not in text, "an editable install leaked into the lock"
+    assert "koolook" not in _pinned_names(), "the self package leaked into the lock"
+
+
+def test_every_top_level_test_extra_is_pinned():
+    pins = _pinned_names()
+    missing = [name for name in _test_extra_names() if name not in pins]
+    assert not missing, (
+        f"these [test] extras are not pinned in constraints-test.txt: {missing}. "
+        "Regenerate the lock: bash scripts/bootstrap_test_env.sh --force --relock"
+    )
+
+
+def test_no_duplicate_pins():
+    names: list[str] = []
+    for raw in CONSTRAINTS.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if line and not line.startswith("#"):
+            names.append(_canonical(line.split("==", 1)[0]))
+    dupes = sorted({name for name in names if names.count(name) > 1})
+    assert not dupes, f"duplicate pins in constraints-test.txt: {dupes}"
+
+
+def test_bootstrap_upgrades_setuptools_before_audit():
+    """Fresh venvs should not fail audit on the ensurepip setuptools seed."""
+    ps1 = (REPO_ROOT / "scripts" / "bootstrap_test_env.ps1").read_text(encoding="utf-8")
+    sh = (REPO_ROOT / "scripts" / "bootstrap_test_env.sh").read_text(encoding="utf-8")
+
+    assert "--upgrade pip setuptools" in ps1
+    assert "--upgrade pip setuptools" in sh
+
+
+def test_bootstrap_relock_does_not_inspect_editable_git_metadata():
+    """Relock should work from cross-drive git worktrees on Windows."""
+    ps1 = (REPO_ROOT / "scripts" / "bootstrap_test_env.ps1").read_text(encoding="utf-8")
+    sh = (REPO_ROOT / "scripts" / "bootstrap_test_env.sh").read_text(encoding="utf-8")
+
+    assert "pip list --format=freeze" in ps1
+    assert "pip list --format=freeze" in sh
+    assert "pip freeze --exclude-editable" not in ps1
+    assert "pip freeze --exclude-editable" not in sh
+
+
+def test_ci_audits_committed_lock_on_prs_and_schedule():
+    ci = (REPO_ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+
+    assert "schedule:" in ci
+    assert "pip-audit -r constraints-test.txt" in ci
+
+
+def test_ci_pytest_installs_from_committed_lock():
+    ci = (REPO_ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+
+    assert '-e ".[test]" -c constraints-test.txt' in ci

ComfyUI/custom_nodes/koolook/tests/scripts/test_loop_audio.py

@@ -0,0 +1,1069 @@
+"""Pure-function coverage for scripts/loop_audio.py.
+
+Anchored by the PR #185 multi-agent review which surfaced three
+silent-failure HIGHs on the audio-source-derivation path:
+
+  * derive_audio_state collapsed missing-Director and unwired-VAE
+    into the same label;
+  * extract_multilines used dict-insertion order, so a shorter needle
+    declared first could silently shadow a longer match;
+  * parse_timeline returned segments verbatim, so a string-valued
+    `start` field would crash the renderer at `start / fps` or quietly
+    break `<` comparisons in video_segment_has_audio.
+
+These tests pin each fix plus the surrounding helpers so future edits
+can't silently regress.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+# Load the script directly — it lives under scripts/, not under a package.
+_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "loop_audio.py"
+sys.path.insert(0, str(_SCRIPT.parent))
+_spec = importlib.util.spec_from_file_location("loop_audio", _SCRIPT)
+assert _spec is not None and _spec.loader is not None
+loop_audio = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(loop_audio)
+
+
+# --- helpers used by multiple tests -----------------------------------------
+
+
+def _director(
+    *,
+    node_type: str = "LTXDirector__koolook",
+    use_custom_audio: bool = False,
+    audio_vae_link: int | None = None,
+    timeline: dict | None = None,
+    epsilon: float = 0.001,
+    fps: int = 24,
+) -> dict:
+    """Build a minimal Koolook Director node dict matching the saved
+    widget order (DIRECTOR_WIDX). Only fields the helpers under test
+    actually read are populated; the rest are placeholders."""
+    import json as _json
+    timeline_str = _json.dumps(timeline) if timeline is not None else ""
+    wv = [
+        "",                # 0  global_prompt
+        120,               # 1  duration_frames
+        5,                 # 2  duration_seconds
+        timeline_str,      # 3  timeline_data
+        "",                # 4  local_prompts
+        "120",             # 5  segment_lengths
+        epsilon,           # 6  epsilon
+        "1.00",            # 7  guide_strength
+        use_custom_audio,  # 8  use_custom_audio
+        fps,               # 9  frame_rate
+        "seconds",         # 10 display_mode
+        0,                 # 11 custom_width
+        0,                 # 12 custom_height
+        "maintain aspect ratio",  # 13 resize_method
+        32,                # 14 divisible_by
+        18,                # 15 img_compression
+        "",                # 16 relay_overrides
+    ]
+    return {
+        "type": node_type,
+        "widgets_values": wv,
+        "inputs": [
+            {"name": "audio_vae", "link": audio_vae_link},
+            {"name": "use_custom_audio", "link": None},
+        ],
+    }
+
+
+# --- extract_director — stable, legacy, and upstream IDs --------------------
+
+
+@pytest.mark.parametrize(
+    "node_type",
+    ["LTXDirector__koolook", "LTXDirector__koolook_v1_3_2", "LTXDirector"],
+)
+def test_extract_director_accepts_supported_director_ids(node_type):
+    node = _director(node_type=node_type)
+    assert loop_audio.extract_director([node]) is node
+
+
+def test_extract_director_prefers_koolook_over_upstream():
+    upstream = _director(node_type="LTXDirector")
+    koolook = _director(node_type="LTXDirector__koolook")
+    assert loop_audio.extract_director([upstream, koolook]) is koolook
+
+
+def test_extract_director_prefers_guide_wired_upstream_over_idle_koolook():
+    upstream = {"id": 10, **_director(node_type="LTXDirector")}
+    upstream["outputs"] = [{"name": "guide_data", "links": [100]}]
+    koolook = {"id": 20, **_director(node_type="LTXDirector__koolook")}
+    koolook["outputs"] = [{"name": "guide_data", "links": []}]
+    reroute = {
+        "id": 30,
+        "type": "Reroute",
+        "inputs": [{"name": "", "link": 100}],
+        "outputs": [{"name": "", "links": [101]}],
+    }
+    guide = {
+        "id": 40,
+        "type": "LTXDirectorGuide",
+        "inputs": [{"name": "guide_data", "link": 101}],
+    }
+
+    assert (
+        loop_audio.extract_director(
+            [koolook, upstream, reroute, guide],
+            [
+                [100, 10, 4, 30, 0, "GUIDE_DATA"],
+                [101, 30, 0, 40, 4, "GUIDE_DATA"],
+            ],
+        )
+        is upstream
+    )
+
+
+def test_director_widget_uses_saved_director_widget_order():
+    node = {
+        "type": "LTXDirector__koolook",
+        "inputs": [
+            {"name": "duration_frames", "widget": {"name": "duration_frames"}},
+            {"name": "epsilon", "widget": {"name": "epsilon"}},
+            {"name": "use_custom_audio", "widget": {"name": "use_custom_audio"}},
+        ],
+        "widgets_values": [
+            "",
+            144,
+            6,
+            "",
+            "",
+            "",
+            0.004,
+            "1.00,1.00,1.00",
+            True,
+            24,
+        ],
+    }
+
+    assert loop_audio.director_widget(node, "epsilon") == 0.004
+    assert loop_audio.director_widget(node, "use_custom_audio") is True
+    assert loop_audio.director_widget(node, "frame_rate") == 24
+
+
+def test_director_widget_keeps_legacy_positional_fallback():
+    node = _director(epsilon=0.002)
+    assert loop_audio.director_widget(node, "epsilon") == 0.002
+
+
+def test_active_relay_overrides_reads_only_wired_director_input():
+    director = {
+        "id": 10,
+        **_director(),
+        "inputs": [
+            {"name": "audio_vae", "link": 99},
+            {"name": "relay_overrides", "link": 20},
+        ],
+    }
+    relay_note = _multiline("RELAY_OVERRIDES", '{"video_strength": 1.0}')
+    relay_note["id"] = 5
+    relay_note["outputs"] = [{"name": "STRING", "links": [20]}]
+
+    assert loop_audio.active_relay_overrides(
+        [director, relay_note],
+        [[20, 5, 0, 10, 16, "STRING"]],
+        director,
+    ) == '{"video_strength": 1.0}'
+
+
+def test_active_relay_overrides_ignores_unwired_note():
+    director = {
+        "id": 10,
+        **_director(),
+        "inputs": [
+            {"name": "audio_vae", "link": 99},
+            {"name": "relay_overrides", "link": None},
+        ],
+    }
+    relay_note = _multiline("RELAY_OVERRIDES", '{"video_strength": 1.0}')
+    relay_note["id"] = 5
+
+    assert loop_audio.active_relay_overrides(
+        [director, relay_note], [], director
+    ) == ""
+
+
+@pytest.mark.parametrize(
+    "node_type, expected",
+    [
+        ("LTXDirector__koolook", "Koolook"),
+        ("LTXDirector__koolook_v1_3_2", "Koolook"),
+        ("LTXDirector", "Original upstream"),
+    ],
+)
+def test_director_flavor_labels_supported_directors(node_type, expected):
+    assert loop_audio.director_flavor(_director(node_type=node_type)) == expected
+
+
+@pytest.mark.parametrize(
+    "node_type, upstream_version, expected",
+    [
+        ("LTXDirector__koolook", "", "v1.3.9"),
+        ("LTXDirector__koolook_v1_3_2", "", "v1.3.9"),
+        ("LTXDirector", "1.3.2", "v1.3.2"),
+        ("LTXDirector", "", "(unknown upstream pin)"),
+    ],
+)
+def test_director_pin_tag_labels_lock_version(node_type, upstream_version, expected):
+    assert (
+        loop_audio.director_pin_tag(
+            _director(node_type=node_type), upstream_version
+        )
+        == expected
+    )
+
+
+# --- derive_audio_state — 5 distinct states --------------------------------
+
+
+@pytest.mark.parametrize(
+    "director_node, timeline, expected",
+    [
+        # (no director) — split off so a missing-Director workflow can't
+        # silently look identical to a director-present-but-VAE-unwired
+        # one (PR #185 review HIGH-1).
+        (None, {"segments": [], "audioSegments": []}, "(no director)"),
+        # off (no VAE) — Director present, audio_vae socket unwired.
+        (
+            _director(audio_vae_link=None),
+            {"segments": [], "audioSegments": []},
+            "off (no VAE)",
+        ),
+        # model-gen — VAE wired, use_custom_audio=False. audioSegments
+        # are ignored on this path.
+        (
+            _director(audio_vae_link=42, use_custom_audio=False),
+            {"segments": [], "audioSegments": []},
+            "model-gen",
+        ),
+        # custom — VAE wired, use_custom_audio=True, audioSegments
+        # non-empty.
+        (
+            _director(audio_vae_link=42, use_custom_audio=True),
+            {"segments": [], "audioSegments": [{"start": 0, "length": 100}]},
+            "custom",
+        ),
+        # custom (empty) — VAE wired, use_custom_audio=True, but no
+        # audioSegments uploaded.
+        (
+            _director(audio_vae_link=42, use_custom_audio=True),
+            {"segments": [], "audioSegments": []},
+            "custom (empty)",
+        ),
+    ],
+)
+def test_derive_audio_state_all_five_states(director_node, timeline, expected):
+    assert loop_audio.derive_audio_state(director_node, timeline) == expected
+
+
+# --- extract_multilines — longest-needle-wins guards future drift ----------
+
+
+def _multiline(title: str, body: str) -> dict:
+    return {
+        "type": "Text Multiline",
+        "title": title,
+        "widgets_values": [body],
+    }
+
+
+def test_extract_multilines_keeps_all_hits_for_one_needle():
+    """Working_Folder_PATH legitimately appears twice on the canvas
+    (project mount + local mirror). Both bodies must come back so the
+    caller can pick by reachability."""
+    nodes = [
+        _multiline("Working_Folder_PATH", "W:/projects/foo"),
+        _multiline("Working_Folder_PATH", "e:/local/foo"),
+    ]
+    out = loop_audio.extract_multilines(nodes, ["working_folder"])
+    assert out["working_folder"] == ["W:/projects/foo", "e:/local/foo"]
+
+
+def test_extract_multilines_longest_needle_wins():
+    """If a future config adds a short substring that's contained in
+    an existing longer one, the longer match should win — regardless
+    of declaration order. The pre-fix loop iterated in dict-insertion
+    order and would have routed both nodes to the shorter needle."""
+    nodes = [
+        _multiline("RELAY_OVERRIDES", "{video_strength: 10}"),
+    ]
+    # Shorter "relay" declared FIRST in the config — pre-fix this would
+    # have shadowed "relay_overrides". Longest-first ordering routes
+    # the node to the more specific needle.
+    out = loop_audio.extract_multilines(
+        nodes, ["relay", "relay_overrides"]
+    )
+    assert out["relay_overrides"] == ["{video_strength: 10}"]
+    assert out["relay"] == []
+
+
+def test_extract_multilines_first_match_wins_per_node():
+    """A node's title can match multiple needles. The loop should
+    record at most one match per node (the longest) to avoid
+    double-counting."""
+    nodes = [_multiline("NAME overlay - info combined", "one node")]
+    out = loop_audio.extract_multilines(
+        nodes, ["name", "overlay - info"]
+    )
+    # Both needles match the title, but the longer one wins and the
+    # per-node break keeps the same node from being counted twice.
+    assert out["name"] == []
+    assert out["overlay - info"] == ["one node"]
+
+
+def test_extract_multilines_accepts_prioritized_alias_map():
+    nodes = [
+        _multiline("NAME", "old setup name"),
+        _multiline("GLOBAL [ base name ]", "new base name"),
+        _multiline("GLOBAL [ path ] - working folder", "E:/runs"),
+    ]
+    out = loop_audio.extract_multilines(
+        nodes,
+        {
+            "name": ["global [ base name ]", "name"],
+            "working_folder": [
+                "global [ path ] - working folder",
+                "working_folder",
+            ],
+        },
+    )
+    assert out["name"] == ["new base name", "old setup name"]
+    assert out["working_folder"] == ["E:/runs"]
+
+
+def test_extract_setup_variables_reads_text_and_primitive_source_nodes():
+    nodes = [
+        _multiline("INPUT Path [ EXR ]", "W:/plates"),
+        {
+            "type": "PrimitiveInt",
+            "title": "GLOBAL [ version ]",
+            "widgets_values": [1, "fixed"],
+        },
+        {
+            "type": "PrimitiveInt",
+            "title": "GLOBAL [ run offset ]",
+            "widgets_values": [7, "fixed"],
+        },
+        {
+            "type": "GetNode",
+            "title": "Get_GLOBAL [ version ]",
+            "widgets_values": ["GLOBAL [ version ]"],
+        },
+        {
+            "type": "SetNode",
+            "title": "Set_GLOBAL [ run ]",
+            "widgets_values": ["GLOBAL [ run ]"],
+        },
+    ]
+    out = loop_audio.extract_setup_variables(
+        nodes,
+        {
+            "input_path_exr": ["input path [ exr ]"],
+            "version": ["global [ version ]"],
+            "run_offset": ["global [ run offset ]"],
+        },
+    )
+    assert out["input_path_exr"] == ["W:/plates"]
+    assert out["version"] == ["1"]
+    assert out["run_offset"] == ["7"]
+
+
+def test_expected_output_tracking_uses_current_setup_values():
+    nodes = [
+        {
+            "type": "Easy_VideoCombine",
+            "widgets_values": {
+                "format": "video/koolook-ASTRA-h264",
+            },
+        },
+        {
+            "type": "easy showAnything",
+            "widgets_values": [
+                '[true, ["E:/old/Previous_h264_v001.mp4"]]',
+            ],
+        },
+    ]
+    out = loop_audio.expected_output_tracking(
+        nodes,
+        {
+            "working_folder": ["E:/current/renders"],
+            "name": ["Bear_2x-FR_AudioFile-K_Dir"],
+        },
+        {"version": ["2"]},
+    )
+    assert out["folder"] == "E:/current/renders"
+    assert out["name"] == "Bear_2x-FR_AudioFile-K_Dir_h264_v002"
+
+
+def test_output_suffix_uses_named_widget_before_positional_fallback():
+    nodes = [
+        {
+            "type": "Easy_VideoCombine",
+            "inputs": [
+                {"name": "frame_rate", "widget": {"name": "frame_rate"}},
+                {"name": "format", "widget": {"name": "format"}},
+                {"name": "version", "widget": {"name": "version"}},
+            ],
+            "widgets_values": [24, "video/ProRes", "999"],
+        },
+    ]
+    assert loop_audio.output_suffix_from_workflow(nodes) == "ProRes"
+
+
+def test_output_suffix_keeps_legacy_positional_fallback():
+    nodes = [
+        {
+            "type": "Easy_VideoCombine",
+            "widgets_values": [24, 0, "upscaled", "video/koolook-ASTRA-h264"],
+        },
+    ]
+    assert loop_audio.output_suffix_from_workflow(nodes) == "h264"
+
+
+def test_delivery_card_path_uses_output_folder_and_name():
+    out = loop_audio.delivery_card_path({
+        "folder": "E:/current/renders",
+        "name": "Bear_h264_v002",
+    })
+    assert out == Path("E:/current/renders") / "cards" / "Bear_h264_v002_card.png"
+
+
+def test_delivery_card_path_can_include_run_number():
+    out = loop_audio.delivery_card_path(
+        {
+            "folder": "E:/current/renders",
+            "name": "Bear_h264_v002",
+        },
+        7,
+    )
+    assert out == (
+        Path("E:/current/renders")
+        / "cards"
+        / "Bear_h264_v002_run007_card.png"
+    )
+
+
+def test_delivery_card_path_skips_when_output_is_unknown():
+    assert loop_audio.delivery_card_path({"folder": "E:/renders"}) is None
+
+
+def test_copy_delivery_card_reports_failure_without_raising(monkeypatch, tmp_path: Path):
+    def fail_copy(_src, _dst):
+        raise OSError("drive unavailable")
+
+    monkeypatch.setattr(loop_audio.shutil, "copy2", fail_copy)
+
+    status = loop_audio.copy_delivery_card(
+        tmp_path / "card.png",
+        {"folder": str(tmp_path), "name": "Bear_h264_v002"},
+    )
+
+    assert status == "failed (drive unavailable)"
+
+
+def test_copy_delivery_card_creates_missing_cards_folder(tmp_path: Path):
+    card = tmp_path / "source.png"
+    folder = tmp_path / "renders"
+    card.write_text("new", encoding="utf-8")
+
+    status = loop_audio.copy_delivery_card(
+        card,
+        {"folder": str(folder), "name": "Bear_h264_v002"},
+        7,
+    )
+
+    expected = folder / "cards" / "Bear_h264_v002_run007_card.png"
+    assert status == str(expected)
+    assert expected.read_text(encoding="utf-8") == "new"
+
+
+def test_copy_delivery_card_leaves_existing_file_in_place(tmp_path: Path):
+    card = tmp_path / "source.png"
+    folder = tmp_path / "renders"
+    existing = folder / "cards" / "Bear_h264_v002_card.png"
+    card.write_text("new", encoding="utf-8")
+    existing.parent.mkdir(parents=True)
+    existing.write_text("old", encoding="utf-8")
+
+    status = loop_audio.copy_delivery_card(
+        card,
+        {"folder": str(folder), "name": "Bear_h264_v002"},
+    )
+
+    assert status.startswith("exists (left in place:")
+    assert existing.read_text(encoding="utf-8") == "old"
+
+
+def test_copy_delivery_card_can_overwrite_existing_file(tmp_path: Path):
+    card = tmp_path / "source.png"
+    folder = tmp_path / "renders"
+    existing = folder / "cards" / "Bear_h264_v002_run007_card.png"
+    card.write_text("new", encoding="utf-8")
+    existing.parent.mkdir(parents=True)
+    existing.write_text("old", encoding="utf-8")
+
+    status = loop_audio.copy_delivery_card(
+        card,
+        {"folder": str(folder), "name": "Bear_h264_v002"},
+        7,
+        overwrite=True,
+    )
+
+    assert status == str(existing)
+    assert existing.read_text(encoding="utf-8") == "new"
+
+
+def test_card_metadata_scrubs_path_bearing_fields():
+    metadata = loop_audio.card_metadata(
+        4,
+        "label",
+        Path("run004_workflow.json"),
+        {"name": ["Bear"], "relay_overrides": ["{}"]},
+        {"input_path_exr": ["W:/projects/client_codename/shot/v003"]},
+        {
+            "folder": "E:/Jobs/Client/Comfy/Runs",
+            "name": "Bear_h264_v002",
+            "version_tag": "v002",
+            "format_suffix": "h264",
+        },
+        _director(),
+        {"segments": [], "audioSegments": []},
+        "custom",
+        {},
+        "clean",
+        "1.3.2",
+    )
+
+    encoded = json.dumps(metadata)
+    assert "W:/projects" not in encoded
+    assert "client_codename" not in encoded
+    assert "E:/Jobs" not in encoded
+    assert "path-sha256:" in encoded
+
+
+def test_card_metadata_does_not_store_boolean_frame_rate():
+    metadata = loop_audio.card_metadata(
+        4,
+        "label",
+        Path("run004_workflow.json"),
+        {"name": ["Bear"], "relay_overrides": ["{}"]},
+        {},
+        {"folder": "", "name": ""},
+        _director(fps=True),
+        {"segments": [], "audioSegments": []},
+        "model-gen",
+        {},
+        "clean",
+        "1.3.2",
+    )
+
+    assert metadata["director"]["frame_rate"] is None
+
+
+def test_sanitize_workflow_for_archive_redacts_absolute_paths():
+    workflow = {
+        "nodes": [
+            {
+                "widgets_values": [
+                    "E:/Jobs/Client/Comfy/Runs",
+                    "notes\nW:/projects/client_codename/shot/v003\nok",
+                    '["e:\\\\G-Drive-BaconX\\\\Jobs\\\\Jeep_Animals\\\\render.json"]',
+                    "<PROJECTS>/samsung_goat/vfx/assets",
+                    "W:/projects/client_codename/shot/v003",
+                    "relative/path/is-kept",
+                    "https://example.com/kept",
+                ]
+            }
+        ]
+    }
+
+    sanitized = loop_audio.sanitize_workflow_for_archive(workflow)
+    encoded = json.dumps(sanitized)
+
+    assert "E:/Jobs" not in encoded
+    assert "W:/projects" not in encoded
+    assert "client_codename" not in encoded
+    assert "samsung_goat" not in encoded
+    assert "relative/path/is-kept" in encoded
+    assert "https://example.com/kept" in encoded
+    assert "path-sha256:" in encoded
+
+
+def test_render_notes_scrubs_paths_and_rejects_boolean_fps():
+    notes = loop_audio.render_notes_md(
+        5,
+        Path("LTX-23-audio_tests_03.json"),
+        {
+            "name": ["Bear"],
+            "relay_overrides": [""],
+            "overlay - info": [""],
+            "overlay - feedback": [""],
+            "working_folder": ["E:/Jobs/Client/Comfy/Runs"],
+        },
+        {
+            "input_path_exr": ["W:/projects/client_codename/shot/v003"],
+            "version": ["1"],
+            "run_offset": ["0"],
+        },
+        _director(fps=True),
+        {"segments": [], "audioSegments": []},
+        "custom",
+        "",
+        [],
+        {"motion": None, "sync": None, "sharp": None},
+        {"folder": "E:/Jobs/Client/Comfy/Runs", "name": "Bear_h264_v001"},
+    )
+
+    assert "E:/Jobs" not in notes
+    assert "W:/projects" not in notes
+    assert "client_codename" not in notes
+    assert "path-sha256:" in notes
+    assert "True fps" not in notes
+    assert "(unknown fps)" in notes
+
+
+def test_audio_card_embeds_metadata_payload(tmp_path: Path):
+    from PIL import Image
+
+    from make_card_audio import render_audio_card
+
+    metadata = {
+        "schema": "koolook.audio_loop.card_metadata.v1",
+        "repo": {"main_sha": "abc1234"},
+        "output": {"name": "Bear_h264_v002"},
+    }
+    out = tmp_path / "card.png"
+    render_audio_card(
+        {
+            "run_number": 3,
+            "date": "2026-05-30",
+            "workflow_name": "workflow.json",
+            "name": "Bear",
+            "relay_overrides_raw": "{}",
+            "info_body": "",
+            "feedback_lines": [],
+            "scores": {},
+            "work_folder": "E:/renders",
+            "output_folder": "E:/renders",
+            "output_name": "Bear_h264_v002",
+            "director_flavor": "Koolook v1.3.9",
+            "audio_src": "custom",
+            "epsilon": 0.001,
+            "frame_rate": 24,
+            "segments": [],
+            "audio_segments": [],
+            "segment_prompt_mode": "none",
+            "metadata": metadata,
+        },
+        out,
+    )
+    embedded = json.loads(Image.open(out).info["koolook_audio_loop"])
+    assert embedded == metadata
+
+
+def test_rebuild_state_handles_non_numeric_run_dir_and_bom_workflow(tmp_path: Path):
+    from make_card_audio import _rebuild_state_from_run_dir
+
+    run_dir = tmp_path / "run-foo_label"
+    run_dir.mkdir()
+    (run_dir / "workflow.json").write_text(
+        json.dumps({"nodes": []}),
+        encoding="utf-8-sig",
+    )
+
+    state = _rebuild_state_from_run_dir(run_dir)
+
+    assert state["run_number"] == 0
+    assert state["run_label"] == "label"
+
+
+def test_rebuild_state_preserves_date_and_splits_repo_sync_metadata(tmp_path: Path):
+    from make_card_audio import _rebuild_state_from_run_dir
+
+    run_dir = tmp_path / "run-005_label"
+    run_dir.mkdir()
+    (run_dir / "run005_workflow.json").write_text(
+        json.dumps({"nodes": [], "links": []}),
+        encoding="utf-8",
+    )
+    (run_dir / "metadata.json").write_text(
+        json.dumps({"run": {"date": "2026-05-01"}}),
+        encoding="utf-8",
+    )
+    (run_dir / "patch_state.txt").write_text(
+        "\n".join(
+            [
+                "MAIN SHA              : abc1234",
+                "Last dev-sync-audio   : def5678  (2026-05-02 11:22)",
+                "Sync scope tag        : relay parser",
+                "Sync worktree         : ComfyUI-Koolook",
+                "Fork dir status       : clean",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    state = _rebuild_state_from_run_dir(run_dir)
+    metadata = state["metadata"]
+
+    assert state["date"] == "2026-05-01"
+    assert metadata["run"]["date"] == "2026-05-01"
+    assert metadata["repo"]["last_dev_sync_audio"] == "def5678"
+    assert metadata["repo"]["last_dev_sync_at"] == "2026-05-02 11:22"
+
+
+def test_extract_multilines_ignores_non_text_multiline_nodes():
+    nodes = [
+        {"type": "LTXDirector__koolook_v1_3_2", "title": "NAME"},
+        _multiline("NAME", "real"),
+    ]
+    out = loop_audio.extract_multilines(nodes, ["name"])
+    assert out["name"] == ["real"]
+
+
+# --- parse_timeline — coerce numeric segment fields ------------------------
+
+
+def test_parse_timeline_coerces_string_numerics():
+    """The Comfy frontend sometimes saves numeric segment fields as
+    strings. parse_timeline must coerce them so downstream arithmetic
+    in the renderer (`start / fps`, `<` comparisons) stays type-safe
+    instead of crashing or doing lexical comparisons."""
+    node = _director(timeline={
+        "segments": [
+            {"id": "a", "start": "0", "length": "120", "prompt": "x"},
+        ],
+        "audioSegments": [],
+    })
+    tl = loop_audio.parse_timeline(node)
+    seg = tl["segments"][0]
+    assert seg["start"] == 0
+    assert seg["length"] == 120
+    assert isinstance(seg["start"], int)
+    assert isinstance(seg["length"], int)
+    # Non-numeric fields pass through.
+    assert seg["prompt"] == "x"
+
+
+def test_parse_timeline_coerces_float_to_int():
+    node = _director(timeline={
+        "segments": [{"start": 1.7, "length": 12.4}],
+        "audioSegments": [],
+    })
+    tl = loop_audio.parse_timeline(node)
+    # int(float(...)) truncates toward 0, matching the upstream
+    # Director's _build_combined_audio coercion behavior.
+    assert tl["segments"][0]["start"] == 1
+    assert tl["segments"][0]["length"] == 12
+
+
+def test_parse_timeline_collapses_bad_values_to_zero():
+    """A malformed segment shouldn't crash the whole loop — the
+    offending field collapses to 0 and we keep going."""
+    node = _director(timeline={
+        "segments": [{"start": "not a number", "length": 100}],
+        "audioSegments": [],
+    })
+    tl = loop_audio.parse_timeline(node)
+    assert tl["segments"][0]["start"] == 0
+    assert tl["segments"][0]["length"] == 100
+
+
+def test_parse_timeline_handles_malformed_json():
+    """Invalid JSON in timeline_data must not raise — the helper
+    returns empty lists so the renderer falls back to "(N=0)" and
+    proceeds."""
+    bad = _director()
+    bad["widgets_values"][3] = "{not json"
+    assert loop_audio.parse_timeline(bad) == {
+        "segments": [], "audioSegments": [],
+    }
+
+
+def test_parse_timeline_handles_missing_director():
+    assert loop_audio.parse_timeline(None) == {
+        "segments": [], "audioSegments": [],
+    }
+
+
+def test_parse_timeline_drops_non_dict_segments():
+    node = _director(timeline={
+        "segments": [
+            {"start": 0, "length": 60},  # kept
+            "not a dict",                 # dropped
+            None,                         # dropped
+        ],
+        "audioSegments": [],
+    })
+    tl = loop_audio.parse_timeline(node)
+    assert len(tl["segments"]) == 1
+
+
+# --- video_segment_has_audio — overlap boundaries --------------------------
+
+
+@pytest.mark.parametrize(
+    "video, audio_segs, expected",
+    [
+        # Same range — overlaps.
+        ({"start": 0, "length": 100}, [{"start": 0, "length": 100}], True),
+        # Audio starts inside video — overlaps.
+        ({"start": 0, "length": 100}, [{"start": 50, "length": 50}], True),
+        # Audio ends inside video — overlaps.
+        ({"start": 50, "length": 100}, [{"start": 0, "length": 75}], True),
+        # Audio strictly before video — no overlap.
+        ({"start": 100, "length": 50}, [{"start": 0, "length": 100}], False),
+        # Audio strictly after video — no overlap.
+        ({"start": 0, "length": 50}, [{"start": 100, "length": 50}], False),
+        # Audio exactly touches video end — half-open intervals
+        # (a_start < v_end) treats this as NOT overlapping.
+        ({"start": 0, "length": 50}, [{"start": 50, "length": 50}], False),
+        # Multiple audio segs — any one overlap is enough.
+        (
+            {"start": 0, "length": 50},
+            [{"start": 100, "length": 10}, {"start": 25, "length": 10}],
+            True,
+        ),
+        # No audio segs — false.
+        ({"start": 0, "length": 50}, [], False),
+    ],
+)
+def test_video_segment_has_audio_boundaries(video, audio_segs, expected):
+    assert loop_audio.video_segment_has_audio(video, audio_segs) is expected
+
+
+# --- segment_prompt_mode — same vs per-segment prompt check -----------------
+
+
+@pytest.mark.parametrize(
+    "segments, expected",
+    [
+        ([], "none"),
+        ([{"prompt": "one prompt"}], "single"),
+        (
+            [{"prompt": "same prompt"}, {"prompt": "same   prompt"}],
+            "same",
+        ),
+        (
+            [{"prompt": "wide shot"}, {"prompt": "close up"}],
+            "per-segment",
+        ),
+        (
+            [{"prompt": "wide shot"}, {"prompt": ""}],
+            "missing",
+        ),
+    ],
+)
+def test_segment_prompt_mode_classifies_prompt_sequence(segments, expected):
+    assert loop_audio.segment_prompt_mode(segments) == expected
+
+
+# --- parse_feedback — score 0 must round-trip (PR #185 review MEDIUM-9) ----
+
+
+def test_parse_feedback_extracts_scores_with_lines():
+    body = (
+        "Looking solid overall\n"
+        "Sync drifts in the last second\n"
+        "motion: 4/5\n"
+        "sync: 3/5\n"
+        "sharpness: 5/5\n"
+    )
+    scores, lines = loop_audio.parse_feedback(body)
+    assert scores == {"motion": 4, "sync": 3, "sharp": 5}
+    assert lines == ["Looking solid overall", "Sync drifts in the last second"]
+
+
+def test_parse_feedback_preserves_zero_as_score():
+    """0 is a legitimate score. Pre-fix the log row coerced it to '?'
+    via `or '?'`; parse_feedback itself stores 0 correctly — this test
+    pins that contract so a future refactor can't subtly inject `or 0`
+    semantics."""
+    scores, _ = loop_audio.parse_feedback("motion: 0/5\nsync: 0\nsharp: 0\n")
+    assert scores == {"motion": 0, "sync": 0, "sharp": 0}
+
+
+def test_render_log_row_preserves_zero_scores():
+    row = loop_audio.render_log_row(
+        3,
+        _director(),
+        "",
+        "model-gen",
+        {"segments": [], "audioSegments": []},
+        {"motion": 0, "sync": 0, "sharp": 0},
+        [],
+    )
+    assert "M0·S0·Sh0" in row
+
+
+def test_render_log_row_records_video_and_audio_segment_counts():
+    row = loop_audio.render_log_row(
+        3,
+        _director(),
+        "",
+        "custom",
+        {"segments": [{}, {}], "audioSegments": [{}, {}]},
+        {"motion": None, "sync": None, "sharp": None},
+        [],
+    )
+    assert "| custom | 2v/2a |" in row
+
+
+def test_parse_feedback_accepts_sharpness_alias():
+    """Both 'sharp' and 'sharpness' are accepted axis names. Both map
+    to the 'sharp' key."""
+    scores, _ = loop_audio.parse_feedback("sharpness: 4\n")
+    assert scores["sharp"] == 4
+
+
+def test_parse_feedback_case_insensitive():
+    scores, _ = loop_audio.parse_feedback("MOTION: 3\nSync 4\n")
+    assert scores["motion"] == 3
+    assert scores["sync"] == 4
+
+
+def test_parse_feedback_empty_body_returns_blank_scores():
+    scores, lines = loop_audio.parse_feedback("")
+    assert scores == {"motion": None, "sync": None, "sharp": None}
+    assert lines == []
+
+
+# --- is_input_wired — None vs False semantics matter for derive_audio_state ---
+
+
+def test_is_input_wired_none_when_director_missing():
+    assert loop_audio.is_input_wired(None, "audio_vae") is None
+
+
+def test_is_input_wired_true_when_link_set():
+    node = {"inputs": [{"name": "audio_vae", "link": 42}]}
+    assert loop_audio.is_input_wired(node, "audio_vae") is True
+
+
+def test_is_input_wired_false_when_link_null():
+    node = {"inputs": [{"name": "audio_vae", "link": None}]}
+    assert loop_audio.is_input_wired(node, "audio_vae") is False
+
+
+def test_is_input_wired_none_when_input_socket_absent():
+    """An older Director schema might not have the named socket at
+    all — same outcome as 'unwired' at runtime (no audio latent
+    produced), but a distinct value here so callers can tell."""
+    node = {"inputs": [{"name": "model", "link": 1}]}
+    assert loop_audio.is_input_wired(node, "audio_vae") is None
+
+
+# --- wrap_path — long mount paths shouldn't bleed past the card edge -------
+
+
+def test_wrap_path_breaks_on_separator():
+    out = loop_audio.wrap_path(
+        "e:/G-Drive-BaconX/Jobs/Jeep_Animals/ComfyUI_LTX23/Phase2",
+        max_chars=30,
+    )
+    # Joined with backslashes, never split mid-segment.
+    for line in out:
+        assert "/" not in line  # normalised to backslash separators
+    joined = "".join(out)
+    assert joined == "e:\\G-Drive-BaconX\\Jobs\\Jeep_Animals\\ComfyUI_LTX23\\Phase2"
+
+
+def test_wrap_path_returns_single_empty_string_for_empty_input():
+    assert loop_audio.wrap_path("") == [""]
+
+
+def test_wrap_path_handles_single_segment_longer_than_max():
+    """A directory name longer than max_chars still gets its own
+    line — we never split mid-name."""
+    out = loop_audio.wrap_path("verylongsingledirectoryname", max_chars=10)
+    assert len(out) == 1
+    assert out[0] == "verylongsingledirectoryname"
+
+
+# --- pick_existing_path — picks reachable path, falls back to first ------
+
+
+def test_pick_existing_path_prefers_real_directory(tmp_path):
+    real = tmp_path / "real"
+    real.mkdir()
+    out = loop_audio.pick_existing_path([
+        "Z:/never-exists",
+        str(real),
+        "Y:/also-never",
+    ])
+    assert out == str(real)
+
+
+def test_pick_existing_path_falls_back_to_first_nonempty():
+    out = loop_audio.pick_existing_path(["Z:/never-exists", "Y:/also-never"])
+    assert out == "Z:/never-exists"
+
+
+def test_pick_existing_path_returns_empty_when_all_empty():
+    assert loop_audio.pick_existing_path(["", "   ", "\""]) == ""
+
+
+# --- first_multiline + autogen_label sanity checks ------------------------
+
+
+def test_first_multiline_returns_first_or_empty():
+    assert loop_audio.first_multiline({"name": ["foo", "bar"]}, "name") == "foo"
+    assert loop_audio.first_multiline({}, "name") == ""
+    assert loop_audio.first_multiline({"name": []}, "name") == ""
+
+
+def test_autogen_label_when_director_missing():
+    label = loop_audio.autogen_label("Bear_3x", None, "")
+    assert "missing" in label
+    assert "audio-off" in label
+
+
+def test_autogen_label_when_director_present():
+    node = _director(use_custom_audio=True, audio_vae_link=42)
+    label = loop_audio.autogen_label(
+        "Bear_3x", node, '{"video_strength": 10.0}'
+    )
+    assert "koolook" in label
+    assert "audio-on" in label
+    assert "vstr10.0" in label
+
+
+def test_autogen_label_when_director_is_upstream():
+    label = loop_audio.autogen_label(
+        "Bear_3x", _director(node_type="LTXDirector"), ""
+    )
+    assert "upstream" in label
+    assert "audio-off" in label
+
+
+def test_relay_overrides_txt_marks_upstream_director_inert():
+    txt = loop_audio.render_relay_overrides_txt(
+        '{"video_strength": 10.0}',
+        _director(node_type="LTXDirector"),
+    )
+    assert "INERT" in txt
+    assert "LTXDirector" in txt
+
+
+def test_next_run_number_reads_folders_and_log(tmp_path):
+    runs = tmp_path / "runs"
+    runs.mkdir()
+    (runs / "run-001_alpha").mkdir()
+    (runs / "log.md").write_text(
+        "| Run | Date |\n"
+        "|---|---|\n"
+        "| 002 | 2026-05-29 |\n",
+        encoding="utf-8",
+    )
+    assert loop_audio.next_run_number(runs) == 3

ComfyUI/custom_nodes/koolook/tests/scripts/test_sync_to_dev.py

@@ -0,0 +1,100 @@
+"""Guards on which modules ``dev-sync`` ships, so the loader can never point
+at a file the install lacks.
+
+The #183 incident (root cause behind #198): a module that ``__init__.py``
+imported but ``scripts/sync_to_dev.py``'s ``RUNTIME_PATHS`` never copied raised
+``ImportError`` at startup. After the #198 refactor the blast radius of such a
+gap depends on *where* the import sits — a per-group node import degrades to
+"that node absent", but the context probe (``koolook_versioning``) and the
+install guard gate *all* registration. So the real invariant is: every module
+``__init__.py`` imports at load must be shipped by ``RUNTIME_PATHS``. This test
+derives those imports from ``__init__.py`` itself (rather than a ``k_*.py``
+glob, which misses the non-``k_`` gates) so it can't drift.
+"""
+from __future__ import annotations
+
+import ast
+import importlib.util
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+_SCRIPT = REPO_ROOT / "scripts" / "sync_to_dev.py"
+_spec = importlib.util.spec_from_file_location("koolook_sync_to_dev_under_test", _SCRIPT)
+assert _spec is not None and _spec.loader is not None
+sync_to_dev = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(sync_to_dev)
+
+
+def _init_load_time_module_deps() -> set[str]:
+    """Top-level package modules/packages ``__init__.py`` imports at load.
+
+    Covers relative ``from .X import ...`` / ``from . import X`` statements and
+    the ``_merge_node_group(label, ".X")`` node-group imports. Returns the
+    first path segment of each (e.g. ``forks.radiance_koolook`` -> ``forks``),
+    the granularity ``RUNTIME_PATHS`` ships at. Absolute imports (the install
+    guard's out-of-package fallback) are level 0 and intentionally ignored.
+    """
+    tree = ast.parse((REPO_ROOT / "__init__.py").read_text(encoding="utf-8"))
+    deps: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and (node.level or 0) >= 1:
+            if node.module:  # from .pkg import ...
+                deps.add(node.module.split(".")[0])
+            else:  # from . import a, b
+                deps.update(alias.name.split(".")[0] for alias in node.names)
+        elif (
+            isinstance(node, ast.Call)
+            and getattr(node.func, "id", None) == "_merge_node_group"
+        ):
+            for arg in node.args:
+                if (
+                    isinstance(arg, ast.Constant)
+                    and isinstance(arg.value, str)
+                    and arg.value.startswith(".")
+                ):
+                    deps.add(arg.value.lstrip(".").split(".")[0])
+    return deps
+
+
+def _route_load_time_module_deps() -> set[str]:
+    tree = ast.parse((REPO_ROOT / "koolook_routes.py").read_text(encoding="utf-8"))
+    deps: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if (node.level or 0) >= 1 and node.module:
+                deps.add(node.module.split(".")[0])
+            elif node.module and node.module.startswith("koolook_"):
+                deps.add(node.module.split(".")[0])
+    return deps
+
+
+def test_init_load_deps_are_shipped_by_runtime_paths():
+    runtime_paths = set(sync_to_dev.RUNTIME_PATHS)
+    deps = _init_load_time_module_deps() | _route_load_time_module_deps()
+    # Sanity: the parse actually found the imports (guards against a refactor
+    # that renames _merge_node_group and silently makes this test vacuous).
+    assert "koolook_versioning" in deps and "k_ai_pipeline" in deps, (
+        f"__init__.py import parse looks broken — only found: {sorted(deps)}"
+    )
+    # A single-file module ships as "<dep>.py"; a package (e.g. forks) ships as
+    # its top-level dir entry.
+    missing = sorted(
+        dep
+        for dep in deps
+        if f"{dep}.py" not in runtime_paths and dep not in runtime_paths
+    )
+    assert not missing, (
+        "__init__.py imports these at load but dev-sync RUNTIME_PATHS does not "
+        f"ship them: {missing}. Add them to RUNTIME_PATHS in "
+        "scripts/sync_to_dev.py so a plain dev-sync can't 404 the loader."
+    )
+
+
+def test_dev_sync_ships_manager_visible_package_metadata():
+    """The live dev install should report the same pack version as the source.
+
+    ComfyUI Manager reads package metadata from ``pyproject.toml``. If dev-sync
+    skips it, the code can be current while the UI still reports an older
+    installed version.
+    """
+    assert "pyproject.toml" in sync_to_dev.RUNTIME_PATHS

ComfyUI/custom_nodes/koolook/tests/scripts/test_sync_to_dev_audio.py

@@ -0,0 +1,99 @@
+"""Safety coverage for scripts/sync_to_dev_audio.py."""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "sync_to_dev_audio.py"
+_spec = importlib.util.spec_from_file_location("sync_to_dev_audio", _SCRIPT)
+assert _spec is not None and _spec.loader is not None
+sync_to_dev_audio = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(sync_to_dev_audio)
+
+
+def _stale_path(root: Path) -> Path:
+    return root / "web" / "whatdreamscost_koolook_v1_3_2"
+
+
+def test_remove_stale_paths_removes_directory(tmp_path: Path) -> None:
+    stale = _stale_path(tmp_path)
+    stale.mkdir(parents=True)
+    (stale / "ltx_director.js").write_text("old extension\n", encoding="utf-8")
+
+    removed = sync_to_dev_audio.remove_stale_paths(
+        tmp_path,
+        dry_run=False,
+        verbose=False,
+    )
+
+    assert removed == 1
+    assert not stale.exists()
+
+
+def test_remove_stale_paths_dry_run_preserves_directory(tmp_path: Path) -> None:
+    stale = _stale_path(tmp_path)
+    stale.mkdir(parents=True)
+
+    removed = sync_to_dev_audio.remove_stale_paths(
+        tmp_path,
+        dry_run=True,
+        verbose=False,
+    )
+
+    assert removed == 1
+    assert stale.exists()
+
+
+def test_remove_stale_paths_idempotent_when_absent(tmp_path: Path) -> None:
+    removed = sync_to_dev_audio.remove_stale_paths(
+        tmp_path,
+        dry_run=False,
+        verbose=False,
+    )
+
+    assert removed == 0
+
+
+def test_remove_stale_paths_unlinks_symlink_without_touching_target(tmp_path: Path) -> None:
+    current = tmp_path / "web" / "whatdreamscost_koolook"
+    current.mkdir(parents=True)
+    keep = current / "ltx_director.js"
+    keep.write_text("current extension\n", encoding="utf-8")
+    stale = _stale_path(tmp_path)
+    try:
+        stale.symlink_to(current, target_is_directory=True)
+    except OSError as exc:
+        pytest.skip(f"symlink creation unavailable: {exc}")
+
+    removed = sync_to_dev_audio.remove_stale_paths(
+        tmp_path,
+        dry_run=False,
+        verbose=False,
+    )
+
+    assert removed == 1
+    assert not stale.exists()
+    assert keep.read_text(encoding="utf-8") == "current extension\n"
+
+
+def test_target_is_repo_root_detects_source_repo() -> None:
+    assert sync_to_dev_audio.target_is_repo_root(sync_to_dev_audio._dev.REPO_ROOT)
+
+
+def test_audio_paths_ship_init_load_gates() -> None:
+    """dev-sync-audio ships ``__init__.py``, so it must also ship the modules
+    ``__init__`` imports at load before any node group. Those gates are not
+    per-group-guarded: a missing ``koolook_install_guard`` makes the absolute
+    import fallback raise uncaught (plugin dead), and a missing
+    ``koolook_versioning`` makes the context probe mislabel its ImportError as
+    a non-Comfy context and register nothing (#198 / #183).
+    """
+    audio_paths = set(sync_to_dev_audio.AUDIO_PATHS)
+    required = {"__init__.py", "koolook_install_guard.py", "koolook_versioning.py"}
+    missing = sorted(required - audio_paths)
+    assert not missing, (
+        f"dev-sync-audio ships __init__.py but not its load-time gate(s): {missing}"
+    )

ComfyUI/custom_nodes/koolook/tests/scripts/test_validate_workflow.py

@@ -0,0 +1,186 @@
+"""Regression tests for scripts/validate_workflow.py.
+
+Anchored by PR #170 review: the validator must report problems rather than
+raise on malformed-but-valid JSON. These tests pin that behavior plus a
+sampling of the existing happy-path and consistency checks so future edits
+cannot silently regress the safety guarantees.
+"""
+from __future__ import annotations
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+# Load the script directly — it lives under scripts/, not under a package.
+_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "validate_workflow.py"
+_spec = importlib.util.spec_from_file_location("validate_workflow", _SCRIPT)
+assert _spec is not None and _spec.loader is not None
+_module = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_module)
+validate = _module.validate
+main = _module.main
+
+
+def _minimal_clean() -> dict:
+    """Smallest workflow that should validate cleanly: two nodes, one link."""
+    return {
+        "last_node_id": 2,
+        "last_link_id": 1,
+        "nodes": [
+            {
+                "id": 1,
+                "type": "Src",
+                "inputs": [],
+                "outputs": [
+                    {"name": "out", "type": "FOO", "links": [1]},
+                ],
+            },
+            {
+                "id": 2,
+                "type": "Dst",
+                "inputs": [
+                    {"name": "in", "type": "FOO", "link": 1},
+                ],
+                "outputs": [],
+            },
+        ],
+        "links": [[1, 1, 0, 2, 0, "FOO"]],
+    }
+
+
+# --- Happy path -------------------------------------------------------------
+
+def test_minimal_clean_workflow_has_no_problems() -> None:
+    assert validate(_minimal_clean()) == []
+
+
+# --- PR #170 review repros: malformed-but-valid JSON must not crash --------
+
+@pytest.mark.parametrize("data", [None, 42, 3.14, "string", [1, 2], (1, 2)])
+def test_top_level_not_object_reports_does_not_crash(data) -> None:
+    problems = validate(data)
+    assert problems, "expected at least one problem"
+    assert "top-level JSON must be an object" in problems[0]
+
+
+def test_node_entry_not_dict_reports_does_not_crash() -> None:
+    # Reviewer's repro 1: nodes contains an int.
+    data = {"nodes": [1], "links": [], "last_node_id": 0, "last_link_id": 0}
+    problems = validate(data)
+    assert any("nodes[0]" in p and "object" in p for p in problems), problems
+
+
+def test_nodes_field_not_list_reports() -> None:
+    data = {"nodes": {"oops": "dict not list"}, "links": []}
+    problems = validate(data)
+    assert any("'nodes' must be a list" in p for p in problems), problems
+
+
+def test_links_field_not_list_reports() -> None:
+    data = {"nodes": [], "links": "not-a-list"}
+    problems = validate(data)
+    assert any("'links' must be a list" in p for p in problems), problems
+
+
+def test_inputs_field_not_list_reports() -> None:
+    data = _minimal_clean()
+    data["nodes"][1]["inputs"] = {"oops": "dict not list"}
+    problems = validate(data)
+    assert any("'inputs' must be a list" in p for p in problems), problems
+
+
+def test_input_entry_not_dict_reports() -> None:
+    data = _minimal_clean()
+    data["nodes"][1]["inputs"] = ["string-not-dict"]
+    problems = validate(data)
+    assert any("inputs[0]" in p and "object" in p for p in problems), problems
+
+
+def test_output_entry_not_dict_reports() -> None:
+    data = _minimal_clean()
+    data["nodes"][0]["outputs"] = [99]
+    problems = validate(data)
+    assert any("outputs[0]" in p and "object" in p for p in problems), problems
+
+
+def test_malformed_link_not_list_reports() -> None:
+    data = _minimal_clean()
+    data["links"].append("not-a-list")
+    problems = validate(data)
+    assert any("links[1]" in p for p in problems), problems
+
+
+def test_malformed_link_wrong_length_reports() -> None:
+    data = _minimal_clean()
+    data["links"].append([2, 1, 0])  # too short
+    problems = validate(data)
+    assert any("links[1]" in p and "6 elements" in p for p in problems), problems
+
+
+# --- Existing consistency checks -------------------------------------------
+
+def test_link_to_missing_src_node_reports() -> None:
+    data = _minimal_clean()
+    data["links"] = [[1, 99, 0, 2, 0, "FOO"]]
+    data["nodes"][0]["outputs"][0]["links"] = []  # not referenced from anywhere now
+    problems = validate(data)
+    assert any("src node 99 missing" in p for p in problems), problems
+
+
+def test_type_mismatch_on_slot_reports() -> None:
+    data = _minimal_clean()
+    data["links"] = [[1, 1, 0, 2, 0, "BAR"]]  # link declares BAR, slots are FOO
+    problems = validate(data)
+    assert any("type mismatch" in p for p in problems), problems
+
+
+def test_wildcard_destination_accepts_concrete_link_type() -> None:
+    data = _minimal_clean()
+    data["nodes"][1]["inputs"][0]["type"] = "*"
+    assert validate(data) == []
+
+
+def test_duplicate_node_ids_report() -> None:
+    data = _minimal_clean()
+    data["nodes"][1]["id"] = 1  # collision with first node
+    problems = validate(data)
+    assert any("Duplicate node IDs" in p for p in problems), problems
+
+
+def test_endpoint_ref_desync_reports() -> None:
+    data = _minimal_clean()
+    data["nodes"][0]["outputs"][0]["links"] = []  # source side forgot link 1
+    problems = validate(data)
+    assert any("missing from node 1 output[0]" in p for p in problems), problems
+
+
+def test_last_node_id_too_low_reports() -> None:
+    data = _minimal_clean()
+    data["last_node_id"] = 0  # but max is 2
+    problems = validate(data)
+    assert any("last_node_id" in p for p in problems), problems
+
+
+# --- CLI smoke (covers main() exit codes) ----------------------------------
+
+def test_cli_returns_zero_on_clean_workflow(tmp_path: Path) -> None:
+    p = tmp_path / "clean.json"
+    p.write_text(json.dumps(_minimal_clean()), encoding="utf-8")
+    assert main([str(p), "--quiet"]) == 0
+
+
+def test_cli_returns_one_on_problems(tmp_path: Path) -> None:
+    p = tmp_path / "broken.json"
+    p.write_text(json.dumps({"nodes": [1], "links": []}), encoding="utf-8")
+    assert main([str(p), "--quiet"]) == 1
+
+
+def test_cli_returns_two_on_missing_file(tmp_path: Path) -> None:
+    assert main([str(tmp_path / "does-not-exist.json"), "--quiet"]) == 2
+
+
+def test_cli_returns_two_on_invalid_json(tmp_path: Path) -> None:
+    p = tmp_path / "bad.json"
+    p.write_text("{not valid", encoding="utf-8")
+    assert main([str(p), "--quiet"]) == 2

ComfyUI/custom_nodes/koolook/tests/server/test_browse_list_children.py

@@ -0,0 +1,90 @@
+"""Tests for ``_list_child_dirs`` / ``_list_child_files`` — the listing
+helpers that power the folder picker (issue #137, mockup section 6).
+
+Folders are listed by name, sorted case-insensitively, with ``_autosave``
+subfolders hidden (those are koolook-internal recovery dirs, not user-
+selectable library locations). Files are listed JSON-only, also sorted
+case-insensitively. Both helpers swallow per-entry ``OSError`` so a
+broken symlink or unreadable dotfile in the middle of the listing
+doesn't sink the whole response.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from koolook_routes import _list_child_dirs, _list_child_files
+
+
+def test_list_child_dirs_returns_sorted_dir_entries(tmp_path: Path) -> None:
+    (tmp_path / "zebra").mkdir()
+    (tmp_path / "Alpha").mkdir()
+    (tmp_path / "mango").mkdir()
+
+    rows = _list_child_dirs(tmp_path)
+
+    assert [r["name"] for r in rows] == ["Alpha", "mango", "zebra"]
+    for row in rows:
+        assert set(row) == {"name", "path"}
+        assert row["path"].endswith(row["name"])
+
+
+def test_list_child_dirs_hides_autosave_subfolders(tmp_path: Path) -> None:
+    """Per-preset autosave dirs live under the library, but the picker
+    must not let users pick them as a library location — they're
+    koolook-internal recovery state. ``_unsaved_autosave`` (no preset
+    name prefix) is also hidden by the same rule."""
+    (tmp_path / "user-pick").mkdir()
+    (tmp_path / "MyPreset_autosave").mkdir()
+    (tmp_path / "_unsaved_autosave").mkdir()
+    (tmp_path / "other-pick").mkdir()
+
+    rows = _list_child_dirs(tmp_path)
+
+    assert [r["name"] for r in rows] == ["other-pick", "user-pick"]
+
+
+def test_list_child_dirs_ignores_regular_files(tmp_path: Path) -> None:
+    (tmp_path / "subdir").mkdir()
+    (tmp_path / "note.txt").write_text("ignored")
+    (tmp_path / "preset.json").write_text("{}")
+
+    rows = _list_child_dirs(tmp_path)
+
+    assert [r["name"] for r in rows] == ["subdir"]
+
+
+def test_list_child_files_returns_only_json_sorted(tmp_path: Path) -> None:
+    """Files-for-context affordance restricts to ``*.json`` because the
+    picker is exclusively used to choose a snapshot library folder;
+    surfacing non-JSON files would mislead the user."""
+    (tmp_path / "Koolook_v03.json").write_text("{}")
+    (tmp_path / "starter.json").write_text("{}")
+    (tmp_path / "readme.md").write_text("ignored")
+    (tmp_path / "notes.txt").write_text("ignored")
+    # Subdirs are not files — should be ignored even if named *.json.
+    (tmp_path / "looks_like_a_file.json").mkdir()
+
+    rows = _list_child_files(tmp_path)
+
+    assert [r["name"] for r in rows] == ["Koolook_v03.json", "starter.json"]
+    for row in rows:
+        assert set(row) == {"name"}, "files-for-context entries carry name only"
+
+
+def test_list_child_files_returns_empty_for_no_json(tmp_path: Path) -> None:
+    (tmp_path / "readme.md").write_text("ignored")
+    (tmp_path / "subdir").mkdir()
+
+    assert _list_child_files(tmp_path) == []
+
+
+def test_list_child_files_is_case_insensitive_on_extension(tmp_path: Path) -> None:
+    """Spelling of ``.json`` shouldn't matter on a case-insensitive FS;
+    surface upper-case copies too so a user-renamed ``PRESET.JSON``
+    doesn't disappear from the affordance."""
+    (tmp_path / "lower.json").write_text("{}")
+    (tmp_path / "UPPER.JSON").write_text("{}")
+
+    rows = _list_child_files(tmp_path)
+
+    assert sorted(r["name"] for r in rows) == ["UPPER.JSON", "lower.json"]

ComfyUI/custom_nodes/koolook/tests/server/test_listing_autosave_mtime.py

@@ -0,0 +1,84 @@
+"""Tests for the listing row-augment that surfaces the newest recovery
+mtime per named preset.
+
+The Load dialog uses the augmented mtime to decide whether to flag a row
+as "newer auto-save available". Before issue #137 the augmentation only
+considered ``periodic.json``; pre-load files were hidden in the Recovery
+disclosure even when newer. After the fix the helper returns the max
+mtime across ``periodic.json`` and every ``pre_load_*.json`` so the row
+flag reflects the freshest recovery file regardless of which capture
+mechanism wrote it.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from koolook_routes import _latest_autosave_mtime
+
+
+def _touch(path: Path, mtime: float) -> None:
+    """Create ``path`` with empty contents and pin its mtime."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("{}")
+    os.utime(path, (mtime, mtime))
+
+
+def test_returns_periodic_mtime_when_only_periodic_is_newer(tmp_path: Path) -> None:
+    autosave_dir = tmp_path / "foo_autosave"
+    _touch(autosave_dir / "periodic.json", mtime=2000.0)
+
+    assert _latest_autosave_mtime(autosave_dir, named_mtime=1000.0) == 2000.0
+
+
+def test_returns_newest_pre_load_mtime_when_only_pre_loads_exist(tmp_path: Path) -> None:
+    """When no ``periodic.json`` exists but ``pre_load_*.json`` files do, the
+    helper returns the mtime of the newest pre_load file (if newer than the
+    named save). Pre_loads are written on every Load and rotated up to 5
+    deep, so any of them may be the freshest recovery point."""
+    autosave_dir = tmp_path / "foo_autosave"
+    _touch(autosave_dir / "pre_load_2024-01-01T10-00-00.json", mtime=1500.0)
+    _touch(autosave_dir / "pre_load_2024-01-02T10-00-00.json", mtime=3000.0)
+    _touch(autosave_dir / "pre_load_2024-01-01T11-00-00.json", mtime=2000.0)
+
+    assert _latest_autosave_mtime(autosave_dir, named_mtime=1000.0) == 3000.0
+
+
+def test_returns_max_when_both_periodic_and_pre_loads_exist(tmp_path: Path) -> None:
+    """When both file kinds exist, the helper returns the newest mtime across
+    them regardless of which kind produced it. Issue #137's whole point:
+    the row flag must reflect the freshest recovery point even when a
+    pre_load is newer than the latest periodic snapshot.
+    """
+    autosave_dir = tmp_path / "foo_autosave"
+    _touch(autosave_dir / "periodic.json", mtime=2000.0)
+    _touch(autosave_dir / "pre_load_2024-01-02T10-00-00.json", mtime=4000.0)
+    _touch(autosave_dir / "pre_load_2024-01-01T10-00-00.json", mtime=1800.0)
+
+    assert _latest_autosave_mtime(autosave_dir, named_mtime=1000.0) == 4000.0
+
+    # And the symmetric case: periodic wins when newer than every pre_load.
+    _touch(autosave_dir / "periodic.json", mtime=5000.0)
+    assert _latest_autosave_mtime(autosave_dir, named_mtime=1000.0) == 5000.0
+
+
+def test_returns_none_when_no_autosave_file_is_newer_than_named(tmp_path: Path) -> None:
+    """Strictly-newer rule: when every autosave file's mtime is ``<=`` the
+    named save's mtime, the helper returns ``None`` so the row stays in
+    its normal state (no "newer auto-save" affordance fires).
+    """
+    autosave_dir = tmp_path / "foo_autosave"
+    _touch(autosave_dir / "periodic.json", mtime=900.0)
+    _touch(autosave_dir / "pre_load_2024-01-01T10-00-00.json", mtime=800.0)
+    _touch(autosave_dir / "pre_load_2024-01-02T10-00-00.json", mtime=1000.0)
+
+    assert _latest_autosave_mtime(autosave_dir, named_mtime=1000.0) is None
+
+
+def test_returns_none_when_autosave_dir_is_missing(tmp_path: Path) -> None:
+    """No autosave dir at all (the common case for freshly-created presets):
+    the helper returns ``None`` without raising. Powers the library-root
+    listing pass where most rows won't have a sibling autosave dir.
+    """
+    missing = tmp_path / "foo_autosave"
+    assert _latest_autosave_mtime(missing, named_mtime=1000.0) is None

ComfyUI/custom_nodes/koolook/tests/server/test_published_setup_api.py

@@ -0,0 +1,664 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from copy import deepcopy
+
+from aiohttp import web
+from aiohttp.test_utils import make_mocked_request
+
+import koolook_routes
+from koolook_setup_runner import PublishedSetupRunner
+from koolook_setups import FileSetupStorage, PublishedSetupRegistry, StaticSetupStorage
+from tests.server.test_published_setup_registry import _valid_setup
+
+
+def test_catalog_routes_expose_list_and_detail_contracts() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        app = _app_with_registry(registry)
+
+        list_response = await _handle(app, "GET", "/koolook/api/setups")
+        detail_response = await _handle(app, "GET", "/koolook/api/setups/ltx-director-demo")
+        missing_response = await _handle(app, "GET", "/koolook/api/setups/missing")
+
+        assert list_response.status == 200
+        assert detail_response.status == 200
+        assert missing_response.status == 404
+
+        rows = _json_body(list_response)
+        detail = _json_body(detail_response)
+        assert rows[0]["id"] == "ltx-director-demo"
+        assert "visualGraph" not in rows[0]
+        assert "apiPrompt" not in rows[0]
+        assert detail["visualGraph"] == _valid_setup()["visualGraph"]
+        assert detail["inputContract"] == _valid_setup()["inputContract"]
+
+    asyncio.run(exercise())
+
+
+def test_setup_runner_simulator_routes_serve_html_and_js() -> None:
+    async def exercise() -> None:
+        app = _app_with_registry(PublishedSetupRegistry(StaticSetupStorage([])))
+
+        html_response = await _handle(app, "GET", "/koolook/setup_runner_simulator.html")
+        js_response = await _handle(app, "GET", "/koolook/setup_runner_simulator.js")
+
+        assert html_response.status == 200
+        assert "Koolook Setup Runner Simulator" in html_response.text
+        assert "./setup_runner_simulator.js" in html_response.text
+        assert js_response.status == 200
+        assert "listPublishedSetups" in js_response.text
+
+    asyncio.run(exercise())
+
+
+def test_version_route_exposes_installed_version_and_release_urls() -> None:
+    async def exercise() -> None:
+        app = _app_with_registry(PublishedSetupRegistry(StaticSetupStorage([])))
+
+        response = await _handle(app, "GET", "/koolook/api/version")
+
+        assert response.status == 200
+        body = _json_body(response)
+        assert body["version"] == "0.4.4"
+        assert body["releasesUrl"] == "https://github.com/malkuthro/ComfyUI-Koolook/releases"
+        assert body["latestReleaseApiUrl"].endswith("/malkuthro/ComfyUI-Koolook/releases/latest")
+
+    asyncio.run(exercise())
+
+
+def test_catalog_list_omits_invalid_setups() -> None:
+    async def exercise() -> None:
+        invalid = deepcopy(_valid_setup())
+        invalid["id"] = "broken"
+        invalid.pop("metadata")
+        registry = PublishedSetupRegistry(StaticSetupStorage([invalid, _valid_setup()]))
+        app = _app_with_registry(registry)
+
+        response = await _handle(app, "GET", "/koolook/api/setups")
+        rows = _json_body(response)
+
+        assert response.status == 200
+        assert [row["id"] for row in rows] == ["ltx-director-demo"]
+        assert registry.diagnostics == ["broken: missing required field: metadata"]
+
+    asyncio.run(exercise())
+
+
+def test_publish_route_persists_setup_and_catalog_returns_it() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([]))
+        app = _app_with_registry(registry)
+        payload = {
+            "visualGraph": {
+                "nodes": [
+                    {
+                        "id": 12,
+                        "type": "Text Multiline",
+                        "inputs": [{"name": "text", "widget": {"name": "text"}}],
+                        "widgets_values": ["published prompt"],
+                    }
+                ],
+                "links": [],
+            },
+            "metadata": {
+                "id": "published-from-sidebar",
+                "title": "Published From Sidebar",
+                "description": "Published through the API.",
+                "category": "Video",
+                "tags": ["publish"],
+                "previewImage": "",
+            },
+            "inputContract": {
+                "inputs": [
+                    {
+                        "key": "prompt",
+                        "label": "Prompt",
+                        "type": "text",
+                        "required": True,
+                        "target": {"node": "12", "input": "text"},
+                    }
+                ]
+            },
+            "outputContract": {"outputs": [{"key": "preview", "type": "image"}]},
+            "source": {"kind": "sidebar-workflow", "path": "Demos/Published From Sidebar"},
+        }
+
+        publish_response = await _handle_json(app, "POST", "/koolook/api/setups", payload)
+        detail_response = await _handle(app, "GET", "/koolook/api/setups/published-from-sidebar")
+
+        assert publish_response.status == 200
+        body = _json_body(publish_response)
+        assert body["ok"] is True
+        assert body["setup"]["id"] == "published-from-sidebar"
+        detail = _json_body(detail_response)
+        assert detail["source"]["path"] == "Demos/Published From Sidebar"
+        assert detail["apiPrompt"] == {
+            "12": {"class_type": "Text Multiline", "inputs": {"text": "published prompt"}}
+        }
+        assert detail["validation"] == {"status": "valid", "diagnostics": []}
+
+    asyncio.run(exercise())
+
+
+def test_publish_route_returns_storage_path(tmp_path) -> None:
+    """The publish response surfaces where the setup was saved on disk so
+    the sidebar can show / copy / open the registry location (issue #227)."""
+
+    async def exercise() -> None:
+        storage_path = tmp_path / "koolook-published-setups" / "setups.json"
+        registry = PublishedSetupRegistry(FileSetupStorage(storage_path))
+        app = _app_with_registry(registry)
+        payload = {
+            "visualGraph": {
+                "nodes": [
+                    {
+                        "id": 12,
+                        "type": "Text Multiline",
+                        "inputs": [{"name": "text", "widget": {"name": "text"}}],
+                        "widgets_values": ["published prompt"],
+                    }
+                ],
+                "links": [],
+            },
+            "metadata": {
+                "id": "published-with-path",
+                "title": "Published With Path",
+                "description": "Surfaces its storage path.",
+                "category": "Video",
+                "tags": ["publish"],
+                "previewImage": "",
+            },
+            "inputContract": {
+                "inputs": [
+                    {
+                        "key": "prompt",
+                        "label": "Prompt",
+                        "type": "text",
+                        "required": True,
+                        "target": {"node": "12", "input": "text"},
+                    }
+                ]
+            },
+            "outputContract": {"outputs": [{"key": "preview", "type": "image"}]},
+            "source": {"kind": "sidebar-workflow", "path": "Demos/Published With Path"},
+        }
+
+        publish_response = await _handle_json(app, "POST", "/koolook/api/setups", payload)
+
+        assert publish_response.status == 200
+        body = _json_body(publish_response)
+        assert body["ok"] is True
+        assert body["setup"]["id"] == "published-with-path"
+        assert body["storagePath"] == str(storage_path)
+
+    asyncio.run(exercise())
+
+
+def test_reveal_published_setup_folder_opens_storage_dir(tmp_path, monkeypatch) -> None:
+    """Open folder on the success card reveals the published-setups
+    directory (not the snapshot library) in the OS file manager."""
+
+    async def exercise() -> None:
+        storage_path = tmp_path / "koolook-published-setups" / "setups.json"
+        storage_path.parent.mkdir(parents=True)
+        registry = PublishedSetupRegistry(FileSetupStorage(storage_path))
+        app = _app_with_registry(registry)
+
+        opened: list = []
+        monkeypatch.setattr(
+            koolook_routes.subprocess,
+            "Popen",
+            lambda args, *a, **k: opened.append(args) or object(),
+        )
+
+        response = await _handle(app, "POST", "/koolook/api/setups/reveal")
+
+        assert response.status == 200
+        assert _json_body(response) == {"ok": True, "path": str(storage_path.parent)}
+        assert len(opened) == 1
+        # Launcher binary is platform-specific; the revealed path is the dir.
+        assert opened[0][-1] == str(storage_path.parent)
+
+    asyncio.run(exercise())
+
+
+def test_reveal_published_setup_folder_missing_dir_returns_404(tmp_path, monkeypatch) -> None:
+    """Reveal fails cleanly (no file-manager spawn) when nothing has been
+    published yet, so the storage directory does not exist on disk."""
+
+    async def exercise() -> None:
+        storage_path = tmp_path / "koolook-published-setups" / "setups.json"
+        registry = PublishedSetupRegistry(FileSetupStorage(storage_path))
+        app = _app_with_registry(registry)
+
+        opened: list = []
+        monkeypatch.setattr(
+            koolook_routes.subprocess,
+            "Popen",
+            lambda args, *a, **k: opened.append(args) or object(),
+        )
+
+        response = await _handle(app, "POST", "/koolook/api/setups/reveal")
+
+        assert response.status == 404
+        assert opened == []
+
+    asyncio.run(exercise())
+
+
+def test_publish_route_preserves_supplied_api_prompt() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([]))
+        app = _app_with_registry(registry)
+        payload = {
+            "visualGraph": {
+                "nodes": [
+                    {
+                        "id": 12,
+                        "type": "Text Multiline",
+                        "inputs": [{"name": "text", "widget": {"name": "text"}}],
+                        "widgets_values": ["fallback prompt"],
+                    }
+                ],
+                "links": [],
+            },
+            "apiPrompt": {
+                "12": {"class_type": "Text Multiline", "inputs": {"text": "comfy api prompt"}}
+            },
+            "metadata": {
+                "id": "published-with-api-prompt",
+                "title": "Published With API Prompt",
+                "description": "Published with Comfy's API workflow.",
+            },
+            "inputContract": {
+                "inputs": [
+                    {
+                        "key": "prompt",
+                        "type": "text",
+                        "target": {"node": "12", "input": "text"},
+                    }
+                ]
+            },
+            "outputContract": {"outputs": [{"key": "preview", "type": "image"}]},
+            "source": {"kind": "sidebar-workflow", "path": "Demos/API Prompt"},
+        }
+
+        publish_response = await _handle_json(app, "POST", "/koolook/api/setups", payload)
+        detail_response = await _handle(app, "GET", "/koolook/api/setups/published-with-api-prompt")
+
+        assert publish_response.status == 200
+        detail = _json_body(detail_response)
+        assert detail["apiPrompt"] == payload["apiPrompt"]
+
+    asyncio.run(exercise())
+
+
+def test_publish_route_rejects_invalid_contract_with_clear_error() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([]))
+        app = _app_with_registry(registry)
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups",
+            {
+                "visualGraph": {
+                    "nodes": [
+                        {
+                            "id": 12,
+                            "type": "Text Multiline",
+                            "inputs": [{"name": "text", "widget": {"name": "text"}}],
+                            "widgets_values": ["bad prompt"],
+                        }
+                    ],
+                    "links": [],
+                },
+                "metadata": {"id": "bad", "title": "Bad", "description": "Bad"},
+                "inputContract": {
+                    "inputs": [{"key": "prompt", "type": "text", "target": {"node": "99", "input": "text"}}]
+                },
+                "outputContract": {"outputs": [{"key": "preview", "type": "image"}]},
+                "source": {"kind": "sidebar-workflow", "path": "Demos/Bad"},
+            },
+        )
+
+        assert response.status == 400
+        assert "target.node not found" in _json_body(response)["errors"][0]
+        assert registry.listSetups() == []
+
+    asyncio.run(exercise())
+
+
+def test_publish_route_rejects_missing_metadata_with_clear_error() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([]))
+        app = _app_with_registry(registry)
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups",
+            {
+                "visualGraph": {"nodes": []},
+                "inputContract": {"inputs": []},
+                "outputContract": {"outputs": []},
+                "source": {"kind": "sidebar-workflow", "path": "Demos/Missing Metadata"},
+            },
+        )
+
+        assert response.status == 400
+        assert "metadata must be an object" in _json_body(response)["errors"][0]
+        assert registry.listSetups() == []
+
+    asyncio.run(exercise())
+
+
+def test_run_route_queues_callable_setup_and_returns_stable_run_id() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        comfy = _FakeComfyClient()
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(registry, comfy),
+        )
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "external prompt"}},
+        )
+
+        assert response.status == 200
+        assert _json_body(response) == {
+            "ok": True,
+            "run": {
+                "runId": "run-000001",
+                "promptId": "comfy-prompt-1",
+                "status": "queued",
+            },
+        }
+        assert comfy.submitted_prompts == [
+            {"12": {"class_type": "Text Multiline", "inputs": {"text": "external prompt"}}}
+        ]
+
+    asyncio.run(exercise())
+
+
+def test_run_status_route_reports_succeeded_outputs_from_comfy_history() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        comfy = _FakeComfyClient(
+            history={
+                "comfy-prompt-1": {
+                    "status": {"completed": True, "status_str": "success"},
+                    "outputs": {
+                        "20": {
+                            "videos": [
+                                {
+                                    "filename": "demo.mp4",
+                                    "subfolder": "koolook",
+                                    "type": "output",
+                                }
+                            ]
+                        }
+                    },
+                }
+            }
+        )
+        runner = PublishedSetupRunner(registry, comfy)
+        app = _app_with_registry(registry, setup_runner_factory=lambda: runner)
+
+        run_response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "external prompt"}},
+        )
+        run_id = _json_body(run_response)["run"]["runId"]
+        status_response = await _handle(app, "GET", f"/koolook/api/runs/{run_id}")
+
+        assert status_response.status == 200
+        assert _json_body(status_response) == {
+            "ok": True,
+            "run": {
+                "runId": "run-000001",
+                "setupId": "ltx-director-demo",
+                "promptId": "comfy-prompt-1",
+                "status": "succeeded",
+                "comfyStatus": {"completed": True, "status_str": "success"},
+                "outputs": [
+                    {
+                        "key": "video",
+                        "label": "Video",
+                        "type": "video",
+                        "items": [
+                            {
+                                "nodeId": "20",
+                                "kind": "videos",
+                                "filename": "demo.mp4",
+                                "subfolder": "koolook",
+                                "type": "output",
+                            }
+                        ],
+                    }
+                ],
+            },
+        }
+
+    asyncio.run(exercise())
+
+
+def test_run_status_route_reports_failed_state_from_comfy_history() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        comfy = _FakeComfyClient(
+            history={
+                "comfy-prompt-1": {
+                    "status": {"completed": True, "status_str": "error"},
+                    "outputs": {},
+                }
+            }
+        )
+        runner = PublishedSetupRunner(registry, comfy)
+        app = _app_with_registry(registry, setup_runner_factory=lambda: runner)
+
+        run_response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "external prompt"}},
+        )
+        run_id = _json_body(run_response)["run"]["runId"]
+        status_response = await _handle(app, "GET", f"/koolook/api/runs/{run_id}")
+
+        assert status_response.status == 200
+        assert _json_body(status_response)["run"]["status"] == "failed"
+
+    asyncio.run(exercise())
+
+
+def test_run_route_returns_clear_errors_for_invalid_inputs() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(registry, _FakeComfyClient()),
+        )
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "ok", "seed": 123}},
+        )
+
+        assert response.status == 400
+        assert _json_body(response) == {
+            "ok": False,
+            "errors": ["input 'seed' is not declared by this setup"],
+        }
+
+    asyncio.run(exercise())
+
+
+def test_run_route_returns_clear_error_for_non_callable_setup() -> None:
+    async def exercise() -> None:
+        setup = _valid_setup()
+        setup["apiPrompt"] = None
+        setup["validation"] = {"status": "draft", "diagnostics": ["API prompt conversion pending."]}
+        registry = PublishedSetupRegistry(StaticSetupStorage([setup]))
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(registry, _FakeComfyClient()),
+        )
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "ok"}},
+        )
+
+        assert response.status == 400
+        assert _json_body(response) == {
+            "ok": False,
+            "errors": ["Published setup 'ltx-director-demo' is not callable."],
+        }
+
+    asyncio.run(exercise())
+
+
+def test_run_route_returns_clear_error_for_comfy_queue_failure() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(
+                registry,
+                _FakeComfyClient(queue_error=RuntimeError("server down")),
+            ),
+        )
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/ltx-director-demo/run",
+            {"inputs": {"prompt": "ok"}},
+        )
+
+        assert response.status == 502
+        assert _json_body(response) == {
+            "ok": False,
+            "errors": ["ComfyUI queue request failed: server down"],
+        }
+
+    asyncio.run(exercise())
+
+
+def test_run_route_returns_clear_error_for_missing_setup() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(registry, _FakeComfyClient()),
+        )
+
+        response = await _handle_json(
+            app,
+            "POST",
+            "/koolook/api/setups/missing/run",
+            {"inputs": {"prompt": "ok"}},
+        )
+
+        assert response.status == 404
+        assert _json_body(response) == {
+            "ok": False,
+            "errors": ["Published setup 'missing' not found."],
+        }
+
+    asyncio.run(exercise())
+
+
+def test_run_status_route_returns_clear_error_for_unknown_run_id() -> None:
+    async def exercise() -> None:
+        registry = PublishedSetupRegistry(StaticSetupStorage([_valid_setup()]))
+        app = _app_with_registry(
+            registry,
+            setup_runner_factory=lambda: PublishedSetupRunner(registry, _FakeComfyClient()),
+        )
+
+        response = await _handle(app, "GET", "/koolook/api/runs/run-missing")
+
+        assert response.status == 404
+        assert _json_body(response) == {
+            "ok": False,
+            "errors": ["Koolook run 'run-missing' not found."],
+        }
+
+    asyncio.run(exercise())
+
+
+class _FakeComfyClient:
+    def __init__(self, *, history=None, queue=None, queue_error=None) -> None:
+        self.submitted_prompts: list[dict] = []
+        self.history = history or {}
+        self.queue = queue or {"queue_running": [], "queue_pending": []}
+        self.queue_error = queue_error
+
+    async def queue_prompt(self, prompt: dict) -> dict:
+        if self.queue_error is not None:
+            raise self.queue_error
+        self.submitted_prompts.append(prompt)
+        return {"prompt_id": "comfy-prompt-1"}
+
+    async def get_history(self, prompt_id: str) -> dict:
+        return {prompt_id: self.history[prompt_id]} if prompt_id in self.history else {}
+
+    async def get_queue(self) -> dict:
+        return self.queue
+
+
+def _app_with_registry(
+    registry: PublishedSetupRegistry,
+    *,
+    setup_runner_factory=None,
+) -> web.Application:
+    routes = web.RouteTableDef()
+    koolook_routes.register_routes(
+        routes,
+        setup_registry_factory=lambda: registry,
+        setup_runner_factory=setup_runner_factory,
+    )
+    app = web.Application()
+    app.add_routes(routes)
+    return app
+
+
+async def _handle(app: web.Application, method: str, path: str) -> web.Response:
+    request = make_mocked_request(method, path, app=app)
+    try:
+        return await app._handle(request)
+    except web.HTTPException as exc:
+        return exc
+
+
+async def _handle_json(app: web.Application, method: str, path: str, payload) -> web.Response:
+    request = make_mocked_request(
+        method,
+        path,
+        app=app,
+        headers={"Content-Type": "application/json"},
+    )
+    request._read_bytes = json.dumps(payload).encode("utf-8")
+    try:
+        return await app._handle(request)
+    except web.HTTPException as exc:
+        return exc
+
+
+def _json_body(response: web.Response):
+    return json.loads(response.text or "")