Nunchaku FLUX.2 Klein Mask Ref Controller

Klein's reference editing has a leaky-bucket problem: give it a photo of three people and ask it to change one, and it changes all three. The NunchakuKleinMaskReferenceController is the fix - it applies spatial attenuation to an encoded reference so the masked region stays true to the reference while the unmasked area is freed up for the prompt to do whatever you asked. It's not inpainting. It's conditioning surgery, done before sampling.

This is a direct port of a feature capitan01R showed off while building the original Flux2Klein-Enhancer: mask the subject, and Klein keeps the subject's structure while happily rebuilding the background. The original author's framing stuck with me - the masked area "gets targeted by the prompt while staying true to its original structure," and the unmasked area "gets fully freed up." That's exactly what this node does.

The inputs that matter

• conditioning - the stream with your reference latents attached (from Multi Reference Latent or the pack's model loader path).
• mask - the MASK input. White = keep true to the reference; black = let the prompt take over.
• strength - 0 to 1, default 1.0. How hard the mask holds. Lower values soften the boundary between "keep" and "replace."
• invert_mask - flips it, which is the standard trick for "keep the background, change the subject."
• feather - gaussian blur radius on the mask, 0-64. This is the one beginners skip and it's the difference between a hard plastic edge and a natural transition. Start at 4-8.
• reference_index - which of your attached references this mask applies to. Defaults to 0 (the first). If you have multiple references, each gets its own controller.

Output: conditioning, onward to the sampler.

How to wire it

VAE-encode your reference → Multi Reference Latent → Mask Ref Controller (mask from any mask node, or a hand-painted one) → KSampler. One controller per reference you want to constrain.

Installing

The one install this whole pack shares:

cd ComfyUI/custom_nodes
git clone https://github.com/tom-m-2020/ComfyUI-Nunchaku-Klein

Vitoom Nunchaku backend wheel first (from huggingface.co/tonera/vitoom-nunchaku), then the tonera Klein checkpoint in diffusion_models/.

Common issues

• Mask seems ignored - check invert_mask and strength. Also confirm the conditioning feeding this node actually carries the reference you think it does.
• Hard edges in the output - feather is 0. A small blur smooths the transition; this is the fix, not a bug.
• Warm color shift around the edited region - Klein's known edit artifact, independent of this node. Chain a Color Anchor downstream to hold the palette.