Add .github/copilot-instructions.md with repository-specific Copilot guidance

Agent-Logs-Url: https://github.com/jags111/efficiency-nodes-comfyui/sessions/7920bef6-9e7c-49ec-9b3a-6be00166c651

Co-authored-by: jags111 <5968619+jags111@users.noreply.github.com>

.github/copilot-instructions.md

@@ -0,0 +1,121 @@
+# Copilot Instructions for efficiency-nodes-comfyui
+
+## Project Overview
+
+This repository contains **Efficiency Nodes for ComfyUI** — a collection of custom nodes for [ComfyUI](https://github.com/comfyanonymous/ComfyUI) that streamline AI image generation workflows and reduce total node count. The project is maintained by jags111 and is a fork/continuation of the original work by Luciano Cirino.
+
+## Repository Structure
+
+```
+efficiency-nodes-comfyui/
+├── efficiency_nodes.py      # Main file containing all node class definitions
+├── tsc_utils.py             # Utility functions (model caching, loading, helpers)
+├── __init__.py              # Package entry point, registers WEB_DIRECTORY and exports
+├── pyproject.toml           # Project metadata and ComfyUI registry config
+├── requirements.txt         # Python dependencies
+├── arial.ttf                # Font used for image annotation nodes
+├── node_settings.json       # Default node settings
+├── py/                      # Helper modules (samplers, encoders, upscalers)
+│   ├── bnk_adv_encode.py    # Advanced CLIP text encoding
+│   ├── bnk_tiled_samplers.py
+│   ├── city96_latent_upscaler.py
+│   ├── smZ_cfg_denoiser.py
+│   └── ...
+├── js/                      # Frontend JavaScript for ComfyUI web interface
+│   ├── appearance.js        # Node color themes
+│   ├── seedcontrol.js       # Seed widget behavior
+│   ├── widgethider.js       # Dynamic widget visibility
+│   └── node_options/        # Right-click context menu additions
+└── workflows/               # Example workflow JSON files
+```
+
+## Architecture & Key Conventions
+
+### Node Class Pattern
+
+All nodes follow the ComfyUI node pattern:
+
+```python
+class TSC_MyNode:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": { "param": ("TYPE", {"default": value}) },
+            "optional": { "opt_param": ("TYPE",) },
+            "hidden":   { "my_unique_id": "UNIQUE_ID" }
+        }
+
+    RETURN_TYPES = ("TYPE1", "TYPE2",)
+    RETURN_NAMES = ("name1", "name2",)
+    FUNCTION = "execute_method"
+    CATEGORY = "Efficiency Nodes/Category"
+
+    def execute_method(self, param, opt_param=None, my_unique_id=None):
+        # implementation
+        return (result1, result2,)
+```
+
+- All node classes are prefixed with `TSC_`
+- `FUNCTION` must match the name of the method that executes the node
+- `CATEGORY` uses the `"Efficiency Nodes/..."` namespace for grouping in the ComfyUI UI
+- Nodes with side effects (saving images, printing) should set `OUTPUT_NODE = True`
+
+### Node Registration
+
+Nodes are registered at the bottom of `efficiency_nodes.py` by updating `NODE_CLASS_MAPPINGS`:
+
+```python
+NODE_CLASS_MAPPINGS = {
+    "KSampler (Efficient)": TSC_KSampler,
+    "Efficient Loader": TSC_EfficientLoader,
+    # ...
+}
+```
+
+Optional features (requiring extra packages like `simpleeval` or `animatediff`) are wrapped in `try/except ImportError` blocks and registered conditionally.
+
+### Model Caching (tsc_utils.py)
+
+The `loaded_objects` and `last_helds` globals in `tsc_utils.py` implement a caching layer to avoid reloading models between node executions:
+
+- `loaded_objects["ckpt"]` — checkpoints
+- `loaded_objects["lora"]` — LoRA weights
+- `loaded_objects["vae"]`  — VAE models
+- `last_helds["latent"]` / `last_helds["image"]` — KSampler output caches
+
+Always call `globals_cleanup(prompt)` at the start of loader nodes to evict stale cache entries.
+
+### Frontend JavaScript
+
+- JS files in `js/` are served by ComfyUI via `WEB_DIRECTORY = "js"` in `__init__.py`
+- Extensions are registered with `app.registerExtension({ name: "efficiency.<name>", ... })`
+- Use `import { app } from "../../scripts/app.js"` for ComfyUI's app object
+- Widget helpers (`findWidgetByName`, `addMenuHandler`) are in `js/node_options/common/utils.js`
+
+## Dependencies
+
+- **Python**: `torch`, `PIL` (Pillow), `numpy`, `comfy` (ComfyUI), `folder_paths`
+- **Optional Python**: `simpleeval` (Evaluate nodes), `clip_interrogator` (CLIP Interrogator node)
+- **ComfyUI extras**: `comfy_extras.nodes_align_your_steps`, `comfy_extras.nodes_gits`, `comfy_extras.nodes_upscale_model`
+
+## Development Guidelines
+
+- **Do not break the node contract**: Changing `RETURN_TYPES`, `RETURN_NAMES`, or `INPUT_TYPES` on existing nodes is a breaking change for saved workflows.
+- **Cache awareness**: When modifying loader nodes, preserve calls to `globals_cleanup()` and the caching functions (`load_checkpoint`, `load_lora`, `load_vae`).
+- **Error messages**: Use the `warning()` and `error()` helpers from `tsc_utils.py` for consistent console output formatting.
+- **Optional imports**: Wrap any new optional feature dependencies in `try/except ImportError` and print a warning when the package is missing.
+- **Node naming**: Use the `TSC_` prefix for new node classes. Register them in `NODE_CLASS_MAPPINGS` with a human-readable display name (e.g., `"My New Node": TSC_MyNewNode`).
+- **JS extensions**: Follow the existing pattern of using `app.registerExtension` with the `"efficiency.<extensionName>"` naming convention.
+
+## Testing & Validation
+
+There is no automated test suite. Validation is done by loading the nodes in a running ComfyUI instance:
+
+1. Install ComfyUI and place this package in `ComfyUI/custom_nodes/efficiency-nodes-comfyui/`
+2. Start ComfyUI and check the console for import errors
+3. Open the ComfyUI web interface and verify nodes appear under the `Efficiency Nodes` menu category
+4. Load example workflows from the `workflows/` directory to test node behavior
+
+## Publishing
+
+The package is published to the [ComfyUI Registry](https://registry.comfy.org/) via the GitHub Actions workflow `.github/workflows/publish.yml`, triggered when `pyproject.toml` is updated on `main`. Update the `version` field in `pyproject.toml` for each release.

.gitignore

@@ -1,37 +0,0 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Virtual environments
-venv/
-ENV/
-env/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db

efficiency_nodes.py

@@ -3957,12 +3957,6 @@ class TSC_ImageOverlay:
             samples = overlay_image.movedim(-1, 1)
             overlay_image = comfy.utils.common_upscale(samples, overlay_image_size[0], overlay_image_size[1], resize_method, False)
             overlay_image = overlay_image.movedim(1, -1)
-        
-        # Handle batch dimension - use first image if overlay_image is a batch
-        if len(overlay_image.shape) == 4:
-            if overlay_image.shape[0] > 1:
-                print(f"{warning('Image Overlay Warning:')} Multiple overlay images detected ({overlay_image.shape[0]}), using only the first image.")
-            overlay_image = overlay_image[0]
             
         overlay_image = tensor2pil(overlay_image)