# ComfyUI-OverlaySuite Cursor & Agent Rules

You are working on `ComfyUI-OverlaySuite`, a modular custom node suite for ComfyUI providing advanced image watermarking, text overlay, typography, and compositing capabilities.

## Key Directives:
1. **ComfyUI Tensor Contract**:
   - Images: `torch.Tensor` of shape `[B, H, W, C]`, dtype `float32`, normalized range `[0.0, 1.0]`, RGB channels.
   - Masks: `torch.Tensor` of shape `[B, H, W]` or `[H, W]`, dtype `float32`, range `[0.0, 1.0]`.
   - Never return uint8 or `[0, 255]` values on image pins.
   - Support batch broadcasting (e.g. 1 watermark over B base images).

2. **Clean Modularity**:
   - `nodes/`: Node classes (`INPUT_TYPES`, `RETURN_TYPES`, `FUNCTION`, `CATEGORY = "OverlaySuite/..."`).
   - `core/`: Pure image math, positioning, layout, and blend modes (agnostic of ComfyUI).
   - `utils/`: Fonts, color parsing (HEX/RGB), and tensor/PIL conversion utilities.

3. **Imports**: use relative imports inside the pack (ComfyUI has its own top-level `utils`/`nodes`); tests load the repo as package `overlaysuite` via `tests/_pkg.py`.

4. **Robustness**:
   - Cross-platform paths using `pathlib.Path`.
   - Graceful font fallbacks without throwing uncaught exceptions.
   - Minimal dependencies (`torch`, `numpy`, `Pillow`).

For full architectural standards and blend mode formulas, see `GEMINI.md`.

