Upload neutral_prompt_patcheds using SD-Hub

neutral_prompt_patcheds/.gitignore

@@ -0,0 +1 @@
+__pycache__/

neutral_prompt_patcheds/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 ljleb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neutral_prompt_patcheds/README.md

@@ -0,0 +1,343 @@
+# sd-webui-neutral-prompt — Patched Edition
+
+> **Unified merge of the main experimental branches — with bugfixes and parametric syntax.**
+>
+> Based on the _Ultimate Edition_ merge, with the following additions:
+> - `AND_SALT[k]` / `AND_SALT_WIDE[k]` / `AND_SALT_BLOB[k]` — user-controlled salience sharpness
+> - `AND_ALIGN[D,S]` / `AND_MASK_ALIGN[D,S]` — any D/S pair without suffix pre-declaration
+> - Fixed `AND_SALT` default (k=5 instead of k=20 — actually visible)
+> - Fixed `AND_SALT_BLOB` morphology order (thickify-first prevents seed self-destruction)
+> - Guard against "base prompt replacement" when no plain AND-child is present
+
+---
+
+## What's inside
+
+| Feature | Origin | Keyword / setting |
+|---|---|---|
+| Perpendicular projection | `main` | `AND_PERP` |
+| Saliency-guided mask | `main` + patch | `AND_SALT[k]` |
+| Saliency blob mask | `life` + **fixed** | `AND_SALT_BLOB[k]` |
+| Saliency wide mask | `main` | `AND_SALT_WIDE[k]` |
+| Semantic guidance top-k | `main` | `AND_TOPK` |
+| CFG rescale (mean-preserving) | `main` | CFG rescale φ slider |
+| XYZ-grid CFG rescale axis | `main` | XYZ-grid option |
+| External API override | `main` / `export_rescale_factor` | `override_cfg_rescale()` |
+| CFG rescale factor export | `export_rescale_factor` | `get_last_cfg_rescale_factor()` |
+| Affine spatial transforms | `affine` | `ROTATE / SLIDE / SCALE / SHEAR` |
+| Soft alignment blend | `alignment_blend` | `AND_ALIGN[D,S]` or `AND_ALIGN_D_S` |
+| Binary alignment mask | `alignment_mask` | `AND_MASK_ALIGN[D,S]` or `AND_MASK_ALIGN_D_S` |
+
+---
+
+## Prompt syntax
+
+```
+positive prompt text
+AND_PERP  negative-direction text :0.8
+AND_SALT[5]  competing concept :1.0          ← k=5 (default; more visible than old k=20)
+AND_SALT_WIDE  classic broad mask :0.8       ← k=1 default
+AND_SALT_BLOB[8]  blob concept :1.0          ← custom k for blob seed sharpness
+AND_TOPK  fine detail tweak :0.5
+AND_ALIGN[4,8]  style blend :0.6             ← any valid D,S pair
+AND_MASK_ALIGN[6,12]  structure style :0.6   ← binary-mask variant
+AND_ALIGN_4_8  style blend :0.6             ← fixed-suffix form still works
+AND_PERP ROTATE[0.125]  rotated concept :1.0
+ROTATE[0.125] AND_PERP  rotated concept :1.0
+AND_SALT[5] ROTATE[0.125] shifted concept :1.0
+```
+
+> **Important:** always include a plain base prompt before `AND_*` segments.
+> If all segments have conciliation keywords (no plain `AND`), the extension
+> falls back to standard CFG automatically and logs a warning.
+
+---
+
+## Salience sharpness k
+
+All three salience keywords accept an optional `[k]` parameter:
+
+```
+AND_SALT[k]       sharp mask      default k = 5
+AND_SALT_WIDE[k]  broad mask      default k = 1
+AND_SALT_BLOB[k]  blob mask       default k = 5
+```
+
+| k value | Effect | Approx. pixel coverage |
+|---|---|---|
+| 1 | Very broad, ~50% of pixels | ~50% |
+| 3 | Moderate | ~11% |
+| 5 | Focused (default) | ~2% |
+| 10 | Surgical | ~0.25% |
+| 20 | Extreme (original ultimate default) | ~0.04% |
+
+---
+
+## Alignment kernel sizes D, S
+
+```
+AND_ALIGN[D,S]      soft blend
+AND_MASK_ALIGN[D,S] binary-mask blend
+```
+
+- **D** = detail kernel size (small → fine detail)
+- **S** = structure kernel size (large → global composition)
+- Both in range **[2, 32]**, **D ≠ S**
+- Child contribution is highest where it changes detail *without* breaking structure.
+
+Fixed-suffix form (`AND_ALIGN_4_8`) is still supported and backward-compatible.
+
+---
+
+## Affine transform keywords
+
+Supported in **either order** relative to the conciliation keyword:
+
+| Keyword | Parameter | Effect |
+|---|---|---|
+| `ROTATE[angle]` | angle in turns (0–1) | Rotate latent contribution |
+| `SLIDE[x,y]` | normalised offset | Translate latent contribution |
+| `SCALE[x,y]` | scale factors | Scale latent contribution |
+| `SHEAR[x,y]` | shear in turns | Shear latent contribution |
+
+Multiple transforms can be chained: `ROTATE[0.125] SLIDE[0.1,0]`
+
+---
+
+## External API
+
+```python
+from lib_neutral_prompt.external_code import override_cfg_rescale, get_last_cfg_rescale_factor
+
+override_cfg_rescale(0.7)               # override for next step only
+factor = get_last_cfg_rescale_factor()  # read after generation
+```
+
+---
+
+## CFG Rescale φ
+
+When > 0, rescales CFG output to reduce colour over-saturation at high CFG values.  
+Uses the **mean-preserving** formula:
+
+```
+rescaled = rescale_mean + (cfg_cond − cfg_cond_mean) × rescale_factor
+```
+
+where `rescale_factor = φ × (std(cond)/std(cfg_cond) − 1) + 1`.
+
+---
+
+## Installation
+
+1. Copy this folder into `stable-diffusion-webui/extensions/`
+2. Restart the webui
+
+---
+
+## Smoke-test checklist
+
+Before reporting a bug, verify:
+
+- [ ] Base prompt exists before `AND_*` segments
+- [ ] `AND_SALT` without `[k]` defaults to k=5 (moderate coverage)
+- [ ] `AND_SALT[1]` behaves like `AND_SALT_WIDE` (broad)
+- [ ] `AND_SALT_BLOB[5]` produces a visible blob region
+- [ ] `AND_ALIGN[4,8]` and `AND_ALIGN_4_8` produce identical results
+- [ ] Prompt with only `AND_SALT ...` (no base) falls back to standard CFG with a warning in console (enable verbose in Settings)
+
+---
+
+## Matryoshka / Nested prompt composition
+
+The extension supports arbitrary nesting of `AND_*` blocks. An outer block
+focuses or restricts a spatial/semantic region; inner blocks operate _inside_
+that region:
+
+```text
+base subject
+AND_SALT[5] [
+  region texture :0.8
+  AND_TOPK[0.05] fine highlights :0.4
+] :0.7
+```
+
+This is called a **matryoshka** structure — like nested dolls, each layer adds
+a more focused effect.
+
+### Basic nesting syntax
+
+```text
+base
+KEYWORD [
+  inner text :weight
+  INNER_KEYWORD inner concept :weight
+] :weight
+```
+
+The outer `[ ... ]` bracket is a **composite group**, not a parameter block.
+It is parsed as such only if the content contains letters (not purely numeric).
+
+### Nesting with params
+
+Params go directly after the keyword, _before_ the composite bracket:
+
+```text
+AND_SALT[5] [          ← k=5 applied, then [ opens composite group
+  texture :0.8
+  AND_TOPK[0.1] detail :0.5
+] :0.7
+```
+
+### Nesting with affine
+
+Affine transforms can precede the keyword at any level:
+
+```text
+SCALE[-1,1] AND_PERP [   ← mirror then perpendicular
+  mirrored concept :0.6
+] :0.5
+```
+
+### How the parser distinguishes params vs composite
+
+| Content inside `[...]` | Treated as |
+|---|---|
+| Purely numeric: `[5]`, `[4,8]`, `[ 0.1 ]` | **Params** for the preceding keyword |
+| Contains letters / spaces + letters | **Composite group** |
+
+So `AND_SALT[5]` → params; `AND_SALT [concept AND other]` → composite.
+
+### Protection with nested prompts
+
+The base-prompt protection guard checks for a **plain base segment at the
+top level** of the prompt. A nested structure like:
+
+```text
+AND_SALT[5] [ ... ] :0.8
+```
+
+has _no_ top-level base, so `auto` and `strict` protection will fire.
+To suppress this intentionally, set protection to `off`.
+
+### Common mistakes
+
+**Forgetting the base prompt**
+```text
+# ❌ triggers protection fallback
+AND_SALT[5] concept :0.8
+
+# ✓
+base subject
+AND_SALT[5] concept :0.8
+```
+
+**Using numeric composite brackets as params**
+```text
+# This is parsed as a composite group, NOT as k=5:
+AND_SALT [5]     ← space before bracket → composite group with text "5"
+AND_SALT[5]      ← no space → params (k=5) ✓
+```
+
+**Zero or out-of-range params**
+```text
+AND_SALT[0]      ← invalid k, silently uses defaults
+AND_ALIGN[4,4]   ← D must differ from S, silently uses defaults
+AND_TOPK[1.5]    ← threshold must be in (0,1], silently uses defaults
+```
+Enable verbose mode in A1111 Settings → Neutral Prompt to see warnings.
+
+---
+
+## Matryoshka builder (UI)
+
+Open the **Matryoshka builder** accordion to compose nested prompts visually:
+
+1. Enter the base prompt text.
+2. Choose a strategy for Child 1, enter its text and weight.
+3. Optionally enable a nested child _inside_ Child 1.
+4. Optionally add a second top-level child.
+5. The **Generated prompt (preview)** updates live.
+6. Click **Apply to prompt** to insert into the main prompt box.
+
+### Ready-made templates
+
+The **Matryoshka templates** accordion contains 7 ready-made recipes:
+
+| Template | What it does |
+|---|---|
+| Nested local detail | SALT region → nested TOPK fine detail |
+| Structure preserve + style inject | ALIGN preserves structure → nested PERP reduces contradiction |
+| Sparse detail inside broad region | SALT_WIDE broad → nested SALT focal sharpening |
+| Perpendicular correction inside texture | SALT texture → nested PERP suppresses contradiction |
+| Nested ALIGN + SALT | ALIGN structure → SALT foreground → nested TOPK highlights |
+| Mirrored composition | Mirrored PERP via SCALE[-1,1] |
+| Deep nested concept isolation | SALT → ALIGN → TOPK (3 levels) |
+
+---
+
+## Prompt debug / explain panel
+
+Open the **Prompt debug / explain** accordion to inspect any prompt.
+
+The panel shows:
+
+```
+ROOT  (N top-level segments)
+├─ [BASE] w=1.00  "base subject"
+└─ [SALIENCE_MASK] w=0.80  [k=5.0]  (2 children)
+   ├─ [BASE] w=0.80  "texture"
+   └─ [SEMANTIC_GUIDANCE] w=0.40  [threshold=0.05]  "highlights"
+
+── Diagnostics ──────────────────────────
+Segments total : 4  (leaf=3, composite=1)
+Max nesting depth : 2
+Affine transforms : 0
+Strategies used   : BASE, SALIENCE_MASK, SEMANTIC_GUIDANCE
+
+Protection mode : auto
+  OK — base segment present at top level
+
+── Effect summary ────────────────────────
+  BASE                             →  base prompt contribution — drives the overall image
+  SALIENCE_MASK                    →  sharp saliency mask — targets the most salient latent pixels
+  SEMANTIC_GUIDANCE                →  semantic top-k — applies sparse targeted changes to the strongest elements
+```
+
+### What the debug panel does NOT simulate
+
+- **Strict ratio check**: whether `norm(base_delta) / norm(aux_delta)` would fall
+  below the threshold is only knowable at generation time with real latents.
+- **Batch/mixed-prompt cases**: the panel parses a single prompt string; it does
+  not simulate multi-prompt batch protection.
+- **Hook conflicts**: whether another A1111 extension has overridden the hijack
+  chain is a runtime condition.
+
+The protection verdict shown is a **structural preview** — a fast heuristic
+to catch the most common mistake (missing base segment) before you start
+generating.
+
+---
+
+## Affine transform builder (UI)
+
+Open the **Affine transform builder** accordion to compose affine snippets:
+
+1. Pick a preset (Mirror H/V, Rotate 45°/90°/180°, Zoom, Stretch, etc.)
+   or select **Custom** and set parameters manually.
+2. The **Affine snippet** box updates live.
+3. Click **Insert affine into prompt** to append the snippet.
+
+Snippets can be placed before a keyword (`ROTATE[0.125] AND_PERP ...`) or
+as a standalone transform (`SCALE[-1,1] AND_SALT[5] ...`).
+
+### Safe ranges
+
+| Transform | Notes |
+|---|---|
+| `ROTATE[angle]` | Angle in turns. `0.25` = 90°, `0.5` = 180° |
+| `SCALE[x,y]` | Both components must be non-zero (avoids singular matrix) |
+| `SLIDE[x,y]` | Translation fraction of latent space |
+| `SHEAR[x,y]` | Angles near ±0.25 turns diverge — avoided automatically |
+| `FLIP_H` | Shortcut for `SCALE[-1,1]` |
+| `FLIP_V` | Shortcut for `SCALE[1,-1]` |

neutral_prompt_patcheds/lib_neutral_prompt/__init__.py

@@ -0,0 +1 @@
+# lib_neutral_prompt package

neutral_prompt_patcheds/lib_neutral_prompt/affine_transform.py

@@ -0,0 +1,83 @@
+"""
+Affine spatial transform utilities for latent tensors.
+Extracted from the `affine` branch so that cfg_denoiser_hijack can stay lean.
+
+Provides:
+  apply_affine_transform()        – apply a 2×3 affine grid to a C×H×W tensor
+  apply_masked_transform()        – apply affine + cosine-feathered mask blending
+  create_cosine_feathered_mask()  – smooth circular weight mask
+"""
+
+from typing import Tuple
+
+import torch
+import torch.nn.functional as F
+
+
+def apply_affine_transform(
+    tensor: torch.Tensor,
+    affine: torch.Tensor,
+    mode: str = 'bilinear',
+) -> torch.Tensor:
+    """
+    Apply a 2×3 affine transform to a C×H×W tensor, preserving aspect ratio.
+
+    :param tensor: Input tensor of shape [C, H, W].
+    :param affine: 2×3 float32 affine matrix.
+    :param mode: Interpolation mode for grid_sample ('bilinear' default).
+                 The original affine branch used bilinear for the pre-noise
+                 inverse path (smoother) and nearest for post-combine.
+                 Bilinear is the better default for both.
+    :return: Transformed tensor of shape [C, H, W].
+    """
+    affine = affine.clone().to(tensor.device)
+    aspect_ratio = tensor.shape[-2] / tensor.shape[-1]
+    affine[0, 1] *= aspect_ratio
+    affine[1, 0] /= aspect_ratio
+
+    grid = F.affine_grid(affine.unsqueeze(0), tensor.unsqueeze(0).size(), align_corners=False)
+    return F.grid_sample(tensor.unsqueeze(0), grid, mode=mode, align_corners=False).squeeze(0)
+
+
+def apply_masked_transform(
+    tensor: torch.Tensor,
+    affine: torch.Tensor,
+    weight: float,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    Apply an affine transform with a cosine-feathered spatial weight mask.
+
+    The mask channel is appended to the tensor before transformation so that
+    the same spatial warp is applied to both content and mask consistently.
+
+    :param tensor: C×H×W latent tensor.
+    :param affine: 2×3 affine matrix.
+    :param weight: Global scalar weight for the mask.
+    :return: (transformed_content [C, H, W], transformed_mask [H, W])
+    """
+    mask = create_cosine_feathered_mask(tensor.shape[-2:], weight).unsqueeze(0).to(tensor.device)
+    tensor_with_mask = torch.cat([tensor, mask], dim=0)          # [C+1, H, W]
+    transformed = apply_affine_transform(tensor_with_mask, affine)
+    return transformed[:-1], transformed[-1]                      # content, mask
+
+
+def create_cosine_feathered_mask(size: Tuple[int, int], weight: float) -> torch.Tensor:
+    """
+    Create a circularly-clipped cosine-feathered mask of shape [H, W].
+
+    Values at the centre approach `weight`; values outside the unit circle
+    are exactly 0, with a smooth cosine fall-off in between.
+
+    :param size: (H, W) tuple.
+    :param weight: Peak mask value at the centre.
+    :return: Float32 mask tensor of shape [H, W].
+    """
+    y, x = torch.meshgrid(
+        torch.linspace(-1, 1, size[0]),
+        torch.linspace(-1, 1, size[1]),
+        indexing='ij',
+    )
+    dist = torch.sqrt(x ** 2 + y ** 2)
+    mask = 0.5 * (1.0 + torch.cos(torch.pi * dist))
+    mask[dist > 1] = 0.0
+    return mask.float() * weight

neutral_prompt_patcheds/lib_neutral_prompt/affine_utils.py

@@ -0,0 +1,220 @@
+"""
+Affine transform subsystem for sd-webui-neutral-prompt.
+
+Single source of truth for:
+  - Matrix constructors: _make_rotate / _make_slide / _make_scale / _make_shear
+  - Application:         _apply_affine
+  - Safe inversion:      _try_invert_affine
+  - Parser dispatch:     affine_transforms (keyword → callable)
+  - UI helpers:          _build_affine_snippet / _AFFINE_TRANSFORMS / _AFFINE_PRESETS
+
+Previously scattered across neutral_prompt_parser.py, cfg_denoiser_hijack.py,
+and matryoshka_utils.py.  Import from here everywhere.
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from typing import Dict, Optional, Tuple
+
+import torch
+
+
+# ---------------------------------------------------------------------------
+# Warning helper
+# ---------------------------------------------------------------------------
+
+def affine_warn(keyword: str, reason: str) -> None:
+    """Print a one-line warning to stderr (respects global_state.verbose)."""
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        if not _gs.verbose:
+            return
+    except ImportError:
+        pass
+    print(
+        f'[neutral-prompt] WARNING: invalid affine params for {keyword} — {reason}. '
+        'Transform ignored; using identity.',
+        file=sys.stderr,
+    )
+
+# Keep old private name as alias (parser uses it)
+_affine_warn = affine_warn
+
+
+# ---------------------------------------------------------------------------
+# Matrix constructors
+# ---------------------------------------------------------------------------
+
+def make_rotate(angle: float) -> Optional[torch.Tensor]:
+    """Rotation matrix. *angle* is in turns (0.25 = 90°)."""
+    if not math.isfinite(angle):
+        affine_warn('ROTATE', f'non-finite angle {angle}')
+        return None
+    a = angle * 2 * math.pi
+    return torch.tensor([
+        [math.cos(a), -math.sin(a), 0],
+        [math.sin(a),  math.cos(a), 0],
+        [0, 0, 1],
+    ], dtype=torch.float32)
+
+
+def make_slide(x: float, y: float) -> Optional[torch.Tensor]:
+    """Translation matrix."""
+    if not math.isfinite(x) or not math.isfinite(y):
+        affine_warn('SLIDE', f'non-finite offset ({x}, {y})')
+        return None
+    return torch.tensor([
+        [1, 0, float(x)],
+        [0, 1, float(y)],
+        [0, 0, 1],
+    ], dtype=torch.float32)
+
+
+def make_scale(x: float, y: Optional[float] = None) -> Optional[torch.Tensor]:
+    """Uniform or anisotropic scale matrix.  Both components must be non-zero."""
+    sy = y if y is not None else x
+    if not math.isfinite(x) or not math.isfinite(sy):
+        affine_warn('SCALE', f'non-finite scale ({x}, {sy})')
+        return None
+    if abs(x) < 1e-6 or abs(sy) < 1e-6:
+        affine_warn('SCALE', f'scale component too close to zero ({x}, {sy}); '
+                              'matrix would be singular')
+        return None
+    return torch.tensor([
+        [float(x), 0,        0],
+        [0,        float(sy), 0],
+        [0,        0,        1],
+    ], dtype=torch.float32)
+
+
+def make_shear(x: float, y: Optional[float] = None) -> Optional[torch.Tensor]:
+    """Shear matrix.  Angles near ±0.25 turns are rejected (tan diverges)."""
+    sy = y if y is not None else x
+    if not math.isfinite(x) or not math.isfinite(sy):
+        affine_warn('SHEAR', f'non-finite shear ({x}, {sy})')
+        return None
+    _SHEAR_MAX = 0.24
+    if abs(x) >= _SHEAR_MAX or abs(sy) >= _SHEAR_MAX:
+        affine_warn('SHEAR', f'shear angle ({x}, {sy}) too close to ±0.25 turns; '
+                              'tan diverges and matrix would be degenerate')
+        return None
+    tx = math.tan(float(x)  * 2 * math.pi)
+    ty = math.tan(float(sy) * 2 * math.pi)
+    if not math.isfinite(tx) or not math.isfinite(ty):
+        affine_warn('SHEAR', f'tan({x}, {sy}) produced non-finite value')
+        return None
+    return torch.tensor([
+        [1,  tx, 0],
+        [ty, 1,  0],
+        [0,  0,  1],
+    ], dtype=torch.float32)
+
+
+# Keep old private names (parser uses them)
+_make_rotate = make_rotate
+_make_slide  = make_slide
+_make_scale  = make_scale
+_make_shear  = make_shear
+
+
+# ---------------------------------------------------------------------------
+# Application helper
+# ---------------------------------------------------------------------------
+
+def apply_affine(t: torch.Tensor, m: Optional[torch.Tensor]) -> torch.Tensor:
+    """Apply matrix *m* to running transform *t*; if *m* is None return *t* unchanged."""
+    return t if m is None else t @ m
+
+_apply_affine = apply_affine   # alias for parser
+
+
+# ---------------------------------------------------------------------------
+# Parser dispatch table
+# ---------------------------------------------------------------------------
+
+affine_transforms: Dict[str, object] = {
+    'ROTATE': lambda t, angle=0,    *_: apply_affine(t, make_rotate(float(angle))),
+    'SLIDE':  lambda t, x=0, y=0,   *_: apply_affine(t, make_slide(float(x), float(y))),
+    'SCALE':  lambda t, x=1, y=None, *_: apply_affine(
+        t, make_scale(float(x), float(y) if y is not None else None)),
+    'SHEAR':  lambda t, x=0, y=None, *_: apply_affine(
+        t, make_shear(float(x), float(y) if y is not None else None)),
+}
+
+
+# ---------------------------------------------------------------------------
+# Safe matrix inversion  (runtime, used by cfg_denoiser_hijack)
+# ---------------------------------------------------------------------------
+
+def try_invert_affine(
+    m3: torch.Tensor,
+    context: str = 'affine transform',
+) -> torch.Tensor:
+    """
+    Safely invert a 3×3 homogeneous affine matrix.
+
+    On any error (singular, NaN) logs a warning (verbose only) and returns
+    the 3×3 identity so the pipeline degrades gracefully instead of crashing.
+    """
+    try:
+        result = torch.linalg.inv(m3)
+        if not torch.isfinite(result).all():
+            raise ValueError('non-finite values in inverted matrix')
+        return result
+    except Exception as exc:
+        try:
+            from lib_neutral_prompt import global_state as _gs
+            verbose = _gs.verbose
+        except ImportError:
+            verbose = True
+        if verbose:
+            print(
+                f'[neutral-prompt] WARNING: could not invert {context}: {exc}. '
+                'Falling back to identity (no affine transform applied).',
+                file=sys.stderr,
+            )
+        return torch.eye(3, device=m3.device, dtype=m3.dtype)
+
+_try_invert_affine = try_invert_affine   # alias
+
+
+# ---------------------------------------------------------------------------
+# UI helpers (snippet builder + preset library)
+# ---------------------------------------------------------------------------
+
+AFFINE_TRANSFORMS = ['ROTATE', 'SCALE', 'SLIDE', 'SHEAR', 'FLIP_H', 'FLIP_V']
+
+AFFINE_PRESETS: Dict[str, Optional[Tuple]] = {
+    'Custom':        None,
+    'Mirror H':      ('SCALE', -1.0,  1.0),
+    'Mirror V':      ('SCALE',  1.0, -1.0),
+    'Rotate 45°':    ('ROTATE', 0.125, None),
+    'Rotate 90°':    ('ROTATE', 0.25,  None),
+    'Rotate 180°':   ('ROTATE', 0.5,   None),
+    'Zoom out 50%':  ('SCALE',  0.5,   0.5),
+    'Zoom in 150%':  ('SCALE',  1.5,   1.5),
+    'Stretch X':     ('SCALE',  1.5,   1.0),
+    'Stretch Y':     ('SCALE',  1.0,   1.5),
+    'Slight rotate': ('ROTATE', 0.05,  None),
+    'Slide right':   ('SLIDE',  0.1,   0.0),
+    'Slide down':    ('SLIDE',  0.0,   0.1),
+}
+
+
+def build_affine_snippet(transform: str, p1: float, p2: float) -> str:
+    """Convert UI control values to a single ``TRANSFORM[args]`` token."""
+    t = transform.strip()
+    if t == 'FLIP_H':  return 'SCALE[-1,1]'
+    if t == 'FLIP_V':  return 'SCALE[1,-1]'
+    if t == 'ROTATE':  return f'ROTATE[{p1}]'
+    if t == 'SCALE':
+        return f'SCALE[{p1},{p2}]' if abs(p1 - p2) > 1e-9 else f'SCALE[{p1}]'
+    if t == 'SLIDE':   return f'SLIDE[{p1},{p2}]'
+    if t == 'SHEAR':
+        return f'SHEAR[{p1},{p2}]' if abs(p1 - p2) > 1e-9 else f'SHEAR[{p1}]'
+    return ''
+
+# Old private alias (matryoshka_utils re-exports from here)
+_build_affine_snippet = build_affine_snippet

neutral_prompt_patcheds/lib_neutral_prompt/cfg_denoiser_hijack.py

@@ -0,0 +1,726 @@
+"""
+Unified CFG Denoiser Hijack
+===========================
+Combines features from all sd-webui-neutral-prompt branches:
+
+  • Core PERP / SALT / TOPK strategies            (main branch)
+  • cfg_rescale with mean-preserving formula       (main branch)
+  • cfg_rescale_override (XYZ-grid / API support)  (main branch)
+  • CFGRescaleFactorSingleton export               (export_rescale_factor branch)
+  • Affine spatial transforms per-prompt           (affine branch)
+  • AND_ALIGN_D_S  – soft alignment blend          (alignment_blend branch)
+  • AND_MASK_ALIGN_D_S – binary alignment mask     (alignment_mask branch)
+  • Improved salience with sharpness parameter k   (life branch)
+
+Changes vs original ultimate:
+  • AND_SALT / AND_SALT_WIDE / AND_SALT_BLOB: k read from conciliation_params
+    (default 5 / 1 / 5 — tuned to actually be visible)
+  • AND_SALT_BLOB: erode/thickify order fixed (thickify first, then erode)
+  • AND_ALIGN[D,S] / AND_MASK_ALIGN[D,S]: bracket-syntax routed via
+    ALIGNMENT_BLEND_CUSTOM / ALIGNMENT_MASK_BLEND_CUSTOM
+  • Guard against "no base prompt" → cond_delta=0 replacement bug
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import re
+import sys
+import textwrap
+from typing import Dict, List, Tuple
+
+import torch
+import torch.nn.functional as F
+
+from lib_neutral_prompt import affine_transform as affine_mod
+from lib_neutral_prompt import global_state, hijacker, neutral_prompt_parser
+from modules import script_callbacks, sd_samplers, shared
+
+
+# ---------------------------------------------------------------------------
+# Pre-noise affine hook  (affine branch)
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class _PreNoiseArgs:
+    x: torch.Tensor
+    cond_indices: List[Tuple[int, float]]
+
+
+class _GlobalToLocalAffineVisitor:
+    def visit_leaf_prompt(
+        self,
+        that: neutral_prompt_parser.LeafPrompt,
+        args: _PreNoiseArgs,
+        index: int,
+    ) -> Dict[int, torch.Tensor]:
+        cond_index = args.cond_indices[index][0]
+        if that.local_transform is not None:
+            m3 = torch.vstack([that.local_transform,
+                               torch.tensor([0.0, 0.0, 1.0])])
+            inv = _try_invert_affine(m3, 'leaf local_transform')[:-1]
+        else:
+            inv = torch.eye(3)[:-1]
+        return {cond_index: inv}
+
+    def visit_composite_prompt(
+        self,
+        that: neutral_prompt_parser.CompositePrompt,
+        args: _PreNoiseArgs,
+        index: int,
+    ) -> Dict[int, torch.Tensor]:
+        inv_transforms: Dict[int, torch.Tensor] = {}
+
+        for child in that.children:
+            inv_transforms.update(child.accept(_GlobalToLocalAffineVisitor(), args, index))
+            index += child.accept(neutral_prompt_parser.FlatSizeVisitor())
+
+        if that.local_transform is not None:
+            m3 = torch.vstack([that.local_transform,
+                               torch.tensor([0.0, 0.0, 1.0])])
+            parent_inv = _try_invert_affine(m3, 'composite parent local_transform')
+            for inv in inv_transforms.values():
+                inv3 = torch.vstack([inv, torch.tensor([0.0, 0.0, 1.0])])
+                inv[:] = (parent_inv @ inv3)[:-1]
+
+        return inv_transforms
+
+
+def _on_cfg_denoiser(params: script_callbacks.CFGDenoiserParams) -> None:
+    if not global_state.is_enabled:
+        return
+    if not _batch_is_compatible(global_state.prompt_exprs, global_state.batch_cond_indices):
+        return
+
+    for prompt, cond_indices in zip(global_state.prompt_exprs,
+                                    global_state.batch_cond_indices):
+        args = _PreNoiseArgs(params.x, cond_indices)
+        inv_transforms = prompt.accept(_GlobalToLocalAffineVisitor(), args, 0)
+        for cond_index, _ in cond_indices:
+            params.x[cond_index] = affine_mod.apply_affine_transform(
+                params.x[cond_index], inv_transforms[cond_index]
+            )
+
+
+script_callbacks.on_cfg_denoiser(_on_cfg_denoiser)
+
+
+def _flat_size(prompt: neutral_prompt_parser.PromptExpr) -> int:
+    return prompt.accept(neutral_prompt_parser.FlatSizeVisitor())
+
+
+def _batch_is_compatible(
+    prompts: List[neutral_prompt_parser.PromptExpr],
+    batch_cond_indices: List[List[Tuple[int, float]]],
+) -> bool:
+    if len(prompts) != len(batch_cond_indices):
+        _console_warn(f'''
+            Neutral Prompt batch mismatch:
+            prompt_exprs={len(prompts)} vs batch_cond_indices={len(batch_cond_indices)}
+            Falling back to original A1111 behavior for this step.
+        ''')
+        return False
+
+    for i, (prompt, cond_indices) in enumerate(zip(prompts, batch_cond_indices)):
+        need = _flat_size(prompt)
+        got = len(cond_indices)
+        if need != got:
+            _console_warn(f'''
+                Neutral Prompt branch mismatch at prompt #{i}:
+                expected {need} branches, got {got}
+                Falling back to original A1111 behavior for this step.
+            ''')
+            return False
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def combine_denoised_hijack(
+    x_out: torch.Tensor,
+    batch_cond_indices: List[List[Tuple[int, float]]],
+    text_uncond: torch.Tensor,
+    cond_scale: float,
+    original_function,
+) -> torch.Tensor:
+    if not global_state.is_enabled:
+        return original_function(x_out, batch_cond_indices, text_uncond, cond_scale)
+
+    if not _batch_is_compatible(global_state.prompt_exprs, batch_cond_indices):
+        return original_function(x_out, batch_cond_indices, text_uncond, cond_scale)
+
+    # ------------------------------------------------------------------
+    # Update step counters for step-window gating (runs before any gating check)
+    # shared.state.sampling_step / sampling_steps are set by A1111 per denoiser call
+    # ------------------------------------------------------------------
+    try:
+        global_state.update_step_state(
+            shared.state.sampling_step,
+            shared.state.sampling_steps,
+        )
+    except Exception:
+        pass   # sampling_step may not be set during warmup; keep previous values
+    # NOTE: Lock-after-End flags are reset in NeutralPromptScript.process(),
+    # not here.  Resetting on step==0 would incorrectly re-arm locks inside
+    # samplers that revisit step 0 (Restart, DPM++ multi-pass, hires fix).
+
+    # ------------------------------------------------------------------
+    # Base-prompt protection  (Off / Auto / Strict / Soft)
+    # ------------------------------------------------------------------
+    should_fallback, reason = _should_fallback_for_protection(
+        x_out, batch_cond_indices, text_uncond
+    )
+    if should_fallback:
+        _console_warn(f'\n    [base-prompt protection] {reason}\n    Falling back to standard CFG.')
+        return original_function(x_out, batch_cond_indices, text_uncond, cond_scale)
+    # ------------------------------------------------------------------
+
+    denoised = _get_webui_denoised(x_out, batch_cond_indices, text_uncond, cond_scale, original_function)
+    uncond = x_out[-text_uncond.shape[0]:]
+
+    for batch_i, (prompt, cond_indices) in enumerate(zip(global_state.prompt_exprs, batch_cond_indices)):
+        args = _DenoiseArgs(x_out, uncond[batch_i], cond_indices)
+        cond_delta = prompt.accept(_CondDeltaVisitor(), args, 0)
+        aux_cond_delta = prompt.accept(_AuxCondDeltaVisitor(), args, cond_delta, 0)
+
+        # --- Soft mode: attenuate auxiliary if base is too weak ---
+        aux_cond_delta, _ = apply_soft_attenuation_if_needed(
+            aux_cond_delta, cond_delta, batch_i
+        )
+
+        if prompt.local_transform is not None:
+            cond_delta = affine_mod.apply_affine_transform(cond_delta, prompt.local_transform)
+            aux_cond_delta = affine_mod.apply_affine_transform(aux_cond_delta, prompt.local_transform)
+
+        cfg_cond = denoised[batch_i] + aux_cond_delta * cond_scale
+        denoised[batch_i] = _cfg_rescale(cfg_cond, uncond[batch_i] + cond_delta + aux_cond_delta)
+
+    return denoised
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _get_webui_denoised(
+    x_out: torch.Tensor,
+    batch_cond_indices: List[List[Tuple[int, float]]],
+    text_uncond: torch.Tensor,
+    cond_scale: float,
+    original_function,
+) -> torch.Tensor:
+    uncond = x_out[-text_uncond.shape[0]:]
+    sliced_batch_x_out: List[torch.Tensor] = []
+    sliced_batch_cond_indices: List[List[Tuple[int, float]]] = []
+
+    for batch_i, (prompt, cond_indices) in enumerate(zip(global_state.prompt_exprs, batch_cond_indices)):
+        args = _DenoiseArgs(x_out, uncond[batch_i], cond_indices)
+        sliced_x_out, sliced_indices = _gather_webui_conds(prompt, args, 0, len(sliced_batch_x_out))
+        if sliced_indices:
+            sliced_batch_cond_indices.append(sliced_indices)
+        sliced_batch_x_out.extend(sliced_x_out)
+
+    sliced_batch_x_out += list(uncond)
+    return original_function(
+        torch.stack(sliced_batch_x_out, dim=0),
+        sliced_batch_cond_indices,
+        text_uncond,
+        cond_scale,
+    )
+
+
+def _cfg_rescale(cfg_cond: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+    """Mean-preserving CFG rescale."""
+    global_state.CFGRescaleFactorSingleton.clear()
+    global_state.apply_and_clear_cfg_rescale_override()
+
+    if global_state.cfg_rescale == 0:
+        return cfg_cond
+
+    cfg_std = cfg_cond.std()
+    if cfg_std == 0:
+        return cfg_cond
+
+    cfg_cond_mean = cfg_cond.mean()
+    rescale_mean = (
+        (1 - global_state.cfg_rescale) * cfg_cond_mean
+        + global_state.cfg_rescale * cond.mean()
+    )
+    rescale_factor = global_state.cfg_rescale * (cond.std() / cfg_std - 1) + 1
+
+    global_state.CFGRescaleFactorSingleton.set(
+        rescale_factor.item() if isinstance(rescale_factor, torch.Tensor) else float(rescale_factor)
+    )
+
+    return rescale_mean + (cfg_cond - cfg_cond_mean) * rescale_factor
+
+
+@dataclasses.dataclass
+class _DenoiseArgs:
+    x_out: torch.Tensor
+    uncond: torch.Tensor
+    cond_indices: List[Tuple[int, float]]
+
+
+def _gather_webui_conds(
+    prompt: neutral_prompt_parser.CompositePrompt,
+    args: _DenoiseArgs,
+    index_in: int,
+    index_out: int,
+) -> Tuple[List[torch.Tensor], List[Tuple[int, float]]]:
+    sliced_x_out: List[torch.Tensor] = []
+    sliced_cond_indices: List[Tuple[int, float]] = []
+
+    for child in prompt.children:
+        if child.conciliation is None:
+            if isinstance(child, neutral_prompt_parser.LeafPrompt) and child.local_transform is None:
+                child_x_out = args.x_out[args.cond_indices[index_in][0]]
+                child_weight = child.weight
+            else:
+                child_x_out, child_weight = _get_cond_delta_and_weight(child, args, index_in)
+                child_x_out = child_x_out + args.uncond
+
+            index_offset = index_out + len(sliced_x_out)
+            sliced_x_out.append(child_x_out)
+            sliced_cond_indices.append((index_offset, child_weight))
+
+        index_in += child.accept(neutral_prompt_parser.FlatSizeVisitor())
+
+    return sliced_x_out, sliced_cond_indices
+
+
+def _get_cond_delta_and_weight(
+    prompt: neutral_prompt_parser.PromptExpr,
+    args: _DenoiseArgs,
+    index: int,
+) -> Tuple[torch.Tensor, float]:
+    cond_delta = prompt.accept(_CondDeltaVisitor(), args, index)
+    cond_delta = cond_delta + prompt.accept(_AuxCondDeltaVisitor(), args, cond_delta, index)
+    weight = prompt.weight
+
+    if prompt.local_transform is not None:
+        transformed, weight_tensor = affine_mod.apply_masked_transform(
+            cond_delta + args.uncond,
+            prompt.local_transform,
+            prompt.weight,
+        )
+        cond_delta = transformed - args.uncond
+        weight = weight_tensor
+
+    return cond_delta, weight
+
+
+# ---------------------------------------------------------------------------
+# Visitor: CondDelta
+# ---------------------------------------------------------------------------
+
+class _CondDeltaVisitor:
+    def visit_leaf_prompt(
+        self,
+        that: neutral_prompt_parser.LeafPrompt,
+        args: _DenoiseArgs,
+        index: int,
+    ) -> torch.Tensor:
+        cond_info = args.cond_indices[index]
+        if that.weight != cond_info[1]:
+            _console_warn(f'''
+                Unexpected noise weight at prompt #{index}
+                Expected :{that.weight}, got :{cond_info[1]}
+            ''')
+        return args.x_out[cond_info[0]] - args.uncond
+
+    def visit_composite_prompt(
+        self,
+        that: neutral_prompt_parser.CompositePrompt,
+        args: _DenoiseArgs,
+        index: int,
+    ) -> torch.Tensor:
+        cond_delta = torch.zeros_like(args.x_out[0])
+        for child in that.children:
+            if child.conciliation is None:
+                child_delta, child_weight = _get_cond_delta_and_weight(child, args, index)
+                cond_delta = cond_delta + child_weight * child_delta
+            index += child.accept(neutral_prompt_parser.FlatSizeVisitor())
+        return cond_delta
+
+
+# ---------------------------------------------------------------------------
+# Visitor: AuxCondDelta — all conciliation strategies
+# ---------------------------------------------------------------------------
+
+class _AuxCondDeltaVisitor:
+    def visit_leaf_prompt(
+        self,
+        that: neutral_prompt_parser.LeafPrompt,
+        args: _DenoiseArgs,
+        cond_delta: torch.Tensor,
+        index: int,
+    ) -> torch.Tensor:
+        return torch.zeros_like(args.x_out[0])
+
+    def visit_composite_prompt(
+        self,
+        that: neutral_prompt_parser.CompositePrompt,
+        args: _DenoiseArgs,
+        cond_delta: torch.Tensor,
+        index: int,
+    ) -> torch.Tensor:
+        aux_cond_delta = torch.zeros_like(args.x_out[0])
+
+        # Each salience list entry: (delta, weight, k)
+        salient_cond_deltas: List[Tuple[torch.Tensor, float, float]] = []
+        salient_wide_deltas: List[Tuple[torch.Tensor, float, float]] = []
+        salient_blob_deltas: List[Tuple[torch.Tensor, float, float]] = []
+        align_blend_deltas: List[Tuple[torch.Tensor, float, int, int]] = []
+        mask_align_deltas: List[Tuple[torch.Tensor, float, int, int]] = []
+
+        CS = neutral_prompt_parser.ConciliationStrategy
+
+        # Step-window gating: compute normalised progress once per composite visit
+        if global_state.step_window_enabled:
+            from lib_neutral_prompt.step_utils import (
+                strategy_is_active_from_state, normalize_progress,
+            )
+            progress = normalize_progress(global_state.current_step, global_state.total_steps)
+        else:
+            progress = None
+
+        for child in that.children:
+            if child.conciliation is not None:
+                # --- Step-window gate ---
+                if progress is not None:
+                    strat_name = child.conciliation.name
+                    if not strategy_is_active_from_state(strat_name, progress):
+                        index += child.accept(neutral_prompt_parser.FlatSizeVisitor())
+                        continue
+
+                child_delta, child_weight = _get_cond_delta_and_weight(child, args, index)
+                strat = child.conciliation
+                cp = child.conciliation_params  # per-child params dict
+
+                if strat == CS.PERPENDICULAR:
+                    aux_cond_delta = aux_cond_delta + child_weight * _get_perpendicular_component(cond_delta, child_delta)
+
+                elif strat == CS.SALIENCE_MASK:
+                    # Default k=5: noticeably more coverage than original k=20.
+                    # User can override via AND_SALT[k].
+                    k = float(cp.get('k', 5.0))
+                    salient_cond_deltas.append((child_delta, child_weight, k))
+
+                elif strat == CS.SALIENCE_MASK_WIDE:
+                    k = float(cp.get('k', 1.0))
+                    salient_wide_deltas.append((child_delta, child_weight, k))
+
+                elif strat == CS.SALIENCE_MASK_BLOB:
+                    k = float(cp.get('k', 5.0))
+                    salient_blob_deltas.append((child_delta, child_weight, k))
+
+                elif strat == CS.SEMANTIC_GUIDANCE:
+                    threshold = float(cp.get('threshold', 0.05))
+                    aux_cond_delta = aux_cond_delta + child_weight * _filter_abs_top_k(child_delta, threshold)
+
+                elif strat == CS.ALIGNMENT_BLEND_CUSTOM:
+                    # AND_ALIGN[D,S] — any user-specified pair
+                    d = int(cp.get('d', 4))
+                    s = int(cp.get('s', 8))
+                    if 2 <= d <= 32 and 2 <= s <= 32 and d != s:
+                        align_blend_deltas.append((child_delta, child_weight, d, s))
+
+                elif strat == CS.ALIGNMENT_MASK_BLEND_CUSTOM:
+                    # AND_MASK_ALIGN[D,S]
+                    d = int(cp.get('d', 4))
+                    s = int(cp.get('s', 8))
+                    if 2 <= d <= 32 and 2 <= s <= 32 and d != s:
+                        mask_align_deltas.append((child_delta, child_weight, d, s))
+
+                else:
+                    # Fixed-suffix AND_ALIGN_D_S (backward-compat)
+                    m = re.match(r'AND_ALIGN_(\d+)_(\d+)', strat.value)
+                    if m:
+                        align_blend_deltas.append((child_delta, child_weight, int(m.group(1)), int(m.group(2))))
+                    else:
+                        m = re.match(r'AND_MASK_ALIGN_(\d+)_(\d+)', strat.value)
+                        if m:
+                            mask_align_deltas.append((child_delta, child_weight, int(m.group(1)), int(m.group(2))))
+
+            index += child.accept(neutral_prompt_parser.FlatSizeVisitor())
+
+        aux_cond_delta = aux_cond_delta + _salient_blend(cond_delta, salient_cond_deltas)
+        aux_cond_delta = aux_cond_delta + _salient_blend(cond_delta, salient_wide_deltas)
+        aux_cond_delta = aux_cond_delta + _salient_blend_blob(cond_delta, salient_blob_deltas)
+        aux_cond_delta = aux_cond_delta + _alignment_blend(cond_delta, align_blend_deltas)
+        aux_cond_delta = aux_cond_delta + _alignment_mask_blend(cond_delta, mask_align_deltas)
+        return aux_cond_delta
+
+
+# ---------------------------------------------------------------------------
+# Strategy implementations
+# ---------------------------------------------------------------------------
+
+def _get_perpendicular_component(normal: torch.Tensor, vector: torch.Tensor) -> torch.Tensor:
+    if (normal == 0).all():
+        if shared.state.sampling_step <= 0:
+            _warn_projection_not_found()
+        return vector
+    return vector - normal * torch.sum(normal * vector) / torch.norm(normal) ** 2
+
+
+def _salient_blend(
+    normal: torch.Tensor,
+    vectors: List[Tuple[torch.Tensor, float, float]],
+) -> torch.Tensor:
+    """
+    Saliency-guided blend.  Each entry: (delta, weight, k).
+
+    k controls child mask sharpness:
+      k=1   → broad (~55% of pixels)  — AND_SALT_WIDE default
+      k=5   → moderate (~5-10%)       — AND_SALT default (was 20, now tuned)
+      k=20  → very sharp (1-2 pixels) — can be set via AND_SALT[20]
+
+    Parent always uses k=1 (diffuse reference) so children compete fairly.
+    """
+    if not vectors:
+        return torch.zeros_like(normal)
+
+    salience_maps = [_get_salience(normal, k=1.0)] + [
+        _get_salience(v, k=k) for v, _, k in vectors
+    ]
+    mask = torch.argmax(torch.stack(salience_maps, dim=0), dim=0)
+
+    result = torch.zeros_like(normal)
+    for mask_i, (vector, weight, _) in enumerate(vectors, start=1):
+        vector_mask = (mask == mask_i).float()
+        result = result + weight * vector_mask * (vector - normal)
+    return result
+
+
+def _salient_blend_blob(
+    normal: torch.Tensor,
+    vectors: List[Tuple[torch.Tensor, float, float]],
+) -> torch.Tensor:
+    """
+    AND_SALT_BLOB — life-branch algorithm (fixed erode/thickify order).
+
+    Fix vs original: original did 6×erode then 2×thickify, which always
+    destroyed the 1-2 pixel seed from k=20 on the first erosion step.
+    Correct pipeline:
+      1. k-softmax  → initial seed (sharpness from conciliation_params)
+      2. thickify ×3 → grow seed into a dense blob first
+      3. erode ×1    → smooth/sharpen edges without destroying the core
+    """
+    if not vectors:
+        return torch.zeros_like(normal)
+
+    salience_maps = [_get_salience(normal, k=1.0)] + [
+        _get_salience(v, k=k) for v, _, k in vectors
+    ]
+    mask = torch.argmax(torch.stack(salience_maps, dim=0), dim=0)
+
+    result = torch.zeros_like(normal)
+    for mask_i, (vector, weight, _) in enumerate(vectors, start=1):
+        vector_mask = (mask == mask_i).float()
+        # Grow first, then smooth — prevents seed self-destruction
+        for _ in range(3):
+            vector_mask = _life_step(vector_mask, _thickify_rule)
+        for _ in range(1):
+            vector_mask = _life_step(vector_mask, _erode_rule)
+        result = result + weight * vector_mask * (vector - normal)
+    return result
+
+
+def _life_step(board: torch.Tensor, rule) -> torch.Tensor:
+    C = board.shape[0]
+    kernel = torch.ones((C, 3, 3), dtype=board.dtype, device=board.device)
+    kernel = kernel.unsqueeze(0).unsqueeze(0)
+
+    padded = torch.cat([board.clone(), board[:-1].clone()], dim=0)
+    padded = torch.nn.functional.pad(padded, (1, 1, 1, 1, 0, 0), value=0)
+
+    neighbors = torch.nn.functional.conv3d(
+        padded.unsqueeze(0).unsqueeze(0),
+        kernel,
+        padding=0,
+    ).squeeze(0).squeeze(0)
+
+    neighbors = neighbors - board
+    return rule(board, neighbors).float()
+
+
+def _erode_rule(board: torch.Tensor, neighbors: torch.Tensor) -> torch.Tensor:
+    C = board.shape[0]
+    return (board == 1) & (neighbors >= C * 5)
+
+
+def _thickify_rule(board: torch.Tensor, neighbors: torch.Tensor) -> torch.Tensor:
+    population = board + neighbors
+    return (board == 1) | (population >= 4)
+
+
+def _get_salience(vector: torch.Tensor, k: float = 1.0) -> torch.Tensor:
+    return torch.softmax(k * torch.abs(vector).flatten(), dim=0).reshape_as(vector)
+
+
+def _filter_abs_top_k(vector: torch.Tensor, k_ratio: float) -> torch.Tensor:
+    k = int(torch.numel(vector) * (1 - k_ratio))
+    k = max(1, k)
+    threshold, _ = torch.kthvalue(torch.abs(vector.flatten()), k)
+    return vector * (torch.abs(vector) >= threshold).to(vector.dtype)
+
+
+# ---------------------------------------------------------------------------
+# Alignment blend  (alignment_blend branch)
+# ---------------------------------------------------------------------------
+
+def _compute_subregion_similarity_map(
+    child_vector: torch.Tensor,
+    parent_vector: torch.Tensor,
+    region_size: int = 2,
+) -> torch.Tensor:
+    C, H, W = child_vector.shape
+    parent = parent_vector.unsqueeze(0)
+    child  = child_vector.unsqueeze(0)
+
+    region_radius = region_size // 2
+    if region_size % 2 == 1:
+        pad_size = (region_radius,) * 4
+    else:
+        pad_size = (region_radius - 1, region_radius) * 2
+
+    parent_reg = F.unfold(F.pad(parent, pad_size, 'constant', 0), kernel_size=region_size)
+    child_reg  = F.unfold(F.pad(child,  pad_size, 'constant', 0), kernel_size=region_size)
+
+    parent_reg = parent_reg.view(1, C, region_size**2, H*W).permute(3, 1, 2, 0).contiguous().view(H*W, C, region_size, region_size)
+    child_reg  = child_reg.view( 1, C, region_size**2, H*W).permute(3, 1, 2, 0).contiguous().view(H*W, C, region_size, region_size)
+
+    unfold2 = torch.nn.Unfold(kernel_size=2)
+    parent_sub = unfold2(parent_reg).view(H*W, C, 4, (region_size - 1)**2)
+    child_sub  = unfold2(child_reg ).view(H*W, C, 4, (region_size - 1)**2)
+
+    parent_sub = F.normalize(parent_sub, p=2, dim=2)
+    child_sub  = F.normalize(child_sub,  p=2, dim=2)
+    sim = (parent_sub * child_sub).sum(dim=2)
+    return sim.mean(dim=2).permute(1, 0).contiguous().view(C, H, W)
+
+
+def _alignment_blend(
+    parent: torch.Tensor,
+    children: List[Tuple[torch.Tensor, float, int, int]],
+) -> torch.Tensor:
+    result = torch.zeros_like(parent)
+    for child, weight, detail_size, structure_size in children:
+        detail_sim    = _compute_subregion_similarity_map(child, parent, detail_size)
+        structure_sim = _compute_subregion_similarity_map(child, parent, structure_size)
+
+        d_abs_max = detail_sim.abs().max().clamp(min=1e-8)
+        s_abs_max = structure_sim.abs().max().clamp(min=1e-8)
+        detail_sim    = detail_sim    / d_abs_max
+        structure_sim = structure_sim / s_abs_max
+
+        alignment_weight = torch.clamp(structure_sim - detail_sim, min=0.0, max=1.0)
+        result = result + (child - parent) * weight * alignment_weight
+    return result
+
+
+def _alignment_mask_blend(
+    parent: torch.Tensor,
+    children: List[Tuple[torch.Tensor, float, int, int]],
+) -> torch.Tensor:
+    result = torch.zeros_like(parent)
+    for child, weight, detail_size, structure_size in children:
+        detail_sim    = _compute_subregion_similarity_map(child, parent, detail_size)
+        structure_sim = _compute_subregion_similarity_map(child, parent, structure_size)
+
+        d_abs_max = detail_sim.abs().max().clamp(min=1e-8)
+        s_abs_max = structure_sim.abs().max().clamp(min=1e-8)
+        detail_sim    = detail_sim    / d_abs_max
+        structure_sim = structure_sim / s_abs_max
+
+        alignment_mask = (structure_sim > detail_sim).to(child)
+        result = result + (child - parent) * weight * alignment_mask
+    return result
+
+
+
+# ---------------------------------------------------------------------------
+# Base-prompt protection policy (imported from protection_utils)
+# ---------------------------------------------------------------------------
+from lib_neutral_prompt.protection_utils import (
+    prompt_has_valid_base_path      as _prompt_has_valid_base_path,
+    get_invalid_base_prompt_indices  as _get_invalid_base_prompt_indices,
+    has_valid_base_path             as _has_valid_base_path,
+    safe_norm                       as _safe_norm,
+    apply_soft_attenuation_if_needed,
+)
+from lib_neutral_prompt.affine_utils import try_invert_affine as _try_invert_affine
+
+
+def _should_fallback_for_protection(
+    x_out: torch.Tensor,
+    batch_cond_indices,
+    text_uncond: torch.Tensor,
+) -> tuple:
+    """
+    Decide whether to fall back to standard CFG.  Delegates to protection_utils.
+    Passes the visitor classes defined in this module to avoid circular imports.
+    """
+    from lib_neutral_prompt.protection_utils import should_fallback_for_protection
+    return should_fallback_for_protection(
+        x_out, batch_cond_indices, text_uncond,
+        _CondDeltaVisitor, _AuxCondDeltaVisitor, _DenoiseArgs,
+    )
+
+
+
+# ---------------------------------------------------------------------------
+# Sampler hijack
+# ---------------------------------------------------------------------------
+
+sd_samplers_hijacker = hijacker.ModuleHijacker.install_or_get(
+    module=sd_samplers,
+    hijacker_attribute='__neutral_prompt_hijacker',
+    on_uninstall=script_callbacks.on_script_unloaded,
+)
+
+
+@sd_samplers_hijacker.hijack('create_sampler')
+def create_sampler_hijack(name: str, model, original_function):
+    sampler = original_function(name, model)
+    if not hasattr(sampler, 'model_wrap_cfg') or not hasattr(sampler.model_wrap_cfg, 'combine_denoised'):
+        if global_state.is_enabled:
+            _warn_unsupported_sampler()
+        return sampler
+
+    sampler.model_wrap_cfg.combine_denoised = functools.partial(
+        combine_denoised_hijack,
+        original_function=sampler.model_wrap_cfg.combine_denoised,
+    )
+    return sampler
+
+
+# ---------------------------------------------------------------------------
+# Warnings / logging
+# ---------------------------------------------------------------------------
+
+def _warn_unsupported_sampler() -> None:
+    _console_warn('''
+        Neutral prompt relies on composition via AND, which the webui does not support
+        when using any of the DDIM, PLMS and UniPC samplers.
+        The sampler will NOT be patched – falling back on the original implementation.
+    ''')
+
+
+def _warn_projection_not_found() -> None:
+    _console_warn('''
+        Could not find a projection for one or more AND_PERP prompts.
+        These prompts will NOT be made perpendicular.
+    ''')
+
+
+def _console_warn(message: str) -> None:
+    if not global_state.verbose:
+        return
+    print(f'\n[sd-webui-neutral-prompt]{textwrap.dedent(message)}', file=sys.stderr)

neutral_prompt_patcheds/lib_neutral_prompt/external_code/__init__.py

@@ -0,0 +1,23 @@
+import contextlib
+
+
+@contextlib.contextmanager
+def fix_path():
+    import sys
+    from pathlib import Path
+
+    extension_path = str(Path(__file__).parent.parent.parent)
+    added = False
+    if extension_path not in sys.path:
+        sys.path.insert(0, extension_path)
+        added = True
+
+    yield
+
+    if added:
+        sys.path.remove(extension_path)
+
+
+with fix_path():
+    del fix_path, contextlib
+    from .api import *

neutral_prompt_patcheds/lib_neutral_prompt/external_code/api.py

@@ -0,0 +1,27 @@
+"""
+External API for sd-webui-neutral-prompt.
+
+Provides thin helpers that external extensions / scripts can import via:
+
+    from lib_neutral_prompt.external_code import override_cfg_rescale, get_last_cfg_rescale_factor
+"""
+
+from typing import Optional
+
+from lib_neutral_prompt import global_state
+
+
+def override_cfg_rescale(cfg_rescale: float) -> None:
+    """
+    Override the CFG rescale value for the *next* generation step only.
+    After the step runs the value is automatically cleared.
+    """
+    global_state.cfg_rescale_override = cfg_rescale
+
+
+def get_last_cfg_rescale_factor() -> Optional[float]:
+    """
+    Return the CFG rescale factor computed during the most recent denoising
+    step, or None if rescaling was not active.
+    """
+    return global_state.CFGRescaleFactorSingleton.get()

neutral_prompt_patcheds/lib_neutral_prompt/global_state.py

@@ -0,0 +1,325 @@
+"""
+Global mutable state shared across the extension.
+
+Combines:
+  - is_enabled / prompt_exprs / verbose         (all branches)
+  - cfg_rescale + cfg_rescale_override           (main branch)
+  - batch_cond_indices                           (affine branch)
+  - CFGRescaleFactorSingleton                    (export_rescale_factor branch)
+  - protection_mode / strict_threshold           (patched — base-prompt protection)
+"""
+
+import threading
+from typing import List, Optional, Tuple
+from lib_neutral_prompt import neutral_prompt_parser
+
+
+# ---------------------------------------------------------------------------
+# Runtime state
+# ---------------------------------------------------------------------------
+
+is_enabled: bool = False
+prompt_exprs: List[neutral_prompt_parser.PromptExpr] = []
+batch_cond_indices: List[List[Tuple[int, float]]] = []
+cfg_rescale: float = 0.0
+verbose: bool = False
+
+# Set to a float value by XYZ-grid or external API to override cfg_rescale
+# for a single generation step, then auto-cleared.
+cfg_rescale_override: Optional[float] = None
+
+
+def apply_and_clear_cfg_rescale_override() -> None:
+    """Apply a one-shot cfg_rescale override and immediately clear it."""
+    global cfg_rescale, cfg_rescale_override
+    if cfg_rescale_override is not None:
+        cfg_rescale = cfg_rescale_override
+        cfg_rescale_override = None
+
+
+# ---------------------------------------------------------------------------
+# Base-prompt protection
+# ---------------------------------------------------------------------------
+# Three modes:
+#
+#   'off'    — no guard; auxiliary children can dominate freely.
+#              Use for experiments or intentional replacement-style prompts.
+#
+#   'auto'   — (DEFAULT) structural guard: fires when the prompt tree has no
+#              top-level base AND-child (i.e. all children have conciliation
+#              keywords).  Prevents obvious "main prompt disappears" cases.
+#
+#   'strict' — structural guard PLUS numerical guard: also fires when a base
+#              child exists but its cond_delta is too weak relative to the
+#              auxiliary contribution:
+#                  norm(base_delta) / norm(aux_delta) < strict_threshold
+#              Use when you notice auxiliary prompts quietly dominating even
+#              though a base prompt is present.
+#
+# Both auto/strict fall back to standard A1111 CFG and print a warning when
+# verbose=True in Settings → Neutral Prompt.
+# ---------------------------------------------------------------------------
+
+_VALID_PROTECTION_MODES = frozenset({'off', 'auto', 'strict', 'soft'})
+
+protection_mode: str = 'auto'
+strict_threshold: float = 0.10   # ratio threshold used by both strict and soft modes
+
+
+def normalize_protection_mode(value: str) -> str:
+    """
+    Normalise an incoming protection-mode string.
+    Strips whitespace, lowercases, and falls back to 'auto' for unknown values.
+    Used wherever mode arrives from the UI or infotext paste.
+    Valid modes: 'off', 'auto', 'strict', 'soft'.
+    """
+    normalised = str(value).strip().lower()
+    if normalised not in _VALID_PROTECTION_MODES:
+        return 'auto'
+    return normalised
+
+
+def clamp_strict_threshold(value) -> float:
+    """Clamp threshold to [0.01, 0.50]; returns 0.10 on parse failure."""
+    try:
+        return max(0.01, min(0.50, float(value)))
+    except (TypeError, ValueError):
+        return 0.10
+
+
+
+# ---------------------------------------------------------------------------
+# Step-window activation control
+# ---------------------------------------------------------------------------
+# Controls which denoising steps each AND_* strategy is active during.
+# All values here are read by step_utils.strategy_is_active_from_state().
+#
+#   step_window_enabled       — master switch; False = always active (default)
+#   step_window_global        — StepWindow or None, applied to every strategy
+#   step_window_per_strategy  — dict[family_name, StepWindow] or None
+#   step_window_use_defaults  — True = fall back to step_utils.STRATEGY_DEFAULTS
+
+step_window_enabled:       bool = False
+step_window_global                = None   # StepWindow | None
+step_window_per_strategy          = None   # dict[str, StepWindow] | None  (family → StepWindow)
+step_window_use_defaults:  bool = False
+step_window_custom_raw            = None   # dict[str, tuple] | None  {AND_* UI key → (start,end)}
+step_window_lock_after_end: bool = False   # freeze strategies after their window closes
+
+# Per-generation per-strategy lock flags  {family_name → True if locked}
+# Keyed by _lock_generation_id: flags from a previous generation are never
+# visible to the current one even if reset_step_lock_flags() was not called.
+_step_lock_flags: dict = {}
+
+# Monotonically increasing counter bumped once per real generation
+# (i.e. once per NeutralPromptScript.process() call).
+# strategy_is_active_from_state embeds this ID in each flag entry so that
+# flags from a previous generation are treated as absent.
+_lock_generation_id: int = 0
+
+
+def begin_new_generation() -> None:
+    """
+    Mark the start of a new generation run.
+
+    Call this exactly once per NeutralPromptScript.process() call.
+    Bumping the generation ID effectively invalidates all lock flags from
+    the previous run — without requiring any lock-flag cleanup in the
+    denoising loop itself.
+
+    This is intentionally NOT triggered by current_step == 0 because
+    some samplers (Restart, DPM++ variants) revisit step 0 internally
+    within a single denoising pass.  Using the process() lifecycle hook
+    instead gives a clean, unambiguous per-generation boundary.
+    """
+    global _lock_generation_id, _step_lock_flags
+    _lock_generation_id += 1
+    _step_lock_flags = {}
+
+
+def ensure_step_lock_run_initialized(run_token) -> bool:
+    """
+    Token-based alternative to begin_new_generation().
+
+    Initialises lock flags when *run_token* differs from the last seen token.
+    Returns True if a reset was performed (new generation), False otherwise.
+
+    Typical token: ``id(global_state.prompt_exprs)`` — a new list object is
+    created on every NeutralPromptScript.process() call, so the token changes
+    exactly once per generation and is stable across sampler restarts that
+    happen inside the denoising loop.
+
+    Prefer begin_new_generation() when you control the call-site (scripts/);
+    use this helper when you only have access to an existing context object.
+    """
+    global _lock_generation_id, _step_lock_flags
+    current_token = getattr(ensure_step_lock_run_initialized, '_last_token', object())
+    if current_token != run_token:
+        ensure_step_lock_run_initialized._last_token = run_token  # type: ignore[attr-defined]
+        _lock_generation_id += 1
+        _step_lock_flags = {}
+        return True
+    return False
+
+
+def reset_step_lock_flags() -> None:
+    """
+    Clear all Lock-after-End flags for the current generation.
+
+    Prefer begin_new_generation() for per-generation resets; this helper
+    exists for testing and for callers that need an in-generation flush.
+    """
+    global _step_lock_flags
+    _step_lock_flags = {}
+
+# Current step counter — set by the hijack each denoising step.
+current_step: int = 0
+total_steps:  int = 1
+
+
+def update_step_state(step, total) -> None:
+    """
+    Update the current denoising step counters.
+
+    Called by the sampler hijack at each step so that step-window gating
+    has accurate progress information.
+
+    Parameters
+    ----------
+    step  : current 0-based step index (any numeric type)
+    total : total number of steps (any numeric type, must be ≥ 1)
+    """
+    global current_step, total_steps
+    try:
+        current = max(0, int(step))
+    except Exception:
+        current = 0
+    try:
+        total_ = max(1, int(total))
+    except Exception:
+        total_ = 1
+    current_step = current
+    total_steps  = total_
+
+
+# ---------------------------------------------------------------------------
+# Infotext helpers
+# ---------------------------------------------------------------------------
+# Keys used when saving/restoring settings via A1111 infotext.
+
+INFOTEXT_KEY_PROTECTION_MODE    = 'NP Protection Mode'
+INFOTEXT_KEY_STRICT_THRESHOLD   = 'NP Strict Threshold'
+INFOTEXT_KEY_CFG_RESCALE        = 'CFG Rescale phi'
+INFOTEXT_KEY_STEP_WIN_ENABLED   = 'NP Step Window Enabled'
+INFOTEXT_KEY_STEP_WIN_MODE      = 'NP Step Window Mode'
+INFOTEXT_KEY_STEP_WIN_START     = 'NP Step Window Start'
+INFOTEXT_KEY_STEP_WIN_END       = 'NP Step Window End'
+INFOTEXT_KEY_STEP_WIN_CUSTOM    = 'NP Step Window Custom'
+INFOTEXT_KEY_STEP_WIN_LOCK      = 'NP Step Window Lock'
+
+
+def apply_infotext(fields: dict) -> None:
+    """
+    Apply a dict of infotext key→value pairs to global state.
+    Called from the script's on_infotext_pasted handler.
+    Only updates fields that are actually present in the dict.
+    """
+    global protection_mode, strict_threshold, cfg_rescale
+    global step_window_enabled, step_window_global, step_window_use_defaults
+    global step_window_per_strategy, step_window_custom_raw, step_window_lock_after_end
+
+    if INFOTEXT_KEY_PROTECTION_MODE in fields:
+        protection_mode = normalize_protection_mode(fields[INFOTEXT_KEY_PROTECTION_MODE])
+    if INFOTEXT_KEY_STRICT_THRESHOLD in fields:
+        strict_threshold = clamp_strict_threshold(fields[INFOTEXT_KEY_STRICT_THRESHOLD])
+    if INFOTEXT_KEY_CFG_RESCALE in fields:
+        try:
+            cfg_rescale = float(fields[INFOTEXT_KEY_CFG_RESCALE])
+        except (TypeError, ValueError):
+            pass
+
+    # Step-window fields (all optional — may be absent in older infotext)
+    if INFOTEXT_KEY_STEP_WIN_ENABLED in fields:
+        raw = fields[INFOTEXT_KEY_STEP_WIN_ENABLED]
+        step_window_enabled = str(raw).lower() in ('true', '1', 'yes')
+
+    if step_window_enabled:
+        mode  = str(fields.get(INFOTEXT_KEY_STEP_WIN_MODE, 'global'))
+        try:
+            start = max(0.0, min(1.0, float(fields.get(INFOTEXT_KEY_STEP_WIN_START, 0.0))))
+        except (TypeError, ValueError):
+            start = 0.0
+        try:
+            end   = max(0.0, min(1.0, float(fields.get(INFOTEXT_KEY_STEP_WIN_END, 1.0))))
+        except (TypeError, ValueError):
+            end = 1.0
+        if start > end:
+            start, end = 0.0, 1.0
+
+        if mode == 'global':
+            # Import here to avoid circular import at module level
+            from lib_neutral_prompt.step_utils import StepWindow as _SW
+            step_window_global       = _SW(start, end)
+            step_window_use_defaults = False
+            step_window_per_strategy = None
+        elif mode == 'per-strategy defaults':
+            step_window_global       = None
+            step_window_use_defaults = True
+            step_window_per_strategy = None
+        elif mode == 'per-strategy custom':
+            step_window_global       = None
+            step_window_use_defaults = False
+            # Restore per-strategy dict from compact string if present
+            if INFOTEXT_KEY_STEP_WIN_CUSTOM in fields:
+                from lib_neutral_prompt.step_utils import (
+                    deserialize_per_strategy_windows,
+                    build_per_strategy_windows,
+                )
+                raw = deserialize_per_strategy_windows(
+                    str(fields[INFOTEXT_KEY_STEP_WIN_CUSTOM])
+                )
+                step_window_custom_raw   = raw
+                step_window_per_strategy = build_per_strategy_windows(raw)
+        else:
+            step_window_global       = None
+            step_window_use_defaults = False
+
+    # Lock after End (may be set independently of other step-window fields)
+    if INFOTEXT_KEY_STEP_WIN_LOCK in fields:
+        raw_lock = fields[INFOTEXT_KEY_STEP_WIN_LOCK]
+        step_window_lock_after_end = str(raw_lock).lower() in ('true', '1', 'yes')
+
+
+# ---------------------------------------------------------------------------
+# CFG Rescale Factor Singleton  (export_rescale_factor branch)
+#
+# Stores the last computed rescale factor so that external tools / scripts
+# can read it without re-deriving it.
+#
+# Uses threading.local() so concurrent API workers each get their own slot.
+# clear() must be called at the start of every _cfg_rescale() call so that
+# get() correctly returns None when rescaling was skipped this step.
+# ---------------------------------------------------------------------------
+
+class CFGRescaleFactorSingleton:
+    """Thread-local store for the most recently computed CFG rescale factor.
+
+    Lifecycle per denoising step:
+      1. _cfg_rescale() calls clear() at entry — value becomes None.
+      2. If rescaling is active, set() stores the computed factor.
+      3. External code calls get() after the step; receives the factor or None.
+    """
+
+    _state = threading.local()
+
+    @classmethod
+    def set(cls, value: float) -> None:
+        cls._state.cfg_rescale_factor = value
+
+    @classmethod
+    def get(cls) -> Optional[float]:
+        return getattr(cls._state, 'cfg_rescale_factor', None)
+
+    @classmethod
+    def clear(cls) -> None:
+        cls._state.cfg_rescale_factor = None

neutral_prompt_patcheds/lib_neutral_prompt/hijacker.py

@@ -0,0 +1,34 @@
+import functools
+
+
+class ModuleHijacker:
+    def __init__(self, module):
+        self.__module = module
+        self.__original_functions = dict()
+
+    def hijack(self, attribute):
+        if attribute not in self.__original_functions:
+            self.__original_functions[attribute] = getattr(self.__module, attribute)
+
+        def decorator(function):
+            setattr(self.__module, attribute, functools.partial(function, original_function=self.__original_functions[attribute]))
+            return function
+
+        return decorator
+
+    def reset_module(self):
+        for attribute, original_function in self.__original_functions.items():
+            setattr(self.__module, attribute, original_function)
+
+        self.__original_functions.clear()
+
+    @staticmethod
+    def install_or_get(module, hijacker_attribute, on_uninstall=lambda _callback: None):
+        if not hasattr(module, hijacker_attribute):
+            module_hijacker = ModuleHijacker(module)
+            setattr(module, hijacker_attribute, module_hijacker)
+            on_uninstall(lambda: delattr(module, hijacker_attribute))
+            on_uninstall(module_hijacker.reset_module)
+            return module_hijacker
+        else:
+            return getattr(module, hijacker_attribute)

neutral_prompt_patcheds/lib_neutral_prompt/matryoshka_utils.py

@@ -0,0 +1,644 @@
+"""
+Pure-Python helpers for Matryoshka (nested prompt) construction, tree rendering,
+and diagnostics.
+
+Importable without gradio or A1111 modules — all functions here have no
+side effects and depend only on neutral_prompt_parser and global_state.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from lib_neutral_prompt import global_state, neutral_prompt_parser
+
+
+# ---------------------------------------------------------------------------
+# Builder helpers
+# ---------------------------------------------------------------------------
+
+_KW_DEFAULTS: Dict[str, str] = {
+    'AND_PERP':       'AND_PERP',
+    'AND_SALT':       'AND_SALT[5]',
+    'AND_SALT_WIDE':  'AND_SALT_WIDE[1]',
+    'AND_SALT_BLOB':  'AND_SALT_BLOB[5]',
+    'AND_TOPK':       'AND_TOPK[0.05]',
+    'AND_ALIGN':      'AND_ALIGN[4,8]',
+    'AND_MASK_ALIGN': 'AND_MASK_ALIGN[4,8]',
+}
+
+BUILDER_STRATEGIES = sorted(_KW_DEFAULTS.keys())
+
+
+def build_child_block(strategy: str, text: str, weight: float,
+                      affine: str = '', nested: str = '') -> str:
+    """
+    Build a single AND_* child block, optionally with an affine prefix
+    and an inner nested block.
+
+    Returns the child line(s) as a string (no trailing newline).
+    Returns an empty string if both `text` and `nested` are empty/whitespace —
+    callers should check for this and skip the block.
+
+    Examples::
+
+        build_child_block('AND_SALT', 'texture', 0.8)
+        # → 'AND_SALT[5] texture :0.8'
+
+        build_child_block('AND_TOPK', 'highlights', 0.5,
+                          nested='AND_PERP blur :0.4')
+        # → 'AND_TOPK[0.05] [\\n  highlights :0.5\\n  AND_PERP blur :0.4\\n] :0.5'
+
+        build_child_block('AND_SALT', '', 0.8)
+        # → '' (empty — nothing to insert)
+    """
+    kw     = _KW_DEFAULTS.get(strategy, strategy)
+    prefix = f'{affine.strip()} ' if affine.strip() else ''
+    w_str  = f':{weight}'
+    text   = text.strip()
+    nested = nested.strip()
+
+    # Nothing to add — signal the caller to skip this block entirely.
+    if not text and not nested:
+        return ''
+
+    if nested:
+        inner_lines: List[str] = []
+        # Only include the text line when text is non-empty
+        if text:
+            inner_lines.append(f'  {text} {w_str}')
+        for ln in nested.splitlines():
+            inner_lines.append(f'  {ln}')
+        body = '\n'.join(inner_lines)
+        return f'{prefix}{kw} [\n{body}\n] {w_str}'
+    else:
+        return f'{prefix}{kw} {text} {w_str}'
+
+
+def build_nested_prompt(base: str, children: List[Dict[str, Any]]) -> str:
+    """
+    Build a complete prompt from a base string and a list of child dicts.
+
+    Each child dict may contain:
+        strategy (str), text (str), weight (float),
+        affine (str, optional), nested (str, optional)
+
+    Children whose `text` and `nested` are both empty are silently skipped.
+    Returns the full prompt as a single string.
+    """
+    parts = [base.strip()] if base.strip() else []
+    for ch in children:
+        block = build_child_block(
+            strategy=ch.get('strategy', 'AND_PERP'),
+            text=ch.get('text', ''),
+            weight=float(ch.get('weight', 1.0)),
+            affine=ch.get('affine', ''),
+            nested=ch.get('nested', ''),
+        )
+        if block:          # empty string → skip
+            parts.append(block)
+    return '\n'.join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Tree renderer
+# ---------------------------------------------------------------------------
+
+def render_prompt_node(
+    node: neutral_prompt_parser.PromptExpr,
+    depth: int = 0,
+    prefix: str = '',
+    is_last: bool = True,
+) -> List[str]:
+    """
+    Recursively render a single AST node as tree lines using box-drawing chars.
+
+    Returns a list of strings (one per line), without trailing newline.
+    """
+    connector = '└─ ' if is_last else '├─ '
+    child_pfx = prefix + ('   ' if is_last else '│  ')
+
+    strat = node.conciliation.name if node.conciliation else 'BASE'
+    w     = f'w={node.weight:.2f}'
+    params_str = ''
+    if node.conciliation_params:
+        params_str = '  [' + ', '.join(f'{k}={v}' for k, v in node.conciliation_params.items()) + ']'
+    aff_str = '  ✦affine' if node.local_transform is not None else ''
+
+    if hasattr(node, 'prompt'):
+        txt   = node.prompt.strip()
+        short = (txt[:55] + '…') if len(txt) > 55 else txt
+        label = f'{connector}[{strat}] {w}{params_str}{aff_str}  "{short}"'
+    else:
+        n = len(node.children) if hasattr(node, 'children') else 0
+        label = f'{connector}[{strat}] {w}{params_str}{aff_str}  ({n} children)'
+
+    lines: List[str] = [prefix + label]
+
+    if hasattr(node, 'children') and node.children:
+        for i, child in enumerate(node.children):
+            last = (i == len(node.children) - 1)
+            lines.extend(render_prompt_node(child, depth + 1, child_pfx, last))
+
+    return lines
+
+
+def render_prompt_tree(prompt_str: str) -> str:
+    """Full tree render. Returns a multi-line string ready for display."""
+    if not prompt_str.strip():
+        return '(empty prompt — nothing to show)'
+
+    try:
+        root = neutral_prompt_parser.parse_root(prompt_str)
+    except Exception as exc:
+        return f'⚠ Parse error: {exc}'
+
+    n = len(root.children) if hasattr(root, 'children') else 0
+    lines = [f'ROOT  ({n} top-level segments)']
+    if hasattr(root, 'children') and root.children:
+        for i, child in enumerate(root.children):
+            last = (i == len(root.children) - 1)
+            lines.extend(render_prompt_node(child, prefix='', is_last=last))
+    return '\n'.join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics
+# ---------------------------------------------------------------------------
+
+_BRACKET_KW_NAMES = frozenset({
+    'SALIENCE_MASK', 'SALIENCE_MASK_WIDE', 'SALIENCE_MASK_BLOB',
+    'SEMANTIC_GUIDANCE', 'ALIGNMENT_BLEND_CUSTOM', 'ALIGNMENT_MASK_BLEND_CUSTOM',
+})
+
+
+def collect_prompt_diagnostics(prompt_str: str) -> Dict[str, Any]:
+    """
+    Parse prompt_str and collect diagnostic metadata.
+
+    Returns a dict with keys:
+        parse_ok, parse_error, max_depth, n_segments, n_leaf, n_composite,
+        n_affine, n_invalid_base, strategies, ignored_hint,
+        protection_would_fire, protection_mode
+    """
+    result: Dict[str, Any] = {
+        'parse_ok': False,
+        'parse_error': None,
+        'max_depth': 0,
+        'n_segments': 0,
+        'n_leaf': 0,
+        'n_composite': 0,
+        'n_affine': 0,
+        'n_invalid_base': 0,
+        'strategies': [],
+        'ignored_hint': False,
+        'protection_would_fire': False,
+        'protection_mode': global_state.normalize_protection_mode(global_state.protection_mode),
+    }
+
+    if not prompt_str.strip():
+        return result
+
+    try:
+        root = neutral_prompt_parser.parse_root(prompt_str)
+    except Exception as exc:
+        result['parse_error'] = str(exc)
+        return result
+
+    result['parse_ok'] = True
+    strategies_seen: List[str] = []
+
+    def _walk(node: Any, depth: int) -> None:
+        result['max_depth'] = max(result['max_depth'], depth)
+        result['n_segments'] += 1
+
+        if node.local_transform is not None:
+            result['n_affine'] += 1
+
+        strat = node.conciliation.name if node.conciliation else 'BASE'
+        if strat not in strategies_seen:
+            strategies_seen.append(strat)
+
+        if (node.conciliation is not None
+                and node.conciliation.name in _BRACKET_KW_NAMES
+                and not node.conciliation_params):
+            result['ignored_hint'] = True
+
+        if hasattr(node, 'prompt'):
+            result['n_leaf'] += 1
+        else:
+            result['n_composite'] += 1
+            if hasattr(node, 'children'):
+                for child in node.children:
+                    _walk(child, depth + 1)
+
+    _walk(root, 0)
+    result['strategies'] = strategies_seen
+
+    if isinstance(root, neutral_prompt_parser.CompositePrompt):
+        has_base = any(c.conciliation is None for c in root.children)
+        mode = result['protection_mode']
+        if mode in ('auto', 'strict') and not has_base:
+            result['protection_would_fire'] = True
+            result['n_invalid_base'] = 1
+
+    return result
+
+
+def render_diagnostics(diag: Dict[str, Any]) -> str:
+    """Turn a diagnostics dict into a readable report string."""
+    if not diag['parse_ok']:
+        err = diag.get('parse_error') or 'unknown'
+        return f'⚠ Parse error: {err}'
+
+    lines = ['── Diagnostics ──────────────────────────']
+    lines.append(f'Segments total : {diag["n_segments"]}  '
+                 f'(leaf={diag["n_leaf"]}, composite={diag["n_composite"]})')
+    lines.append(f'Max nesting depth : {diag["max_depth"]}')
+    lines.append(f'Affine transforms : {diag["n_affine"]}')
+    lines.append(f'Strategies used   : {", ".join(diag["strategies"]) or "none"}')
+
+    if diag['ignored_hint']:
+        lines.append('⚠ One or more bracket params were invalid and ignored. Using defaults.')
+
+    lines.append('')
+    mode = diag['protection_mode']
+    lines.append(f'Protection mode : {mode}')
+    if mode == 'off':
+        lines.append('  Guard disabled — no fallback will occur')
+    elif diag['protection_would_fire']:
+        lines.append('  ⚠ WOULD FIRE — no plain base segment at the top level')
+        lines.append('  Fix: add a plain base prompt before all AND_* segments')
+    else:
+        lines.append('  OK — base segment present at top level')
+        if mode == 'strict':
+            thr = global_state.strict_threshold
+            lines.append(f'  Strict ratio check ({thr:.2f}) runs at generation time')
+
+    return '\n'.join(lines)
+
+
+def render_full_explain(prompt_str: str) -> str:
+    """
+    Combine tree + diagnostics + effect summaries into a single panel output.
+
+    For an empty prompt returns only the empty-state message (no spurious
+    parse-error noise).
+    """
+    if not prompt_str.strip():
+        return '(empty prompt — nothing to show)'
+
+    tree  = render_prompt_tree(prompt_str)
+    diag  = collect_prompt_diagnostics(prompt_str)
+    diagr = render_diagnostics(diag)
+    summary = _render_effect_summary(diag)
+
+    parts = [tree, '', diagr]
+    if summary:
+        parts += ['', summary]
+    return '\n'.join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Effect summaries
+# ---------------------------------------------------------------------------
+
+_EFFECT_DESCRIPTIONS: Dict[str, str] = {
+    'BASE':                         'base prompt contribution — drives the overall image',
+    'PERPENDICULAR':                'perpendicular projection — reduces contradicting features',
+    'SALIENCE_MASK':                'sharp saliency mask — targets the most salient latent pixels',
+    'SALIENCE_MASK_WIDE':           'broad saliency mask — covers a wide region (~55% of pixels)',
+    'SALIENCE_MASK_BLOB':           'blob saliency — grows seed region to a smooth connected area',
+    'SEMANTIC_GUIDANCE':            'semantic top-k — applies sparse targeted changes to the strongest elements',
+    'ALIGNMENT_BLEND_CUSTOM':       'alignment blend — soft injection that preserves global structure',
+    'ALIGNMENT_MASK_BLEND_CUSTOM':  'alignment mask — binary-mask variant of alignment blend (stricter)',
+}
+# Catch legacy fixed-suffix ALIGNMENT_BLEND_D_S patterns
+_ALIGNMENT_PREFIX = 'ALIGNMENT_BLEND_'
+_ALIGNMENT_MASK_PREFIX = 'ALIGNMENT_MASK_BLEND_'
+
+
+def _effect_for_strategy(name: str) -> str:
+    if name in _EFFECT_DESCRIPTIONS:
+        return _EFFECT_DESCRIPTIONS[name]
+    if name.startswith(_ALIGNMENT_MASK_PREFIX):
+        return _EFFECT_DESCRIPTIONS['ALIGNMENT_MASK_BLEND_CUSTOM']
+    if name.startswith(_ALIGNMENT_PREFIX):
+        return _EFFECT_DESCRIPTIONS['ALIGNMENT_BLEND_CUSTOM']
+    return f'strategy: {name}'
+
+
+def _render_effect_summary(diag: Dict[str, Any]) -> str:
+    """
+    Build a one-line-per-strategy effect summary from diagnostics data.
+    Returns an empty string if the prompt failed to parse.
+    """
+    if not diag.get('parse_ok'):
+        return ''
+    strategies = diag.get('strategies', [])
+    if not strategies:
+        return ''
+    lines = ['── Effect summary ───────────────────────']
+    for s in strategies:
+        lines.append(f'  {s:32s}→  {_effect_for_strategy(s)}')
+    lines.append('')
+    lines.append('  Note: protection verdict above is a structural preview.')
+    lines.append('  The strict ratio check and batch diagnostics run at generation time.')
+    return '\n'.join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Matryoshka templates
+# ---------------------------------------------------------------------------
+
+MATRYOSHKA_TEMPLATES: Dict[str, Dict[str, str]] = {
+    'Nested local detail': {
+        'description': (
+            'Add fine detail inside a saliency region. '
+            'SALT focuses on salient pixels; nested TOPK applies sparse corrections within that region.'
+        ),
+        'prompt': (
+            'base subject, environment\n'
+            'AND_SALT[5] [\n'
+            '  subject texture :0.8\n'
+            '  AND_TOPK[0.05] fine detail highlights :0.5\n'
+            '] :0.8'
+        ),
+    },
+    'Structure preserve + style inject': {
+        'description': (
+            'Keep global composition while injecting a style locally. '
+            'ALIGN preserves structure; nested PERP reduces contradiction.'
+        ),
+        'prompt': (
+            'base composition, environment\n'
+            'AND_ALIGN[4,8] [\n'
+            '  style name :0.8\n'
+            '  AND_PERP style contradiction :0.5\n'
+            '] :0.7'
+        ),
+    },
+    'Sparse detail inside broad region': {
+        'description': (
+            'SALT_WIDE covers a broad region; nested SALT sharpens a smaller focal point inside it.'
+        ),
+        'prompt': (
+            'base subject\n'
+            'AND_SALT_WIDE[1] [\n'
+            '  surface texture :0.7\n'
+            '  AND_SALT[7] focal detail :0.6\n'
+            '] :0.8'
+        ),
+    },
+    'Perpendicular correction inside texture block': {
+        'description': (
+            'Inject texture while suppressing contradicting composition hints '
+            'via nested perpendicular projection.'
+        ),
+        'prompt': (
+            'base portrait, detailed\n'
+            'AND_SALT[5] [\n'
+            '  skin texture, pores :0.8\n'
+            '  AND_PERP smooth featureless face :0.4\n'
+            '] :0.7'
+        ),
+    },
+    'Nested ALIGN + SALT': {
+        'description': (
+            'Two-pass spatial injection: ALIGN blends a structural concept, '
+            'SALT sharpens a second concept only in salient regions.'
+        ),
+        'prompt': (
+            'base subject\n'
+            'AND_ALIGN[4,8] background concept :0.6\n'
+            'AND_SALT[5] [\n'
+            '  foreground detail :0.8\n'
+            '  AND_TOPK[0.1] specular highlights :0.4\n'
+            '] :0.7'
+        ),
+    },
+    'Mirrored composition': {
+        'description': (
+            'Apply the same concept mirrored, blended via PERP to add symmetric detail '
+            'without overwriting the composition.'
+        ),
+        'prompt': (
+            'base subject\n'
+            'SCALE[-1,1] AND_PERP mirrored version of subject :0.5'
+        ),
+    },
+    'Deep nested concept isolation': {
+        'description': (
+            'Three levels: outer SALT focuses area, middle ALIGN preserves sub-structure, '
+            'inner TOPK applies sparse micro-corrections.'
+        ),
+        'prompt': (
+            'base subject\n'
+            'AND_SALT[5] [\n'
+            '  region concept :0.8\n'
+            '  AND_ALIGN[4,8] [\n'
+            '    structure keeper :0.7\n'
+            '    AND_TOPK[0.05] micro detail :0.4\n'
+            '  ] :0.6\n'
+            '] :0.7'
+        ),
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Affine snippet builder — re-exported from affine_utils (single source of truth)
+# ---------------------------------------------------------------------------
+from lib_neutral_prompt.affine_utils import (
+    AFFINE_TRANSFORMS as _AFFINE_TRANSFORMS,
+    AFFINE_PRESETS    as _AFFINE_PRESETS,
+    build_affine_snippet as _build_affine_snippet,
+)
+
+
+# ---------------------------------------------------------------------------
+# Builder v1.2 — list-based node model
+# ---------------------------------------------------------------------------
+
+import dataclasses
+import uuid
+
+
+@dataclasses.dataclass
+class BuilderNode:
+    """
+    A single AND_* node in the visual matryoshka builder tree.
+
+    Fields
+    ------
+    node_id   : unique identifier (auto-generated UUID4 short)
+    strategy  : key into _KW_DEFAULTS (e.g. 'AND_SALT', 'AND_TOPK')
+    text      : text content for this node
+    weight    : contribution weight (0.0 … 2.0 typical)
+    affine    : optional affine snippet prefix (e.g. 'ROTATE[0.125]')
+    children  : list of BuilderNode — forms the nested (matryoshka) subtree
+    """
+    node_id:  str
+    strategy: str
+    text:     str
+    weight:   float
+    affine:   str                      = dataclasses.field(default='')
+    children: List['BuilderNode']      = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def make(cls, strategy: str = 'AND_SALT', text: str = '',
+             weight: float = 0.8, affine: str = '') -> 'BuilderNode':
+        """Create a new BuilderNode with a fresh UUID."""
+        return cls(
+            node_id=uuid.uuid4().hex[:8],
+            strategy=strategy,
+            text=text,
+            weight=weight,
+            affine=affine,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Builder tree operations (pure — no gradio)
+# ---------------------------------------------------------------------------
+
+def builder_add_child(nodes: List[BuilderNode], parent_id: Optional[str] = None,
+                      **kwargs) -> List[BuilderNode]:
+    """
+    Add a new child BuilderNode.
+
+    If *parent_id* is None: append to the top-level list.
+    If *parent_id* matches a node id: append as nested child of that node.
+    Returns a *new* list (original is not mutated).
+    """
+    new_node = BuilderNode.make(**kwargs)
+    if parent_id is None:
+        return list(nodes) + [new_node]
+
+    def _add(ns: List[BuilderNode]) -> List[BuilderNode]:
+        result = []
+        for n in ns:
+            if n.node_id == parent_id:
+                result.append(dataclasses.replace(n, children=list(n.children) + [new_node]))
+            else:
+                result.append(dataclasses.replace(n, children=_add(n.children)))
+        return result
+
+    return _add(nodes)
+
+
+def builder_remove_node(nodes: List[BuilderNode], node_id: str) -> List[BuilderNode]:
+    """Remove the node with *node_id* from anywhere in the tree."""
+    def _remove(ns: List[BuilderNode]) -> List[BuilderNode]:
+        return [
+            dataclasses.replace(n, children=_remove(n.children))
+            for n in ns if n.node_id != node_id
+        ]
+    return _remove(nodes)
+
+
+def builder_duplicate_node(nodes: List[BuilderNode], node_id: str) -> List[BuilderNode]:
+    """
+    Insert a deep copy of *node_id* immediately after it in its parent list.
+    The duplicate gets a fresh node_id.
+    """
+    def _fresh(n: BuilderNode) -> BuilderNode:
+        return dataclasses.replace(
+            n,
+            node_id=uuid.uuid4().hex[:8],
+            children=[_fresh(c) for c in n.children],
+        )
+
+    def _dup(ns: List[BuilderNode]) -> List[BuilderNode]:
+        result = []
+        for n in ns:
+            result.append(dataclasses.replace(n, children=_dup(n.children)))
+            if n.node_id == node_id:
+                result.append(_fresh(n))
+        return result
+
+    return _dup(nodes)
+
+
+def builder_move_up(nodes: List[BuilderNode], node_id: str) -> List[BuilderNode]:
+    """Swap *node_id* with its predecessor in its parent list."""
+    def _swap(ns: List[BuilderNode]) -> List[BuilderNode]:
+        out = []
+        for i, n in enumerate(ns):
+            if n.node_id == node_id and i > 0:
+                out[-1], swapped = dataclasses.replace(n, children=_swap(n.children)), out[-1]
+                out.append(swapped)
+            else:
+                out.append(dataclasses.replace(n, children=_swap(n.children)))
+        return out
+    return _swap(nodes)
+
+
+def builder_move_down(nodes: List[BuilderNode], node_id: str) -> List[BuilderNode]:
+    """Swap *node_id* with its successor in its parent list."""
+    def _swap(ns: List[BuilderNode]) -> List[BuilderNode]:
+        out = [dataclasses.replace(n, children=_swap(n.children)) for n in ns]
+        for i, n in enumerate(out):
+            if n.node_id == node_id and i < len(out) - 1:
+                out[i], out[i + 1] = out[i + 1], out[i]
+                break
+        return out
+    return _swap(nodes)
+
+
+def builder_update_node(nodes: List[BuilderNode], node_id: str,
+                        **kwargs) -> List[BuilderNode]:
+    """
+    Update fields of *node_id* anywhere in the tree.
+    Only keys present in *kwargs* are changed.
+    """
+    def _update(ns: List[BuilderNode]) -> List[BuilderNode]:
+        return [
+            dataclasses.replace(
+                n,
+                children=_update(n.children),
+                **{k: v for k, v in kwargs.items() if k != 'children'},
+            ) if n.node_id == node_id
+            else dataclasses.replace(n, children=_update(n.children))
+            for n in ns
+        ]
+    return _update(nodes)
+
+
+def serialize_builder_tree(base: str, nodes: List[BuilderNode], indent: int = 0) -> str:
+    """
+    Convert a base string + list of BuilderNodes into a prompt string.
+    Nested children are rendered as composite bracket blocks.
+    """
+    lines: List[str] = []
+    if indent == 0 and base.strip():
+        lines.append(base.strip())
+
+    for node in nodes:
+        kw     = _KW_DEFAULTS.get(node.strategy, node.strategy)
+        prefix = f'{node.affine.strip()} ' if node.affine.strip() else ''
+        w_str  = f':{node.weight}'
+        pad    = '  ' * indent
+
+        if node.children:
+            # Composite bracket block
+            inner: List[str] = []
+            if node.text.strip():
+                inner.append(f'  {pad}{node.text.strip()} {w_str}')
+            for sub in node.children:
+                for sub_ln in serialize_builder_tree('', [sub], indent + 1).splitlines():
+                    if sub_ln.strip():
+                        inner.append(f'  {pad}{sub_ln}')
+            body = '\n'.join(inner)
+            lines.append(f'{pad}{prefix}{kw} [\n{body}\n{pad}] {w_str}')
+        else:
+            if node.text.strip():
+                lines.append(f'{pad}{prefix}{kw} {node.text.strip()} {w_str}')
+            # Node with no text and no children: skip (same policy as build_child_block)
+
+    return '\n'.join(lines)
+
+
+def builder_tree_to_prompt(base: str, nodes: List[BuilderNode]) -> str:
+    """Top-level entry point: serialise the full builder tree to a prompt string."""
+    return serialize_builder_tree(base, nodes)

neutral_prompt_patcheds/lib_neutral_prompt/neutral_prompt_parser.py

@@ -0,0 +1,453 @@
+"""
+Unified Neutral Prompt Parser
+Combines:
+  - Core AND / AND_PERP / AND_SALT / AND_TOPK strategies (main branch)
+  - Affine spatial transforms: ROTATE / SLIDE / SCALE / SHEAR (affine branch)
+  - Fixed AND_ALIGN_D_S / AND_MASK_ALIGN_D_S  (alignment_blend branch)
+  - Bracket-syntax AND_ALIGN[D,S] / AND_MASK_ALIGN[D,S]  (NEW — any valid pair)
+  - Configurable k for salience: AND_SALT[k] / AND_SALT_WIDE[k] / AND_SALT_BLOB[k]  (NEW)
+
+New syntax examples:
+  AND_SALT[5]           concept :0.8    k=5.0  (more coverage than default 20)
+  AND_SALT_WIDE[3]      concept :0.6    explicit k override
+  AND_SALT_BLOB[8]      concept :1.0    blob seed sharpness
+  AND_ALIGN[4,8]        style :0.5      detail=4, structure=8 (any valid pair)
+  AND_MASK_ALIGN[6,12]  style :0.5      binary-mask variant
+
+  AND_ALIGN_4_8 still works — backward-compatible.
+"""
+
+import abc
+import dataclasses
+import math
+import re
+from enum import Enum
+from itertools import product
+from typing import Any, Dict, List, Optional, Tuple
+
+import torch
+
+
+# ---------------------------------------------------------------------------
+# Keyword registry
+# ---------------------------------------------------------------------------
+
+_BASE_KEYWORD_MAP = {
+    'AND_PERP':       'PERPENDICULAR',
+    'AND_SALT':       'SALIENCE_MASK',
+    'AND_SALT_WIDE':  'SALIENCE_MASK_WIDE',
+    'AND_SALT_BLOB':  'SALIENCE_MASK_BLOB',
+    'AND_TOPK':       'SEMANTIC_GUIDANCE',
+    # Bracket-syntax custom alignment (any D,S pair via AND_ALIGN[D,S])
+    'AND_ALIGN':      'ALIGNMENT_BLEND_CUSTOM',
+    'AND_MASK_ALIGN': 'ALIGNMENT_MASK_BLEND_CUSTOM',
+}
+
+_ALIGN_KEYWORD_MAP = {
+    f'AND_ALIGN_{i}_{j}': f'ALIGNMENT_BLEND_{i}_{j}'
+    for i, j in product(range(2, 33), repeat=2) if i != j
+}
+_MASK_ALIGN_KEYWORD_MAP = {
+    f'AND_MASK_ALIGN_{i}_{j}': f'ALIGNMENT_MASK_BLEND_{i}_{j}'
+    for i, j in product(range(2, 33), repeat=2) if i != j
+}
+
+keyword_mapping = _BASE_KEYWORD_MAP | _ALIGN_KEYWORD_MAP | _MASK_ALIGN_KEYWORD_MAP
+
+PromptKeyword = Enum('PromptKeyword', {'AND': 'AND', **{k: k for k in keyword_mapping}})
+ConciliationStrategy = Enum('ConciliationStrategy', {v: k for k, v in keyword_mapping.items()})
+
+prompt_keywords = [e.value for e in PromptKeyword]
+conciliation_strategies = [e.value for e in ConciliationStrategy]
+
+_prompt_keywords_set = frozenset(prompt_keywords)
+_conciliation_strategies_set = frozenset(conciliation_strategies)
+
+_SALT_KEYWORDS = frozenset({'AND_SALT', 'AND_SALT_WIDE', 'AND_SALT_BLOB'})
+_ALIGN_BRACKET_KEYWORDS = frozenset({'AND_ALIGN', 'AND_MASK_ALIGN'})
+_TOPK_KEYWORDS = frozenset({'AND_TOPK'})
+
+
+
+# ---------------------------------------------------------------------------
+# Affine transform definitions  (imported from affine_utils — single source of truth)
+# ---------------------------------------------------------------------------
+from lib_neutral_prompt.affine_utils import (
+    affine_transforms,
+    _affine_warn,
+    _make_rotate,
+    _make_slide,
+    _make_scale,
+    _make_shear,
+    _apply_affine,
+)
+
+
+
+# ---------------------------------------------------------------------------
+# AST node types
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class PromptExpr(abc.ABC):
+    weight: float
+    conciliation: Optional[ConciliationStrategy]
+    local_transform: Optional[torch.Tensor]
+
+    @abc.abstractmethod
+    def accept(self, visitor, *args, **kwargs) -> Any:
+        pass
+
+
+@dataclasses.dataclass
+class LeafPrompt(PromptExpr):
+    prompt: str
+    # conciliation_params MUST be last — it has a default, parent fields don't.
+    conciliation_params: Dict[str, Any] = dataclasses.field(default_factory=dict)
+
+    def accept(self, visitor, *args, **kwargs):
+        return visitor.visit_leaf_prompt(self, *args, **kwargs)
+
+
+@dataclasses.dataclass
+class CompositePrompt(PromptExpr):
+    children: List[PromptExpr]
+    conciliation_params: Dict[str, Any] = dataclasses.field(default_factory=dict)
+
+    def accept(self, visitor, *args, **kwargs):
+        return visitor.visit_composite_prompt(self, *args, **kwargs)
+
+
+class FlatSizeVisitor:
+    def visit_leaf_prompt(self, that: 'LeafPrompt') -> int:
+        return 1
+
+    def visit_composite_prompt(self, that: 'CompositePrompt') -> int:
+        return sum(child.accept(self) for child in that.children) if that.children else 0
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+def parse_root(string: str) -> CompositePrompt:
+    tokens = tokenize(string)
+    prompts = parse_prompts(tokens)
+    return CompositePrompt(1.0, None, None, prompts)
+
+
+def parse_prompts(tokens: List[str], *, nested: bool = False) -> List[PromptExpr]:
+    prompts = [parse_prompt(tokens, first=True, nested=nested)]
+    while tokens:
+        if nested and tokens[0] == ']':
+            break
+        prompts.append(parse_prompt(tokens, first=False, nested=nested))
+    return prompts
+
+
+def _compose_affine(
+    a: Optional[torch.Tensor],
+    b: Optional[torch.Tensor],
+) -> Optional[torch.Tensor]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    a3 = torch.vstack([a, torch.tensor([0.0, 0.0, 1.0], dtype=torch.float32)])
+    b3 = torch.vstack([b, torch.tensor([0.0, 0.0, 1.0], dtype=torch.float32)])
+    return (b3 @ a3)[:-1]
+
+
+def _looks_like_leading_affine_prompt(tokens: List[str]) -> bool:
+    pos = 0
+    n = len(tokens)
+    if pos < n and not tokens[pos].strip():
+        pos += 1
+    if pos >= n or tokens[pos] not in affine_transforms:
+        return False
+    while pos < n and tokens[pos] in affine_transforms:
+        pos += 1
+        if pos >= n or tokens[pos] != '[':
+            return False
+        pos += 1
+        if pos < n and tokens[pos] != ']':
+            pos += 1
+        if pos >= n or tokens[pos] != ']':
+            return False
+        pos += 1
+        if pos < n and not tokens[pos].strip():
+            pos += 1
+    return pos < n and tokens[pos] in _prompt_keywords_set
+
+
+def _parse_keyword_params(tokens: List[str], keyword: str) -> Dict[str, Any]:
+    """
+    Consume optional bracket params immediately after a keyword token.
+
+    Safe: only consumes [inner] when inner is purely numeric (digits, dots,
+    commas, spaces), so composite-prompt brackets like AND_ALIGN[child AND other]
+    are never eaten.
+
+    Supported forms (spaces around comma are tolerated):
+      AND_SALT[5]          -> {'k': 5.0}
+      AND_SALT[3, 5]       -- invalid (too many parts) → warning
+      AND_ALIGN[4,8]       -> {'d': 4, 's': 8}
+      AND_ALIGN[4, 8]      -> {'d': 4, 's': 8}   (spaces OK)
+      AND_MASK_ALIGN[6,12] -> {'d': 6, 's': 12}
+
+    On invalid but numeric content: consumes the brackets, emits a warning,
+    returns {} so the text is not silently swallowed as plain prompt text.
+    """
+    if (keyword not in _SALT_KEYWORDS and keyword not in _ALIGN_BRACKET_KEYWORDS
+            and keyword not in _TOPK_KEYWORDS):
+        return {}
+    if len(tokens) < 3 or tokens[0] != '[' or tokens[2] != ']':
+        return {}
+
+    inner = tokens[1].strip()
+    # Allow digits, dots, commas, and spaces — but nothing alphabetic.
+    # This keeps composite brackets like [concept AND style] safely un-consumed.
+    if not re.match(r'^[\d.,\s]+$', inner):
+        return {}
+
+    # Consume the brackets now — we own this content.
+    tokens.pop(0); tokens.pop(0); tokens.pop(0)
+
+    try:
+        parts = [p.strip() for p in inner.split(',') if p.strip()]
+
+        if keyword in _SALT_KEYWORDS:
+            if len(parts) != 1:
+                _param_warn(keyword, inner,
+                            f"expected exactly one number (k), got {len(parts)} value(s)")
+                return {}
+            k = float(parts[0])
+            if k <= 0:
+                _param_warn(keyword, inner,
+                            f"k must be > 0, got {k}")
+                return {}
+            return {'k': k}
+
+        elif keyword in _ALIGN_BRACKET_KEYWORDS:
+            if len(parts) != 2:
+                _param_warn(keyword, inner,
+                            f"expected exactly two numbers (D, S), got {len(parts)} value(s)")
+                return {}
+            d, s = int(float(parts[0])), int(float(parts[1]))
+            if not (2 <= d <= 32):
+                _param_warn(keyword, inner,
+                            f"D={d} is out of range [2, 32]")
+                return {}
+            if not (2 <= s <= 32):
+                _param_warn(keyword, inner,
+                            f"S={s} is out of range [2, 32]")
+                return {}
+            if d == s:
+                _param_warn(keyword, inner,
+                            f"D and S must differ (both are {d}); "
+                            "no structural distinction possible")
+                return {}
+            return {'d': d, 's': s}
+
+        elif keyword in _TOPK_KEYWORDS:
+            if len(parts) != 1:
+                _param_warn(keyword, inner,
+                            f"expected exactly one number (threshold), got {len(parts)} value(s)")
+                return {}
+            threshold = float(parts[0])
+            if not (0.0 < threshold <= 1.0):
+                _param_warn(keyword, inner,
+                            f"threshold must be in (0, 1], got {threshold}")
+                return {}
+            return {'threshold': threshold}
+
+    except (ValueError, IndexError) as exc:
+        _param_warn(keyword, inner, f"could not parse numbers: {exc}")
+
+    return {}
+
+
+def _param_warn(keyword: str, raw: str, reason: str) -> None:
+    """
+    Print a one-line parse warning to stderr.
+
+    Controlled by global_state.verbose so it doesn't spam quiet setups.
+    Imported lazily to avoid a circular import at module level.
+    """
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        if not _gs.verbose:
+            return
+    except ImportError:
+        pass  # if global_state is not yet available, always print
+    import sys
+    print(
+        f"[neutral-prompt] WARNING: invalid params for {keyword}[{raw}] — {reason}. "
+        "Ignoring bracket content; keyword will use its default behaviour.",
+        file=sys.stderr,
+    )
+
+
+def parse_prompt(tokens: List[str], *, first: bool, nested: bool = False) -> PromptExpr:
+    leading_affine: Optional[torch.Tensor] = None
+    if _looks_like_leading_affine_prompt(tokens):
+        probe = tokens.copy()
+        leading_affine = _parse_affine_transform(probe)
+        tokens[:] = probe
+
+    if tokens and tokens[0] in _prompt_keywords_set:
+        prompt_type = tokens.pop(0)
+    else:
+        prompt_type = PromptKeyword.AND.value
+
+    conciliation = ConciliationStrategy(prompt_type) if prompt_type in _conciliation_strategies_set else None
+
+    # Parse trailing affine once before params (handles AND_PERP ROTATE[0.25] text)
+    # and once after (handles AND_SALT[5] ROTATE[0.25] text).
+    trailing_affine_pre = _parse_affine_transform(tokens)
+
+    # Consume bracket params BEFORE composite-bracket check.
+    # This ensures AND_ALIGN[4,8] text is not confused with
+    # AND_ALIGN [child AND other] (composite form).
+    conciliation_params = _parse_keyword_params(tokens, prompt_type)
+
+    # Second trailing-affine pass: catches affine that comes AFTER [k] params.
+    trailing_affine_post = _parse_affine_transform(tokens)
+    trailing_affine = _compose_affine(trailing_affine_pre, trailing_affine_post)
+    affine_transform = _compose_affine(leading_affine, trailing_affine)
+
+    tokens_copy = tokens.copy()
+    if tokens_copy and tokens_copy[0] == '[':
+        tokens_copy.pop(0)
+        prompts = parse_prompts(tokens_copy, nested=True)
+        if tokens_copy:
+            assert tokens_copy.pop(0) == ']'
+        if len(prompts) > 1:
+            tokens[:] = tokens_copy
+            weight = _parse_weight(tokens)
+            return CompositePrompt(weight, conciliation, affine_transform, prompts, conciliation_params)
+
+    prompt_text, weight = _parse_prompt_text(tokens, nested=nested)
+    return LeafPrompt(weight, conciliation, affine_transform, prompt_text, conciliation_params)
+
+
+def _parse_prompt_text(tokens: List[str], *, nested: bool = False) -> Tuple[str, float]:
+    text = ''
+    depth = 0
+    weight = 1.0
+    while tokens:
+        tok = tokens[0]
+        if tok == ']':
+            if depth == 0:
+                if nested:
+                    break
+            else:
+                depth -= 1
+        elif tok == '[':
+            depth += 1
+        elif tok == ':':
+            if len(tokens) >= 2 and _is_float(tokens[1].strip()):
+                if len(tokens) < 3 or tokens[2] in _prompt_keywords_set or (tokens[2] == ']' and depth == 0):
+                    tokens.pop(0)
+                    weight = float(tokens.pop(0).strip())
+                    break
+        elif tok in _prompt_keywords_set:
+            break
+        elif depth == 0 and _looks_like_leading_affine_prompt(tokens):
+            break
+        text += tokens.pop(0)
+    return text, weight
+
+
+def _parse_affine_transform(tokens: List[str]) -> Optional[torch.Tensor]:
+    tokens_copy = tokens.copy()
+    if tokens_copy and not tokens_copy[0].strip():
+        tokens_copy.pop(0)
+
+    affine_funcs = []
+
+    while tokens_copy and tokens_copy[0] in affine_transforms:
+        func = affine_transforms[tokens_copy.pop(0)]
+        args: List[float] = []
+
+        if not (tokens_copy and tokens_copy[0] == '['):
+            break
+        tokens_copy.pop(0)
+
+        if tokens_copy and tokens_copy[0] != ']':
+            if tokens_copy[0].strip():
+                try:
+                    args = [float(a.strip()) for a in tokens_copy.pop(0).split(',')]
+                except ValueError:
+                    break
+            else:
+                tokens_copy.pop(0)
+
+        if not (tokens_copy and tokens_copy[0] == ']'):
+            break
+        tokens_copy.pop(0)
+
+        affine_funcs.append(lambda t, f=func, a=args: f(t, *a))
+        if tokens_copy and not tokens_copy[0].strip():
+            tokens_copy.pop(0)
+        tokens[:] = tokens_copy
+
+    if not affine_funcs:
+        return None
+
+    transform = torch.eye(3, dtype=torch.float32)[:-1]
+    for fn in reversed(affine_funcs):
+        transform = fn(transform)
+    return transform
+
+
+def _parse_weight(tokens: List[str]) -> float:
+    if len(tokens) >= 2 and tokens[0] == ':' and _is_float(tokens[1]):
+        tokens.pop(0)
+        return float(tokens.pop(0))
+    return 1.0
+
+
+def tokenize(s: str) -> List[str]:
+    affine_kw_pattern = '|'.join(
+        rf'(?<!\w){kw}(?!\w)' for kw in affine_transforms
+    )
+    keyword_pattern = (
+        r'(?<!\w)AND_MASK_ALIGN_\d+_\d+(?!\w)'   # fixed-suffix (longest first)
+        r'|(?<!\w)AND_ALIGN_\d+_\d+(?!\w)'
+        r'|(?<!\w)AND_MASK_ALIGN(?!\w)'            # bare bracket-syntax keyword
+        r'|(?<!\w)AND_ALIGN(?!\w)'
+        r'|(?<!\w)AND_PERP(?!\w)'
+        r'|(?<!\w)AND_SALT_WIDE(?!\w)'
+        r'|(?<!\w)AND_SALT_BLOB(?!\w)'
+        r'|(?<!\w)AND_SALT(?!\w)'
+        r'|(?<!\w)AND_TOPK(?!\w)'
+        r'|(?<!\w)AND(?!\w)'
+    )
+    return [t for t in re.split(rf'(\[|\]|:|{keyword_pattern}|{affine_kw_pattern})', s) if t.strip()]
+
+
+def _is_float(s: str) -> bool:
+    try:
+        float(s)
+        return True
+    except ValueError:
+        return False
+
+
+if __name__ == '__main__':
+    cases = [
+        ('original AND_SALT',        'hello AND_SALT concept :1.0'),
+        ('original AND_ALIGN_4_8',   'hello AND_ALIGN_4_8 watercolor :0.5'),
+        ('new AND_SALT[5]',          'hello AND_SALT[5] concept :1.0'),
+        ('new AND_SALT_WIDE[3]',     'hello AND_SALT_WIDE[3] concept :0.8'),
+        ('new AND_SALT_BLOB[8]',     'hello AND_SALT_BLOB[8] concept :1.0'),
+        ('new AND_ALIGN[4,8]',       'hello AND_ALIGN[4,8] watercolor :0.5'),
+        ('new AND_MASK_ALIGN[6,12]', 'hello AND_MASK_ALIGN[6,12] structure :0.7'),
+        ('composite not eaten',      'hello AND_ALIGN[arst AND defg :2.0] :0.5'),
+    ]
+    for label, c in cases:
+        res = parse_root(c)
+        child = res.children[-1]
+        print(f'[{label}]')
+        print(f'  conciliation={child.conciliation}  params={child.conciliation_params}')

neutral_prompt_patcheds/lib_neutral_prompt/prompt_parser_hijack.py

@@ -0,0 +1,134 @@
+import re
+import logging
+from typing import List
+
+from lib_neutral_prompt import hijacker, global_state, neutral_prompt_parser
+from modules import script_callbacks, prompt_parser
+
+# ---------------------------------------------------------------------------
+# Fix: prompt_parser_fixed escapes standalone '&' as a multicond separator.
+# neutral_prompt_parser does NOT treat '&' as AND — it keeps it as literal text.
+# So a leaf like  "cat & dog"  transpiles to  "cat & dog :1.0",
+# and the patched prompt_parser splits that into 3 multicond branches instead of 1,
+# which shifts all batch_cond_indices and breaks PERP/SALT/affine.
+#
+# Solution: escape any standalone '&' inside leaf text with '\&' before handing
+# the string to the webui parser. The patched prompt_parser correctly unescapes
+# '\&' back to '&' during conditioning, so the model sees the original text.
+# ---------------------------------------------------------------------------
+
+_STANDALONE_AMP = re.compile(r'(?<!\\)(?<!\S)&(?!\S)')
+
+# ── debug logging ──────────────────────────────────────────────────────────
+# Set env variable NP_DEBUG=1 to enable verbose output in the A1111 console.
+# Example (Linux/Mac):   NP_DEBUG=1 python launch.py
+# Example (Windows cmd): set NP_DEBUG=1 && python launch.py
+import os as _os
+_DEBUG = _os.getenv("NP_DEBUG", "0").strip() not in ("0", "", "false", "no", "off")
+_log = logging.getLogger("neutral_prompt.hijack")
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _escape_leaf_ampersands(text: str) -> str:
+    """Escape standalone '&' so patched prompt_parser doesn't split a single
+    Neutral Prompt leaf into extra multicond branches.
+      "cat & dog"  ->  "cat \\& dog"
+      "R&D"        ->  "R&D"           (unchanged — not standalone)
+      "\\&"        ->  "\\&"           (unchanged — already escaped)
+    """
+    if not text or '&' not in text:
+        return text
+    return _STANDALONE_AMP.sub(r'\\&', text)
+
+
+prompt_parser_hijacker = hijacker.ModuleHijacker.install_or_get(
+    module=prompt_parser,
+    hijacker_attribute='__neutral_prompt_hijacker',
+    on_uninstall=script_callbacks.on_script_unloaded,
+)
+
+
+@prompt_parser_hijacker.hijack('get_multicond_prompt_list')
+def get_multicond_prompt_list_hijack(prompts, original_function):
+    if not global_state.is_enabled:
+        return original_function(prompts)
+
+    global_state.prompt_exprs = parse_prompts(prompts)
+    webui_prompts = transpile_exprs(global_state.prompt_exprs)
+
+    # ── debug: transpiled strings ──────────────────────────────────────────
+    if _DEBUG:
+        for i, (orig, transp) in enumerate(zip(prompts, webui_prompts)):
+            _log.warning(
+                "[NP_DEBUG] prompt[%d]\n"
+                "  original   : %r\n"
+                "  transpiled : %r\n"
+                "  branches   : %d",
+                i, orig, transp,
+                # count multicond splits the same way prompt_parser_fixed does
+                len(re.split(r'(?:\bAND\b|(?<!\S)&(?!\S))(?!_PERP|_SALT|_TOPK)', transp))
+            )
+    # ──────────────────────────────────────────────────────────────────────
+
+    if isinstance(prompts, getattr(prompt_parser, 'SdConditioning', type(None))):
+        webui_prompts = prompt_parser.SdConditioning(webui_prompts, copy_from=prompts)
+
+    result = original_function(webui_prompts)
+
+    # ── debug: multicond parts ─────────────────────────────────────────────
+    if _DEBUG:
+        conds_list, prompt_flat_list, prompt_indexes = result
+        _log.warning(
+            "[NP_DEBUG] get_multicond_prompt_list result\n"
+            "  prompt_flat_list : %r\n"
+            "  prompt_indexes   : %r\n"
+            "  conds_list       : %r",
+            list(prompt_flat_list),
+            dict(prompt_indexes),
+            conds_list,
+        )
+    # ──────────────────────────────────────────────────────────────────────
+
+    return result
+
+
+def parse_prompts(prompts: List[str]) -> List[neutral_prompt_parser.PromptExpr]:
+    exprs = []
+    for prompt in prompts:
+        expr = neutral_prompt_parser.parse_root(prompt)
+        exprs.append(expr)
+    return exprs
+
+
+def transpile_exprs(exprs: neutral_prompt_parser.PromptExpr):
+    webui_prompts = []
+    for expr in exprs:
+        webui_prompts.append(expr.accept(WebuiPromptVisitor()))
+    return webui_prompts
+
+
+class WebuiPromptVisitor:
+    def visit_leaf_prompt(self, that: neutral_prompt_parser.LeafPrompt) -> str:
+        prompt = _escape_leaf_ampersands(that.prompt)
+        return f'{prompt} :{that.weight}'
+
+    def visit_composite_prompt(self, that: neutral_prompt_parser.CompositePrompt) -> str:
+        return ' AND '.join(child.accept(self) for child in that.children)
+
+
+@prompt_parser_hijacker.hijack('reconstruct_multicond_batch')
+def reconstruct_multicond_batch_hijack(*args, original_function, **kwargs):
+    """Store batch_cond_indices for the pre-noise affine hook (affine branch)."""
+    res = original_function(*args, **kwargs)
+    global_state.batch_cond_indices = res[0]
+
+    # ── debug: batch_cond_indices ──────────────────────────────────────────
+    if _DEBUG:
+        _log.warning(
+            "[NP_DEBUG] reconstruct_multicond_batch\n"
+            "  batch_cond_indices : %r",
+            res[0],
+        )
+    # ──────────────────────────────────────────────────────────────────────
+
+    return res

neutral_prompt_patcheds/lib_neutral_prompt/protection_utils.py

@@ -0,0 +1,277 @@
+"""
+Base-prompt protection subsystem for sd-webui-neutral-prompt.
+
+Extracted from cfg_denoiser_hijack.py to form a standalone, testable module.
+
+Protection modes
+----------------
+off    — no guard at all; auxiliary children can dominate freely.
+auto   — structural guard: fires when the prompt tree lacks a top-level
+         base AND-child (every child has a conciliation keyword).
+strict — auto PLUS numerical: also fires when norm(base_delta)/norm(aux_delta)
+         falls below *strict_threshold*.  Falls back to standard A1111 CFG.
+soft   — auto structural guard + numerical attenuation: instead of a hard
+         fallback, attenuates the auxiliary delta so that
+         norm(base_delta) / norm(attenuated_aux_delta) ≈ soft_floor.
+         The image retains auxiliary influence but cannot overpower the base.
+
+All modes except 'off' print a diagnostic message when global_state.verbose=True.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional, Tuple
+
+import torch
+
+from lib_neutral_prompt import global_state, neutral_prompt_parser
+
+
+# ---------------------------------------------------------------------------
+# Structural checks (per-prompt, O(n) in children)
+# ---------------------------------------------------------------------------
+
+def prompt_has_valid_base_path(
+    prompt: neutral_prompt_parser.PromptExpr,
+) -> bool:
+    """
+    Per-prompt structural check.
+
+    Returns True iff *prompt* is a CompositePrompt with at least one top-level
+    child that carries no conciliation keyword (i.e. a plain base segment).
+    """
+    return (
+        isinstance(prompt, neutral_prompt_parser.CompositePrompt)
+        and any(c.conciliation is None for c in prompt.children)
+    )
+
+
+def get_invalid_base_prompt_indices(
+    prompt_exprs: List[neutral_prompt_parser.PromptExpr],
+) -> List[int]:
+    """
+    Return the 0-based indices of any prompts in the batch that lack a
+    valid base AND-path.  An empty return value means every prompt is OK.
+
+    Per-prompt rather than any(...): a healthy neighbour must not silently
+    legalise a broken prompt in the same batched request.
+    """
+    return [
+        i for i, p in enumerate(prompt_exprs)
+        if not prompt_has_valid_base_path(p)
+    ]
+
+
+def has_valid_base_path(
+    prompt_exprs: List[neutral_prompt_parser.PromptExpr],
+) -> bool:
+    """
+    Batch-level alias: True iff the batch is non-empty AND every prompt has a
+    valid base path.  An empty batch returns False (nothing to protect).
+    """
+    return bool(prompt_exprs) and len(get_invalid_base_prompt_indices(prompt_exprs)) == 0
+
+
+# Old private names kept for backward-compat (hijack still references them via import)
+_prompt_has_valid_base_path      = prompt_has_valid_base_path
+_get_invalid_base_prompt_indices = get_invalid_base_prompt_indices
+_has_valid_base_path             = has_valid_base_path
+
+
+# ---------------------------------------------------------------------------
+# Numerical helpers
+# ---------------------------------------------------------------------------
+
+def safe_norm(tensor: torch.Tensor) -> float:
+    """Return float L2-norm; 0.0 on any error (empty tensor, NaN, etc.)."""
+    try:
+        v = torch.linalg.norm(tensor.float()).item()
+        return v if v == v else 0.0   # NaN guard
+    except Exception:
+        return 0.0
+
+_safe_norm = safe_norm   # alias
+
+
+# ---------------------------------------------------------------------------
+# Soft-mode attenuation
+# ---------------------------------------------------------------------------
+
+def compute_soft_attenuation(
+    base_norm: float,
+    aux_norm: float,
+    threshold: float,
+) -> float:
+    """
+    Compute a [0, 1] scale factor for the auxiliary delta so that, after
+    scaling, the base/aux ratio reaches at least *threshold*.
+
+    When the ratio is already ≥ threshold returns 1.0 (no change).
+    When aux_norm ≈ 0 returns 1.0 (nothing to attenuate).
+
+    Formula: factor = min(1, base_norm / (aux_norm * threshold))
+    This ensures norm(base) / norm(factor * aux) ≈ threshold.
+    """
+    if aux_norm < 1e-8 or base_norm < 0:
+        return 1.0
+    ratio = base_norm / aux_norm
+    if ratio >= threshold:
+        return 1.0
+    # factor so that base / (factor * aux) = threshold  ↔  factor = base / (aux * threshold)
+    return max(0.0, base_norm / (aux_norm * threshold))
+
+
+# ---------------------------------------------------------------------------
+# Primary policy function
+# ---------------------------------------------------------------------------
+
+def should_fallback_for_protection(
+    x_out: torch.Tensor,
+    batch_cond_indices: List[List],
+    text_uncond: torch.Tensor,
+    # These visitors are injected to avoid circular imports
+    CondDeltaVisitor,        # noqa: N803
+    AuxCondDeltaVisitor,     # noqa: N803
+    DenoiseArgs,             # noqa: N803
+) -> Tuple[bool, Optional[str]]:
+    """
+    Decide whether to fall back to standard CFG.
+
+    Returns ``(should_fallback: bool, reason: str | None)``.
+
+    Modes:
+      'off'    → (False, None)   — never fires.
+      'auto'   → structural check only.
+      'strict' → structural check + numerical ratio check → hard fallback.
+      'soft'   → structural check only → (False, None); attenuation is
+                 handled separately by apply_soft_attenuation_if_needed().
+    """
+    mode = global_state.normalize_protection_mode(global_state.protection_mode)
+
+    if mode == 'off':
+        return False, None
+
+    # --- Structural check (auto / strict / soft) — per-prompt ---
+    invalid_indices = get_invalid_base_prompt_indices(global_state.prompt_exprs)
+    if invalid_indices:
+        reason = (
+            f'no valid base AND-path for prompt index/indices {invalid_indices} '
+            f'(mode={mode}). '
+            'Those segments have only conciliation keywords (AND_PERP / AND_SALT / ...). '
+            'Add a plain base prompt before AND_* segments, '
+            'or set protection to "off" to allow this intentionally.'
+        )
+        return True, reason
+
+    # Soft mode only does structural check; numerical handling is done in-place.
+    if mode in ('auto', 'soft'):
+        return False, None
+
+    # --- Numerical check (strict only) ---
+    threshold = global_state.clamp_strict_threshold(global_state.strict_threshold)
+    uncond = x_out[-text_uncond.shape[0]:]
+
+    for batch_i, (prompt, cond_indices) in enumerate(
+            zip(global_state.prompt_exprs, batch_cond_indices)):
+        args       = DenoiseArgs(x_out, uncond[batch_i], cond_indices)
+        base_delta = prompt.accept(CondDeltaVisitor(), args, 0)
+        aux_delta  = prompt.accept(AuxCondDeltaVisitor(), args, base_delta, 0)
+
+        base_norm = safe_norm(base_delta)
+        aux_norm  = safe_norm(aux_delta)
+
+        if aux_norm < 1e-8:
+            continue
+
+        ratio = base_norm / aux_norm
+        if ratio < threshold:
+            return (
+                True,
+                f'base/aux ratio {ratio:.4f} < threshold {threshold:.4f} '
+                f'(prompt #{batch_i}, mode=strict). '
+                'Base contribution is too weak relative to auxiliary. '
+                'Lower the strict threshold or switch to "auto" to allow this.',
+            )
+
+    return False, None
+
+
+def apply_soft_attenuation_if_needed(
+    aux_delta: torch.Tensor,
+    base_delta: torch.Tensor,
+    prompt_index: int,
+) -> Tuple[torch.Tensor, Optional[str]]:
+    """
+    For 'soft' mode: attenuate *aux_delta* in-place (returns new tensor) so
+    that norm(base)/norm(aux) ≥ soft_threshold.
+
+    Returns ``(possibly_attenuated_aux_delta, diagnostic_note | None)``.
+    Called per-prompt inside the combine_denoised loop.
+    """
+    mode = global_state.normalize_protection_mode(global_state.protection_mode)
+    if mode != 'soft':
+        return aux_delta, None
+
+    threshold  = global_state.clamp_strict_threshold(global_state.strict_threshold)
+    base_norm  = safe_norm(base_delta)
+    aux_norm   = safe_norm(aux_delta)
+    factor     = compute_soft_attenuation(base_norm, aux_norm, threshold)
+
+    if factor >= 1.0:
+        return aux_delta, None
+
+    note = (
+        f'[soft protection] prompt #{prompt_index}: '
+        f'base/aux ratio {base_norm / aux_norm:.4f} < {threshold:.4f}; '
+        f'attenuating aux × {factor:.3f}'
+    )
+    if global_state.verbose:
+        print(f'[neutral-prompt] {note}', file=sys.stderr)
+
+    return aux_delta * factor, note
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics helpers (used by matryoshka_utils explain panel)
+# ---------------------------------------------------------------------------
+
+def protection_verdict(
+    prompt_str: str,
+) -> Tuple[str, str]:
+    """
+    Structural-only verdict for the debug/explain panel.
+
+    Returns (status, message) where status is 'ok', 'fire', or 'off'.
+    Does not simulate runtime ratio checks or batch state.
+    """
+    from lib_neutral_prompt import neutral_prompt_parser as _p
+    mode = global_state.normalize_protection_mode(global_state.protection_mode)
+
+    if mode == 'off':
+        return 'off', 'Guard disabled — no fallback will occur'
+
+    try:
+        root = _p.parse_root(prompt_str)
+    except Exception:
+        return 'fire', 'Parse failed — cannot determine base-path'
+
+    if isinstance(root, _p.CompositePrompt):
+        has_base = any(c.conciliation is None for c in root.children)
+    else:
+        has_base = root.conciliation is None
+
+    if not has_base:
+        return 'fire', 'WOULD FIRE — no plain base segment at the top level'
+
+    suffix = ''
+    if mode == 'strict':
+        thr = global_state.clamp_strict_threshold(global_state.strict_threshold)
+        suffix = f'\n  Strict ratio check ({thr:.2f}) runs at generation time'
+    elif mode == 'soft':
+        thr = global_state.clamp_strict_threshold(global_state.strict_threshold)
+        suffix = (
+            f'\n  Soft attenuation active: aux will be scaled if '
+            f'base/aux ratio < {thr:.2f}'
+        )
+    return 'ok', f'OK — base segment present{suffix}'

neutral_prompt_patcheds/lib_neutral_prompt/step_utils.py

@@ -0,0 +1,454 @@
+"""
+Step-window activation control for sd-webui-neutral-prompt.
+
+Allows AND_* strategies to be active only during a sub-range of the denoising
+process, specified as a normalised progress window [start, end] ∈ [0, 1].
+
+Typical use:
+  - AND_ALIGN / AND_PERP  : early steps (0.0–0.5) for structure/composition
+  - AND_SALT / AND_TOPK   : late steps  (0.5–1.0) for texture/detail
+
+Three levels of control (coarse to fine):
+  1. Global window     — applies to ALL AND_* strategies.
+  2. Per-strategy window — overrides global for a specific strategy family.
+  3. Per-node window   — (future) per-node override inside matryoshka trees.
+
+This module is intentionally pure (no torch, no gradio) so it can be
+imported in both UI and runtime without side effects.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Dict, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class StepWindow:
+    """A normalised [start, end] activation window.
+
+    start and end are clamped to [0, 1] with start ≤ end.
+    An all-active window is StepWindow(0.0, 1.0).
+    """
+    start: float = 0.0
+    end:   float = 1.0
+
+    def __post_init__(self) -> None:
+        # Use object.__setattr__ because the dataclass is frozen
+        object.__setattr__(self, 'start', max(0.0, min(1.0, float(self.start))))
+        object.__setattr__(self, 'end',   max(0.0, min(1.0, float(self.end))))
+        if self.start > self.end:
+            object.__setattr__(self, 'end', self.start)
+
+    def is_active_at(self, progress: float) -> bool:
+        """Return True if *progress* ∈ [start, end] (inclusive)."""
+        return self.start <= progress <= self.end
+
+    def __repr__(self) -> str:
+        return f'StepWindow({self.start:.2f}–{self.end:.2f})'
+
+
+ALWAYS_ACTIVE = StepWindow(0.0, 1.0)
+
+
+# ---------------------------------------------------------------------------
+# Strategy-family presets
+# ---------------------------------------------------------------------------
+# These are sensible defaults reflecting typical SD denoising behaviour:
+#   - Global structure/composition → early steps
+#   - Local texture/detail         → late steps
+# Users can override any entry via the UI.
+
+STRATEGY_DEFAULTS: Dict[str, StepWindow] = {
+    'PERPENDICULAR':                StepWindow(0.0, 0.5),   # composition correction
+    'SALIENCE_MASK':                StepWindow(0.4, 1.0),   # local texture detail
+    'SALIENCE_MASK_WIDE':           StepWindow(0.3, 1.0),   # broad region texture
+    'SALIENCE_MASK_BLOB':           StepWindow(0.4, 1.0),   # blob region
+    'SEMANTIC_GUIDANCE':            StepWindow(0.4, 1.0),   # sparse semantic detail
+    'ALIGNMENT_BLEND_CUSTOM':       StepWindow(0.0, 0.6),   # alignment preserves structure
+    'ALIGNMENT_MASK_BLEND_CUSTOM':  StepWindow(0.0, 0.6),
+}
+
+
+def _strategy_family(strategy_name: str) -> str:
+    """
+    Map a concrete ConciliationStrategy name (including legacy fixed-suffix
+    variants like 'ALIGNMENT_BLEND_4_8') to a canonical family key.
+    """
+    if strategy_name.startswith('ALIGNMENT_MASK_BLEND_'):
+        return 'ALIGNMENT_MASK_BLEND_CUSTOM'
+    if strategy_name.startswith('ALIGNMENT_BLEND_'):
+        return 'ALIGNMENT_BLEND_CUSTOM'
+    return strategy_name
+
+
+# ---------------------------------------------------------------------------
+# Progress normalisation
+# ---------------------------------------------------------------------------
+
+def normalize_progress(current_step: int, total_steps: int) -> float:
+    """
+    Convert an absolute step index to a normalised progress value in [0, 1].
+
+    The first step (index 0) maps to 0.0 and the last step (index
+    total_steps - 1) maps to 1.0.  Edge-cases:
+
+        total_steps = 1  →  always returns 0.0
+        step 19 of 20 → 1.00
+    """
+    denom = max(total_steps - 1, 1)
+    return max(0.0, min(1.0, current_step / denom))
+
+
+def normalize_step_range(start, end) -> 'Tuple[float, float]':
+    """
+    Parse and clamp a (start, end) pair to [0, 1].
+
+    If start > end after clamping, returns (0.0, 1.0) — full range fallback.
+    Accepts floats, ints, or stringified numbers.
+    """
+    try:
+        s = max(0.0, min(1.0, float(start)))
+    except (TypeError, ValueError):
+        s = 0.0
+    try:
+        e = max(0.0, min(1.0, float(end)))
+    except (TypeError, ValueError):
+        e = 1.0
+    if s > e:
+        return 0.0, 1.0
+    return s, e
+
+
+# Canonical UI names for each per-strategy group (user-facing labels)
+STRATEGY_UI_KEYS = [
+    'AND_PERP',
+    'AND_SALT',
+    'AND_SALT_WIDE',
+    'AND_SALT_BLOB',
+    'AND_TOPK',
+    'AND_ALIGN',
+    'AND_MASK_ALIGN',
+]
+
+# Map UI key → canonical family name used in strategy_is_active
+_UI_KEY_TO_FAMILY: Dict[str, str] = {
+    'AND_PERP':       'PERPENDICULAR',
+    'AND_SALT':       'SALIENCE_MASK',
+    'AND_SALT_WIDE':  'SALIENCE_MASK_WIDE',
+    'AND_SALT_BLOB':  'SALIENCE_MASK_BLOB',
+    'AND_TOPK':       'SEMANTIC_GUIDANCE',
+    'AND_ALIGN':      'ALIGNMENT_BLEND_CUSTOM',
+    'AND_MASK_ALIGN': 'ALIGNMENT_MASK_BLEND_CUSTOM',
+}
+
+_FAMILY_TO_UI_KEY: Dict[str, str] = {v: k for k, v in _UI_KEY_TO_FAMILY.items()}
+
+
+def ui_key_to_family(ui_key: str) -> str:
+    """Convert an AND_* UI key to its canonical family name."""
+    return _UI_KEY_TO_FAMILY.get(ui_key, ui_key)
+
+
+def family_to_ui_key(family: str) -> str:
+    """Convert a family name back to its AND_* UI key."""
+    return _FAMILY_TO_UI_KEY.get(family, family)
+
+
+def build_per_strategy_windows(
+    custom_dict: Dict[str, 'Tuple[float, float]'],
+) -> Dict[str, StepWindow]:
+    """
+    Convert a raw {AND_* UI key → (start, end)} dict to the
+    {family_name → StepWindow} format expected by strategy_is_active.
+
+    Entries with invalid ranges are repaired by normalize_step_range.
+    Unrecognised keys are silently skipped.
+    """
+    result: Dict[str, StepWindow] = {}
+    for ui_key, (start, end) in custom_dict.items():
+        if ui_key not in _UI_KEY_TO_FAMILY:
+            continue   # silently skip unrecognised keys
+        family = ui_key_to_family(ui_key)
+        s, e = normalize_step_range(start, end)
+        result[family] = StepWindow(s, e)
+    return result
+
+
+def default_custom_windows() -> Dict[str, 'Tuple[float, float]']:
+    """
+    Return the STRATEGY_DEFAULTS as a {AND_* UI key → (start, end)} dict —
+    the natural starting point for the per-strategy custom editor.
+    """
+    out: Dict[str, 'Tuple[float, float]'] = {}
+    for family, win in STRATEGY_DEFAULTS.items():
+        ui_key = _FAMILY_TO_UI_KEY.get(family)
+        if ui_key:
+            out[ui_key] = (win.start, win.end)
+    return out
+
+
+def serialize_per_strategy_windows(
+    custom_dict: Dict[str, 'Tuple[float, float]'],
+) -> str:
+    """
+    Serialise to a compact string for generation params / infotext.
+
+    Format: ``AND_PERP:0.00-0.50,AND_SALT:0.40-1.00,...``
+    """
+    parts = []
+    for ui_key in STRATEGY_UI_KEYS:
+        if ui_key in custom_dict:
+            s, e = custom_dict[ui_key]
+            parts.append(f'{ui_key}:{s:.4f}-{e:.4f}')
+    return ','.join(parts)
+
+
+def deserialize_per_strategy_windows(
+    raw: str,
+) -> Dict[str, 'Tuple[float, float]']:
+    """
+    Parse the compact string back to {AND_* UI key → (start, end)}.
+    Tolerates malformed entries (skips them silently).
+    """
+    result: Dict[str, 'Tuple[float, float]'] = {}
+    for token in raw.split(','):
+        token = token.strip()
+        if not token:
+            continue
+        if ':' not in token or '-' not in token:
+            continue
+        try:
+            ui_key, range_part = token.split(':', 1)
+            ui_key = ui_key.strip()
+            start_str, end_str = range_part.split('-', 1)
+            s, e = normalize_step_range(start_str.strip(), end_str.strip())
+            if ui_key in _UI_KEY_TO_FAMILY:
+                result[ui_key] = (s, e)
+        except Exception:
+            continue
+    return result
+
+
+
+    """
+    Convert an absolute step counter to a normalised progress value [0, 1].
+
+    Examples:
+        step 0  of 20 → 0.00
+        step 10 of 20 → 0.526  (10/19)
+        step 19 of 20 → 1.00
+    """
+    denom = max(total_steps - 1, 1)
+    return max(0.0, min(1.0, current_step / denom))
+
+
+# ---------------------------------------------------------------------------
+# Activation decision
+# ---------------------------------------------------------------------------
+
+def strategy_is_active(
+    strategy_name: str,
+    progress: float,
+    global_window: Optional[StepWindow] = None,
+    per_strategy_windows: Optional[Dict[str, StepWindow]] = None,
+    use_defaults: bool = False,
+) -> bool:
+    """
+    Return True if *strategy_name* should be applied at the given *progress*.
+
+    Priority order (highest wins):
+      1. Per-strategy window (if provided and contains this strategy's family).
+      2. Global window (if provided).
+      3. STRATEGY_DEFAULTS (if use_defaults=True).
+      4. ALWAYS_ACTIVE otherwise.
+
+    Parameters
+    ----------
+    strategy_name :
+        ConciliationStrategy.name or a raw strategy string.
+    progress :
+        Normalised step progress in [0, 1].
+    global_window :
+        A single window applied to every strategy (unless overridden).
+    per_strategy_windows :
+        Dict mapping strategy family name → StepWindow.  Overrides global.
+    use_defaults :
+        If True, fall back to STRATEGY_DEFAULTS when no explicit window is set.
+    """
+    family = _strategy_family(strategy_name)
+
+    # Per-strategy override
+    if per_strategy_windows and family in per_strategy_windows:
+        return per_strategy_windows[family].is_active_at(progress)
+
+    # Global override
+    if global_window is not None:
+        return global_window.is_active_at(progress)
+
+    # Preset defaults
+    if use_defaults and family in STRATEGY_DEFAULTS:
+        return STRATEGY_DEFAULTS[family].is_active_at(progress)
+
+    return True   # ALWAYS_ACTIVE
+
+
+# ---------------------------------------------------------------------------
+# global_state integration helpers
+# ---------------------------------------------------------------------------
+
+def get_global_window() -> Optional[StepWindow]:
+    """Read the global step window from global_state (may be None = disabled)."""
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        return _gs.step_window_global
+    except AttributeError:
+        return None
+
+
+def get_per_strategy_windows() -> Dict[str, StepWindow]:
+    """Read per-strategy windows from global_state (empty dict if not set)."""
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        return _gs.step_window_per_strategy or {}
+    except AttributeError:
+        return {}
+
+
+def get_use_defaults() -> bool:
+    """Read whether STRATEGY_DEFAULTS are active."""
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        return bool(_gs.step_window_use_defaults)
+    except AttributeError:
+        return False
+
+
+def strategy_is_active_from_state(
+    strategy_name: str,
+    progress: float,
+) -> bool:
+    """
+    Convenience wrapper: read all step-window settings from global_state and
+    return whether *strategy_name* is active at *progress*.
+
+    Also handles Lock after End: if ``global_state.step_window_lock_after_end``
+    is True and the strategy's window has ended, it sets a permanent lock flag
+    in ``global_state._step_lock_flags[family]`` and returns False for all
+    subsequent calls this generation.
+    """
+    from lib_neutral_prompt import global_state as _gs
+
+    family = _strategy_family(strategy_name)
+
+    # ── Lock after End: check permanent lock first ─────────────────────────
+    lock_enabled = getattr(_gs, 'step_window_lock_after_end', False)
+    if lock_enabled:
+        lock_flags = getattr(_gs, '_step_lock_flags', None)
+        if lock_flags is None:
+            _gs._step_lock_flags = {}
+            lock_flags = _gs._step_lock_flags
+        if lock_flags.get(family, False):
+            return False   # permanently frozen this generation
+
+    # ── Normal activity check ───────────────────────────────────────────────
+    active = strategy_is_active(
+        strategy_name,
+        progress,
+        global_window=get_global_window(),
+        per_strategy_windows=get_per_strategy_windows(),
+        use_defaults=get_use_defaults(),
+    )
+
+    # ── Lock after End: set flag when window has closed ─────────────────────
+    if lock_enabled and not active:
+        # Only lock once we have actually been past the window start
+        # (avoids locking strategies that haven't started yet)
+        window = _resolve_window_for_family(family)
+        if window is not None and progress >= window.start:
+            # We were inside the window at some point; window has now ended
+            lock_flags[family] = True  # type: ignore[index]
+
+    return active
+
+
+def _resolve_window_for_family(family: str) -> Optional[StepWindow]:
+    """
+    Return the effective StepWindow for *family* given the current global_state,
+    or None if no window restriction applies.
+    Used by Lock after End to decide whether to set the lock flag.
+    """
+    try:
+        from lib_neutral_prompt import global_state as _gs
+        per = getattr(_gs, 'step_window_per_strategy', None) or {}
+        if family in per:
+            return per[family]
+        gw = getattr(_gs, 'step_window_global', None)
+        if gw is not None:
+            return gw
+        if getattr(_gs, 'step_window_use_defaults', False):
+            return STRATEGY_DEFAULTS.get(family)
+    except Exception:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Explain / diagnostic summary
+# ---------------------------------------------------------------------------
+
+def render_step_window_summary(
+    strategies: list,
+    progress: Optional[float] = None,
+    global_window: Optional[StepWindow] = None,
+    per_strategy_windows: Optional[Dict[str, StepWindow]] = None,
+    use_defaults: bool = False,
+) -> str:
+    """
+    Build a human-readable summary of step-window settings for the debug panel.
+
+    *strategies* is a list of strategy-name strings (from diagnostics['strategies']).
+    *progress* is the current (or hypothetical) normalised step (optional).
+    """
+    if not strategies:
+        return ''
+
+    lines = ['── Step windows ─────────────────────────']
+
+    # Header: show effective global window or "all steps"
+    if global_window is not None:
+        lines.append(f'Global window : {global_window}')
+    elif use_defaults:
+        lines.append('Global window : (per-strategy defaults active)')
+    else:
+        lines.append('Global window : all steps (no restriction)')
+
+    for s in strategies:
+        if s == 'BASE':
+            continue
+        family = _strategy_family(s)
+        # Resolve effective window
+        if per_strategy_windows and family in per_strategy_windows:
+            win = per_strategy_windows[family]
+            src = 'custom'
+        elif global_window is not None:
+            win = global_window
+            src = 'global'
+        elif use_defaults and family in STRATEGY_DEFAULTS:
+            win = STRATEGY_DEFAULTS[family]
+            src = 'default'
+        else:
+            win = ALWAYS_ACTIVE
+            src = 'always'
+
+        if progress is not None:
+            active = '✓ active' if win.is_active_at(progress) else '✗ gated'
+            lines.append(f'  {s:32s} {win}  [{src}]  @ {progress:.2f} → {active}')
+        else:
+            lines.append(f'  {s:32s} {win}  [{src}]')
+
+    return '\n'.join(lines)

neutral_prompt_patcheds/lib_neutral_prompt/ui.py

@@ -0,0 +1,811 @@
+"""
+Gradio UI for sd-webui-neutral-prompt  — v1.1 "Matryoshka visibility"
+
+New in v1.1:
+  - Tree-style debug/explain with branch connectors and full diagnostics
+  - Matryoshka builder v1: 2-level visual composer with live preview
+  - Matryoshka templates: 7 ready-made nested recipes
+  - AND_TOPK[threshold] slider
+  - Affine transform builder with presets
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Tuple
+import dataclasses
+import gradio as gr
+
+from lib_neutral_prompt import global_state, neutral_prompt_parser
+from lib_neutral_prompt.matryoshka_utils import (
+    build_child_block,
+    build_nested_prompt,
+    render_prompt_node,
+    render_prompt_tree,
+    collect_prompt_diagnostics,
+    render_diagnostics,
+    render_full_explain,
+    MATRYOSHKA_TEMPLATES,
+    BUILDER_STRATEGIES,
+    _KW_DEFAULTS,
+)
+from lib_neutral_prompt.affine_utils import (
+    AFFINE_TRANSFORMS as _AFFINE_TRANSFORMS,
+    AFFINE_PRESETS    as _AFFINE_PRESETS,
+    build_affine_snippet as _build_affine_snippet,
+)
+from lib_neutral_prompt.step_utils import (
+    StepWindow, STRATEGY_DEFAULTS,
+    STRATEGY_UI_KEYS as _STRATEGY_UI_KEYS,
+    build_per_strategy_windows as _build_per_strategy_windows,
+    serialize_per_strategy_windows as _serialize_per_strategy_windows,
+    deserialize_per_strategy_windows as _deserialize_per_strategy_windows,
+    default_custom_windows as _step_default_custom,
+)
+from modules import script_callbacks, shared
+
+
+txt2img_prompt_textbox = None
+img2img_prompt_textbox = None
+
+
+# ---------------------------------------------------------------------------
+# Prompt-type registry
+# ---------------------------------------------------------------------------
+
+prompt_types: Dict[str, str] = {
+    'Perpendicular (AND_PERP)':                neutral_prompt_parser.PromptKeyword.AND_PERP.value,
+    'Saliency sharp (AND_SALT)':               neutral_prompt_parser.PromptKeyword.AND_SALT.value,
+    'Saliency blob (AND_SALT_BLOB)':           neutral_prompt_parser.PromptKeyword.AND_SALT_BLOB.value,
+    'Saliency wide / classic (AND_SALT_WIDE)': neutral_prompt_parser.PromptKeyword.AND_SALT_WIDE.value,
+    'Semantic guidance top-k (AND_TOPK)':      neutral_prompt_parser.PromptKeyword.AND_TOPK.value,
+    'Alignment blend — custom D/S (AND_ALIGN)':      neutral_prompt_parser.PromptKeyword.AND_ALIGN.value,
+    'Alignment mask — custom D/S (AND_MASK_ALIGN)':  neutral_prompt_parser.PromptKeyword.AND_MASK_ALIGN.value,
+}
+for _d, _s in ((2, 4), (2, 8), (4, 8), (4, 16), (8, 16), (8, 32)):
+    prompt_types[f'Alignment blend  detail={_d}  structure={_s}  (AND_ALIGN_{_d}_{_s})'] = \
+        getattr(neutral_prompt_parser.PromptKeyword, f'AND_ALIGN_{_d}_{_s}').value
+    prompt_types[f'Alignment mask   detail={_d}  structure={_s}  (AND_MASK_ALIGN_{_d}_{_s})'] = \
+        getattr(neutral_prompt_parser.PromptKeyword, f'AND_MASK_ALIGN_{_d}_{_s}').value
+
+_SALT_LABELS  = frozenset({'Saliency sharp (AND_SALT)', 'Saliency blob (AND_SALT_BLOB)',
+                            'Saliency wide / classic (AND_SALT_WIDE)'})
+_TOPK_LABELS  = frozenset({'Semantic guidance top-k (AND_TOPK)'})
+_ALIGN_CUSTOM_LABELS = frozenset({'Alignment blend — custom D/S (AND_ALIGN)',
+                                   'Alignment mask — custom D/S (AND_MASK_ALIGN)'})
+
+prompt_types_tooltip = (
+    'AND               – add all features equally (webui built-in)\n'
+    'AND_PERP          – reduce contradicting features via perpendicular projection\n'
+    'AND_SALT[k]       – sharp saliency mask  (default k=5; higher k → fewer pixels)\n'
+    'AND_SALT_BLOB[k]  – blob saliency: grown seed region\n'
+    'AND_SALT_WIDE[k]  – broad saliency mask  (default k=1; ~55% of pixels)\n'
+    'AND_TOPK[t]       – small targeted changes (top-t fraction; default 0.05)\n'
+    '\n'
+    'AND_ALIGN[D,S]      – soft blend: detail without breaking structure\n'
+    'AND_MASK_ALIGN[D,S] – binary-mask variant of AND_ALIGN\n'
+    '  D = detail kernel [2,32]   S = structure kernel [2,32]   D ≠ S\n'
+    '\n'
+    'Affine: ROTATE[angle]  SLIDE[x,y]  SCALE[x,y]  SHEAR[x,y]\n'
+    '\n'
+    'Matryoshka nesting: AND_SALT[5] [ inner text AND_TOPK[0.1] detail ]'
+)
+
+
+def _build_keyword(label: str, salt_k: float, align_d: int, align_s: int,
+                   topk_threshold: float = 0.05) -> str:
+    kw = prompt_types[label]
+    if label in _SALT_LABELS:
+        return f'{kw}[{salt_k}]'
+    if label in _TOPK_LABELS:
+        return f'{kw}[{topk_threshold}]'
+    if label in _ALIGN_CUSTOM_LABELS:
+        d, s = int(align_d), int(align_s)
+        if d != s and 2 <= d <= 32 and 2 <= s <= 32:
+            return f'{kw}[{d},{s}]'
+    return kw
+
+
+
+def _build_step_window_preview(mode: str, start: float, end: float,
+                               custom_raw: Optional[Dict] = None) -> str:
+    """Build a human-readable summary of the step-window setting."""
+    if mode == 'global':
+        win = StepWindow(start, end)
+        lines = [f'Global window: {win}', '']
+        for strat in ('PERPENDICULAR', 'SALIENCE_MASK', 'SALIENCE_MASK_WIDE',
+                      'SEMANTIC_GUIDANCE', 'ALIGNMENT_BLEND_CUSTOM'):
+            lines.append(f'  {strat:34s} → {win}')
+        return '\n'.join(lines)
+    elif mode == 'per-strategy defaults':
+        lines = ['Per-strategy defaults:', '']
+        for strat, win in STRATEGY_DEFAULTS.items():
+            lines.append(f'  {strat:34s} → {win}')
+        return '\n'.join(lines)
+    elif mode == 'per-strategy custom' and custom_raw:
+        from lib_neutral_prompt.step_utils import StepWindow as _SW, normalize_step_range
+        lines = ['Per-strategy custom windows:', '']
+        for ui_key in _STRATEGY_UI_KEYS:
+            if ui_key in custom_raw:
+                s, e = custom_raw[ui_key]
+                lines.append(f'  {ui_key:16s} → {_SW(s, e)}')
+        return '\n'.join(lines)
+    return ''
+
+
+# ---------------------------------------------------------------------------
+# UI component class
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class AccordionInterface:
+    get_elem_id: Callable[[str], str]
+
+    def __post_init__(self):
+        self.is_rendered = False
+
+        self.cfg_rescale = gr.Slider(
+            label='CFG rescale φ', minimum=0, maximum=1, value=0,
+            info='0 = disabled. Rescales CFG output to reduce over-saturation.',
+        )
+
+        # --- Base-prompt protection ---
+        self.protection_mode = gr.Radio(
+            label='Base prompt protection', choices=['off', 'auto', 'strict', 'soft'],
+            value=global_state.protection_mode,
+            info=(
+                'off — no guard.  '
+                'auto — structural guard (hard fallback).  '
+                'strict — structural + ratio guard (hard fallback).  '
+                'soft — structural guard + ratio attenuation (no fallback, visible effect).'
+            ),
+        )
+        self.strict_threshold = gr.Slider(
+            label='Ratio threshold  (strict / soft)', minimum=0.01, maximum=0.5, step=0.01,
+            value=global_state.strict_threshold,
+            info='strict: fallback when base/aux < threshold.  soft: attenuate aux until ratio ≥ threshold.',
+            visible=(global_state.normalize_protection_mode(global_state.protection_mode) in ('strict', 'soft')),
+        )
+
+        # --- Prompt formatter ---
+        self.neutral_prompt = gr.Textbox(
+            label='Neutral prompt', show_label=False, lines=3,
+            placeholder='Auxiliary prompt  (press "Apply to prompt" to append)',
+        )
+        self.neutral_cond_scale = gr.Slider(label='Prompt weight', minimum=-3, maximum=3, value=1)
+        self.aux_prompt_type = gr.Dropdown(
+            label='Prompt type', choices=list(prompt_types.keys()),
+            value=next(iter(prompt_types.keys())), info=prompt_types_tooltip,
+            elem_id=self.get_elem_id('formatter_prompt_type'),
+        )
+        _def = next(iter(prompt_types.keys()))
+        self.salt_k = gr.Slider(
+            label='Salience sharpness k', minimum=0.5, maximum=20.0, step=0.5, value=5.0,
+            info='Low k → broad. High k → surgical. Default 5.',
+            visible=(_def in _SALT_LABELS),
+        )
+        self.topk_threshold = gr.Slider(
+            label='Top-k threshold', minimum=0.01, maximum=0.5, step=0.01, value=0.05,
+            info='Fraction of elements that receive the contribution. Default 0.05.',
+            visible=(_def in _TOPK_LABELS),
+        )
+        self.align_detail = gr.Slider(
+            label='Alignment detail kernel D', minimum=2, maximum=32, step=1, value=4,
+            info='Fine detail kernel size. D ≠ S.', visible=False,
+        )
+        self.align_structure = gr.Slider(
+            label='Alignment structure kernel S', minimum=2, maximum=32, step=1, value=8,
+            info='Global structure kernel size. D ≠ S.', visible=False,
+        )
+        self.append_to_prompt_button = gr.Button(value='Apply to prompt')
+
+        # --- Affine formatter ---
+        self.affine_preset = gr.Dropdown(
+            label='Affine preset', choices=list(_AFFINE_PRESETS.keys()), value='Custom',
+        )
+        self.affine_transform = gr.Dropdown(
+            label='Transform', choices=_AFFINE_TRANSFORMS, value='ROTATE',
+        )
+        self.affine_p1 = gr.Slider(
+            label='Parameter 1 (angle / x / scale)', minimum=-2.0, maximum=2.0, step=0.01,
+            value=0.125,
+            info='ROTATE: turns (0.25=90°). SCALE/SLIDE/SHEAR: x-component.',
+        )
+        self.affine_p2 = gr.Slider(
+            label='Parameter 2 (y / scale-y)', minimum=-2.0, maximum=2.0, step=0.01, value=1.0,
+            info='y-component. Ignored for ROTATE, FLIP_H, FLIP_V.',
+        )
+        self.affine_preview = gr.Textbox(
+            label='Affine snippet', interactive=False,
+            value=_build_affine_snippet('ROTATE', 0.125, 1.0),
+        )
+        self.affine_insert_button = gr.Button(value='Insert affine into prompt')
+
+        # --- Step window ---
+        self.step_window_enabled = gr.Checkbox(
+            label='Enable step-window gating for AND_*', value=False,
+            info='Restrict each strategy to a sub-range of the denoising steps.',
+        )
+        self.step_window_lock = gr.Checkbox(
+            label='🔒 Lock after End', value=False, visible=False,
+            info='После последнего активного диапазона — заморозить навсегда. '
+                 'Стратегия не возобновится, даже если шаги войдут в другой диапазон.',
+        )
+        self.step_window_mode = gr.Radio(
+            label='Step window mode',
+            choices=['global', 'per-strategy defaults', 'per-strategy custom'],
+            value='global', visible=False,
+            info='"global" applies one window to all AND_* strategies.  '
+                 '"per-strategy defaults" uses built-in schedule (PERP/ALIGN early, SALT/TOPK late).  '
+                 '"per-strategy custom" lets you set each window independently.',
+        )
+        self.step_window_start = gr.Slider(
+            label='Global window start', minimum=0.0, maximum=1.0, step=0.01, value=0.0,
+            info='Normalised progress: 0 = first step, 1 = last step.',
+            visible=False,
+        )
+        self.step_window_end = gr.Slider(
+            label='Global window end', minimum=0.0, maximum=1.0, step=0.01, value=1.0,
+            visible=False,
+        )
+        # Per-strategy custom sliders — one start/end pair per strategy
+        _ps_defaults = _step_default_custom()
+        self.step_ps_sliders: Dict[str, Tuple] = {}   # {ui_key: (start_slider, end_slider)}
+        for _ui_key in _STRATEGY_UI_KEYS:
+            _s, _e = _ps_defaults.get(_ui_key, (0.0, 1.0))
+            self.step_ps_sliders[_ui_key] = (
+                gr.Slider(label=f'{_ui_key} start', minimum=0.0, maximum=1.0,
+                          step=0.01, value=_s, visible=False),
+                gr.Slider(label=f'{_ui_key} end',   minimum=0.0, maximum=1.0,
+                          step=0.01, value=_e, visible=False),
+            )
+        self.step_ps_reset_btn = gr.Button(value='Reset to defaults', visible=False)
+        self.step_window_preview = gr.Textbox(
+            label='Step window preview', interactive=False, visible=False,
+            value='',
+        )
+
+        # --- Matryoshka builder ---
+        self.builder_base = gr.Textbox(
+            label='Base prompt', lines=2, placeholder='main subject, environment, style…',
+        )
+        # Child 1
+        self.builder_ch1_strategy = gr.Dropdown(
+            label='Child 1 — strategy', choices=BUILDER_STRATEGIES, value='AND_SALT',
+        )
+        self.builder_ch1_text = gr.Textbox(
+            label='Child 1 — text', lines=1, placeholder='concept, texture, style…',
+        )
+        self.builder_ch1_weight = gr.Slider(
+            label='Child 1 — weight', minimum=0.0, maximum=2.0, step=0.05, value=0.8,
+        )
+        self.builder_ch1_affine = gr.Textbox(
+            label='Child 1 — affine (optional)', lines=1,
+            placeholder='e.g. ROTATE[0.125]  or  SCALE[-1,1]',
+        )
+        # Optional nested child inside child 1
+        self.builder_ch1_nested_enable = gr.Checkbox(label='Add nested child inside child 1', value=False)
+        self.builder_ch1_nested_strategy = gr.Dropdown(
+            label='Nested — strategy', choices=BUILDER_STRATEGIES, value='AND_TOPK', visible=False,
+        )
+        self.builder_ch1_nested_text = gr.Textbox(
+            label='Nested — text', lines=1, placeholder='inner concept…', visible=False,
+        )
+        self.builder_ch1_nested_weight = gr.Slider(
+            label='Nested — weight', minimum=0.0, maximum=2.0, step=0.05, value=0.5, visible=False,
+        )
+        # Child 2
+        self.builder_ch2_enable = gr.Checkbox(label='Add second child', value=False)
+        self.builder_ch2_strategy = gr.Dropdown(
+            label='Child 2 — strategy', choices=BUILDER_STRATEGIES, value='AND_PERP', visible=False,
+        )
+        self.builder_ch2_text = gr.Textbox(
+            label='Child 2 — text', lines=1, placeholder='concept…', visible=False,
+        )
+        self.builder_ch2_weight = gr.Slider(
+            label='Child 2 — weight', minimum=0.0, maximum=2.0, step=0.05, value=0.6, visible=False,
+        )
+        # Output
+        self.builder_preview = gr.Textbox(
+            label='Generated prompt (preview)', lines=7, interactive=False,
+        )
+        self.builder_apply_button   = gr.Button(value='Apply to prompt')
+        self.builder_copy_button    = gr.Button(value='Copy generated prompt')
+        self.builder_explain_button = gr.Button(value='Explain this prompt')
+
+        # --- Templates ---
+        self.template_dropdown = gr.Dropdown(
+            label='Matryoshka template', choices=list(MATRYOSHKA_TEMPLATES.keys()),
+            value=next(iter(MATRYOSHKA_TEMPLATES.keys())),
+        )
+        self.template_description = gr.Textbox(
+            label='Template description', interactive=False,
+            value=next(iter(MATRYOSHKA_TEMPLATES.values()))['description'],
+        )
+        self.template_preview = gr.Textbox(
+            label='Template prompt', lines=8, interactive=False,
+            value=next(iter(MATRYOSHKA_TEMPLATES.values()))['prompt'],
+        )
+        self.template_load_button = gr.Button(value='Load template into prompt')
+
+        # --- Debug / explain (matryoshka tree) ---
+        self.debug_prompt_input = gr.Textbox(
+            label='Prompt to explain', lines=5,
+            placeholder='Paste any prompt here, including nested ones, to see the full parse tree…',
+        )
+        self.debug_output = gr.Textbox(
+            label='Parse tree + diagnostics  (structural preview — not a full runtime simulation)',
+            lines=18, interactive=False,
+            value='(enter a prompt above)',
+        )
+        self.debug_parse_button = gr.Button(value='Explain prompt')
+        self.debug_copy_button  = gr.Button(value='Copy explain output')
+
+    # ------------------------------------------------------------------
+
+    def arrange_components(self, is_img2img: bool) -> None:
+        if self.is_rendered:
+            return
+
+        with gr.Accordion(label='Neutral Prompt', open=False):
+            self.cfg_rescale.render()
+
+            with gr.Accordion(label='Base prompt protection', open=False):
+                self.protection_mode.render()
+                self.strict_threshold.render()
+
+            with gr.Accordion(label='Prompt formatter', open=False):
+                self.neutral_prompt.render()
+                self.neutral_cond_scale.render()
+                self.aux_prompt_type.render()
+                self.salt_k.render()
+                self.topk_threshold.render()
+                with gr.Row():
+                    self.align_detail.render()
+                    self.align_structure.render()
+                self.append_to_prompt_button.render()
+
+            with gr.Accordion(label='Matryoshka builder', open=False):
+                self.builder_base.render()
+                with gr.Row():
+                    self.builder_ch1_strategy.render()
+                    self.builder_ch1_weight.render()
+                self.builder_ch1_text.render()
+                self.builder_ch1_affine.render()
+                self.builder_ch1_nested_enable.render()
+                with gr.Row():
+                    self.builder_ch1_nested_strategy.render()
+                    self.builder_ch1_nested_weight.render()
+                self.builder_ch1_nested_text.render()
+                self.builder_ch2_enable.render()
+                with gr.Row():
+                    self.builder_ch2_strategy.render()
+                    self.builder_ch2_weight.render()
+                self.builder_ch2_text.render()
+                self.builder_preview.render()
+                with gr.Row():
+                    self.builder_apply_button.render()
+                    self.builder_copy_button.render()
+                    self.builder_explain_button.render()
+
+            with gr.Accordion(label='Matryoshka templates', open=False):
+                self.template_dropdown.render()
+                self.template_description.render()
+                self.template_preview.render()
+                self.template_load_button.render()
+
+            with gr.Accordion(label='Affine transform builder', open=False):
+                self.affine_preset.render()
+                with gr.Row():
+                    self.affine_transform.render()
+                    self.affine_p1.render()
+                    self.affine_p2.render()
+                self.affine_preview.render()
+                self.affine_insert_button.render()
+
+            with gr.Accordion(label='Step-window gating (AND_* activation)', open=False):
+                self.step_window_enabled.render()
+                self.step_window_lock.render()
+                self.step_window_mode.render()
+                with gr.Row():
+                    self.step_window_start.render()
+                    self.step_window_end.render()
+                with gr.Accordion(label='Per-strategy custom windows', open=False):
+                    for _ui_key, (_s_slider, _e_slider) in self.step_ps_sliders.items():
+                        with gr.Row():
+                            _s_slider.render()
+                            _e_slider.render()
+                    self.step_ps_reset_btn.render()
+                self.step_window_preview.render()
+
+            with gr.Accordion(label='Prompt debug / explain', open=False):
+                self.debug_prompt_input.render()
+                with gr.Row():
+                    self.debug_parse_button.render()
+                    self.debug_copy_button.render()
+                self.debug_output.render()
+
+    def connect_events(self, is_img2img: bool) -> None:
+        if self.is_rendered:
+            return
+
+        prompt_textbox = img2img_prompt_textbox if is_img2img else txt2img_prompt_textbox
+
+        # ---- Protection ----
+        def _on_protection_change(mode, threshold):
+            mode = global_state.normalize_protection_mode(mode)
+            global_state.protection_mode  = mode
+            global_state.strict_threshold = global_state.clamp_strict_threshold(threshold)
+            return gr.update(visible=(mode in ('strict', 'soft')))
+
+        self.protection_mode.change(
+            fn=_on_protection_change,
+            inputs=[self.protection_mode, self.strict_threshold],
+            outputs=[self.strict_threshold],
+        )
+        self.strict_threshold.change(
+            fn=lambda m, t: (
+                setattr(global_state, 'protection_mode',  global_state.normalize_protection_mode(m)) or
+                setattr(global_state, 'strict_threshold', global_state.clamp_strict_threshold(t))
+            ),
+            inputs=[self.protection_mode, self.strict_threshold], outputs=[],
+        )
+
+        # ---- Formatter type sliders ----
+        def _on_type_change(label):
+            return (gr.update(visible=(label in _SALT_LABELS)),
+                    gr.update(visible=(label in _TOPK_LABELS)),
+                    gr.update(visible=(label in _ALIGN_CUSTOM_LABELS)),
+                    gr.update(visible=(label in _ALIGN_CUSTOM_LABELS)))
+
+        self.aux_prompt_type.change(
+            fn=_on_type_change, inputs=[self.aux_prompt_type],
+            outputs=[self.salt_k, self.topk_threshold, self.align_detail, self.align_structure],
+        )
+
+        self.append_to_prompt_button.click(
+            fn=lambda init, p, sc, lbl, k, topk, d, s: (
+                f'{init}\n{_build_keyword(lbl, k, int(d), int(s), topk)} {p} :{sc}', ''),
+            inputs=[prompt_textbox, self.neutral_prompt, self.neutral_cond_scale,
+                    self.aux_prompt_type, self.salt_k, self.topk_threshold,
+                    self.align_detail, self.align_structure],
+            outputs=[prompt_textbox, self.neutral_prompt],
+        )
+
+        # ---- Affine ----
+        def _apply_affine_preset(name):
+            data = _AFFINE_PRESETS.get(name)
+            if data is None:
+                return gr.update(), gr.update(), gr.update(), gr.update()
+            t, p1, p2 = data[0], float(data[1]) if len(data) > 1 else 0.0, float(data[2]) if len(data) > 2 else 1.0
+            return (gr.update(value=t), gr.update(value=p1),
+                    gr.update(value=p2), gr.update(value=_build_affine_snippet(t, p1, p2)))
+
+        self.affine_preset.change(
+            fn=_apply_affine_preset, inputs=[self.affine_preset],
+            outputs=[self.affine_transform, self.affine_p1, self.affine_p2, self.affine_preview],
+        )
+        def _live_affine(t, p1, p2):
+            return gr.update(value=_build_affine_snippet(t, p1, p2))
+        for c in (self.affine_transform, self.affine_p1, self.affine_p2):
+            c.change(fn=_live_affine, inputs=[self.affine_transform, self.affine_p1, self.affine_p2],
+                     outputs=[self.affine_preview])
+
+        self.affine_insert_button.click(
+            fn=lambda init, t, p1, p2: f'{init} {_build_affine_snippet(t, p1, p2)}'.strip(),
+            inputs=[prompt_textbox, self.affine_transform, self.affine_p1, self.affine_p2],
+            outputs=[prompt_textbox],
+        )
+
+        # ---- Builder live preview ----
+        def _builder_update(base, s1, t1, w1, aff1, nest_on, ns, nt, nw, ch2_on, s2, t2, w2):
+            nested_str = build_child_block(ns, nt, nw) if nest_on and nt.strip() else ''
+            ch1 = build_child_block(s1, t1, w1, affine=aff1, nested=nested_str) if t1.strip() else ''
+            ch2 = build_child_block(s2, t2, w2) if ch2_on and t2.strip() else ''
+            children = [c for c in [
+                {'strategy': s1, 'text': t1, 'weight': w1, 'affine': aff1,
+                 'nested': build_child_block(ns, nt, nw) if nest_on and nt.strip() else ''},
+                {'strategy': s2, 'text': t2, 'weight': w2} if ch2_on and t2.strip() else None,
+            ] if c is not None]
+            return gr.update(value=build_nested_prompt(base, children))
+
+        _builder_inputs = [
+            self.builder_base,
+            self.builder_ch1_strategy, self.builder_ch1_text, self.builder_ch1_weight,
+            self.builder_ch1_affine,
+            self.builder_ch1_nested_enable,
+            self.builder_ch1_nested_strategy, self.builder_ch1_nested_text, self.builder_ch1_nested_weight,
+            self.builder_ch2_enable,
+            self.builder_ch2_strategy, self.builder_ch2_text, self.builder_ch2_weight,
+        ]
+        for ctrl in _builder_inputs:
+            ctrl.change(fn=_builder_update, inputs=_builder_inputs, outputs=[self.builder_preview])
+
+        # Toggle visibility of nested / ch2 sections
+        self.builder_ch1_nested_enable.change(
+            fn=lambda on: (gr.update(visible=on), gr.update(visible=on), gr.update(visible=on)),
+            inputs=[self.builder_ch1_nested_enable],
+            outputs=[self.builder_ch1_nested_strategy, self.builder_ch1_nested_text,
+                     self.builder_ch1_nested_weight],
+        )
+        self.builder_ch2_enable.change(
+            fn=lambda on: (gr.update(visible=on), gr.update(visible=on), gr.update(visible=on)),
+            inputs=[self.builder_ch2_enable],
+            outputs=[self.builder_ch2_strategy, self.builder_ch2_text, self.builder_ch2_weight],
+        )
+
+        # Builder → apply / explain
+        self.builder_apply_button.click(
+            fn=lambda init, preview: (f'{init}\n{preview}'.strip() if preview.strip() else init, ''),
+            inputs=[prompt_textbox, self.builder_preview], outputs=[prompt_textbox, self.builder_preview],
+        )
+        # Copy buttons: copy content into a dedicated copy-sink textbox via JS,
+        # or — since Gradio doesn't have a native clipboard API — make the textbox
+        # temporarily interactive so the user can Ctrl+A / Ctrl+C easily.
+        # We implement this as a no-op event (the Textbox is already selectable).
+        # A real clipboard call requires gr.HTML + JS, which we keep optional.
+        self.builder_copy_button.click(fn=lambda x: x,
+                                        inputs=[self.builder_preview],
+                                        outputs=[self.builder_preview])
+        self.debug_copy_button.click(fn=lambda x: x,
+                                      inputs=[self.debug_output],
+                                      outputs=[self.debug_output])
+        self.builder_explain_button.click(
+            fn=lambda preview: gr.update(value=render_full_explain(preview)),
+            inputs=[self.builder_preview], outputs=[self.debug_output],
+        )
+
+        # ---- Templates ----
+        def _on_template_change(name):
+            t = MATRYOSHKA_TEMPLATES.get(name, {})
+            return (gr.update(value=t.get('description', '')),
+                    gr.update(value=t.get('prompt', '')))
+
+        self.template_dropdown.change(
+            fn=_on_template_change, inputs=[self.template_dropdown],
+            outputs=[self.template_description, self.template_preview],
+        )
+        self.template_load_button.click(
+            fn=lambda init, tmpl: f'{init}\n{tmpl}'.strip() if tmpl.strip() else init,
+            inputs=[prompt_textbox, self.template_preview], outputs=[prompt_textbox],
+        )
+
+        # ---- Step window ----
+        _ps_all_sliders = [sl for (s, e) in self.step_ps_sliders.values() for sl in (s, e)]
+
+        def _step_window_update(enabled, lock, mode, start, end, *ps_vals):
+            vis          = bool(enabled)
+            show_global  = vis and mode == 'global'
+            show_custom  = vis and mode == 'per-strategy custom'
+
+            global_state.step_window_enabled        = vis
+            global_state.step_window_lock_after_end = bool(lock)
+            if vis:
+                if mode == 'global':
+                    global_state.step_window_global       = StepWindow(start, end)
+                    global_state.step_window_use_defaults = False
+                    global_state.step_window_per_strategy = None
+                elif mode == 'per-strategy defaults':
+                    global_state.step_window_global       = None
+                    global_state.step_window_use_defaults = True
+                    global_state.step_window_per_strategy = None
+                elif mode == 'per-strategy custom':
+                    raw = {}
+                    for idx, ui_key in enumerate(_STRATEGY_UI_KEYS):
+                        raw[ui_key] = (float(ps_vals[idx * 2]), float(ps_vals[idx * 2 + 1]))
+                    global_state.step_window_global       = None
+                    global_state.step_window_use_defaults = False
+                    global_state.step_window_custom_raw   = raw
+                    global_state.step_window_per_strategy = _build_per_strategy_windows(raw)
+            else:
+                global_state.step_window_global       = None
+                global_state.step_window_use_defaults = False
+                global_state.step_window_per_strategy = None
+
+            custom_raw = getattr(global_state, 'step_window_custom_raw', None) or {}
+            preview = _build_step_window_preview(mode, start, end, custom_raw) if vis else ''
+
+            ps_vis = [gr.update(visible=show_custom)] * len(_ps_all_sliders)
+            return (
+                gr.update(visible=vis),            # mode
+                gr.update(visible=vis),            # lock checkbox
+                gr.update(visible=show_global),    # global start
+                gr.update(visible=show_global),    # global end
+                *ps_vis,                           # per-strategy sliders
+                gr.update(visible=show_custom),    # reset_btn
+                gr.update(visible=vis, value=preview),  # preview
+            )
+
+        def _ps_reset(*_):
+            from lib_neutral_prompt.step_utils import default_custom_windows
+            defaults = default_custom_windows()
+            updates = []
+            for ui_key in _STRATEGY_UI_KEYS:
+                s, e = defaults.get(ui_key, (0.0, 1.0))
+                updates.extend([gr.update(value=s), gr.update(value=e)])
+            return updates
+
+        _sw_inputs = ([self.step_window_enabled, self.step_window_lock,
+                       self.step_window_mode,
+                       self.step_window_start, self.step_window_end]
+                      + _ps_all_sliders)
+        _sw_outputs = ([self.step_window_mode, self.step_window_lock,
+                        self.step_window_start, self.step_window_end]
+                       + _ps_all_sliders
+                       + [self.step_ps_reset_btn, self.step_window_preview])
+
+        for ctrl in _sw_inputs:
+            ctrl.change(fn=_step_window_update, inputs=_sw_inputs, outputs=_sw_outputs)
+
+        self.step_ps_reset_btn.click(fn=_ps_reset, inputs=[], outputs=_ps_all_sliders)
+        _explain_fn = lambda s: gr.update(value=render_full_explain(s))
+        self.debug_parse_button.click(fn=_explain_fn, inputs=[self.debug_prompt_input],
+                                      outputs=[self.debug_output])
+        self.debug_prompt_input.change(fn=_explain_fn, inputs=[self.debug_prompt_input],
+                                       outputs=[self.debug_output])
+
+    def set_rendered(self, value: bool = True) -> None:
+        self.is_rendered = value
+
+    # ------------------------------------------------------------------
+
+    def _collect_ps_slider_values(self) -> Dict[str, Tuple[float, float]]:
+        """Read current per-strategy slider values into a raw dict."""
+        raw: Dict[str, Tuple[float, float]] = {}
+        for ui_key, (s_sl, e_sl) in self.step_ps_sliders.items():
+            raw[ui_key] = (float(s_sl.value), float(e_sl.value))
+        return raw
+
+    def get_components(self) -> Tuple:
+        ps_components = []
+        for _ui_key, (_s, _e) in self.step_ps_sliders.items():
+            ps_components.extend([_s, _e])
+        return (self.cfg_rescale, self.protection_mode, self.strict_threshold,
+                self.step_window_enabled, self.step_window_lock,
+                self.step_window_mode,
+                self.step_window_start, self.step_window_end,
+                *ps_components)
+
+    def get_infotext_fields(self) -> Tuple:
+        return tuple(zip(self.get_components(), (
+            'CFG Rescale phi',
+            'NP Protection Mode', 'NP Strict Threshold',
+            'NP Step Window Enabled', 'NP Step Window Lock',
+            'NP Step Window Mode',
+            'NP Step Window Start',   'NP Step Window End',
+            # per-strategy sliders not individually in infotext — serialised as one key
+        )))
+
+    def get_paste_field_names(self) -> List[str]:
+        return [
+            'CFG Rescale phi',
+            'NP Protection Mode', 'NP Strict Threshold',
+            'NP Step Window Enabled', 'NP Step Window Lock',
+            'NP Step Window Mode',
+            'NP Step Window Start',   'NP Step Window End',
+            'NP Step Window Custom',
+        ]
+
+    def get_extra_generation_params(self, args: Dict) -> Dict:
+        params = {
+            'CFG Rescale phi':     args['cfg_rescale'],
+            'NP Protection Mode':  args['protection_mode'],
+            'NP Strict Threshold': args['strict_threshold'],
+        }
+        if args.get('step_window_enabled'):
+            params['NP Step Window Enabled'] = True
+            params['NP Step Window Mode']    = args.get('step_window_mode', 'global')
+            params['NP Step Window Start']   = round(float(args.get('step_window_start', 0.0)), 4)
+            params['NP Step Window End']     = round(float(args.get('step_window_end',   1.0)), 4)
+            if args.get('step_window_lock_after_end'):
+                params['NP Step Window Lock'] = True
+            if args.get('step_window_mode') == 'per-strategy custom':
+                raw = args.get('step_window_custom_raw') or {}
+                params['NP Step Window Custom'] = _serialize_per_strategy_windows(raw)
+        return params
+
+    def unpack_processing_args(self, cfg_rescale: float,
+                               protection_mode: str = 'auto',
+                               strict_threshold: float = 0.1,
+                               step_window_enabled: bool = False,
+                               step_window_lock_after_end: bool = False,
+                               step_window_mode: str = 'global',
+                               step_window_start: float = 0.0,
+                               step_window_end:   float = 1.0,
+                               **ps_kwargs) -> Dict:
+        # Per-strategy raw dict: collect from kwargs (AND_PERP_start, AND_PERP_end, ...)
+        custom_raw: Dict[str, Tuple[float, float]] = {}
+        for ui_key in _STRATEGY_UI_KEYS:
+            s_key = f'{ui_key}_start'
+            e_key = f'{ui_key}_end'
+            if s_key in ps_kwargs and e_key in ps_kwargs:
+                custom_raw[ui_key] = (float(ps_kwargs[s_key]), float(ps_kwargs[e_key]))
+
+        enabled = bool(step_window_enabled)
+        lock    = bool(step_window_lock_after_end)
+        mode    = str(step_window_mode)
+        start   = max(0.0, min(1.0, float(step_window_start)))
+        end     = max(0.0, min(1.0, float(step_window_end)))
+        if start > end:
+            start, end = 0.0, 1.0
+
+        global_state.step_window_enabled        = enabled
+        global_state.step_window_lock_after_end = lock
+        if enabled:
+            if mode == 'global':
+                global_state.step_window_global       = StepWindow(start, end)
+                global_state.step_window_use_defaults = False
+                global_state.step_window_per_strategy = None
+                global_state.step_window_custom_raw   = None
+            elif mode == 'per-strategy defaults':
+                global_state.step_window_global       = None
+                global_state.step_window_use_defaults = True
+                global_state.step_window_per_strategy = None
+                global_state.step_window_custom_raw   = None
+            elif mode == 'per-strategy custom':
+                global_state.step_window_global       = None
+                global_state.step_window_use_defaults = False
+                global_state.step_window_custom_raw   = custom_raw
+                global_state.step_window_per_strategy = _build_per_strategy_windows(custom_raw)
+            else:
+                global_state.step_window_global       = None
+                global_state.step_window_use_defaults = False
+                global_state.step_window_per_strategy = None
+        else:
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = False
+            global_state.step_window_per_strategy = None
+
+        return {
+            'cfg_rescale':               cfg_rescale,
+            'protection_mode':           protection_mode,
+            'strict_threshold':          strict_threshold,
+            'step_window_enabled':       enabled,
+            'step_window_lock_after_end': lock,
+            'step_window_mode':          mode,
+            'step_window_start':         start,
+            'step_window_end':           end,
+            'step_window_custom_raw':    custom_raw,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Settings & callbacks
+# ---------------------------------------------------------------------------
+
+def on_ui_settings() -> None:
+    section = ('neutral_prompt', 'Neutral Prompt')
+    shared.opts.add_option(
+        'neutral_prompt_enabled',
+        shared.OptionInfo(True, 'Enable neutral-prompt extension', section=section),
+    )
+    global_state.is_enabled = shared.opts.data.get('neutral_prompt_enabled', True)
+    shared.opts.onchange('neutral_prompt_enabled', _update_enabled)
+    shared.opts.add_option(
+        'neutral_prompt_verbose',
+        shared.OptionInfo(False, 'Enable verbose debugging for neutral-prompt', section=section),
+    )
+    global_state.verbose = shared.opts.data.get('neutral_prompt_verbose', False)
+    shared.opts.onchange('neutral_prompt_verbose', _update_verbose)
+
+
+script_callbacks.on_ui_settings(on_ui_settings)
+
+
+def _update_enabled() -> None:
+    global_state.is_enabled = shared.opts.data.get('neutral_prompt_enabled', True)
+
+
+def _update_verbose() -> None:
+    global_state.verbose = shared.opts.data.get('neutral_prompt_verbose', False)
+
+
+def on_after_component(component, **_kwargs) -> None:
+    global txt2img_prompt_textbox, img2img_prompt_textbox
+    eid = getattr(component, 'elem_id', None)
+    if eid == 'txt2img_prompt':
+        txt2img_prompt_textbox = component
+    elif eid == 'img2img_prompt':
+        img2img_prompt_textbox = component
+
+
+script_callbacks.on_after_component(on_after_component)

neutral_prompt_patcheds/lib_neutral_prompt/xyz_grid.py

@@ -0,0 +1,42 @@
+import sys
+from types import ModuleType
+from typing import Optional
+from modules import scripts
+from lib_neutral_prompt import global_state
+
+
+def patch():
+    xyz_module = find_xyz_module()
+    if xyz_module is None:
+        print("[sd-webui-neutral-prompt]", "xyz_grid.py not found.", file=sys.stderr)
+        return
+
+    xyz_module.axis_options.extend([
+        xyz_module.AxisOption("[Neutral Prompt] CFG Rescale", int_or_float, apply_cfg_rescale()),
+    ])
+
+
+class XyzFloat(float):
+    is_xyz: bool = True
+
+
+def apply_cfg_rescale():
+    def callback(_p, v, _vs):
+        global_state.cfg_rescale = XyzFloat(v)
+
+    return callback
+
+
+def int_or_float(string):
+    try:
+        return int(string)
+    except ValueError:
+        return float(string)
+
+
+def find_xyz_module() -> Optional[ModuleType]:
+    for data in scripts.scripts_data:
+        if data.script_class.__module__ in {"xyz_grid.py", "xy_grid.py"} and hasattr(data, "module"):
+            return data.module
+
+    return None

neutral_prompt_patcheds/scripts/neutral_prompt.py

@@ -0,0 +1,99 @@
+from lib_neutral_prompt import global_state, hijacker, neutral_prompt_parser, prompt_parser_hijack, cfg_denoiser_hijack, ui, xyz_grid
+from modules import scripts, processing, shared
+from typing import Dict
+import functools
+
+
+class NeutralPromptScript(scripts.Script):
+    def __init__(self):
+        self.accordion_interface = None
+        self._is_img2img = False
+
+    @property
+    def is_img2img(self):
+        return self._is_img2img
+
+    @is_img2img.setter
+    def is_img2img(self, is_img2img):
+        self._is_img2img = is_img2img
+        if self.accordion_interface is None:
+            self.accordion_interface = ui.AccordionInterface(self.elem_id)
+
+    def title(self) -> str:
+        return "Neutral Prompt"
+
+    def show(self, is_img2img: bool):
+        return scripts.AlwaysVisible
+
+    def ui(self, is_img2img: bool):
+        self.hijack_composable_lora(is_img2img)
+
+        self.accordion_interface.arrange_components(is_img2img)
+        self.accordion_interface.connect_events(is_img2img)
+        self.infotext_fields = self.accordion_interface.get_infotext_fields()
+        self.paste_field_names = self.accordion_interface.get_paste_field_names()
+        self.accordion_interface.set_rendered()
+        return self.accordion_interface.get_components()
+
+    def process(self, p: processing.StableDiffusionProcessing, *args):
+        args = self.accordion_interface.unpack_processing_args(*args)
+
+        self.update_global_state(args)
+        if global_state.is_enabled:
+            p.extra_generation_params.update(self.accordion_interface.get_extra_generation_params(args))
+            # Reset Lock-after-End flags once per real generation lifecycle.
+            # This must happen AFTER update_global_state so that
+            # step_window_lock_after_end reflects the current UI value.
+            if global_state.step_window_lock_after_end:
+                global_state.begin_new_generation()
+
+    def update_global_state(self, args: Dict):
+        if shared.state.job_no == 0:
+            global_state.is_enabled = shared.opts.data.get('neutral_prompt_enabled', True)
+
+        for k, v in args.items():
+            try:
+                getattr(global_state, k)
+            except AttributeError:
+                continue
+
+            if getattr(getattr(global_state, k), 'is_xyz', False):
+                xyz_attr = getattr(global_state, k)
+                xyz_attr.is_xyz = False
+                args[k] = xyz_attr
+                continue
+
+            if shared.state.job_no > 0:
+                continue
+
+            setattr(global_state, k, v)
+
+    def hijack_composable_lora(self, is_img2img):
+        if self.accordion_interface.is_rendered:
+            return
+
+        lora_script = None
+        script_runner = scripts.scripts_img2img if is_img2img else scripts.scripts_txt2img
+
+        for script in script_runner.alwayson_scripts:
+            if script.title().lower() == "composable lora":
+                lora_script = script
+                break
+
+        if lora_script is not None:
+            lora_script.process = functools.partial(composable_lora_process_hijack, original_function=lora_script.process)
+
+
+def composable_lora_process_hijack(p: processing.StableDiffusionProcessing, *args, original_function, **kwargs):
+    if not global_state.is_enabled:
+        return original_function(p, *args, **kwargs)
+
+    exprs = prompt_parser_hijack.parse_prompts(p.all_prompts)
+    all_prompts, p.all_prompts = p.all_prompts, prompt_parser_hijack.transpile_exprs(exprs)
+    res = original_function(p, *args, **kwargs)
+    # restore original prompts
+    p.all_prompts = all_prompts
+    return res
+
+
+xyz_grid.patch()

neutral_prompt_patcheds/test/perp_parser/__init__.py

@@ -0,0 +1,54 @@
+"""
+Test package init — installs a minimal torch mock when real torch is absent.
+
+This runs before any test module in the package is imported, so all parser
+tests get a working `torch` in sys.modules without needing torch installed.
+Runtime tests that require real torch use @unittest.skipUnless independently.
+"""
+import pathlib, sys
+
+# Make the extension root importable regardless of CWD.
+_root = str(pathlib.Path(__file__).parent.parent.parent)
+if _root not in sys.path:
+    sys.path.insert(0, _root)
+
+# Install mock if real torch is absent.
+import math, types
+
+def _install_mock_torch():
+    try:
+        import importlib.util
+        spec = importlib.util.find_spec('torch')
+        if spec is not None and getattr(spec, 'origin', None) is not None:
+            return  # real torch present — nothing to do
+    except (ValueError, ModuleNotFoundError):
+        pass
+
+    if 'torch' in sys.modules:
+        return  # already mocked
+
+    class _FT:
+        def __init__(self, data=None): self.data = data
+        def __getitem__(self, key):
+            if isinstance(self.data, list):
+                return _FT(self.data[key] if isinstance(key, (int, slice)) else None)
+            return _FT(None)
+        def __matmul__(self, other): return _FT('matmul')
+
+    torch = types.ModuleType('torch')
+    torch.Tensor  = _FT
+    torch.float32 = 'float32'
+    torch.pi      = math.pi
+    torch.eye     = lambda n, dtype=None: _FT(list(range(n)))
+    torch.tensor  = lambda data, dtype=None: _FT(data)
+    torch.vstack  = lambda tensors: _FT([t.data for t in tensors])
+    torch.linalg  = types.SimpleNamespace(inv=lambda x: _FT('inv'))
+
+    nn    = types.ModuleType('torch.nn')
+    nn_fn = types.ModuleType('torch.nn.functional')
+    torch.nn = nn
+    sys.modules['torch']               = torch
+    sys.modules['torch.nn']            = nn
+    sys.modules['torch.nn.functional'] = nn_fn
+
+_install_mock_torch()

neutral_prompt_patcheds/test/perp_parser/mock_torch.py

@@ -0,0 +1,61 @@
+"""
+Minimal torch mock for parser-only tests (no real tensor math needed).
+
+Usage — place this BEFORE any lib_neutral_prompt imports:
+
+    from test.perp_parser.mock_torch import install
+    install()
+    from lib_neutral_prompt import neutral_prompt_parser
+"""
+
+import math
+import sys
+import types
+
+
+class _FakeTensor:
+    """Enough of torch.Tensor for the parser AST dataclasses."""
+    def __init__(self, data=None):
+        self.data = data
+
+    def __getitem__(self, key):
+        if isinstance(self.data, list) and isinstance(key, (int, slice)):
+            return _FakeTensor(self.data[key])
+        return _FakeTensor(None)
+
+    def __matmul__(self, other):
+        return _FakeTensor('matmul')
+
+    def __repr__(self):
+        return f'FakeTensor({self.data})'
+
+
+def install() -> None:
+    """Install a minimal torch mock into sys.modules (idempotent)."""
+    if 'torch' in sys.modules and not isinstance(sys.modules['torch'], types.ModuleType):
+        return  # real torch already present
+    # Only mock if torch is actually missing
+    try:
+        import importlib.util
+        spec = importlib.util.find_spec('torch')
+        if spec is not None and getattr(spec, 'origin', None) is not None:
+            return  # real torch is available — use it
+    except (ValueError, ModuleNotFoundError):
+        pass
+
+    torch = types.ModuleType('torch')
+    torch.Tensor   = _FakeTensor
+    torch.float32  = 'float32'
+    torch.pi       = math.pi
+    torch.eye      = lambda n, dtype=None: _FakeTensor(list(range(n)))
+    torch.tensor   = lambda data, dtype=None: _FakeTensor(data)
+    torch.vstack   = lambda tensors: _FakeTensor([t.data for t in tensors])
+    torch.linalg   = types.SimpleNamespace(inv=lambda x: _FakeTensor('inv'))
+
+    nn     = types.ModuleType('torch.nn')
+    nn_fn  = types.ModuleType('torch.nn.functional')
+    torch.nn = nn
+
+    sys.modules['torch']              = torch
+    sys.modules['torch.nn']           = nn
+    sys.modules['torch.nn.functional'] = nn_fn

neutral_prompt_patcheds/test/perp_parser/test_affine_keyword_order.py

@@ -0,0 +1,133 @@
+"""
+Tests for affine-keyword ordering in parse_prompt.
+
+Both orderings must work correctly:
+  (A) AND_PERP ROTATE[0.125] vivid colors   ← trailing affine (original)
+  (B) ROTATE[0.125] AND_PERP vivid colors   ← leading affine  (documented)
+"""
+import unittest
+
+from lib_neutral_prompt import neutral_prompt_parser as p
+from lib_neutral_prompt.neutral_prompt_parser import ConciliationStrategy
+
+
+class TestAffineKeywordOrder(unittest.TestCase):
+
+    # ------------------------------------------------------------------ #
+    # trailing affine  (AND_PERP ROTATE[...] text)                        #
+    # ------------------------------------------------------------------ #
+
+    def test_trailing_affine_basic(self):
+        root = p.parse_root("base AND_PERP ROTATE[0.125] vivid colors :0.8")
+        self.assertEqual(len(root.children), 2)
+        self.assertEqual(root.children[0].prompt.strip(), "base")
+        self.assertIsNone(root.children[0].local_transform)
+        self.assertIsNotNone(root.children[1].local_transform)
+        self.assertEqual(root.children[1].conciliation, ConciliationStrategy.PERPENDICULAR)
+        self.assertAlmostEqual(root.children[1].weight, 0.8)
+
+    # ------------------------------------------------------------------ #
+    # leading affine  (ROTATE[...] AND_PERP text)                         #
+    # ------------------------------------------------------------------ #
+
+    def test_leading_affine_mid_prompt(self):
+        """ROTATE[...] AND_PERP must NOT be consumed into the previous prompt's text."""
+        root = p.parse_root("base ROTATE[0.125] AND_PERP vivid colors :0.8")
+        self.assertEqual(len(root.children), 2,
+            f"Expected 2 children, got {len(root.children)}: "
+            f"{[getattr(c,'prompt','composite') for c in root.children]}")
+        first, second = root.children
+        # first segment = "base " with no transform
+        self.assertIn("base", first.prompt)
+        self.assertNotIn("ROTATE", first.prompt)
+        self.assertIsNone(first.local_transform)
+        # second segment gets the transform
+        self.assertIsNotNone(second.local_transform)
+        self.assertEqual(second.conciliation, ConciliationStrategy.PERPENDICULAR)
+        self.assertAlmostEqual(second.weight, 0.8)
+
+    def test_leading_affine_at_start(self):
+        """ROTATE[...] AND_PERP as first (and only non-AND) segment."""
+        root = p.parse_root("ROTATE[0.125] AND_PERP vivid colors :0.8")
+        self.assertEqual(len(root.children), 1)
+        child = root.children[0]
+        self.assertIsNotNone(child.local_transform)
+        self.assertEqual(child.conciliation, ConciliationStrategy.PERPENDICULAR)
+        self.assertIn("vivid", child.prompt)
+        self.assertNotIn("ROTATE", child.prompt)
+
+    def test_leading_affine_with_and_salt(self):
+        root = p.parse_root("portrait SLIDE[0.05,0] AND_SALT vibrant :1.2")
+        self.assertEqual(len(root.children), 2)
+        second = root.children[1]
+        self.assertIsNotNone(second.local_transform)
+        self.assertEqual(second.conciliation, ConciliationStrategy.SALIENCE_MASK)
+
+    # ------------------------------------------------------------------ #
+    # Composed / chained affine                                            #
+    # ------------------------------------------------------------------ #
+
+    def test_leading_and_trailing_compose(self):
+        """ROTATE[a] AND_PERP SCALE[b,b] text — both affines composed."""
+        root = p.parse_root("base AND_PERP ROTATE[0.125] AND_PERP SCALE[1.5,1.5] vivid")
+        # Just check no crash and all children parse
+        self.assertGreaterEqual(len(root.children), 1)
+
+    # ------------------------------------------------------------------ #
+    # CFGRescaleFactorSingleton lifecycle                                   #
+    # ------------------------------------------------------------------ #
+
+    def test_cfg_rescale_singleton_clear(self):
+        from lib_neutral_prompt.global_state import CFGRescaleFactorSingleton as S
+        S.clear()
+        self.assertIsNone(S.get())
+        S.set(1.23)
+        self.assertAlmostEqual(S.get(), 1.23)
+        S.clear()
+        self.assertIsNone(S.get())
+
+    def test_cfg_rescale_singleton_thread_local(self):
+        import threading
+        from lib_neutral_prompt.global_state import CFGRescaleFactorSingleton as S
+        results = {}
+        def worker(val, key):
+            S.clear()
+            S.set(val)
+            import time; time.sleep(0.01)
+            results[key] = S.get()
+        threads = [threading.Thread(target=worker, args=(i * 10.0, i)) for i in range(3)]
+        for t in threads: t.start()
+        for t in threads: t.join()
+        for i in range(3):
+            self.assertAlmostEqual(results[i], i * 10.0,
+                msg=f"Thread {i} got {results[i]} expected {i*10.0}")
+
+    # ------------------------------------------------------------------ #
+    # New AND_SALT variants parse correctly                                #
+    # ------------------------------------------------------------------ #
+
+    def test_and_salt_wide_parsed(self):
+        root = p.parse_root("base AND_SALT_WIDE vivid")
+        self.assertEqual(len(root.children), 2)
+        self.assertEqual(root.children[1].conciliation,
+                         p.ConciliationStrategy.SALIENCE_MASK_WIDE)
+
+    def test_and_salt_blob_parsed(self):
+        root = p.parse_root("base AND_SALT_BLOB vivid")
+        self.assertEqual(len(root.children), 2)
+        self.assertEqual(root.children[1].conciliation,
+                         p.ConciliationStrategy.SALIENCE_MASK_BLOB)
+
+    def test_and_align_parsed(self):
+        root = p.parse_root("base AND_ALIGN_4_8 vivid")
+        self.assertEqual(len(root.children), 2)
+        self.assertIn('AND_ALIGN_4_8', root.children[1].conciliation.value)
+
+    def test_and_mask_align_parsed(self):
+        root = p.parse_root("base AND_MASK_ALIGN_4_8 vivid")
+        self.assertEqual(len(root.children), 2)
+        self.assertIn('AND_MASK_ALIGN_4_8', root.children[1].conciliation.value)
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_affine_pipeline.py

@@ -0,0 +1,217 @@
+"""
+Integration smoke tests for the pre-noise affine pipeline.
+
+Requires PyTorch.  If torch is not installed the entire module is skipped via
+``unittest.skipUnless``, so ``unittest discover`` still exits cleanly.
+
+Mocked: A1111 modules only (modules.script_callbacks, modules.sd_samplers,
+        modules.shared).  torch itself is real — no sys.modules replacement.
+
+Tests:
+  1. Hook is a no-op when global_state.is_enabled = False.
+  2. Identity transform (angle=0) leaves x numerically unchanged.
+  3. Non-identity transform calls apply_affine_transform (verified by spy).
+  4. Prompts with no affine leave x unchanged.
+  5. Empty state does not crash.
+  6. Batch with multiple prompts does not crash.
+"""
+
+import dataclasses
+import importlib
+import math
+import sys
+import types
+import unittest
+
+# ---------------------------------------------------------------------------
+# Detect torch availability — skip the whole module if absent
+# ---------------------------------------------------------------------------
+try:
+    import importlib.util as _ilu
+    _spec = _ilu.find_spec('torch')
+    _TORCH_AVAILABLE = _spec is not None and getattr(_spec, 'origin', None) is not None
+except (ValueError, ModuleNotFoundError):
+    _TORCH_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# A1111 module stubs  (installed unconditionally so cfg_denoiser_hijack can
+# be imported even when running the skip path)
+# ---------------------------------------------------------------------------
+
+def _stub(name):
+    m = types.ModuleType(name)
+    sys.modules.setdefault(name, m)
+    return sys.modules[name]
+
+for _mod_name in ('modules', 'modules.script_callbacks', 'modules.sd_samplers',
+                  'modules.shared', 'modules.prompt_parser', 'gradio'):
+    _stub(_mod_name)
+
+import modules.script_callbacks as _sc
+if not hasattr(_sc, 'on_cfg_denoiser'):
+    _sc.on_cfg_denoiser    = lambda fn: None
+if not hasattr(_sc, 'on_script_unloaded'):
+    _sc.on_script_unloaded = lambda fn: None
+
+import modules.shared as _sh
+if not hasattr(_sh, 'opts'):
+    _sh.opts = types.SimpleNamespace(
+        data={},
+        add_option=lambda *a, **k: None,
+        onchange=lambda *a, **k: None,
+        OptionInfo=lambda *a, **k: None,
+    )
+
+import modules.sd_samplers as _ss
+if not hasattr(_ss, 'cfg_denoiser'):
+    _ss.cfg_denoiser   = None
+# cfg_denoiser_hijack installs a hijack on create_sampler at import time
+if not hasattr(_ss, 'create_sampler'):
+    _ss.create_sampler = lambda *a, **k: None
+
+
+# ---------------------------------------------------------------------------
+# Repo root on sys.path
+# ---------------------------------------------------------------------------
+
+from pathlib import Path
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+
+# ---------------------------------------------------------------------------
+# Conditional imports (only when torch is available)
+# ---------------------------------------------------------------------------
+
+if _TORCH_AVAILABLE:
+    import torch
+    from lib_neutral_prompt import global_state, neutral_prompt_parser
+    from lib_neutral_prompt.cfg_denoiser_hijack import _on_cfg_denoiser
+    import lib_neutral_prompt.affine_transform as _at_mod
+
+    # -----------------------------------------------------------------------
+    # Helpers
+    # -----------------------------------------------------------------------
+
+    def _leaf(text, angle=None):
+        """LeafPrompt, optionally with a ROTATE affine (angle in turns)."""
+        transform = None
+        if angle is not None:
+            c = math.cos(angle * 2 * math.pi)
+            s = math.sin(angle * 2 * math.pi)
+            transform = torch.tensor([[c, -s, 0.0], [s, c, 0.0]])
+        return neutral_prompt_parser.LeafPrompt(1.0, None, transform, text)
+
+    def _comp(*children):
+        return neutral_prompt_parser.CompositePrompt(1.0, None, None, list(children))
+
+    @dataclasses.dataclass
+    class _FakeParams:
+        x: torch.Tensor
+
+
+# ---------------------------------------------------------------------------
+# Test class
+# ---------------------------------------------------------------------------
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping pipeline tests')
+class TestOnCfgDenoiserSmokeTest(unittest.TestCase):
+
+    def setUp(self):
+        global_state.is_enabled = True
+        global_state.prompt_exprs = []
+        global_state.batch_cond_indices = []
+
+    def tearDown(self):
+        global_state.is_enabled = False
+        global_state.prompt_exprs = []
+        global_state.batch_cond_indices = []
+
+    # 1. disabled → x untouched
+    def test_disabled_leaves_x_unchanged(self):
+        global_state.is_enabled = False
+        x = torch.zeros(2, 4, 8, 8)
+        x[0] = 1.0
+        orig = x.clone()
+        params = _FakeParams(x=x.clone())
+        global_state.prompt_exprs        = [_comp(_leaf("base"), _leaf("perp", 0.125))]
+        global_state.batch_cond_indices  = [[(0, 1.0), (1, 1.0)]]
+        _on_cfg_denoiser(params)
+        self.assertTrue(torch.equal(params.x, orig), "Disabled hook must not modify x")
+
+    # 2. identity transform → x numerically unchanged
+    def test_identity_transform_no_change(self):
+        x = torch.randn(2, 4, 8, 8)
+        orig = x.clone()
+        params = _FakeParams(x=x.clone())
+        global_state.prompt_exprs        = [_comp(_leaf("base"), _leaf("perp", 0))]
+        global_state.batch_cond_indices  = [[(0, 1.0), (1, 1.0)]]
+        _on_cfg_denoiser(params)
+        self.assertTrue(torch.allclose(params.x, orig, atol=1e-5),
+                        "Identity affine must not change x")
+
+    # 3. non-identity → apply_affine_transform is called (spy)
+    def test_nonidentity_calls_apply_affine_transform(self):
+        x = torch.zeros(2, 4, 8, 8)
+        x[1] = torch.randn(4, 8, 8)
+        params = _FakeParams(x=x.clone())
+        global_state.prompt_exprs        = [_comp(_leaf("base"), _leaf("perp", 0.25))]
+        global_state.batch_cond_indices  = [[(0, 1.0), (1, 1.0)]]
+
+        _real = _at_mod.apply_affine_transform
+        calls = []
+        def _spy(tensor, affine, mode='bilinear'):
+            calls.append(True)
+            return _real(tensor, affine, mode)
+
+        _at_mod.apply_affine_transform = _spy
+        try:
+            _on_cfg_denoiser(params)
+        finally:
+            _at_mod.apply_affine_transform = _real
+
+        self.assertGreater(len(calls), 0,
+                           "apply_affine_transform must be called for non-identity transform")
+
+    # 4. no affine on any child → x unchanged
+    def test_no_affine_no_change(self):
+        x = torch.randn(2, 4, 8, 8)
+        orig = x.clone()
+        params = _FakeParams(x=x.clone())
+        global_state.prompt_exprs        = [_comp(_leaf("base"), _leaf("perp"))]
+        global_state.batch_cond_indices  = [[(0, 1.0), (1, 1.0)]]
+        _on_cfg_denoiser(params)
+        self.assertTrue(torch.allclose(params.x, orig, atol=1e-5),
+                        "No affine → x must not change")
+
+    # 5. empty state → no crash
+    def test_empty_state_no_crash(self):
+        params = _FakeParams(x=torch.randn(1, 4, 8, 8))
+        global_state.prompt_exprs = []
+        global_state.batch_cond_indices = []
+        try:
+            _on_cfg_denoiser(params)
+        except Exception as e:
+            self.fail(f"_on_cfg_denoiser raised with empty state: {e}")
+
+    # 6. two batch entries → no crash
+    def test_batch_multiple_prompts_no_crash(self):
+        params = _FakeParams(x=torch.zeros(4, 4, 8, 8))
+        global_state.prompt_exprs = [
+            _comp(_leaf("base_a"), _leaf("perp_a", 0.25)),
+            _comp(_leaf("base_b"), _leaf("perp_b", 0.125)),
+        ]
+        global_state.batch_cond_indices = [
+            [(0, 1.0), (1, 1.0)],
+            [(2, 1.0), (3, 1.0)],
+        ]
+        try:
+            _on_cfg_denoiser(params)
+        except Exception as e:
+            self.fail(f"Multi-prompt batch raised: {e}")
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_basic_parser.py

@@ -0,0 +1,122 @@
+import unittest
+import pathlib
+import sys
+sys.path.append(str(pathlib.Path(__file__).parent.parent.parent))
+from lib_neutral_prompt import neutral_prompt_parser
+
+
+class TestPromptParser(unittest.TestCase):
+    def setUp(self):
+        self.simple_prompt = neutral_prompt_parser.parse_root("hello :1.0")
+        self.and_prompt = neutral_prompt_parser.parse_root("hello AND goodbye :2.0")
+        self.and_perp_prompt = neutral_prompt_parser.parse_root("hello :1.0 AND_PERP goodbye :2.0")
+        self.and_salt_prompt = neutral_prompt_parser.parse_root("hello :1.0 AND_SALT goodbye :2.0")
+        self.nested_and_perp_prompt = neutral_prompt_parser.parse_root("hello :1.0 AND_PERP [goodbye :2.0 AND_PERP welcome :3.0]")
+        self.nested_and_salt_prompt = neutral_prompt_parser.parse_root("hello :1.0 AND_SALT [goodbye :2.0 AND_SALT welcome :3.0]")
+        self.invalid_weight = neutral_prompt_parser.parse_root("hello :not_a_float")
+
+    def test_simple_prompt_child_count(self):
+        self.assertEqual(len(self.simple_prompt.children), 1)
+
+    def test_simple_prompt_child_weight(self):
+        self.assertEqual(self.simple_prompt.children[0].weight, 1.0)
+
+    def test_simple_prompt_child_prompt(self):
+        self.assertEqual(self.simple_prompt.children[0].prompt, "hello ")
+
+    def test_square_weight_prompt(self):
+        prompt = "a [b c d e : f g h :1.5]"
+        parsed = neutral_prompt_parser.parse_root(prompt)
+        self.assertEqual(parsed.children[0].prompt, prompt)
+
+        composed_prompt = f"{prompt} AND_PERP other prompt"
+        parsed = neutral_prompt_parser.parse_root(composed_prompt)
+        self.assertEqual(parsed.children[0].prompt, prompt)
+
+    def test_and_prompt_child_count(self):
+        self.assertEqual(len(self.and_prompt.children), 2)
+
+    def test_and_prompt_child_weights_and_prompts(self):
+        self.assertEqual(self.and_prompt.children[0].weight, 1.0)
+        self.assertEqual(self.and_prompt.children[0].prompt, "hello ")
+        self.assertEqual(self.and_prompt.children[1].weight, 2.0)
+        self.assertEqual(self.and_prompt.children[1].prompt, " goodbye ")
+
+    def test_and_perp_prompt_child_count(self):
+        self.assertEqual(len(self.and_perp_prompt.children), 2)
+
+    def test_and_perp_prompt_child_types(self):
+        self.assertIsInstance(self.and_perp_prompt.children[0], neutral_prompt_parser.LeafPrompt)
+        self.assertIsInstance(self.and_perp_prompt.children[1], neutral_prompt_parser.LeafPrompt)
+
+    def test_and_perp_prompt_nested_child(self):
+        nested_child = self.and_perp_prompt.children[1]
+        self.assertEqual(nested_child.weight, 2.0)
+        self.assertEqual(nested_child.prompt.strip(), "goodbye")
+
+    def test_nested_and_perp_prompt_child_count(self):
+        self.assertEqual(len(self.nested_and_perp_prompt.children), 2)
+
+    def test_nested_and_perp_prompt_child_types(self):
+        self.assertIsInstance(self.nested_and_perp_prompt.children[0], neutral_prompt_parser.LeafPrompt)
+        self.assertIsInstance(self.nested_and_perp_prompt.children[1], neutral_prompt_parser.CompositePrompt)
+
+    def test_nested_and_perp_prompt_nested_child_types(self):
+        nested_child = self.nested_and_perp_prompt.children[1].children[0]
+        self.assertIsInstance(nested_child, neutral_prompt_parser.LeafPrompt)
+        nested_child = self.nested_and_perp_prompt.children[1].children[1]
+        self.assertIsInstance(nested_child, neutral_prompt_parser.LeafPrompt)
+
+    def test_nested_and_perp_prompt_nested_child(self):
+        nested_child = self.nested_and_perp_prompt.children[1].children[1]
+        self.assertEqual(nested_child.weight, 3.0)
+        self.assertEqual(nested_child.prompt.strip(), "welcome")
+
+    def test_invalid_weight_child_count(self):
+        self.assertEqual(len(self.invalid_weight.children), 1)
+
+    def test_invalid_weight_child_weight(self):
+        self.assertEqual(self.invalid_weight.children[0].weight, 1.0)
+
+    def test_invalid_weight_child_prompt(self):
+        self.assertEqual(self.invalid_weight.children[0].prompt, "hello :not_a_float")
+
+    def test_and_salt_prompt_child_count(self):
+        self.assertEqual(len(self.and_salt_prompt.children), 2)
+
+    def test_and_salt_prompt_child_types(self):
+        self.assertIsInstance(self.and_salt_prompt.children[0], neutral_prompt_parser.LeafPrompt)
+        self.assertIsInstance(self.and_salt_prompt.children[1], neutral_prompt_parser.LeafPrompt)
+
+    def test_and_salt_prompt_nested_child(self):
+        nested_child = self.and_salt_prompt.children[1]
+        self.assertEqual(nested_child.weight, 2.0)
+        self.assertEqual(nested_child.prompt.strip(), "goodbye")
+
+    def test_nested_and_salt_prompt_child_count(self):
+        self.assertEqual(len(self.nested_and_salt_prompt.children), 2)
+
+    def test_nested_and_salt_prompt_child_types(self):
+        self.assertIsInstance(self.nested_and_salt_prompt.children[0], neutral_prompt_parser.LeafPrompt)
+        self.assertIsInstance(self.nested_and_salt_prompt.children[1], neutral_prompt_parser.CompositePrompt)
+
+    def test_nested_and_salt_prompt_nested_child_types(self):
+        nested_child = self.nested_and_salt_prompt.children[1].children[0]
+        self.assertIsInstance(nested_child, neutral_prompt_parser.LeafPrompt)
+        nested_child = self.nested_and_salt_prompt.children[1].children[1]
+        self.assertIsInstance(nested_child, neutral_prompt_parser.LeafPrompt)
+
+    def test_nested_and_salt_prompt_nested_child(self):
+        nested_child = self.nested_and_salt_prompt.children[1].children[1]
+        self.assertEqual(nested_child.weight, 3.0)
+        self.assertEqual(nested_child.prompt.strip(), "welcome")
+
+    def test_start_with_prompt_editing(self):
+        prompt = "[(long shot:1.2):0.1] detail.."
+        res = neutral_prompt_parser.parse_root(prompt)
+        self.assertEqual(res.children[0].weight, 1.0)
+        self.assertEqual(res.children[0].prompt, prompt)
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_lock_after_end.py

@@ -0,0 +1,544 @@
+"""
+Tests for Lock after End (Sprint 3 feature).
+
+Covers:
+1. Basic lock: strategy frozen after window closes
+2. No-lock: strategy reactivates normally without the flag
+3. Lock not set before window start (haven't entered the window yet)
+4. Reset at step 0: lock flags cleared each generation
+5. Per-strategy custom: only the specific strategy gets locked
+6. Global window + lock interaction
+7. Infotext round-trip: lock_after_end serialized and restored
+8. update helper: reset_step_lock_flags clears all flags
+"""
+
+import unittest
+from lib_neutral_prompt import global_state
+from lib_neutral_prompt.step_utils import (
+    StepWindow,
+    normalize_progress,
+    strategy_is_active,
+    strategy_is_active_from_state,
+    build_per_strategy_windows,
+)
+
+class _StateGuard:
+    """Context manager that saves and restores global_state step-window vars."""
+    _FIELDS = (
+        'step_window_enabled',
+        'step_window_global',
+        'step_window_per_strategy',
+        'step_window_use_defaults',
+        'step_window_lock_after_end',
+        '_step_lock_flags',
+        '_lock_generation_id',
+        'current_step',
+        'total_steps',
+    )
+
+    def __enter__(self):
+        self._saved = {f: getattr(global_state, f, None) for f in self._FIELDS}
+        return self
+
+    def __exit__(self, *_):
+        for f, v in self._saved.items():
+            setattr(global_state, f, v)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# 1. Basic lock behaviour
+# ---------------------------------------------------------------------------
+
+class TestLockAfterEndBasic(unittest.TestCase):
+
+    def test_lock_freezes_after_window_end(self):
+        """
+        Window 0.0–0.5: active at progress 0.3, inactive (and locked) at 0.7.
+        Once locked, stays False even if progress would re-enter the range.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # Inside window — must be active
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+            # After window ends at progress 0.7 → inactive and locked
+            result_late = strategy_is_active_from_state('PERPENDICULAR', 0.7)
+            self.assertFalse(result_late)
+
+            # Flag must now be set
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # Subsequent call at 0.4 (would normally be inside window) still False
+            result_rewound = strategy_is_active_from_state('PERPENDICULAR', 0.4)
+            self.assertFalse(result_rewound)
+
+    def test_no_lock_flag_allows_reactivation(self):
+        """Without lock_after_end the strategy returns True when re-entering range."""
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = False
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            # No lock set → a re-query at 0.3 returns True
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+
+# ---------------------------------------------------------------------------
+# 2. Lock not fired before window start
+# ---------------------------------------------------------------------------
+
+class TestLockNotFiredBeforeWindowStart(unittest.TestCase):
+
+    def test_progress_before_window_start_does_not_lock(self):
+        """
+        If progress is before the window start (strategy hasn't started yet),
+        the lock must NOT be set — otherwise the strategy could never activate.
+        Window 0.4–1.0: at progress 0.1 strategy is inactive but lock must NOT fire.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.4, 1.0)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # Step 0 of 10 → progress 0.0 → before window start
+            result = strategy_is_active_from_state('SALIENCE_MASK', 0.0)
+            self.assertFalse(result)
+            self.assertFalse(global_state._step_lock_flags.get('SALIENCE_MASK', False),
+                             'Lock must not fire before window start')
+
+            # Now enter the window at 0.5 → must be active
+            result_in = strategy_is_active_from_state('SALIENCE_MASK', 0.5)
+            self.assertTrue(result_in)
+
+
+# ---------------------------------------------------------------------------
+# 3. reset_step_lock_flags and begin_new_generation
+# ---------------------------------------------------------------------------
+
+class TestLockLifecycle(unittest.TestCase):
+
+    def test_reset_clears_all_flags(self):
+        with _StateGuard():
+            global_state._step_lock_flags = {
+                'PERPENDICULAR': True,
+                'SALIENCE_MASK': True,
+            }
+            global_state.reset_step_lock_flags()
+            self.assertEqual(global_state._step_lock_flags, {})
+
+    def test_reset_idempotent_on_empty(self):
+        with _StateGuard():
+            global_state._step_lock_flags = {}
+            global_state.reset_step_lock_flags()
+            self.assertEqual(global_state._step_lock_flags, {})
+
+    def test_begin_new_generation_clears_flags(self):
+        with _StateGuard():
+            global_state._step_lock_flags = {'PERPENDICULAR': True}
+            global_state.begin_new_generation()
+            self.assertEqual(global_state._step_lock_flags, {})
+
+    def test_begin_new_generation_increments_id(self):
+        with _StateGuard():
+            before = global_state._lock_generation_id
+            global_state.begin_new_generation()
+            self.assertEqual(global_state._lock_generation_id, before + 1)
+            global_state.begin_new_generation()
+            self.assertEqual(global_state._lock_generation_id, before + 2)
+
+    def test_strategy_active_after_begin_new_generation(self):
+        """After begin_new_generation, a previously locked strategy re-arms."""
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # Lock it
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # New generation → re-arms
+            global_state.begin_new_generation()
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+    # ── KEY TEST: restart / rollback safety ───────────────────────────────
+
+    def test_step_zero_revisit_does_not_clear_lock(self):
+        """
+        Sampler-internal rollback to step 0 (Restart sampler, DPM++ multi-pass)
+        must NOT clear lock flags.  Only begin_new_generation() (= process() hook)
+        should do that.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # Normal run: enters window, exits, gets locked
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # Simulate sampler rollback: step counter goes back to 0
+            global_state.update_step_state(0, 20)
+            progress_after_rollback = normalize_progress(
+                global_state.current_step, global_state.total_steps
+            )
+            # Without a new process() call, lock must still be active
+            result = strategy_is_active_from_state('PERPENDICULAR', progress_after_rollback)
+            self.assertFalse(result,
+                'Lock must survive sampler-internal rollback to step 0')
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False),
+                'Flag must remain set after step-0 rollback')
+
+    def test_hires_fix_second_pass_clears_lock(self):
+        """
+        Hires fix calls process() again for its second denoising pass.
+        Simulating that with begin_new_generation() must re-arm strategies.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # First pass: gets locked
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+
+            # Hires fix: process() is called → begin_new_generation()
+            global_state.begin_new_generation()
+
+            # Second pass must start fresh
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+
+# ---------------------------------------------------------------------------
+# 4. Per-strategy: only the locked strategy is frozen
+# ---------------------------------------------------------------------------
+
+class TestLockPerStrategy(unittest.TestCase):
+
+    def test_only_locked_strategy_frozen(self):
+        """
+        Custom windows: AND_PERP 0.0–0.4, AND_SALT 0.5–1.0.
+        After AND_PERP window closes (progress=0.6), AND_PERP is locked.
+        AND_SALT is still active.
+        """
+        with _StateGuard():
+            raw = {'AND_PERP': (0.0, 0.4), 'AND_SALT': (0.5, 1.0)}
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = None
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = build_per_strategy_windows(raw)
+            global_state._step_lock_flags           = {}
+
+            # Inside AND_PERP window
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.2))
+            # Inside AND_SALT window
+            self.assertTrue(strategy_is_active_from_state('SALIENCE_MASK', 0.6))
+
+            # After AND_PERP ends → lock fires
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.6))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # AND_SALT unaffected
+            self.assertFalse(global_state._step_lock_flags.get('SALIENCE_MASK', False))
+            self.assertTrue(strategy_is_active_from_state('SALIENCE_MASK', 0.8))
+
+    def test_defaults_mode_with_lock(self):
+        """
+        use_defaults=True: PERPENDICULAR default 0.0–0.5.
+        At progress 0.7 it should lock (window has ended and we were past start).
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = None
+            global_state.step_window_use_defaults   = True
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            # Active inside default window
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+            # Outside → lock
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+
+# ---------------------------------------------------------------------------
+# 5. Infotext round-trip
+# ---------------------------------------------------------------------------
+
+class TestLockAfterEndInfotext(unittest.TestCase):
+
+    def test_apply_infotext_restores_lock(self):
+        with _StateGuard():
+            global_state.step_window_lock_after_end = False
+            global_state.apply_infotext({
+                'NP Step Window Enabled': 'True',
+                'NP Step Window Mode':    'global',
+                'NP Step Window Start':   '0.0',
+                'NP Step Window End':     '0.5',
+                'NP Step Window Lock':    'True',
+            })
+            self.assertTrue(global_state.step_window_lock_after_end)
+
+    def test_apply_infotext_disables_lock(self):
+        with _StateGuard():
+            global_state.step_window_lock_after_end = True
+            global_state.apply_infotext({'NP Step Window Lock': 'False'})
+            self.assertFalse(global_state.step_window_lock_after_end)
+
+    def test_apply_infotext_lock_absent_leaves_state_unchanged(self):
+        with _StateGuard():
+            global_state.step_window_lock_after_end = True
+            global_state.apply_infotext({'NP Step Window Enabled': 'True'})
+            # Key absent → unchanged
+            self.assertTrue(global_state.step_window_lock_after_end)
+
+    def test_lock_key_in_infotext_constants(self):
+        self.assertEqual(global_state.INFOTEXT_KEY_STEP_WIN_LOCK, 'NP Step Window Lock')
+
+
+# ---------------------------------------------------------------------------
+# 6. Global simulation: step 0→N progression with lock
+# ---------------------------------------------------------------------------
+
+class TestLockSimulatedRun(unittest.TestCase):
+    """
+    Simulate a real 10-step run with lock_after_end=True and window 0.0–0.5.
+    Verify: active steps 0–4, locked from step 5 onward.
+    """
+
+    def test_simulated_10_step_run(self):
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            results = []
+            for step in range(10):
+                global_state.update_step_state(step, 10)
+                p = normalize_progress(global_state.current_step, global_state.total_steps)
+                active = strategy_is_active_from_state('PERPENDICULAR', p)
+                results.append(active)
+
+            # Steps 0–4: progress 0.0–0.44 → inside window 0.0–0.5 → active
+            for i in range(5):
+                self.assertTrue(results[i], f'Expected active at step {i}')
+            # Step 5 onward: progress 0.56+ → outside → locked
+            for i in range(5, 10):
+                self.assertFalse(results[i], f'Expected locked at step {i}')
+
+
+# ---------------------------------------------------------------------------
+# 7. Restart-within-same-generation must NOT clear lock flags
+# ---------------------------------------------------------------------------
+
+class TestLockSurvivesRestartWithinRun(unittest.TestCase):
+    """
+    Key property: if the sampler revisits step 0 within one generation
+    (e.g. Restart sampler, DPM++ SDE second pass, hires fix denoiser),
+    the lock flags must be preserved.
+
+    This is guaranteed by begin_new_generation() being called from process()
+    lifecycle, NOT from step == 0 in the denoising loop.
+    """
+
+    def test_begin_new_generation_called_once_then_step_reset(self):
+        """
+        Simulate: generation starts → begin_new_generation() → strategy locks →
+        sampler restarts (step resets to 0 internally) → lock survives.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+
+            # --- Generation starts: process() calls begin_new_generation() ---
+            global_state.begin_new_generation()
+
+            # Inside window → active
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+            # Window ends → locked
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False),
+                            'Lock flag must be set after window end')
+
+            # Sampler restart: step goes back to 0 — but NO new begin_new_generation()
+            # (process() is NOT called again for a restart within one generation)
+            global_state.update_step_state(0, 20)
+
+            # Lock must survive the step reset
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.0),
+                             'Strategy must remain locked after intra-run step reset')
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False),
+                            'Lock flag must persist after intra-run step reset')
+
+    def test_ensure_step_lock_run_initialized_same_token_no_reset(self):
+        """
+        ensure_step_lock_run_initialized with the same token must NOT reset flags.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            RUN_TOKEN = object()
+            global_state.ensure_step_lock_run_initialized(RUN_TOKEN)
+
+            # Active inside window
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.2))
+            # Window ends → lock fires
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # Same token called again (sampler restart within same generation)
+            reset_happened = global_state.ensure_step_lock_run_initialized(RUN_TOKEN)
+
+            self.assertFalse(reset_happened, 'Same token must not trigger reset')
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False),
+                            'Lock flag must survive same-token re-call')
+
+            # Strategy must still be locked
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.3),
+                             'Strategy must stay locked within same run')
+
+    def test_ensure_step_lock_run_initialized_new_token_resets(self):
+        """
+        ensure_step_lock_run_initialized with a NEW token must reset flags
+        (simulates a genuinely new generation).
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+            global_state._step_lock_flags           = {}
+
+            TOKEN_A = object()
+            TOKEN_B = object()
+
+            global_state.ensure_step_lock_run_initialized(TOKEN_A)
+
+            # Lock fires
+            strategy_is_active_from_state('PERPENDICULAR', 0.2)   # activate
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            self.assertTrue(global_state._step_lock_flags.get('PERPENDICULAR', False))
+
+            # New generation: new token
+            reset_happened = global_state.ensure_step_lock_run_initialized(TOKEN_B)
+
+            self.assertTrue(reset_happened, 'New token must trigger reset')
+            self.assertFalse(global_state._step_lock_flags.get('PERPENDICULAR', False),
+                             'Lock flags must be cleared for new generation')
+
+            # Strategy must now be active again (inside window)
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3),
+                            'Strategy must be active again after new generation reset')
+
+
+# ---------------------------------------------------------------------------
+# 8. begin_new_generation() vs reset_step_lock_flags() contract
+# ---------------------------------------------------------------------------
+
+class TestBeginNewGenerationContract(unittest.TestCase):
+
+    def test_begin_new_generation_increments_id(self):
+        with _StateGuard():
+            before = global_state._lock_generation_id
+            global_state.begin_new_generation()
+            self.assertGreater(global_state._lock_generation_id, before)
+
+    def test_begin_new_generation_clears_flags(self):
+        with _StateGuard():
+            global_state._step_lock_flags = {'PERPENDICULAR': True, 'SALIENCE_MASK': True}
+            global_state.begin_new_generation()
+            self.assertEqual(global_state._step_lock_flags, {})
+
+    def test_begin_new_generation_twice_clears_flags_both_times(self):
+        """Two consecutive begin_new_generation() calls each start with clean flags."""
+        with _StateGuard():
+            global_state.begin_new_generation()
+            global_state._step_lock_flags['PERPENDICULAR'] = True
+            global_state.begin_new_generation()
+            self.assertEqual(global_state._step_lock_flags, {})
+
+    def test_reset_step_lock_flags_does_not_change_generation_id(self):
+        with _StateGuard():
+            gen_id_before = global_state._lock_generation_id
+            global_state.reset_step_lock_flags()
+            self.assertEqual(global_state._lock_generation_id, gen_id_before)
+
+    def test_process_lifecycle_integration(self):
+        """
+        Verify the full lifecycle as used in scripts/neutral_prompt.py:
+        begin_new_generation() once per process() → locks survive denoising loop →
+        next begin_new_generation() clears them.
+        """
+        with _StateGuard():
+            global_state.step_window_enabled        = True
+            global_state.step_window_lock_after_end = True
+            global_state.step_window_global         = StepWindow(0.0, 0.5)
+            global_state.step_window_use_defaults   = False
+            global_state.step_window_per_strategy   = None
+
+            # --- Generation 1: process() called once ---
+            global_state.begin_new_generation()
+
+            strategy_is_active_from_state('PERPENDICULAR', 0.2)   # activate
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.7))
+            locked_gen1 = global_state._step_lock_flags.get('PERPENDICULAR', False)
+            self.assertTrue(locked_gen1)
+
+            # No new process() call → lock survives any step count
+            self.assertFalse(strategy_is_active_from_state('PERPENDICULAR', 0.0))
+
+            # --- Generation 2: new process() call ---
+            global_state.begin_new_generation()
+            flags_after_new_gen = global_state._step_lock_flags.copy()
+            self.assertEqual(flags_after_new_gen, {},
+                             'All flags must be cleared at start of new generation')
+
+            # Strategy active again inside its window
+            self.assertTrue(strategy_is_active_from_state('PERPENDICULAR', 0.3))
+
+
+if __name__ == '__main__':
+    unittest.main()
+

neutral_prompt_patcheds/test/perp_parser/test_malicious_parser.py

@@ -0,0 +1,182 @@
+import unittest
+import pathlib
+import sys
+sys.path.append(str(pathlib.Path(__file__).parent.parent.parent))
+from lib_neutral_prompt import neutral_prompt_parser
+
+
+class TestMaliciousPromptParser(unittest.TestCase):
+    def setUp(self):
+        self.parser = neutral_prompt_parser
+
+    def test_empty(self):
+        result = self.parser.parse_root("")
+        self.assertEqual(result.children[0].prompt, "")
+        self.assertEqual(result.children[0].weight, 1.0)
+
+    def test_zero_weight(self):
+        result = self.parser.parse_root("hello :0.0")
+        self.assertEqual(result.children[0].weight, 0.0)
+
+    def test_mixed_positive_and_negative_weights(self):
+        result = self.parser.parse_root("hello :1.0 AND goodbye :-2.0")
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[1].weight, -2.0)
+
+    def test_debalanced_square_brackets(self):
+        prompt = "a [ b " * 100
+        result = self.parser.parse_root(prompt)
+        self.assertEqual(result.children[0].prompt, prompt)
+
+        prompt = "a ] b " * 100
+        result = self.parser.parse_root(prompt)
+        self.assertEqual(result.children[0].prompt, prompt)
+
+        repeats = 10
+        prompt = "a [ [ b AND c ] " * repeats
+        result = self.parser.parse_root(prompt)
+        self.assertEqual([x.prompt for x in result.children], ["a [[ b ", *[" c ] a [[ b "] * (repeats - 1), " c ]"])
+
+        repeats = 10
+        prompt = "a [ b AND c ] ] " * repeats
+        result = self.parser.parse_root(prompt)
+        self.assertEqual([x.prompt for x in result.children], ["a [ b ", *[" c ]] a [ b "] * (repeats - 1), " c ]]"])
+
+    def test_erroneous_syntax(self):
+        result = self.parser.parse_root("hello :1.0 AND_PERP [goodbye :2.0")
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[1].prompt, "[goodbye ")
+        self.assertEqual(result.children[1].weight, 2.0)
+
+        result = self.parser.parse_root("hello :1.0 AND_PERP goodbye :2.0]")
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[1].prompt, " goodbye ")
+
+        result = self.parser.parse_root("hello :1.0 AND_PERP goodbye] :2.0")
+        self.assertEqual(result.children[1].prompt, " goodbye]")
+        self.assertEqual(result.children[1].weight, 2.0)
+
+        result = self.parser.parse_root("hello :1.0 AND_PERP a [ goodbye :2.0")
+        self.assertEqual(result.children[1].weight, 2.0)
+        self.assertEqual(result.children[1].prompt, " a [ goodbye ")
+
+        result = self.parser.parse_root("hello :1.0 AND_PERP AND goodbye :2.0")
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[2].prompt, " goodbye ")
+
+    def test_huge_number_of_prompt_parts(self):
+        result = self.parser.parse_root(" AND ".join(f"hello{i} :{i}" for i in range(10**4)))
+        self.assertEqual(len(result.children), 10**4)
+
+    def test_prompt_ending_with_weight(self):
+        result = self.parser.parse_root("hello :1.0 AND :2.0")
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[1].prompt, "")
+        self.assertEqual(result.children[1].weight, 2.0)
+
+    def test_huge_input_string(self):
+        big_string = "hello :1.0 AND " * 10**4
+        result = self.parser.parse_root(big_string)
+        self.assertEqual(len(result.children), 10**4 + 1)
+
+    def test_deeply_nested_prompt(self):
+        deeply_nested_prompt = "hello :1.0" + " AND_PERP [goodbye :2.0" * 100 + "]" * 100
+        result = self.parser.parse_root(deeply_nested_prompt)
+        self.assertIsInstance(result.children[1], neutral_prompt_parser.CompositePrompt)
+
+    def test_complex_nested_prompts(self):
+        complex_prompt = "hello :1.0 AND goodbye :2.0 AND_PERP [welcome :3.0 AND farewell :4.0 AND_PERP greetings:5.0]"
+        result = self.parser.parse_root(complex_prompt)
+        self.assertEqual(result.children[0].weight, 1.0)
+        self.assertEqual(result.children[1].weight, 2.0)
+        self.assertEqual(result.children[2].children[0].weight, 3.0)
+        self.assertEqual(result.children[2].children[1].weight, 4.0)
+        self.assertEqual(result.children[2].children[2].weight, 5.0)
+
+    def test_string_with_random_characters(self):
+        random_chars = "ASDFGHJKL:@#$/.,|}{><~`12[3]456AND_PERP7890"
+        try:
+            self.parser.parse_root(random_chars)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with random characters.")
+
+    def test_string_with_unexpected_symbols(self):
+        unexpected_symbols = "hello :1.0 AND $%^&*()goodbye :2.0"
+        try:
+            self.parser.parse_root(unexpected_symbols)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with unexpected symbols.")
+
+    def test_string_with_unconventional_structure(self):
+        unconventional_structure = "hello :1.0 AND_PERP :2.0 AND [goodbye]"
+        try:
+            self.parser.parse_root(unconventional_structure)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with unconventional structure.")
+
+    def test_string_with_mixed_alphabets_and_numbers(self):
+        mixed_alphabets_and_numbers = "123hello :1.0 AND goodbye456 :2.0"
+        try:
+            self.parser.parse_root(mixed_alphabets_and_numbers)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with mixed alphabets and numbers.")
+
+    def test_string_with_nested_brackets(self):
+        nested_brackets = "hello :1.0 AND [goodbye :2.0 AND [[welcome :3.0]]]"
+        try:
+            self.parser.parse_root(nested_brackets)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with nested brackets.")
+
+    def test_unmatched_opening_braces(self):
+        unmatched_opening_braces = "hello [[[[[[[[[ :1.0 AND_PERP goodbye :2.0"
+        try:
+            self.parser.parse_root(unmatched_opening_braces)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with unmatched opening braces.")
+
+    def test_unmatched_closing_braces(self):
+        unmatched_closing_braces = "hello :1.0 AND_PERP goodbye ]]]]]]]]] :2.0"
+        try:
+            self.parser.parse_root(unmatched_closing_braces)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with unmatched closing braces.")
+
+    def test_repeating_colons(self):
+        repeating_colons = "hello ::::::: :1.0 AND_PERP goodbye :::: :2.0"
+        try:
+            self.parser.parse_root(repeating_colons)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with repeating colons.")
+
+    def test_excessive_whitespace(self):
+        excessive_whitespace = "hello    :1.0  AND_PERP     goodbye  :2.0"
+        try:
+            self.parser.parse_root(excessive_whitespace)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with excessive whitespace.")
+
+    def test_repeating_AND_keyword(self):
+        repeating_AND_keyword = "hello :1.0 AND AND AND AND AND goodbye :2.0"
+        try:
+            self.parser.parse_root(repeating_AND_keyword)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with repeating AND keyword.")
+
+    def test_repeating_AND_PERP_keyword(self):
+        repeating_AND_PERP_keyword = "hello :1.0 AND_PERP AND_PERP AND_PERP AND_PERP goodbye :2.0"
+        try:
+            self.parser.parse_root(repeating_AND_PERP_keyword)
+        except Exception:
+            self.fail("parse_root couldn't handle a string with repeating AND_PERP keyword.")
+
+    def test_square_weight_prompt(self):
+        prompt = "AND_PERP [weighted] you thought it was the end"
+        try:
+            self.parser.parse_root(prompt)
+        except Exception:
+            self.fail("parse_root couldn't handle a string starting with a square-weighted sub-prompt.")
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_matryoshka.py

@@ -0,0 +1,440 @@
+"""
+Tests for v1.1 matryoshka tree render, diagnostics, and builder helpers.
+All tests are pure-Python and require no real torch or gradio.
+"""
+
+import unittest
+# mock_torch is installed by the package __init__ before this file loads
+
+import lib_neutral_prompt.neutral_prompt_parser as p
+from lib_neutral_prompt.matryoshka_utils import (
+    render_prompt_node,
+    render_prompt_tree,
+    collect_prompt_diagnostics,
+    render_diagnostics,
+    render_full_explain,
+    build_child_block,
+    build_nested_prompt,
+    MATRYOSHKA_TEMPLATES,
+    _build_affine_snippet,
+)
+
+
+# ---------------------------------------------------------------------------
+# render_prompt_tree
+# ---------------------------------------------------------------------------
+
+class TestRenderPromptTree(unittest.TestCase):
+
+    def test_empty_prompt_returns_hint(self):
+        out = render_prompt_tree('')
+        self.assertIn('empty', out.lower())
+
+    def test_base_only(self):
+        out = render_prompt_tree('a dog in a park')
+        self.assertIn('ROOT', out)
+        self.assertIn('BASE', out)
+        self.assertIn('a dog in a park', out)
+
+    def test_single_child(self):
+        out = render_prompt_tree('base subject AND_SALT[5] texture :0.8')
+        self.assertIn('BASE', out)
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('k=5', out)
+
+    def test_topk_child(self):
+        out = render_prompt_tree('base AND_TOPK[0.1] highlights :0.6')
+        self.assertIn('SEMANTIC_GUIDANCE', out)
+        self.assertIn('threshold=0.1', out)
+
+    def test_align_child(self):
+        out = render_prompt_tree('base AND_ALIGN[4,8] style :0.7')
+        self.assertIn('ALIGNMENT_BLEND_CUSTOM', out)
+        self.assertIn('d=4', out)
+        self.assertIn('s=8', out)
+
+    def test_affine_annotated(self):
+        out = render_prompt_tree('base ROTATE[0.125] AND_PERP vivid :0.8')
+        self.assertIn('affine', out)
+
+    def test_multiple_children_all_shown(self):
+        out = render_prompt_tree('base AND_SALT[5] tex :0.8 AND_TOPK[0.1] style :0.6')
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('SEMANTIC_GUIDANCE', out)
+
+    def test_nested_prompt_depth(self):
+        # nested composite should show multiple levels
+        prompt = 'base AND_SALT[5] [ inner text :0.8 AND_TOPK[0.1] detail :0.5 ] :0.7'
+        out = render_prompt_tree(prompt)
+        self.assertIn('SALIENCE_MASK', out)
+        # inner structure rendered
+
+    def test_tree_connectors_present(self):
+        out = render_prompt_tree('base AND_SALT[5] tex :0.8 AND_PERP vivid :0.5')
+        # should contain box-drawing branch chars
+        self.assertTrue('├' in out or '└' in out)
+
+    def test_weight_shown(self):
+        out = render_prompt_tree('base AND_PERP style :0.42')
+        self.assertIn('0.42', out)
+
+    def test_parse_error_graceful(self):
+        # Pathological input must not raise
+        try:
+            out = render_prompt_tree('[[[[[')
+        except Exception as exc:
+            self.fail(f'render_prompt_tree raised on bad input: {exc}')
+
+    def test_deeply_nested(self):
+        prompt = ('base AND_SALT[5] [\n'
+                  '  region :0.8\n'
+                  '  AND_ALIGN[4,8] [\n'
+                  '    sub-structure :0.7\n'
+                  '    AND_TOPK[0.05] micro :0.4\n'
+                  '  ] :0.6\n'
+                  '] :0.7')
+        try:
+            out = render_prompt_tree(prompt)
+        except Exception as exc:
+            self.fail(f'deeply nested raised: {exc}')
+        self.assertIn('ROOT', out)
+
+
+# ---------------------------------------------------------------------------
+# render_prompt_node (unit)
+# ---------------------------------------------------------------------------
+
+class TestRenderPromptNode(unittest.TestCase):
+
+    def _leaf_node(self, text='hello', strat=None, params=None, w=1.0):
+        return p.LeafPrompt(
+            weight=w,
+            conciliation=strat,
+            local_transform=None,
+            prompt=text,
+            conciliation_params=params or {},
+        )
+
+    def test_base_leaf(self):
+        node = self._leaf_node('base text')
+        lines = render_prompt_node(node)
+        self.assertEqual(len(lines), 1)
+        self.assertIn('BASE', lines[0])
+        self.assertIn('base text', lines[0])
+
+    def test_leaf_with_params(self):
+        node = self._leaf_node('texture', strat=p.ConciliationStrategy.SALIENCE_MASK,
+                               params={'k': 5.0})
+        lines = render_prompt_node(node)
+        self.assertIn('k=5.0', lines[0])
+
+    def test_leaf_affine_flag(self):
+        import lib_neutral_prompt.neutral_prompt_parser as _pp
+        node = self._leaf_node('vivid', strat=_pp.ConciliationStrategy.PERPENDICULAR)
+        try:
+            import torch
+            node.local_transform = torch.eye(3)[:-1]
+        except ImportError:
+            return  # skip if no torch
+        lines = render_prompt_node(node)
+        self.assertIn('affine', lines[0])
+
+    def test_connector_chars_for_non_last(self):
+        node = self._leaf_node('x')
+        lines = render_prompt_node(node, is_last=False)
+        self.assertTrue(lines[0].startswith('├─'))
+
+    def test_connector_chars_for_last(self):
+        node = self._leaf_node('x')
+        lines = render_prompt_node(node, is_last=True)
+        self.assertTrue(lines[0].startswith('└─'))
+
+
+# ---------------------------------------------------------------------------
+# collect_prompt_diagnostics
+# ---------------------------------------------------------------------------
+
+class TestCollectDiagnostics(unittest.TestCase):
+
+    def test_empty_prompt(self):
+        d = collect_prompt_diagnostics('')
+        self.assertFalse(d['parse_ok'])
+
+    def test_base_only(self):
+        d = collect_prompt_diagnostics('a dog')
+        self.assertTrue(d['parse_ok'])
+        self.assertGreater(d['n_segments'], 0)
+        self.assertIn('BASE', d['strategies'])
+
+    def test_single_salt(self):
+        d = collect_prompt_diagnostics('base AND_SALT[5] texture :0.8')
+        self.assertTrue(d['parse_ok'])
+        self.assertIn('SALIENCE_MASK', d['strategies'])
+        self.assertIn('BASE', d['strategies'])
+
+    def test_no_base_fires_protection(self):
+        d = collect_prompt_diagnostics('AND_SALT[5] concept :0.8')
+        self.assertTrue(d['parse_ok'])
+        self.assertTrue(d['protection_would_fire'])
+
+    def test_with_base_no_fire(self):
+        d = collect_prompt_diagnostics('base subject AND_PERP style :0.8')
+        self.assertFalse(d['protection_would_fire'])
+
+    def test_max_depth_base(self):
+        d = collect_prompt_diagnostics('just a base')
+        self.assertGreaterEqual(d['max_depth'], 0)
+
+    def test_affine_counted(self):
+        d = collect_prompt_diagnostics('base ROTATE[0.125] AND_PERP vivid :0.8')
+        self.assertGreater(d['n_affine'], 0)
+
+    def test_multiple_strategies(self):
+        d = collect_prompt_diagnostics('base AND_SALT[5] tex :0.8 AND_TOPK[0.1] sty :0.6')
+        self.assertIn('SALIENCE_MASK', d['strategies'])
+        self.assertIn('SEMANTIC_GUIDANCE', d['strategies'])
+
+    def test_parse_error_graceful(self):
+        d = collect_prompt_diagnostics('AND[invalid garbage')
+        # Should not raise; parse_ok may be False or True depending on parser tolerance
+
+
+# ---------------------------------------------------------------------------
+# render_diagnostics
+# ---------------------------------------------------------------------------
+
+class TestRenderDiagnostics(unittest.TestCase):
+
+    def test_no_base_warning(self):
+        d = collect_prompt_diagnostics('AND_SALT[5] only :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('WOULD FIRE', out)
+
+    def test_ok_case(self):
+        d = collect_prompt_diagnostics('base AND_PERP style :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('OK', out)
+
+    def test_parse_error_shown(self):
+        d = {'parse_ok': False, 'parse_error': 'something bad'}
+        out = render_diagnostics(d)
+        self.assertIn('something bad', out)
+
+    def test_strategies_listed(self):
+        d = collect_prompt_diagnostics('base AND_SALT[5] tex :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('SALIENCE_MASK', out)
+
+
+# ---------------------------------------------------------------------------
+# render_full_explain
+# ---------------------------------------------------------------------------
+
+class TestRenderFullExplain(unittest.TestCase):
+
+    def test_contains_both_tree_and_diagnostics(self):
+        out = render_full_explain('base AND_SALT[5] texture :0.8')
+        self.assertIn('ROOT', out)
+        self.assertIn('Diagnostics', out)
+
+    def test_empty_prompt(self):
+        out = render_full_explain('')
+        self.assertIn('empty', out.lower())
+
+    def test_nested_prompt(self):
+        try:
+            out = render_full_explain(
+                'base AND_SALT[5] [ inner :0.8 AND_TOPK[0.05] detail :0.4 ] :0.7'
+            )
+        except Exception as exc:
+            self.fail(f'render_full_explain raised on nested: {exc}')
+        self.assertIn('ROOT', out)
+
+
+# ---------------------------------------------------------------------------
+# build_child_block
+# ---------------------------------------------------------------------------
+
+class TestBuildChildBlock(unittest.TestCase):
+
+    def test_simple_salt(self):
+        out = build_child_block('AND_SALT', 'texture detail', 0.8)
+        self.assertIn('AND_SALT[5]', out)
+        self.assertIn('texture detail', out)
+        self.assertIn(':0.8', out)
+
+    def test_topk_threshold(self):
+        out = build_child_block('AND_TOPK', 'highlights', 0.5)
+        self.assertIn('AND_TOPK[0.05]', out)
+        self.assertIn('highlights', out)
+
+    def test_align_default(self):
+        out = build_child_block('AND_ALIGN', 'structure', 0.7)
+        self.assertIn('AND_ALIGN[4,8]', out)
+
+    def test_perp_simple(self):
+        out = build_child_block('AND_PERP', 'blur', 0.5)
+        self.assertIn('AND_PERP', out)
+        self.assertIn('blur', out)
+
+    def test_with_affine(self):
+        out = build_child_block('AND_PERP', 'mirror', 0.6, affine='SCALE[-1,1]')
+        self.assertIn('SCALE[-1,1]', out)
+        self.assertTrue(out.startswith('SCALE[-1,1]'))
+
+    def test_with_nested_child(self):
+        nested = build_child_block('AND_TOPK', 'highlights', 0.4)
+        out = build_child_block('AND_SALT', 'texture', 0.8, nested=nested)
+        self.assertIn('[', out)
+        self.assertIn(']', out)
+        self.assertIn('AND_TOPK', out)
+
+    def test_empty_text_handled(self):
+        out = build_child_block('AND_SALT', '', 0.8)
+        # Empty text → empty string (caller should skip)
+        self.assertEqual(out, '')
+
+    def test_weight_formatting(self):
+        out = build_child_block('AND_PERP', 'concept', 0.35)
+        self.assertIn(':0.35', out)
+
+    def test_nested_block_indented(self):
+        nested = build_child_block('AND_PERP', 'inner', 0.4)
+        out = build_child_block('AND_SALT', 'outer', 0.8, nested=nested)
+        # Inner content should be indented
+        lines = out.splitlines()
+        inner_lines = [l for l in lines if 'inner' in l]
+        self.assertTrue(any(l.startswith('  ') for l in inner_lines),
+                        'Inner nested line should be indented')
+
+
+# ---------------------------------------------------------------------------
+# build_nested_prompt
+# ---------------------------------------------------------------------------
+
+class TestBuildNestedPrompt(unittest.TestCase):
+
+    def test_base_only(self):
+        out = build_nested_prompt('a dog', [])
+        self.assertEqual(out.strip(), 'a dog')
+
+    def test_base_with_one_child(self):
+        out = build_nested_prompt('base subject', [
+            {'strategy': 'AND_SALT', 'text': 'texture', 'weight': 0.8},
+        ])
+        self.assertIn('base subject', out)
+        self.assertIn('AND_SALT', out)
+        self.assertIn('texture', out)
+
+    def test_two_children(self):
+        out = build_nested_prompt('base', [
+            {'strategy': 'AND_SALT',  'text': 'tex', 'weight': 0.8},
+            {'strategy': 'AND_TOPK',  'text': 'sty', 'weight': 0.5},
+        ])
+        self.assertIn('AND_SALT', out)
+        self.assertIn('AND_TOPK', out)
+
+    def test_child_with_nested(self):
+        inner = build_child_block('AND_TOPK', 'highlights', 0.4)
+        out = build_nested_prompt('base', [
+            {'strategy': 'AND_SALT', 'text': 'texture', 'weight': 0.8, 'nested': inner},
+        ])
+        self.assertIn('AND_TOPK', out)
+
+    def test_generated_prompt_parseable(self):
+        out = build_nested_prompt('base subject', [
+            {'strategy': 'AND_SALT',  'text': 'tex', 'weight': 0.8},
+            {'strategy': 'AND_PERP',  'text': 'sty', 'weight': 0.5},
+        ])
+        try:
+            p.parse_root(out)
+        except Exception as exc:
+            self.fail(f'build_nested_prompt produced unparseable prompt: {exc}')
+
+    def test_empty_base_no_crash(self):
+        out = build_nested_prompt('', [
+            {'strategy': 'AND_SALT', 'text': 'texture', 'weight': 0.8},
+        ])
+        self.assertIn('AND_SALT', out)
+
+    def test_child_with_empty_text_skipped(self):
+        out = build_nested_prompt('base', [
+            {'strategy': 'AND_SALT', 'text': '', 'weight': 0.8},
+        ])
+        # Empty text child: no crash, base survives
+        self.assertIn('base', out)
+
+
+# ---------------------------------------------------------------------------
+# MATRYOSHKA_TEMPLATES
+# ---------------------------------------------------------------------------
+
+class TestMatryoshkaTemplates(unittest.TestCase):
+
+    def test_all_templates_have_required_keys(self):
+        for name, tmpl in MATRYOSHKA_TEMPLATES.items():
+            with self.subTest(template=name):
+                self.assertIn('description', tmpl, f'{name}: missing "description"')
+                self.assertIn('prompt', tmpl,      f'{name}: missing "prompt"')
+                self.assertIsInstance(tmpl['description'], str)
+                self.assertIsInstance(tmpl['prompt'], str)
+
+    def test_all_templates_parse_without_crash(self):
+        for name, tmpl in MATRYOSHKA_TEMPLATES.items():
+            with self.subTest(template=name):
+                try:
+                    p.parse_root(tmpl['prompt'])
+                except Exception as exc:
+                    self.fail(f'Template "{name}" failed parse_root: {exc}')
+
+    def test_all_template_prompts_nonempty(self):
+        for name, tmpl in MATRYOSHKA_TEMPLATES.items():
+            with self.subTest(template=name):
+                self.assertTrue(tmpl['prompt'].strip(), f'{name} prompt is empty')
+
+    def test_at_least_five_templates(self):
+        self.assertGreaterEqual(len(MATRYOSHKA_TEMPLATES), 5)
+
+    def test_deep_nested_template_parseable(self):
+        tmpl = MATRYOSHKA_TEMPLATES.get('Deep nested concept isolation')
+        if tmpl:
+            try:
+                p.parse_root(tmpl['prompt'])
+            except Exception as exc:
+                self.fail(f'Deep nested template parse failed: {exc}')
+
+
+# ---------------------------------------------------------------------------
+# _build_affine_snippet (already tested in test_parametric_syntax, quick sanity)
+# ---------------------------------------------------------------------------
+
+class TestAffineSnippetSanity(unittest.TestCase):
+
+    def test_flip_h(self):
+        self.assertEqual(_build_affine_snippet('FLIP_H', 0, 0), 'SCALE[-1,1]')
+
+    def test_rotate(self):
+        s = _build_affine_snippet('ROTATE', 0.25, 1.0)
+        self.assertIn('ROTATE', s)
+        self.assertIn('0.25', s)
+
+    def test_scale_uniform(self):
+        s = _build_affine_snippet('SCALE', 2.0, 2.0)
+        self.assertEqual(s, 'SCALE[2.0]')
+
+    def test_slide_2d(self):
+        s = _build_affine_snippet('SLIDE', 0.1, 0.2)
+        self.assertEqual(s, 'SLIDE[0.1,0.2]')
+
+    def test_snippet_parseable(self):
+        snippets = ['ROTATE[0.125]', 'SCALE[-1,1]', 'SCALE[0.5]', 'SLIDE[0.1,0.0]']
+        for snip in snippets:
+            with self.subTest(snip=snip):
+                try:
+                    p.parse_root(f'base {snip} AND_PERP style :0.8')
+                except Exception as exc:
+                    self.fail(f'Snippet "{snip}" not parseable: {exc}')
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_matryoshka_golden.py

@@ -0,0 +1,331 @@
+"""
+Golden tests for matryoshka_utils: tree render, diagnostics, effect summaries.
+
+These tests lock in the *exact* formatted output for a set of representative
+prompts so that silent formatting/logic regressions are caught immediately.
+They also cover the polishing fixes from Sprint 1:
+  - build_child_block: empty text → empty string
+  - build_child_block: empty text + nested → no bare ':weight' line
+  - render_full_explain: empty prompt → clean message only
+  - effect summaries appear in render_full_explain output
+"""
+
+import unittest
+# mock_torch installed by package __init__
+
+import lib_neutral_prompt.neutral_prompt_parser as p
+from lib_neutral_prompt.matryoshka_utils import (
+    build_child_block,
+    build_nested_prompt,
+    render_prompt_tree,
+    render_prompt_node,
+    collect_prompt_diagnostics,
+    render_diagnostics,
+    render_full_explain,
+    _render_effect_summary,
+    _effect_for_strategy,
+)
+
+
+# ---------------------------------------------------------------------------
+# Builder polishing: empty-text behaviour
+# ---------------------------------------------------------------------------
+
+class TestBuilderEmptyTextPolishing(unittest.TestCase):
+
+    def test_empty_text_returns_empty_string(self):
+        out = build_child_block('AND_SALT', '', 0.8)
+        self.assertEqual(out, '',
+                         'Empty text with no nested must return empty string')
+
+    def test_empty_text_empty_nested_returns_empty_string(self):
+        out = build_child_block('AND_TOPK', '', 0.5, nested='')
+        self.assertEqual(out, '')
+
+    def test_empty_text_whitespace_returns_empty_string(self):
+        out = build_child_block('AND_PERP', '   ', 0.7)
+        self.assertEqual(out, '')
+
+    def test_empty_text_with_nested_no_bare_weight_line(self):
+        """If text is empty but nested is not, the nested block must not
+        include a bare '  :0.5' line at the top."""
+        nested = 'AND_PERP blur :0.4'
+        out = build_child_block('AND_TOPK', '', 0.5, nested=nested)
+        # Should not be empty (nested content exists)
+        self.assertNotEqual(out, '')
+        # Must not contain a line that is only whitespace + ':weight'
+        for line in out.splitlines():
+            stripped = line.strip()
+            self.assertFalse(
+                stripped.startswith(':') and len(stripped.split()) == 1,
+                f'Found bare weight line: {repr(line)}',
+            )
+
+    def test_nonempty_text_with_nested_includes_text_line(self):
+        """When text is non-empty, the nested block must include a text line."""
+        nested = 'AND_PERP correction :0.3'
+        out = build_child_block('AND_SALT', 'texture', 0.8, nested=nested)
+        self.assertIn('texture', out)
+        self.assertIn('AND_PERP', out)
+        self.assertIn('[', out)
+
+    def test_nested_prompt_skips_empty_children(self):
+        out = build_nested_prompt('base subject', [
+            {'strategy': 'AND_SALT', 'text': '',        'weight': 0.8},  # empty → skip
+            {'strategy': 'AND_PERP', 'text': 'vivid',   'weight': 0.5},  # kept
+            {'strategy': 'AND_TOPK', 'text': '  ',      'weight': 0.6},  # whitespace → skip
+        ])
+        self.assertIn('AND_PERP', out)
+        self.assertNotIn('AND_SALT', out)
+        self.assertNotIn('AND_TOPK', out)
+
+    def test_nested_prompt_all_empty_children_gives_base_only(self):
+        out = build_nested_prompt('base', [
+            {'strategy': 'AND_SALT', 'text': '', 'weight': 0.8},
+        ])
+        self.assertEqual(out.strip(), 'base')
+
+    def test_nested_only_child_no_text(self):
+        """Child with empty text but non-empty nested should be kept."""
+        inner = build_child_block('AND_PERP', 'correction', 0.3)
+        out = build_child_block('AND_TOPK', '', 0.5, nested=inner)
+        self.assertNotEqual(out, '', 'Should keep block when nested is non-empty')
+        self.assertIn('AND_PERP', out)
+
+
+# ---------------------------------------------------------------------------
+# render_full_explain: empty-prompt clean state
+# ---------------------------------------------------------------------------
+
+class TestRenderFullExplainEmptyState(unittest.TestCase):
+
+    def test_empty_string_returns_clean_message(self):
+        out = render_full_explain('')
+        self.assertIn('empty', out.lower())
+        self.assertNotIn('Parse error', out)
+        self.assertNotIn('unknown', out.lower())
+
+    def test_whitespace_only_returns_clean_message(self):
+        out = render_full_explain('   \n  ')
+        self.assertIn('empty', out.lower())
+        self.assertNotIn('Parse error', out)
+
+    def test_nonempty_prompt_no_empty_message(self):
+        out = render_full_explain('base AND_SALT[5] texture :0.8')
+        self.assertNotIn('empty prompt', out.lower())
+        self.assertIn('ROOT', out)
+
+
+# ---------------------------------------------------------------------------
+# Effect summaries
+# ---------------------------------------------------------------------------
+
+class TestEffectSummary(unittest.TestCase):
+
+    def test_effect_for_base(self):
+        desc = _effect_for_strategy('BASE')
+        self.assertIn('base', desc.lower())
+
+    def test_effect_for_salience_mask(self):
+        desc = _effect_for_strategy('SALIENCE_MASK')
+        self.assertIn('saliency', desc.lower())
+
+    def test_effect_for_semantic_guidance(self):
+        desc = _effect_for_strategy('SEMANTIC_GUIDANCE')
+        self.assertIn('top-k', desc.lower())
+
+    def test_effect_for_alignment_custom(self):
+        desc = _effect_for_strategy('ALIGNMENT_BLEND_CUSTOM')
+        self.assertIn('align', desc.lower())
+
+    def test_effect_for_alignment_legacy_suffix(self):
+        # Fixed-suffix strategies like ALIGNMENT_BLEND_4_8 → same description
+        desc = _effect_for_strategy('ALIGNMENT_BLEND_4_8')
+        self.assertIn('align', desc.lower())
+
+    def test_effect_for_unknown_strategy(self):
+        desc = _effect_for_strategy('SOME_UNKNOWN_STRATEGY')
+        self.assertIn('SOME_UNKNOWN_STRATEGY', desc)
+
+    def test_effect_summary_in_render_full_explain(self):
+        out = render_full_explain('base AND_SALT[5] texture :0.8')
+        self.assertIn('Effect summary', out)
+        self.assertIn('SALIENCE_MASK', out)
+
+    def test_effect_summary_notes_preview_nature(self):
+        out = render_full_explain('base AND_TOPK[0.1] highlights :0.6')
+        self.assertIn('structural preview', out.lower())
+
+    def test_render_effect_summary_empty_on_parse_fail(self):
+        diag = {'parse_ok': False, 'strategies': []}
+        out = _render_effect_summary(diag)
+        self.assertEqual(out, '')
+
+    def test_render_effect_summary_empty_on_no_strategies(self):
+        diag = {'parse_ok': True, 'strategies': []}
+        out = _render_effect_summary(diag)
+        self.assertEqual(out, '')
+
+
+# ---------------------------------------------------------------------------
+# Golden: tree format
+# ---------------------------------------------------------------------------
+
+class TestTreeGoldenFormat(unittest.TestCase):
+    """Check structural properties of the tree output rather than exact strings,
+    making these tests robust to minor phrasing changes while still catching
+    regressions in tree shape, connectors, and content."""
+
+    def _tree(self, prompt):
+        return render_prompt_tree(prompt)
+
+    def test_root_header(self):
+        out = self._tree('base AND_PERP style :0.8')
+        self.assertTrue(out.startswith('ROOT'), f'Expected ROOT header, got: {out[:40]}')
+
+    def test_leaf_connector_last(self):
+        out = self._tree('base AND_PERP style :0.8')
+        # Last segment uses └─
+        self.assertIn('└─', out)
+
+    def test_multiple_children_mixed_connectors(self):
+        out = self._tree('base AND_SALT[5] tex :0.8 AND_PERP vivid :0.5')
+        self.assertIn('├─', out)
+        self.assertIn('└─', out)
+
+    def test_base_shows_BASE(self):
+        out = self._tree('base subject')
+        self.assertIn('BASE', out)
+
+    def test_salt_shows_k_param(self):
+        out = self._tree('base AND_SALT[7] texture :0.8')
+        self.assertIn('k=7.0', out)
+
+    def test_topk_shows_threshold_param(self):
+        out = self._tree('base AND_TOPK[0.15] highlights :0.6')
+        self.assertIn('threshold=0.15', out)
+
+    def test_align_shows_d_s_params(self):
+        out = self._tree('base AND_ALIGN[6,12] style :0.7')
+        self.assertIn('d=6', out)
+        self.assertIn('s=12', out)
+
+    def test_weight_shown_to_two_decimals(self):
+        out = self._tree('base AND_PERP vivid :0.42')
+        self.assertIn('0.42', out)
+
+    def test_nested_composite_shows_children_count(self):
+        prompt = 'base AND_SALT[5] [ texture :0.8 AND_TOPK[0.05] detail :0.4 ] :0.7'
+        out = self._tree(prompt)
+        # Composite node should show "(N children)"
+        self.assertIn('children)', out)
+
+    def test_deep_nested_has_continuation_bar(self):
+        prompt = ('base AND_SALT[5] [\n'
+                  '  region :0.8\n'
+                  '  AND_ALIGN[4,8] [\n'
+                  '    sub :0.7\n'
+                  '    AND_TOPK[0.05] micro :0.4\n'
+                  '  ] :0.6\n'
+                  '] :0.7')
+        out = self._tree(prompt)
+        # Deep nesting should show either │ continuation bars or ├─/└─ at 2+ depths
+        # (exact rendering depends on depth threshold)
+        # Ensure at least 3 levels of nesting are represented in the tree
+        self.assertGreaterEqual(out.count('├─') + out.count('└─'), 4,
+                                'Expected at least 4 branch markers for deep nesting')
+
+    def test_affine_annotated(self):
+        out = self._tree('base ROTATE[0.125] AND_PERP vivid :0.8')
+        self.assertIn('affine', out)
+
+    def test_text_truncated_at_55_chars(self):
+        long_text = 'a' * 60
+        out = self._tree(f'base AND_PERP {long_text} :0.8')
+        self.assertIn('…', out)
+
+    def test_empty_returns_clean_empty_message(self):
+        out = self._tree('')
+        self.assertIn('empty', out.lower())
+        self.assertNotIn('ROOT', out)
+
+
+# ---------------------------------------------------------------------------
+# Golden: diagnostics content
+# ---------------------------------------------------------------------------
+
+class TestDiagnosticsGolden(unittest.TestCase):
+
+    def _diag(self, prompt):
+        return collect_prompt_diagnostics(prompt)
+
+    def test_base_only_n_segments(self):
+        d = self._diag('a dog in a park')
+        self.assertGreaterEqual(d['n_segments'], 1)
+
+    def test_two_children_strategy_list(self):
+        d = self._diag('base AND_SALT[5] tex :0.8 AND_TOPK[0.1] sty :0.6')
+        self.assertIn('SALIENCE_MASK',    d['strategies'])
+        self.assertIn('SEMANTIC_GUIDANCE', d['strategies'])
+        self.assertIn('BASE',              d['strategies'])
+
+    def test_affine_count(self):
+        d = self._diag('base ROTATE[0.125] AND_PERP vivid :0.8')
+        self.assertGreaterEqual(d['n_affine'], 1)
+
+    def test_protection_fires_no_base(self):
+        d = self._diag('AND_SALT[5] only :0.8')
+        self.assertTrue(d['protection_would_fire'])
+
+    def test_protection_ok_with_base(self):
+        d = self._diag('base AND_SALT[5] tex :0.8')
+        self.assertFalse(d['protection_would_fire'])
+
+    def test_depth_deep_nested(self):
+        prompt = ('base AND_SALT[5] [\n'
+                  '  region :0.8\n'
+                  '  AND_ALIGN[4,8] [\n'
+                  '    sub :0.7\n'
+                  '    AND_TOPK[0.05] micro :0.4\n'
+                  '  ] :0.6\n'
+                  '] :0.7')
+        d = self._diag(prompt)
+        self.assertGreaterEqual(d['max_depth'], 2)
+
+    def test_render_diagnostics_includes_strategies(self):
+        d = self._diag('base AND_SALT[5] tex :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('Strategies used', out)
+
+    def test_render_diagnostics_protection_would_fire_message(self):
+        d = self._diag('AND_TOPK[0.1] only :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('WOULD FIRE', out)
+
+    def test_render_diagnostics_ok_message(self):
+        d = self._diag('base AND_PERP style :0.8')
+        out = render_diagnostics(d)
+        self.assertIn('OK', out)
+
+
+# ---------------------------------------------------------------------------
+# Integration: full explain round-trip for all templates
+# ---------------------------------------------------------------------------
+
+class TestTemplatesExplainIntegration(unittest.TestCase):
+    """Every template must produce a non-trivial full explain output."""
+
+    def test_all_templates_full_explain(self):
+        from lib_neutral_prompt.matryoshka_utils import MATRYOSHKA_TEMPLATES
+        for name, tmpl in MATRYOSHKA_TEMPLATES.items():
+            with self.subTest(template=name):
+                out = render_full_explain(tmpl['prompt'])
+                self.assertIn('ROOT', out,  f'{name}: missing ROOT in explain')
+                self.assertIn('Diagnostics', out, f'{name}: missing Diagnostics')
+                self.assertIn('Effect summary', out, f'{name}: missing Effect summary')
+                self.assertNotIn('Parse error', out, f'{name}: unexpected parse error')
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_parametric_syntax.py

@@ -0,0 +1,535 @@
+"""
+Tests for parametric prompt syntax (patched extension).
+
+Requires: torch OR falls back to mock_torch for pure parser logic.
+
+Covers:
+  - AND_SALT[k] / AND_SALT_WIDE[k] / AND_SALT_BLOB[k]  parser
+  - AND_ALIGN[d,s] / AND_MASK_ALIGN[d,s]                parser
+  - conciliation_params populated correctly
+  - weight still parsed correctly alongside params
+  - composite brackets NOT consumed as params
+  - backward-compat: AND_ALIGN_4_8 still works
+  - invalid / boundary params rejected gracefully
+  - params survive alongside affine transforms
+"""
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent.parent))
+
+# mock_torch installed by package __init__.py
+
+from lib_neutral_prompt import neutral_prompt_parser as p
+
+CS = p.ConciliationStrategy
+
+
+def _child(prompt_str, idx=-1):
+    return p.parse_root(prompt_str).children[idx]
+
+
+class TestSaltKParam(unittest.TestCase):
+
+    def test_salt_default_no_params(self):
+        child = _child("base AND_SALT concept :1.0")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK)
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_with_k_integer(self):
+        child = _child("base AND_SALT[5] concept :1.0")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK)
+        self.assertAlmostEqual(child.conciliation_params['k'], 5.0)
+
+    def test_salt_with_k_float(self):
+        child = _child("base AND_SALT[3.5] concept :0.8")
+        self.assertAlmostEqual(child.conciliation_params['k'], 3.5)
+
+    def test_salt_k_preserves_weight(self):
+        child = _child("base AND_SALT[5] concept :0.75")
+        self.assertAlmostEqual(child.weight, 0.75)
+        self.assertAlmostEqual(child.conciliation_params['k'], 5.0)
+
+    def test_salt_wide_with_k(self):
+        child = _child("base AND_SALT_WIDE[1.5] concept :1.0")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK_WIDE)
+        self.assertAlmostEqual(child.conciliation_params['k'], 1.5)
+
+    def test_salt_wide_default_no_params(self):
+        child = _child("base AND_SALT_WIDE concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_blob_with_k(self):
+        child = _child("base AND_SALT_BLOB[8] concept :1.0")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK_BLOB)
+        self.assertAlmostEqual(child.conciliation_params['k'], 8.0)
+
+    def test_salt_blob_default_no_params(self):
+        child = _child("base AND_SALT_BLOB concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_k_zero_rejected(self):
+        child = _child("base AND_SALT[0] concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_k_negative_rejected(self):
+        child = _child("base AND_SALT[-1] concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_k_max_value_accepted(self):
+        child = _child("base AND_SALT[20] concept :1.0")
+        self.assertAlmostEqual(child.conciliation_params['k'], 20.0)
+
+    def test_salt_k_very_small_accepted(self):
+        child = _child("base AND_SALT[0.5] concept :1.0")
+        self.assertAlmostEqual(child.conciliation_params['k'], 0.5)
+
+
+class TestAlignBracketParam(unittest.TestCase):
+
+    def test_align_bracket_basic(self):
+        child = _child("base AND_ALIGN[4,8] style :0.5")
+        self.assertEqual(child.conciliation, CS.ALIGNMENT_BLEND_CUSTOM)
+        self.assertEqual(child.conciliation_params, {'d': 4, 's': 8})
+
+    def test_align_bracket_large_pair(self):
+        child = _child("base AND_ALIGN[8,32] style :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 8, 's': 32})
+
+    def test_align_bracket_preserves_weight(self):
+        child = _child("base AND_ALIGN[4,8] style :0.65")
+        self.assertAlmostEqual(child.weight, 0.65)
+        self.assertEqual(child.conciliation_params, {'d': 4, 's': 8})
+
+    def test_mask_align_bracket_basic(self):
+        child = _child("base AND_MASK_ALIGN[6,12] structure :0.7")
+        self.assertEqual(child.conciliation, CS.ALIGNMENT_MASK_BLEND_CUSTOM)
+        self.assertEqual(child.conciliation_params, {'d': 6, 's': 12})
+
+    def test_mask_align_bracket_min_pair(self):
+        child = _child("base AND_MASK_ALIGN[2,3] structure :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 2, 's': 3})
+
+    def test_align_equal_ds_rejected(self):
+        """d == s has no structural distinction → params must be rejected."""
+        child = _child("base AND_ALIGN[4,4] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_align_d_out_of_range_low(self):
+        child = _child("base AND_ALIGN[1,8] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_align_s_out_of_range_high(self):
+        child = _child("base AND_ALIGN[4,33] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_align_inverted_pair_accepted(self):
+        """d > s is valid (just an unusual choice) as long as d != s."""
+        child = _child("base AND_ALIGN[8,4] style :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 8, 's': 4})
+
+
+class TestBackwardCompatibility(unittest.TestCase):
+
+    def test_fixed_suffix_align(self):
+        child = _child("base AND_ALIGN_4_8 style :0.5")
+        self.assertEqual(child.conciliation, CS.ALIGNMENT_BLEND_4_8)
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_fixed_suffix_mask_align(self):
+        child = _child("base AND_MASK_ALIGN_4_8 structure :0.5")
+        self.assertEqual(child.conciliation, CS.ALIGNMENT_MASK_BLEND_4_8)
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_both_forms_coexist(self):
+        root = p.parse_root("base AND_ALIGN_4_8 old :0.5 AND_ALIGN[6,12] new :0.7")
+        old, new = root.children[1], root.children[2]
+        self.assertEqual(old.conciliation, CS.ALIGNMENT_BLEND_4_8)
+        self.assertEqual(old.conciliation_params, {})
+        self.assertEqual(new.conciliation, CS.ALIGNMENT_BLEND_CUSTOM)
+        self.assertEqual(new.conciliation_params, {'d': 6, 's': 12})
+
+    def test_plain_and_salt_unchanged(self):
+        child = _child("base AND_SALT concept :1.0")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK)
+        self.assertEqual(child.conciliation_params, {})
+
+
+class TestCompositeBracketNotConsumed(unittest.TestCase):
+
+    def test_align_composite_not_eaten(self):
+        root = p.parse_root("base AND_ALIGN[arst AND defg :2.0] :0.5")
+        child = root.children[-1]
+        self.assertIsInstance(child, p.CompositePrompt)
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_salt_composite_not_eaten(self):
+        root = p.parse_root("base AND_SALT[concept AND style :1.5] :0.8")
+        child = root.children[-1]
+        self.assertIsInstance(child, p.CompositePrompt)
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_mask_align_composite_not_eaten(self):
+        root = p.parse_root("base AND_MASK_ALIGN[a AND b] :0.5")
+        child = root.children[-1]
+        self.assertIsInstance(child, p.CompositePrompt)
+        self.assertEqual(child.conciliation_params, {})
+
+
+class TestParamsWithAffineTransform(unittest.TestCase):
+
+    def test_salt_k_with_trailing_affine(self):
+        child = _child("base AND_SALT[5] ROTATE[0.125] concept :0.8")
+        self.assertEqual(child.conciliation, CS.SALIENCE_MASK)
+        self.assertAlmostEqual(child.conciliation_params['k'], 5.0)
+        self.assertIsNotNone(child.local_transform)
+
+    def test_align_custom_with_leading_affine(self):
+        child = _child("base ROTATE[0.125] AND_ALIGN[4,8] style :0.5")
+        self.assertEqual(child.conciliation, CS.ALIGNMENT_BLEND_CUSTOM)
+        self.assertEqual(child.conciliation_params, {'d': 4, 's': 8})
+        self.assertIsNotNone(child.local_transform)
+
+    def test_salt_k_and_affine_weight_all_correct(self):
+        child = _child("base AND_SALT[3] ROTATE[0.25] concept :0.6")
+        self.assertAlmostEqual(child.conciliation_params['k'], 3.0)
+        self.assertAlmostEqual(child.weight, 0.6)
+        self.assertIsNotNone(child.local_transform)
+
+
+if __name__ == '__main__':
+    unittest.main()
+
+
+class TestSpacesInBracketParams(unittest.TestCase):
+    """Spaces around comma inside bracket params must be tolerated."""
+
+    def test_align_spaces_around_comma(self):
+        child = _child("base AND_ALIGN[4, 8] style :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 4, 's': 8})
+
+    def test_mask_align_spaces_around_comma(self):
+        child = _child("base AND_MASK_ALIGN[6, 12] style :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 6, 's': 12})
+
+    def test_salt_inner_spaces(self):
+        child = _child("base AND_SALT[ 5 ] concept :1.0")
+        self.assertAlmostEqual(child.conciliation_params.get('k', 0), 5.0)
+
+    def test_align_many_spaces(self):
+        child = _child("base AND_ALIGN[ 4 ,  8 ] style :0.5")
+        self.assertEqual(child.conciliation_params, {'d': 4, 's': 8})
+
+
+class TestInvalidParamWarnings(unittest.TestCase):
+    """
+    Invalid bracket params must:
+      1. NOT crash.
+      2. Return empty conciliation_params (keyword uses its default).
+      3. NOT leak bracket content into prompt text.
+      4. Emit a warning to stderr when verbose=True.
+    """
+
+    def _parse(self, s):
+        return p.parse_root(s)
+
+    def _last_child(self, s):
+        return self._parse(s).children[-1]
+
+    # --- k invalid values ---
+
+    def test_k_zero_no_params(self):
+        child = self._last_child("base AND_SALT[0] concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_k_negative_no_params(self):
+        child = self._last_child("base AND_SALT[-3] concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_k_too_many_parts_no_params(self):
+        child = self._last_child("base AND_SALT[3,5] concept :1.0")
+        self.assertEqual(child.conciliation_params, {})
+
+    # --- D,S invalid values ---
+
+    def test_ds_equal_no_params(self):
+        child = self._last_child("base AND_ALIGN[4,4] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_d_too_low_no_params(self):
+        child = self._last_child("base AND_ALIGN[1,8] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_s_too_high_no_params(self):
+        child = self._last_child("base AND_ALIGN[4,33] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_wrong_part_count_no_params(self):
+        child = self._last_child("base AND_ALIGN[4] style :0.5")
+        self.assertEqual(child.conciliation_params, {})
+
+    # --- No crash on bad input ---
+
+    def test_no_crash_on_empty_brackets(self):
+        # AND_SALT[] — inner is empty, should not crash
+        try:
+            root = self._parse("base AND_SALT[] concept :1.0")
+            # brackets may be treated as composite or ignored; just no crash
+        except Exception as exc:
+            self.fail(f"Crashed on AND_SALT[]: {exc}")
+
+    # --- Warning emitted to stderr ---
+
+    def test_warning_emitted_for_k_zero(self):
+        import sys, io
+        from lib_neutral_prompt import global_state as gs
+        gs.verbose = True
+        buf = io.StringIO()
+        with unittest.mock.patch('sys.stderr', buf):
+            self._parse("base AND_SALT[0] concept :1.0")
+        gs.verbose = False
+        self.assertIn('AND_SALT', buf.getvalue(),
+                      "Expected warning mentioning AND_SALT in stderr")
+        self.assertIn('k must be', buf.getvalue().lower().replace('k must be', 'k must be'),
+                      "Expected warning explaining the reason")
+
+    def test_warning_emitted_for_ds_equal(self):
+        import io, unittest.mock
+        from lib_neutral_prompt import global_state as gs
+        gs.verbose = True
+        buf = io.StringIO()
+        with unittest.mock.patch('sys.stderr', buf):
+            self._parse("base AND_ALIGN[4,4] style :0.5")
+        gs.verbose = False
+        self.assertIn('AND_ALIGN', buf.getvalue())
+        self.assertIn('differ', buf.getvalue())
+
+    def test_no_warning_when_verbose_false(self):
+        import io, unittest.mock
+        from lib_neutral_prompt import global_state as gs
+        gs.verbose = False
+        buf = io.StringIO()
+        with unittest.mock.patch('sys.stderr', buf):
+            self._parse("base AND_SALT[0] concept :1.0")
+        self.assertEqual(buf.getvalue(), '',
+                         "No warning expected when verbose=False")
+
+
+# ---------------------------------------------------------------------------
+# AND_TOPK[threshold] — parametric threshold
+# ---------------------------------------------------------------------------
+
+class TestTopkBracketSyntax(unittest.TestCase):
+
+    def test_topk_default_no_brackets(self):
+        root = p.parse_root('base AND_TOPK concept :0.8')
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_explicit_threshold(self):
+        root = p.parse_root('base AND_TOPK[0.1] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 0.1)
+
+    def test_topk_small_threshold(self):
+        root = p.parse_root('base AND_TOPK[0.01] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 0.01)
+
+    def test_topk_max_threshold(self):
+        root = p.parse_root('base AND_TOPK[1.0] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 1.0)
+
+    def test_topk_threshold_zero_rejected(self):
+        # threshold=0 is invalid (nothing would be selected)
+        root = p.parse_root('base AND_TOPK[0] concept :0.8')
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_threshold_over_one_rejected(self):
+        root = p.parse_root('base AND_TOPK[1.1] concept :0.8')
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_too_many_params_rejected(self):
+        root = p.parse_root('base AND_TOPK[0.1,0.2] concept :0.8')
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_spaces_in_brackets(self):
+        root = p.parse_root('base AND_TOPK[ 0.1 ] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 0.1)
+
+    def test_topk_does_not_consume_non_numeric_brackets(self):
+        # Composite brackets must NOT be eaten
+        root = p.parse_root('base AND_TOPK [concept AND style] :0.8')
+        # The [...] is a composite group, not params — topk should have no params
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_with_trailing_affine(self):
+        root = p.parse_root('base AND_TOPK[0.05] ROTATE[0.125] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 0.05)
+        self.assertIsNotNone(child.local_transform)
+
+    def test_topk_with_leading_affine(self):
+        root = p.parse_root('base ROTATE[0.125] AND_TOPK[0.1] concept :0.8')
+        child = root.children[-1]
+        self.assertAlmostEqual(child.conciliation_params.get('threshold'), 0.1)
+        self.assertIsNotNone(child.local_transform)
+
+    def test_topk_backward_compat_default(self):
+        # Without brackets the default 0.05 must come from cfg_denoiser, not parser
+        root = p.parse_root('base AND_TOPK concept :1.0')
+        child = root.children[-1]
+        self.assertEqual(child.conciliation_params, {})
+
+    def test_topk_coexists_with_salt(self):
+        root = p.parse_root('base AND_SALT[3] texture :0.8 AND_TOPK[0.1] style :0.6')
+        self.assertEqual(len(root.children), 3)
+        salt  = root.children[1]
+        topk  = root.children[2]
+        self.assertAlmostEqual(salt.conciliation_params.get('k'), 3.0)
+        self.assertAlmostEqual(topk.conciliation_params.get('threshold'), 0.1)
+
+
+# ---------------------------------------------------------------------------
+# Affine builder helper (ui-level function, no gradio import needed)
+# ---------------------------------------------------------------------------
+
+class TestAffineBuilderHelper(unittest.TestCase):
+    """Tests for _build_affine_snippet via neutral_prompt_parser — no gradio."""
+
+    def _snippet(self, transform, p1, p2):
+        # Inline logic mirrors _build_affine_snippet in ui.py
+        t = transform.strip()
+        import math
+        if t == 'FLIP_H':  return 'SCALE[-1,1]'
+        if t == 'FLIP_V':  return 'SCALE[1,-1]'
+        if t == 'ROTATE':  return f'ROTATE[{p1}]'
+        if t == 'SCALE':
+            return f'SCALE[{p1},{p2}]' if abs(p1 - p2) > 1e-9 else f'SCALE[{p1}]'
+        if t == 'SLIDE':   return f'SLIDE[{p1},{p2}]'
+        if t == 'SHEAR':
+            return f'SHEAR[{p1},{p2}]' if abs(p1 - p2) > 1e-9 else f'SHEAR[{p1}]'
+        return ''
+
+    def test_flip_h(self):
+        self.assertEqual(self._snippet('FLIP_H', 0, 0), 'SCALE[-1,1]')
+
+    def test_flip_v(self):
+        self.assertEqual(self._snippet('FLIP_V', 0, 0), 'SCALE[1,-1]')
+
+    def test_rotate(self):
+        self.assertEqual(self._snippet('ROTATE', 0.125, 1.0), 'ROTATE[0.125]')
+
+    def test_scale_uniform(self):
+        self.assertEqual(self._snippet('SCALE', 2.0, 2.0), 'SCALE[2.0]')
+
+    def test_scale_anisotropic(self):
+        self.assertEqual(self._snippet('SCALE', 1.5, 1.0), 'SCALE[1.5,1.0]')
+
+    def test_slide(self):
+        self.assertEqual(self._snippet('SLIDE', 0.1, 0.2), 'SLIDE[0.1,0.2]')
+
+    def test_shear_uniform(self):
+        self.assertEqual(self._snippet('SHEAR', 0.05, 0.05), 'SHEAR[0.05]')
+
+    def test_snippet_parseable_by_parser(self):
+        """Each generated snippet must survive parse_root without crashing."""
+        cases = [
+            'ROTATE[0.125]', 'SCALE[-1,1]', 'SCALE[1,-1]',
+            'SCALE[0.5]', 'SCALE[1.5,1.0]',
+            'SLIDE[0.1,0.2]', 'SHEAR[0.05]',
+        ]
+        for snippet in cases:
+            with self.subTest(snippet=snippet):
+                try:
+                    p.parse_root(f'base {snippet} AND_PERP style :0.8')
+                except Exception as exc:
+                    self.fail(f'snippet "{snippet}" crashed parse_root: {exc}')
+
+
+# ---------------------------------------------------------------------------
+# Debug/explain helper (_render_parse_tree logic, without gradio)
+# ---------------------------------------------------------------------------
+
+class TestDebugRenderLogic(unittest.TestCase):
+    """Test the parse-tree renderer used by the debug panel."""
+
+    def _render(self, prompt_str):
+        # Import the function directly from ui module logic — replicate inline
+        # so we don't need gradio at test time.
+        if not prompt_str.strip():
+            return '(empty prompt)'
+        try:
+            root = p.parse_root(prompt_str)
+        except Exception as exc:
+            return f'Parse error: {exc}'
+
+        lines = []
+
+        def _node(node, depth=0):
+            indent = '  ' * depth
+            strat = node.conciliation.name if node.conciliation else 'BASE'
+            w = f'weight={node.weight:.3f}'
+            params = ''
+            if node.conciliation_params:
+                params = '  params=' + ', '.join(f'{k}={v}' for k, v in node.conciliation_params.items())
+            aff = '  [affine]' if node.local_transform is not None else ''
+            if hasattr(node, 'prompt'):
+                text = repr(node.prompt[:60])
+                lines.append(f'{indent}[{strat}]  {w}{params}{aff}  text={text}')
+            else:
+                lines.append(f'{indent}[{strat}]  {w}{params}{aff}  ({len(node.children)} children)')
+                for child in node.children:
+                    _node(child, depth + 1)
+
+        _node(root)
+        return '\n'.join(lines)
+
+    def test_empty_prompt(self):
+        out = self._render('')
+        self.assertEqual(out, '(empty prompt)')
+
+    def test_base_only(self):
+        out = self._render('a dog')
+        self.assertIn('BASE', out)
+        self.assertIn('a dog', out)
+
+    def test_with_salt(self):
+        out = self._render('base AND_SALT[3] texture :0.8')
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('k=3', out)
+
+    def test_with_topk(self):
+        out = self._render('base AND_TOPK[0.1] style :0.6')
+        self.assertIn('SEMANTIC_GUIDANCE', out)
+        self.assertIn('threshold=0.1', out)
+
+    def test_with_align(self):
+        out = self._render('base AND_ALIGN[4,8] detail :0.7')
+        self.assertIn('ALIGNMENT_BLEND_CUSTOM', out)
+        self.assertIn('d=4', out)
+        self.assertIn('s=8', out)
+
+    def test_with_affine(self):
+        out = self._render('base ROTATE[0.125] AND_PERP vivid :0.8')
+        self.assertIn('[affine]', out)
+
+    def test_multiple_children(self):
+        out = self._render('base AND_SALT[5] texture :0.8 AND_TOPK[0.05] style :0.6')
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('SEMANTIC_GUIDANCE', out)
+
+    def test_parse_error_graceful(self):
+        # Malformed / deeply weird input must not raise — parser should handle it
+        try:
+            out = self._render('[[[[[')
+        except Exception as exc:
+            self.fail(f'_render raised on bad input: {exc}')

neutral_prompt_patcheds/test/perp_parser/test_runtime_behavior.py

@@ -0,0 +1,826 @@
+"""
+Runtime behavior tests.
+
+Requires PyTorch.  If torch is absent the whole module is skipped — same
+pattern as test_affine_pipeline.py so the CI exit code stays clean.
+
+Covers:
+  - _get_salience: k param changes pixel coverage (monotonically)
+  - blob morphology: thickify-first pipeline vs erode-first pipeline
+  - no-base guard: fallback when all children are conciliatory
+  - API override lifecycle: clear → set → get → clear
+"""
+
+import pathlib
+import sys
+import types
+import unittest
+
+# ---------------------------------------------------------------------------
+# Torch availability check — skip entire module if absent
+# ---------------------------------------------------------------------------
+try:
+    import importlib.util as _ilu
+    _spec = _ilu.find_spec('torch')
+    _TORCH_AVAILABLE = _spec is not None and getattr(_spec, 'origin', None) is not None
+except (ValueError, ModuleNotFoundError):
+    _TORCH_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# A1111 stubs (must be installed before importing lib modules)
+# ---------------------------------------------------------------------------
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent.parent))
+
+
+def _stub(name):
+    m = types.ModuleType(name)
+    sys.modules.setdefault(name, m)
+    return sys.modules[name]
+
+
+for _n in ('modules', 'modules.script_callbacks', 'modules.sd_samplers',
+           'modules.shared', 'modules.prompt_parser', 'gradio'):
+    _stub(_n)
+
+import modules.script_callbacks as _sc
+for _attr in ('on_cfg_denoiser', 'on_script_unloaded', 'CFGDenoiserParams'):
+    if not hasattr(_sc, _attr):
+        setattr(_sc, _attr, lambda *a, **kw: None)
+
+import modules.shared as _sh
+if not hasattr(_sh, 'state'):
+    _sh.state = types.SimpleNamespace(sampling_step=1)
+
+import modules.sd_samplers as _ss
+if not hasattr(_ss, 'create_sampler'):
+    _ss.create_sampler = lambda *a, **kw: None
+
+import lib_neutral_prompt.hijacker as _h_mod
+
+
+class _StubHijacker:
+    @classmethod
+    def install_or_get(cls, **kwargs):
+        return cls()
+    def hijack(self, name):
+        return lambda fn: fn
+
+
+_h_mod.ModuleHijacker = _StubHijacker
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestSalienceKCoverage(unittest.TestCase):
+    """Higher k → strictly fewer pixels where child salience beats parent."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        cls.torch = torch
+        cls.hj = hj
+
+    def _winning_fraction(self, k_child, C=4, H=64, W=64):
+        torch, hj = self.torch, self.hj
+        torch.manual_seed(7)
+        parent = torch.randn(C, H, W)
+        child  = torch.randn(C, H, W)
+        sal_p = hj._get_salience(parent, k=1.0)
+        sal_c = hj._get_salience(child,  k=k_child)
+        mask = torch.argmax(torch.stack([sal_p, sal_c]), dim=0)
+        return (mask == 1).float().mean().item()
+
+    def test_k1_broad(self):
+        self.assertGreater(self._winning_fraction(1.0), 0.40)
+
+    def test_k5_moderate(self):
+        f = self._winning_fraction(5.0)
+        self.assertLess(f, 0.15)
+        self.assertGreater(f, 0.001)
+
+    def test_k20_surgical(self):
+        self.assertLess(self._winning_fraction(20.0), 0.01)
+
+    def test_monotone_k(self):
+        f1  = self._winning_fraction(1.0)
+        f5  = self._winning_fraction(5.0)
+        f20 = self._winning_fraction(20.0)
+        self.assertGreater(f1, f5, "k=1 should cover more than k=5")
+        self.assertGreater(f5, f20, "k=5 should cover more than k=20")
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestBlobMorphology(unittest.TestCase):
+    """Thickify-first pipeline keeps blob alive; erode-first destroys it."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        cls.torch = torch
+        cls.hj = hj
+
+    def _seed(self, C=4, H=8, W=8):
+        board = self.torch.zeros(C, H, W)
+        board[:, H // 2, W // 2] = 1.0
+        return board
+
+    def _run(self, board, thickify, erode):
+        hj = self.hj
+        for _ in range(thickify):
+            board = hj._life_step(board, hj._thickify_rule)
+        for _ in range(erode):
+            board = hj._life_step(board, hj._erode_rule)
+        return board
+
+    def test_erode_first_kills_isolated_seed(self):
+        """Original ultimate ordering: 6 erodes → seed dies immediately."""
+        result = self._run(self._seed(), thickify=0, erode=6)
+        self.assertEqual(result.sum().item(), 0,
+                         "Erode-first should destroy an isolated pixel seed")
+
+    def test_thickify_first_survives(self):
+        """Patched ordering: 3 thickify then 1 erode → seed survives."""
+        result = self._run(self._seed(), thickify=3, erode=1)
+        self.assertGreater(result.sum().item(), 0,
+                           "Thickify-first should keep blob alive")
+
+    def test_thickify_grows_region(self):
+        original_mass = self._seed().sum().item()
+        grown = self._run(self._seed(), thickify=3, erode=0)
+        self.assertGreater(grown.sum().item(), original_mass)
+
+    def test_erode_after_thickify_reduces_mass(self):
+        grown  = self._run(self._seed(), thickify=3, erode=0).sum().item()
+        pruned = self._run(self._seed(), thickify=3, erode=1).sum().item()
+        self.assertLess(pruned, grown,
+                        "Erosion after thickify should trim edges")
+        self.assertGreater(pruned, 0,
+                           "But core should still survive")
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestNoBaseGuard(unittest.TestCase):
+    """combine_denoised_hijack falls back when all children are conciliatory."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        import lib_neutral_prompt.global_state as gs
+        import lib_neutral_prompt.neutral_prompt_parser as npp
+        cls.torch = torch
+        cls.hj    = hj
+        cls.gs    = gs
+        cls.npp   = npp
+
+    def setUp(self):
+        self.gs.is_enabled = True
+        self.gs.verbose    = False
+        self.gs.prompt_exprs       = []
+        self.gs.batch_cond_indices = []
+
+    def tearDown(self):
+        self.gs.is_enabled = False
+        self.gs.prompt_exprs       = []
+        self.gs.batch_cond_indices = []
+
+    def _counter(self):
+        calls = [0]
+        def fn(x_out, batch_cond_indices, text_uncond, cond_scale):
+            calls[0] += 1
+            return x_out[-1:]
+        return fn, calls
+
+    def test_fallback_when_no_base_child(self):
+        root = self.npp.parse_root("AND_SALT concept :1.0")
+        self.gs.prompt_exprs       = [root]
+        self.gs.batch_cond_indices = [[(0, 1.0)]]
+
+        x_out = self.torch.randn(2, 4, 8, 8)
+        text_uncond = x_out[-1:]
+        fn, calls = self._counter()
+
+        self.hj.combine_denoised_hijack(
+            x_out, self.gs.batch_cond_indices, text_uncond, 7.0, fn
+        )
+        self.assertEqual(calls[0], 1,
+                         "Guard must fall back when there is no base AND child")
+
+    def test_no_fallback_when_base_exists(self):
+        """
+        When a base AND-child exists, the guard must NOT fire.
+
+        Architecture note: combine_denoised_hijack always calls original_function
+        at least once via _get_webui_denoised() on the normal path — that call
+        receives a *sliced* x_out (not the raw full tensor).
+        The guard fallback, by contrast, passes the *original* x_out unchanged.
+
+        We distinguish the two by capturing the first argument the counter saw:
+          - guard path  → x_out.shape[0] == n_conds + n_uncond  (full tensor)
+          - normal path → x_out.shape[0] <= n_conds              (sliced tensor)
+        """
+        root = self.npp.parse_root("base concept AND_SALT tweak :1.0")
+        self.gs.prompt_exprs       = [root]
+        # 2 cond slots (base + AND_SALT) + 1 implicit uncond
+        self.gs.batch_cond_indices = [[(0, 1.0), (1, 1.0)]]
+
+        n_cond   = 2
+        n_uncond = 1
+        x_out       = self.torch.randn(n_cond + n_uncond, 4, 8, 8)
+        text_uncond = x_out[-n_uncond:]
+
+        seen_shapes = []
+
+        def capturing_fn(x, batch_cond_indices, text_uncond, cond_scale):
+            seen_shapes.append(x.shape[0])
+            return x[-1:]
+
+        try:
+            self.hj.combine_denoised_hijack(
+                x_out, self.gs.batch_cond_indices, text_uncond, 7.0, capturing_fn
+            )
+        except Exception:
+            pass  # downstream tensor errors are fine; we only check entry shape
+
+        self.assertTrue(len(seen_shapes) > 0,
+                        "original_function was never called at all")
+        # On the normal path the first call is from _get_webui_denoised which
+        # passes a sliced tensor (only base-AND children + uncond).
+        # On the guard path it would pass the full x_out (n_cond + n_uncond rows).
+        full_tensor_size = n_cond + n_uncond
+        self.assertLess(seen_shapes[0], full_tensor_size,
+                        "Guard fired and passed full x_out — it should NOT have")
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestCFGRescaleAPILifecycle(unittest.TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        import lib_neutral_prompt.global_state as gs
+        cls.gs = gs
+
+    def setUp(self):
+        self.gs.cfg_rescale = 0.0
+        self.gs.cfg_rescale_override = None
+        self.gs.CFGRescaleFactorSingleton.clear()
+
+    def test_override_applied_and_cleared(self):
+        self.gs.cfg_rescale_override = 0.7
+        self.gs.apply_and_clear_cfg_rescale_override()
+        self.assertAlmostEqual(self.gs.cfg_rescale, 0.7)
+        self.assertIsNone(self.gs.cfg_rescale_override)
+
+    def test_singleton_clear_returns_none(self):
+        self.gs.CFGRescaleFactorSingleton.clear()
+        self.assertIsNone(self.gs.CFGRescaleFactorSingleton.get())
+
+    def test_singleton_set_and_get(self):
+        self.gs.CFGRescaleFactorSingleton.set(0.85)
+        self.assertAlmostEqual(self.gs.CFGRescaleFactorSingleton.get(), 0.85)
+
+    def test_singleton_cleared_between_steps(self):
+        self.gs.CFGRescaleFactorSingleton.set(0.85)
+        self.gs.CFGRescaleFactorSingleton.clear()
+        self.assertIsNone(self.gs.CFGRescaleFactorSingleton.get())
+
+    def test_no_override_does_not_change_rescale(self):
+        """apply_and_clear with no pending override must leave cfg_rescale alone."""
+        self.gs.cfg_rescale = 0.3
+        self.gs.apply_and_clear_cfg_rescale_override()
+        self.assertAlmostEqual(self.gs.cfg_rescale, 0.3)
+
+
+if __name__ == '__main__':
+    unittest.main()
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestProtectionModes(unittest.TestCase):
+    """Off / Auto / Strict protection modes."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        import lib_neutral_prompt.global_state as gs
+        import lib_neutral_prompt.neutral_prompt_parser as npp
+        cls.torch = torch
+        cls.hj    = hj
+        cls.gs    = gs
+        cls.npp   = npp
+
+    def setUp(self):
+        self.gs.is_enabled        = True
+        self.gs.verbose           = False
+        self.gs.protection_mode   = 'auto'
+        self.gs.strict_threshold  = 0.1
+        self.gs.prompt_exprs      = []
+        self.gs.batch_cond_indices = []
+
+    def tearDown(self):
+        self.gs.is_enabled       = False
+        self.gs.protection_mode  = 'auto'
+        self.gs.prompt_exprs     = []
+        self.gs.batch_cond_indices = []
+
+    def _run(self, prompt_str, n_cond, protection_mode, strict_threshold=0.1):
+        """Return the shape[0] of x_out passed to original_fn on first call."""
+        root = self.npp.parse_root(prompt_str)
+        self.gs.prompt_exprs       = [root]
+        self.gs.batch_cond_indices = [[(i, 1.0) for i in range(n_cond)]]
+        self.gs.protection_mode    = protection_mode
+        self.gs.strict_threshold   = strict_threshold
+
+        n_uncond = 1
+        x_out       = self.torch.randn(n_cond + n_uncond, 4, 8, 8)
+        text_uncond = x_out[-n_uncond:]
+
+        seen = []
+        def fn(x, *a, **kw):
+            seen.append(x.shape[0])
+            return x[-1:]
+
+        try:
+            self.hj.combine_denoised_hijack(
+                x_out, self.gs.batch_cond_indices, text_uncond, 7.0, fn)
+        except Exception:
+            pass
+
+        return seen, n_cond + n_uncond
+
+    def _guard_fired(self, seen, full_size):
+        """Guard fires when original_fn receives the full-size x_out."""
+        return len(seen) > 0 and seen[0] == full_size
+
+    # --- Auto mode ---
+
+    def test_auto_fires_on_no_base(self):
+        seen, full = self._run("AND_SALT concept :1.0", n_cond=1,
+                               protection_mode='auto')
+        self.assertTrue(self._guard_fired(seen, full),
+                        "Auto guard must fire when no base AND-child exists")
+
+    def test_auto_does_not_fire_with_base(self):
+        seen, full = self._run("base concept AND_SALT tweak :1.0", n_cond=2,
+                               protection_mode='auto')
+        self.assertFalse(self._guard_fired(seen, full),
+                         "Auto guard must NOT fire when base AND-child exists")
+
+    # --- Off mode ---
+
+    def test_off_never_fires_even_without_base(self):
+        seen, full = self._run("AND_SALT concept :1.0", n_cond=1,
+                               protection_mode='off')
+        self.assertFalse(self._guard_fired(seen, full),
+                         "Off mode must never fire the guard")
+
+    # --- Strict mode: structural check same as auto ---
+
+    def test_strict_fires_on_no_base(self):
+        seen, full = self._run("AND_SALT concept :1.0", n_cond=1,
+                               protection_mode='strict')
+        self.assertTrue(self._guard_fired(seen, full),
+                        "Strict guard must also fire on structural no-base case")
+
+    # --- global_state defaults ---
+
+    def test_default_protection_mode_is_auto(self):
+        import importlib, lib_neutral_prompt.global_state as gs_mod
+        # default is set at module level; check it's 'auto'
+        self.assertEqual(gs_mod.protection_mode, 'auto')
+
+    def test_strict_threshold_default(self):
+        import lib_neutral_prompt.global_state as gs_mod
+        self.assertAlmostEqual(gs_mod.strict_threshold, 0.1)
+
+
+# ---------------------------------------------------------------------------
+# Tests for global_state helpers (no torch needed)
+# ---------------------------------------------------------------------------
+
+class TestGlobalStateHelpers(unittest.TestCase):
+    """normalize_protection_mode and clamp_strict_threshold."""
+
+    @classmethod
+    def setUpClass(cls):
+        import lib_neutral_prompt.global_state as gs
+        cls.gs = gs
+
+    def test_normalize_valid_modes(self):
+        for mode in ('off', 'auto', 'strict'):
+            self.assertEqual(self.gs.normalize_protection_mode(mode), mode)
+
+    def test_normalize_uppercase(self):
+        self.assertEqual(self.gs.normalize_protection_mode('AUTO'), 'auto')
+        self.assertEqual(self.gs.normalize_protection_mode('Strict'), 'strict')
+
+    def test_normalize_whitespace(self):
+        self.assertEqual(self.gs.normalize_protection_mode('  off  '), 'off')
+
+    def test_normalize_unknown_falls_back_to_auto(self):
+        self.assertEqual(self.gs.normalize_protection_mode('strong'), 'auto')
+        self.assertEqual(self.gs.normalize_protection_mode(''), 'auto')
+        self.assertEqual(self.gs.normalize_protection_mode('1'), 'auto')
+
+    def test_clamp_valid(self):
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(0.10), 0.10)
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(0.50), 0.50)
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(0.01), 0.01)
+
+    def test_clamp_below_min(self):
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(0.0), 0.01)
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(-5), 0.01)
+
+    def test_clamp_above_max(self):
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(0.99), 0.50)
+
+    def test_clamp_bad_type_returns_default(self):
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold('bad'), 0.10)
+        self.assertAlmostEqual(self.gs.clamp_strict_threshold(None), 0.10)
+
+    def test_apply_infotext_protection(self):
+        import lib_neutral_prompt.global_state as gs
+        gs.protection_mode  = 'auto'
+        gs.strict_threshold = 0.10
+        gs.apply_infotext({
+            gs.INFOTEXT_KEY_PROTECTION_MODE:  'strict',
+            gs.INFOTEXT_KEY_STRICT_THRESHOLD: '0.25',
+        })
+        self.assertEqual(gs.protection_mode, 'strict')
+        self.assertAlmostEqual(gs.strict_threshold, 0.25)
+
+    def test_apply_infotext_invalid_mode_falls_back(self):
+        import lib_neutral_prompt.global_state as gs
+        gs.protection_mode = 'off'
+        gs.apply_infotext({gs.INFOTEXT_KEY_PROTECTION_MODE: 'maximum'})
+        self.assertEqual(gs.protection_mode, 'auto')
+
+    def test_apply_infotext_partial_update(self):
+        """apply_infotext must not touch fields absent from the dict."""
+        import lib_neutral_prompt.global_state as gs
+        gs.protection_mode  = 'strict'
+        gs.strict_threshold = 0.20
+        gs.apply_infotext({})  # empty dict
+        self.assertEqual(gs.protection_mode, 'strict')
+        self.assertAlmostEqual(gs.strict_threshold, 0.20)
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestProtectionPolicyFunction(unittest.TestCase):
+    """_should_fallback_for_protection across Off / Auto / Strict."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        import lib_neutral_prompt.global_state as gs
+        import lib_neutral_prompt.neutral_prompt_parser as npp
+        cls.torch = torch
+        cls.hj    = hj
+        cls.gs    = gs
+        cls.npp   = npp
+
+    def setUp(self):
+        self.gs.is_enabled        = True
+        self.gs.protection_mode   = 'auto'
+        self.gs.strict_threshold  = 0.10
+        self.gs.prompt_exprs      = []
+        self.gs.batch_cond_indices = []
+
+    def tearDown(self):
+        self.gs.is_enabled       = False
+        self.gs.protection_mode  = 'auto'
+
+    def _setup(self, prompt_str, n_cond):
+        root = self.npp.parse_root(prompt_str)
+        self.gs.prompt_exprs       = [root]
+        self.gs.batch_cond_indices = [[(i, 1.0) for i in range(n_cond)]]
+        n_uncond = 1
+        x_out       = self.torch.randn(n_cond + n_uncond, 4, 8, 8)
+        text_uncond = x_out[-n_uncond:]
+        return x_out, text_uncond
+
+    # --- Off: never fires regardless of structure ---
+
+    def test_off_no_base(self):
+        self.gs.protection_mode = 'off'
+        x_out, text_uncond = self._setup("AND_SALT concept :1.0", n_cond=1)
+        should, reason = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertFalse(should)
+        self.assertIsNone(reason)
+
+    def test_off_with_base(self):
+        self.gs.protection_mode = 'off'
+        x_out, text_uncond = self._setup("base AND_SALT tweak :1.0", n_cond=2)
+        should, _ = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertFalse(should)
+
+    # --- Auto: structural check only ---
+
+    def test_auto_fires_no_base(self):
+        self.gs.protection_mode = 'auto'
+        x_out, text_uncond = self._setup("AND_SALT concept :1.0", n_cond=1)
+        should, reason = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertTrue(should)
+        self.assertIn('no valid base', reason)
+        self.assertIn('auto', reason)
+
+    def test_auto_does_not_fire_with_base(self):
+        self.gs.protection_mode = 'auto'
+        x_out, text_uncond = self._setup("base AND_SALT tweak :1.0", n_cond=2)
+        should, _ = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertFalse(should)
+
+    # --- Strict: also fires on no-base (structural) ---
+
+    def test_strict_fires_on_no_base(self):
+        self.gs.protection_mode = 'strict'
+        x_out, text_uncond = self._setup("AND_SALT concept :1.0", n_cond=1)
+        should, reason = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertTrue(should)
+        self.assertIn('strict', reason)
+
+    # --- Strict: numerical ratio check ---
+
+    def test_strict_reason_contains_ratio_info(self):
+        """When strict fires on ratio, reason must include ratio and threshold."""
+        self.gs.protection_mode  = 'strict'
+        self.gs.strict_threshold = 0.99   # almost certain to fire
+
+        x_out, text_uncond = self._setup("base AND_SALT tweak :1.0", n_cond=2)
+        should, reason = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+
+        if should:
+            # If it fired, reason must explain why
+            self.assertIn('ratio', reason)
+            self.assertIn('threshold', reason)
+        # If it didn't fire (both norms happened to be equal), that's fine too.
+
+    def test_strict_does_not_fire_with_threshold_zero(self):
+        """threshold=0.01 (minimum) should almost never fire on random latents."""
+        self.gs.protection_mode  = 'strict'
+        self.gs.strict_threshold = 0.01
+
+        x_out, text_uncond = self._setup("base AND_SALT tweak :1.0", n_cond=2)
+        should, _ = self.hj._should_fallback_for_protection(
+            x_out, self.gs.batch_cond_indices, text_uncond)
+        self.assertFalse(should,
+                         "threshold=0.01 should almost never trigger on random latents")
+
+    # --- _has_valid_base_path ---
+
+    def test_has_valid_base_path_true(self):
+        root = self.npp.parse_root("base AND_SALT tweak :1.0")
+        self.assertTrue(self.hj._has_valid_base_path([root]))
+
+    def test_has_valid_base_path_false(self):
+        root = self.npp.parse_root("AND_SALT only :1.0")
+        self.assertFalse(self.hj._has_valid_base_path([root]))
+
+    def test_has_valid_base_path_empty(self):
+        self.assertFalse(self.hj._has_valid_base_path([]))
+
+    # --- _safe_norm ---
+
+    def test_safe_norm_normal(self):
+        t = self.torch.ones(4, 8, 8)
+        self.assertGreater(self.hj._safe_norm(t), 0.0)
+
+    def test_safe_norm_zeros(self):
+        t = self.torch.zeros(4, 8, 8)
+        self.assertAlmostEqual(self.hj._safe_norm(t), 0.0)
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestPerPromptProtection(unittest.TestCase):
+    """Per-prompt structural check — a healthy prompt must not shield a bad neighbour."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        import lib_neutral_prompt.global_state as gs
+        import lib_neutral_prompt.neutral_prompt_parser as npp
+        cls.torch = torch
+        cls.hj    = hj
+        cls.gs    = gs
+        cls.npp   = npp
+
+    def setUp(self):
+        self.gs.is_enabled       = True
+        self.gs.protection_mode  = 'auto'
+        self.gs.strict_threshold = 0.10
+        self.gs.prompt_exprs     = []
+        self.gs.batch_cond_indices = []
+
+    def tearDown(self):
+        self.gs.is_enabled       = False
+        self.gs.protection_mode  = 'auto'
+        self.gs.prompt_exprs     = []
+        self.gs.batch_cond_indices = []
+
+    # --- _get_invalid_base_prompt_indices ---
+
+    def test_helper_all_good(self):
+        roots = [
+            self.npp.parse_root("base AND_SALT tweak :1.0"),
+            self.npp.parse_root("base AND_PERP style :0.8"),
+        ]
+        self.assertEqual(self.hj._get_invalid_base_prompt_indices(roots), [])
+
+    def test_helper_all_bad(self):
+        roots = [
+            self.npp.parse_root("AND_SALT only :1.0"),
+            self.npp.parse_root("AND_PERP only :0.8"),
+        ]
+        self.assertEqual(self.hj._get_invalid_base_prompt_indices(roots), [0, 1])
+
+    def test_helper_mixed_batch(self):
+        roots = [
+            self.npp.parse_root("base AND_SALT tweak :1.0"),   # index 0 — good
+            self.npp.parse_root("AND_PERP only :0.8"),          # index 1 — bad
+        ]
+        self.assertEqual(self.hj._get_invalid_base_prompt_indices(roots), [1])
+
+    def test_helper_empty_exprs(self):
+        self.assertEqual(self.hj._get_invalid_base_prompt_indices([]), [])
+
+    # --- _prompt_has_valid_base_path ---
+
+    def test_per_prompt_good(self):
+        root = self.npp.parse_root("base AND_SALT tweak :1.0")
+        self.assertTrue(self.hj._prompt_has_valid_base_path(root))
+
+    def test_per_prompt_bad(self):
+        root = self.npp.parse_root("AND_SALT only :1.0")
+        self.assertFalse(self.hj._prompt_has_valid_base_path(root))
+
+    # --- Mixed-batch policy: auto must fire even if index-0 is healthy ---
+
+    def _run_mixed_batch(self, protection_mode):
+        """Batch: prompt 0 OK, prompt 1 has no base."""
+        root_good = self.npp.parse_root("base AND_SALT tweak :1.0")
+        root_bad  = self.npp.parse_root("AND_SALT only :1.0")
+        self.gs.prompt_exprs       = [root_good, root_bad]
+        self.gs.batch_cond_indices = [[(0, 1.0), (1, 1.0)], [(2, 1.0)]]
+        self.gs.protection_mode    = protection_mode
+
+        n_uncond = 1
+        x_out       = self.torch.randn(3 + n_uncond, 4, 8, 8)
+        text_uncond = x_out[-n_uncond:]
+
+        seen = []
+        def fn(x, *a, **kw):
+            seen.append(x.shape[0])
+            return x[-1:]
+
+        try:
+            self.hj.combine_denoised_hijack(
+                x_out, self.gs.batch_cond_indices, text_uncond, 7.0, fn)
+        except Exception:
+            pass
+        return seen, x_out.shape[0]
+
+    def test_auto_fires_on_mixed_batch(self):
+        seen, full = self._run_mixed_batch('auto')
+        # Guard should have passed full x_out to original_fn (fallback path)
+        self.assertTrue(len(seen) > 0 and seen[0] == full,
+                        "Auto guard must fire when any prompt in the batch lacks a base path")
+
+    def test_off_does_not_fire_on_mixed_batch(self):
+        seen, full = self._run_mixed_batch('off')
+        self.assertTrue(len(seen) == 0 or seen[0] != full,
+                        "Off mode must never trigger the guard, even for bad prompts")
+
+
+@unittest.skipUnless(_TORCH_AVAILABLE, 'PyTorch is not installed — skipping runtime tests')
+class TestSafeAffineInversion(unittest.TestCase):
+    """_try_invert_affine: graceful fallback on singular / NaN matrices."""
+
+    @classmethod
+    def setUpClass(cls):
+        import torch
+        import lib_neutral_prompt.cfg_denoiser_hijack as hj
+        import lib_neutral_prompt.global_state as gs
+        cls.torch = torch
+        cls.hj    = hj
+        cls.gs    = gs
+
+    def setUp(self):
+        self.gs.verbose = False
+
+    def tearDown(self):
+        self.gs.verbose = False
+
+    def test_normal_invertible_matrix(self):
+        m = self.torch.eye(3)
+        result = self.hj._try_invert_affine(m, 'test')
+        self.assertTrue(self.torch.allclose(result, self.torch.eye(3)),
+                        "Inverting identity should return identity")
+
+    def test_singular_matrix_returns_identity(self):
+        """SCALE[0] gives a singular matrix — must not crash."""
+        m = self.torch.zeros(3, 3)  # fully degenerate
+        result = self.hj._try_invert_affine(m, 'singular test')
+        self.assertTrue(self.torch.allclose(result, self.torch.eye(3)),
+                        "Singular matrix must fall back to identity")
+
+    def test_nearly_singular_returns_identity(self):
+        m = self.torch.eye(3)
+        m[0, 0] = 1e-9   # effectively zero scale
+        result = self.hj._try_invert_affine(m, 'nearly singular')
+        # Either returns eye (fallback) or a finite result — must not be NaN/Inf
+        self.assertTrue(self.torch.isfinite(result).all(),
+                        "Result must be finite even for nearly-singular input")
+
+    def test_verbose_warning_on_singular(self):
+        import io, unittest.mock
+        self.gs.verbose = True
+        buf = io.StringIO()
+        m = self.torch.zeros(3, 3)
+        with unittest.mock.patch('sys.stderr', buf):
+            self.hj._try_invert_affine(m, 'singular context')
+        self.gs.verbose = False
+        self.assertIn('singular context', buf.getvalue())
+        self.assertIn('identity', buf.getvalue().lower())
+
+    def test_no_warning_when_verbose_false(self):
+        import io, unittest.mock
+        self.gs.verbose = False
+        buf = io.StringIO()
+        m = self.torch.zeros(3, 3)
+        with unittest.mock.patch('sys.stderr', buf):
+            self.hj._try_invert_affine(m, 'silent singular')
+        self.assertEqual(buf.getvalue(), '',
+                         "No warning expected when verbose=False")
+
+
+class TestAffineParserValidation(unittest.TestCase):
+    """Parser-level rejection of invalid affine params."""
+
+    @classmethod
+    def setUpClass(cls):
+        # mock_torch already installed by package __init__
+        import lib_neutral_prompt.neutral_prompt_parser as _p
+        cls.p = _p
+
+    def _parse(self, s):
+        return self.p.parse_root(s)
+
+    def _child(self, s, idx=-1):
+        return self._parse(s).children[idx]
+
+    # --- SCALE[0] must not produce a transform ---
+
+    def test_scale_zero_rejected(self):
+        """SCALE[0] must not crash. If a transform is stored it must come from
+        the identity fallback (make_scale returned None → _apply_affine kept t)."""
+        try:
+            child = self._child("base AND_PERP SCALE[0] text :0.8")
+        except Exception as exc:
+            self.fail(f"SCALE[0] must not crash the parser: {exc}")
+        # Either no transform stored (None) or the stored transform is the
+        # identity that _apply_affine kept when make_scale returned None.
+        # Both are acceptable — the key guarantee is no crash.
+
+    def test_scale_nonzero_accepted(self):
+        child = self._child("base AND_PERP SCALE[2] text :0.8")
+        self.assertIsNotNone(child.local_transform,
+                             "SCALE[2] should produce a valid transform")
+
+    # --- SHEAR near 0.25 turns must be rejected ---
+
+    def test_shear_safe_value_accepted(self):
+        child = self._child("base AND_PERP SHEAR[0.1] text :0.8")
+        # Should produce a transform (0.1 turns is safe)
+        # Don't assert non-None since mock torch may not multiply correctly,
+        # just check no crash occurred.
+
+    def test_shear_dangerous_value_warning(self):
+        """SHEAR[0.25] is exactly at the singularity — must not crash."""
+        try:
+            root = self._parse("base AND_PERP SHEAR[0.25] text :0.8")
+        except Exception as exc:
+            self.fail(f"SHEAR[0.25] must not crash the parser: {exc}")
+
+    # --- Non-finite params must not crash ---
+
+    def test_rotate_no_crash(self):
+        try:
+            self._parse("base AND_PERP ROTATE[0.5] text :0.8")
+        except Exception as exc:
+            self.fail(f"ROTATE[0.5] crashed: {exc}")
+
+    def test_slide_no_crash(self):
+        try:
+            self._parse("base AND_SALT SLIDE[0.1,0.2] text :1.0")
+        except Exception as exc:
+            self.fail(f"SLIDE crashed: {exc}")

neutral_prompt_patcheds/test/perp_parser/test_sprint2.py

@@ -0,0 +1,656 @@
+"""
+Sprint 2 tests: protection_utils, affine_utils, step_utils, builder v1.2.
+
+All pure-Python, no torch (torch-dependent cases skipped via mock).
+"""
+
+import unittest
+
+# mock_torch installed by package __init__
+
+from lib_neutral_prompt import global_state
+from lib_neutral_prompt.affine_utils import (
+    make_rotate, make_slide, make_scale, make_shear,
+    apply_affine, try_invert_affine,
+    build_affine_snippet, AFFINE_PRESETS, AFFINE_TRANSFORMS,
+    affine_transforms,
+    _make_rotate, _make_scale, _apply_affine,   # alias checks
+)
+from lib_neutral_prompt.protection_utils import (
+    prompt_has_valid_base_path,
+    get_invalid_base_prompt_indices,
+    has_valid_base_path,
+    safe_norm,
+    compute_soft_attenuation,
+    protection_verdict,
+)
+from lib_neutral_prompt.step_utils import (
+    StepWindow, ALWAYS_ACTIVE, STRATEGY_DEFAULTS,
+    normalize_progress, strategy_is_active,
+    _strategy_family, render_step_window_summary,
+)
+from lib_neutral_prompt.matryoshka_utils import (
+    BuilderNode,
+    builder_add_child, builder_remove_node, builder_duplicate_node,
+    builder_move_up, builder_move_down, builder_update_node,
+    serialize_builder_tree, builder_tree_to_prompt,
+)
+import lib_neutral_prompt.neutral_prompt_parser as p
+
+import sys as _sys
+
+def _has_real_torch() -> bool:
+    """True iff real torch (not the test mock) is available."""
+    try:
+        import torch as _t
+        _t.tensor([1.0]).float().item()
+        _t.linalg.norm(_t.tensor([3.0, 4.0])).item()
+        return True
+    except Exception:
+        return False
+
+_REAL_TORCH = _has_real_torch()
+_skip_no_torch = unittest.skipUnless(_REAL_TORCH, 'requires real torch')
+
+
+
+# ---------------------------------------------------------------------------
+# affine_utils
+# ---------------------------------------------------------------------------
+
+class TestAffineUtils(unittest.TestCase):
+
+    # --- matrix constructors ---
+
+    @_skip_no_torch
+    def test_rotate_matrix_shape(self):
+        import torch
+        m = make_rotate(0.0)
+        self.assertEqual(m.shape, (3, 3))
+
+    @_skip_no_torch
+    def test_rotate_zero_is_identity(self):
+        import torch
+        m = make_rotate(0.0)
+        self.assertTrue(torch.allclose(m, torch.eye(3), atol=1e-5))
+
+    @_skip_no_torch
+    def test_rotate_quarter_turn(self):
+        import torch
+        m = make_rotate(0.25)   # 90°
+        expected = torch.tensor([[0, -1, 0], [1, 0, 0], [0, 0, 1]], dtype=torch.float32)
+        self.assertTrue(torch.allclose(m, expected, atol=1e-5))
+
+    def test_rotate_nonfinite_returns_none(self):
+        self.assertIsNone(make_rotate(float('inf')))
+        self.assertIsNone(make_rotate(float('nan')))
+
+    @_skip_no_torch
+    def test_scale_uniform(self):
+        import torch
+        m = make_scale(2.0)
+        self.assertAlmostEqual(m[0, 0].item(), 2.0)
+        self.assertAlmostEqual(m[1, 1].item(), 2.0)
+
+    def test_scale_zero_rejected(self):
+        self.assertIsNone(make_scale(0.0))
+        self.assertIsNone(make_scale(1.0, 0.0))
+        self.assertIsNone(make_scale(0.0, 1.0))
+
+    def test_scale_nonfinite_rejected(self):
+        self.assertIsNone(make_scale(float('nan'), 1.0))
+
+    @_skip_no_torch
+    def test_shear_safe_range(self):
+        import torch
+        m = make_shear(0.1)
+        self.assertIsNotNone(m)
+        self.assertEqual(m.shape, (3, 3))
+
+    def test_shear_unsafe_range_rejected(self):
+        self.assertIsNone(make_shear(0.25))
+        self.assertIsNone(make_shear(-0.25))
+
+    @_skip_no_torch
+    def test_slide_matrix(self):
+        import torch
+        m = make_slide(0.1, 0.2)
+        self.assertAlmostEqual(m[0, 2].item(), 0.1)
+        self.assertAlmostEqual(m[1, 2].item(), 0.2)
+
+    def test_slide_nonfinite_rejected(self):
+        self.assertIsNone(make_slide(float('nan'), 0.0))
+
+    @_skip_no_torch
+    def test_apply_affine_none_returns_t(self):
+        import torch
+        t = torch.eye(3)
+        self.assertIs(apply_affine(t, None), t)
+
+    @_skip_no_torch
+    def test_try_invert_identity(self):
+        import torch
+        eye = torch.eye(3)
+        result = try_invert_affine(eye)
+        self.assertTrue(torch.allclose(result, eye, atol=1e-6))
+
+    @_skip_no_torch
+    def test_try_invert_singular_returns_identity(self):
+        import torch
+        singular = torch.zeros(3, 3)
+        result = try_invert_affine(singular, 'test_singular')
+        self.assertTrue(torch.allclose(result, torch.eye(3), atol=1e-6))
+
+    def test_private_aliases_work(self):
+        # Backward-compat aliases must point to the same function
+        self.assertIs(_make_rotate, make_rotate)
+        self.assertIs(_make_scale, make_scale)
+        self.assertIs(_apply_affine, apply_affine)
+
+    # --- parser dispatch table ---
+
+    def test_affine_transforms_keys(self):
+        self.assertIn('ROTATE', affine_transforms)
+        self.assertIn('SCALE',  affine_transforms)
+        self.assertIn('SLIDE',  affine_transforms)
+        self.assertIn('SHEAR',  affine_transforms)
+
+    @_skip_no_torch
+    def test_affine_transforms_callable(self):
+        import torch
+        t = torch.eye(3, dtype=torch.float32)
+        result = affine_transforms['ROTATE'](t, 0.0)
+        self.assertTrue(torch.allclose(result, t, atol=1e-5))
+
+    # --- snippet builder ---
+
+    def test_snippet_flip_h(self):
+        self.assertEqual(build_affine_snippet('FLIP_H', 0, 0), 'SCALE[-1,1]')
+
+    def test_snippet_flip_v(self):
+        self.assertEqual(build_affine_snippet('FLIP_V', 0, 0), 'SCALE[1,-1]')
+
+    def test_snippet_rotate(self):
+        s = build_affine_snippet('ROTATE', 0.25, 0)
+        self.assertEqual(s, 'ROTATE[0.25]')
+
+    def test_snippet_scale_uniform(self):
+        s = build_affine_snippet('SCALE', 2.0, 2.0)
+        self.assertEqual(s, 'SCALE[2.0]')
+
+    def test_snippet_scale_anisotropic(self):
+        s = build_affine_snippet('SCALE', 1.5, 1.0)
+        self.assertEqual(s, 'SCALE[1.5,1.0]')
+
+    def test_snippet_parseable(self):
+        for snip in ['ROTATE[0.125]', 'SCALE[-1,1]', 'SLIDE[0.1,0.0]']:
+            with self.subTest(snip=snip):
+                p.parse_root(f'base {snip} AND_PERP style :0.8')
+
+    def test_presets_non_none_are_tuples(self):
+        for name, val in AFFINE_PRESETS.items():
+            with self.subTest(preset=name):
+                if val is not None:
+                    self.assertIsInstance(val, tuple)
+                    self.assertIn(val[0], AFFINE_TRANSFORMS)
+
+
+# ---------------------------------------------------------------------------
+# protection_utils
+# ---------------------------------------------------------------------------
+
+class TestProtectionUtils(unittest.TestCase):
+
+    def _leaf(self, strat=None):
+        return p.LeafPrompt(weight=1.0, conciliation=strat,
+                            local_transform=None, prompt='text',
+                            conciliation_params={})
+
+    def _composite(self, children):
+        return p.CompositePrompt(weight=1.0, conciliation=None,
+                                 local_transform=None, children=children,
+                                 conciliation_params={})
+
+    # --- structural checks ---
+
+    def test_base_child_is_valid(self):
+        node = self._composite([self._leaf(None)])
+        self.assertTrue(prompt_has_valid_base_path(node))
+
+    def test_all_conciliation_is_invalid(self):
+        node = self._composite([
+            self._leaf(p.ConciliationStrategy.PERPENDICULAR),
+        ])
+        self.assertFalse(prompt_has_valid_base_path(node))
+
+    def test_leaf_not_valid_base_path(self):
+        self.assertFalse(prompt_has_valid_base_path(self._leaf(None)))
+
+    def test_mixed_children_is_valid(self):
+        node = self._composite([
+            self._leaf(None),
+            self._leaf(p.ConciliationStrategy.SALIENCE_MASK),
+        ])
+        self.assertTrue(prompt_has_valid_base_path(node))
+
+    def test_invalid_indices_empty_on_ok_batch(self):
+        ok = self._composite([self._leaf(None)])
+        self.assertEqual(get_invalid_base_prompt_indices([ok]), [])
+
+    def test_invalid_indices_reports_bad_positions(self):
+        ok  = self._composite([self._leaf(None)])
+        bad = self._composite([self._leaf(p.ConciliationStrategy.PERPENDICULAR)])
+        indices = get_invalid_base_prompt_indices([ok, bad, ok])
+        self.assertEqual(indices, [1])
+
+    def test_has_valid_base_path_empty_is_false(self):
+        self.assertFalse(has_valid_base_path([]))
+
+    def test_has_valid_base_path_all_ok(self):
+        ok = self._composite([self._leaf(None)])
+        self.assertTrue(has_valid_base_path([ok]))
+
+    def test_has_valid_base_path_mixed_batch_is_false(self):
+        ok  = self._composite([self._leaf(None)])
+        bad = self._composite([self._leaf(p.ConciliationStrategy.PERPENDICULAR)])
+        self.assertFalse(has_valid_base_path([ok, bad]))
+
+    # --- safe_norm ---
+
+    @_skip_no_torch
+    def test_safe_norm_positive(self):
+        import torch
+        t = torch.tensor([3.0, 4.0])
+        self.assertAlmostEqual(safe_norm(t), 5.0, places=4)
+
+    @_skip_no_torch
+    def test_safe_norm_zero_tensor(self):
+        import torch
+        self.assertEqual(safe_norm(torch.zeros(3)), 0.0)
+
+    @_skip_no_torch
+    def test_safe_norm_nan_returns_zero(self):
+        import torch
+        t = torch.tensor([float('nan'), 1.0])
+        self.assertEqual(safe_norm(t), 0.0)
+
+    # --- soft attenuation ---
+
+    def test_attenuation_no_change_when_ratio_ok(self):
+        # base_norm / aux_norm = 0.8 / 0.4 = 2.0 ≥ threshold 0.1
+        factor = compute_soft_attenuation(0.8, 0.4, 0.1)
+        self.assertAlmostEqual(factor, 1.0)
+
+    def test_attenuation_reduces_when_ratio_low(self):
+        # base=0.05, aux=1.0, threshold=0.2 → ratio=0.05 < 0.2
+        # factor = 0.05 / (1.0 * 0.2) = 0.25
+        factor = compute_soft_attenuation(0.05, 1.0, 0.2)
+        self.assertAlmostEqual(factor, 0.25, places=5)
+
+    def test_attenuation_zero_aux_returns_one(self):
+        self.assertAlmostEqual(compute_soft_attenuation(0.5, 0.0, 0.1), 1.0)
+
+    def test_attenuation_clamped_to_zero_min(self):
+        factor = compute_soft_attenuation(-1.0, 1.0, 0.2)
+        self.assertGreaterEqual(factor, 0.0)
+
+    # --- protection_verdict ---
+
+    def test_verdict_off(self):
+        saved = global_state.protection_mode
+        global_state.protection_mode = 'off'
+        try:
+            status, msg = protection_verdict('base AND_PERP style :0.8')
+            self.assertEqual(status, 'off')
+        finally:
+            global_state.protection_mode = saved
+
+    def test_verdict_ok_with_base(self):
+        saved = global_state.protection_mode
+        global_state.protection_mode = 'auto'
+        try:
+            status, msg = protection_verdict('base subject AND_SALT[5] texture :0.8')
+            self.assertEqual(status, 'ok')
+        finally:
+            global_state.protection_mode = saved
+
+    def test_verdict_fire_no_base(self):
+        saved = global_state.protection_mode
+        global_state.protection_mode = 'auto'
+        try:
+            status, msg = protection_verdict('AND_SALT[5] only :0.8')
+            self.assertEqual(status, 'fire')
+        finally:
+            global_state.protection_mode = saved
+
+    def test_verdict_soft_mode_mentions_attenuation(self):
+        saved = global_state.protection_mode
+        global_state.protection_mode = 'soft'
+        try:
+            status, msg = protection_verdict('base AND_SALT[5] texture :0.8')
+            self.assertEqual(status, 'ok')
+            self.assertIn('attenuat', msg.lower())
+        finally:
+            global_state.protection_mode = saved
+
+    def test_normalize_soft_is_valid(self):
+        self.assertEqual(global_state.normalize_protection_mode('soft'), 'soft')
+
+    def test_normalize_unknown_falls_back_to_auto(self):
+        self.assertEqual(global_state.normalize_protection_mode('INVALID'), 'auto')
+
+
+# ---------------------------------------------------------------------------
+# step_utils
+# ---------------------------------------------------------------------------
+
+class TestStepWindow(unittest.TestCase):
+
+    def test_clamp_start_to_zero(self):
+        w = StepWindow(-0.5, 0.8)
+        self.assertAlmostEqual(w.start, 0.0)
+
+    def test_clamp_end_to_one(self):
+        w = StepWindow(0.2, 2.0)
+        self.assertAlmostEqual(w.end, 1.0)
+
+    def test_start_gt_end_clamped(self):
+        w = StepWindow(0.8, 0.2)
+        self.assertLessEqual(w.start, w.end)
+
+    def test_is_active_inside(self):
+        w = StepWindow(0.3, 0.7)
+        self.assertTrue(w.is_active_at(0.5))
+
+    def test_is_active_at_boundary(self):
+        w = StepWindow(0.3, 0.7)
+        self.assertTrue(w.is_active_at(0.3))
+        self.assertTrue(w.is_active_at(0.7))
+
+    def test_is_active_outside(self):
+        w = StepWindow(0.3, 0.7)
+        self.assertFalse(w.is_active_at(0.1))
+        self.assertFalse(w.is_active_at(0.9))
+
+    def test_always_active_is_always_active(self):
+        for p in [0.0, 0.5, 1.0]:
+            self.assertTrue(ALWAYS_ACTIVE.is_active_at(p))
+
+    def test_repr(self):
+        w = StepWindow(0.3, 0.7)
+        self.assertIn('0.30', repr(w))
+        self.assertIn('0.70', repr(w))
+
+
+class TestNormalizeProgress(unittest.TestCase):
+
+    def test_first_step(self):
+        self.assertAlmostEqual(normalize_progress(0, 20), 0.0)
+
+    def test_last_step(self):
+        self.assertAlmostEqual(normalize_progress(19, 20), 1.0)
+
+    def test_midpoint(self):
+        p = normalize_progress(10, 21)
+        self.assertAlmostEqual(p, 10 / 20)
+
+    def test_single_step(self):
+        self.assertAlmostEqual(normalize_progress(0, 1), 0.0)
+
+    def test_clamp_to_zero_one(self):
+        self.assertGreaterEqual(normalize_progress(0, 100), 0.0)
+        self.assertLessEqual(normalize_progress(99, 100), 1.0)
+
+
+class TestStrategyIsActive(unittest.TestCase):
+
+    def test_no_window_always_active(self):
+        self.assertTrue(strategy_is_active('SALIENCE_MASK', 0.5))
+        self.assertTrue(strategy_is_active('PERPENDICULAR', 0.0))
+
+    def test_global_window_gates(self):
+        win = StepWindow(0.4, 0.8)
+        self.assertTrue( strategy_is_active('SALIENCE_MASK', 0.6, global_window=win))
+        self.assertFalse(strategy_is_active('SALIENCE_MASK', 0.1, global_window=win))
+
+    def test_per_strategy_overrides_global(self):
+        global_win = StepWindow(0.0, 1.0)
+        per_s = {'SALIENCE_MASK': StepWindow(0.6, 1.0)}
+        # At 0.3: global says active, per-strategy says inactive
+        self.assertFalse(strategy_is_active(
+            'SALIENCE_MASK', 0.3, global_window=global_win,
+            per_strategy_windows=per_s))
+
+    def test_defaults_perp_early(self):
+        # PERPENDICULAR default: 0.0–0.5
+        self.assertTrue( strategy_is_active('PERPENDICULAR', 0.3, use_defaults=True))
+        self.assertFalse(strategy_is_active('PERPENDICULAR', 0.8, use_defaults=True))
+
+    def test_defaults_salt_late(self):
+        # SALIENCE_MASK default: 0.4–1.0
+        self.assertTrue( strategy_is_active('SALIENCE_MASK', 0.7, use_defaults=True))
+        self.assertFalse(strategy_is_active('SALIENCE_MASK', 0.1, use_defaults=True))
+
+    def test_legacy_alignment_strategy_family(self):
+        fam = _strategy_family('ALIGNMENT_BLEND_4_8')
+        self.assertEqual(fam, 'ALIGNMENT_BLEND_CUSTOM')
+
+    def test_legacy_mask_alignment_family(self):
+        fam = _strategy_family('ALIGNMENT_MASK_BLEND_8_16')
+        self.assertEqual(fam, 'ALIGNMENT_MASK_BLEND_CUSTOM')
+
+    def test_base_strategy_family_unchanged(self):
+        self.assertEqual(_strategy_family('PERPENDICULAR'), 'PERPENDICULAR')
+
+
+class TestStepWindowSummary(unittest.TestCase):
+
+    def test_empty_strategies_returns_empty(self):
+        out = render_step_window_summary([])
+        self.assertEqual(out, '')
+
+    def test_no_window_shows_all_steps(self):
+        out = render_step_window_summary(['SALIENCE_MASK'])
+        self.assertIn('all steps', out)
+
+    def test_global_window_shown(self):
+        win = StepWindow(0.3, 0.8)
+        out = render_step_window_summary(['SALIENCE_MASK'], global_window=win)
+        self.assertIn('SALIENCE_MASK', out)
+        self.assertIn('0.30', out)
+
+    def test_defaults_shown(self):
+        out = render_step_window_summary(['PERPENDICULAR'], use_defaults=True)
+        self.assertIn('PERPENDICULAR', out)
+        self.assertIn('default', out)
+
+    def test_progress_shows_active_status(self):
+        win = StepWindow(0.4, 0.9)
+        out = render_step_window_summary(['SALIENCE_MASK'], progress=0.5, global_window=win)
+        self.assertIn('active', out)
+
+
+# ---------------------------------------------------------------------------
+# Builder v1.2
+# ---------------------------------------------------------------------------
+
+class TestBuilderNode(unittest.TestCase):
+
+    def test_make_creates_node(self):
+        n = BuilderNode.make('AND_SALT', 'texture', 0.8)
+        self.assertEqual(n.strategy, 'AND_SALT')
+        self.assertEqual(n.text, 'texture')
+        self.assertAlmostEqual(n.weight, 0.8)
+        self.assertIsNotNone(n.node_id)
+
+    def test_make_unique_ids(self):
+        ids = {BuilderNode.make().node_id for _ in range(20)}
+        self.assertEqual(len(ids), 20)
+
+    def test_default_no_children(self):
+        n = BuilderNode.make()
+        self.assertEqual(n.children, [])
+
+
+class TestBuilderAddChild(unittest.TestCase):
+
+    def test_add_to_empty(self):
+        nodes = builder_add_child([], strategy='AND_SALT', text='tex', weight=0.8)
+        self.assertEqual(len(nodes), 1)
+        self.assertEqual(nodes[0].strategy, 'AND_SALT')
+
+    def test_add_appends(self):
+        n1 = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        nodes = builder_add_child([n1], strategy='AND_PERP', text='style', weight=0.5)
+        self.assertEqual(len(nodes), 2)
+
+    def test_add_nested_child(self):
+        parent = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        nodes = builder_add_child([parent], parent_id=parent.node_id,
+                                  strategy='AND_TOPK', text='detail', weight=0.4)
+        self.assertEqual(len(nodes), 1)
+        self.assertEqual(len(nodes[0].children), 1)
+        self.assertEqual(nodes[0].children[0].strategy, 'AND_TOPK')
+
+    def test_original_not_mutated(self):
+        original = [BuilderNode.make()]
+        builder_add_child(original)
+        self.assertEqual(len(original), 1)
+
+
+class TestBuilderRemoveNode(unittest.TestCase):
+
+    def test_remove_top_level(self):
+        n1 = BuilderNode.make()
+        n2 = BuilderNode.make()
+        result = builder_remove_node([n1, n2], n1.node_id)
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0].node_id, n2.node_id)
+
+    def test_remove_nested(self):
+        child = BuilderNode.make('AND_TOPK', 'c', 0.5)
+        parent = BuilderNode.make('AND_SALT', 'p', 0.8)
+        parent = dataclasses_replace(parent, children=[child])
+        result = builder_remove_node([parent], child.node_id)
+        self.assertEqual(len(result[0].children), 0)
+
+    def test_remove_nonexistent_no_error(self):
+        n = BuilderNode.make()
+        result = builder_remove_node([n], 'nonexistent')
+        self.assertEqual(len(result), 1)
+
+
+class TestBuilderDuplicateNode(unittest.TestCase):
+
+    def test_duplicate_creates_new_id(self):
+        n = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        result = builder_duplicate_node([n], n.node_id)
+        self.assertEqual(len(result), 2)
+        self.assertNotEqual(result[0].node_id, result[1].node_id)
+
+    def test_duplicate_copies_content(self):
+        n = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        result = builder_duplicate_node([n], n.node_id)
+        self.assertEqual(result[1].text, 'tex')
+        self.assertEqual(result[1].strategy, 'AND_SALT')
+
+
+class TestBuilderMoveNodes(unittest.TestCase):
+
+    def _nodes(self, *strategies):
+        return [BuilderNode.make(s, s, 1.0) for s in strategies]
+
+    def test_move_up_swaps(self):
+        ns = self._nodes('AND_SALT', 'AND_PERP', 'AND_TOPK')
+        result = builder_move_up(ns, ns[1].node_id)
+        self.assertEqual(result[0].strategy, 'AND_PERP')
+        self.assertEqual(result[1].strategy, 'AND_SALT')
+
+    def test_move_up_first_no_change(self):
+        ns = self._nodes('AND_SALT', 'AND_PERP')
+        result = builder_move_up(ns, ns[0].node_id)
+        self.assertEqual(result[0].strategy, 'AND_SALT')
+
+    def test_move_down_swaps(self):
+        ns = self._nodes('AND_SALT', 'AND_PERP', 'AND_TOPK')
+        result = builder_move_down(ns, ns[1].node_id)
+        self.assertEqual(result[1].strategy, 'AND_TOPK')
+        self.assertEqual(result[2].strategy, 'AND_PERP')
+
+    def test_move_down_last_no_change(self):
+        ns = self._nodes('AND_SALT', 'AND_PERP')
+        result = builder_move_down(ns, ns[-1].node_id)
+        self.assertEqual(result[-1].strategy, 'AND_PERP')
+
+
+class TestBuilderUpdateNode(unittest.TestCase):
+
+    def test_update_text(self):
+        n = BuilderNode.make('AND_SALT', 'old', 0.8)
+        result = builder_update_node([n], n.node_id, text='new')
+        self.assertEqual(result[0].text, 'new')
+
+    def test_update_weight(self):
+        n = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        result = builder_update_node([n], n.node_id, weight=0.3)
+        self.assertAlmostEqual(result[0].weight, 0.3)
+
+    def test_update_nonexistent_no_change(self):
+        n = BuilderNode.make('AND_SALT', 'tex', 0.8)
+        result = builder_update_node([n], 'nope', text='changed')
+        self.assertEqual(result[0].text, 'tex')
+
+
+class TestSerializeBuilderTree(unittest.TestCase):
+
+    def test_base_only(self):
+        out = builder_tree_to_prompt('base subject', [])
+        self.assertEqual(out.strip(), 'base subject')
+
+    def test_single_node(self):
+        n = BuilderNode.make('AND_SALT', 'texture', 0.8)
+        out = builder_tree_to_prompt('base', [n])
+        self.assertIn('AND_SALT[5]', out)
+        self.assertIn('texture', out)
+        self.assertIn(':0.8', out)
+
+    def test_nested_node_renders_brackets(self):
+        child = BuilderNode.make('AND_TOPK', 'highlights', 0.4)
+        parent_node = BuilderNode.make('AND_SALT', 'texture', 0.8)
+        parent_node = dataclasses_replace(parent_node, children=[child])
+        out = builder_tree_to_prompt('base', [parent_node])
+        self.assertIn('[', out)
+        self.assertIn(']', out)
+        self.assertIn('AND_TOPK', out)
+
+    def test_generated_prompt_parseable(self):
+        n1 = BuilderNode.make('AND_SALT', 'texture', 0.8)
+        n2 = BuilderNode.make('AND_PERP', 'style', 0.5)
+        out = builder_tree_to_prompt('base', [n1, n2])
+        p.parse_root(out)   # must not raise
+
+    def test_empty_text_node_skipped(self):
+        n = BuilderNode.make('AND_SALT', '', 0.8)
+        out = builder_tree_to_prompt('base', [n])
+        self.assertNotIn('AND_SALT', out)
+
+    def test_affine_prefix_included(self):
+        n = BuilderNode.make('AND_PERP', 'mirror', 0.6, affine='SCALE[-1,1]')
+        out = builder_tree_to_prompt('base', [n])
+        self.assertIn('SCALE[-1,1]', out)
+
+    def test_two_top_level_children(self):
+        n1 = BuilderNode.make('AND_SALT',  'tex',   0.8)
+        n2 = BuilderNode.make('AND_ALIGN', 'shape', 0.7)
+        out = builder_tree_to_prompt('base', [n1, n2])
+        self.assertIn('AND_SALT',  out)
+        self.assertIn('AND_ALIGN', out)
+
+
+# dataclasses.replace alias for Python <3.13
+import dataclasses
+dataclasses_replace = dataclasses.replace
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_sprint2_hotfix.py

@@ -0,0 +1,419 @@
+"""
+Sprint 2 hotfix tests — covers all 4 issues patched after Sprint 2 review.
+
+1. BUILDER_STRATEGIES name fix (smoke-test that the name resolves)
+2. update_step_state helper + step-counter round-trip
+3. get_extra_generation_params / unpack_processing_args step-window round-trip
+4. apply_infotext step-window restore
+   + 'custom' mode absent from two-mode choices
+"""
+
+import unittest
+
+import lib_neutral_prompt.neutral_prompt_parser as p
+from lib_neutral_prompt import global_state
+from lib_neutral_prompt.matryoshka_utils import BUILDER_STRATEGIES
+from lib_neutral_prompt.step_utils import StepWindow, strategy_is_active, normalize_progress
+
+
+# ---------------------------------------------------------------------------
+# Fix 1 — BUILDER_STRATEGIES is importable and non-empty
+# ---------------------------------------------------------------------------
+
+class TestBuilderStrategiesName(unittest.TestCase):
+
+    def test_importable_and_non_empty(self):
+        self.assertIsInstance(BUILDER_STRATEGIES, list)
+        self.assertGreater(len(BUILDER_STRATEGIES), 0)
+
+    def test_contains_core_strategies(self):
+        self.assertIn('AND_SALT',  BUILDER_STRATEGIES)
+        self.assertIn('AND_PERP',  BUILDER_STRATEGIES)
+        self.assertIn('AND_TOPK',  BUILDER_STRATEGIES)
+        self.assertIn('AND_ALIGN', BUILDER_STRATEGIES)
+
+    def test_no_underscore_variant_exported(self):
+        """The UI used to import _BUILDER_STRATEGIES — make sure that's gone."""
+        import lib_neutral_prompt.matryoshka_utils as mu
+        self.assertFalse(
+            hasattr(mu, '_BUILDER_STRATEGIES'),
+            '_BUILDER_STRATEGIES should not be exported; use BUILDER_STRATEGIES',
+        )
+
+
+# ---------------------------------------------------------------------------
+# Fix 2 — update_step_state + step-window gating integration
+# ---------------------------------------------------------------------------
+
+class TestUpdateStepState(unittest.TestCase):
+
+    def setUp(self):
+        self._saved_step  = global_state.current_step
+        self._saved_total = global_state.total_steps
+
+    def tearDown(self):
+        global_state.current_step = self._saved_step
+        global_state.total_steps  = self._saved_total
+
+    def test_basic_update(self):
+        global_state.update_step_state(5, 20)
+        self.assertEqual(global_state.current_step, 5)
+        self.assertEqual(global_state.total_steps,  20)
+
+    def test_float_inputs_converted(self):
+        global_state.update_step_state(3.9, 19.1)
+        self.assertEqual(global_state.current_step, 3)
+        self.assertEqual(global_state.total_steps,  19)
+
+    def test_negative_step_clamped_to_zero(self):
+        global_state.update_step_state(-1, 10)
+        self.assertEqual(global_state.current_step, 0)
+
+    def test_zero_total_clamped_to_one(self):
+        global_state.update_step_state(0, 0)
+        self.assertEqual(global_state.total_steps, 1)
+
+    def test_bad_types_do_not_crash(self):
+        global_state.update_step_state('bad', None)
+        # Should stay at some valid state
+        self.assertGreaterEqual(global_state.current_step, 0)
+        self.assertGreaterEqual(global_state.total_steps, 1)
+
+    def test_first_step_progress_is_zero(self):
+        global_state.update_step_state(0, 20)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        self.assertAlmostEqual(p, 0.0)
+
+    def test_last_step_progress_is_one(self):
+        global_state.update_step_state(19, 20)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        self.assertAlmostEqual(p, 1.0)
+
+
+class TestStepWindowGatingIntegration(unittest.TestCase):
+    """
+    Simulate the hijack path: update_step_state → normalize_progress
+    → strategy_is_active with a global window.
+    This is the scenario described in the fix-2 specification.
+    """
+
+    def setUp(self):
+        self._saved_step  = global_state.current_step
+        self._saved_total = global_state.total_steps
+
+    def tearDown(self):
+        global_state.current_step = self._saved_step
+        global_state.total_steps  = self._saved_total
+
+    def _set_step(self, step, total):
+        global_state.update_step_state(step, total)
+
+    def test_and_salt_gated_out_in_early_window(self):
+        """AND_SALT with window 0.6–1.0 should be skipped at step 0/9."""
+        self._set_step(0, 10)
+        win = StepWindow(0.6, 1.0)
+        progress = normalize_progress(global_state.current_step, global_state.total_steps)
+        active = strategy_is_active('SALIENCE_MASK', progress, global_window=win)
+        self.assertFalse(active, f'Expected inactive at progress={progress:.3f}')
+
+    def test_and_salt_active_in_late_window(self):
+        """AND_SALT with window 0.6–1.0 should be active at step 8/10."""
+        self._set_step(8, 10)
+        win = StepWindow(0.6, 1.0)
+        progress = normalize_progress(global_state.current_step, global_state.total_steps)
+        active = strategy_is_active('SALIENCE_MASK', progress, global_window=win)
+        self.assertTrue(active, f'Expected active at progress={progress:.3f}')
+
+    def test_and_perp_active_early_with_defaults(self):
+        """AND_PERP defaults: 0.0–0.5 → step 2/10 should be active."""
+        self._set_step(2, 10)
+        progress = normalize_progress(global_state.current_step, global_state.total_steps)
+        active = strategy_is_active('PERPENDICULAR', progress, use_defaults=True)
+        self.assertTrue(active, f'Expected active at progress={progress:.3f}')
+
+    def test_and_perp_gated_out_late_with_defaults(self):
+        """AND_PERP defaults: 0.0–0.5 → step 8/10 should be inactive."""
+        self._set_step(8, 10)
+        progress = normalize_progress(global_state.current_step, global_state.total_steps)
+        active = strategy_is_active('PERPENDICULAR', progress, use_defaults=True)
+        self.assertFalse(active, f'Expected inactive at progress={progress:.3f}')
+
+    def test_no_window_always_active_regardless_of_step(self):
+        for step in (0, 5, 9):
+            with self.subTest(step=step):
+                self._set_step(step, 10)
+                progress = normalize_progress(global_state.current_step, global_state.total_steps)
+                self.assertTrue(strategy_is_active('SALIENCE_MASK', progress))
+
+
+# ---------------------------------------------------------------------------
+# Fix 3 — step-window round-trip through unpack_processing_args + get_extra
+# ---------------------------------------------------------------------------
+
+def _unpack_step_window(cfg_rescale=0.0, protection_mode='auto', strict_threshold=0.1,
+                        step_window_enabled=False, step_window_mode='global',
+                        step_window_start=0.0, step_window_end=1.0):
+    """
+    Pure-logic equivalent of AccordionInterface.unpack_processing_args
+    without any gradio dependency — mirrors the real implementation exactly.
+    """
+    enabled = bool(step_window_enabled)
+    mode    = str(step_window_mode)
+    start   = max(0.0, min(1.0, float(step_window_start)))
+    end     = max(0.0, min(1.0, float(step_window_end)))
+    if start > end:
+        start, end = 0.0, 1.0
+
+    global_state.step_window_enabled = enabled
+    if enabled:
+        if mode == 'global':
+            global_state.step_window_global       = StepWindow(start, end)
+            global_state.step_window_use_defaults = False
+        elif mode == 'per-strategy defaults':
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = True
+        else:
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = False
+    else:
+        global_state.step_window_global       = None
+        global_state.step_window_use_defaults = False
+
+    return {'cfg_rescale': cfg_rescale, 'protection_mode': protection_mode,
+            'strict_threshold': strict_threshold,
+            'step_window_enabled': enabled, 'step_window_mode': mode,
+            'step_window_start': start, 'step_window_end': end}
+
+
+def _get_extra_params(args):
+    """Pure-logic equivalent of AccordionInterface.get_extra_generation_params."""
+    p = {'CFG Rescale phi': args['cfg_rescale'],
+         'NP Protection Mode': args['protection_mode'],
+         'NP Strict Threshold': args['strict_threshold']}
+    if args.get('step_window_enabled'):
+        p['NP Step Window Enabled'] = True
+        p['NP Step Window Mode']    = args.get('step_window_mode', 'global')
+        p['NP Step Window Start']   = round(float(args.get('step_window_start', 0.0)), 4)
+        p['NP Step Window End']     = round(float(args.get('step_window_end',   1.0)), 4)
+    return p
+
+
+class TestStepWindowProcessingRoundTrip(unittest.TestCase):
+
+    def setUp(self):
+        self._saved_enabled      = global_state.step_window_enabled
+        self._saved_global       = global_state.step_window_global
+        self._saved_use_defaults = global_state.step_window_use_defaults
+
+    def tearDown(self):
+        global_state.step_window_enabled      = self._saved_enabled
+        global_state.step_window_global       = self._saved_global
+        global_state.step_window_use_defaults = self._saved_use_defaults
+
+    def test_global_window_written_to_state(self):
+        args = _unpack_step_window(
+            cfg_rescale=0.0,
+            step_window_enabled=True,
+            step_window_mode='global',
+            step_window_start=0.3,
+            step_window_end=0.8,
+        )
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertIsNotNone(global_state.step_window_global)
+        self.assertAlmostEqual(global_state.step_window_global.start, 0.3, places=4)
+        self.assertAlmostEqual(global_state.step_window_global.end,   0.8, places=4)
+
+    def test_defaults_mode_sets_use_defaults(self):
+        _unpack_step_window(
+            cfg_rescale=0.0,
+            step_window_enabled=True,
+            step_window_mode='per-strategy defaults',
+        )
+        self.assertTrue(global_state.step_window_use_defaults)
+        self.assertIsNone(global_state.step_window_global)
+
+    def test_disabled_clears_state(self):
+        global_state.step_window_enabled = True
+        global_state.step_window_global  = StepWindow(0.3, 0.8)
+        _unpack_step_window(cfg_rescale=0.0, step_window_enabled=False)
+        self.assertFalse(global_state.step_window_enabled)
+        self.assertIsNone(global_state.step_window_global)
+
+    def test_invalid_range_falls_back_to_full(self):
+        args = _unpack_step_window(
+            cfg_rescale=0.0,
+            step_window_enabled=True,
+            step_window_mode='global',
+            step_window_start=0.9,
+            step_window_end=0.1,    # start > end → fallback
+        )
+        self.assertAlmostEqual(args['step_window_start'], 0.0)
+        self.assertAlmostEqual(args['step_window_end'],   1.0)
+
+    def test_extra_params_include_step_window_when_enabled(self):
+        args = {
+            'cfg_rescale': 0.0,
+            'protection_mode': 'auto',
+            'strict_threshold': 0.1,
+            'step_window_enabled': True,
+            'step_window_mode': 'global',
+            'step_window_start': 0.3,
+            'step_window_end': 0.8,
+        }
+        params = _get_extra_params(args)
+        self.assertIn('NP Step Window Enabled', params)
+        self.assertIn('NP Step Window Mode',    params)
+        self.assertIn('NP Step Window Start',   params)
+        self.assertIn('NP Step Window End',     params)
+        self.assertAlmostEqual(params['NP Step Window Start'], 0.3, places=4)
+
+    def test_extra_params_omit_step_window_when_disabled(self):
+        args = {
+            'cfg_rescale': 0.0,
+            'protection_mode': 'auto',
+            'strict_threshold': 0.1,
+            'step_window_enabled': False,
+        }
+        params = _get_extra_params(args)
+        self.assertNotIn('NP Step Window Enabled', params)
+
+
+# ---------------------------------------------------------------------------
+# Fix 3 — apply_infotext step-window restore
+# ---------------------------------------------------------------------------
+
+class TestApplyInfotextStepWindow(unittest.TestCase):
+
+    def setUp(self):
+        self._saved_enabled      = global_state.step_window_enabled
+        self._saved_global       = global_state.step_window_global
+        self._saved_use_defaults = global_state.step_window_use_defaults
+
+    def tearDown(self):
+        global_state.step_window_enabled      = self._saved_enabled
+        global_state.step_window_global       = self._saved_global
+        global_state.step_window_use_defaults = self._saved_use_defaults
+
+    def test_global_window_restored(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'global',
+            'NP Step Window Start':   '0.25',
+            'NP Step Window End':     '0.75',
+        })
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertIsNotNone(global_state.step_window_global)
+        self.assertAlmostEqual(global_state.step_window_global.start, 0.25, places=4)
+        self.assertAlmostEqual(global_state.step_window_global.end,   0.75, places=4)
+
+    def test_defaults_mode_restored(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'per-strategy defaults',
+        })
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertTrue(global_state.step_window_use_defaults)
+        self.assertIsNone(global_state.step_window_global)
+
+    def test_disabled_not_restored_when_key_absent(self):
+        global_state.step_window_enabled = True
+        global_state.apply_infotext({})   # no step-window keys
+        # Should be unchanged
+        self.assertTrue(global_state.step_window_enabled)
+
+    def test_false_string_disables(self):
+        global_state.step_window_enabled = True
+        global_state.apply_infotext({'NP Step Window Enabled': 'False'})
+        self.assertFalse(global_state.step_window_enabled)
+
+    def test_invalid_range_falls_back_to_full(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'global',
+            'NP Step Window Start':   '0.9',
+            'NP Step Window End':     '0.1',   # inverted
+        })
+        win = global_state.step_window_global
+        self.assertAlmostEqual(win.start, 0.0, places=4)
+        self.assertAlmostEqual(win.end,   1.0, places=4)
+
+    def test_old_infotext_without_step_window_keys_does_not_crash(self):
+        global_state.apply_infotext({
+            'CFG Rescale phi':  '0.5',
+            'NP Protection Mode': 'auto',
+        })
+        # No crash, step_window unchanged
+
+
+# ---------------------------------------------------------------------------
+# Fix 4 — 'custom' absent from step_window_mode UI choices
+# ---------------------------------------------------------------------------
+
+class TestCustomModeRemovedFromUI(unittest.TestCase):
+
+    def test_step_window_update_handler_accepts_two_modes(self):
+        """
+        The step-window update logic must handle exactly the two released modes
+        without any 'custom' branch.
+        """
+        saved = {
+            'enabled':      global_state.step_window_enabled,
+            'global':       global_state.step_window_global,
+            'use_defaults': global_state.step_window_use_defaults,
+        }
+        try:
+            for mode in ('global', 'per-strategy defaults'):
+                with self.subTest(mode=mode):
+                    global_state.step_window_enabled = True
+                    if mode == 'global':
+                        global_state.step_window_global       = StepWindow(0.3, 0.8)
+                        global_state.step_window_use_defaults = False
+                    else:
+                        global_state.step_window_global       = None
+                        global_state.step_window_use_defaults = True
+                    # Verify state is consistent for both valid modes
+                    if mode == 'global':
+                        self.assertIsNotNone(global_state.step_window_global)
+                    else:
+                        self.assertTrue(global_state.step_window_use_defaults)
+        finally:
+            global_state.step_window_enabled      = saved['enabled']
+            global_state.step_window_global       = saved['global']
+            global_state.step_window_use_defaults = saved['use_defaults']
+
+    def test_step_utils_still_supports_custom_internally(self):
+        """
+        custom is removed from UI but step_utils.strategy_is_active must
+        still accept None per_strategy_windows gracefully (for API use).
+        """
+        from lib_neutral_prompt.step_utils import strategy_is_active
+        # custom = no global_window, no per_strategy_windows, no defaults
+        active = strategy_is_active('SALIENCE_MASK', 0.5,
+                                    global_window=None,
+                                    per_strategy_windows=None,
+                                    use_defaults=False)
+        self.assertTrue(active, 'Without any window, strategy must be always active')
+
+    def test_unpack_does_not_expose_custom_mode_to_state(self):
+        """
+        If someone passes 'custom' through the API, unpack must fall back
+        to a safe state (no window, no defaults).
+        """
+        saved_global   = global_state.step_window_global
+        saved_defaults = global_state.step_window_use_defaults
+        try:
+            _unpack_step_window(
+                cfg_rescale=0.0,
+                step_window_enabled=True,
+                step_window_mode='custom',   # not in UI, but API-safe
+            )
+            # In the 'else' branch: global=None, use_defaults=False
+            self.assertIsNone(global_state.step_window_global)
+            self.assertFalse(global_state.step_window_use_defaults)
+        finally:
+            global_state.step_window_global       = saved_global
+            global_state.step_window_use_defaults = saved_defaults
+
+
+if __name__ == '__main__':
+    unittest.main()

neutral_prompt_patcheds/test/perp_parser/test_stabilization.py

@@ -0,0 +1,539 @@
+"""
+Stabilization test suite — Sprint 2 hotfix + per-strategy custom windows.
+
+Sections
+--------
+1. UI smoke-test          – verifies ui.py imports and AccordionInterface constructs
+                            without NameError / bad Gradio kwargs
+2. Step-window integration – update_step_state → progress → strategy activation
+3. Generation params round-trip – serialize → apply_infotext → state restored
+4. Per-strategy custom windows – serialize/deserialize/build helpers
+5. Per-strategy round-trip     – custom mode infotext restore
+"""
+
+import sys
+import types
+import unittest
+import importlib
+
+from lib_neutral_prompt import global_state
+from lib_neutral_prompt.step_utils import (
+    StepWindow,
+    normalize_progress,
+    strategy_is_active,
+    STRATEGY_UI_KEYS,
+    STRATEGY_DEFAULTS,
+    normalize_step_range,
+    build_per_strategy_windows,
+    serialize_per_strategy_windows,
+    deserialize_per_strategy_windows,
+    default_custom_windows,
+    ui_key_to_family,
+)
+
+
+# ===========================================================================
+# 1. UI smoke-test
+# ===========================================================================
+
+def _make_fake_gradio():
+    """
+    Minimal gradio mock that records kwargs without raising on unknown ones.
+    This lets us detect *missing constants* (NameError) and *wrong import paths*
+    while ignoring version-specific kwargs differences.
+    """
+    gr = types.ModuleType('gradio')
+
+    class _Component:
+        def __init__(self, *a, **kw):
+            self._kwargs = kw
+            self.value = kw.get('value')
+        def render(self):          return self
+        def change(self, **kw):    return self
+        def click(self, **kw):     return self
+        @staticmethod
+        def update(**kw):          return kw
+
+    for name in ('Checkbox', 'Radio', 'Slider', 'Textbox', 'Button',
+                 'Dropdown', 'Accordion', 'Row', 'Column', 'Tab', 'Tabs',
+                 'HTML', 'Markdown', 'Number', 'Code'):
+        setattr(gr, name, _Component)
+
+    gr.update = lambda **kw: kw
+    gr.__version__ = '3.41.0'
+    return gr
+
+
+class TestUISmoke(unittest.TestCase):
+    """
+    Import lib_neutral_prompt.ui under mocked gradio + modules and verify that
+    AccordionInterface can be constructed without errors.
+
+    This catches:
+    * NameError (undefined constants like _BUILDER_STRATEGIES)
+    * ImportError (bad relative imports)
+    * AttributeError from wrong Gradio kwarg names such as 'tooltip'
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        # If ui.py was already imported in this process (e.g. by another test
+        # module), the gradio mock cannot be reliably injected.  Mark as skipped
+        # rather than erroring out.
+        if 'lib_neutral_prompt.ui' in sys.modules:
+            cls._ui      = sys.modules['lib_neutral_prompt.ui']
+            cls._skipped = True
+            return
+        cls._skipped = False
+
+        gr = _make_fake_gradio()
+        sys.modules['gradio'] = gr
+
+        fake_cb = types.SimpleNamespace(
+            on_ui_settings=lambda *a, **k: None,
+            on_ui_tabs=lambda *a, **k: None,
+            on_after_component=lambda *a, **k: None,
+        )
+        fake_shared = types.SimpleNamespace(
+            opts=types.SimpleNamespace(
+                add_option=lambda *a, **k: None,
+                onchange=lambda *a, **k: None,
+                data={},
+            ),
+            state=types.SimpleNamespace(sampling_step=0, sampling_steps=1),
+        )
+        fake_modules = types.ModuleType('modules')
+        fake_modules.script_callbacks = fake_cb
+        fake_modules.shared = fake_shared
+        sys.modules.setdefault('modules', fake_modules)
+        sys.modules.setdefault('modules.script_callbacks', fake_cb)
+        sys.modules.setdefault('modules.shared', fake_shared)
+
+        try:
+            cls._ui = importlib.import_module('lib_neutral_prompt.ui')
+        except Exception as exc:
+            raise unittest.SkipTest(f'lib_neutral_prompt.ui failed to import: {exc}')
+
+    def setUp(self):
+        if self._skipped:
+            self.skipTest('lib_neutral_prompt.ui already imported; smoke-test skipped')
+
+    def test_module_imported_without_error(self):
+        self.assertIsNotNone(self._ui)
+
+    def test_accordion_interface_constructs(self):
+        obj = self._ui.AccordionInterface(get_elem_id=lambda s: f'test_{s}')
+        self.assertIsNotNone(obj)
+
+    def test_builder_strategies_constant_reachable(self):
+        from lib_neutral_prompt.matryoshka_utils import BUILDER_STRATEGIES
+        self.assertIsInstance(BUILDER_STRATEGIES, list)
+        self.assertGreater(len(BUILDER_STRATEGIES), 0)
+
+    def test_step_ps_sliders_created_for_all_strategies(self):
+        obj = self._ui.AccordionInterface(get_elem_id=lambda s: f'test2_{s}')
+        for ui_key in STRATEGY_UI_KEYS:
+            self.assertIn(ui_key, obj.step_ps_sliders,
+                          f'Missing per-strategy slider pair for {ui_key}')
+            pair = obj.step_ps_sliders[ui_key]
+            self.assertEqual(len(pair), 2)
+
+    def test_no_tooltip_kwarg_on_dropdown(self):
+        """Regression: tooltip= must have been replaced by info= on all Dropdowns."""
+        import ast
+        import pathlib
+        src = pathlib.Path(
+            __file__).parent.parent.parent / 'lib_neutral_prompt' / 'ui.py'
+        tree = ast.parse(src.read_text())
+        violations = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                for kw in node.keywords:
+                    if kw.arg == 'tooltip':
+                        violations.append(f'line {node.lineno}')
+        self.assertFalse(violations,
+                         f'Found tooltip= kwarg(s) in ui.py: {violations}')
+
+
+# ===========================================================================
+# 2. Step-window integration
+# ===========================================================================
+
+class TestStepWindowIntegration(unittest.TestCase):
+    """
+    Verify that update_step_state → normalize_progress → strategy_is_active
+    gives the expected gating behaviour.
+    """
+
+    def setUp(self):
+        self._step  = global_state.current_step
+        self._total = global_state.total_steps
+
+    def tearDown(self):
+        global_state.current_step = self._step
+        global_state.total_steps  = self._total
+
+    # ---- global window ----
+
+    def test_late_strategy_inactive_at_step_0(self):
+        global_state.update_step_state(0, 10)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        # SALIENCE_MASK default: 0.4–1.0 → inactive at 0.0
+        self.assertFalse(strategy_is_active('SALIENCE_MASK', p, use_defaults=True))
+
+    def test_late_strategy_active_at_step_8(self):
+        global_state.update_step_state(8, 10)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        self.assertTrue(strategy_is_active('SALIENCE_MASK', p, use_defaults=True))
+
+    def test_early_strategy_active_at_step_0(self):
+        global_state.update_step_state(0, 10)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        # PERPENDICULAR default: 0.0–0.5 → active at 0.0
+        self.assertTrue(strategy_is_active('PERPENDICULAR', p, use_defaults=True))
+
+    def test_early_strategy_inactive_at_step_8(self):
+        global_state.update_step_state(8, 10)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        self.assertFalse(strategy_is_active('PERPENDICULAR', p, use_defaults=True))
+
+    def test_global_window_overrides_defaults(self):
+        """A global window [0.6, 1.0] gates AND_PERP out even at step 0."""
+        global_state.update_step_state(0, 10)
+        p = normalize_progress(global_state.current_step, global_state.total_steps)
+        win = StepWindow(0.6, 1.0)
+        self.assertFalse(strategy_is_active('PERPENDICULAR', p,
+                                            global_window=win, use_defaults=True))
+
+    def test_no_window_always_active(self):
+        for step in (0, 5, 9):
+            global_state.update_step_state(step, 10)
+            p = normalize_progress(global_state.current_step, global_state.total_steps)
+            with self.subTest(step=step):
+                self.assertTrue(strategy_is_active('SALIENCE_MASK', p))
+
+
+# ===========================================================================
+# 3. Generation params round-trip (global mode)
+# ===========================================================================
+
+def _unpack(cfg_rescale=0.0, protection_mode='auto', strict_threshold=0.1,
+            step_window_enabled=False, step_window_mode='global',
+            step_window_start=0.0, step_window_end=1.0, **ps_kwargs):
+    """Mirrors AccordionInterface.unpack_processing_args logic — no gradio needed."""
+    from lib_neutral_prompt.step_utils import (
+        StepWindow, build_per_strategy_windows, STRATEGY_UI_KEYS,
+    )
+    enabled = bool(step_window_enabled)
+    mode    = str(step_window_mode)
+    start   = max(0.0, min(1.0, float(step_window_start)))
+    end     = max(0.0, min(1.0, float(step_window_end)))
+    if start > end:
+        start, end = 0.0, 1.0
+
+    custom_raw = {}
+    for uk in STRATEGY_UI_KEYS:
+        sk, ek = f'{uk}_start', f'{uk}_end'
+        if sk in ps_kwargs and ek in ps_kwargs:
+            custom_raw[uk] = (float(ps_kwargs[sk]), float(ps_kwargs[ek]))
+
+    global_state.step_window_enabled = enabled
+    if enabled:
+        if mode == 'global':
+            global_state.step_window_global       = StepWindow(start, end)
+            global_state.step_window_use_defaults = False
+            global_state.step_window_per_strategy = None
+        elif mode == 'per-strategy defaults':
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = True
+            global_state.step_window_per_strategy = None
+        elif mode == 'per-strategy custom':
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = False
+            global_state.step_window_custom_raw   = custom_raw
+            global_state.step_window_per_strategy = build_per_strategy_windows(custom_raw)
+        else:
+            global_state.step_window_global       = None
+            global_state.step_window_use_defaults = False
+    else:
+        global_state.step_window_global       = None
+        global_state.step_window_use_defaults = False
+        global_state.step_window_per_strategy = None
+
+    return {
+        'cfg_rescale': cfg_rescale, 'protection_mode': protection_mode,
+        'strict_threshold': strict_threshold,
+        'step_window_enabled': enabled, 'step_window_mode': mode,
+        'step_window_start': start, 'step_window_end': end,
+        'step_window_custom_raw': custom_raw,
+    }
+
+
+def _extra(args):
+    """Mirrors AccordionInterface.get_extra_generation_params — no gradio."""
+    p = {
+        'CFG Rescale phi':     args['cfg_rescale'],
+        'NP Protection Mode':  args['protection_mode'],
+        'NP Strict Threshold': args['strict_threshold'],
+    }
+    if args.get('step_window_enabled'):
+        p['NP Step Window Enabled'] = True
+        p['NP Step Window Mode']    = args.get('step_window_mode', 'global')
+        p['NP Step Window Start']   = round(float(args.get('step_window_start', 0.0)), 4)
+        p['NP Step Window End']     = round(float(args.get('step_window_end',   1.0)), 4)
+        if args.get('step_window_mode') == 'per-strategy custom':
+            raw = args.get('step_window_custom_raw') or {}
+            p['NP Step Window Custom'] = serialize_per_strategy_windows(raw)
+    return p
+
+
+class TestGenerationParamsRoundTrip(unittest.TestCase):
+
+    def setUp(self):
+        self._state = {
+            'enabled':      global_state.step_window_enabled,
+            'global':       global_state.step_window_global,
+            'use_defaults': global_state.step_window_use_defaults,
+            'per_strategy': global_state.step_window_per_strategy,
+        }
+
+    def tearDown(self):
+        global_state.step_window_enabled      = self._state['enabled']
+        global_state.step_window_global       = self._state['global']
+        global_state.step_window_use_defaults = self._state['use_defaults']
+        global_state.step_window_per_strategy = self._state['per_strategy']
+
+    # -- global mode round-trip --
+
+    def test_global_extra_params_present_when_enabled(self):
+        args = _unpack(step_window_enabled=True, step_window_mode='global',
+                       step_window_start=0.25, step_window_end=0.80)
+        p = _extra(args)
+        self.assertTrue(p['NP Step Window Enabled'])
+        self.assertEqual(p['NP Step Window Mode'], 'global')
+        self.assertAlmostEqual(p['NP Step Window Start'], 0.25, places=4)
+        self.assertAlmostEqual(p['NP Step Window End'],   0.80, places=4)
+
+    def test_global_extra_params_absent_when_disabled(self):
+        args = _unpack(step_window_enabled=False)
+        p = _extra(args)
+        self.assertNotIn('NP Step Window Enabled', p)
+
+    def test_global_apply_infotext_restores_state(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'global',
+            'NP Step Window Start':   '0.3',
+            'NP Step Window End':     '0.7',
+        })
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertIsNotNone(global_state.step_window_global)
+        self.assertAlmostEqual(global_state.step_window_global.start, 0.3, places=4)
+        self.assertAlmostEqual(global_state.step_window_global.end,   0.7, places=4)
+
+    def test_inverted_range_repaired_in_unpack(self):
+        args = _unpack(step_window_enabled=True, step_window_mode='global',
+                       step_window_start=0.9, step_window_end=0.1)
+        self.assertAlmostEqual(args['step_window_start'], 0.0)
+        self.assertAlmostEqual(args['step_window_end'],   1.0)
+
+    def test_inverted_range_repaired_in_apply_infotext(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'global',
+            'NP Step Window Start':   '0.9',
+            'NP Step Window End':     '0.1',
+        })
+        win = global_state.step_window_global
+        self.assertAlmostEqual(win.start, 0.0)
+        self.assertAlmostEqual(win.end,   1.0)
+
+    def test_old_infotext_without_step_window_keys_safe(self):
+        global_state.apply_infotext({'CFG Rescale phi': '0.5', 'NP Protection Mode': 'auto'})
+        # No exception — step-window state unchanged
+
+    def test_defaults_mode_apply_infotext(self):
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'per-strategy defaults',
+        })
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertTrue(global_state.step_window_use_defaults)
+        self.assertIsNone(global_state.step_window_global)
+
+
+# ===========================================================================
+# 4. Per-strategy custom window helpers
+# ===========================================================================
+
+class TestPerStrategyHelpers(unittest.TestCase):
+
+    def test_ui_key_to_family_all_keys(self):
+        mapping = {
+            'AND_PERP':       'PERPENDICULAR',
+            'AND_SALT':       'SALIENCE_MASK',
+            'AND_SALT_WIDE':  'SALIENCE_MASK_WIDE',
+            'AND_SALT_BLOB':  'SALIENCE_MASK_BLOB',
+            'AND_TOPK':       'SEMANTIC_GUIDANCE',
+            'AND_ALIGN':      'ALIGNMENT_BLEND_CUSTOM',
+            'AND_MASK_ALIGN': 'ALIGNMENT_MASK_BLEND_CUSTOM',
+        }
+        for ui_key, expected_family in mapping.items():
+            with self.subTest(ui_key=ui_key):
+                self.assertEqual(ui_key_to_family(ui_key), expected_family)
+
+    def test_build_per_strategy_windows_types(self):
+        raw = {'AND_SALT': (0.4, 1.0), 'AND_PERP': (0.0, 0.5)}
+        result = build_per_strategy_windows(raw)
+        self.assertIsInstance(result['SALIENCE_MASK'], StepWindow)
+        self.assertAlmostEqual(result['SALIENCE_MASK'].start, 0.4)
+        self.assertAlmostEqual(result['PERPENDICULAR'].end,   0.5)
+
+    def test_build_per_strategy_windows_repairs_inverted(self):
+        raw = {'AND_SALT': (0.9, 0.1)}   # inverted
+        result = build_per_strategy_windows(raw)
+        win = result['SALIENCE_MASK']
+        self.assertAlmostEqual(win.start, 0.0)
+        self.assertAlmostEqual(win.end,   1.0)
+
+    def test_unknown_ui_key_skipped(self):
+        raw = {'AND_MYSTERY': (0.2, 0.8)}
+        result = build_per_strategy_windows(raw)
+        self.assertEqual(len(result), 0)
+
+    def test_serialize_round_trip(self):
+        raw = {'AND_PERP': (0.0, 0.5), 'AND_SALT': (0.4, 1.0)}
+        serialized = serialize_per_strategy_windows(raw)
+        restored   = deserialize_per_strategy_windows(serialized)
+        for ui_key in raw:
+            self.assertIn(ui_key, restored)
+            self.assertAlmostEqual(restored[ui_key][0], raw[ui_key][0], places=3)
+            self.assertAlmostEqual(restored[ui_key][1], raw[ui_key][1], places=3)
+
+    def test_deserialize_tolerates_garbage(self):
+        restored = deserialize_per_strategy_windows('bad:data,AND_SALT:0.40-1.00,junk')
+        self.assertIn('AND_SALT', restored)
+        self.assertAlmostEqual(restored['AND_SALT'][0], 0.4, places=2)
+
+    def test_deserialize_empty_string(self):
+        self.assertEqual(deserialize_per_strategy_windows(''), {})
+
+    def test_normalize_step_range_clamps(self):
+        s, e = normalize_step_range(-0.5, 1.5)
+        self.assertAlmostEqual(s, 0.0)
+        self.assertAlmostEqual(e, 1.0)
+
+    def test_normalize_step_range_swaps_inverted(self):
+        s, e = normalize_step_range(0.8, 0.2)
+        self.assertAlmostEqual(s, 0.0)
+        self.assertAlmostEqual(e, 1.0)
+
+    def test_default_custom_windows_covers_all_keys(self):
+        defaults = default_custom_windows()
+        for uk in STRATEGY_UI_KEYS:
+            self.assertIn(uk, defaults)
+            s, e = defaults[uk]
+            self.assertGreaterEqual(s, 0.0)
+            self.assertLessEqual(e,   1.0)
+            self.assertLessEqual(s,   e)
+
+    def test_strategy_is_active_custom_window_overrides_defaults(self):
+        """Custom window for AND_SALT: 0.0–0.3 should gate it out at step 8/10."""
+        raw = {'AND_SALT': (0.0, 0.3)}
+        per_strategy = build_per_strategy_windows(raw)
+        progress = normalize_progress(8, 10)
+        active = strategy_is_active('SALIENCE_MASK', progress,
+                                    per_strategy_windows=per_strategy,
+                                    use_defaults=True)
+        self.assertFalse(active)
+
+    def test_strategy_is_active_fallback_to_defaults_when_key_missing(self):
+        """If AND_TOPK not in custom dict, fall back to STRATEGY_DEFAULTS."""
+        raw = {'AND_SALT': (0.0, 0.3)}   # only SALT defined
+        per_strategy = build_per_strategy_windows(raw)
+        # SEMANTIC_GUIDANCE default: 0.4–1.0 → active at step 8/10
+        progress = normalize_progress(8, 10)
+        active = strategy_is_active('SEMANTIC_GUIDANCE', progress,
+                                    per_strategy_windows=per_strategy,
+                                    use_defaults=True)
+        self.assertTrue(active)
+
+
+# ===========================================================================
+# 5. Per-strategy custom round-trip via infotext
+# ===========================================================================
+
+class TestPerStrategyRoundTrip(unittest.TestCase):
+
+    def setUp(self):
+        self._state = {
+            'enabled':      global_state.step_window_enabled,
+            'use_defaults': global_state.step_window_use_defaults,
+            'per_strategy': global_state.step_window_per_strategy,
+            'custom_raw':   global_state.step_window_custom_raw,
+        }
+
+    def tearDown(self):
+        global_state.step_window_enabled      = self._state['enabled']
+        global_state.step_window_use_defaults = self._state['use_defaults']
+        global_state.step_window_per_strategy = self._state['per_strategy']
+        global_state.step_window_custom_raw   = self._state['custom_raw']
+
+    def test_custom_mode_extra_params_has_custom_key(self):
+        raw  = {'AND_PERP': (0.0, 0.4), 'AND_SALT': (0.5, 1.0)}
+        args = _unpack(step_window_enabled=True, step_window_mode='per-strategy custom',
+                       **{f'{k}_start': v[0] for k, v in raw.items()},
+                       **{f'{k}_end':   v[1] for k, v in raw.items()})
+        params = _extra(args)
+        self.assertIn('NP Step Window Custom', params)
+        self.assertIn('AND_PERP', params['NP Step Window Custom'])
+        self.assertIn('AND_SALT', params['NP Step Window Custom'])
+
+    def test_custom_mode_infotext_restore(self):
+        raw_str = serialize_per_strategy_windows(
+            {'AND_PERP': (0.0, 0.4), 'AND_SALT': (0.5, 1.0)}
+        )
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'per-strategy custom',
+            'NP Step Window Custom':  raw_str,
+        })
+        self.assertTrue(global_state.step_window_enabled)
+        self.assertIsNotNone(global_state.step_window_per_strategy)
+        self.assertIn('PERPENDICULAR', global_state.step_window_per_strategy)
+        self.assertIn('SALIENCE_MASK', global_state.step_window_per_strategy)
+        perp_win = global_state.step_window_per_strategy['PERPENDICULAR']
+        self.assertAlmostEqual(perp_win.start, 0.0, places=3)
+        self.assertAlmostEqual(perp_win.end,   0.4, places=3)
+
+    def test_custom_mode_restored_state_gates_correctly(self):
+        """After restore, strategy_is_active uses the per-strategy windows."""
+        raw_str = serialize_per_strategy_windows({'AND_PERP': (0.0, 0.2)})
+        global_state.apply_infotext({
+            'NP Step Window Enabled': 'True',
+            'NP Step Window Mode':    'per-strategy custom',
+            'NP Step Window Custom':  raw_str,
+        })
+        per_strategy = global_state.step_window_per_strategy
+        # AND_PERP window 0.0–0.2 → inactive at step 5/10 (progress=0.56)
+        progress = normalize_progress(5, 10)
+        self.assertFalse(
+            strategy_is_active('PERPENDICULAR', progress,
+                               per_strategy_windows=per_strategy)
+        )
+
+    def test_full_round_trip_all_strategies(self):
+        raw = default_custom_windows()
+        serialized = serialize_per_strategy_windows(raw)
+        restored   = deserialize_per_strategy_windows(serialized)
+        # Every key present
+        for uk in STRATEGY_UI_KEYS:
+            self.assertIn(uk, restored)
+        # Values match to 3 decimal places
+        for uk in STRATEGY_UI_KEYS:
+            self.assertAlmostEqual(restored[uk][0], raw[uk][0], places=3)
+            self.assertAlmostEqual(restored[uk][1], raw[uk][1], places=3)
+
+
+if __name__ == '__main__':
+    unittest.main()