feat(krea2): training-free style reference

docs/src/content/docs/features/krea-2.mdx

@@ -1,7 +1,7 @@
 ---
 title: Krea-2
-description: Generate images with the Krea-2 text-to-image models (Turbo and Raw), including the GGUF / single-file workflow and the conditioning enhancers.
-lastUpdated: 2026-07-30
+description: Generate images with the Krea-2 text-to-image models (Turbo and Raw), including the GGUF / single-file workflow, the conditioning enhancers and training-free style reference.
+lastUpdated: 2026-08-20
 sidebar:
   order: 5
 ---
@@ -91,6 +91,35 @@ Reducing image resolution or disabling regional prompting is the practical fallb
 is skipped on unsupported hardware and cannot exercise every GPU/backend combination.
 :::
 
+## Style reference
+
+Krea-2 can transfer the *look* of a reference image — palette, texture, rendering — while the prompt keeps
+driving the content. There is **no adapter model and no LoRA**: the reference's attention keys and values
+are spliced into the target's, so it works with any Krea-2 checkpoint out of the box.
+
+On the canvas, add a **Reference Image** while a Krea-2 model is selected, pick an image, and set **Style
+Strength**. In the workflow editor the same thing is the **Style Reference - Krea-2** node, feeding the
+**Style Reference** input of **Denoise - Krea-2**.
+
+- **Style Strength** is the one knob you need. `1.0` is the recommended setting; the slider goes to `2.0`
+  for a heavier effect. `0` disables the reference entirely and costs nothing.
+- The remaining node inputs (block range, key/value scaling, AdaIN strengths) are for tuning and should be
+  left at their defaults. Style Strength already modulates several of them.
+- Style Strength is recorded in image metadata, so you can see what a given image was generated with. It has
+  no recall button of its own — the reference image itself is not part of the metadata.
+
+:::caution[One reference, matching size, roughly 2x runtime]
+- **Exactly one** reference image is used. If several are enabled on the canvas, only the first is applied
+  and the others are flagged with a warning.
+- The reference must be encoded at **the same width and height as the denoise node** — its image tokens are
+  appended to the target's. On the canvas this is wired up for you. In the workflow editor, set the same
+  width and height on both nodes, or the denoise node will refuse the reference.
+- Every step runs **one extra transformer pass** for the reference, so generation takes roughly **twice as
+  long**.
+- The reference's keys and values are retained for the whole step: about **0.5 GB at 1024²** and **1.7 GB at
+  2560×1440**. At 1440p that no longer fits on a 24 GB card alongside the model.
+:::
+
 ## LoRA
 
 Krea-2 LoRAs (diffusers PEFT format) are supported and apply to both the transformer and — where the

invokeai/app/invocations/fields.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, Callable, Optional, Tuple
+from typing import Any, Callable, Literal, Optional, Tuple
 
 from pydantic import BaseModel, ConfigDict, Field, RootModel, TypeAdapter
 from pydantic.fields import _Unset
@@ -398,6 +398,42 @@ class Krea2ConditioningField(BaseModel):
     )
 
 
+class Krea2StyleReferenceField(BaseModel):
+    """Style-reference conditioning for Krea-2 shared-KV reference attention.
+
+    Carries the VAE-encoded reference latents plus the tuning parameters that shape how strongly, and in
+    which frequency bands, the reference influences the target. The reference must be encoded at exactly
+    the denoise node's resolution, so the dims travel with it for an early, legible mismatch error.
+
+    Only ``style_strength`` is meant for everyday use; it modulates several of the others. The remainder
+    are exposed for tuning and should be left at their defaults.
+    """
+
+    reference_latents_name: str = Field(description="Name of the saved [1, 16, 1, H/8, W/8] reference latents.")
+    width: int = Field(description="Image width the reference was encoded at (must match denoise width).")
+    height: int = Field(description="Image height the reference was encoded at (must match denoise height).")
+    style_strength: float = Field(
+        default=1.0,
+        description="Overall style strength. 0 makes the denoise node skip the reference entirely.",
+    )
+    blocks: str = Field(default="7-27", description="Transformer blocks the reference is injected into.")
+    ref_k_strength: float = Field(default=1.06, description="Multiplier on the reference key path.")
+    adain_strength: float = Field(default=0.85, description="Reference statistics applied to the target Q/K.")
+    value_mode: Literal["target", "raw_reference", "ref_mean", "target_adain", "target_adain_plus_ref"] = Field(
+        default="target_adain_plus_ref", description="How the reference value vectors are constructed."
+    )
+    value_adain_strength: float = Field(
+        default=0.65,
+        description="Reference statistics applied to the target value path. Has no effect while ref_value_mix is 1.0.",
+    )
+    ref_value_mix: float = Field(default=1.0, description="How much raw reference value signal is kept.")
+    high_scale_start: float = Field(default=1.04, description="High-frequency reference key scale at step 0.")
+    high_scale_end: float = Field(default=0.0, description="High-frequency reference key scale at the last step.")
+    low_scale_start: float = Field(default=1.0, description="Low-frequency reference key scale at step 0.")
+    low_scale_end: float = Field(default=1.10, description="Low-frequency reference key scale at the last step.")
+    beta: float = Field(default=2.5, description="Exponent of the high-to-low frequency falloff curve.")
+
+
 class AnimaConditioningField(BaseModel):
     """An Anima conditioning tensor primitive value.