chore(release): 2.20.0 [skip ci]

Release: merge dev into main

.github/workflows/tag-list.yml

@@ -0,0 +1,101 @@
+name: Build tag list
+
+# MANUAL ONLY, and deliberately so.
+#
+# The list is not tied to our release cycle — it describes Danbooru, not this
+# project — and it goes stale slowly. Verified 2026-08-06: a roughly two-year-old
+# tag file still autocompletes correctly, because staleness moves post counts
+# (and therefore ranking) while tag NAMES barely change. There is no correctness
+# argument for a schedule, only a ranking one, and that does not justify a timer
+# pointed at someone else's API.
+#
+# So: run it when you want a refresh — a new character tag everyone is asking
+# for, or once in a while out of tidiness. The asset stays put until then.
+#
+# It publishes to a FIXED tag, replacing the asset in place, so the download URL
+# never changes:
+#
+#   https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/releases/download/tag-list/wildcard-pipeline-tags.csv
+#
+# That stability is the point: the SPA's "download tag list" button hardcodes
+# that URL and never needs updating. A per-run tag would break it every time.
+#
+# The tag is intentionally not semver, so semantic-release ignores it and this
+# never looks like a product release.
+on:
+  workflow_dispatch:
+    inputs:
+      min_count:
+        description: "Stop once tags drop below this many posts. 20 ≈ 150k tags; 68 ≈ the 100k other extensions ship."
+        required: true
+        default: "20"
+        type: string
+      alias_pages:
+        description: "Pages of aliases to fetch (1000 each). Aliases are what make `hires` find `highres`."
+        required: true
+        default: "60"
+        type: string
+      publish:
+        description: "Attach the result to the tag-list release. Off = build it and keep it as a run artifact only."
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # No dependencies on purpose: the builder uses urllib from the standard
+      # library, so there is nothing to install and nothing to keep patched.
+      - name: Build
+        run: |
+          python scripts/build_tag_list.py \
+            --min-count "${{ inputs.min_count }}" \
+            --alias-pages "${{ inputs.alias_pages }}" \
+            --out wildcard-pipeline-tags.csv
+
+      - name: Summarise
+        run: |
+          {
+            echo "### Tag list built"
+            echo
+            echo "| | |"
+            echo "|---|---|"
+            echo "| Tags | $(wc -l < wildcard-pipeline-tags.csv) |"
+            echo "| Size | $(du -h wildcard-pipeline-tags.csv | cut -f1) |"
+            echo "| Floor | ${{ inputs.min_count }} posts |"
+            echo "| Published | ${{ inputs.publish }} |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Always kept, so a build can be inspected before it replaces the asset
+      # everyone downloads.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wildcard-pipeline-tags
+          path: wildcard-pipeline-tags.csv
+          retention-days: 14
+
+      - name: Publish to the fixed tag-list release
+        if: ${{ inputs.publish }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          # `--clobber` replaces the asset in place, which is what keeps the
+          # download URL stable across refreshes.
+          if gh release view tag-list >/dev/null 2>&1; then
+            gh release upload tag-list wildcard-pipeline-tags.csv --clobber
+          else
+            gh release create tag-list wildcard-pipeline-tags.csv \
+              --title "Booru tag list" \
+              --notes "Autocomplete data for ComfyUI-Wildcard-Pipeline. Rebuilt on demand; not a product release. Download it from the manager's Settings page rather than by hand." \
+              --latest=false
+          fi

.gitignore

@@ -52,6 +52,8 @@ Thumbs.db
 /docs/*
 !/docs/help/
 !/docs/import-export-contract.md
+# Network behaviour + download hardening, linked from the README
+!/docs/network-access.md
 # Curated release highlights — read by .releaserc.js at release time, so it
 # must be tracked (the release step commits the cleared file back).
 !/docs/release-notes/
@@ -61,8 +63,16 @@ Thumbs.db
 
 # Throwaway design / scratch artifacts (mockups, screenshots, demos)
 /_temp/
+# Root-level PNGs are always scratch QA screenshots here — legit images live
+# under public/. Anchored so it never touches public/images/**. Keeps stray
+# captures out of git and out of pack-release's ship-list gate.
+/*.png
 
 # DB location control — per-contributor sidecar config + root-location DB dir
 db-config.json
+wp-settings.json
 /db/
 .tmp-check/
+
+# Playwright MCP session artifacts (page snapshots, console logs).
+.playwright-mcp/

.releaserc.js

@@ -119,7 +119,11 @@ export default {
       "@semantic-release/exec",
       {
         // 1. Stamp version into package.json + pyproject.toml.
-        // 2. Pack the deployable file set into a zip so the
+        // 2. Rebuild js/ + web/ so the bundle's baked-in version matches the
+        //    stamped pyproject.toml. The server reports that version and the
+        //    canvas + manager ask for a reload while the two differ, so a zip
+        //    packed from the pre-stamp build would nag on every page load.
+        //    Pack the deployable file set into a zip so the
         //    @semantic-release/github plugin can attach it to the
         //    release. Zip is built AFTER versioning so the file lands
         //    with the right version in its name.
@@ -127,7 +131,7 @@ export default {
         //    from a clean slate (the content already lives in this release's
         //    notes + CHANGELOG.md).
         prepareCmd:
-          "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json'));p.version='${nextRelease.version}';fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n');const t=fs.readFileSync('pyproject.toml','utf8').replace(/^version = \\\".+?\\\"/m,'version = \\\"${nextRelease.version}\\\"');fs.writeFileSync('pyproject.toml',t);\" && node -e \"require('fs').writeFileSync('docs/release-notes/next.md','')\" && node scripts/pack-release.mjs ${nextRelease.version}",
+          "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json'));p.version='${nextRelease.version}';fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n');const t=fs.readFileSync('pyproject.toml','utf8').replace(/^version = \\\".+?\\\"/m,'version = \\\"${nextRelease.version}\\\"');fs.writeFileSync('pyproject.toml',t);\" && node -e \"require('fs').writeFileSync('docs/release-notes/next.md','')\" && pnpm build && node scripts/pack-release.mjs ${nextRelease.version}",
       },
     ],
     [

CHANGELOG.md

@@ -1,3 +1,292 @@
+## 🎉 Wildcard Pipeline 2.20.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Features
+
+- **Pick which images go on to the upscaler with WP Image Filter.** Put the new node between your first KSampler and the upscaler. When a run reaches it, a picker opens with every image (grouped by frame when a Context Loop made them). Click the ones you want, click the frame around an image (or **Zoom & refine**, or **Space**) to look closer, and **Enter** to send them on. Only the picked images continue, and their latent, masks, positive and negative conditioning, prompt texts and Context come along with them, so the upscaler gets each image's own prompt. Two **extra** slots carry anything else that should follow the picks. **Keep all** lets everything through and **Stop branch** stops what comes after the node without failing the run. On the node you choose whether it pauses every run, reuses your last picks, or lets everything pass, a timeout, and whether picks keep their batches or go on one image per item. The picker can be tucked away to look at the canvas and keeps your picks until you open it again. While it waits, a short chime plays and the tab title starts with **● Pick images**, so you notice from another tab (new settings: **Image Filter sound**, on by default, and **Image Filter desktop notification**, off by default). No schema change.
+- **Refine your picks before they reach the upscaler.** In the Image Filter zoom, a **Refine** panel lets you edit the frame's positive and negative prompt and paint a mask on the image. An edited prompt replaces the text output, and with a CLIP wired into the node's new optional **clip** input the conditioning is re-encoded to match. A painted mask goes to the **masks** output, so an inpainting upscaler can work on just that area.
+- **The Image Filter picker knows your Context Loop.** Frames are labelled with the options your sweep pinned (hover for the seed and prompt), a sweep opens as a grid where you choose which wildcards go on rows and columns and the rest split into small grids (click a row, column or group name to pick all of it), **C** compares two images with a slider, **Fit** (**F**) makes a few images fill the picker, **I** adds a Details panel to the zoom (the frame's values, its other images, and each value marked in the prompt), and the picker opens zoomed if you left it zoomed. **Send to Loop** writes your picks back to the loop, locking the kept frames' seeds and bypassing the rest, so the next run repeats only what you liked.
+
+### Fixes
+
+- **Sweep combinations can clear a wildcard's options in one click.** Next to **all** and **enabled only** there is now **none**, so you can untick everything and pick just the few options you want instead of unticking them one by one. A wildcard with nothing ticked sweeps nothing until you tick one.
+- **Editing a loop frame goes back to base when that frame goes away.** With frame #5 picked under **edit frame**, lowering the count below 5 or changing the sweep left you editing a frame that no longer existed (or now meant a different combination). It now switches back to **base**.
+- **Frame locks and bypasses no longer come back on the wrong frame.** Lowering a Context Loop's count used to keep the seed locks and bypasses of the frames past it, and raising the count again brought them back. Now they are dropped. Changing a sweep moves each lock and bypass with its combination, or drops it when that combination no longer runs.
+- **The loop's count is locked while a sweep is on.** The sweep decides how many frames run, so the count field now greys out and shows the sweep's frame count instead of looking editable.
+
+
+
+---
+
+**Full changelog:** [v2.19.0…v2.20.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.19.0...v2.20.0)
+
+## 🎉 Wildcard Pipeline 2.19.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Features
+
+- **Make your pipeline react to the loaded checkpoint with WP Model Info.** Put the new node first in the chain and wire your checkpoint's MODEL into it. It writes `$model_family` (sdxl, flux, sd15, …, read from the model), `$model_variant` (pony, illustrious, noobai or animagine, read from the file name by rules you can edit on the node) and `$model_name` (each can be pinned to a value of your own, and they stay out of the Assembler unless you switch them on), so derivations can branch on the model you loaded. The derivation editor's new **LoRA by model** button adds a ready-made rule that sets `$loras` per variant. To drive a constraint from the model, set the new **Match variable** option on a wildcard (in its node settings, under Runtime): it picks the option whose text equals a variable instead of rolling, so a "Model" wildcard with pony and illustrious options becomes a normal constraint source. No schema change, so shared modules work on older versions too.
+- **Bring your A1111 and Forge wildcards along with the new Wildcard packs tab.** On **Import / Export → Wildcard packs**, choose a folder, files or a `.zip` (or drop them; a pack dropped on the Import tab lands here too). Dynamic Prompts, PPP and Impact Pack `.txt`, `.yaml` and `.json` wildcards are named by path the way `__animals/cats__` finds it, and a folder of related lists merges into one wildcard tagged by list, like one you'd build by hand: `hair/colors/red.txt`, `blonde.txt` and `dark.txt` become one `hair/colors` wildcard with the tags red, blonde and dark, and each folder level becomes a tag group. Billions of Wildcards goes from 2,653 lists to 935 wildcards this way. A reference to a merged list becomes a tag filter on the merged wildcard, so it still draws from that list, and any merged row can be split back into separate lists with one click. Before anything is imported you review the plan: every wildcard is sorted by role (entry point, composition, vocabulary, group) and marked Exact, Close or Needs a look, by domain, with the reason one click away. `__references__` (globs included) turn into `@{}` links, `__2$$name__` picks two different values like it did before, a line written twice keeps its double weight, and weights, PPP labels and `else` choices carry over as weights, sub-categories and the fallback. Only the entry points go into bundles (one per domain inside a pack bundle), so dropping a bundle rolls the prompts the pack was written for while the lists stay in the library. Each wildcard gets a category per domain and a library tag for the whole pack, `#` comments become its description, and importing the same pack again finds what you already have instead of adding copies.
+- **Compare options side by side with Sweep combinations on the Context Loop.** Open **Sweep combinations** on the loop node, pick wildcards from the Contexts after it and tick the options you want, and one Generate runs every combination, one frame each: three hair colours against three moods makes nine prompts in grid order. The menu shows the total and lists every frame before you run, and **Hold other picks** keeps everything you didn't sweep the same across frames, so only what you swept changes. A limit (64 by default) caps big sweeps.
+- **Give a wildcard a fallback for when constraints rule everything out.** Hover an option's probability in the wildcard editor and click **set as fallback**. That option still rolls normally with its weight, and it's also used whenever nothing else is left to pick, so a hair wildcard whose constraints exclude every colour can say "loose hair" instead of nothing, without a duplicate option. It also kicks in when every weight is 0. Give it weight 0 if it should only ever stand in. One fallback per wildcard, it works for nested `@{}` picks too, and WP Debug and the Test Runner note "Fallback used" where it took over. Untick it on a node to keep the empty result there. Shared wildcards with a fallback are stamped schema 9, so older versions refuse them and ask for an update.
+- **Choose whether the Community tab shares anonymous usage stats.** The Community tab now tells the community site which pages are opened and when packs are installed, published or signed in to, so we can see what's used. It sets no cookies and sends no account details. Turn it off under **Settings → General → Privacy**. It's also off when your browser sends Do Not Track.
+- **Tidy prompt syntax with three new Prompt Cleaner rules.** **Empty groups** removes leftovers like `()`, `[]` and `(:1.2)`, which you get when a weighted `@{}` ref resolves to nothing. **Merge weights** folds stacked weights into one, the way ComfyUI multiplies them: `((a:1.1):1.2)` becomes `(a:1.32)`, and `(a:1.0)` becomes plain `a`. **LoRA spacing** turns `< lora : x : 0.8 >` into `<lora:x:0.8>` and puts a space between a LoRA tag and a word it touches. The Balanced preset (the default) now turns on empty groups and LoRA spacing, so existing Cleaners on Balanced tidy these on the next run. Merge weights is on in Aggressive. Each rule has its own row, so you can turn it off per node.
+- **See which constraints can leave a wildcard empty before you run.** When some value of a constraint's source rules out every option of its target (all excluded, shut out by an Only rule, or weighted 0) and the target has no fallback, the constraint row on the canvas now shows a **rules out all** badge. Hover it to see which source values do it, then allow an option for them or give the target a fallback.
+
+### Fixes
+
+- **Update Now works with the Manager built into ComfyUI.** It only knew the older ComfyUI-Manager custom node, so with the built-in Manager it fell back to "update manually", and the Restart button in Settings was missing. After **Restart ComfyUI** the page now waits for ComfyUI to come back and reloads itself, so it never keeps showing the old version. If ComfyUI comes back still on the old version, the dialog says the update didn't apply instead of claiming success.
+- **Bypassed and muted Assemblers and Prompt Cleaners now dim their text boxes too.** The prompt and negative boxes used to stay bright while the rest of the node dimmed.
+- **The Sweep Limit field no longer hides its number under the arrows.** It now has the same small up/down arrows as the seed fields.
+- **Importing modules together with their categories now works.** A JSON import that brought in a new category along with the modules filed under it could fail with "database integrity violation". Modules whose category merges into one you already have by name now land in that category.
+- **Import / Export sees your whole library.** With more than 1000 modules, the Export list and the Import duplicate check only looked at the first 1000, so re-importing a big pack showed everything past that as changed.
+- **The All items list shows your whole library.** It stopped at the first 1000 modules and 1000 bundles, so after importing a big wildcard pack the rest never showed up there.
+
+
+
+---
+
+**Full changelog:** [v2.18.0…v2.19.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.18.0...v2.19.0)
+
+## 🎉 Wildcard Pipeline 2.18.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Features
+
+- **Send words to the negative prompt from the pick that needs them.** Wildcard options and fixed values get an optional Negative line under their value, combines get one Negative for the whole phrase, and derivations get a fourth action, **Add to negative**. Pick "strawberry blonde" hair and "strawberry, fruit" lands in the negative. The WP Prompt Assembler has a new `negative` output and a negative template where `$negatives` marks the spot. Negatives follow usage: an Assembler only collects the words of variables its template rendered, so a face detailer never gets the hair negatives, and repeated tags are dropped. Negatives never change your picks. Context Injector rows can carry a negative, the Prompt Cleaner cleans a negative next to the prompt with its own rule column, bulk add takes `value #tag *N -- negative` (or `name = value -- negative` for fixed values), and WP Debug and the Test Runner show where each word came from. Shared modules that use a negative are stamped schema 8, so older versions refuse them and ask for an update. The docs have a new Negatives page.
+
+- **A derivation branch can do several things.** Click **+ And** under a branch's action to add another one, so a single rule can read "if tier = warmup then $pose replace $pose_portrait AND add `extra arms` to $pose's negative". The actions run in order, and each one sees what the one before it wrote. On the canvas, a branch with several actions shows them all in its summary and gets one value override per action, and WP Debug lists every action a branch ran. Shared derivations that use this are stamped schema 8.
+- **Reach a variable's negatives with `$name.neg`.** `$pose.neg` is the negative words `$pose` carries right now, and `$props.1.neg` is only pick 1's. Use it anywhere `$vars` work: in an "Add to negative" action to hand one variable's negatives to another, in a combine, in the Assembler's negative template, or in a condition (`$hair.neg contains blonde`). Reading `.neg` never counts as using the variable, so its words aren't collected twice. Autocomplete offers `.neg` after the dot, and it shows in red. Because of this, an accepts tag group can't be called `neg`.
+- **Replace a variable's negative, not just add to it.** Derivations have a fifth action, **Replace negative**. It drops the negative words a variable carries and uses the action's text instead, still without touching the variable's own text. Shared derivations that use it are stamped schema 8.
+- **A roomier Rules section on the canvas.** A derivation's node modal now shows each IF, ELIF and ELSE as its own card. Every test and every action gets its own row with a full-width field, so long values wrap instead of being squeezed into a table column. AND / OR groups read as indented rows under an "ANY of" / "ALL of" header. An empty field shows the library value (chips included) until you type, and an overridden field lights up with the library value underneath and a **Use library** link to undo it.
+
+- **Derivation branches can combine tests with AND / OR.** Click **+ Condition** under a test to add another, and click a connector to switch it between AND (all must match) and OR (any may match). Each connector flips on its own, with AND binding tighter than OR, so "a AND b OR c" reads as "(a AND b) OR c" and the AND part is shown boxed. **+ Group** nests a boxed list with the opposite connector, so a branch can read "night AND (rain OR fog)". On the canvas, a grouped branch shows the whole expression and gets one value override per test. Shared derivations that use this are stamped schema 7, so older versions refuse them and ask for an update instead of failing mid-run.
+
+- **Placeholders for modules you haven't built yet.** Type `@` and a name nothing in the library has, and the last row of the list offers **Placeholder @name**. It inserts a red chip under that name, which you later click to point at the real module. No more hand-typing `@{…#name}`.
+- **Broken references are marked where they are.** A field holding a red chip gets a red outline, and its row gets marked too: a wildcard option (in the library editor and on the canvas) or a derivation branch and its rule. Before, only the list view's warning triangle said something was wrong.
+
+- **Test Runner baselines: see what an edit changed.** Run a saved scenario, open the new **Compare** tab and choose **Save as baseline**. After you edit a module, run the scenario again and Compare lists every seed whose output changed, with the removed and added words highlighted, plus any variable values and warnings that appeared or went away. Seeds are deterministic, so for an unchanged stack every seed matches, and a real change never gets lost among random ones. A scenario on random seeds can rerun the baseline's own seeds in one click.
+- **Re-run all pinned scenarios at once.** **Re-run all** next to the Pinned heading in the Test Runner runs every pinned scenario as saved. Each one's badge then says whether it still **matches** its baseline or how many outputs **changed**.
+- **See which scenarios use a module.** The wildcard and derivation editors show **In N scenarios** beside the Test Runner button. It opens the Test Runner with the list narrowed to those scenarios.
+- **Inspect any module in a Test Runner scenario.** Click a stack card to see how that module is set up next to what the last run did with it. A wildcard shows each option's share of the weight beside how often it was actually picked, and flags options that never came up. A constraint shows what it links, how far it reaches and how many times it applied. Combines, derivations, fixed values and bundles each get their own view, and **Edit** opens the module's editor.
+- **Test Runner guide in the docs.** Documentation now has a Test Runner page covering scenarios, reading a run, the inspector and baselines.
+- **Tags work as collections.** A module, bundle or template can carry several tags, and now they have a home. The new **Tags** page (under Library in the sidebar) lists every tag with how many items carry it, opens a tag as a filtered list, and renames, merges or deletes one across the whole library in one step. With two or more tags in a list filter, switch between **Any tag** and **All tags**.
+
+- **WP Debug explains the run.** The Debug node now has four tabs. **Variables** lists every value with the step that set it. **Trace** groups the steps by Context node, and each step opens to say why it did what it did: which derivation branch fired and the actual value behind every condition, a wildcard's odds and the constraints that re-weighted it, how far a constraint reached, and where a nested `@` pick came from. **Warnings** gives every warning a plain label and links it to its step, and **Raw** keeps the JSON. Derivation rules fold one at a time, and a step can jump to its node on the canvas.
+
+### Fixes
+
+- **Turning off one fixed value no longer turns off the rest.** Fixed values whose rows had no ids (common in imported packs) switched on and off together on the canvas. Each row now toggles on its own, both in the editor and when the workflow runs.
+- **Read-only previews keep a variable's accessor.** Rule summaries on the canvas, the debug view and other previews showed `$outfit.SHOES` as plain `$outfit`. They now show the whole reference.
+- **Wildcard icons stay purple on the canvas.** Opening a modal or adding certain nodes could repaint every wildcard's icon grey until the page was reloaded.
+
+- **WP Debug shows a cut-off value in full when you open its step.** A trace row fits its value on one line, and opening the step only repeated it in full when it was over 60 characters, so a shorter value cut off by a narrow node stayed cut off. Opening the step now shows any value the row had to cut.
+- **WP Debug's "show node" works again.** It did nothing in workflows whose node ids are text (like `wpctx`) rather than numbers, and for nodes in a subgraph (or back at the root while you were inside one). It now finds the node, opens its graph if needed, then selects and centres it. Trace headers now name a Context node by its codename (the `navy-dove` shown on the node), with its title and graph id in the tooltip.
+- **The Context node warns about broken refs in a derivation's canvas overrides.** A ref typed into a value override on the canvas was never checked, so pointing it at a deleted module (or leaving a placeholder there) showed no warning on the node.
+- **Reopening a derivation no longer changes its presence checks.** The editor rewrote every "exists", "does not exist", "is set" and "is unset" condition to "equals" when you opened a saved derivation, so saving it again changed what it did.
+- **"Exists → is empty" conditions run.** The editor offered it, but the engine rejected the op and the whole derivation failed. The engine now supports `is_empty` and `is_not_empty`.
+- **Test Runner in the light theme.** The closed trace drawer no longer casts a dark shadow down the right edge of the page, and the drawer and module picker shadows now follow the theme.
+- **Long Context chains no longer slow the canvas down.** Every Context node used to re-work its whole upstream chain several times a second, so the cost grew with the square of the chain's length. Nodes now reuse the last result until something upstream actually changes. On a 16-node chain, a round of refreshes went from about 28 ms to under 1 ms.
+- **A reference that resolves to nothing no longer leaves a gap.** A placeholder or deleted module, a filter that matches no option, or an empty option used to leave a double space or a stray comma behind, so `red, @missing, dress` came out as `red, , dress`. It now comes out as `red, dress`, in the run and in the editor previews.
+
+
+
+---
+
+**Full changelog:** [v2.17.2…v2.18.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.17.2...v2.18.0)
+
+## 🎉 Wildcard Pipeline 2.17.2
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **Faster startup.** Opening ComfyUI used to download 43 of the extension's files before the canvas finished loading, even with no Wildcard Pipeline node on it. It now downloads 2 (166 KB → 92 KB gzipped). The toast stack, the Display playground, the template editor and the subgraph conflict badge now load the first time you use them.
+
+
+
+---
+
+**Full changelog:** [v2.17.1…v2.17.2](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.17.1...v2.17.2)
+
+## 🎉 Wildcard Pipeline 2.17.1
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **What's new shows the release you are running.** After an update, the page could keep showing the notes of an older release for a few hours ("Release notes for v2.15.3 — you are running v2.17.0"), because it trusted a release check cached before the update. It now headlines the newest release it knows about, and a cached check older than your version is fetched again.
+
+
+
+---
+
+**Full changelog:** [v2.17.0…v2.17.1](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.17.0...v2.17.1)
+
+## 🎉 Wildcard Pipeline 2.17.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+
+
+---
+
+**Full changelog:** [v2.16.0…v2.17.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.16.0...v2.17.0)
+
+## 🎉 Wildcard Pipeline 2.16.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Features
+
+- **Link one wildcard's pick to another's with the new Only rule.** A constraint rule set to **Only** turns its row into a short list. An exception *maid → frilled apron* in Only mode means that whenever the source rolls "maid", the target can only roll "frilled apron", and an outfit you add to the target later is shut out too. Before, the same link needed an Exclude rule for every other outfit, and any outfit added afterwards slipped through. In the matrix, an Only cell links subcategories the same way, and the other cells in that row show a faint × so you can see what is shut out. Only is in the cell popover, the exceptions mode picker and the canvas instance editor. Constraints that use it publish as schema version 6, so an older extension refuses them and asks you to update instead of failing the constraint.
+
+### Fixes
+
+- **Setting a matrix cell back to Neutral on the canvas no longer breaks the constraint.** Overriding a library rule to Neutral in a Context node's constraint editor saved a value the engine didn't accept, so the whole constraint stopped applying when the graph ran. The editor now saves it correctly, and workflows saved with the old value run again.
+- **The constraint docs described Allow wrongly.** They said Allow keeps only the matching options. Allow has always meant "no change" (it shows as Neutral in the matrix). The docs now say so, and the keep-only behaviour they described is what Only does.
+
+
+
+---
+
+**Full changelog:** [v2.15.3…v2.16.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.15.3...v2.16.0)
+
+## 🎉 Wildcard Pipeline 2.15.3
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+New docs for chips, references and the filter grammar.
+
+### Highlights
+
+- **Docs: Chips & references.** A new page in the manager's Docs tab (How it connects → Chips & references) explains the chips you see in text fields and their three states (resolved, filtered, broken), how to make a placeholder `$var` chip before anything produces it, the full `@{uuid#name:filter!null}` reference form and why plain `@name` stays text, and the sub-category filter grammar: `not`, `and`, `or` (or a comma) and parentheses, e.g. `not warm and (low or high)`. Searching the docs for "chip" or "filter" now finds it.
+
+
+
+---
+
+**Full changelog:** [v2.15.2…v2.15.3](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.15.2...v2.15.3)
+
+## 🎉 Wildcard Pipeline 2.15.2
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **`$outfit.1.SHOES` now reads the second pick's shoe.** On a wildcard that picks several options, an indexed axis read skipped any pick whose option carries no tag on that axis, so every later index slid down by one: with `robe, jeans` picked, `$outfit.0.SHOES` printed the jeans' boots beside the robe and `$outfit.1.SHOES` came out empty. Each index now names the same pick as `$outfit.1`, in templates and in derivation conditions alike. The bare `$outfit.SHOES` read was already right and is unchanged.
+
+- **The Prompt Assembler preview shows the tag that was actually rolled.** The preview filled `$outfit.SHOES` with the first tag of the group whatever the option, so it could read `sandals | robe | red stilettos` for an outfit with no shoes and a pair of heels. It now reads the same roll as the values beside it, and matches what the prompt will say.
+
+
+
+---
+
+**Full changelog:** [v2.15.1…v2.15.2](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.15.1...v2.15.2)
+
+## 🎉 Wildcard Pipeline 2.15.1
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **Library file exports now record the schema version their content needs.** Exporting from the library always wrote schema version 2 into the file, even when it held range multi-picks like `{1-3$$…}`, constraints with a narrowed reach, or wildcards with an **accepts** tag axis. An older extension would then import the file and silently misread or drop those features. Exports now say 3, 4 or 5 when they use those features, so an older extension refuses the file and asks you to update. Files without them still export as version 2.
+
+
+
+---
+
+**Full changelog:** [v2.15.0…v2.15.1](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.15.0...v2.15.1)
+
+## 🎉 Wildcard Pipeline 2.15.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **Shared wildcards with accepts tag axes now say when your extension is too old for them.** A wildcard whose tag group is marked **accepts** is now published as schema version 5. Before, it went out as version 2, and an extension from before 2.14 installed it without complaint while quietly dropping the accepts setting, so `$outfit.SHOES` read empty and constraints lost the rolled tag. That older extension now refuses the pack and asks you to update. Wildcards without an accepts group publish exactly as before.
+
+- **Updating a community item no longer re-runs the old tag conversion on it.** "Update" and "Install as new entry" labelled every download as the oldest schema version, so each install ran the version 1 to 2 upgrade again over content that was already current. Downloads now keep the version the community recorded for them, and so do dependencies fetched from a constraint's "download missing" action.
+
+
+
+---
+
+**Full changelog:** [v2.14.1…v2.15.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.14.1...v2.15.0)
+
+## 🎉 Wildcard Pipeline 2.14.1
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+### Fixes
+
+- **Cutting an already-empty field no longer wipes your clipboard.** Cut an option's text, press Ctrl+A Ctrl+X again on the now-empty field, and the text you meant to paste was gone: the editor let the browser cut an invisible caret marker, which replaced what was on the clipboard. The second cut now leaves the clipboard alone, and a paste never writes that invisible character into a value.
+
+
+
+---
+
+**Full changelog:** [v2.14.0…v2.14.1](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.14.0...v2.14.1)
+
+## 🎉 Wildcard Pipeline 2.14.0
+
+📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)
+
+Read a wildcard's chosen tag as a variable, a much faster ComfyUI start, and a bulk-delete fix worth reading.
+
+### Highlights
+
+- **Tag groups can now be axes you read as variables.** Mark a wildcard's tag group **accepts** and it becomes an *axis*: the wildcard rolls exactly one of its tags each pick, and you can read that tag anywhere with **`$var.AXIS`**. An `$outfit` wildcard with an accepts group `SHOES` exposes **`$outfit.SHOES`** as the shoe it chose this run — the same value in every template, combine, derivation and chained node, because it is rolled once when the option is picked rather than each time it is read. Groups left **classify** (the default) behave exactly as before, so nothing already in your library changes.
+
+  Where it pays off is constraints. When an accepts axis is the **source** of a constraint, the rule keys on the single rolled tag rather than every tag the option happens to carry — so a diagonal "same tag wins" matrix pins the target to exactly what was rolled, and `$outfit.SHOES` and the shoe that gets picked agree every run. If the **target** is also an accepts axis, it stays in the pool when the source allows any of its alternatives and then rolls the matched one, so the two wildcards never disagree on the axis. The editor marks accepts groups in the constraint matrix, warns when an option carries none of its axis's tags, and offers a wildcard's axes in the `$` autocomplete.
+
+- **Optional booru tag autocomplete.** Turn it on in Settings → Tag autocomplete and typing a few letters into an option value suggests danbooru tags, ranked by how often they are actually used, colour-coded by kind (character, copyright, artist, meta) and resolving aliases — type `hires` and it offers `highres`, naming what it matched so the jump is never mysterious.
+
+  It stays out of the way of everything you already use: `$` variables and `@` references always win the caret, and suggestions never appear while you are typing one. Off unless you switch it on.
+
+  The tag list is a file you install once — press **Download** in Settings to fetch it from this project's GitHub release, or drop your own CSV at the path shown there. **This is the only thing this extension ever fetches from the internet**, it only happens when you press the button, and the [README](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline#network-access) documents exactly what that request does and the restrictions around it.
+
+- **This extension was making ComfyUI slow to load, and it will clean up after itself on the next start.** Our frontend files carry a content hash in their names, so every release produced new filenames — and ComfyUI Manager installs an update by writing the new files over the old ones without removing what the new version no longer ships. Nothing ever deleted the previous version's files, so they piled up with every update.
+
+  On a real install that had been updated a dozen times: **1,774 files taking 60 MB, where about 300 were live.** ComfyUI requests every JavaScript file an extension exposes when the page loads, so that install was fetching 237 of our chunks instead of 58 — nearly 10 MB, which was 42% of all extension code on that page and by a wide margin the largest single contributor to its load time.
+
+  This release records what each build produces and deletes anything left over from an older version when ComfyUI starts. **No action needed — the first start after updating does the cleanup**, and it is conservative: only files this project's build system generates are ever removed. On the install measured above it freed 52 MB and removed 1,579 files.
+
+- **Sourcemaps are no longer shipped.** They were being written on every build and included in the package, but never linked, so no browser had ever requested one — 22.5 MB of files that existed only to be ignored. Debug builds can still produce them.
+
+- **"Select all" now means the rows you can see.** With a filter active, the header checkbox selected *every* row, not the filtered ones — so narrowing a list down to a handful, selecting all and deleting removed the whole list, most of it never on screen and with no warning. This affected the **wildcard** and **fixed-values** editors, and on wildcards it reached bulk weight and tag changes too: setting a weight on a filtered selection silently rewrote every option's weight, with no change in row count to hint at it. Select-all is now scoped to what the filter is showing, in both directions. If you have ever lost options or had a weight distribution flattened, this was why.
+
+- **A constraint can no longer hold two rules for the same pair.** Adding the same source/target combination twice — say `rain → sandals` as both *exclude* and *boost ×3* — looked like two active rules, but only one ever applied: whichever came last in the list. Order decided the outcome, nothing showed you the order, and in the worst case a deliberate **exclude was silently thrown away** by a later duplicate. Saving or importing a constraint with a repeated pair is now refused, naming the pair so you know which one to remove. Existing constraints keep working exactly as before — nothing already in your library is rejected, and no generation changes.
+
+- **Constraint exceptions and derivation rules have a filter bar.** The wildcard and fixed-values editors got one previously; these two did not, which was backwards — an exception list is routinely longer than the wildcard it filters. Type to narrow the list, with a count and a clear button.
+
+  Rules keep their real numbers while filtered, so "Rule 5" stays Rule 5 instead of renumbering to 1, and editing or deleting a filtered row acts on that row rather than the one that happens to share its position.
+
+- **The library-change check stopped re-downloading your whole library every five seconds.** Both the manager and the in-graph Context node watch for library edits made elsewhere, by polling a list of module hashes. That list was re-sent in full on every tick with no caching headers — 33 KB every five seconds on a real library, roughly **24 MB an hour per open tab**, sitting idle. Producing it also re-read and re-parsed every module payload in the database each time.
+
+  The check now answers "nothing changed" with an empty response the browser already knows how to handle, and works that out from a cheap row count rather than by rebuilding the list. On a local install this was invisible; if you reach ComfyUI over Tailscale, a VPN or any metered connection, it was the largest thing this extension did.
+
+- **The webfonts are no longer bundled into JavaScript.** Both fonts were being base64-encoded into a code file that ComfyUI had to download and parse *before* it could finish registering this extension's nodes — about 90 KB of JavaScript that was never really JavaScript. They are now ordinary font files the browser fetches on its own, in the background, while everything else carries on. Node registration no longer waits for them.
+
+  Two things follow from that. Text appears sooner on a slow CPU, because 90 KB stopped going through the JavaScript parser. And the fonts now stay cached when you update — previously every release changed the code file they were hidden inside, so your browser re-downloaded them every time.
+
+  Total download on a fresh install is roughly unchanged: the encoding overhead and the compression that undid it cancel out. The gain is in *when* the work happens, not how much of it there is.
+
+<!-- /modal -->
+
+### Upgrade notes
+
+Nothing to do beyond updating. If the interface renders briefly in a system font on the first load after this update, that is the fonts arriving in the background as intended — it settles within a moment and does not recur.
+
+
+
+---
+
+**Full changelog:** [v2.13.2…v2.14.0](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/compare/v2.13.2...v2.14.0)
+
 ## 🎉 Wildcard Pipeline 2.13.2
 
 📖 [Docs (wiki)](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) · 💬 [Discord](https://discord.gg/BFYR9WQdVR) · 📦 [Install via ComfyUI Manager](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start) · 🐛 [Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)

CLAUDE.md

@@ -44,9 +44,14 @@ ruff check .           # Python lint
 - **Toast singleton** — one Vue app mounted to body-level div renders all toasts pushed via `src/components/shared/toast-store.ts`. Every Context node import same store so toasts surface from anywhere. Position mirror ComfyUI native PrimeVue toast anchor (rect-relative to `.graph-canvas-container`).
 - **Subgraph traversal** — `collectUpstreamVariables` / `collectUpstreamValues` / `findDownstreamAssemblers` cross subgraph boundaries via `-10` SubgraphInputNode + `-20` SubgraphOutputNode sentinel ids. Walkers expect `app.graph` (root); per-call `buildSubgraphParents` map handle step-out. Use `walkAllNodes(rootGraph)` for graph-wide scans (e.g. pre-run validation).
 - **Subgraph badges** — `extension/subgraph-badge.ts` attach `LGraphBadge` (via `window.LGraphBadge`) to any SubgraphNode containing WP nodes. Badge surface worst inner conflict severity with human label (e.g. `missing $foo`, `2 conflicts`). Wire via `nodeCreated` + `loadedGraphNode` hooks — `beforeRegisterNodeDef` does NOT fire for SubgraphNodes.
-- **Conflict scanner** — advisory only; never block execution. Runtime last-write-wins. Rule types: `shadows_upstream` (info), `duplicate_variable` (warning), `missing_template_variable` (warning), `constraint_source_missing` / `constraint_target_missing` (warning — uuid not in catalog), `constraint_orphan_source` (warning — no source instance UPSTREAM), `constraint_orphan_target` (warning — the constraint's reach selector covers ZERO reachable downstream instances; per-selector, NOT count-aware — overlapping constraints may freely share an instance). Engine emits runtime warnings `constraint_never_applied` (the reach matched nothing at runtime) and `constraint_partial_reach` (a `next N` / `pick` reach matched fewer instances than requested).
-- **Constraint reach (SP3)** — each constraint carries a `target_select` reach selector: `{mode: "first"|"next"|"all"|"pick", count?, picks?}`, default `all`. Every constraint whose reach covers a firing downstream target instance applies, COMBINED — per-pick × per-tag × per-constraint multiply, with `exclude` (factor 0) absorbing. No more one-shot/consumed-set: the engine counts per-constraint downstream hits in `ctx["__wp_constraint_hits__"]`. Reach is downstream-relative (counts from the constraint's own chain position) and cross-node + transitive (resolves `@{uuid}` at any depth). `pick` selects specific instances by `_uid` (direct top-level) or carrier `_uid` + option id (nested). The re-weight math is the pure `engine/modules/_constraint_math.py::combine_constraint_factor`, mirrored in TS at `src/manager/utils/constraint-math.ts` via the shared `tests/fixtures/constraint-corpus.json`. Published payloads using a non-default `target_select` stamp `schema_version = 4` (additive; community catalog v4).
-- **Bundle-size gate** — entry `main.js` must stay ≤ 30 KB gzipped; total `js/` ≤ 250 KB. Pre-commit run `pnpm build:extension && pnpm size`. Raising budget require explicit PR discussion.
+- **Conflict scanner** — advisory only; never block execution. Runtime last-write-wins. Rule types: `shadows_upstream` (info), `duplicate_variable` (warning), `missing_template_variable` (warning), `constraint_source_missing` / `constraint_target_missing` (warning — uuid not in catalog), `constraint_orphan_source` (warning — no source instance UPSTREAM), `constraint_orphan_target` (warning — the constraint's reach selector covers ZERO reachable downstream instances; per-selector, NOT count-aware — overlapping constraints may freely share an instance), `constraint_excludes_all` (warning — some source option leaves a covered target with no option of weight > 0 and no fallback; `extension/constraint-dead-ends.ts`, checks one constraint at a time and leans quiet when unsure). Engine emits runtime warnings `constraint_never_applied` (the reach matched nothing at runtime) and `constraint_partial_reach` (a `next N` / `pick` reach matched fewer instances than requested).
+- **Constraint reach (SP3)** — each constraint carries a `target_select` reach selector: `{mode: "first"|"next"|"all"|"pick", count?, picks?}`, default `all`. Every constraint whose reach covers a firing downstream target instance applies, COMBINED — per-pick × per-tag × per-constraint multiply, with `exclude` (factor 0) absorbing. Mode `only` (linked picks, schema v6) turns its row into an allow-list: when the source fires, a target with no rule of its own in that row is excluded (by value on an exception, by tag in a matrix row; a matrix `allow` cell is NOT a mention because editors show it as Neutral). No more one-shot/consumed-set: the engine counts per-constraint downstream hits in `ctx["__wp_constraint_hits__"]`. Reach is downstream-relative (counts from the constraint's own chain position) and cross-node + transitive (resolves `@{uuid}` at any depth). `pick` selects specific instances by `_uid` (direct top-level) or carrier `_uid` + option id (nested). The re-weight math is the pure `engine/modules/_constraint_math.py::combine_constraint_factor`, mirrored in TS at `src/manager/utils/constraint-math.ts` via the shared `tests/fixtures/constraint-corpus.json`. Published payloads using a non-default `target_select` stamp `schema_version = 4` (additive; community catalog v4).
+- **Send-to-negative (schema v8)** — wildcard options, fixed values and combines carry an optional `negative` (same grammar as their value); derivation mode `negative` adds to a variable's negatives without writing it, and `negative_replace` swaps them for its value (test both with `isNegativeMode`). The engine files them per variable in `ctx["__wp_negatives__"]` (`engine/negatives.py`, cross-node key). Negatives FOLLOW USAGE: the Assembler's `negative` output only takes negatives of variables its template rendered; a write replaces a variable's negatives, append/prepend keep them. Negative text resolves on its own `key::neg` seed stream and refs inside it resolve quietly (no pick, no ref log, no hits, no chaining), so negatives never shift picks. Store an empty negative as absent. `$name.neg` / `$name.K.neg` reads a variable's negatives (`neg` rides the axis slot of the accessor grammar and is reserved: no `accepts` group may use it); it is not a read of `$name`, so it carries no negatives along. Both need v8.
+- **Multi-action derivation clauses (schema v8)** — a branch or `else` runs its `action`, then each `extra_actions` entry in order (absent, never `[]`, for one action). Each action sees the previous one's write. Walk actions with `clause_actions` (Python) / `clauseActions` (TS); never read `.action` alone. Instance overrides key extra actions `"{bi}.{K}"` / `"else.{K}"` (`action_override_key` ≡ `actionOverrideKey`).
+- **Wildcard fallback (schema v9)** — at most one non-null option per wildcard may carry `fallback: true` (stored only as `true`). It rolls like any option (weight, filters, toggles, constraints all apply; flagging never changes a normal draw) and is ALSO taken, without an rng draw, when nothing is live after weights + constraints (`engine/modules/_fallback.py:find_fallback`, run after filters + toggles) — top-level handler AND nested `ref_option_pool`. It replaces the `constraint_excludes_all_options` warning with an info `fallback_used`. Editors and probability helpers give it its normal share.
+- **Model-aware pipelines** — `WP_ModelInfo` (`wp_nodes/model_info_node.py`) writes `$model_family` (from `model.model.model_config`'s class), `$model_variant` (file-name rules) and `$model_name`; the file name comes from following its `model` link through the hidden `prompt` (`engine/model_info.py::find_checkpoint_name`). Rules + stems mirror in TS at `src/extension/model-info.ts` via `tests/fixtures/model-variant-corpus.json`. Graph walkers treat it as a var source like the injector (kind `model`). Wildcard instance `match_variable` picks the option whose text equals that variable (else fallback, else roll + `match_variable_no_match`), which is how a variable becomes a constraint source. Workflow/instance state only, no schema bump.
+- **Image Filter** — `WP_ImageFilter` (`wp_nodes/image_filter_node.py`, pure logic in `engine/image_filter.py`) is `is_input_list` with a FIXED slot set (no dynamic "any" outputs; `extra_1/2` are `MatchType`). A paused run waits in an `async execute` on the thread-safe `PENDING` store; the picker answers via `POST /wp/api/image-filter/answer` (`wp_api/image_filter.py`) after the `wp-image-filter` websocket event. "Stop" returns one `ExecutionBlocker(None)` PER output (a bare blocker does not block). Values batched like the frame's images are sliced (tensor dim 0, LATENT dict, CONDITIONING incl. `pooled_output`); everything else is kept/dropped with its frame. Picker answers may carry `edits` keyed `"f:i"` (`positive`/`negative` text, `mask` = PNG data URL whose ALPHA is the mask): with `same_shape` the first edited image of an item decides its prompt; an edited prompt is re-encoded only when the optional `clip` input is wired; once any mask is painted every output item gets a mask (incoming or empty). Send to Loop writes back through `editLoopConfig` (`widgets/context_loop.ts`).
+- **Bundle-size gate** — entry `main.js` must stay ≤ 30 KB gzipped; total `js/` ≤ 468 KB. Pre-commit run `pnpm build:extension && pnpm size`. Raising budget require explicit PR discussion.
 - **Coverage gate** — vitest v8 coverage with thresholds (lines/statements 50%, functions 40%, branches 65%). Anchored to current baseline; ratchet up alongside new tests.
 - **Caching** — `WP_Context` + `WP_Debug` set `not_idempotent=True` so seed cycling always re-executes.
 - **Conventional Commits** — enforced by commitlint. semantic-release read log to cut versions.
@@ -58,12 +63,13 @@ ruff check .           # Python lint
 
 ## Frontend overview
 
-- **Entry** `src/main.ts` → `js/main.js` (~1.6 KB gzip). Top-level await preload widget chunks so `getCustomWidgets` factories run sync (Promise return → `{widget: undefined}` and widget never mount). Register extension + lazy-import widget code only when ComfyUI hand matching node.
-- **Lazy chunks** `src/widgets/{context,debug,assembler}.ts` — one mount glue per widget. Each `import()` become own asset chunk, plus sibling SFC chunk (`ContextWidget`, `DebugViewer`, `AssemblerHelper`).
-- **Shared** `src/widgets/_shared.ts` expose `createDomWidgetHost`, JSON helpers (`parseWidgetJson`, `parseWidgetJsonWithRecovery` for corrupt-workflow recovery path), shared types. Largest shared chunk (`_shared`, ~33 KB gzip) is Vue runtime + plugin-vue helper, pulled in by every widget on first use.
+- **Entry** `src/main.ts` → `js/main.js` (~4 KB gzip). One top-level `await import("./boot")` preload widget glue so `getCustomWidgets` factories run sync (Promise return → `{widget: undefined}` and widget never mount; ComfyUI does not await an async `getCustomWidgets`).
+- **Boot chunk** `src/boot.ts` — everything registration + node creation need, re-exported from ONE module so it ship as ONE chunk (empty canvas = `main.js` + `boot-*.mjs`). Before, each preload was own `import()` and shared deps split out: 43 files. Only add what registration needs; anything reached by user action (modal, toast stack, subgraph badge) gets a `load*` helper in `boot.ts`, not an `import()` in `main.ts` (a chunk loaded from `main.ts` makes Rollup split vue + stores back out).
+- **Widget glue** `src/widgets/*.ts` — one mount glue per widget, in the boot chunk. Each loads its SFC via `defineAsyncComponent` (`ContextWidget`, `DebugViewer`, `AssemblerHelper`, `RichTextInput`, …) so SFC chunks download only when a matching node exists.
+- **Shared** `src/widgets/_shared.ts` expose `createDomWidgetHost`, JSON helpers (`parseWidgetJson`, `parseWidgetJsonWithRecovery` for corrupt-workflow recovery path), shared types. Lives in boot chunk with Vue runtime.
 - **Graph + conflicts** `src/extension/{graph,conflicts,subgraph-badge,reactive,graph-events}.ts` — pure logic, no DOM. Imported by widgets, easy to unit-test isolated.
 - **Reactivity** `extension/reactive.ts:reactiveFromGraph` — wires `onConnectionsChange` chain + 400ms polling fallback + `afterConfigureGraph` re-sync so widgets recompute on graph edits + workflow loads without flashing stale state.
-- **Adding new widget**: (1) write SFC under `src/components/<name>/`, (2) add `src/widgets/<name>.ts` exposing `create(node, inputName)` that return `createDomWidgetHost(...)`, (3) wire in `src/main.ts` — either as `getCustomWidgets` entry (for inputs declared with matching widget-type) or via `beforeRegisterNodeDef → onNodeCreated` (for free-floating helpers). Use `import("./widgets/<name>")` so stay out of entry chunk + size gate keep holding.
+- **Adding new widget**: (1) write SFC under `src/components/<name>/`, (2) add `src/widgets/<name>.ts` exposing `create(node, inputName)` that return `createDomWidgetHost(...)`, (3) re-export it from `src/boot.ts` and wire in `src/main.ts` — either as `getCustomWidgets` entry (for inputs declared with matching widget-type) or via `beforeRegisterNodeDef → onNodeCreated` (for free-floating helpers). SFC via `defineAsyncComponent`, never static import, so boot chunk stay small.
 
 ## Schema versioning + lazy migration machine
 
@@ -81,11 +87,19 @@ Spec: `D:\Desktop\Wildcard-Pipeline-Community\docs\superpowers\specs\2026-06-05-
 - `tolerant_drift_status TEXT` — `none` | `tolerant` | `strict`. Set by parseTolerantAsCurrentShape during install.
 - `schema_migrated_at TEXT` — wall-clock stamp of last lazy migration step.
 
+**Which number goes where** (three constants, one job each — don't collapse them):
+
+- **`CURRENT_SCHEMA_VERSION` = 2** (`src/manager/import-export/migrations.ts`, mirrored in `engine/migrations/__init__.py`): head of the migration chain. Stays 2 because v3–v9 are additive and need no migrator.
+- **`MAX_KNOWN_SCHEMA_VERSION` = 9** (same two files): the highest version this runtime reads + writes natively. Advertised to the community as `window.__wpcRuntime.schemaVersion` (`src/manager/main.ts`) and the ceiling above which `migrateImportEnvelope` refuses a pack.
+- **Content stamp** (`schemaVersionForPayload` in `src/manager/import-export/single-row-publish.ts`): what publish sends — the LOWEST version the payload's features need (2 baseline, 3 SP2b range/`~` grammar, 4 non-default constraint `target_select`, 5 a wildcard `accepts` tag axis, 6 a constraint `only` rule, 7 a derivation branch with AND/OR groups or `is_empty`/`is_not_empty`, 8 a non-empty `negative`, a derivation "Add to negative" / "Replace negative" action, `extra_actions` or a `$name.neg` read, 9 a wildcard option flagged `fallback`).
+
+A pack arriving from the community keeps the stamp the server stored for it (`CommunityDownload.schema_version`, fed to `wrapAsEngineExport` / the dependency downloader) so install migrates it from where it actually is. Never stamp a received pack with a constant. Local round-trips of live rows (e.g. `BundleEditor` extract) stamp `MAX_KNOWN_SCHEMA_VERSION`.
+
 **The machine**:
 
-- **Validator registry** (`src/manager/import-export/validators/`): one Zod validator per known `schema_version`. Strict at `≤ CURRENT_SCHEMA_VERSION`; future versions go through `parseTolerantAsCurrentShape` (additive-strip).
+- **Validator registry** (`src/validators/index.ts:getValidator`): one Zod validator per shape-changing `schema_version` (v1, v2). v3–v9 didn't change a shape, so they validate against v2. Tolerant mode (`.strip()`) is for installing newer payloads (`parseTolerantAsCurrentShape`).
 - **`parseTolerantAsCurrentShape(raw, currentVersion)`** (`src/manager/import-export/tolerant-parse.ts`): strips fields the current shape doesn't know, returns the projection that matches `currentVersion`. Used at install when source `schema_version > CURRENT`.
-- **`migratePayload(payload, from, to)`** (`src/manager/import-export/migration-machine.ts`): forward-only chain. Each step is a registered function in the migrators map. `from > to` is illegal — no downgrades.
+- **`migratePayload(payload, from, to)`** (`src/manager/import-export/migrations.ts`, beside the envelope-level `migrateImportEnvelope`): forward-only chain. Each step is a registered function in the migrators map. `from > to` is illegal — no downgrades.
 - **`lazy_migrate_row(row, currentVersion, migrators, validators)`** (`engine/db/lazy_migrate.py`): reads `original_payload_json` (or `payload` if absent), walks the migrator chain to `currentVersion`, validates, writes back. Bulk-at-boot runner is eager iteration of this routine.
 - **Install decision tree** (`src/manager/import-export/install.ts`): branches on `source_schema_version` vs `CURRENT_SCHEMA_VERSION`:
   - `=`: strict validate + insert.
@@ -93,20 +107,30 @@ Spec: `D:\Desktop\Wildcard-Pipeline-Community\docs\superpowers\specs\2026-06-05-
   - `>` and tolerant-only diff: parseTolerantAsCurrentShape, mark `tolerant_drift_status='tolerant'`, insert.
   - `>` and breaking-future diff (per catalog `is_breaking_from_previous` AND-fold across the interval): refuse install with a clear error.
 
-**Server probe**: `engine-export-wrap.ts:ENGINE_SCHEMA_VERSION` is the sister's pinned CURRENT — it ships in the sister bundle, not fetched from server. The host bridge install path reads it from `window.__wpcRuntime.schemaVersion`. Server-first deploy ordering (see community CLAUDE.md) means the community catalog always reflects shapes ≥ sister's CURRENT.
+**Server probe**: the host bridge advertises `MAX_KNOWN_SCHEMA_VERSION` as `window.__wpcRuntime.schemaVersion`; it ships in the sister bundle, not fetched from server. The community embed refuses to install a pack stamped above it. Server-first deploy ordering (see community CLAUDE.md) means the community catalog always reflects shapes ≥ sister's MAX_KNOWN.
 
 ### Bumping `schema_version` (the proper way)
 
 When a payload shape change lands (not a row-column change — those don't bump schema):
 
-1. **Add the new shape's validator.** New file under `src/manager/import-export/validators/v<N>.ts` exporting a Zod schema. Register in `validators/index.ts`.
-2. **Add the migrator step.** In `src/manager/import-export/migration-machine.ts`, register `migrators[N-1 → N]: (payload) => ...`. Forward-only. The function is pure — no side effects.
-3. **Add fixtures.** `src/manager/__tests__/import-export/fixtures/v<N>/` — at minimum: a `valid-strict.json`, a `from-v<N-1>-migrated.json` round-trip case, and one `breaking-shape.json` if the bump is breaking.
-4. **Bump the constant.** `CURRENT_SCHEMA_VERSION` lives in the validator registry. Bump it to `N`. Also bump `ENGINE_SCHEMA_VERSION` in `src/manager/components/engine-export-wrap.ts`.
+**Additive bump** (an optional field, new enum value or new text grammar an old runtime can safely lack — v3 through v9 all were):
+
+1. **Add the version constant** next to `TAG_AXES_SCHEMA_VERSION` / `CONSTRAINT_ONLY_SCHEMA_VERSION` in `migrations.ts` (and `engine/migrations/__init__.py`), with a comment saying what triggers it.
+2. **Teach `schemaVersionForPayload`** AND its Python mirror `engine/migrations/stamping.py` to return it only when the payload actually uses the feature (structural walk, bundle children + instance overrides included), and add cases to `src/manager/__tests__/import-export/publish-stamping.test.ts` + `tests/engine/test_schema_stamping.py`.
+3. **Bump `MAX_KNOWN_SCHEMA_VERSION`** in `migrations.ts` AND `engine/migrations/__init__.py`, and update the drift guard in `schema-version-fork.test.ts` to exercise the new highest stamp.
+4. **Make sure the strict validator keeps the new field** (it strips unknown keys) — `src/validators/module/v2.ts` + the engine-parity test.
+5. **Catalog row** — step 7 below. `CURRENT_SCHEMA_VERSION` does not move.
+
+**Shape-changing bump** (needs a migrator):
+
+1. **Add the new shape's validator.** New file under `src/validators/module/v<N>.ts` (and `bundle/` if needed). Register every subtype at `N` in `src/validators/index.ts`.
+2. **Add the migrator step.** In `src/manager/import-export/migrations.ts`, add to `MIGRATION_CHAIN` (envelope) and/or `registerMigrator` (per row), and mirror it under `engine/migrations/`. Forward-only. The function is pure — no side effects.
+3. **Add fixtures.** Under `src/validators/fixtures/v<N>/` — at minimum a strict-valid module per subtype, plus a migrated-from-v<N-1> round-trip case in `src/manager/__tests__/import-export/migration-machine.test.ts`.
+4. **Bump the constants.** `CURRENT_SCHEMA_VERSION` and `MAX_KNOWN_SCHEMA_VERSION` to at least `N`, in both `migrations.ts` and `engine/migrations/__init__.py`.
 5. **Write the migration test.** `tests/engine/db/test_lazy_migrate.py` should cover v<N-1>→v<N> round-trip + the breaking-future path if applicable.
 6. **Run `pytest tests/engine/ -q && pnpm test` until green.** Sister pre-commit hook (~2 min) also runs lint + typecheck + build + size; expect that wait.
 7. **Coordinate the community-side catalog row.** Community web's `schema_catalog` table gets the matching `(version, is_breaking_from_previous, notes)` row + a deploy that lands BEFORE sister's PR merges. See community CLAUDE.md "Bumping the schema" for the server side.
-8. **Sister deploys after server.** Once catalog HEAD ≥ sister's CURRENT, sister can safely refuse breaking-future shapes.
+8. **Sister deploys after server.** Once catalog HEAD ≥ sister's MAX_KNOWN, sister can safely publish the new stamp and refuse breaking-future shapes.
 
 ### Validator ↔ engine parity (DON'T skip)
 
@@ -122,6 +146,9 @@ this:
   shape to `src/validators/fixtures/engine-parity/*.json`.
 - `src/validators/__tests__/engine-parity.test.ts` asserts the **strict**
   community validator accepts every one of those fixtures.
+- `tests/test_engine_parity_fixtures.py` re-runs the dump in memory and fails
+  pytest when a committed fixture is stale, so forgetting the script is
+  caught in CI.
 
 **Any time you change an engine module payload shape** (a `*_handler.py`
 `validate_payload`, or what the editor stores), run

README.md

@@ -1,157 +1,161 @@
 <h1 align="center">
-  <img src="public/images/favicon.svg" width="40" align="center" alt=""/>
+  <img src="public/images/favicon.svg" width="40" align="top" alt=""/>
   &nbsp;Wildcard Pipeline
 </h1>
 
 <p align="center">
-  <em>Modular procedural prompt generation for ComfyUI — wildcards, constraints, derivations, loops, and a persistent module library.</em>
+  <em>Random prompts for ComfyUI that actually make sense together.</em>
 </p>
 
 <p align="center">
-  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/DumiFlex/ComfyUI-Wildcard-Pipeline/ci.yml?branch=main&label=ci"></a>
-  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/releases"><img alt="Release" src="https://img.shields.io/github/v/release/DumiFlex/ComfyUI-Wildcard-Pipeline?include_prereleases"></a>
-  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/DumiFlex/ComfyUI-Wildcard-Pipeline"></a>
-  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki"><img alt="Wiki" src="https://img.shields.io/badge/docs-wiki-blue"></a>
+  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/DumiFlex/ComfyUI-Wildcard-Pipeline/ci.yml?branch=main&label=ci&logo=githubactions&logoColor=white"></a>
+  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/releases"><img alt="Release" src="https://img.shields.io/github/v/release/DumiFlex/ComfyUI-Wildcard-Pipeline?include_prereleases&logo=github&logoColor=white"></a>
+  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/DumiFlex/ComfyUI-Wildcard-Pipeline?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxwYXRoIGQ9Im0xNiAxNiAzLTggMyA4Yy0uODcuNjUtMS45MiAxLTMgMXMtMi4xMy0uMzUtMy0xWiIvPjxwYXRoIGQ9Im0yIDE2IDMtOCAzIDhjLS44Ny42NS0xLjkyIDEtMyAxcy0yLjEzLS4zNS0zLTFaIi8%2BPHBhdGggZD0iTTcgMjFoMTAiLz48cGF0aCBkPSJNMTIgM3YxOCIvPjxwYXRoIGQ9Ik0zIDdoMmMyIDAgNS0xIDctMiAyIDEgNSAyIDcgMmgyIi8%2BPC9zdmc%2B"></a>
+  <a href="https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki"><img alt="Wiki" src="https://img.shields.io/badge/docs-wiki-blue?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxwYXRoIGQ9Ik0xMiA3djE0Ii8%2BPHBhdGggZD0iTTMgMThhMSAxIDAgMCAxLTEtMVY0YTEgMSAwIDAgMSAxLTFoNWE0IDQgMCAwIDEgNCA0IDQgNCAwIDAgMSA0LTRoNWExIDEgMCAwIDEgMSAxdjEzYTEgMSAwIDAgMS0xIDFoLTZhMyAzIDAgMCAwLTMgMyAzIDMgMCAwIDAtMy0zeiIvPjwvc3ZnPg%3D%3D"></a>
   <a href="https://discord.gg/BFYR9WQdVR"><img alt="Discord" src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white"></a>
+  <a href="https://wp.dumiflex.dev/?utm_source=github&amp;utm_medium=readme"><img alt="Community" src="https://img.shields.io/badge/community-modules-8A63D2?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDI0IDEwMjQiIGZpbGw9IndoaXRlIj48cGF0aCBkPSJtNTEyLDJjLTUzLjYsMC05OC40NywzOC4xNi0xMDguODQsODguNzMtNzUuMDcsMTkuMjktMTQzLjMyLDU4LjI2LTE5OC43NCwxMTMuNjgtNTUuNDIsNTUuNDItOTQuMzksMTIzLjY4LTExMy42OCwxOTguNzQtNTAuNTgsMTAuMzgtODguNzMsNTUuMjQtODguNzMsMTA4Ljg0czM4LjE2LDk4LjQ3LDg4LjczLDEwOC44NGMxMy42Miw1My4xNCwzNy4wMywxMDIuNjQsNjkuNzcsMTQ3LjQ3LDM3LjE0LDUwLjg2LDg1LjgzLDkzLjg2LDE0MC44MSwxMjQuMzMsNS41NCwzLjA4LDExLjU2LDQuNTQsMTcuNDgsNC41NCwxMi43LDAsMjUuMDItNi43MiwzMS42MS0xOC42MSw5LjY4LTE3LjQ0LDMuMzgtMzkuNDItMTQuMDctNDkuMDktODUuMzItNDcuMzItMTQ3LjIyLTEyNS43MS0xNzMuMzgtMjE4LjIxLDM2LjMtMTguMjksNjEuMjctNTUuOTIsNjEuMjctOTkuMjhzLTI0Ljk0LTgwLjk3LTYxLjIzLTk5LjI3YzM0LjIyLTExOS45NiwxMjkuNzktMjE1LjUyLDI0OS43NC0yNDkuNzQsMTguMywzNi4yOSw1NS45Miw2MS4yMyw5OS4yNyw2MS4yMyw2MS4yNywwLDExMS4xMS00OS44NCwxMTEuMTEtMTExLjExUzU3My4yNywyLDUxMiwyWk0xMTMuMTEsNDczLjExYzIxLjQ0LDAsMzguODksMTcuNDQsMzguODksMzguODksMCwyMC4xLTE1LjMyLDM2LjY5LTM0LjkxLDM4LjY5aC0uMDFjLS4xOC4wMi0uMzYuMDMtLjUzLjA0LTEuMTMuMS0yLjI4LjE2LTMuNDMuMTYtMjEuNDQsMC0zOC44OS0xNy40NC0zOC44OS0zOC44OXMxNy40NC0zOC44OSwzOC44OS0zOC44OVptMzk4Ljg5LTMyMS4xMWMtMjEuNDQsMC0zOC44OS0xNy40NC0zOC44OS0zOC44OXMxNy40NC0zOC44OSwzOC44OS0zOC44OSwzOC44OSwxNy40NCwzOC44OSwzOC44OS0xNy40NCwzOC44OS0zOC44OSwzOC44OVoiLz48cGF0aCBkPSJtOTMzLjI3LDQwMy4xNmMtMTMuNjItNTMuMTQtMzcuMDMtMTAyLjY0LTY5Ljc3LTE0Ny40Ny0zNy4xNC01MC44Ni04NS44My05My44Ni0xNDAuODEtMTI0LjMzLTE3LjQ0LTkuNjgtMzkuNDItMy4zOC00OS4wOSwxNC4wNy05LjY4LDE3LjQ0LTMuMzgsMzkuNDIsMTQuMDcsNDkuMDksODUuMzIsNDcuMzIsMTQ3LjIyLDEyNS43MSwxNzMuMzgsMjE4LjIxLTM2LjMsMTguMjktNjEuMjcsNTUuOTItNjEuMjcsOTkuMjhzMjQuOTQsODAuOTcsNjEuMjMsOTkuMjdjLTM0LjIyLDExOS45Ni0xMjkuNzksMjE1LjUyLTI0OS43NCwyNDkuNzQtMTguMy0zNi4yOS01NS45Mi02MS4yMy05OS4yNy02MS4yMy02MS4yNywwLTExMS4xMSw0OS44NC0xMTEuMTEsMTExLjExczQ5Ljg0LDExMS4xMSwxMTEuMTEsMTExLjExYzUzLjYsMCw5OC40Ny0zOC4xNiwxMDguODQtODguNzMsNzUuMDctMTkuMjksMTQzLjMyLTU4LjI2LDE5OC43NC0xMTMuNjgsNTUuNDItNTUuNDIsOTQuMzktMTIzLjY4LDExMy42OC0xOTguNzQsNTAuNTgtMTAuMzgsODguNzMtNTUuMjQsODguNzMtMTA4Ljg0cy0zOC4xNi05OC40Ny04OC43My0xMDguODRabS00MjEuMjcsNTQ2LjYyYy0yMS40NCwwLTM4Ljg5LTE3LjQ0LTM4Ljg5LTM4Ljg5czE3LjQ0LTM4Ljg5LDM4Ljg5LTM4Ljg5LDM4Ljg5LDE3LjQ0LDM4Ljg5LDM4Ljg5LTE3LjQ0LDM4Ljg5LTM4Ljg5LDM4Ljg5Wm0zOTguODktMzk4Ljg5Yy0yMS40NCwwLTM4Ljg5LTE3LjQ0LTM4Ljg5LTM4Ljg5LDAtMjAuMDMsMTUuMjItMzYuNTgsMzQuNzItMzguNjcuMzgtLjA0Ljc3LS4wOCwxLjE2LS4xMWguMDJjLjk5LS4wOCwxLjk5LS4xMSwyLjk5LS4xMSwyMS40NCwwLDM4Ljg5LDE3LjQ0LDM4Ljg5LDM4Ljg5cy0xNy40NCwzOC44OS0zOC44OSwzOC44OVoiLz48cGF0aCBkPSJtNzM1LjAyLDUxNy41NmMtMTUzLjgyLDMwLjg3LTE4Ni41OSw2My42NC0yMTcuNDYsMjE3LjQ2LTEuMjIsNi4wOC05LjksNi4wOC0xMS4xMiwwLTMwLjg3LTE1My44Mi02My42NC0xODYuNTktMjE3LjQ2LTIxNy40Ni02LjA4LTEuMjItNi4wOC05LjksMC0xMS4xMiwxNTMuODItMzAuODcsMTg2LjU5LTYzLjY0LDIxNy40Ni0yMTcuNDYsMS4yMi02LjA4LDkuOS02LjA4LDExLjEyLDAsMzAuODcsMTUzLjgyLDYzLjY0LDE4Ni41OSwyMTcuNDYsMjE3LjQ2LDYuMDgsMS4yMiw2LjA4LDkuOSwwLDExLjEyWiIvPjxwYXRoIGQ9Im00MzQuMDYsNjY1Ljg1Yy01MS4wOCwxMC4yNS02MS45NiwyMS4xMy03Mi4yMiw3Mi4yMi0uNDEsMi4wMi0zLjI5LDIuMDItMy42OSwwLTEwLjI1LTUxLjA4LTIxLjEzLTYxLjk2LTcyLjIyLTcyLjIyLTIuMDItLjQxLTIuMDItMy4yOSwwLTMuNjksNTEuMDgtMTAuMjUsNjEuOTYtMjEuMTMsNzIuMjItNzIuMjIuNDEtMi4wMiwzLjI5LTIuMDIsMy42OSwwLDEwLjI1LDUxLjA4LDIxLjEzLDYxLjk2LDcyLjIyLDcyLjIyLDIuMDIuNDEsMi4wMiwzLjI5LDAsMy42OVoiLz48cGF0aCBkPSJtNzM4LjA3LDM2MS44NGMtNTEuMDgsMTAuMjUtNjEuOTYsMjEuMTMtNzIuMjIsNzIuMjItLjQxLDIuMDItMy4yOSwyLjAyLTMuNjksMC0xMC4yNS01MS4wOC0yMS4xMy02MS45Ni03Mi4yMi03Mi4yMi0yLjAyLS40MS0yLjAyLTMuMjksMC0zLjY5LDUxLjA4LTEwLjI1LDYxLjk2LTIxLjEzLDcyLjIyLTcyLjIyLjQxLTIuMDIsMy4yOS0yLjAyLDMuNjksMCwxMC4yNSw1MS4wOCwyMS4xMyw2MS45Niw3Mi4yMiw3Mi4yMiwyLjAyLjQxLDIuMDIsMy4yOSwwLDMuNjlaIi8%2BPC9zdmc%2B"></a>
 </p>
 
 <p align="center">
-  <img src="public/images/docs/flow-intro.svg" alt="Wildcard, Fixed Values, Combine, Derivation and Constraint modules resolve inside WP Context, which emits named $variables that fill the WP Prompt Assembler template, which CLIP Encode turns into conditioning" />
+  <img src="public/images/docs/flow-intro.svg" alt="Modules resolve inside WP Context, which emits named $variables that fill the WP Prompt Assembler template, which CLIP Encode turns into conditioning" />
 </p>
 
-## What it does
+Plain wildcards pick every part of a prompt on its own, so you get a snowy beach
+at noon under the stars. Wildcard Pipeline builds the prompt step by step, and
+each step can see what the earlier ones picked. If the weather comes out as rain,
+the mood can lean gloomy and the lighting can follow. Every Generate gives you a
+fresh prompt that still hangs together.
 
-Stock ComfyUI prompt nodes either take a single literal string or pick from a flat wildcard file. **Wildcard Pipeline** lets each module read what the previous modules picked — so `$mood` reacts to `$weather` via a constraint, a `combine` interpolates `$style $subject` into `$scene`, a derivation flips `$accent` based on `$mood`, and your final prompt is a coherent multi-element composition instead of a Frankenstein concatenation.
+## Install
 
-**One Generate. One coherent prompt. Re-roll until you stop laughing.**
+- **ComfyUI Manager (recommended):** search for **Wildcard Pipeline** by
+  **dumiflex**, click **Install** and restart ComfyUI.
+- **By hand:** download the zip from the
+  [latest release](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/releases/latest),
+  unzip it into `ComfyUI/custom_nodes/` and restart ComfyUI.
 
-## Highlights
+<details>
+<summary>Installing from source</summary>
 
-- **Module stack inside a Context node** — drop in `wildcard`, `fixed_values`, `combine`, `derivation`, `constraint`, `bundle` modules and they each publish a `$variable` to the chain.
-- **Constraints with carriers** — re-weight downstream wildcards based on what upstream picked. Matrix + per-option exceptions. Carrier-via-nested-ref so a constraint can reach a wildcard nested inside another wildcard's option.
-- **Loops + per-iteration seeds** — `WP Context Loop` runs your whole chain N times from a single Generate; `WP Seed List` pairs N unique sampler seeds with the N prompts so every output is distinct.
-- **Persistent library** — a manager SPA backed by SQLite stores reusable modules, frozen bundles, prompt templates, and a category tree. Browse / edit / fork / push from the canvas.
-- **Inspector** — `WP Debug` shows the post-run snapshot, per-module trace, per-wildcard picks, and the conflict-scanner warnings.
-- **Type-coercion helpers** — `WP Var → Int / Float / Bool` parse typed values out of any `$variable` so wildcards can drive image width, step count, sampler cfg, conditional switches.
-- **Works on both renderers** — the legacy canvas and ComfyUI's Nodes 2.0 Vue renderer, including switching between them with a workflow already open.
+A git clone has no built frontend, so you need Node.js and pnpm:
 
-## Installation
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline
+cd ComfyUI-Wildcard-Pipeline
+pnpm install
+pnpm build
+```
 
-### ComfyUI Manager (recommended)
-
-1. Open the **ComfyUI Manager** in your browser.
-2. Search for **Wildcard Pipeline** by **dumiflex**.
-3. Click **Install** and restart ComfyUI.
-
-### Manual installation
-
-1. Navigate to your ComfyUI `custom_nodes` directory.
-2. Clone the repository:
-
-   ```bash
-   git clone https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline
-   ```
-
-3. Install the Python dependencies:
-
-   ```bash
-   pip install -e .
-   ```
-
-4. Build the frontend assets (requires Node.js and pnpm):
-
-   ```bash
-   pnpm install
-   pnpm run build
-   ```
-
-5. Restart ComfyUI.
+</details>
 
 ## Quick start
 
-1. Open the Wildcard Pipeline manager (sidebar → **Wildcards** → **+ New**). Name `subject`, variable binding `$subject`, three options: `a cat`, `a dog`, `a fox` at weight 1 each. Save.
-2. On the canvas, drop `WP Context` → `WP Prompt Assembler` → `CLIP Text Encode` → `KSampler`. Add your wildcard to the context. Type `a $subject` into the assembler template. Queue.
+1. Open the **Wildcard Pipeline** manager from the ComfyUI sidebar and create a
+   wildcard called `subject` with three options: `a cat`, `a dog`, `a fox`.
+2. On the canvas, chain **WP Context** → **WP Prompt Assembler** →
+   **CLIP Text Encode**. Add your wildcard to the Context node and type
+   `a photo of $subject` into the Assembler.
+3. Queue a few times. Each run picks a new subject.
 
-Each Generate rolls a fresh subject. Full walkthrough: [Quick Start wiki page](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start).
+The [Quick Start wiki page](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Quick-Start)
+walks through a fuller example.
 
-## The nodes
+## How it works
+
+You stack **modules** inside a **WP Context** node. Each module sets one or more
+`$variables`, and the **WP Prompt Assembler** drops them into your template.
+
+| Module | What it does |
+|---|---|
+| **Wildcard** | Picks one option from a weighted list. |
+| **Fixed Values** | Sets variables to values you choose, like a style or quality tags. |
+| **Combine** | Builds one variable out of others, e.g. `$style $subject`. |
+| **Derivation** | If/else rules: "if `$weather` is rain AND `$time` is night, set `$lighting` to neon". Conditions can be grouped with AND / OR. |
+| **Constraint** | Makes an earlier pick change the odds of a later one, or rule options out entirely. |
+| **Bundle** | A saved group of modules you can drop in as one piece. |
+
+Options can point at other modules with `@name`, so a wildcard can nest another
+one. If the module you want doesn't exist yet, pick **Placeholder** from the `@`
+list and connect it later.
+
+### Nodes
 
 | Node | What it does |
 |---|---|
-| `WP Context` | Holds a module stack, emits a resolved `$variable` context. |
-| `WP Context Loop` | Runs the downstream chain N times in one click; emits per-iteration `$iteration` + `$iteration_total`. |
-| `WP Context Injector` | Lifts any ComfyUI node output (multiline String, INT, etc.) into a named `$variable`. |
-| `WP Seed List` | Emits a list of N derived seeds — one per loop iteration — so every (prompt, seed) pair is unique. |
-| `WP Prompt Assembler` | Fills `$var` placeholders in a template string. Supports `{a\|b\|c}` inline picks + missing-var detection. |
-| `WP Prompt Cleaner` | Rule-based prompt cleanup: whitespace, punctuation, exact + fuzzy dedupe, blocklist. |
-| `WP Debug` | Read-only inspector — Snapshot / Trace / Picks / Warnings tabs. |
-| `WP Var → Int / Float / Bool` | Parse typed values out of any `$variable` to drive ComfyUI INT / FLOAT / BOOLEAN inputs. |
+| **WP Context** | Holds your module stack and outputs the picked variables. Chain several together. |
+| **WP Prompt Assembler** | Fills `$variables` in a template. Also supports inline `{a\|b\|c}` picks. |
+| **WP Context Loop** + **WP Seed List** | Run the whole chain N times from one Generate, each with its own prompt and seed, or sweep every combination of chosen wildcard options. |
+| **WP Context Injector** | Turns any ComfyUI output (text, a number) into a `$variable`. |
+| **WP Model Info** | Reads the loaded checkpoint into `$model_family` / `$model_variant` (Pony, Illustrious, …) so rules can pick LoRAs and tags per model. |
+| **WP Image Filter** | Pauses the run so you pick which images go on to the upscaler. Their latent, conditioning, prompt text and Context are filtered with them, and you can edit a prompt or paint a mask before they go on. |
+| **WP Prompt Cleaner** | Tidies the final prompt: spacing, stray commas, empty `()`, nested weights, LoRA tags, duplicates, a blocklist. |
+| **WP Debug** | Shows what happened during a run (see below). |
+| **WP Var → Int / Float / Bool** | Use a variable to drive a number or switch, like image size or steps. |
 
-Full node reference: [Nodes wiki page](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Nodes).
+Most nodes have a help page in ComfyUI's node info panel, and the
+[wiki](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki) covers
+[nodes](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Nodes),
+[modules](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Modules) and
+[concepts](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Concepts)
+in depth.
 
-## The modules
+## The manager
 
-| Module | Writes | Role |
-|---|---|---|
-| **Wildcard** | `$<name>` | Weighted random pick from a pool. The core building block. |
-| **Fixed Values** | `$<name>` (× N) | Static `name → value` bindings — style, quality boosters, negative-prompt fragments. |
-| **Combine** | `$<name>` | Templated string that interpolates earlier `$vars` into a single output `$var`. |
-| **Derivation** | `$<name>` | IF / ELIF / ELSE rules that read picked `$vars` and rewrite others. |
-| **Constraint** | *(none)* | One-shot re-weight of a downstream wildcard's pool based on an upstream pick. |
-| **Bundle** | *(group)* | Frozen group of modules — drop into any Context as a reusable unit. |
-| **Template** | *(asm side)* | Saved Prompt Assembler template string in the library. |
-
-Full module reference: [Modules wiki page](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Modules).
-
-## Looping a chain — one click, N coherent prompts
+Open it from the ComfyUI sidebar. It's where your modules live between workflows.
 
 <p align="center">
-  <img src="public/images/docs/flow-loop.svg" alt="WP Context Loop drives WP Context and the Prompt Assembler; CLIP Encode turns each prompt into conditioning for KSampler, while WP Seed List supplies the matching seed directly" />
+  <img src="public/images/docs/spa_manager.png" alt="Wildcard Pipeline manager dashboard with module counts, quick create buttons and recently opened items" />
 </p>
 
-Drop `WP Context Loop` before your `WP Context` and pair it with `WP Seed List` for distinct sampler seeds. Both lists fan out in lockstep so iteration N's prompt always pairs with seed N. Each iteration carries its own `$iteration` / `$iteration_total` for in-template labelling (`frame 1 of 4 — a fox`). See [Concepts → Seeds and loops](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Concepts#seeds-and-loops).
+- **Library:** create, edit and search your modules, bundles and prompt
+  templates. The **Tags** page groups them into collections, and you can rename
+  or merge a tag across the whole library.
+- **Test Runner:** try a set of modules over many seeds without generating
+  images. See how often each option comes up and which rules fired, save a
+  baseline, and after an edit see exactly which outputs changed.
+- **Community:** browse and install modules other people have shared on the
+  [community site](https://wp.dumiflex.dev/?utm_source=github&utm_medium=readme), and publish your own.
+- **Import / Export:** move modules between machines as JSON files, or bring in
+  wildcard packs from A1111 or Forge on the **Wildcard packs** tab. Dynamic Prompts,
+  PPP and Impact Pack `.txt`, `.yaml` and `.json` files (or a `.zip` of them) become
+  wildcards, with `__references__` turned into links. A folder of related lists merges
+  into one wildcard whose options are tagged by list, with a tag group per folder level.
+  You review the plan first (each wildcard's role, what was merged and how exactly it
+  carries over), and the pack's entry points are filed into bundles per folder.
+- **Documentation:** the full guide, built into the app.
 
-## The manager (SPA)
+## Checking a run
 
-A dedicated single-page app for browsing + editing the library. Open it from the ComfyUI sidebar.
+Connect **WP Debug** to a Context node and generate. It shows:
 
-<p align="center">
-  <img src="public/images/docs/spa_manager.png" alt="Wildcard Pipeline manager — Dashboard view with module counts, Quick Create row, and a list of recently opened library entries" />
-</p>
+- **Variables:** every value, and which step set it.
+- **Trace:** each step, and why it did what it did: which derivation rule fired,
+  a wildcard's odds and what re-weighted them, where a nested pick came from.
+- **Warnings:** anything that went wrong, linked to the step that caused it.
+- **Raw:** the underlying data, for bug reports.
 
-- **Library** — wildcards / fixed values / combines / derivations / constraints / bundles / templates / categories. Filter, search, bulk-tag, favorite.
-- **Test Runner** — resolve any module against the engine N times and inspect per-rule fire rates / per-option pick rates.
-- **Import / Export** — versioned JSON exports with conflict resolution (rename / overwrite / skip per row).
-- **Cascade impact dialog** — deleting a module shows you every bundle + constraint + combine that references it before you confirm.
-- **Documentation tab** — full in-app docs covering every node + module + concept, with worked examples.
+## Help and sharing
 
-## Inspecting a run
+[Discord](https://discord.gg/BFYR9WQdVR) is the place for all of it: there are
+channels for questions, bug reports, feature requests and showing what you made.
+You can also report bugs on [GitHub Issues](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues).
 
-Wire a `WP Debug` node off any Context output. After Generate it fills with a tabbed snapshot of what flowed through that point:
+Made something you like? Post your images and workflows on Discord, and publish
+your modules on the [community site](https://wp.dumiflex.dev/?utm_source=github&utm_medium=readme) so others can
+install them from the manager's **Community** page.
 
-- **Snapshot** — final `$variable → value` map.
-- **Trace** — per-module execution log: what each ran, what it wrote, where the seed came from.
-- **Picks** — which wildcard option was picked, its weight, its sub-category.
-- **Warnings** — runtime warnings (constraint never fired, missing variable, etc.).
+## Privacy
 
-See [Nodes → WP Debug](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki/Nodes#wp-debug).
-
-## Documentation
-
-- 📖 **[GitHub Wiki](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/wiki)** — Home / Quick Start / Nodes / Modules / Concepts
-- 🖥️ **In-app docs** — sidebar → Documentation tab inside the manager SPA (every concept, every module, every node, with worked examples)
-- 💬 **[Discord](https://discord.gg/BFYR9WQdVR)** — chat, show-and-tell, fastest path to a response
-- 💭 **[GitHub Discussions](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/discussions)** — long-form questions, ideas, design threads
-- 🐛 **[Issue tracker](https://github.com/DumiFlex/ComfyUI-Wildcard-Pipeline/issues)** — bug reports + feature requests
-
-## Status
-
-Active development. Versioned releases with [semantic-release](https://github.com/semantic-release/semantic-release) — every merged commit on `main` either ships a release or stays as `next` until the next breaking / feature change rolls one. Bundle-size + test gates run on every branch push and PR.
+Everything runs locally. The extension only goes online to check for updates
+(you can turn this off in Settings), when you open the Community page, or when
+you choose to download the optional tag list for autocomplete. Details are in
+[docs/network-access.md](docs/network-access.md).
 
 ## Contributing
 
-PRs welcome. See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for the dev loop (`pnpm install` → `pnpm dev` for the extension watcher, `pnpm test` for vitest, `pytest` for the engine, `ruff check .` for lint).
+PRs are welcome. [CONTRIBUTING.md](.github/CONTRIBUTING.md) explains the dev setup.
 
 ## License
 
-[GPL-3.0-or-later](./LICENSE). Free to use, modify, fork. If you ship modifications, ship the source too.
+[GPL-3.0-or-later](LICENSE)

__init__.py

@@ -4,7 +4,14 @@ import os
 import sys
 
 # Tells ComfyUI to serve files from this folder under
-# /extensions/<package-name>/ and auto-load any `*.js` it finds.
+# /extensions/<package-name>/ and auto-load any `*.js` it finds. Only the
+# entry `main.js` uses that extension; lazy chunks are `.mjs` so ComfyUI does
+# not import them all up front (vite.config.mts).
+#
+# "any *.js it finds" is load-bearing: ComfyUI fetches EVERY file it lists
+# here on page load, so a chunk left behind by an older version is not merely
+# dead weight on disk — it is a request and a parse on every visit. Hence the
+# prune below.
 WEB_DIRECTORY = "./js"
 
 # Expose engine/ and wp_nodes/ as top-level packages so internal absolute imports
@@ -22,11 +29,70 @@ if _PKG_DIR not in sys.path:
 # ruff: noqa: E402 — imports must follow the sys.path shim above
 from comfy_api.latest import ComfyExtension
 
+# Remove chunks left by previous versions BEFORE ComfyUI scans WEB_DIRECTORY.
+# Manager updates extract over the installed folder without deleting what the
+# new version dropped, and our filenames are content-hashed, so every update
+# leaves the previous build behind. Self-healing on the next start; see
+# `wp_api/web_assets.py` for the measurements that motivated it.
+#
+# Wrapped because nothing here is worth failing a plugin load over — the
+# fallback is the disk usage that already exists.
+try:
+    from pathlib import Path as _Path
+
+    from wp_api.web_assets import prune_package_assets as _prune_package_assets
+
+    _prune_package_assets(_Path(_PKG_DIR))
+except Exception:  # noqa: BLE001 - never crash ComfyUI over housekeeping
+    import logging as _logging
+
+    _logging.getLogger(__name__).exception(
+        "wildcard-pipeline: stale-asset prune failed",
+    )
+
+# Move our files into `<ComfyUI>/user/wildcard-pipeline/` if a previous version
+# left them loose in the user directory.
+#
+# Placement is load-bearing: this must run BEFORE anything opens the database.
+# SQLite keeps `-wal` and `-shm` sidecars beside the main file, and moving that
+# set out from under an open connection corrupts it. Node imports below can
+# reach the DB, so the migration goes above them.
+#
+# Wrapped for the same reason as the prune above: the fallback is "keep using
+# the old location", which is strictly better than failing to load.
+try:
+    from engine.db.relocate import migrate_user_data as _migrate_user_data
+
+    _report = _migrate_user_data()
+    if _report.did_anything:
+        import logging as _logging
+
+        _log = _logging.getLogger(__name__)
+        if _report.moved:
+            _log.info(
+                "wildcard-pipeline: moved into user/wildcard-pipeline/: %s",
+                ", ".join(_report.moved),
+            )
+        # Skips and failures are warnings: in both cases a file the user cares
+        # about is not where the extension will now look for it.
+        for _note in _report.skipped:
+            _log.warning("wildcard-pipeline: left in place — %s", _note)
+        for _note in _report.failed:
+            _log.warning("wildcard-pipeline: could not move %s", _note)
+except Exception:  # noqa: BLE001 - never crash ComfyUI over housekeeping
+    import logging as _logging
+
+    _logging.getLogger(__name__).exception(
+        "wildcard-pipeline: user-data relocation failed",
+    )
+
 from wp_nodes.assembler_node import WPPromptAssembler
 from wp_nodes.context_loop import WPContextLoop
 from wp_nodes.context_node import WPContext
 from wp_nodes.debug_node import WPDebug
+from wp_nodes.image_filter_node import WPImageFilter
 from wp_nodes.injector_node import WPContextInjector
+from wp_nodes.model_info_node import WPModelInfo
 from wp_nodes.prompt_cleaner import WPPromptCleaner
 from wp_nodes.seed_list import WPSeedList
 from wp_nodes.var_to_bool import WPVarToBool
@@ -44,6 +110,8 @@ class WildcardPipelineExtension(ComfyExtension):
             WPPromptAssembler,
             WPDebug,
             WPContextInjector,
+            WPModelInfo,
+            WPImageFilter,
             WPPromptCleaner,
             WPSeedList,
             WPVarToInt,

conftest.py

@@ -40,3 +40,17 @@ def wp_db(tmp_path):
         yield conn
     finally:
         conn.close()
+
+
+@pytest.fixture(autouse=True)
+def _isolate_wp_settings(tmp_path, monkeypatch):
+    """Keep every test off the real settings file and the backup scheduler.
+
+    `PipelineEngine.run` reads `engine/prefs.py` on every run and `migrate`
+    consults it before upgrading a DB, so without this a test could read — or
+    a Settings API test write — the developer's real `settings.json`.
+    `register_routes` starts the daily backup thread; tests that want it call
+    `engine.db.backups.start_daily_scheduler` directly.
+    """
+    monkeypatch.setenv("WP_SETTINGS_PATH", str(tmp_path / "wp-settings.json"))
+    monkeypatch.setattr("wp_api._start_backups", lambda: None)

docs/help/WP_ContextInjector.md

@@ -17,6 +17,7 @@ Lifts arbitrary ComfyUI outputs into named `$variable` bindings on the PipelineC
 2. Each connected slot adds a row. Type the variable name (e.g. `style`).
 3. Optionally tick **internal** to hide it from the assembled prompt while keeping it readable by Combine / Derivation rules.
 4. Optionally write a template (`"I love $input_0"`) — the slot's raw value substitutes `$<slot_name>` before being written to ctx.
+5. Optionally write a **Negative** (row Edit panel, under Template) with the same `$slot` grammar. It replaces the variable's negative words and reaches only Assemblers that render the variable. Template rows take one too.
 
 ## Tips
 

docs/help/WP_ContextLoop.md

@@ -12,6 +12,7 @@ Optional power-user node that loops a WP_Context chain N times in a single workf
 | `override_seed` | switch | When OFF (default): `seed` is ignored. Downstream WP_Context widget seeds drive each node; loop iteration only adds XOR variation. When ON: `seed` becomes the base; derived N times via `strategy`; replaces downstream widget seeds. |
 | `iteration var` | text | Stamps `$<name>` (0..N-1) and `$<name>_total` (N) into each iteration's context. Default `iteration`. |
 | `bypass` | switch | Skip the loop. Behaves as `count=1`. |
+| Sweep combinations | menu | Run every combination of chosen wildcard options instead of `count` random rolls. See below. |
 
 ## Outputs
 
@@ -25,6 +26,16 @@ Each iteration runs the downstream chain with a different seed. Locked modules (
 
 Concrete example: `count=3`, `override_seed=ON`, `seed=42`, `strategy=sequential` → downstream WP_Context chain runs three times with chain seeds 42, 43, 44. PromptAssembler emits three prompts; KSampler renders three batches; SaveImage writes three files.
 
+## Sweep combinations
+
+Open **Sweep combinations** on the node and switch it on. Pick wildcards from the WP_Context nodes after the loop and tick which of their options to include; one Generate then runs every combination, one frame each. Sweeping `$hair` (red, blonde, black) against `$mood` (calm, joyful, brooding) gives 9 prompts in grid order: the first wildcard changes slowest, the last fastest. Above each wildcard's options, **all** ticks every option, **none** clears them so you can tick just the few you want, and **enabled only** goes back to the wildcard's enabled options.
+
+- **Limit** (default 64, max 999) caps the frames; extra combinations are skipped in order.
+- **Hold other picks** (default on) keeps every module you didn't sweep on the same pick across frames, so only the swept wildcards change.
+- The menu lists every frame before you run, the button shows the frame count, and `count` follows it.
+- Seed locks and bypassed frames follow their combination when you change the sweep (a lock on red + calm stays on red + calm), and go away when that combination no longer runs.
+- Each frame pins the swept wildcards like a hand-pinned option: tag axes still roll and constraints they drive still apply downstream.
+
 ## Tips
 
 - The `seed` field is a stock ComfyUI INT widget with `control_after_generate` — same randomize / fixed / increment buttons KSampler exposes. Right-click → "Convert widget to input" to swap it for an rgthree Seed wire when you want its UI affordances.

docs/help/WP_Debug.md

@@ -11,10 +11,10 @@ Inspect every variable flowing through the WP chain at this point. Terminal node
 1. Drop it anywhere in the chain.
 2. Run the workflow.
 3. The body shows tabs:
-   - **Snapshot** — every bound variable + value.
-   - **Trace** — per-module resolution history.
-   - **Picks** — what each wildcard rolled.
+   - **Variables** — every bound variable + value and the step that set it. A variable's negative words sit under it in red, naming their module when it isn't the variable's own; the tab bar counts variables with negatives.
+   - **Trace** — every step in run order, grouped by Context node; open one for why it did what it did. An "Add to negative" derivation action reads `negative: …`.
    - **Warnings** — unknown vars, constraints that never fired, etc.
+   - **Raw** — the snapshot JSON (including the negatives table).
 
 Drag the bottom-right corner to resize.
 

docs/help/WP_ImageFilter.md

@@ -0,0 +1,57 @@
+# WP Image Filter
+
+Pauses the run so you can pick which images go on. Everything that belongs to an image (its latent, masks, conditioning, prompt text and Context) is filtered with it, so the node can sit between the first KSampler and the upscaler and the upscaler only gets the picked images with their own prompts.
+
+## Inputs and outputs
+
+Every input has a matching output. Connect only what you need.
+
+- **images**: the images to pick from. Required; this is what the picker shows.
+- **latent**, **masks**: sliced to the picked images. A mask you paint in the picker replaces that image's mask.
+- **positive**, **negative**: CONDITIONING. A batched conditioning is sliced with the images; a single one is kept for each frame that keeps any image.
+- **positive_text**, **negative_text**: the prompt strings, kept or dropped with their frame.
+- **context**: the WP Context of each frame, kept or dropped with it.
+- **clip** (input only, optional): re-encodes a prompt you edit in the picker, so the positive/negative conditioning follows the edit. Without it an edit changes only the text outputs.
+- **extra_1**, **extra_2**: any type. The output takes the type of what you connect. Batched values are sliced; anything else follows its frame.
+- **picks** (output only): what was kept, as `frame:image` (1-based), for example `1:2, 3:1`.
+
+A Context Loop (or any list) makes one **frame** per iteration. Lists line up by frame; a shorter list repeats its last item.
+
+## The picker
+
+- Click an image to pick it. Ctrl+A picks everything; a frame with several images has an **all** button that picks the frame.
+- Click the frame around an image (its border or its label) to zoom in, where you can compare, edit the prompt and paint a mask. **Zoom & refine** in the header, or **Space**, opens and leaves the zoom too (Space zooms the image under the mouse). In the zoom, ←/→ move and ↑ picks. The picker remembers: leave it zoomed and the next one opens zoomed.
+- **I** or **Details** (in the zoom) adds a Details panel for power users: the frame's variable values (swept ones first, in their grid colour; **Copy** copies them), its seed, the other images of the frame with **Pick whole frame**, and the positive prompt with each value marked where it landed (click it to edit). Everything else in the zoom still works, and the picker remembers whether Details was on.
+- **C** (in the zoom) pins the image; step to another and a slider compares the two. **C** again stops.
+- **Fit** (or **F**) in the header makes the images as big as the picker allows, so a handful of images fill the screen. The picker remembers it.
+- **Enter** or **Keep N picked** sends the picks on. **Keep all** sends everything. **Stop branch** stops the nodes after this one; the rest of the run finishes normally.
+- A short chime plays when the picker opens, and the tab title starts with **● Pick images** while something waits. Turn the chime off under **Settings → Wildcard Pipeline → Runtime behavior → Image Filter sound**. Turn on **Image Filter desktop notification** there to also get a system notification while the tab is in the background.
+- **Escape** or the − button tucks the picker away. A "waiting" pill stays at the bottom of the screen and reopens it with your picks still there.
+
+## Labels, sweep grid and Send to Loop
+
+- With a Context Loop, each frame is labelled with its number and the options its sweep pinned, for example `#3 · red · pencil`. Hover a label for the frame's seed and prompt.
+- A sweep of two or more wildcards opens as a **grid**. The bar above it picks which wildcard goes on **Rows** and which on **Columns** (⇄ swaps them); any others **Split by**, one small grid per value. Click a row, column or group name to pick all of it. **Frames** in the header switches back to the list.
+- **Send to Loop** writes your picks back to the loop: picked frames get their seeds locked (when the loop overrides seeds) and every other frame is bypassed, so the next run repeats only what you kept.
+
+## Refine before it goes on
+
+In the zoom, the **Refine** panel edits the frame's prompts and paints a mask for the upscaler. Tiles show ✎ for an edited prompt and ◐ for a painted mask.
+
+- An edited prompt replaces the text output. With a CLIP wired into **clip**, the conditioning is re-encoded to match; without one it stays as it was, and the panel says so.
+- With **Same shape** a frame's picks go on together, so a prompt edit covers the whole frame. With **One per image** it covers just that image.
+- **M** or **Paint** opens the mask painter: brush, eraser, size, invert and clear. The mask goes to the **masks** output, resized to the image. Images you don't paint keep the incoming mask, or an empty one when nothing is wired in.
+
+![How the picks carry over](images/how-picks-carry-over.webp)
+
+## Settings on the node
+
+- **Mode**: **Pause & pick** asks every run. **Reuse last picks** keeps the same picks without asking, and asks again when they no longer fit (for example the batch size changed). **Pass all** lets everything through.
+- **Send picks as**: **Same shape** keeps each frame's picks together as one batch. **One per image** sends every pick as its own item, with its own copy of the frame's prompt, conditioning and Context.
+- **Timeout**: seconds to wait. 0 waits until you answer. After a timeout it keeps all, keeps the first image, or stops the branch.
+
+## Tips
+
+- The **LAST RUN** strip shows what the last run kept.
+- Cancelling the run while the picker is open closes it.
+- Use the **picks** output in a filename or a note to remember which images you picked.

docs/help/WP_ModelInfo.md

@@ -0,0 +1,37 @@
+# WP Model Info
+
+Names the loaded checkpoint so your rules can branch on it. Writes three variables into the Context:
+
+- `$model_family`: the architecture, read from the model itself (`sd15`, `sdxl`, `flux`, `sd3`, …).
+- `$model_variant`: the fine-tune line, read from the file name by the variant rules (`pony`, `illustrious`, `noobai`, `animagine`, or empty when nothing matches).
+- `$model_name`: the file name without folders or extension.
+
+Pony and Illustrious are both SDXL underneath, so only the file name can tell them apart.
+
+## Inputs
+
+- **upstream** *(optional)*: an existing Context to extend. Only nodes **after** Model Info see its variables, so put it first in the chain.
+- **model** *(optional)*: the MODEL from your checkpoint loader. Gives the family, and the node follows the wire back to the loader to read its file name (through LoRA loaders and other model patches).
+
+## The widget
+
+- **Detected** shows the three values and where each comes from. The variant and name update as soon as you change the loader's checkpoint; the family needs the loaded model, so it shows after the first run.
+- The **globe** on a row decides whether the Assembler can use that variable. All three start internal: later rules read them, but the Assembler leaves them out of the prompt and its variable chips. Click the globe to use one in the Assembler, for example `$model_variant` in a file-name prefix.
+- Click the **pin** on a row to use your own value instead, for example a file name when no model is wired, or a variant to try your Pony rules without switching checkpoint. Click it again to go back to detection.
+- **Variant rules** are `variant` + `pattern` rows. The first pattern found in the file name sets `$model_variant`, and its row lights up. Case-insensitive, `|` separates alternatives. A broken row is outlined in red and skipped (WP Debug says why). **Reset** puts the shipped rules back.
+
+## Output
+
+- **context**: the upstream Context plus the three variables. To use a value outside the pipeline, turn its globe off and put it in an Assembler template.
+
+## How to use
+
+1. Wire **Load Checkpoint → MODEL** into **model**, and Model Info's **context** into your first WP Context.
+2. Branch on `$model_variant` in a derivation. The derivation editor's **LoRA by model** button adds a ready-made rule that sets `$loras` per variant; put `$loras` in your Assembler template.
+3. To drive a **constraint** from the model, make a wildcard (say "Model") with options `pony` and `illustrious`, and in its node settings set **Match variable** to `model_variant`. It then picks the option equal to the detected variant, and any constraint can use it as its source.
+
+## Tips
+
+- If a node that loads LoRAs from the prompt sits on the model, take MODEL from **before** it, or the graph loops.
+- A wildcard set to **Match variable** uses its fallback option when no option matches; without one it rolls as usual and WP Debug says why.
+- WP Debug's trace shows each value and where it came from (model, loader, rules or pinned).

docs/help/WP_PromptAssembler.md

@@ -6,10 +6,21 @@ Fill-in-the-blank prompt template. Anywhere you write `$variable`, the assembler
 
 - **context** — `PIPELINE_CONTEXT` from any WP node.
 - **template** — your prompt text. Use `$varname` to reference bound values.
+- **negative_template** — optional negative template (collapsible section under the preview). `$negatives` marks where the collected negative words go; it reads `$vars` too.
 
-## Output
+## Outputs
 
 - **prompt** — the resolved STRING. Feed into CLIP encoders, WP Prompt Cleaner, etc.
+- **negative** — the negative words of every variable the template rendered, filled into the negative template. Feed into your negative CLIP encoder.
+
+## Negative output
+
+Wildcard options, fixed values, combines, derivation "Add to negative" actions and Injector rows can carry negative words for the variable they set. The negative output only takes the words of variables this template actually rendered, so a detailer Assembler that renders just `$face` gets only the face words. Internal variables add nothing.
+
+- `lowres, bad anatomy, $negatives` puts the collected words at the slot.
+- An empty negative template outputs just the collected words.
+- A negative template without `$negatives` gets them appended at the end.
+- Repeated tags are dropped (case-insensitive, `(blurry:1.2)` counts as `blurry`), including tags already in the negative template.
 
 ## How to use
 

docs/help/WP_PromptCleaner.md

@@ -1,14 +1,20 @@
 # WP Prompt Cleaner
 
-Drops duplicate tags, strips orphan punctuation, filters blocklisted words. Operates on the prompt string alone — no context input needed.
+Drops duplicate tags, strips orphan punctuation, removes empty `()` groups, merges nested weights, tidies LoRA tags and filters blocklisted words. Operates on the prompt string alone — no context input needed.
 
 ## Inputs
 
 - **prompt** — STRING from any source (typically a WP Prompt Assembler).
+- **negative** — optional STRING (wire-only), e.g. the Assembler's negative output.
 
-## Output
+## Outputs
 
 - **prompt** — the cleaned STRING.
+- **negative** — the cleaned negative (empty when the negative input is unwired).
+
+## Cleaning the negative
+
+The RULES list has a second checkbox column for the negative. Its defaults match the prompt column's (gentle: whitespace only), except fuzzy dedupe and blocklist off, since near-duplicates in a negative are usually deliberate and blocklisted words often belong there. **Drop negative tags also in prompt** (off by default) removes a negative tag the prompt also asks for; either way the run stats name the overlap.
 
 ## How to use
 
@@ -27,11 +33,21 @@ Drops duplicate tags, strips orphan punctuation, filters blocklisted words. Oper
 | Preset | Rules |
 |---|---|
 | gentle | whitespace |
-| balanced | whitespace, punctuation, tag dedupe |
-| aggressive | whitespace, punctuation, tag dedupe, fuzzy dedupe |
+| balanced | empty groups, LoRA spacing, whitespace, punctuation, tag dedupe |
+| aggressive | empty groups, merge weights, LoRA spacing, whitespace, punctuation, tag dedupe, fuzzy dedupe |
 
 Blocklist auto-enables when its entries are non-empty.
 
+## Prompt syntax rules
+
+These read the prompt the way ComfyUI does, and work in both modes.
+
+- **empty groups** — removes brackets with nothing inside: `()`, `[]`, `( , )`, `(:1.2)`, and groups left empty once those go. `red (), dress` → `red, dress`. The usual source is a weighted ref that resolved to nothing: `(@{hat}:1.2)` → `(:1.2)`.
+- **merge weights** — folds stacked weights into one group by multiplying them, as ComfyUI does (a bare `( )` counts as 1.1): `((a:1.1):1.2)` → `(a:1.32)`, `(((a)))` → `(a:1.33)`. A weight of 1 is unwrapped: `(a:1.0)` → `a`. Only merges when the inner group is everything inside the outer one (`((a:1.1), b:1.2)` stays), and rounds to 2 decimals. `[ ]` is not a weight in ComfyUI, so it's never merged.
+- **LoRA spacing** — `< lora : x : 0.8 >` → `<lora:x:0.8>`, `girl<lora:x:1>smile` → `girl <lora:x:1> smile`. Also covers lyco, locon, hypernet and `<embedding:…>`. Spaces inside a file name stay.
+
+Escaped `\(` `\)` are literal and left alone, LoRA and embedding names are never edited, and if the brackets don't balance the bracket rules leave the prompt exactly as written.
+
 ## Blocklist
 
 Click **Blocklist…** to open the editor. Two modes:

docs/network-access.md

@@ -0,0 +1,41 @@
+# Network access
+
+Wildcard Pipeline runs offline. Generating prompts, the canvas nodes and the
+library manager never touch the network. These are the only outbound requests
+it makes:
+
+| What | When | Where to |
+| --- | --- | --- |
+| Update check | When the manager opens (turn off under Settings → Updates), or when you click **Check now** | GitHub releases API |
+| Community tab | Only when you open the **Community** page in the manager | `wp.dumiflex.dev` |
+| Booru tag list for value autocomplete | Only when you click **Download** under Settings → Tag autocomplete | `github.com` → `objects.githubusercontent.com`, our own release asset |
+
+Delete the downloaded tag file and the autocomplete feature simply turns off.
+
+## How the tag-list download is locked down
+
+ComfyUI serves its API without authentication, so the download endpoint is
+built with nothing a caller can steer:
+
+- **The URL is a constant.** There is no URL parameter (the request body is
+  ignored), so it cannot be pointed at your internal network or a cloud
+  metadata address.
+- **Redirects are checked at every hop** against a fixed host list, because
+  GitHub serves release assets via a CDN. A redirect anywhere else is refused
+  mid-chain.
+- **The destination is computed server-side** from ComfyUI's user directory
+  plus a fixed filename. No caller input reaches the path, and a symlink
+  sitting at that path is refused rather than followed.
+- **The response is size-capped while streaming**, so a hostile or corrupted
+  reply cannot fill your disk. `Content-Length` is checked but never trusted
+  alone.
+- **One download at a time**, so the endpoint cannot be used to start many
+  large fetches at once.
+- **The file is parsed before it replaces anything.** A reply that is not a
+  readable tag list leaves your existing one untouched, and the final move is
+  atomic.
+
+The reasoning is kept next to the code in
+[`wp_api/_tag_download.py`](../wp_api/_tag_download.py), and each restriction
+has a test in
+[`tests/wp_api/test_tag_download.py`](../tests/wp_api/test_tag_download.py).

engine/cascade/fixers.py

@@ -41,6 +41,33 @@ from engine.syntax.subcat_filter import ParseError as _ParseError
 from engine.syntax.subcat_filter import parse as _parse_subcat
 from engine.syntax.subcat_filter import reads_as as _reads_as
 
+
+def derivation_actions(payload: Any) -> list[tuple[str, dict[str, Any]]]:
+    """Every action dict of a derivation payload with its path: each branch's
+    ``action`` and ``extra_actions`` (THEN ... AND ...), the ``else`` clause's
+    too, and the legacy ``actions`` list older rows may still carry. The
+    dicts are the payload's own, so a fixer can rewrite them in place."""
+    out: list[tuple[str, dict[str, Any]]] = []
+    rules = payload.get("rules") if isinstance(payload, dict) else None
+    for ri, rule in enumerate(rules if isinstance(rules, list) else []):
+        if not isinstance(rule, dict):
+            continue
+        clauses: list[tuple[str, Any]] = [
+            (f"rules[{ri}].branches[{bi}]", b)
+            for bi, b in enumerate(rule.get("branches") or [])
+        ]
+        clauses.append((f"rules[{ri}].else", rule.get("else")))
+        for where, clause in clauses:
+            if not isinstance(clause, dict):
+                continue
+            if isinstance(clause.get("action"), dict):
+                out.append((f"{where}.action", clause["action"]))
+            for key in ("extra_actions", "actions"):
+                for ai, action in enumerate(clause.get(key) or []):
+                    if isinstance(action, dict):
+                        out.append((f"{where}.{key}[{ai}]", action))
+    return out
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------
@@ -327,26 +354,24 @@ def fix_wildcard_delete(
         changed = False
 
         if t == "wildcard":
+            # `negative` (send-to-negative) holds refs with the same grammar.
             for opt in new_payload.get("options") or []:
-                v = opt.get("value")
-                if isinstance(v, str):
-                    new_v = _strip_whole_ref_in_string(v, wildcard_id)
-                    if new_v != v:
-                        opt["value"] = new_v
-                        changed = True
+                for field in ("value", "negative"):
+                    v = opt.get(field)
+                    if isinstance(v, str):
+                        new_v = _strip_whole_ref_in_string(v, wildcard_id)
+                        if new_v != v:
+                            opt[field] = new_v
+                            changed = True
 
         elif t == "derivation":
-            for rule in new_payload.get("rules") or []:
-                for branch in rule.get("branches") or []:
-                    for action in branch.get("actions") or []:
-                        if not isinstance(action, dict):
-                            continue
-                        for k, v in list(action.items()):
-                            if isinstance(v, str):
-                                new_v = _strip_whole_ref_in_string(v, wildcard_id)
-                                if new_v != v:
-                                    action[k] = new_v
-                                    changed = True
+            for _path, action in derivation_actions(new_payload):
+                for k, v in list(action.items()):
+                    if isinstance(v, str):
+                        new_v = _strip_whole_ref_in_string(v, wildcard_id)
+                        if new_v != v:
+                            action[k] = new_v
+                            changed = True
 
         if changed:
             touched.append(_deepcopy_row(m))
@@ -417,13 +442,15 @@ def fix_subcat_delete(
 
         elif t == "wildcard" and m["id"] != wildcard_id:
             # Strip @{wildcard_id:subcat_name} text refs from option values
+            # `negative` (send-to-negative) holds refs with the same grammar.
             for opt in new_payload.get("options") or []:
-                v = opt.get("value")
-                if isinstance(v, str):
-                    new_v = _strip_subcat_ref_in_string(v, wildcard_id, subcat_name)
-                    if new_v != v:
-                        opt["value"] = new_v
-                        changed = True
+                for field in ("value", "negative"):
+                    v = opt.get(field)
+                    if isinstance(v, str):
+                        new_v = _strip_subcat_ref_in_string(v, wildcard_id, subcat_name)
+                        if new_v != v:
+                            opt[field] = new_v
+                            changed = True
 
         if changed:
             touched.append(_deepcopy_row(m))
@@ -496,13 +523,15 @@ def fix_subcat_rename(
 
         elif t == "wildcard" and m["id"] != wildcard_id:
             # Rewrite @{wildcard_id:old_name} → @{wildcard_id:new_name}
+            # `negative` (send-to-negative) holds refs with the same grammar.
             for opt in new_payload.get("options") or []:
-                v = opt.get("value")
-                if isinstance(v, str):
-                    new_v = _rewrite_subcat_ref_in_string(v, wildcard_id, old_name, new_name)
-                    if new_v != v:
-                        opt["value"] = new_v
-                        changed = True
+                for field in ("value", "negative"):
+                    v = opt.get(field)
+                    if isinstance(v, str):
+                        new_v = _rewrite_subcat_ref_in_string(v, wildcard_id, old_name, new_name)
+                        if new_v != v:
+                            opt[field] = new_v
+                            changed = True
 
         if changed:
             touched.append(_deepcopy_row(m))
@@ -560,26 +589,24 @@ def fix_wildcard_rename_name(
         changed = False
 
         if t == "wildcard":
+            # `negative` (send-to-negative) holds refs with the same grammar.
             for opt in new_payload.get("options") or []:
-                v = opt.get("value")
-                if isinstance(v, str):
-                    new_v = _rewrite_ref_name_in_string(v, wildcard_id, new_name)
-                    if new_v != v:
-                        opt["value"] = new_v
-                        changed = True
+                for field in ("value", "negative"):
+                    v = opt.get(field)
+                    if isinstance(v, str):
+                        new_v = _rewrite_ref_name_in_string(v, wildcard_id, new_name)
+                        if new_v != v:
+                            opt[field] = new_v
+                            changed = True
 
         elif t == "derivation":
-            for rule in new_payload.get("rules") or []:
-                for branch in rule.get("branches") or []:
-                    for action in branch.get("actions") or []:
-                        if not isinstance(action, dict):
-                            continue
-                        for k, v in list(action.items()):
-                            if isinstance(v, str):
-                                new_v = _rewrite_ref_name_in_string(v, wildcard_id, new_name)
-                                if new_v != v:
-                                    action[k] = new_v
-                                    changed = True
+            for _path, action in derivation_actions(new_payload):
+                for k, v in list(action.items()):
+                    if isinstance(v, str):
+                        new_v = _rewrite_ref_name_in_string(v, wildcard_id, new_name)
+                        if new_v != v:
+                            action[k] = new_v
+                            changed = True
 
         if changed:
             touched.append(_deepcopy_row(m))
@@ -668,46 +695,51 @@ def fix_combine_output_var_rename(
                 new_payload["output_var"] = new_name
                 changed = True
             # Also rewrite $old in its own template in case it self-references
-            tpl = new_payload.get("template", "")
-            if isinstance(tpl, str):
-                new_tpl = _rewrite_var_in_string(tpl, old_name, new_name)
-                if new_tpl != tpl:
-                    new_payload["template"] = new_tpl
-                    changed = True
-
-        elif t == "wildcard":
-            for opt in new_payload.get("options") or []:
-                v = opt.get("value")
-                if isinstance(v, str):
-                    new_v = _rewrite_var_in_string(v, old_name, new_name)
-                    if new_v != v:
-                        opt["value"] = new_v
+            # The combine's own `negative` reads $vars like its template.
+            for field in ("template", "negative"):
+                tpl = new_payload.get(field, "")
+                if isinstance(tpl, str):
+                    new_tpl = _rewrite_var_in_string(tpl, old_name, new_name)
+                    if new_tpl != tpl:
+                        new_payload[field] = new_tpl
                         changed = True
 
+        elif t == "wildcard":
+            # `negative` (send-to-negative) holds refs with the same grammar.
+            for opt in new_payload.get("options") or []:
+                for field in ("value", "negative"):
+                    v = opt.get(field)
+                    if isinstance(v, str):
+                        new_v = _rewrite_var_in_string(v, old_name, new_name)
+                        if new_v != v:
+                            opt[field] = new_v
+                            changed = True
+
         elif t == "derivation":
-            for rule in new_payload.get("rules") or []:
-                for branch in rule.get("branches") or []:
-                    for action in branch.get("actions") or []:
-                        if not isinstance(action, dict):
-                            continue
-                        for k in list(action.keys()):
-                            v = action[k]
-                            if k == "set_var" and v == old_name:
-                                action[k] = new_name
-                                changed = True
-                            elif isinstance(v, str):
-                                new_v = _rewrite_var_in_string(v, old_name, new_name)
-                                if new_v != v:
-                                    action[k] = new_v
-                                    changed = True
+            for _path, action in derivation_actions(new_payload):
+                for k in list(action.keys()):
+                    v = action[k]
+                    # `target_var` names the variable bare (no `$`); the
+                    # legacy `set_var` did too.
+                    if k in ("set_var", "target_var") and isinstance(v, str) \
+                            and v.lstrip("$") == old_name:
+                        action[k] = new_name
+                        changed = True
+                    elif isinstance(v, str):
+                        new_v = _rewrite_var_in_string(v, old_name, new_name)
+                        if new_v != v:
+                            action[k] = new_v
+                            changed = True
 
         elif t == "combine" and m["id"] != combine_id:
-            tpl = new_payload.get("template", "")
-            if isinstance(tpl, str):
-                new_tpl = _rewrite_var_in_string(tpl, old_name, new_name)
-                if new_tpl != tpl:
-                    new_payload["template"] = new_tpl
-                    changed = True
+            # The combine's own `negative` reads $vars like its template.
+            for field in ("template", "negative"):
+                tpl = new_payload.get(field, "")
+                if isinstance(tpl, str):
+                    new_tpl = _rewrite_var_in_string(tpl, old_name, new_name)
+                    if new_tpl != tpl:
+                        new_payload[field] = new_tpl
+                        changed = True
 
         if changed:
             touched.append(_deepcopy_row(m))

engine/cascade/scan.py

@@ -17,7 +17,7 @@ import re
 import sqlite3
 from typing import Any
 
-from engine.cascade.fixers import collect_tags
+from engine.cascade.fixers import collect_tags, derivation_actions
 from engine.db.repositories import ModuleRepository
 
 # 4-segment ref: ``@{8hex [#name] [:expr] [!null]}`` — uuid + optional
@@ -67,38 +67,28 @@ def _scan_wildcard_delete(conn: sqlite3.Connection, wildcard_id: str) -> list[di
         if t == "wildcard":
             opts = p.get("options") or []
             for idx, opt in enumerate(opts):
-                v = opt.get("value")
-                if not isinstance(v, str):
-                    continue
-                if any(m.group(1) == wildcard_id for m in _REF_REGEX.finditer(v)):
-                    out.append(_ref_entry("wildcard", m, f"options[{idx}].value"))
+                hit = next((
+                    f for f in ("value", "negative")
+                    if isinstance(opt.get(f), str) and any(
+                        r.group(1) == wildcard_id
+                        for r in _REF_REGEX.finditer(opt[f])
+                    )
+                ), None)
+                if hit:
+                    out.append(_ref_entry("wildcard", m, f"options[{idx}].{hit}"))
                     break
             continue
 
         if t == "derivation":
-            found = False
-            rules = p.get("rules") or []
-            for ri, rule in enumerate(rules):
-                if found:
+            for path, action in derivation_actions(p):
+                if any(
+                    isinstance(v, str) and any(
+                        r.group(1) == wildcard_id for r in _REF_REGEX.finditer(v)
+                    )
+                    for v in action.values()
+                ):
+                    out.append(_ref_entry("derivation", m, path))
                     break
-                for bi, branch in enumerate(rule.get("branches") or []):
-                    if found:
-                        break
-                    for ai, action in enumerate(branch.get("actions") or []):
-                        if not isinstance(action, dict):
-                            continue
-                        for v in action.values():
-                            if isinstance(v, str) and any(
-                                m.group(1) == wildcard_id for m in _REF_REGEX.finditer(v)
-                            ):
-                                out.append(_ref_entry(
-                                    "derivation", m,
-                                    f"rules[{ri}].branches[{bi}].actions[{ai}]",
-                                ))
-                                found = True
-                                break
-                        if found:
-                            break
             continue
 
     # Bundles intentionally excluded from the wildcard-delete impact
@@ -150,9 +140,10 @@ def _scan_subcat(
         if m["type"] == "wildcard" and m["id"] != wildcard_id:
             opts = (m.get("payload") or {}).get("options") or []
             for idx, opt in enumerate(opts):
-                v = opt.get("value")
-                if not isinstance(v, str):
-                    continue
+                v = " ".join(
+                    opt[f] for f in ("value", "negative")
+                    if isinstance(opt.get(f), str)
+                )
                 # SP1: `sub` is the raw `:expr` segment (the 4-segment regex
                 # already split `!null` into the null group). A boolean filter
                 # like `warm or cold` references multiple tags, so parse it and
@@ -189,41 +180,30 @@ def _scan_combine_output_var(
             continue
 
         if t == "derivation":
-            found = False
-            for ri, rule in enumerate(p.get("rules") or []):
-                if found:
-                    break
-                for bi, branch in enumerate(rule.get("branches") or []):
-                    if found:
+            for path, action in derivation_actions(p):
+                hit = None
+                for k, v in action.items():
+                    # The variable read in a string value (`$name`,
+                    # `$name.neg`, ...) or named as the action's target.
+                    if isinstance(v, str) and var_name in _VAR_REGEX.findall(v):
+                        hit = f"{path}.{k}"
                         break
-                    for ai, action in enumerate(branch.get("actions") or []):
-                        if not isinstance(action, dict):
-                            continue
-                        for k, v in action.items():
-                            # Match as variable ref in a string value
-                            if isinstance(v, str) and var_name in _VAR_REGEX.findall(v):
-                                out.append(_ref_entry(
-                                    "derivation", m,
-                                    f"rules[{ri}].branches[{bi}].actions[{ai}].{k}",
-                                ))
-                                found = True
-                                break
-                            # Or match as the explicit set_var target
-                            if k == "set_var" and v == var_name:
-                                out.append(_ref_entry(
-                                    "derivation", m,
-                                    f"rules[{ri}].branches[{bi}].actions[{ai}].set_var",
-                                ))
-                                found = True
-                                break
-                        if found:
-                            break
+                    if k in ("set_var", "target_var") and isinstance(v, str) \
+                            and v.lstrip("$") == var_name:
+                        hit = f"{path}.{k}"
+                        break
+                if hit:
+                    out.append(_ref_entry("derivation", m, hit))
+                    break
             continue
 
         if t == "combine":
-            tpl = p.get("template", "")
-            if isinstance(tpl, str) and var_name in _VAR_REGEX.findall(tpl):
-                out.append(_ref_entry("combine", m, "payload.template"))
+            # A combine's own `negative` reads $vars like its template.
+            for field in ("template", "negative"):
+                tpl = p.get(field, "")
+                if isinstance(tpl, str) and var_name in _VAR_REGEX.findall(tpl):
+                    out.append(_ref_entry("combine", m, f"payload.{field}"))
+                    break
             continue
 
     return out

engine/cleaner/pipeline.py

@@ -21,8 +21,19 @@ from engine.cleaner.types import RuleId, RunReport
 
 INTENSITY_TO_RULES: dict[str, list[RuleId]] = {
     "gentle": ["whitespace"],
-    "balanced": ["whitespace", "punctuation", "dedupe_exact"],
+    # Empty groups + LoRA spacing never change what a prompt means; merging
+    # weights rewrites how it reads, so it waits for aggressive.
+    "balanced": [
+        "empty_groups",
+        "lora_spacing",
+        "whitespace",
+        "punctuation",
+        "dedupe_exact",
+    ],
     "aggressive": [
+        "empty_groups",
+        "merge_weights",
+        "lora_spacing",
         "whitespace",
         "punctuation",
         "dedupe_exact",
@@ -31,8 +42,36 @@ INTENSITY_TO_RULES: dict[str, list[RuleId]] = {
 }
 
 
-def _effective_rules(intensity: str, overrides: dict[str, bool]) -> set[RuleId]:
-    base: set[RuleId] = set(INTENSITY_TO_RULES.get(intensity, INTENSITY_TO_RULES["balanced"]))
+#: Send-to-negative: the negative column's defaults per preset. Fuzzy dedupe
+#: stays off (near-duplicates in a negative, "bad hand" / "bad hands", are
+#: usually deliberate) and the blocklist never auto-enables (it keeps words
+#: OUT of the prompt, and those are often the words a negative names).
+INTENSITY_TO_NEG_RULES: dict[str, list[RuleId]] = {
+    "gentle": ["whitespace"],
+    "balanced": [
+        "empty_groups",
+        "lora_spacing",
+        "whitespace",
+        "punctuation",
+        "dedupe_exact",
+    ],
+    "aggressive": [
+        "empty_groups",
+        "merge_weights",
+        "lora_spacing",
+        "whitespace",
+        "punctuation",
+        "dedupe_exact",
+    ],
+}
+
+
+def _effective_rules(
+    intensity: str,
+    overrides: dict[str, bool],
+    table: dict[str, list[RuleId]] = INTENSITY_TO_RULES,
+) -> set[RuleId]:
+    base: set[RuleId] = set(table.get(intensity, table["balanced"]))
     for rule_id, enabled in overrides.items():
         if enabled:
             base.add(rule_id)  # type: ignore[arg-type]
@@ -70,3 +109,45 @@ class PromptCleaner:
             out = result["text"]
             report[rule_id] = result["stats"]
         return {"text": out, "report": report}
+
+    def run_negative(
+        self,
+        text: str,
+        config: dict[str, Any] | None = None,
+        prompt: str = "",
+    ) -> dict[str, Any]:
+        """Clean the negative with the negative column's rules.
+
+        `negative_rules_override` is the column's per-rule toggles; the
+        blocklist entries are shared with the prompt column. The report
+        always names tags the negative shares with `prompt` (the model is
+        told to draw them and not draw them); `drop_prompt_overlap` removes
+        them from the negative.
+        """
+        cfg = config or {}
+        mode = cfg.get("mode", "tags")
+        intensity = cfg.get("intensity", "balanced")
+        overrides: dict[str, bool] = dict(cfg.get("negative_rules_override") or {})
+        active = _effective_rules(intensity, overrides, INTENSITY_TO_NEG_RULES)
+        out = text
+        report: dict[str, Any] = {}
+        for rule_id, fn in RULE_REGISTRY:
+            if rule_id not in active:
+                continue
+            result = fn(out, mode, cfg)
+            out = result["text"]
+            report[rule_id] = result["stats"]
+
+        from engine.negatives import split_tags, tag_key  # noqa: PLC0415
+
+        prompt_keys = {tag_key(t) for t in split_tags(prompt)}
+        tags = split_tags(out)
+        overlap = [t for t in tags if tag_key(t) in prompt_keys]
+        if overlap:
+            report["prompt_overlap"] = {
+                "tags": overlap,
+                "dropped": bool(cfg.get("drop_prompt_overlap")),
+            }
+            if cfg.get("drop_prompt_overlap"):
+                out = ", ".join(t for t in tags if tag_key(t) not in prompt_keys)
+        return {"text": out, "report": report}

engine/cleaner/rules/__init__.py

@@ -12,14 +12,21 @@ from collections.abc import Callable
 from engine.cleaner.rules import (
     blocklist,
     dedupe,
+    lora,
     punctuation,
+    syntax,
     whitespace,
 )
 from engine.cleaner.types import RuleId, RuleResult
 
 ApplyFn = Callable[[str, str, dict], RuleResult]
 
+# The bracket and LoRA rules run first: the commas and spaces they leave
+# behind are then tidied by whitespace / punctuation in the same run.
 RULE_REGISTRY: list[tuple[RuleId, ApplyFn]] = [
+    ("empty_groups", syntax.apply_empty_groups),
+    ("merge_weights", syntax.apply_merge_weights),
+    ("lora_spacing", lora.apply),
     ("whitespace", whitespace.apply),
     ("punctuation", punctuation.apply),
     ("dedupe_exact", dedupe.apply_exact),

engine/cleaner/rules/lora.py

@@ -0,0 +1,61 @@
+"""LoRA tag spacing.
+
+Tidies `<lora:name:0.8>` style tags (and the lyco / locon / hypernet /
+embedding siblings that share the shape, see engine/cleaner/atoms.py):
+
+  * inside the tag, spaces at the edges of each `:` segment go
+    (`< lora : name : 0.8 >` -> `<lora:name:0.8>`). Spaces INSIDE a
+    segment stay, so a file name with spaces still resolves;
+  * outside, a tag jammed against a word gets one space on that side
+    (`girl<lora:x:1>smile` -> `girl <lora:x:1> smile`), and spaces
+    between a tag and a following comma go (`<lora:x:1> , hat` ->
+    `<lora:x:1>, hat`).
+
+Reports `stats.tidied` = tags changed.
+"""
+from __future__ import annotations
+
+import re
+
+from engine.cleaner.types import RuleResult
+
+_TAG_RE = re.compile(
+    r"<\s*(?P<kind>lora|lyco|locon|hypernet|embedding)\s*:(?P<rest>[^<>]*)>",
+    re.IGNORECASE,
+)
+# A tag needs a space from a neighbour unless that neighbour is whitespace,
+# a separator or a bracket edge.
+_NO_SPACE_BEFORE = set(" \t\n,([{")
+_NO_SPACE_AFTER = set(" \t\n,)]}")
+
+
+def apply(text: str, mode: str, config: dict) -> RuleResult:
+    tidied = 0
+    out: list[str] = []
+    pos = 0
+    for m in _TAG_RE.finditer(text):
+        start, end = m.start(), m.end()
+        before = text[pos:start]
+        segments = [s.strip() for s in m.group("rest").split(":")]
+        tag = f"<{m.group('kind')}:{':'.join(segments)}>"
+        changed = tag != m.group(0)
+        # Space on the left when the tag touches a word (or another tag).
+        prev = (out[-1][-1:] if not before and out else before[-1:]) or ""
+        if prev and prev not in _NO_SPACE_BEFORE:
+            before += " "
+            changed = True
+        out.append(before + tag)
+        pos = end
+        # Spaces between the tag and a following comma.
+        after = text[pos:]
+        stripped = after.lstrip(" \t")
+        if stripped.startswith(",") and stripped != after:
+            pos += len(after) - len(stripped)
+            changed = True
+        elif after and after[0] not in _NO_SPACE_AFTER and not _TAG_RE.match(after):
+            out.append(" ")
+            changed = True
+        if changed:
+            tidied += 1
+    out.append(text[pos:])
+    return {"text": "".join(out) if tidied else text, "stats": {"tidied": tidied}}

engine/cleaner/rules/syntax.py

@@ -0,0 +1,243 @@
+"""Bracket-aware rules: empty groups + nested weight merging.
+
+Both rules read the prompt as ComfyUI's weight grammar sees it: `( )`
+groups (each bare group is a 1.1 weight, `(x:w)` sets one, nested weights
+multiply) and `[ ]` groups (not a weight in ComfyUI, but still emptied).
+
+The scanner keeps three things as literal text it never looks inside:
+
+  * escapes — `\\(` and `\\)` are literal parens (`artist \\(style\\)`);
+  * angle tags — `<lora:name:0.8>` and siblings are file references;
+  * anything after a bracket that doesn't balance — see below.
+
+If the brackets don't balance (a stray `(` or `)`), the rules return the
+prompt exactly as written: guessing which paren the author meant could
+re-weight half the prompt.
+
+`empty_groups` drops `()`, `[]`, `( , )`, `(:1.2)` and groups left empty
+once their own empty children are gone, then closes the seam the group
+left (`red (), dress` -> `red, dress`), the way the resolver's join tidy
+closes the seam an empty `@{ref}` leaves.
+
+`merge_weights` folds a group whose whole content is another `( )` group
+into one group with the product weight (`((a:1.1):1.2)` -> `(a:1.32)`,
+`((a))` -> `(a:1.21)`), and unwraps a group whose weight is exactly 1
+(`(a:1.0)` -> `a`). Weights are rounded to 2 decimals. A group with
+anything beside the inner group (`((a:1.1), b:1.2)`) is left alone, since
+merging would change what the outer weight applies to.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from engine.cleaner.types import RuleResult
+
+_OPEN = {"(": ")", "[": "]"}
+_CLOSE = {")", "]"}
+
+# `:1.2` at the end of a group's content. ComfyUI splits on the LAST colon
+# and only treats the tail as a weight when it parses as a number.
+_WEIGHT_TAIL = re.compile(r"^(?P<body>.*?)\s*:\s*(?P<w>[-+]?(?:\d+\.?\d*|\.\d+))\s*$", re.DOTALL)
+_EMPTY_TAIL = re.compile(r"^[\s,]*(?::\s*[-+]?(?:\d+\.?\d*|\.\d+)\s*)?[\s,]*$")
+
+#: Placeholder for a removed group until its seam is closed. A control char
+#: no prompt contains.
+_GAP = "\x00"
+_HWS = " \t"
+
+
+@dataclass
+class _Group:
+    open: str
+    children: list[str | _Group] = field(default_factory=list)
+    #: Built by a merge, so folding it again isn't a second merge.
+    merged: bool = False
+
+
+def _parse(text: str) -> list[str | _Group] | None:
+    """Split `text` into literal runs and bracket groups. None when the
+    brackets don't balance."""
+    root: list[str | _Group] = []
+    stack: list[_Group] = []
+    buf: list[str] = []
+
+    def flush() -> None:
+        if buf:
+            (stack[-1].children if stack else root).append("".join(buf))
+            buf.clear()
+
+    i, n = 0, len(text)
+    while i < n:
+        ch = text[i]
+        if ch == "\\" and i + 1 < n:
+            buf.append(text[i : i + 2])
+            i += 2
+            continue
+        if ch == "<":
+            end = text.find(">", i + 1)
+            nxt = text.find("<", i + 1)
+            if end != -1 and (nxt == -1 or nxt > end):
+                buf.append(text[i : end + 1])
+                i = end + 1
+                continue
+        if ch in _OPEN:
+            flush()
+            group = _Group(ch)
+            (stack[-1].children if stack else root).append(group)
+            stack.append(group)
+        elif ch in _CLOSE:
+            if not stack or _OPEN[stack[-1].open] != ch:
+                return None
+            flush()
+            stack.pop()
+        else:
+            buf.append(ch)
+        i += 1
+    if stack:
+        return None
+    flush()
+    return root
+
+
+def _render(nodes: list[str | _Group]) -> str:
+    return "".join(n if isinstance(n, str) else _render_group(n) for n in nodes)
+
+
+def _render_group(g: _Group) -> str:
+    return g.open + _render(g.children) + _OPEN[g.open]
+
+
+# ---------------------------------------------------------------- empty groups
+
+
+def _drop_empty(nodes: list[str | _Group], counter: list[int]) -> list[str | _Group]:
+    out: list[str | _Group] = []
+    for node in nodes:
+        if isinstance(node, str):
+            out.append(node)
+            continue
+        node.children = _drop_empty(node.children, counter)
+        inner = _render(node.children).replace(_GAP, "")
+        if _EMPTY_TAIL.match(inner):
+            counter[0] += 1
+            out.append(_GAP)
+        else:
+            out.append(node)
+    return out
+
+
+def _close_gaps(text: str) -> str:
+    """Close the seam each removed group left behind."""
+    while _GAP in text:
+        idx = text.index(_GAP)
+        left = text[:idx].rstrip(_HWS)
+        right = text[idx + 1 :]
+        # Runs of gaps (`() []`) close as one seam.
+        while right.lstrip(_HWS).startswith(_GAP):
+            right = right.lstrip(_HWS)[1:]
+        had_ws = text[:idx] != left or right[:1] in (" ", "\t")
+        right = right.lstrip(_HWS)
+        if not left:
+            if right.startswith(","):
+                right = right[1:].lstrip(_HWS)
+            text = right
+            continue
+        if not right:
+            text = left[:-1].rstrip(_HWS) if left.endswith(",") else left
+            continue
+        if left.endswith(",") and right.startswith(","):
+            right = right[1:].lstrip(_HWS)
+            text = left + (" " if right else "") + right
+            continue
+        if left.endswith(",") and right[0] in ")]":
+            text = left[:-1].rstrip(_HWS) + right
+            continue
+        if left[-1] in "([" and right.startswith(","):
+            text = left + right[1:].lstrip(_HWS)
+            continue
+        joiner = "" if right[0] in ",)]\n" or left[-1] in "([\n" else (" " if had_ws else "")
+        text = left + joiner + right
+    return text
+
+
+def apply_empty_groups(text: str, mode: str, config: dict) -> RuleResult:
+    tree = _parse(text)
+    if tree is None:
+        return {"text": text, "stats": {"removed": 0}}
+    counter = [0]
+    tree = _drop_empty(tree, counter)
+    if not counter[0]:
+        return {"text": text, "stats": {"removed": 0}}
+    return {"text": _close_gaps(_render(tree)), "stats": {"removed": counter[0]}}
+
+
+# --------------------------------------------------------------- merge weights
+
+
+def _fmt(weight: float) -> str:
+    return f"{weight:.2f}".rstrip("0").rstrip(".")
+
+
+def _split_weight(g: _Group) -> tuple[list[str | _Group], float, bool]:
+    """(body nodes, weight, explicit) for a `( )` group. The weight tail can
+    only sit in the group's last literal run."""
+    last = g.children[-1] if g.children else None
+    if isinstance(last, str):
+        m = _WEIGHT_TAIL.match(last)
+        if m and (m.group("body").strip() or len(g.children) > 1):
+            body = [*g.children[:-1], m.group("body")] if m.group("body") else list(g.children[:-1])
+            return body, float(m.group("w")), True
+    return list(g.children), 1.1, False
+
+
+def _only_group(body: list[str | _Group]) -> _Group | None:
+    """The single `( )` group `body` consists of, ignoring whitespace."""
+    groups = [n for n in body if isinstance(n, _Group)]
+    if len(groups) != 1 or groups[0].open != "(":
+        return None
+    if any(isinstance(n, str) and n.strip() for n in body):
+        return None
+    return groups[0]
+
+
+def _merge(nodes: list[str | _Group], counter: list[int]) -> list[str | _Group]:
+    out: list[str | _Group] = []
+    for node in nodes:
+        if isinstance(node, str):
+            out.append(node)
+            continue
+        node.children = _merge(node.children, counter)
+        if node.open != "(":
+            out.append(node)
+            continue
+        body, weight, explicit = _split_weight(node)
+        inner = _only_group(body)
+        changed = False
+        counted = inner is not None and inner.merged
+        while inner is not None:
+            inner_body, inner_w, _ = _split_weight(inner)
+            body, weight, explicit = inner_body, round(weight * inner_w, 6), True
+            changed = True
+            inner = _only_group(body)
+        if explicit and round(weight, 2) == 1:
+            counter[0] += 0 if counted else 1
+            out.extend(body)
+            continue
+        if changed:
+            counter[0] += 0 if counted else 1
+            out.append(_Group("(", [*body, f":{_fmt(weight)}"], merged=True))
+            continue
+        out.append(node)
+    return out
+
+
+def apply_merge_weights(text: str, mode: str, config: dict) -> RuleResult:
+    tree = _parse(text)
+    if tree is None:
+        return {"text": text, "stats": {"merged": 0}}
+    counter = [0]
+    tree = _merge(tree, counter)
+    if not counter[0]:
+        return {"text": text, "stats": {"merged": 0}}
+    return {"text": _render(tree), "stats": {"merged": counter[0]}}

engine/cleaner/types.py

@@ -9,6 +9,9 @@ from __future__ import annotations
 from typing import Any, Literal, TypedDict
 
 RuleId = Literal[
+    "empty_groups",
+    "merge_weights",
+    "lora_spacing",
     "whitespace",
     "punctuation",
     "dedupe_exact",

engine/context.py

@@ -21,6 +21,32 @@ class ContextInternals(TypedDict, total=False):
 Context = dict[str, Any]
 
 
+#: Engine tables the text resolver reads by KEY rather than as variables.
+#: `strip_internals` still drops them — its result is the variable surface, and
+#: anything enumerating it (the assembler's variables panel, debug views) would
+#: list `$__wp_axes__` as a user variable. Callers that need accessor syntax
+#: re-attach them to their own local dict via `with_resolver_tables`.
+RESOLVER_TABLES = ("__wp_axes__", "__wp_picks__", "__wp_negatives__")
+
+
+def with_resolver_tables(
+    stripped: dict[str, Any], source: dict[str, Any]
+) -> dict[str, Any]:
+    """Re-attach the accessor tables to an already-stripped ctx.
+
+    `$var.0` and `$var.AXIS` resolve against `__wp_picks__` / `__wp_axes__`,
+    which `strip_internals` removes along with every other `__` key. Without
+    them the assembler rendered both accessors as literal text while the same
+    template resolved one node upstream. The returned dict is for a resolver
+    call only — never for anything that enumerates variables.
+    """
+    out = dict(stripped)
+    for key in RESOLVER_TABLES:
+        if key in source:
+            out[key] = source[key]
+    return out
+
+
 def strip_internals(ctx: dict[str, Any]) -> dict[str, Any]:
     """Return a copy of ``ctx`` with engine-only + user-flagged-internal keys removed.
 

engine/db/backups.py

@@ -0,0 +1,438 @@
+"""Library database backups: create, list, prune, delete, staged restore.
+
+Backups live in ``<db file parent>/backups/`` — next to the database they
+protect, so moving the library (Settings → Database location) is the only
+thing that separates them, and a user who backs up "the wildcard-pipeline
+folder" gets both.
+
+File names carry everything we need to know about a backup, so there is no
+index file to drift out of sync with the directory::
+
+    wildcard-pipeline-YYYYMMDD-HHMMSS-<reason>[-N].db
+
+(UTC timestamp; ``-N`` only when two backups land in the same second.)
+
+Reasons:
+
+- ``manual``        — the user pressed "Back up now". Never pruned: the user
+  made it deliberately, so only the user deletes it.
+- ``daily``         — the background scheduler (``maybe_daily_backup``).
+- ``pre-migration`` — taken by ``engine/db/migrations.py:migrate`` right
+  before it applies schema changes to an existing library.
+- ``pre-restore``   — the live DB, saved right before a restore overwrote it,
+  so a restore is itself undoable.
+
+Copies go through SQLite's online backup API rather than a file copy: the
+library runs in WAL mode, where committed data can sit in ``-wal`` rather
+than the main file, and a plain copy of the main file would silently lose it.
+
+Restore is staged, like the DB location move: the request only records the
+chosen backup in the sidecar (``engine/db/config.py``), and
+``execute_pending_restore`` swaps the file at the next start, before any
+connection opens. Swapping a SQLite file out from under live connections is
+how databases get corrupted.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import sqlite3
+import tempfile
+import threading
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from engine import prefs
+from engine.db import config as db_config
+from engine.db.connection import resolve_db_path
+
+logger = logging.getLogger(__name__)
+
+BACKUPS_DIRNAME = "backups"
+REASONS = ("manual", "daily", "pre-migration", "pre-restore")
+#: Reasons `prune` may delete. Manual backups are the user's, not ours.
+AUTOMATIC_REASONS = frozenset({"daily", "pre-migration", "pre-restore"})
+DAILY_INTERVAL = timedelta(hours=24)
+SCHEDULER_PERIOD_S = 3600.0
+
+_NAME_RE = re.compile(
+    r"^wildcard-pipeline-(\d{8})-(\d{6})-"
+    r"(manual|daily|pre-migration|pre-restore)(?:-(\d+))?\.db$"
+)
+
+
+class BackupNotFound(LookupError):
+    """The named backup isn't a valid backup file in the backups dir."""
+
+
+def backups_dir(db_path: Path) -> Path:
+    """Where backups of ``db_path`` live. Not created until one is written."""
+    return Path(db_path).parent / BACKUPS_DIRNAME
+
+
+def _parse_name(name: str) -> tuple[datetime, str, int] | None:
+    m = _NAME_RE.fullmatch(name)
+    if not m:
+        return None
+    try:
+        ts = datetime.strptime(m.group(1) + m.group(2), "%Y%m%d%H%M%S")
+    except ValueError:
+        return None
+    return ts.replace(tzinfo=timezone.utc), m.group(3), int(m.group(4) or 1)
+
+
+def _new_backup_path(directory: Path, reason: str, now: datetime | None = None) -> Path:
+    """First free ``wildcard-pipeline-<ts>-<reason>[-N].db`` in ``directory``."""
+    stamp = (now or datetime.now(timezone.utc)).strftime("%Y%m%d-%H%M%S")
+    base = f"wildcard-pipeline-{stamp}-{reason}"
+    candidate = directory / f"{base}.db"
+    n = 2
+    while candidate.exists():
+        candidate = directory / f"{base}-{n}.db"
+        n += 1
+    return candidate
+
+
+def _entry(path: Path) -> dict[str, Any] | None:
+    parsed = _parse_name(path.name)
+    if parsed is None or not path.is_file():
+        return None
+    ts, reason, _ = parsed
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return None
+    return {
+        "name": path.name,
+        "size": size,
+        "created_at": ts.isoformat().replace("+00:00", "Z"),
+        "reason": reason,
+    }
+
+
+def _sort_key(path: Path) -> tuple[datetime, int]:
+    parsed = _parse_name(path.name)
+    assert parsed is not None
+    return parsed[0], parsed[2]
+
+
+def _check_reason(reason: str) -> None:
+    if reason not in REASONS:
+        raise ValueError(f"unknown backup reason {reason!r}; expected one of {REASONS}")
+
+
+def create_backup(
+    db_path: Path,
+    reason: str,
+    *,
+    conn: sqlite3.Connection | None = None,
+) -> dict[str, Any]:
+    """Write a consistent snapshot of ``db_path`` and return its list entry.
+
+    ``conn`` lets a caller that already holds a connection (the migration
+    runner) back up through it instead of opening a second one. The snapshot
+    is written to a temp file and renamed into place, so a half-written
+    backup never shows up in the list.
+    """
+    _check_reason(reason)
+    db_path = Path(db_path)
+    if conn is None and not db_path.is_file():
+        raise FileNotFoundError(f"database {db_path} does not exist")
+    directory = backups_dir(db_path)
+    directory.mkdir(parents=True, exist_ok=True)
+    target = _new_backup_path(directory, reason)
+    fd, tmp_str = tempfile.mkstemp(prefix=".backup-", suffix=".db", dir=str(directory))
+    os.close(fd)
+    tmp = Path(tmp_str)
+    try:
+        src = conn if conn is not None else sqlite3.connect(str(db_path))
+        try:
+            dst = sqlite3.connect(str(tmp))
+            try:
+                src.backup(dst)
+            finally:
+                dst.close()
+        finally:
+            if conn is None:
+                src.close()
+        os.replace(tmp, target)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+    entry = _entry(target)
+    assert entry is not None
+    logger.info("wp_db_backup: wrote %s", target)
+    return entry
+
+
+def _backup_paths(db_path: Path) -> list[Path]:
+    """Valid backup files, newest first."""
+    directory = backups_dir(db_path)
+    if not directory.is_dir():
+        return []
+    paths = [p for p in directory.iterdir() if p.is_file() and _parse_name(p.name)]
+    paths.sort(key=_sort_key, reverse=True)
+    return paths
+
+
+def list_backups(db_path: Path) -> list[dict[str, Any]]:
+    """Every backup of ``db_path``, newest first."""
+    out = []
+    for p in _backup_paths(db_path):
+        e = _entry(p)
+        if e is not None:
+            out.append(e)
+    return out
+
+
+def prune(db_path: Path, keep: int) -> list[str]:
+    """Delete the oldest AUTOMATIC backups beyond ``keep``; return their names.
+
+    Manual backups neither count toward ``keep`` nor get deleted.
+    """
+    keep = max(0, int(keep))
+    automatic = [p for p in _backup_paths(db_path)
+                 if _parse_name(p.name)[1] in AUTOMATIC_REASONS]  # type: ignore[index]
+    removed: list[str] = []
+    for p in automatic[keep:]:
+        try:
+            p.unlink()
+            removed.append(p.name)
+        except OSError:
+            logger.exception("wp_db_backup: could not prune %s", p)
+    return removed
+
+
+def resolve_backup(db_path: Path, name: str) -> Path:
+    """Map a client-supplied backup name to its file, or raise BackupNotFound.
+
+    SECURITY: ``name`` comes from an unauthenticated HTTP request and ends up
+    in ``unlink`` / a file copy over the live DB. It must be a bare file name
+    matching the backup pattern (which admits no separators or ``..``) and
+    must resolve to a file directly inside the backups dir.
+    """
+    if not isinstance(name, str) or _parse_name(name) is None:
+        raise BackupNotFound(name)
+    directory = backups_dir(db_path).resolve()
+    candidate = (directory / name).resolve()
+    if candidate.parent != directory or not candidate.is_file():
+        raise BackupNotFound(name)
+    return candidate
+
+
+def delete_backup(db_path: Path, name: str) -> None:
+    """Delete one backup by name; raises BackupNotFound for anything else."""
+    resolve_backup(db_path, name).unlink()
+
+
+def _newest_age(db_path: Path, now: datetime) -> timedelta | None:
+    paths = _backup_paths(db_path)
+    if not paths:
+        return None
+    return now - _sort_key(paths[0])[0]
+
+
+def maybe_daily_backup(
+    db_path: Path | None = None,
+    *,
+    now: datetime | None = None,
+) -> dict[str, Any] | None:
+    """Take a ``daily`` backup when one is due; return it, or None.
+
+    Due = backups + daily backups enabled, the DB exists, and the newest
+    backup of ANY reason is at least 24h old (a manual backup this morning
+    already covers today).
+    """
+    cfg = prefs.backups()
+    if not (cfg["enabled"] and cfg["daily"]):
+        return None
+    db_path = Path(db_path) if db_path is not None else resolve_db_path()
+    if not db_path.is_file():
+        return None
+    now = now or datetime.now(timezone.utc)
+    age = _newest_age(db_path, now)
+    if age is not None and age < DAILY_INTERVAL:
+        return None
+    entry = create_backup(db_path, "daily")
+    prune(db_path, cfg["keep"])
+    return entry
+
+
+def backup_before_migration(conn: sqlite3.Connection) -> dict[str, Any] | None:
+    """Called by `migrate` before applying pending migrations to a library
+    that already has some. Never raises: a failed backup is logged and the
+    migration goes ahead, because refusing to start is worse than the risk
+    the backup was insuring against.
+    """
+    try:
+        if not prefs.backups()["enabled"]:
+            return None
+        db_file = _main_db_file(conn)
+        if db_file is None:
+            return None
+        entry = create_backup(db_file, "pre-migration", conn=conn)
+        prune(db_file, prefs.backups()["keep"])
+        return entry
+    except Exception:  # noqa: BLE001 - see docstring
+        logger.exception("wp_db_backup: pre-migration backup failed; migrating anyway")
+        return None
+
+
+def _main_db_file(conn: sqlite3.Connection) -> Path | None:
+    """The file behind ``conn``'s main schema, or None for in-memory DBs."""
+    for row in conn.execute("PRAGMA database_list;").fetchall():
+        if row[1] == "main":
+            return Path(row[2]) if row[2] else None
+    return None
+
+
+# ── staged restore ───────────────────────────────────────────────────
+
+
+def stage_restore(db_path: Path, name: str) -> Path:
+    """Record a restore of backup ``name`` for the next start."""
+    path = resolve_backup(db_path, name)
+    db_config.set_pending_restore(path)
+    return path
+
+
+def cancel_restore() -> None:
+    db_config.clear_pending_restore()
+
+
+def pending_restore_name(db_path: Path) -> str | None:
+    """Name of the staged restore's backup, if one is staged for this DB."""
+    pr = db_config.load().get("pending_restore")
+    if not pr:
+        return None
+    src = Path(pr["from"])
+    try:
+        resolve_backup(db_path, src.name)
+    except BackupNotFound:
+        return None
+    return src.name
+
+
+def _copy_live_db_file(db_path: Path) -> None:
+    """Fallback pre-restore snapshot: plain file copy (nothing is open yet)."""
+    directory = backups_dir(db_path)
+    directory.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(db_path, _new_backup_path(directory, "pre-restore"))
+
+
+def execute_pending_restore() -> None:
+    """If a restore is staged, run it and clear the entry. Never raises.
+
+    Runs at plugin load, right after ``execute_pending_move`` and before any
+    connection opens. Order: snapshot the live DB as ``pre-restore`` (so the
+    restore is undoable), drop the live ``-wal`` / ``-shm`` (they belong to the
+    file being replaced — left behind, SQLite would replay them onto the
+    restored one), then copy the backup into place via temp + rename.
+    """
+    try:
+        _execute_pending_restore()
+    except Exception:  # noqa: BLE001 - see docstring
+        logger.exception("wp_db_restore: failed")
+
+
+def _execute_pending_restore() -> None:
+    pr = db_config.load().get("pending_restore")
+    if not pr:
+        return
+    db_path = resolve_db_path()
+    src = Path(pr["from"])
+    try:
+        src = resolve_backup(db_path, src.name)
+    except BackupNotFound:
+        # A backup that is gone (or a sidecar pointing somewhere else) will
+        # never become restorable; keeping the entry would retry forever.
+        logger.error("wp_db_restore: backup %s not found in %s, dropping request",
+                     pr["from"], backups_dir(db_path))
+        db_config.clear_pending_restore()
+        return
+
+    if db_path.is_file():
+        try:
+            create_backup(db_path, "pre-restore")
+        except Exception:  # noqa: BLE001 - fall back to a raw copy
+            logger.exception("wp_db_restore: online pre-restore backup failed, copying file")
+            try:
+                _copy_live_db_file(db_path)
+            except OSError:
+                # Without a safety copy, overwriting would be irreversible.
+                logger.exception("wp_db_restore: could not save current DB; not restoring")
+                return
+
+    for suffix in ("-wal", "-shm"):
+        Path(str(db_path) + suffix).unlink(missing_ok=True)
+
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_str = tempfile.mkstemp(prefix=".restore-", suffix=".db", dir=str(db_path.parent))
+    os.close(fd)
+    tmp = Path(tmp_str)
+    try:
+        shutil.copyfile(src, tmp)
+        os.replace(tmp, db_path)
+    except OSError:
+        tmp.unlink(missing_ok=True)
+        logger.exception("wp_db_restore: copying %s over %s failed", src, db_path)
+        return
+    db_config.clear_pending_restore()
+    try:
+        prune(db_path, prefs.backups()["keep"])
+    except Exception:  # noqa: BLE001 - pruning is housekeeping
+        logger.exception("wp_db_restore: prune failed")
+    logger.info("wp_db_restore: restored %s -> %s", src, db_path)
+
+
+# ── daily scheduler ─────────────────────────────────────────────────
+
+_scheduler_lock = threading.Lock()
+_scheduler: threading.Thread | None = None
+_scheduler_stop = threading.Event()
+
+
+def _safe_daily() -> None:
+    try:
+        maybe_daily_backup()
+    except Exception:  # noqa: BLE001 - a failed backup must not kill the loop
+        logger.exception("wp_db_backup: daily backup failed")
+
+
+def _scheduler_loop(period: float) -> None:
+    while not _scheduler_stop.wait(period):
+        _safe_daily()
+
+
+def start_daily_scheduler(period: float = SCHEDULER_PERIOD_S) -> bool:
+    """Check for a due daily backup now, then hourly on a daemon thread.
+
+    Hourly checks against a 24h interval, rather than one 24h timer, so a
+    machine that sleeps or a ComfyUI that restarts often still gets its
+    backup roughly on schedule. Idempotent: returns False if already running.
+    """
+    global _scheduler
+    with _scheduler_lock:
+        if _scheduler is not None and _scheduler.is_alive():
+            return False
+        _scheduler_stop.clear()
+        _safe_daily()
+        _scheduler = threading.Thread(
+            target=_scheduler_loop, args=(period,),
+            name="wp-daily-backup", daemon=True,
+        )
+        _scheduler.start()
+        return True
+
+
+def stop_daily_scheduler() -> None:
+    """Stop the scheduler thread (tests)."""
+    global _scheduler
+    with _scheduler_lock:
+        _scheduler_stop.set()
+        if _scheduler is not None:
+            _scheduler.join(timeout=5)
+        _scheduler = None

engine/db/config.py

@@ -1,4 +1,4 @@
-"""Sidecar config for DB location preference + pending move state.
+"""Sidecar config for DB location preference + pending move/restore state.
 
 Lives at ``<plugin>/db-config.json`` so the resolver can read it BEFORE
 opening any DB connection (chicken-and-egg: the preference about where
@@ -35,6 +35,11 @@ class PendingMove(TypedDict, total=False):
 class DbConfig(TypedDict, total=False):
     preference: Preference
     pending_move: dict[str, str]  # {"from": "...", "to": "...", "mode": "..."}
+    # {"from": "<absolute backup path>"} — a restore staged from Settings,
+    # executed by `engine/db/backups.py:execute_pending_restore` at the next
+    # start, before any connection opens (a live SQLite file can't safely be
+    # swapped out from under open connections).
+    pending_restore: dict[str, str]
 
 
 def _read_raw(path: Path) -> dict[str, Any]:
@@ -73,6 +78,11 @@ def load(path: Path | None = None) -> DbConfig:
         if (isinstance(mode, str) and mode in _VALID_MODES
                 and isinstance(src, str) and isinstance(dst, str)):
             out["pending_move"] = {"from": src, "to": dst, "mode": mode}
+    pr = raw.get("pending_restore")
+    if isinstance(pr, dict):
+        src = pr.get("from")
+        if isinstance(src, str) and src:
+            out["pending_restore"] = {"from": src}
     return out
 
 
@@ -87,6 +97,9 @@ def save(config: DbConfig, path: Path | None = None) -> None:
     pm = config.get("pending_move")
     if isinstance(pm, dict) and {"from", "to", "mode"} <= pm.keys():
         out["pending_move"] = {"from": pm["from"], "to": pm["to"], "mode": pm["mode"]}
+    pr = config.get("pending_restore")
+    if isinstance(pr, dict) and isinstance(pr.get("from"), str) and pr["from"]:
+        out["pending_restore"] = {"from": pr["from"]}
     fd, tmp_str = tempfile.mkstemp(prefix=".db-config-", dir=str(path.parent))
     tmp_path = Path(tmp_str)
     try:
@@ -107,6 +120,27 @@ def clear_pending_move(path: Path | None = None) -> None:
         save(cfg, path)
 
 
+def set_pending_restore(backup_path: Path, path: Path | None = None) -> None:
+    """Stage a restore from ``backup_path``; preserves the other fields.
+
+    Callers validate the path (it must be a file in the backups dir) — this
+    layer only persists it.
+    """
+    path = _resolve_sidecar(path)
+    cfg = load(path)
+    cfg["pending_restore"] = {"from": str(backup_path)}
+    save(cfg, path)
+
+
+def clear_pending_restore(path: Path | None = None) -> None:
+    """Remove just the pending_restore field; preserve everything else."""
+    path = _resolve_sidecar(path)
+    cfg = load(path)
+    if "pending_restore" in cfg:
+        cfg.pop("pending_restore", None)
+        save(cfg, path)
+
+
 def plugin_root() -> Path:
     """Expose the plugin root so the resolver can compute the `root` location."""
     return _PLUGIN_ROOT

engine/db/connection.py

@@ -33,6 +33,17 @@ from pathlib import Path
 
 DB_FILENAME = "wildcard-pipeline.db"
 
+#: Our own folder under ComfyUI's user directory.
+#:
+#: Everything of ours that must survive an extension reinstall lives here: the
+#: library database and the downloaded tag list, with room for whatever comes
+#: next. They used to sit loose in `<ComfyUI>/user/` alongside ComfyUI's own
+#: files, which was fine when there was one of them and stopped being fine at
+#: two. One folder is also one thing to back up, and one thing to delete.
+#:
+#: `engine/db/relocate.py` moves pre-existing files in on first boot.
+WP_DATA_DIRNAME = "wildcard-pipeline"
+
 
 def _comfyui_user_dir_from_api() -> Path | None:
     """Use ComfyUI's `folder_paths.get_user_directory()` when the host
@@ -102,6 +113,28 @@ def _load_sidecar() -> dict:
     return dict(load())
 
 
+def comfyui_user_dir() -> Path | None:
+    """ComfyUI's user directory, or ``None`` when it cannot be detected.
+
+    The same detector chain the ``user`` DB location uses, exposed because it
+    is not database-specific — anything of ours that must survive an extension
+    reinstall belongs under here rather than in the package folder.
+    """
+    return _comfyui_user_dir_from_api() or _comfyui_user_dir_from_path()
+
+
+def wp_data_dir() -> Path | None:
+    """Our folder inside ComfyUI's user directory, or ``None`` when the user
+    directory cannot be detected.
+
+    Does NOT create the directory — callers that write do that, so a read-only
+    probe (the Settings panel asking "where would this live?") never has the
+    side effect of making a folder the user did not ask for.
+    """
+    base = comfyui_user_dir()
+    return (base / WP_DATA_DIRNAME) if base else None
+
+
 def user_location_path() -> Path | None:
     """Return the ``user`` preference target path, or ``None`` if the
     ComfyUI user dir can't be detected.
@@ -111,7 +144,7 @@ def user_location_path() -> Path | None:
     list all three potential locations regardless of which one is
     currently active (or whether one is detectable at all)."""
     comfy_user = _comfyui_user_dir_from_api() or _comfyui_user_dir_from_path()
-    return (comfy_user / DB_FILENAME) if comfy_user else None
+    return (comfy_user / WP_DATA_DIRNAME / DB_FILENAME) if comfy_user else None
 
 
 def global_location_path() -> Path:
@@ -153,14 +186,14 @@ def resolve_db_path_with_source() -> tuple[Path, str]:
     if preference == "user":
         comfy_user = _comfyui_user_dir_from_api() or _comfyui_user_dir_from_path()
         if comfy_user is not None:
-            return comfy_user / DB_FILENAME, "user"
+            return comfy_user / WP_DATA_DIRNAME / DB_FILENAME, "user"
         # Detection failed — fall through to the default chain rather
         # than crash. Last-ditch fallback below will catch it.
 
     # Default — same as explicit "user" preference.
     comfy_user = _comfyui_user_dir_from_api() or _comfyui_user_dir_from_path()
     if comfy_user is not None:
-        return comfy_user / DB_FILENAME, "user"
+        return comfy_user / WP_DATA_DIRNAME / DB_FILENAME, "user"
 
     # Last-ditch fallback. The design folds the old "legacy" label into
     # "global" because the path is identical and the UI has no separate

engine/db/migrations.py

@@ -174,6 +174,23 @@ def assert_schema_compatible(conn: sqlite3.Connection) -> None:
             )
 
 
+def _backup_if_upgrading(conn: sqlite3.Connection, applied: int) -> None:
+    """Snapshot an existing library before this build changes its schema.
+
+    Only when there is something to lose AND something about to change: a
+    fresh database (``applied == 0``) has no data, an up-to-date one has no
+    pending step, and an in-memory one has no file. `backup_before_migration`
+    swallows its own failures — a backup problem never blocks a migration.
+    """
+    if applied <= 0:
+        return
+    if not any(version > applied for version, _ in _discover()):
+        return
+    from engine.db.backups import backup_before_migration
+
+    backup_before_migration(conn)
+
+
 def migrate(conn: sqlite3.Connection) -> None:
     """Apply all pending migrations. Safe to call repeatedly.
 
@@ -182,6 +199,7 @@ def migrate(conn: sqlite3.Connection) -> None:
     """
     assert_schema_compatible(conn)
     applied = current_version(conn)
+    _backup_if_upgrading(conn, applied)
     for version, mig_file in _discover():
         if version <= applied:
             continue

engine/db/migrations_sql/018_test_scenarios.sql

@@ -0,0 +1,35 @@
+-- Test Runner scenarios — saved stacks the Test Runner re-runs on demand.
+--
+-- A scenario references library modules and bundles LIVE by id (the stack
+-- JSON holds `{module: id}` / `{bundle: id}` items), so editing a module
+-- changes the next run. That is the point: a stored baseline lets the
+-- runner say which variables moved since. Local-only by design, never
+-- exported or published.
+--
+-- Columns:
+--   stack      JSON list of stack items, run top to bottom
+--   pins       JSON object of pinned $var values (stand-ins for upstream)
+--   seeds      JSON seed spec (from+count, random+count, or list)
+--   output_var the variable the runner treats as the prompt, or NULL
+--   baseline   JSON snapshot of a run to compare against, or NULL
+--   last_run   JSON summary of the most recent run, or NULL
+--
+-- NOTE: the migration runner splits on the semicolon char, so comments
+-- must avoid it.
+
+CREATE TABLE IF NOT EXISTS test_scenarios (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '',
+  is_pinned   INTEGER NOT NULL DEFAULT 0,
+  stack       TEXT NOT NULL DEFAULT '[]',
+  pins        TEXT NOT NULL DEFAULT '{}',
+  seeds       TEXT NOT NULL DEFAULT '{"from": 0, "count": 100}',
+  output_var  TEXT,
+  baseline    TEXT,
+  last_run    TEXT,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_test_scenarios_updated_at ON test_scenarios(updated_at DESC);

engine/db/migrations_sql/019_template_negative.py

@@ -0,0 +1,32 @@
+"""Migration 019 -- negative_template column on saved prompt templates.
+
+Send-to-negative gives the PromptAssembler a second box, the negative
+template (``$vars`` plus the reserved ``$negatives`` slot). A saved
+template stores both boxes, so ``templates`` gains ``negative_template``
+(TEXT, nullable, no default).
+
+NULL is meaningful: a template saved before this migration has no
+negative, and loading it leaves the Assembler's negative box as it was
+instead of blanking it. A template saved afterwards stores a string,
+even an empty one, so loading it sets the box.
+
+Row-level column, not a payload shape: no ``schema_version`` bump.
+
+Idempotent: the ALTER is gated on ``PRAGMA table_info``. The migration
+runner's version table is the primary re-run guard; the column check
+exists for test fixtures that rewind ``migrations``.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+
+def _has_column(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    cur = conn.execute(f"PRAGMA table_info({table});")
+    return any(row[1] == column for row in cur.fetchall())
+
+
+def up(conn: sqlite3.Connection) -> None:
+    with conn:
+        if not _has_column(conn, "templates", "negative_template"):
+            conn.execute("ALTER TABLE templates ADD COLUMN negative_template TEXT;")

engine/db/relocate.py

@@ -0,0 +1,103 @@
+"""One-time move of our files from ``<ComfyUI>/user/`` into ``<user>/wildcard-pipeline/``.
+
+The library database and the downloaded tag list used to sit loose in ComfyUI's
+user directory. Existing installs have real data there, so introducing the
+subfolder is only half the change — without this the extension would silently
+come up with an empty library and no tag list, which reads as data loss even
+though the files are still on disk.
+
+Design constraints, in the order they mattered:
+
+1. **Never overwrite.** If something already exists at the destination, the
+   legacy file is left exactly where it is and reported as skipped. A
+   destination file means either a completed migration or a deliberate
+   user-placed file; both outsrank anything we could infer.
+2. **Run before the database is opened.** SQLite keeps ``-wal`` and ``-shm``
+   sidecars next to the main file, and moving the set out from under an open
+   connection corrupts it. ``__init__.py`` calls this at import, before routes
+   are registered and before anything connects.
+3. **Move the sidecars with it.** A ``-wal`` left behind holds committed
+   transactions that have not been checkpointed into the main file yet; moving
+   the ``.db`` alone can lose the most recent writes.
+4. **Never raise.** A failed migration must degrade to "extension starts with
+   the old path still in place", not to "ComfyUI fails to load the extension".
+   Every failure is reported in the return value for the caller to log.
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from engine.db.connection import DB_FILENAME, comfyui_user_dir, wp_data_dir
+
+#: Kept in sync with `wp_api/tags.py::TAG_FILE_NAME`. Duplicated rather than
+#: imported because `engine/` must not import from `wp_api/` — the directory
+#: contract in CLAUDE.md keeps the engine free of ComfyUI-facing modules, and
+#: `wp_api` imports aiohttp.
+TAG_FILE_NAME = "wildcard-pipeline-tags.csv"
+
+#: SQLite's write-ahead-log sidecars. Moved with the database, never alone.
+_DB_SIDECAR_SUFFIXES = ("-wal", "-shm")
+
+
+@dataclass
+class RelocationReport:
+    """What happened, for the caller to log. Empty everywhere = nothing to do."""
+
+    moved: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    failed: list[str] = field(default_factory=list)
+
+    @property
+    def did_anything(self) -> bool:
+        return bool(self.moved or self.skipped or self.failed)
+
+
+def _move_one(src: Path, dst: Path, report: RelocationReport) -> None:
+    """Move ``src`` to ``dst`` if and only if ``src`` exists and ``dst`` does not."""
+    if not src.exists():
+        return
+    if dst.exists():
+        report.skipped.append(f"{src.name} (already present at destination)")
+        return
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        # `shutil.move` rather than `Path.rename`: the user directory and our
+        # subfolder are normally the same filesystem, but a user dir that is a
+        # mount or a symlink elsewhere would make rename fail with EXDEV.
+        shutil.move(str(src), str(dst))
+        report.moved.append(src.name)
+    except Exception as exc:  # noqa: BLE001 - see module docstring, item 4
+        report.failed.append(f"{src.name}: {exc}")
+
+
+def migrate_user_data() -> RelocationReport:
+    """Move the database and tag list into ``<user>/wildcard-pipeline/``.
+
+    Idempotent: once the files are at the destination every subsequent call
+    finds nothing to move and returns an empty report. Safe to call on every
+    boot, which is exactly what happens.
+    """
+    report = RelocationReport()
+    base = comfyui_user_dir()
+    target = wp_data_dir()
+    if base is None or target is None:
+        # No detectable user directory. `resolve_db_path_with_source` falls
+        # back to `~/.comfyui/` in this case, which was never inside the user
+        # dir, so there is nothing here to move.
+        return report
+
+    # Database first, sidecars immediately after it. Order matters only for
+    # readability of the report; the "never overwrite" rule makes each move
+    # independent.
+    _move_one(base / DB_FILENAME, target / DB_FILENAME, report)
+    for suffix in _DB_SIDECAR_SUFFIXES:
+        _move_one(
+            base / f"{DB_FILENAME}{suffix}",
+            target / f"{DB_FILENAME}{suffix}",
+            report,
+        )
+
+    _move_one(base / TAG_FILE_NAME, target / TAG_FILE_NAME, report)
+    return report

engine/db/repositories.py

@@ -422,6 +422,57 @@ class ModuleRepository:
         rows = self._conn.execute(sql, params).fetchall()
         return [_row_to_module(r) for r in rows]
 
+    def library_stamp(self) -> str:
+        """A cheap value that changes whenever any module's payload changes.
+
+        Exists so the drift endpoint can answer "nothing changed" WITHOUT
+        building the hash map. That map costs a `json.loads` of every payload
+        in the library, and the drift poll asks for it every five seconds per
+        open tab — so the expensive part has to sit behind this, not in front
+        of it.
+
+        Three columns, each covering what the others miss:
+          - `COUNT(*)`    — any insert or delete.
+          - `SUM(version)`— any payload edit; `update` does `version = version + 1`.
+          - `MAX(updated_at)` — backstop for a delete+insert that happened to
+            leave count and version-sum unchanged.
+
+        Note what deliberately does NOT move it: `set_community_origin` and the
+        favorite toggle write without bumping `version`, and neither changes a
+        `payload_hash`. A stamp that ignored them would be wrong; a stamp that
+        moved on them would just cost every client a pointless refetch.
+        """
+        row = self._conn.execute(
+            "SELECT COUNT(*) AS n, COALESCE(SUM(version), 0) AS v, "
+            "COALESCE(MAX(updated_at), '') AS t FROM modules;"
+        ).fetchone()
+        return f"{row['n']}:{row['v']}:{row['t']}"
+
+    def list_hash_rows(self) -> list[dict[str, Any]]:
+        """`{id, type, payload_hash}` for every module — the drift map.
+
+        Deliberately not `list()`. That selects every column and runs each row
+        through `_row_to_module`, which parses `tags`, reads the community and
+        content-rating columns and builds a seventeen-key dict — all of it
+        discarded here. This selects the three columns the drift map needs.
+
+        The `payload` parse survives because `payload_hash` is computed, not
+        stored (unlike `bundles`, which has the column). Removing that too
+        means a schema migration; the stamp above makes it moot in the steady
+        state, which is the case that actually repeats.
+        """
+        rows = self._conn.execute(
+            "SELECT id, type, payload FROM modules;"
+        ).fetchall()
+        return [
+            {
+                "id": r["id"],
+                "type": r["type"],
+                "payload_hash": payload_hash(json.loads(r["payload"])),
+            }
+            for r in rows
+        ]
+
     def count(
         self,
         *,
@@ -813,6 +864,30 @@ class BundleRepository:
         rows = self._conn.execute(sql, params).fetchall()
         return [_row_to_bundle(r) for r in rows]
 
+    def library_stamp(self) -> str:
+        """Cheap change signal for the bundle drift poll.
+
+        See `ModuleRepository.library_stamp` — same three columns, same
+        reasoning."""
+        row = self._conn.execute(
+            "SELECT COUNT(*) AS n, COALESCE(SUM(version), 0) AS v, "
+            "COALESCE(MAX(updated_at), '') AS t FROM bundles;"
+        ).fetchone()
+        return f"{row['n']}:{row['v']}:{row['t']}"
+
+    def list_hash_rows(self) -> list[dict[str, Any]]:
+        """`{id, payload_hash}` for every bundle.
+
+        Unlike modules, `bundles.payload_hash` is a real stored column, so
+        this reads two columns and parses nothing at all. `list()` here would
+        have selected every column and run `_row_to_bundle` over each row,
+        which parses `tags` AND `children` per bundle for a map that wants
+        neither."""
+        rows = self._conn.execute(
+            "SELECT id, payload_hash FROM bundles;"
+        ).fetchall()
+        return [{"id": r["id"], "payload_hash": r["payload_hash"]} for r in rows]
+
     def count(
         self,
         *,
@@ -833,6 +908,16 @@ class TemplateNotFound(LookupError):
     """Raised when a requested template id does not exist."""
 
 
+def _template_negative(row: sqlite3.Row) -> str | None:
+    """Migration 019's column. NULL = saved before negatives existed (loading
+    leaves the Assembler's negative box alone). Pre-migration fixtures lack
+    the column entirely."""
+    try:
+        return row["negative_template"]
+    except (IndexError, KeyError):
+        return None
+
+
 def _row_to_template(row: sqlite3.Row) -> dict[str, Any]:
     return {
         "id": row["id"],
@@ -842,6 +927,7 @@ def _row_to_template(row: sqlite3.Row) -> dict[str, Any]:
         "tags": json.loads(row["tags"]),
         "is_favorite": bool(row["is_favorite"]),
         "template_string": row["template_string"],
+        "negative_template": _template_negative(row),
         "created_at": row["created_at"],
         "updated_at": row["updated_at"],
     }
@@ -871,6 +957,7 @@ class TemplateRepository:
         category_id: str | None = None,
         tags: list[str] | None = None,
         is_favorite: bool = False,
+        negative_template: str | None = None,
     ) -> dict[str, Any]:
         tid = self._gen_id()
         now = _now()
@@ -878,12 +965,13 @@ class TemplateRepository:
             self._conn.execute(
                 "INSERT INTO templates("
                 "id, name, description, category_id, tags, "
-                "is_favorite, template_string, created_at, updated_at"
-                ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?);",
+                "is_favorite, template_string, negative_template, "
+                "created_at, updated_at"
+                ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);",
                 (
                     tid, name, description, category_id,
                     json.dumps(tags or []), int(is_favorite),
-                    template_string, now, now,
+                    template_string, negative_template, now, now,
                 ),
             )
         return self.get(tid)
@@ -906,6 +994,7 @@ class TemplateRepository:
         tags: list[str] | _Unset = _UNSET,
         template_string: str | _Unset = _UNSET,
         is_favorite: bool | _Unset = _UNSET,
+        negative_template: str | None | _Unset = _UNSET,
     ) -> dict[str, Any]:
         existing = self.get(template_id)
         new = {
@@ -925,18 +1014,25 @@ class TemplateRepository:
             "is_favorite": (
                 existing["is_favorite"] if isinstance(is_favorite, _Unset) else is_favorite
             ),
+            "negative_template": (
+                existing["negative_template"]
+                if isinstance(negative_template, _Unset)
+                else negative_template
+            ),
         }
         now = _now()
         with self._conn:
             self._conn.execute(
                 "UPDATE templates SET "
                 "name = ?, description = ?, category_id = ?, tags = ?, "
-                "is_favorite = ?, template_string = ?, updated_at = ? "
+                "is_favorite = ?, template_string = ?, negative_template = ?, "
+                "updated_at = ? "
                 "WHERE id = ?;",
                 (
                     new["name"], new["description"], new["category_id"],
                     json.dumps(new["tags"]), int(new["is_favorite"]),
-                    new["template_string"], now, template_id,
+                    new["template_string"], new["negative_template"], now,
+                    template_id,
                 ),
             )
         return self.get(template_id)
@@ -1018,3 +1114,156 @@ class TemplateRepository:
             "SELECT COUNT(*) AS n FROM templates" + where, params,
         ).fetchone()
         return int(row["n"]) if row is not None else 0
+
+
+class ScenarioNotFound(LookupError):
+    """Raised when a requested Test Runner scenario id does not exist."""
+
+
+_DEFAULT_SCENARIO_SEEDS: dict[str, Any] = {"from": 0, "count": 100}
+
+
+def _json_or_none(raw: str | None) -> Any:
+    return json.loads(raw) if raw else None
+
+
+def _row_to_scenario(row: sqlite3.Row) -> dict[str, Any]:
+    return {
+        "id": row["id"],
+        "name": row["name"],
+        "description": row["description"],
+        "is_pinned": bool(row["is_pinned"]),
+        "stack": json.loads(row["stack"]),
+        "pins": json.loads(row["pins"]),
+        "seeds": json.loads(row["seeds"]),
+        "output_var": row["output_var"],
+        "baseline": _json_or_none(row["baseline"]),
+        "last_run": _json_or_none(row["last_run"]),
+        "created_at": row["created_at"],
+        "updated_at": row["updated_at"],
+    }
+
+
+class ScenarioRepository:
+    """CRUD for saved Test Runner scenarios (migration 018).
+
+    A scenario's stack references library modules / bundles by id and is
+    resolved live at run time, so nothing here snapshots module payloads.
+    `baseline` and `last_run` are opaque JSON the Test Runner writes; the
+    repository only stores them. Pure DB — engine-isolated.
+    """
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def _gen_id(self) -> str:
+        return secrets.token_hex(_ID_HEX_LEN // 2)
+
+    def create(
+        self,
+        *,
+        name: str,
+        description: str = "",
+        is_pinned: bool = False,
+        stack: list[Any] | None = None,
+        pins: dict[str, str] | None = None,
+        seeds: dict[str, Any] | None = None,
+        output_var: str | None = None,
+        baseline: dict[str, Any] | None = None,
+        last_run: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        sid = self._gen_id()
+        now = _now()
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO test_scenarios("
+                "id, name, description, is_pinned, stack, pins, seeds, "
+                "output_var, baseline, last_run, created_at, updated_at"
+                ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);",
+                (
+                    sid, name, description, int(is_pinned),
+                    json.dumps(stack or []), json.dumps(pins or {}),
+                    json.dumps(seeds or _DEFAULT_SCENARIO_SEEDS), output_var,
+                    None if baseline is None else json.dumps(baseline),
+                    None if last_run is None else json.dumps(last_run),
+                    now, now,
+                ),
+            )
+        return self.get(sid)
+
+    def get(self, scenario_id: str) -> dict[str, Any]:
+        row = self._conn.execute(
+            "SELECT * FROM test_scenarios WHERE id = ?;", (scenario_id,),
+        ).fetchone()
+        if row is None:
+            raise ScenarioNotFound(scenario_id)
+        return _row_to_scenario(row)
+
+    _UPDATABLE = (
+        "name", "description", "is_pinned", "stack", "pins", "seeds",
+        "output_var", "baseline", "last_run",
+    )
+
+    def update(self, scenario_id: str, **fields: Any) -> dict[str, Any]:
+        """Patch any of `_UPDATABLE`. `baseline` / `last_run` / `output_var`
+        accept None to clear. Unknown keys raise TypeError."""
+        unknown = set(fields) - set(self._UPDATABLE)
+        if unknown:
+            raise TypeError(f"unknown scenario fields: {sorted(unknown)}")
+        existing = self.get(scenario_id)
+        new = {**existing, **fields}
+
+        def _opt(value: Any) -> str | None:
+            return None if value is None else json.dumps(value)
+
+        with self._conn:
+            self._conn.execute(
+                "UPDATE test_scenarios SET "
+                "name = ?, description = ?, is_pinned = ?, stack = ?, pins = ?, "
+                "seeds = ?, output_var = ?, baseline = ?, last_run = ?, updated_at = ? "
+                "WHERE id = ?;",
+                (
+                    new["name"], new["description"], int(bool(new["is_pinned"])),
+                    json.dumps(new["stack"]), json.dumps(new["pins"]),
+                    json.dumps(new["seeds"]), new["output_var"],
+                    _opt(new["baseline"]), _opt(new["last_run"]),
+                    _now(), scenario_id,
+                ),
+            )
+        return self.get(scenario_id)
+
+    def delete(self, scenario_id: str) -> None:
+        with self._conn:
+            cur = self._conn.execute(
+                "DELETE FROM test_scenarios WHERE id = ?;", (scenario_id,),
+            )
+        if cur.rowcount == 0:
+            raise ScenarioNotFound(scenario_id)
+
+    def list(self, *, query: str | None = None) -> list[dict[str, Any]]:
+        """Pinned first, then most recently updated. `query` matches the
+        name (case-insensitive substring)."""
+        sql = "SELECT * FROM test_scenarios"
+        params: list[Any] = []
+        if query:
+            escaped = query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            sql += " WHERE name LIKE ? ESCAPE '\\' COLLATE NOCASE"
+            params.append(f"%{escaped}%")
+        sql += " ORDER BY is_pinned DESC, updated_at DESC, id;"
+        return [_row_to_scenario(r) for r in self._conn.execute(sql, params).fetchall()]
+
+    def using(self, *, module_id: str | None = None, bundle_id: str | None = None) -> list[str]:
+        """Ids of scenarios whose stack references a module or bundle — the
+        "used in N scenarios" hint in the module editors."""
+        key, target = ("module", module_id) if module_id else ("bundle", bundle_id)
+        if not target:
+            return []
+        out: list[str] = []
+        for row in self._conn.execute("SELECT id, stack FROM test_scenarios;").fetchall():
+            try:
+                stack = json.loads(row["stack"])
+            except (TypeError, ValueError):
+                continue
+            if any(isinstance(i, dict) and i.get(key) == target for i in stack):
+                out.append(row["id"])
+        return out

engine/exporter.py

@@ -33,7 +33,7 @@ from engine.db.repositories import (
     TemplateNotFound,
     TemplateRepository,
 )
-from engine.migrations import CURRENT_SCHEMA_VERSION
+from engine.migrations.stamping import schema_version_for_payload
 
 
 def _walk_inner_bundles(repo: BundleRepository, seed: list[str]) -> list[str]:
@@ -152,9 +152,7 @@ def build_export_payload(
         except TemplateNotFound:
             pass
 
-    return {
-        "schema_version": CURRENT_SCHEMA_VERSION,
-        "exported_at": now_iso(),
+    buckets: dict[str, list[dict[str, Any]]] = {
         "bundles": bundles,
         "wildcards": wildcards,
         "fixed_values": fixed_values,
@@ -164,3 +162,11 @@ def build_export_payload(
         "categories": categories,
         "templates": templates,
     }
+    # Stamp the lowest version the exported content needs (range grammar 3,
+    # constraint reach 4, accepts tag axes 5), not the migration-chain head:
+    # an older extension must refuse a file whose features it can't read.
+    return {
+        "schema_version": schema_version_for_payload(buckets),
+        "exported_at": now_iso(),
+        **buckets,
+    }

engine/image_filter.py

@@ -0,0 +1,376 @@
+"""Pure logic behind ``WP_ImageFilter`` — the pause-and-pick node.
+
+The node sits between two passes (first KSampler → upscaler / hires pass) and
+lets the user choose which images go on. Everything wired through it follows
+the same picks so its outputs stay lined up for the next sampler: the latents
+of the picked images, the conditionings and prompt strings of the frames they
+came from, the masks, the pipeline context.
+
+Shapes. With ``is_input_list`` the node receives every input as a list. The
+``images`` list sets the frames: ``images[f]`` is one IMAGE batch, so a plain
+batch is one frame of B images and a Context Loop of N iterations is N frames.
+A pick is ``(frame, image)``. Each other slot is aligned to the frames the way
+ComfyUI aligns lists (one item per frame, or its last item repeated) and then:
+
+- a value batched like its frame's images (latent ``samples``, a mask, a
+  conditioning tensor whose first dimension equals the frame's batch) is
+  sliced to the picked images;
+- anything else (a string, a context, a batch-1 conditioning shared by the
+  whole batch, a model) is kept or dropped with its frame.
+
+Duck-typed on ``.shape`` + list indexing (torch tensors and numpy arrays both
+qualify) so this module stays free of torch and ComfyUI imports and is tested
+with plain pytest.
+
+The waiting side lives here too: ``PendingAnswers`` is the thread-safe hand-off
+between the HTTP route (aiohttp's loop) and the node (ComfyUI runs prompts in a
+worker thread with its own event loop, so an ``asyncio.Event`` from one loop
+can't be awaited from the other).
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+Pick = tuple[int, int]
+#: One output frame: the source frame and the image indexes it keeps.
+PlanItem = tuple[int, list[int]]
+
+MODES = ("pause", "reuse", "pass_all")
+SEND_AS = ("same_shape", "per_image")
+ON_TIMEOUT = ("keep_all", "stop", "keep_first")
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "mode": "pause",
+    "send_as": "same_shape",
+    # Seconds; 0 waits until answered (or the run is cancelled).
+    "timeout": 600,
+    "on_timeout": "keep_all",
+}
+
+#: Upper bound for the timeout widget (a day). Guards against a typo turning
+#: into a node that can never time out by accident.
+MAX_TIMEOUT = 86_400
+
+
+def parse_config(raw: Any) -> dict[str, Any]:
+    """Decode the node's JSON config widget, falling back per key.
+
+    Unknown keys are ignored and bad values collapse to their default, so a
+    hand-edited or older workflow still runs (same recovery rule as the
+    Context Loop's ``_parse_config``).
+    """
+    out = dict(DEFAULT_CONFIG)
+    if isinstance(raw, str):
+        try:
+            raw = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            raw = {}
+    if not isinstance(raw, dict):
+        return out
+    for key, allowed in (
+        ("mode", MODES),
+        ("send_as", SEND_AS),
+        ("on_timeout", ON_TIMEOUT),
+    ):
+        if raw.get(key) in allowed:
+            out[key] = raw[key]
+    timeout = raw.get("timeout")
+    if isinstance(timeout, (int, float)) and not isinstance(timeout, bool):
+        out["timeout"] = max(0, min(MAX_TIMEOUT, int(timeout)))
+    return out
+
+
+# ------------------------------------------------------------------ picks ---
+
+
+def batch_len(value: Any) -> int | None:
+    """First dimension of a tensor-like, else None."""
+    shape = getattr(value, "shape", None)
+    if shape is None:
+        return None
+    try:
+        return int(shape[0]) if len(shape) >= 1 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def all_picks(batch_sizes: list[int]) -> list[Pick]:
+    return [(f, i) for f, b in enumerate(batch_sizes) for i in range(b)]
+
+
+def normalize_picks(raw: Any, batch_sizes: list[int]) -> list[Pick]:
+    """Keep the in-range ``[frame, image]`` pairs, deduplicated, in order."""
+    if not isinstance(raw, (list, tuple)):
+        return []
+    seen: set[Pick] = set()
+    for item in raw:
+        if not isinstance(item, (list, tuple)) or len(item) != 2:
+            continue
+        f, i = item
+        if isinstance(f, bool) or isinstance(i, bool):
+            continue
+        if not isinstance(f, int) or not isinstance(i, int):
+            continue
+        if 0 <= f < len(batch_sizes) and 0 <= i < batch_sizes[f]:
+            seen.add((f, i))
+    return sorted(seen)
+
+
+def plan_output(picks: list[Pick], send_as: str = "same_shape") -> list[PlanItem]:
+    """Group picks into output frames.
+
+    ``same_shape``: one output frame per source frame that has a pick, holding
+    its picked images. ``per_image``: one output frame per picked image.
+    """
+    ordered = sorted(set(picks))
+    if send_as == "per_image":
+        return [(f, [i]) for f, i in ordered]
+    plan: list[PlanItem] = []
+    for f, i in ordered:
+        if plan and plan[-1][0] == f:
+            plan[-1][1].append(i)
+        else:
+            plan.append((f, [i]))
+    return plan
+
+
+def format_picks(picks: list[Pick]) -> str:
+    """1-based ``frame:image`` list for the ``picks`` output, e.g. ``1:2, 3:1``."""
+    return ", ".join(f"{f + 1}:{i + 1}" for f, i in sorted(picks))
+
+
+# ------------------------------------------------------------- following ---
+
+
+def align(values: list[Any] | None, frames: int) -> list[Any]:
+    """Line a slot's list up with the frames, ComfyUI-style.
+
+    A slot with fewer items than frames repeats its last item (that is how
+    ComfyUI pairs lists of different lengths); an unconnected slot is None for
+    every frame.
+    """
+    if not values:
+        return [None] * frames
+    return [values[f] if f < len(values) else values[-1] for f in range(frames)]
+
+
+def _take(value: Any, idx: list[int], batch: int) -> Any:
+    n = batch_len(value)
+    if n is None or n != batch or idx == list(range(batch)):
+        return value
+    return value[idx]
+
+
+def _is_conditioning(value: Any) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(
+            isinstance(entry, (list, tuple))
+            and len(entry) == 2
+            and batch_len(entry[0]) is not None
+            and isinstance(entry[1], dict)
+            for entry in value
+        )
+    )
+
+
+def take_images(value: Any, idx: list[int], batch: int) -> Any:
+    """Slice one frame's value down to the picked images, when it is batched.
+
+    Values whose batch doesn't match the frame's image batch pass through: a
+    batch-1 conditioning broadcast over 4 images, a single mask for the whole
+    batch, a string.
+    """
+    if value is None:
+        return None
+    if isinstance(value, dict) and "samples" in value:
+        # LATENT: slice samples and whatever travels batched beside them.
+        out = dict(value)
+        out["samples"] = _take(value["samples"], idx, batch)
+        if "noise_mask" in value:
+            out["noise_mask"] = _take(value["noise_mask"], idx, batch)
+        bi = value.get("batch_index")
+        if isinstance(bi, list) and len(bi) == batch:
+            out["batch_index"] = [bi[i] for i in idx]
+        return out
+    if _is_conditioning(value):
+        sliced = []
+        for tensor, extras in value:
+            new_extras = {
+                k: (_take(v, idx, batch) if batch_len(v) is not None else v)
+                for k, v in extras.items()
+            }
+            sliced.append([_take(tensor, idx, batch), new_extras])
+        return sliced
+    return _take(value, idx, batch)
+
+
+def follow_slot(
+    values: list[Any] | None,
+    plan: list[PlanItem],
+    batch_sizes: list[int],
+) -> list[Any]:
+    """The output list for one slot under ``plan``."""
+    aligned = align(values, len(batch_sizes))
+    return [take_images(aligned[f], idx, batch_sizes[f]) for f, idx in plan]
+
+
+# ---------------------------------------------------------------- answers ---
+
+
+#: Per-image edits from the picker: ``positive`` / ``negative`` replacement
+#: text and ``mask``, a PNG data URL (white = masked) at any size.
+Edit = dict[str, str]
+
+#: Longest prompt edit accepted (characters) and mask data URL (bytes).
+MAX_EDIT_TEXT = 20_000
+MAX_MASK_URL = 16 * 1024 * 1024
+MASK_PREFIX = "data:image/png;base64,"
+
+
+@dataclass(frozen=True)
+class Answer:
+    """What the picker sent back: ``picks``, ``keep_all`` or ``stop``, plus
+    any per-image ``edits`` made in the picker."""
+
+    action: str
+    picks: tuple[Pick, ...] = ()
+    edits: dict[Pick, Edit] = field(default_factory=dict)
+
+
+def parse_edits(raw: Any, batch_sizes: list[int]) -> dict[Pick, Edit]:
+    """Validate ``{"f:i": {positive?, negative?, mask?}}``; bad entries drop."""
+    out: dict[Pick, Edit] = {}
+    if not isinstance(raw, dict):
+        return out
+    for key, entry in raw.items():
+        if not isinstance(key, str) or not isinstance(entry, dict):
+            continue
+        parts = key.split(":")
+        if len(parts) != 2 or not all(p.isdigit() for p in parts):
+            continue
+        f, i = int(parts[0]), int(parts[1])
+        if not (0 <= f < len(batch_sizes) and 0 <= i < batch_sizes[f]):
+            continue
+        edit: Edit = {}
+        for name in ("positive", "negative"):
+            text = entry.get(name)
+            if isinstance(text, str) and len(text) <= MAX_EDIT_TEXT:
+                edit[name] = text
+        mask = entry.get("mask")
+        if isinstance(mask, str) and mask.startswith(MASK_PREFIX) and len(mask) <= MAX_MASK_URL:
+            edit["mask"] = mask
+        if edit:
+            out[(f, i)] = edit
+    return out
+
+
+def parse_answer(payload: Any, batch_sizes: list[int]) -> Answer | None:
+    """Validate a picker response body; None when it is unusable."""
+    if not isinstance(payload, dict):
+        return None
+    action = payload.get("action")
+    edits = parse_edits(payload.get("edits"), batch_sizes)
+    if action == "keep_all":
+        return Answer("keep_all", tuple(all_picks(batch_sizes)), edits)
+    if action == "stop":
+        return Answer("stop")
+    if action == "picks":
+        picks = tuple(normalize_picks(payload.get("picks"), batch_sizes))
+        return Answer("picks", picks, {p: e for p, e in edits.items() if p in picks})
+    return None
+
+
+def item_text_edits(
+    plan: list[PlanItem], edits: dict[Pick, Edit], key: str,
+) -> list[str | None]:
+    """Edited ``positive`` / ``negative`` text per output item, or None.
+
+    An item with several images (Same shape) has one prompt, so the first
+    edited image in it decides (the picker writes the same text to all of a
+    frame's images in that mode).
+    """
+    out: list[str | None] = []
+    for f, idx in plan:
+        text = next((edits[(f, i)][key] for i in idx if key in edits.get((f, i), {})), None)
+        out.append(text)
+    return out
+
+
+def item_mask_edits(plan: list[PlanItem], edits: dict[Pick, Edit]) -> list[list[str] | None]:
+    """Per output item, the painted mask URL of each image ("" when that image
+    has none), or None when no image of the item was painted."""
+    out: list[list[str] | None] = []
+    for f, idx in plan:
+        urls = [edits.get((f, i), {}).get("mask", "") for i in idx]
+        out.append(urls if any(urls) else None)
+    return out
+
+
+def resolve_timeout(on_timeout: str, batch_sizes: list[int]) -> Answer:
+    if on_timeout == "stop":
+        return Answer("stop")
+    if on_timeout == "keep_first" and batch_sizes:
+        return Answer("picks", ((0, 0),))
+    return Answer("keep_all", tuple(all_picks(batch_sizes)))
+
+
+class PendingAnswers:
+    """Thread-safe registry of nodes waiting for a pick.
+
+    ``open`` registers a request (and keeps its payload so a reloaded page can
+    show it again), ``answer`` is called from the HTTP route, ``take`` is polled
+    by the waiting node, ``close`` drops the request whatever happened.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._requests: dict[str, dict[str, Any]] = {}
+        self._answers: dict[str, Any] = {}
+
+    def open(self, token: str, request: dict[str, Any]) -> None:
+        with self._lock:
+            self._requests[token] = request
+            self._answers.pop(token, None)
+
+    def answer(self, token: str, payload: Any) -> bool:
+        """Store a response; False when nothing is waiting on ``token``."""
+        with self._lock:
+            if token not in self._requests:
+                return False
+            self._answers[token] = payload
+            return True
+
+    def take(self, token: str) -> Any:
+        with self._lock:
+            return self._answers.pop(token, None)
+
+    def close(self, token: str) -> None:
+        with self._lock:
+            self._requests.pop(token, None)
+            self._answers.pop(token, None)
+
+    def pending(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return list(self._requests.values())
+
+
+#: Process-wide registry shared by the node and the route.
+PENDING = PendingAnswers()
+
+#: Last picks per node (``unique_id``), for the "Reuse last picks" mode.
+#: In memory only: a restart forgets them and the node asks again.
+LAST_PICKS: dict[str, list[Pick]] = {}
+
+
+def reusable_picks(stored: list[Pick] | None, batch_sizes: list[int]) -> list[Pick] | None:
+    """Stored picks when they still fit the incoming frames, else None."""
+    if not stored:
+        return None
+    picks = normalize_picks([list(p) for p in stored], batch_sizes)
+    return picks if len(picks) == len(stored) else None

engine/importer.py

@@ -359,6 +359,27 @@ def _bundle_exists(conn: sqlite3.Connection, bid: str) -> bool:
     return row is not None
 
 
+def _follow_category(
+    conn: sqlite3.Connection, entity: dict[str, Any], cat_map: dict[str, str],
+) -> dict[str, Any]:
+    """Point an entity's ``category_id`` at where its category landed.
+
+    A category merged into an existing one by name keeps the existing id,
+    so members carrying the incoming id follow it. An id that names no
+    category at all (not imported, not in the library) becomes ``None``
+    rather than failing the whole commit on the foreign key.
+    """
+    cid = entity.get("category_id")
+    if not isinstance(cid, str) or not cid:
+        return entity
+    target = cat_map.get(cid, cid)
+    if target == cid and _category_id_exists(conn, cid):
+        return entity
+    out = dict(entity)
+    out["category_id"] = target if _category_id_exists(conn, target) else None
+    return out
+
+
 def _category_id_exists(conn: sqlite3.Connection, cid: str) -> bool:
     row = conn.execute(
         "SELECT 1 FROM module_categories WHERE id = ?;", (cid,),
@@ -431,14 +452,16 @@ def _insert_template(
     conn.execute(
         "INSERT INTO templates("
         "id, name, description, category_id, tags, "
-        "is_favorite, template_string, created_at, updated_at"
-        ") VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?);",
+        "is_favorite, template_string, negative_template, "
+        "created_at, updated_at"
+        ") VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?);",
         (
             tid, entity["name"], entity.get("description", ""),
             entity.get("category_id"),
             json.dumps(entity.get("tags") or []),
             int(entity.get("is_favorite", False)),
             entity.get("template_string", ""),
+            _negative_template_of(entity),
             entity.get("created_at", now),
             entity.get("updated_at", now),
         ),
@@ -446,20 +469,29 @@ def _insert_template(
     return tid
 
 
+def _negative_template_of(entity: dict[str, Any]) -> str | None:
+    """Migration 019's optional column. Absent (a pack exported before
+    negatives existed) or not a string = NULL."""
+    neg = entity.get("negative_template")
+    return neg if isinstance(neg, str) else None
+
+
 def _update_template(
     conn: sqlite3.Connection, tid: str, content: dict[str, Any],
 ) -> None:
     """UPDATE the templates row identified by `tid` to mirror `content`.
 
     Stamps `updated_at`; no `version` bump (templates have no version
-    column).
+    column). A pack without `negative_template` keeps the row's existing
+    negative (COALESCE) rather than wiping it.
     """
     _require_entity_fields("template", "replace", content, ("name",))
     now = now_iso()
     conn.execute(
         "UPDATE templates SET "
         "name = ?, description = ?, category_id = ?, tags = ?, "
-        "is_favorite = ?, template_string = ?, updated_at = ? "
+        "is_favorite = ?, template_string = ?, "
+        "negative_template = COALESCE(?, negative_template), updated_at = ? "
         "WHERE id = ?;",
         (
             content["name"], content.get("description", ""),
@@ -467,6 +499,7 @@ def _update_template(
             json.dumps(content.get("tags") or []),
             int(content.get("is_favorite", False)),
             content.get("template_string", ""),
+            _negative_template_of(content),
             now, tid,
         ),
     )
@@ -492,11 +525,19 @@ def _fetch_template_row(
         "tags": json.loads(row["tags"]),
         "is_favorite": bool(row["is_favorite"]),
         "template_string": row["template_string"],
+        "negative_template": _row_negative_template(row),
         "created_at": row["created_at"],
         "updated_at": row["updated_at"],
     }
 
 
+def _row_negative_template(row: sqlite3.Row) -> str | None:
+    try:
+        return row["negative_template"]
+    except (IndexError, KeyError):
+        return None
+
+
 def commit_import(
     conn: sqlite3.Connection, payload: dict[str, Any],
 ) -> dict[str, Any]:
@@ -511,6 +552,16 @@ def commit_import(
     ``with conn:`` block, and the import_undo row is NOT inserted.
     """
     adds = list(payload.get("adds") or [])
+    # Categories go in first: modules, bundles and templates point at them
+    # by id (a foreign key), so a category listed after its members would
+    # fail the insert.
+    adds = (
+        [op for op in adds if isinstance(op, dict) and op.get("kind") == "category"]
+        + [op for op in adds if not (isinstance(op, dict) and op.get("kind") == "category")]
+    )
+    # Incoming category id -> the id it landed on (its own, or the existing
+    # category it merged into by name).
+    cat_map: dict[str, str] = {}
     replaces = list(payload.get("replaces") or [])
     renames = list(payload.get("renames") or [])
 
@@ -546,7 +597,9 @@ def commit_import(
                         (name,),
                     ).fetchone()
                     if existing is not None:
-                        # Skip — nothing to undo.
+                        # Skip — nothing to undo. Members follow the merge.
+                        if entity.get("id"):
+                            cat_map[entity["id"]] = existing[0]
                         continue
                     cid = entity.get("id") or name.lower()
                     if _category_id_exists(conn, cid):
@@ -565,8 +618,11 @@ def commit_import(
                         ),
                     )
                     imported_records.append({"kind": "category", "id": cid})
+                    if entity.get("id"):
+                        cat_map[entity["id"]] = cid
 
                 elif kind == "bundle":
+                    entity = _follow_category(conn, entity, cat_map)
                     _require_entity_fields(
                         "bundle", "add", entity, ("id", "name"),
                     )
@@ -579,6 +635,7 @@ def commit_import(
                     imported_records.append({"kind": "bundle", "id": bid})
 
                 elif kind == "template":
+                    entity = _follow_category(conn, entity, cat_map)
                     _require_entity_fields(
                         "template", "add", entity, ("id", "name"),
                     )
@@ -591,6 +648,7 @@ def commit_import(
                     imported_records.append({"kind": "template", "id": tid})
 
                 elif _is_module_kind(kind or ""):
+                    entity = _follow_category(conn, entity, cat_map)
                     _require_entity_fields(
                         kind, "add", entity, ("id", "name"),  # type: ignore[arg-type]
                     )
@@ -612,7 +670,7 @@ def commit_import(
             for op in replaces:
                 kind = op.get("kind")
                 rid = op.get("id")
-                new_content = op.get("new_content") or {}
+                new_content = _follow_category(conn, op.get("new_content") or {}, cat_map)
                 if not rid:
                     raise _ImporterContractError(
                         f"{kind} replace missing 'id' field",
@@ -653,7 +711,7 @@ def commit_import(
                 kind = op.get("kind")
                 old_id = op.get("old_id")
                 new_id = op.get("new_id")
-                content = op.get("content") or {}
+                content = _follow_category(conn, op.get("content") or {}, cat_map)
                 if not new_id:
                     raise _ImporterContractError(
                         f"{kind} rename missing 'new_id' field",
@@ -816,6 +874,7 @@ def undo_import(
                         "UPDATE templates SET "
                         "name = ?, description = ?, category_id = ?, "
                         "tags = ?, is_favorite = ?, template_string = ?, "
+                        "negative_template = ?, "
                         "created_at = ?, updated_at = ? "
                         "WHERE id = ?;",
                         (
@@ -824,6 +883,7 @@ def undo_import(
                             json.dumps(row["tags"]),
                             int(row["is_favorite"]),
                             row["template_string"],
+                            row.get("negative_template"),
                             row["created_at"], row["updated_at"], rid,
                         ),
                     )

engine/migrations/__init__.py

@@ -16,16 +16,35 @@ CURRENT_SCHEMA_VERSION = 2
 
 # Highest schema version this runtime can natively READ + WRITE — distinct
 # from CURRENT_SCHEMA_VERSION (the migration-chain head, which stays 2 because
-# v2->v3/v3->v4 are no-ops). v3 is the SP2b text-grammar bump (shape-identical
-# to v2) and v4 is the additive `target_select` constraint reach; both are
-# handled natively, so a payload at CURRENT < v <= MAX_KNOWN installs AS-IS
-# with no migration. Mirror of TS `MAX_KNOWN_SCHEMA_VERSION` in
+# v2->v3 through v6->v7 are no-ops). v3 is the SP2b text-grammar bump (shape-
+# identical to v2), v4 is the additive `target_select` constraint reach, v5
+# is the additive `accepts` tag-axis kind, v6 the constraint `only` rule and
+# v7 derivation AND/OR condition groups plus the `is_empty`/`is_not_empty` ops,
+# v8 send-to-negative (`negative` text + the derivation `negative` mode);
+# all are handled natively, so a
+# payload at CURRENT < v <= MAX_KNOWN installs AS-IS with no migration.
+# Mirror of TS `MAX_KNOWN_SCHEMA_VERSION` in
 # `src/manager/import-export/migrations.ts`.
 #
 # MAINTENANCE CONTRACT: bump this whenever the TS `schemaVersionForPayload()`
 # learns to stamp a new (higher) version — otherwise this commit-side
 # re-validate will reject the very shapes the runtime just learned to produce.
-MAX_KNOWN_SCHEMA_VERSION = 4
+MAX_KNOWN_SCHEMA_VERSION = 9
+
+# Feature stamps (mirror of the TS constants beside MAX_KNOWN). Each is the
+# catalog version a payload needs once it uses that feature; see
+# `engine/migrations/stamping.py:schema_version_for_payload`.
+SP2B_SCHEMA_VERSION = 3  # range count / `~` flag in a `{N$$…}` multi-pick
+SP3_REACH_SCHEMA_VERSION = 4  # non-default constraint `target_select`
+TAG_AXES_SCHEMA_VERSION = 5  # wildcard `tag_group_kinds` with an `accepts` group
+CONSTRAINT_ONLY_SCHEMA_VERSION = 6  # constraint rule with mode `only`
+# derivation condition group (AND / OR) or an `is_empty` / `is_not_empty` test
+DERIVATION_CONDITIONS_SCHEMA_VERSION = 7
+# send-to-negative: a non-empty `negative` on a wildcard option, fixed value or
+# combine, or a derivation action with mode `negative`
+NEGATIVES_SCHEMA_VERSION = 8
+# wildcard fallback option: an option flagged `fallback: true`
+FALLBACK_SCHEMA_VERSION = 9
 
 _CHAIN = {
     0: migrate_v0_to_v1,

engine/migrations/stamping.py

@@ -0,0 +1,241 @@
+"""Content-driven ``schema_version`` stamping. Mirror of TS
+``schemaVersionForPayload`` in ``src/manager/import-export/single-row-publish.ts``.
+
+A payload is stamped with the LOWEST catalog version its features need, so
+an older consumer can still install everything that doesn't use a newer
+feature:
+
+- ``FALLBACK_SCHEMA_VERSION`` (9): a wildcard option is flagged
+  ``fallback: true`` (also used when nothing else is left to pick).
+- ``NEGATIVES_SCHEMA_VERSION`` (8): a wildcard option, fixed value or
+  combine carries a non-empty ``negative``, a derivation action uses the
+  ``negative`` ("Add to negative") mode, a derivation branch runs more than
+  one action (``extra_actions``), or text reads a variable's negatives
+  (``$name.neg``).
+- ``DERIVATION_CONDITIONS_SCHEMA_VERSION`` (7): a derivation branch groups
+  tests with AND / OR, or a test uses ``is_empty`` / ``is_not_empty``.
+- ``CONSTRAINT_ONLY_SCHEMA_VERSION`` (6): a constraint matrix cell,
+  exception or instance mode override uses the ``only`` rule.
+- ``TAG_AXES_SCHEMA_VERSION`` (5): a wildcard ``tag_group_kinds`` map marks
+  any group ``accepts``.
+- ``SP3_REACH_SCHEMA_VERSION`` (4): a constraint carries a non-default
+  ``target_select`` reach selector.
+- ``SP2B_SCHEMA_VERSION`` (3): the payload text uses a range count or the
+  ``~`` independent flag in a ``{N$$…}`` multi-pick.
+- ``CURRENT_SCHEMA_VERSION`` (2) otherwise.
+
+Each scan walks the whole structure (bundle children, instance overrides,
+every export bucket), so the marker is found wherever it lives. Keep the two
+sides in step: a new feature stamp lands in both files in the same PR.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from engine.migrations import (
+    CONSTRAINT_ONLY_SCHEMA_VERSION,
+    CURRENT_SCHEMA_VERSION,
+    DERIVATION_CONDITIONS_SCHEMA_VERSION,
+    FALLBACK_SCHEMA_VERSION,
+    NEGATIVES_SCHEMA_VERSION,
+    SP2B_SCHEMA_VERSION,
+    SP3_REACH_SCHEMA_VERSION,
+    TAG_AXES_SCHEMA_VERSION,
+)
+
+# SP2b nested-multi-pick marker: a `{N$$…}` whose count is a range (`N-M`)
+# or carries the `~` flag. A plain fixed-count `{N$$…}` predates SP2b.
+_SP2B_MARKER_RE = re.compile(r"\{\d+(?:-\d+~?|~)\$\$")
+# `$name.neg`, `$name.K.neg` (and `$name.neg.K`): reads a variable's negatives.
+_NEG_ACCESSOR_RE = re.compile(
+    r"\$[A-Za-z_][A-Za-z0-9_]*(?:\.\d+)?\.neg(?![A-Za-z0-9_])"
+)
+
+
+def _is_number(value: Any) -> bool:
+    # JSON booleans come back as Python bools, which are ints; TS
+    # `typeof x === "number"` is false for them.
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_non_default_target_select(sel: Any) -> bool:
+    """True when ``sel`` narrows reach. Only an absent selector or a bare
+    ``{"mode": "all"}`` is the default; ``{"mode": "pick", "picks": []}``
+    still counts because a pre-SP3 consumer can't parse the mode at all."""
+    if not isinstance(sel, dict):
+        return False
+    mode = sel.get("mode")
+    if isinstance(mode, str) and mode != "all":
+        return True
+    if _is_number(sel.get("count")):
+        return True
+    picks = sel.get("picks")
+    return isinstance(picks, list) and len(picks) > 0
+
+
+def uses_target_select_reach(node: Any) -> bool:
+    """Any ``target_select`` at any depth holding a non-default selector."""
+    if isinstance(node, list):
+        return any(uses_target_select_reach(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    if _is_non_default_target_select(node.get("target_select")):
+        return True
+    return any(
+        isinstance(value, (dict, list)) and uses_target_select_reach(value)
+        for value in node.values()
+    )
+
+
+def uses_accepts_tag_axis(node: Any) -> bool:
+    """Any ``tag_group_kinds`` map at any depth marking a group ``accepts``."""
+    if isinstance(node, list):
+        return any(uses_accepts_tag_axis(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    kinds = node.get("tag_group_kinds")
+    if isinstance(kinds, dict) and any(k == "accepts" for k in kinds.values()):
+        return True
+    return any(
+        isinstance(value, (dict, list)) and uses_accepts_tag_axis(value)
+        for value in node.values()
+    )
+
+
+_EXCEPTION_LIST_KEYS = ("exceptions", "extra_exceptions")
+_MODE_OVERRIDE_KEYS = ("cell_mode_overrides", "exception_mode_overrides")
+
+
+def _matrix_uses_only(matrix: Any) -> bool:
+    if not isinstance(matrix, dict):
+        return False
+    return any(
+        isinstance(row, dict) and any(
+            isinstance(cell, dict) and cell.get("mode") == "only"
+            for cell in row.values()
+        )
+        for row in matrix.values()
+    )
+
+
+def uses_constraint_only_rule(node: Any) -> bool:
+    """Any constraint rule at any depth whose mode is ``only``: a library
+    matrix cell or exception, an instance extra exception, or an instance mode
+    override (a string map)."""
+    if isinstance(node, list):
+        return any(uses_constraint_only_rule(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    if _matrix_uses_only(node.get("matrix")):
+        return True
+    for key in _EXCEPTION_LIST_KEYS:
+        excs = node.get(key)
+        if isinstance(excs, list) and any(
+            isinstance(e, dict) and e.get("mode") == "only" for e in excs
+        ):
+            return True
+    for key in _MODE_OVERRIDE_KEYS:
+        overrides = node.get(key)
+        if isinstance(overrides, dict) and any(
+            m == "only" for m in overrides.values()
+        ):
+            return True
+    return any(
+        isinstance(value, (dict, list)) and uses_constraint_only_rule(value)
+        for value in node.values()
+    )
+
+
+_V7_CONDITION_OPS = ("is_empty", "is_not_empty")
+
+
+def _is_v7_condition(cond: Any) -> bool:
+    if not isinstance(cond, dict):
+        return False
+    if "conditions" in cond:
+        return True
+    return cond.get("op") in _V7_CONDITION_OPS
+
+
+def uses_derivation_conditions(node: Any) -> bool:
+    """Any derivation branch at any depth whose ``condition`` is an AND / OR
+    group or a test using ``is_empty`` / ``is_not_empty``."""
+    if isinstance(node, list):
+        return any(uses_derivation_conditions(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    branches = node.get("branches")
+    if isinstance(branches, list) and any(
+        isinstance(b, dict) and _is_v7_condition(b.get("condition"))
+        for b in branches
+    ):
+        return True
+    return any(
+        isinstance(value, (dict, list)) and uses_derivation_conditions(value)
+        for value in node.values()
+    )
+
+
+def uses_negatives(node: Any) -> bool:
+    """Any non-empty ``negative`` string, or a derivation action whose mode is
+    ``negative``, at any depth. An empty negative is stored as absent and
+    never needs v8."""
+    if isinstance(node, list):
+        return any(uses_negatives(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    neg = node.get("negative")
+    if isinstance(neg, str) and neg.strip():
+        return True
+    if node.get("mode") in ("negative", "negative_replace") and "target_var" in node:
+        return True
+    extra = node.get("extra_actions")
+    if isinstance(extra, list) and extra:
+        return True
+    return any(
+        (isinstance(value, (dict, list)) and uses_negatives(value))
+        or (isinstance(value, str) and _NEG_ACCESSOR_RE.search(value) is not None)
+        for value in node.values()
+    )
+
+
+def uses_fallback_option(node: Any) -> bool:
+    """Any wildcard option flagged ``fallback: true`` at any depth (library
+    payload, bundle child or a node's own copy)."""
+    if isinstance(node, list):
+        return any(uses_fallback_option(child) for child in node)
+    if not isinstance(node, dict):
+        return False
+    if node.get("fallback") is True and "value" in node:
+        return True
+    return any(
+        isinstance(value, (dict, list)) and uses_fallback_option(value)
+        for value in node.values()
+    )
+
+
+def uses_sp2b_grammar(node: Any) -> bool:
+    """Range-count or ``~`` multi-pick anywhere in the serialised payload."""
+    text = json.dumps(node, ensure_ascii=False, default=str)
+    return _SP2B_MARKER_RE.search(text) is not None
+
+
+def schema_version_for_payload(payload: Any) -> int:
+    """The lowest catalog version that covers every feature in ``payload``."""
+    if uses_fallback_option(payload):
+        return FALLBACK_SCHEMA_VERSION
+    if uses_negatives(payload):
+        return NEGATIVES_SCHEMA_VERSION
+    if uses_derivation_conditions(payload):
+        return DERIVATION_CONDITIONS_SCHEMA_VERSION
+    if uses_constraint_only_rule(payload):
+        return CONSTRAINT_ONLY_SCHEMA_VERSION
+    if uses_accepts_tag_axis(payload):
+        return TAG_AXES_SCHEMA_VERSION
+    if uses_target_select_reach(payload):
+        return SP3_REACH_SCHEMA_VERSION
+    if uses_sp2b_grammar(payload):
+        return SP2B_SCHEMA_VERSION
+    return CURRENT_SCHEMA_VERSION

engine/model_info.py

@@ -0,0 +1,248 @@
+"""Model detection for WP_ModelInfo — pure string logic, no ComfyUI imports.
+
+The node hands this module two facts it read off the graph: the loaded
+model's config class name (``SDXL``, ``Flux``, …) and the checkpoint file
+name. From those it derives the three variables the node writes:
+
+* ``model_family``  — the architecture, from the config class name.
+* ``model_variant`` — the fine-tune lineage (pony, illustrious, …), from the
+  file name. Pony and Illustrious are both SDXL by architecture, so the file
+  name is the only place that difference shows.
+* ``model_name``    — the file name without folders or extension.
+
+Variant rules are mirrored in TS at ``src/extension/model-info.ts`` (static
+preview on the canvas) via the shared ``tests/fixtures/model-variant-corpus.json``.
+Keep the two in step.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+#: Variables the node writes, in display order.
+FAMILY_VAR = "model_family"
+VARIANT_VAR = "model_variant"
+NAME_VAR = "model_name"
+MODEL_VARS = (FAMILY_VAR, VARIANT_VAR, NAME_VAR)
+
+#: Shipped variant rules, as the node's rule rows: first match wins,
+#: case-insensitive, matched anywhere in the file name. NoobAI sits above
+#: Illustrious because NoobAI files often mention both.
+DEFAULT_VARIANT_RULES: tuple[dict[str, str], ...] = (
+    {"variant": "noobai", "pattern": "noob"},
+    {"variant": "pony", "pattern": "pony|pdxl"},
+    {"variant": "illustrious", "pattern": "illustrious|ilxl"},
+    {"variant": "animagine", "pattern": "animagine"},
+)
+
+# Config class name (``model.model.model_config``'s class) → family. Checked
+# as prefixes, longest first, so ``SDXLRefiner`` lands before ``SDXL``.
+_FAMILY_PREFIXES: tuple[tuple[str, str], ...] = (
+    ("SDXLRefiner", "sdxl_refiner"),
+    ("SDXL", "sdxl"),
+    ("SSD1B", "sdxl"),
+    ("Segmind_Vega", "sdxl"),
+    ("KOALA", "sdxl"),
+    ("SD15", "sd15"),
+    ("SD20", "sd2"),
+    ("SD21", "sd2"),
+    ("SD3", "sd3"),
+    ("Stable_Cascade", "stable_cascade"),
+    ("FluxSchnell", "flux"),
+    ("Flux", "flux"),
+    ("Chroma", "chroma"),
+    ("AuraFlow", "auraflow"),
+    ("PixArt", "pixart"),
+    ("HunyuanDiT", "hunyuan_dit"),
+    ("HunyuanVideo", "hunyuan_video"),
+    ("HiDream", "hidream"),
+    ("Lumina2", "lumina2"),
+    ("QwenImage", "qwen_image"),
+    ("WAN", "wan"),
+    ("LTXV", "ltxv"),
+    ("Cosmos", "cosmos"),
+)
+
+
+def family_from_config_name(class_name: str) -> str:
+    """Map a model config class name to a lowercase family id.
+
+    Unknown classes fall back to their own name in snake case, so a model
+    ComfyUI adds after this list was written still gets a stable value.
+    """
+    name = (class_name or "").strip()
+    if not name:
+        return ""
+    for prefix, family in sorted(_FAMILY_PREFIXES, key=lambda p: -len(p[0])):
+        if name.startswith(prefix):
+            return family
+    snake = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", name)
+    return re.sub(r"[^a-z0-9]+", "_", snake.lower()).strip("_")
+
+
+def model_stem(path: str) -> str:
+    """``SDXL\\pony\\ponyDiffusionV6XL.safetensors`` → ``ponyDiffusionV6XL``."""
+    base = re.split(r"[\\/]", (path or "").strip())[-1]
+    dot = base.rfind(".")
+    return base[:dot] if dot > 0 else base
+
+
+@dataclass(frozen=True)
+class VariantRule:
+    variant: str
+    pattern: str
+    regex: re.Pattern[str]
+
+
+def compile_variant_rules(rows: Any) -> tuple[list[VariantRule], list[str]]:
+    """Compile the node's rule rows. Returns ``(rules, problems)``.
+
+    A row with neither field filled is an unfinished row and is skipped
+    quietly. A row missing one field, or with a pattern that does not
+    compile, is reported in ``problems`` and skipped, so one typo never
+    stops the other rules from working.
+    """
+    rules: list[VariantRule] = []
+    problems: list[str] = []
+    for row in rows if isinstance(rows, (list, tuple)) else ():
+        if not isinstance(row, dict):
+            continue
+        variant = str(row.get("variant") or "").strip()
+        pattern = str(row.get("pattern") or "").strip()
+        if not variant and not pattern:
+            continue
+        if not variant or not pattern:
+            problems.append(
+                f"rule {variant or pattern!r} needs both a variant and a pattern",
+            )
+            continue
+        try:
+            regex = re.compile(pattern, re.IGNORECASE)
+        except re.error as exc:
+            problems.append(f"bad pattern for {variant!r}: {exc}")
+            continue
+        rules.append(VariantRule(variant, pattern, regex))
+    return rules, problems
+
+
+@dataclass(frozen=True)
+class ModelInfoConfig:
+    """The node's widget state. Empty pins mean "detect it"."""
+
+    rules: tuple[dict[str, str], ...]
+    family: str = ""
+    variant: str = ""
+    name: str = ""
+    #: Short keys (``family`` / ``variant`` / ``name``) flagged internal: the
+    #: variable still reaches later rules, but the Assembler leaves it out.
+    #: All three are internal unless the widget says ``false``.
+    internal: frozenset[str] = frozenset(("family", "variant", "name"))
+
+
+def parse_config(raw: Any) -> ModelInfoConfig:
+    """Read the ``wp_model_info`` widget JSON. Anything unreadable, or a
+    config without a ``rules`` list, gets the shipped rules."""
+    data: Any = raw
+    if isinstance(raw, str):
+        try:
+            data = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            data = {}
+    if not isinstance(data, dict):
+        data = {}
+    rows = data.get("rules")
+    rules = (
+        tuple(r for r in rows if isinstance(r, dict))
+        if isinstance(rows, list) else DEFAULT_VARIANT_RULES
+    )
+
+    def pin(key: str) -> str:
+        v = data.get(key)
+        return v.strip() if isinstance(v, str) else ""
+
+    flags = data.get("internal")
+    internal = frozenset(
+        k for k in ("family", "variant", "name")
+        if not (isinstance(flags, dict) and flags.get(k) is False)
+    )
+    return ModelInfoConfig(rules, pin("family"), pin("variant"), pin("name"), internal)
+
+
+def detect_variant(name: str, rules: list[VariantRule]) -> str:
+    """The first rule whose pattern occurs in ``name``, else ``""``."""
+    if not name:
+        return ""
+    for rule in rules:
+        if rule.regex.search(name):
+            return rule.variant
+    return ""
+
+
+# Input names a loader node keeps its file name under.
+_NAME_INPUTS = ("ckpt_name", "unet_name", "model_name", "model_path")
+# Inputs a pass-through node (LoRA loader, sampling patch, …) takes the model on.
+_MODEL_INPUTS = ("model", "MODEL")
+# Inputs a primitive node holding a converted widget keeps its value under.
+_VALUE_INPUTS = ("value", "string", "text", "STRING")
+
+
+def _is_link(v: Any) -> bool:
+    return isinstance(v, (list, tuple)) and len(v) == 2 and isinstance(v[1], int)
+
+
+def _string_behind(prompt: dict, value: Any, depth: int = 0) -> str:
+    """A widget value, following it through a primitive node when the widget
+    was converted to an input."""
+    if isinstance(value, str):
+        return value
+    if not _is_link(value) or depth > 8:
+        return ""
+    node = prompt.get(str(value[0]))
+    inputs = node.get("inputs") if isinstance(node, dict) else None
+    if not isinstance(inputs, dict):
+        return ""
+    for key in _NAME_INPUTS + _VALUE_INPUTS:
+        if key in inputs:
+            found = _string_behind(prompt, inputs[key], depth + 1)
+            if found:
+                return found
+    return ""
+
+
+def find_checkpoint_name(
+    prompt: Any, node_id: Any, input_name: str = "model",
+) -> str:
+    """Follow ``node_id``'s ``input_name`` link back to the node that loaded
+    the model and return its file name, or ``""``.
+
+    ``prompt`` is ComfyUI's API prompt (``{id: {class_type, inputs}}``, links
+    as ``[origin_id, slot]``). Pass-through nodes — LoRA loaders, sampling
+    patches — are stepped over via their own ``model`` input.
+    """
+    if not isinstance(prompt, dict) or node_id is None:
+        return ""
+    node = prompt.get(str(node_id))
+    inputs = node.get("inputs") if isinstance(node, dict) else None
+    link = inputs.get(input_name) if isinstance(inputs, dict) else None
+    seen: set[str] = set()
+    while _is_link(link):
+        origin_id = str(link[0])
+        if origin_id in seen or len(seen) > 64:
+            return ""
+        seen.add(origin_id)
+        origin = prompt.get(origin_id)
+        o_inputs = origin.get("inputs") if isinstance(origin, dict) else None
+        if not isinstance(o_inputs, dict):
+            return ""
+        for key in _NAME_INPUTS:
+            if key in o_inputs:
+                name = _string_behind(prompt, o_inputs[key])
+                if name:
+                    return name
+        link = next(
+            (o_inputs[k] for k in _MODEL_INPUTS if _is_link(o_inputs.get(k))),
+            None,
+        )
+    return ""

engine/modules/__init__.py

@@ -47,6 +47,101 @@ class _RuntimeResolveContext:
     # occurrence matches on. None outside any carrier option.
     _carrier_uid: str | None = None
     _carrier_option_id: str | None = None
+    # Rolled `accepts`-axis choices, keyed by VARIABLE BINDING (the namespace
+    # `$outfit.SHOES` addresses) rather than module uuid like `_picks`. A
+    # projection of `ctx["__wp_axes__"]`, built once here so the resolver stays
+    # a pure consumer with no ctx dependency.
+    _axes: dict[str, Any] = field(default_factory=dict)
+    # Accepts axes each binding's wildcard declares (`ctx["__wp_axis_decl__"]`),
+    # so an empty axis read can say whether the axis is missing or the pick
+    # simply carried no tag on it.
+    _axis_decl: dict[str, Any] = field(default_factory=dict)
+    # Opt-in record of every nested `@{uuid}` pick (`ctx["__wp_ref_log__"]`,
+    # a list the caller seeds, e.g. the Test Runner). None when the caller
+    # did not ask, so a canvas run records nothing. `_ref_owner` is the
+    # stack uid of the module whose resolve this frame belongs to.
+    _ref_log: list[dict[str, Any]] | None = None
+    _ref_owner: str | None = None
+    # Send-to-negative collectors (engine/negatives.py `collecting`). None =
+    # not collecting. `_reads` gets one (name, index) per `$var` read the
+    # text rendered; `_ref_negs` gets the `negative` of every option a nested
+    # `@{ref}` picked. A quiet (negative-side) resolve leaves both None.
+    _reads: list[tuple[str, Any]] | None = None
+    _ref_negs: list[str] | None = None
+
+    # The run's negatives table (`ctx["__wp_negatives__"]`), by reference so
+    # a `$name.neg` read sees negatives filed earlier in the same module.
+    _negs: dict[str, Any] | None = None
+
+    def get_negative(self, name: str, index: int | None) -> str | None:
+        """`name`'s negatives as one line (tag-deduped), or None when it has
+        none. `index` narrows to pick K's entries plus the whole-value ones,
+        like `$name.K` carries."""
+        from engine import negatives  # noqa: PLC0415 - import cycle
+
+        rows = self._negs.get(name) if isinstance(self._negs, dict) else None
+        if not isinstance(rows, list):
+            return None
+        texts = [
+            str(e.get("text", "")) for e in rows
+            if isinstance(e, dict)
+            and (index is None or e.get("pick") is None or e.get("pick") == index)
+        ]
+        joined = negatives.join_unique(texts)
+        return joined or None
+
+    def note_var_read(self, name: str, index: Any) -> None:
+        if self._reads is not None:
+            self._reads.append((name, index))
+
+    def note_ref_negative(self, option: dict[str, Any]) -> None:
+        if self._ref_negs is None:
+            return
+        neg = option.get("negative")
+        if isinstance(neg, str) and neg.strip():
+            self._ref_negs.append(neg.strip())
+
+    def log_ref(self, entry: dict[str, Any]) -> dict[str, Any] | None:
+        """Append one nested-ref pick to the ref log, tagged with the
+        owning module's uid, and return the stored dict (so the resolver
+        can fill in the resolved text after recursing). No-op → None when
+        no log was requested."""
+        if self._ref_log is None:
+            return None
+        row = {"owner": self._ref_owner, **entry}
+        self._ref_log.append(row)
+        return row
+
+    def get_axis(self, name: str, axis: str) -> Any:
+        """Rolled axis choice(s) for a binding, or None when it has none.
+
+        Returns a plain string for a single-pick source and a list (one entry
+        per pick, in pick order) for a multi-select one, mirroring the shape of
+        the variable itself. Shaping and the empty/warn decision belong to the
+        resolver; this only fetches.
+
+        A binding that rolled no axes at all, and a binding that rolled some
+        but not THIS one, both yield None — the caller cannot act differently
+        on those two, and collapsing them keeps the read a single lookup.
+        """
+        entry = self._axes.get(name)
+        if isinstance(entry, list):
+            # Positional: one slot per pick, None where that pick's option
+            # carries no tag on this axis. Compacting the gaps away shifted
+            # every later pick down, so `$outfit.1.SHOES` read pick 2's shoe
+            # beside `$outfit.1`.
+            got = [e.get(axis) if isinstance(e, dict) else None for e in entry]
+            return got if any(g is not None for g in got) else None
+        if isinstance(entry, dict):
+            return entry.get(axis)
+        return None
+
+    def declared_axes(self, name: str) -> list[str] | None:
+        """Accepts axes the wildcard bound to `name` declares, or None when
+        that is unknown (nothing recorded, e.g. a ctx from before this table
+        existed or a binding no wildcard wrote)."""
+        got = self._axis_decl.get(name)
+        return [str(a) for a in got] if isinstance(got, list) else None
 
     def get_var(self, name: str) -> str | None:
         # SP2a: return the raw stored value (may be a ListVar from a
@@ -132,7 +227,11 @@ def build_resolve_ctx(
     """
     constraints = ctx.get("__wp_constraints__")
     picks = ctx.get("__wp_picks__")
+    axes = ctx.get("__wp_axes__")
+    axis_decl = ctx.get("__wp_axis_decl__")
     hits = ctx.setdefault("__wp_constraint_hits__", {})
+    ref_log = ctx.get("__wp_ref_log__")
+    negs = ctx.get("__wp_negatives__")
     return _RuntimeResolveContext(  # type: ignore[return-value]
         rng=ctx["__wp_rng__"],
         max_ref_depth=int(ctx.get("__wp_max_ref_depth__", 8)),
@@ -153,6 +252,14 @@ def build_resolve_ctx(
         # resolver's increments stick in ctx + share one counter with
         # the direct path for first/next coverage.
         _hits=hits if isinstance(hits, dict) else {},
+        # Same treatment as `_vars`: a projection built at frame construction,
+        # so `get_axis` is a dict lookup and the resolver never reaches into
+        # ctx.
+        _axes=axes if isinstance(axes, dict) else {},
+        _axis_decl=axis_decl if isinstance(axis_decl, dict) else {},
+        _ref_log=ref_log if isinstance(ref_log, list) else None,
+        _ref_owner=ctx.get("__wp_current_module_uid__"),
+        _negs=negs if isinstance(negs, dict) else None,
     )
 
 

engine/modules/_constraint_math.py

@@ -3,14 +3,53 @@
 One multiply operator at three levels: across an option's matching matrix
 cells (multi-tag), across source picks (multi-pick), and — by the caller —
 across constraints. `exclude` (factor 0) is the absorbing element.
+
+**One exception, added 2026-08 (tag axes).** Tags belonging to a source group
+the wildcard declared `accepts` are ALTERNATIVES the option offers, not
+statements that are all true at once. Those fold with `max`, so one sibling's
+`exclude` cannot speak for the rest. Everything else still multiplies, and the
+axis path is unreachable unless the caller passes `axis_kinds` — so a payload
+that predates the feature folds byte-identically.
+
+**`only` (2026-09, linked picks).** A rule that turns its row into an
+allow-list: when the source fires, every target WITHOUT a rule of its own in
+that row is excluded. On an exception it gates by literal value — any target
+value with no exception for that source value drops out. In a matrix row it
+gates by tag — an option carrying no tag that has a rule in the row drops out.
+The `only` rule itself weighs 1.0 (like `allow`), and a target that has any
+other rule in the row keeps that rule, so `only` shuts out the unmentioned and
+leaves the mentioned alone. In a matrix row an `allow` cell does NOT count as
+a mention: the editors show `allow` as the empty "neutral" state, so counting
+it would let an invisible cell through. An `allow` exception is a visible row
+in the exceptions list, so it does count. A payload with no `only` rule never reaches either
+gate, so it folds byte-identically.
 """
 from __future__ import annotations
 
 from typing import Any
 
-EXCLUDE = object()  # sentinel: option drops out of the pool
 
-def _apply_rule(rule: dict[str, Any]):
+class _ExcludeSentinel:
+    """Absorbing zero: the option drops out of the pool entirely.
+
+    A distinct class rather than a bare ``object()`` so a type checker can
+    narrow ``float | _ExcludeSentinel`` after an isinstance test. With the bare
+    sentinel every ``factor *= r`` was unprovable, because ``is EXCLUDE`` does
+    not narrow an ``object``.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid only
+        return "EXCLUDE"
+
+
+EXCLUDE = _ExcludeSentinel()  # sentinel: option drops out of the pool
+
+_Factor = float | _ExcludeSentinel
+
+
+def _apply_rule(rule: dict[str, Any]) -> _Factor:
     mode = rule.get("mode")
     if mode == "exclude":
         return EXCLUDE
@@ -19,10 +58,87 @@ def _apply_rule(rule: dict[str, Any]):
             return max(0.0, float(rule.get("factor", 1.0)))
         except (TypeError, ValueError):
             return 1.0
-    return 1.0  # allow / unknown -> no weight change
+    return 1.0  # allow / only / unknown -> no weight change
 
-def combine_constraint_factor(source_picks, option, matrix, exceptions):
+
+def _row_has_only(row: dict[str, Any]) -> bool:
+    return any(isinstance(r, dict) and r.get("mode") == "only" for r in row.values())
+
+
+def _cell_factor(
+    matrix: dict[str, Any],
+    source_tag: str,
+    opt_tags: list[str],
+    target_axes: dict[str, list[str]] | None = None,
+) -> _Factor:
+    """Fold one source tag against every tag on the option.
+
+    Classify target tags fold with PRODUCT — an option sitting on several rows
+    of the same source tag is genuinely several separate statements about it.
+    Tags belonging to a target ``accepts`` axis (``target_axes``: group →
+    members) fold with MAX instead: the option OFFERS those as ALTERNATIVES, so
+    it stays viable when the source allows ANY of them (the mirror of the
+    source-side accepts fold — the target's own roll is then restricted to the
+    allowed members by the caller). A no-rule target tag is neutral (1.0).
+    EXCLUDE is absorbing for a classify tag and for a fully-excluded axis; the
+    ``target_axes`` path is unreachable unless the caller passes it, so a legacy
+    call folds byte-identically.
+    """
+    row = matrix.get(source_tag)
+    if not isinstance(row, dict):
+        return 1.0
+    # `only` makes the row an allow-list: an option carrying no tag that the
+    # row mentions is shut out. Inside an accepts axis an unmentioned member
+    # then offers nothing (0), rather than the usual neutral 1.0. A neutral
+    # (`allow`) cell is not a mention — see the module docstring.
+    has_only = _row_has_only(row)
+    if has_only:
+        row = {
+            t: r for t, r in row.items()
+            if isinstance(r, dict) and r.get("mode") != "allow"
+        }
+        if not any(t in row for t in opt_tags):
+            return EXCLUDE
+    unruled = 0.0 if has_only else 1.0
+    target_axes = target_axes or {}
+    axis_of = {t: ax for ax, members in target_axes.items() for t in (members or [])}
+    factor = 1.0
+    axis_members: dict[str, list[str]] = {}
+    for t in opt_tags:
+        ax = axis_of.get(t)
+        if ax is None:
+            rule = row.get(t)
+            if isinstance(rule, dict):
+                r = _apply_rule(rule)
+                if isinstance(r, _ExcludeSentinel):
+                    return EXCLUDE
+                factor *= r
+        else:
+            axis_members.setdefault(ax, []).append(t)
+    for members in axis_members.values():
+        best = 0.0
+        for t in members:
+            rule = row.get(t)
+            r = _apply_rule(rule) if isinstance(rule, dict) else unruled
+            best = max(best, 0.0 if isinstance(r, _ExcludeSentinel) else r)
+        # Every alternative this axis offered was excluded → the option drops.
+        if best <= 0.0:
+            return EXCLUDE
+        factor *= best
+    return factor
+
+
+def combine_constraint_factor(
+    source_picks: list[dict[str, Any]] | None,
+    option: dict[str, Any],
+    matrix: dict[str, Any] | None,
+    exceptions: list[Any] | None,
+    axis_kinds: dict[str, str] | None = None,
+    target_axes: dict[str, list[str]] | None = None,
+) -> _Factor:
     matrix = matrix or {}
+    axis_kinds = axis_kinds or {}
+    target_axes = target_axes or {}
     exc_by_pair: dict[tuple[str, str], dict] = {}
     for e in (exceptions or []):
         if not isinstance(e, dict):
@@ -35,6 +151,12 @@ def combine_constraint_factor(source_picks, option, matrix, exceptions):
             t = e.get("target")
         if isinstance(s, str) and isinstance(t, str):
             exc_by_pair[(s, t)] = e
+    # Source values whose exceptions include an `only`: for those, a target
+    # value with no exception of its own is excluded. Read off the de-duplicated
+    # pair map so it agrees with the rule that actually applies to each pair.
+    only_sources = {
+        s for (s, _t), e in exc_by_pair.items() if e.get("mode") == "only"
+    }
     opt_value = str(option.get("value", ""))
     opt_tags = option.get("tags") or []
     factor = 1.0
@@ -44,19 +166,47 @@ def combine_constraint_factor(source_picks, option, matrix, exceptions):
         exc = exc_by_pair.get((p_value, opt_value))
         if exc is not None:
             r = _apply_rule(exc)
-            if r is EXCLUDE:
+            if isinstance(r, _ExcludeSentinel):
                 return EXCLUDE
             factor *= r
             continue
-        for s in p_tags:
-            row = matrix.get(s)
-            if not isinstance(row, dict):
+        if p_value in only_sources:
+            return EXCLUDE
+
+        # Partition this pick's tags: those inside an `accepts` axis fold with
+        # max, the rest keep multiplying. A pick only carries `axes` when the
+        # source wildcard declared the group `accepts`, and `axis_kinds` gates
+        # it a second time, so a legacy pick takes the flat path untouched.
+        pick_axes = pick.get("axes") or {}
+        accepts: dict[str, list[str]] = {}
+        claimed: set[str] = set()
+        for axis, members in pick_axes.items():
+            if axis_kinds.get(axis) != "accepts":
                 continue
-            for t in opt_tags:
-                rule = row.get(t)
-                if isinstance(rule, dict):
-                    r = _apply_rule(rule)
-                    if r is EXCLUDE:
-                        return EXCLUDE
-                    factor *= r
+            in_axis = [t for t in p_tags if t in (members or [])]
+            if in_axis:
+                accepts[axis] = in_axis
+                claimed.update(in_axis)
+
+        for s in p_tags:
+            if s in claimed:
+                continue
+            r = _cell_factor(matrix, s, opt_tags, target_axes)
+            if isinstance(r, _ExcludeSentinel):
+                return EXCLUDE
+            factor *= r
+
+        for members in accepts.values():
+            best = 0.0
+            for s in members:
+                r = _cell_factor(matrix, s, opt_tags, target_axes)
+                # One member's EXCLUDE is that member declining, not the axis
+                # declining — it contributes 0 to the max and the siblings
+                # still get their say.
+                best = max(best, 0.0 if isinstance(r, _ExcludeSentinel) else r)
+            # Every alternative the option offered was excluded, so the option
+            # really does drop out.
+            if best <= 0.0:
+                return EXCLUDE
+            factor *= best
     return factor

engine/modules/_constraints.py

@@ -132,6 +132,8 @@ def apply_constraints_for_target(
     hits=None,
     firing_uid=None,
     carrier_ctx=None,
+    applied_out=None,
+    target_axes=None,
 ) -> tuple[list[dict[str, Any]], bool]:
     """Apply EVERY constraint whose reach selector covers this firing
     target instance, combined sequentially.
@@ -219,9 +221,18 @@ def apply_constraints_for_target(
             continue
         adjust_warnings: list[dict[str, Any]] = []
         options = _apply_constraint_to_options(
-            options, c, src_pick, adjust_warnings,
+            options, c, src_pick, adjust_warnings, target_axes,
         )
         any_applied = True
+        # Record the (constraint, resolved source pick) pairs that actually
+        # covered THIS firing target instance. The caller (wildcard_handler)
+        # uses them to restrict the target's OWN `accepts`-axis roll to tags
+        # these same constraints don't exclude — so `$source.AXIS` and
+        # `$target.AXIS` agree under a diagonal. Only covered constraints land
+        # here, so a selector-limited constraint (`first`/`next`/`pick`) that
+        # skipped this instance also leaves the axis roll alone.
+        if applied_out is not None:
+            applied_out.append((c, src_pick))
         for w in adjust_warnings:
             _push_constraint_warning(
                 warnings,
@@ -242,10 +253,10 @@ def warn_excludes_all(
     warnings: list[dict[str, Any]],
 ) -> None:
     """Emit the ``constraint_excludes_all_options`` warning when post-
-    application weights sum to zero. ``_pick_weighted`` falls back to
-    ``options[0]`` silently — without this warning the user sees the
-    same option forever with no signal that constraints over-narrowed
-    the pool.
+    application weights sum to zero. ``_pick_weighted`` returns None for
+    such a pool and the wildcard binds an empty string, so without this
+    warning an over-narrowed pool is indistinguishable from a wildcard
+    that legitimately rolled its null option.
 
     Call AFTER ``apply_constraints_for_target`` returned ``any_applied``.
     """
@@ -259,6 +270,6 @@ def warn_excludes_all(
             target_uuid=target_uuid,
             detail={
                 "target_wildcard_id": target_uuid,
-                "hint": "every option was excluded; falling back to options[0]",
+                "hint": "every option was excluded; the target emits nothing",
             },
         )

engine/modules/_detail.py

@@ -0,0 +1,24 @@
+"""Per-module run detail for the WP Debug node.
+
+A run opts in by setting ``ctx["__wp_explain__"] = True`` (the canvas Context
+node does; the Test Runner's thousand-seed runs don't). The pipeline then gives
+each module an empty ``ctx["__wp_module_detail__"]`` dict before it resolves and
+files whatever the handler put there on that module's trace row as ``detail``.
+
+Handlers call :func:`module_detail` and write only when it returns a dict, so
+an un-opted run pays one dict lookup per module and nothing else.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+EXPLAIN_KEY = "__wp_explain__"
+DETAIL_KEY = "__wp_module_detail__"
+
+
+def module_detail(ctx: Any) -> dict[str, Any] | None:
+    """The active module's detail sink, or None when nobody asked for one."""
+    if not isinstance(ctx, dict):
+        return None
+    sink = ctx.get(DETAIL_KEY)
+    return sink if isinstance(sink, dict) else None

engine/modules/_fallback.py

@@ -0,0 +1,68 @@
+"""Wildcard fallback option (schema v9).
+
+A wildcard may mark one non-null option ``fallback: true``. That option rolls
+like any other (its weight, the node's filters + toggles and constraints all
+apply), and is ALSO taken, without an rng draw, when nothing is left to pick:
+every option, the fallback included, was excluded by a constraint (an Only
+rule included) or weighted 0. Without a fallback such a wildcard binds an
+empty string, which is what it did before v9 and still does. Flagging an
+option never changes a normal draw. A fallback weighted 0 is only ever used
+as the fallback.
+
+Shared by the top-level wildcard handler and the nested ``@{uuid}`` resolver
+so both surfaces agree. The node's filters + toggles decide whether the
+fallback is available at all (``find_fallback`` runs after them).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_fallback(option: Any) -> bool:
+    """True for an option flagged as the wildcard's fallback. The null option
+    can't be one (an empty fallback is what having none already means)."""
+    return (
+        isinstance(option, dict)
+        and option.get("fallback") is True
+        and not option.get("is_null")
+    )
+
+
+def find_fallback(options: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """The first flagged option in ``options`` (validation allows one), as it
+    was before weights + constraints. It stays in the draw pool."""
+    return next((o for o in options if is_fallback(o)), None)
+
+
+def pool_is_dead(options: list[dict[str, Any]]) -> bool:
+    """True when a weighted draw over ``options`` has nothing to pick."""
+    total = 0.0
+    for o in options:
+        try:
+            total += max(0.0, float(o.get("weight", 1)))
+        except (TypeError, ValueError):
+            continue
+    return total <= 0
+
+
+def fallback_warning(
+    target_uuid: str, fallback: dict[str, Any], *, constrained: bool,
+) -> dict[str, Any]:
+    """The info-level ``fallback_used`` note WP Debug and the Test Runner show
+    in place of ``constraint_excludes_all_options``."""
+    why = "constraints excluded every option" if constrained else "no option was left to pick"
+    return {
+        "type": "fallback_used",
+        "severity": "info",
+        "module_id": target_uuid,
+        "source_field": "",
+        "position": 0,
+        "token_index": None,
+        "detail": {
+            "target_wildcard_id": target_uuid,
+            "option_id": fallback.get("id"),
+            "value": fallback.get("value", ""),
+            "reason": "constraints" if constrained else "empty_pool",
+        },
+        "message": f"{why}; used the fallback {fallback.get('value', '')!r}",
+    }

engine/modules/combine_handler.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from engine import negatives
 from engine.modules import build_resolve_ctx
 from engine.modules._seed import derive_module_rng
 from engine.modules.dispatcher import ModuleHandler
@@ -72,6 +73,9 @@ class CombineHandler(ModuleHandler):
         for v in input_vars:
             if not isinstance(v, str):
                 raise ValueError("combine payload.input_vars entries must be strings")
+        neg = payload.get("negative")
+        if neg is not None and not isinstance(neg, str):
+            raise ValueError("combine payload.negative must be a string")
 
     @classmethod
     def resolve(
@@ -107,6 +111,7 @@ class CombineHandler(ModuleHandler):
             # frozen across the whole run, nested refs included.
             _hb = ctx.get("__wp_hold_base_ctx__")
             if isinstance(_hb, dict) and output_var in _hb:
+                negatives.copy_from(ctx, _hb, [output_var])
                 return {output_var: _hb[output_var]}
             chain_seed = int(ctx.get("__wp_node_seed_hold__", ctx.get("__wp_node_seed__", 0)) or 0)
         else:
@@ -122,5 +127,17 @@ class CombineHandler(ModuleHandler):
         # picks up our derived RNG instead of the chain RNG.
         ctx_local = {**ctx, "__wp_rng__": rng}
         resolve_ctx = build_resolve_ctx(ctx_local, surface="combine")
-        result = resolve_text(template, resolve_ctx)
+        with negatives.collecting(resolve_ctx) as col:
+            result = resolve_text(template, resolve_ctx)
+        # Send-to-negative: the phrase carries the negatives of every variable
+        # its template rendered, plus its own (resolved quietly on the
+        # combine's negative stream so its {a|b} never shifts the value's).
+        own = negatives.clean_negative(payload.get("negative"))
+        entries = negatives.entries_for_reads(ctx, col.reads)
+        entries += negatives.own_entries(
+            [own] if own else [], resolve_ctx,
+            negatives.neg_rng(effective_seed, output_var),
+            pick=None, source=output_var,
+        )
+        negatives.set_entries(ctx, output_var, entries)
         return {output_var: result}

engine/modules/constraint_handler.py

@@ -19,10 +19,13 @@ from __future__ import annotations
 
 from typing import Any
 
+from engine.modules._detail import module_detail
 from engine.modules._keys import decode_key, encode_key
 from engine.modules.dispatcher import ModuleHandler
 
-_VALID_MODES = {"allow", "exclude", "boost", "reduce"}
+# `only` (2026-09, linked picks) turns its row into an allow-list — see
+# `_constraint_math`. Additive: a payload using it stamps schema_version 6.
+_VALID_MODES = {"allow", "exclude", "boost", "reduce", "only"}
 
 # SP3 reach selector — which downstream target instance(s) a constraint
 # reaches. Shape only here; reach *behaviour* is applied by a later task.
@@ -142,6 +145,14 @@ def _ctx_set_constraint(ctx: Any, meta: dict[str, Any]) -> None:
             })
 
 
+def _override_mode(mode: Any) -> Any:
+    """Canvas matrix builds before 2026-09 stored a neutral cell override as
+    ``"neutral"`` (the editor's name) instead of ``"allow"`` (the engine's),
+    which failed the whole constraint at run time. Read it as ``allow`` so
+    workflows saved by those builds run."""
+    return "allow" if mode == "neutral" else mode
+
+
 def _validate_cell(cell: Any, where: str) -> None:
     if not isinstance(cell, dict):
         raise ValueError(f"constraint {where} must be an object")
@@ -163,6 +174,55 @@ def _validate_cell(cell: Any, where: str) -> None:
         raise ValueError(f"constraint {where}.factor must not be negative")
 
 
+def exception_pair(exc: dict[str, Any]) -> tuple[str, str] | None:
+    """The `(source, target)` key an exception is filed under, or None.
+
+    MUST match `_constraint_math.combine_constraint_factor`'s key resolution
+    exactly — tier-2 `source_value`/`target_value` first, legacy
+    `source`/`target` as fallback. If the two ever disagree, the duplicate
+    check below stops describing what the engine actually does.
+    """
+    source = exc.get("source_value")
+    if source is None:
+        source = exc.get("source")
+    target = exc.get("target_value")
+    if target is None:
+        target = exc.get("target")
+    if isinstance(source, str) and isinstance(target, str):
+        return (source, target)
+    return None
+
+
+def find_duplicate_exception_pairs(payload: dict[str, Any]) -> list[tuple[str, str]]:
+    """`(source, target)` pairs appearing more than once, in first-seen order.
+
+    Two exceptions on the same pair cannot both apply. `combine_constraint_factor`
+    files them into a dict keyed by the pair, so the LAST one in the list wins
+    and every earlier one is discarded silently — and that includes discarding
+    an `exclude`, which the documented model says is absorbing:
+
+        exceptions [exclude, boost x3]  ->  factor 3.0   (exclusion defeated)
+        exceptions [boost x3, exclude]  ->  EXCLUDE
+        exceptions [boost x3, reduce x0.5] -> 0.5  (not the combined 1.5)
+
+    So the result depends on list order, which no surface shows and nothing
+    lets you edit. Reported by the maintainer 2026-08-06 after noticing the
+    editor would happily accept contradictory duplicates.
+    """
+    seen: set[tuple[str, str]] = set()
+    duplicates: list[tuple[str, str]] = []
+    for exc in payload.get("exceptions") or []:
+        if not isinstance(exc, dict):
+            continue
+        pair = exception_pair(exc)
+        if pair is None:
+            continue
+        if pair in seen and pair not in duplicates:
+            duplicates.append(pair)
+        seen.add(pair)
+    return duplicates
+
+
 class ConstraintHandler(ModuleHandler):
     """Records a constraint matrix into the context for downstream consumers."""
 
@@ -236,6 +296,31 @@ class ConstraintHandler(ModuleHandler):
                 )
         _validate_target_select(payload.get("target_select"))
 
+    @classmethod
+    def validate_authoring(cls, payload: dict[str, Any]) -> None:
+        """Extra rules applied when a payload is SAVED or IMPORTED, not when
+        it is executed.
+
+        Deliberately separate from `validate_payload`, which `resolve` calls on
+        every run. A rule enforced there would turn an existing bad payload
+        into a hard failure mid-graph — strictly worse than the silent
+        misbehaviour it replaces, and it would fire on data the user cannot
+        reach to fix without the graph running. Enforcing at the authoring
+        boundary stops new ones being created (from the editor, the API, or an
+        import) while leaving existing rows executable.
+        """
+        duplicates = find_duplicate_exception_pairs(payload)
+        if duplicates:
+            listed = ", ".join(
+                f"({source!r} -> {target!r})" for source, target in duplicates
+            )
+            raise ValueError(
+                "constraint payload.exceptions contains more than one rule for "
+                f"the same source/target pair: {listed}. Only one can apply — "
+                "the engine keeps whichever comes last — so keep the rule you "
+                "want and delete the rest."
+            )
+
     @classmethod
     def resolve(
         cls,
@@ -288,7 +373,7 @@ class ConstraintHandler(ModuleHandler):
                 # value across resolves.
                 merged = dict(cell)
                 if key in cell_mode_overrides:
-                    mode = cell_mode_overrides[key]
+                    mode = _override_mode(cell_mode_overrides[key])
                     if mode not in _VALID_MODES:
                         raise ValueError(
                             f"constraint cell_mode_overrides[{key!r}] must be one of "
@@ -328,7 +413,7 @@ class ConstraintHandler(ModuleHandler):
             if len(parts) != 2:
                 continue
             src, tgt = parts[0], parts[1]
-            mode = cell_mode_overrides.get(key, "allow")
+            mode = _override_mode(cell_mode_overrides.get(key, "allow"))
             if mode not in _VALID_MODES:
                 raise ValueError(
                     f"constraint cell_mode_overrides[{key!r}] must be one of "
@@ -486,4 +571,17 @@ class ConstraintHandler(ModuleHandler):
             "__constraint_bundle_origin__": bundle_origin,
         }
         _ctx_set_constraint(ctx, meta)
+        detail = module_detail(ctx)
+        if detail is not None:
+            cells = [c for row in matrix.values() for c in row.values()]
+            detail.update({
+                "uid": module_id or "",
+                "reach": ts,
+                "cells": len(cells),
+                "exceptions": len(exceptions),
+                "only": any(
+                    isinstance(r, dict) and r.get("mode") == "only"
+                    for r in (*cells, *exceptions)
+                ),
+            })
         return {}

engine/modules/derivation_handler.py

@@ -1,11 +1,16 @@
 """Derivation module resolver — IF/ELIF/ELSE rules over the runtime context.
 
 Each rule has an ordered list of branches (index 0 == IF, the rest == ELIF)
-and an optional ``else`` clause. Rules evaluate independently top-to-bottom:
+and an optional ``else`` clause. A branch ``condition`` is either one test
+(``{var, op, value}``) or a group (``{match: "all"|"any", conditions: [...]}``)
+whose members are tests or further groups, so a branch can AND / OR several
+tests together (schema v7). Rules evaluate independently top-to-bottom:
 the first branch whose condition matches wins; if none match, the ``else``
 action (if any) fires; otherwise the rule is a no-op.
 
-Actions mutate the runtime context directly. Multiple rules can target the
+A branch (and the ``else`` clause) runs its ``action`` and then, in order,
+each entry of its optional ``extra_actions`` list (schema v8): "THEN ... AND
+...". Actions mutate the runtime context directly. Multiple rules can target the
 same variable; later rules see earlier mutations. Action ``value`` strings
 are resolved through resolve_text with surface="derivation" so $var tokens
 and {a|b|c} picks work inside derivation action values.
@@ -15,11 +20,18 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from engine import negatives
 from engine.modules import build_resolve_ctx
+from engine.modules._detail import module_detail
 from engine.modules._seed import derive_module_rng
 from engine.modules.dispatcher import ModuleHandler
 from engine.syntax import resolve_text
-from engine.syntax.types import deref_var_value, split_var_accessor
+from engine.syntax.resolve import NEG_ACCESSOR
+from engine.syntax.types import (
+    deref_var_value,
+    parse_var_reference,
+    split_var_accessor,
+)
 
 _VALID_OPS = {
     "equals", "not_equals", "contains", "matches",
@@ -30,8 +42,22 @@ _VALID_OPS = {
     # semantics they need — wildcards can pick options with empty
     # values, leaving keys present-but-empty.
     "exists", "not_exists", "is_set", "is_unset",
+    # Emptiness refinements the editor's "exists" switch has always offered.
+    # `is_empty` is "present and empty" (a wildcard that rolled its null
+    # option); `is_not_empty` is "resolved to something non-empty".
+    "is_empty", "is_not_empty",
 }
-_VALID_MODES = {"replace", "append", "prepend"}
+_VALID_MATCHES = {"all", "any"}
+_MISSING = object()
+# Groups nest; the editor stops at three levels, the cap here only guards a
+# hand-built payload against runaway recursion.
+_MAX_CONDITION_DEPTH = 8
+# `negative` (schema v8, send-to-negative): "Add to negative" — the value is
+# added to the target variable's negatives; the variable itself is untouched.
+# `negative_replace` (also v8): "Replace negative" — the value becomes the
+# variable's only negative, dropping what it carried.
+NEGATIVE_MODES = {"negative", "negative_replace"}
+_VALID_MODES = {"replace", "append", "prepend", *NEGATIVE_MODES}
 
 
 def _ctx_get_raw(ctx: Any, name: str) -> Any:
@@ -56,14 +82,58 @@ def _ctx_get_raw(ctx: Any, name: str) -> Any:
     return None
 
 
+def _ctx_axis(ctx: Any, base: str, axis: str, index: int | None) -> str:
+    """Read a rolled axis choice out of `ctx["__wp_axes__"]`.
+
+    Mirrors the resolver's `_resolve_axis` shaping so a condition and a
+    template agree on what `$outfit.SHOES` means. Missing yields "" rather than
+    raising: derivations are control flow, so an unanswerable condition is
+    simply false.
+    """
+    if not isinstance(ctx, dict):
+        return ""
+    entry = (ctx.get("__wp_axes__") or {}).get(base)
+    if isinstance(entry, list):
+        # Positional, like the resolver: a pick with no tag on this axis keeps
+        # its slot so `.K` lines up with `$outfit.K`.
+        vals = [
+            (e.get(axis) or "") if isinstance(e, dict) else "" for e in entry
+        ]
+        if index is None:
+            return ", ".join(v for v in vals if v)
+        return vals[index] if 0 <= index < len(vals) else ""
+    if isinstance(entry, dict):
+        got = entry.get(axis, "")
+        # A single pick behaves as a one-element list, as everywhere else.
+        if index is not None:
+            return got if index == 0 else ""
+        return got
+    return ""
+
+
 def _ctx_get(ctx: Any, name: str) -> str:
-    """Read `name` as a string, honoring a `.K` list accessor and folding a
-    ListVar to its joined value (SP2a): `$mood.0` splits to base `mood` +
-    index 0. The fold/accessor contract lives in deref_var_value."""
-    base, index = split_var_accessor(name)
+    """Read `name` as a string, honoring a `.K` list accessor, a `.AXIS` read
+    (2026-08 tag axes), and folding a ListVar to its joined value (SP2a):
+    `$mood.0` splits to base `mood` + index 0. The fold/accessor contract lives
+    in deref_var_value; the axis contract in `_ctx_axis`."""
+    base, index, axis = parse_var_reference(name)
+    if axis == NEG_ACCESSOR:
+        return _ctx_negative(ctx, base, index)
+    if axis:
+        return _ctx_axis(ctx, base, axis, index)
     return deref_var_value(_ctx_get_raw(ctx, base), index)
 
 
+def _ctx_negative(ctx: Any, base: str, index: int | None) -> str:
+    """`$name.neg` in a condition: the variable's negatives as one line,
+    read the same way the resolver renders them."""
+    texts = [
+        str(e.get("text", "")) for e in negatives.get_entries(ctx, base)
+        if index is None or e.get("pick") is None or e.get("pick") == index
+    ]
+    return negatives.join_unique(texts)
+
+
 def _ctx_has(ctx: Any, name: str) -> bool:
     """Whether `name` is a known key in `ctx`, regardless of value.
 
@@ -76,7 +146,23 @@ def _ctx_has(ctx: Any, name: str) -> bool:
     """
     if ctx is None:
         return False
-    name = split_var_accessor(name)[0]  # SP2a: presence checks the base var
+    base, _index, axis = parse_var_reference(name)
+    if axis == NEG_ACCESSOR:
+        return bool(_ctx_negative(ctx, base, _index))
+    if axis:
+        # An axis is present when the binding actually rolled it. Checked
+        # against the axes bucket, not ctx: `$outfit.SHOES` can exist while
+        # `outfit` is unbound, and vice versa.
+        entry = (
+            (ctx.get("__wp_axes__") or {}).get(base)
+            if isinstance(ctx, dict) else None
+        )
+        if isinstance(entry, dict):
+            return axis in entry
+        if isinstance(entry, list):
+            return any(isinstance(e, dict) and axis in e for e in entry)
+        return False
+    name = base  # SP2a: presence checks the base var
     # Engine ctx is a dict in tests + at runtime; check `__contains__`
     # before falling back to a getter probe so we get the cheap path.
     try:
@@ -129,6 +215,10 @@ def _match_condition(condition: dict[str, Any], ctx: Any) -> bool:
         return _ctx_has(ctx, var) and _ctx_get(ctx, var) != ""
     if op == "is_unset":
         return not _ctx_has(ctx, var) or _ctx_get(ctx, var) == ""
+    if op == "is_empty":
+        return _ctx_has(ctx, var) and _ctx_get(ctx, var) == ""
+    if op == "is_not_empty":
+        return _ctx_get(ctx, var) != ""
     actual = _ctx_get(ctx, var)
     if op == "equals":
         return actual == value
@@ -144,6 +234,91 @@ def _match_condition(condition: dict[str, Any], ctx: Any) -> bool:
     return False
 
 
+def is_condition_group(condition: Any) -> bool:
+    """A group carries ``conditions``; a single test carries ``var``."""
+    return isinstance(condition, dict) and "conditions" in condition
+
+
+def condition_leaves(condition: Any) -> list[dict[str, Any]]:
+    """Every single test in ``condition``, depth-first. The position in this
+    list is the test's override index (see ``condition_override_key``)."""
+    if is_condition_group(condition):
+        out: list[dict[str, Any]] = []
+        for child in condition.get("conditions") or []:
+            out.extend(condition_leaves(child))
+        return out
+    return [condition] if isinstance(condition, dict) else []
+
+
+def condition_override_key(branch_index: int, leaf_index: int) -> str:
+    """Key into ``condition_value_overrides[rule_id]`` for one test of a
+    branch. The first test keeps the bare branch index it always had, so a
+    single-test branch and its saved overrides are unchanged; later tests of a
+    grouped branch append ``.K`` (their depth-first position).
+
+    MUST stay byte-identical to the TS twin ``conditionOverrideKey`` in
+    ``src/extension/derivation-conditions.ts``.
+    """
+    return str(branch_index) if leaf_index == 0 else f"{branch_index}.{leaf_index}"
+
+
+def _with_value_overrides(
+    condition: Any, overrides: dict[str, Any], branch_index: int,
+) -> Any:
+    """Copy of ``condition`` with each test's ``value`` swapped for its
+    instance override, when one is set."""
+    counter = [0]
+
+    def walk(node: Any) -> Any:
+        if is_condition_group(node):
+            return {**node, "conditions": [walk(c) for c in node.get("conditions") or []]}
+        if not isinstance(node, dict):
+            return node
+        key = condition_override_key(branch_index, counter[0])
+        counter[0] += 1
+        override = overrides.get(key)
+        return {**node, "value": override} if isinstance(override, str) else node
+
+    return walk(condition)
+
+
+def _eval_condition(condition: Any, ctx: Any) -> bool:
+    if is_condition_group(condition):
+        children = condition.get("conditions") or []
+        if condition.get("match") == "any":
+            return any(_eval_condition(c, ctx) for c in children)
+        return all(_eval_condition(c, ctx) for c in children)
+    if not isinstance(condition, dict):
+        return False
+    return _match_condition(condition, ctx)
+
+
+def _explain_condition(condition: Any, ctx: Any) -> dict[str, Any]:
+    """The condition tree with each test's outcome and the value it read, for
+    the WP Debug node. Evaluates every test, unlike ``_eval_condition``, so a
+    group that short-circuited still shows why each member did or didn't
+    match. Reads only; nothing here writes to ``ctx``."""
+    if is_condition_group(condition):
+        children = [_explain_condition(c, ctx) for c in condition.get("conditions") or []]
+        match = "any" if condition.get("match") == "any" else "all"
+        results = [c["result"] for c in children]
+        return {
+            "match": match,
+            "result": any(results) if match == "any" else all(results),
+            "conditions": children,
+        }
+    if not isinstance(condition, dict):
+        return {"var": "", "op": "", "value": "", "actual": None, "result": False}
+    var = str(condition.get("var", ""))
+    return {
+        "var": var,
+        "op": str(condition.get("op", "")),
+        "value": condition.get("value", ""),
+        "actual": _ctx_get(ctx, var) if _ctx_has(ctx, var) else None,
+        "result": _match_condition(condition, ctx),
+    }
+
+
 def branch_carrier_key(rule_id: str, branch: int | str) -> str:
     """Carrier key for a derivation branch occurrence -- the `option_id` the
     SP3 nested-occurrence model matches a constraint `pick` against. `branch`
@@ -161,12 +336,30 @@ def _apply_action(
     ctx: Any,
     resolve_ctx: Any,
     carrier_key: str | None = None,
-) -> tuple[str, str] | None:
+    neg_seed: int | None = None,
+    neg_key: str | None = None,
+) -> tuple[str, str | None] | None:
+    """Run one action. Returns (target, new value), with value None for an
+    "Add to negative" / "Replace negative" action (it writes no value), or None when it did
+    nothing. `neg_seed` + `neg_key` key the action's negative stream
+    (`neg_key` defaults to the carrier key)."""
     target = action.get("target_var", "")
     if not target:
         return None
     mode = action.get("mode", "replace")
     raw_value = str(action.get("value", ""))
+    n_rng = negatives.neg_rng(
+        neg_seed or 0, f"derivation::{neg_key or carrier_key or target}",
+    )
+    if mode in NEGATIVE_MODES:
+        text = negatives.quiet_resolve(raw_value, resolve_ctx, n_rng)
+        negatives.set_entries(
+            ctx, target,
+            [{"text": text, "pick": None, "source": carrier_key or "derivation"}],
+            add=mode == "negative",
+        )
+        return target, None
+    col = negatives.Collector()
     # Stamp this derivation instance as the CARRIER of any `@{}` in the action
     # value, keyed by the branch key (`${rule_id}:${bi}` / `${rule_id}:else`) —
     # the `option_id` the SP3 nested-occurrence model matches a `pick` against.
@@ -181,26 +374,91 @@ def _apply_action(
         prev = get_carrier()
         set_carrier(module_uid, carrier_key)
         try:
-            new_value = resolve_text(raw_value, resolve_ctx)
+            with negatives.collecting(resolve_ctx) as col:
+                new_value = resolve_text(raw_value, resolve_ctx)
         finally:
             set_carrier(*prev)
     else:
-        new_value = resolve_text(raw_value, resolve_ctx)
+        with negatives.collecting(resolve_ctx) as col:
+            new_value = resolve_text(raw_value, resolve_ctx)
+    if mode not in ("replace", "append", "prepend"):
+        return None
+    # The written text carries the negatives of the variables it read and of
+    # the options its refs picked. Replace swaps the target's negatives for
+    # those; append / prepend keep the old ones and add.
+    entries = negatives.entries_for_reads(ctx, col.reads)
+    entries += negatives.own_entries(
+        col.ref_negatives, resolve_ctx, n_rng,
+        pick=None, source=carrier_key or "derivation",
+    )
+    negatives.set_entries(ctx, target, entries, add=mode != "replace")
     if mode == "replace":
         result = new_value
     elif mode == "append":
         result = _ctx_get(ctx, target) + new_value
-    elif mode == "prepend":
-        result = new_value + _ctx_get(ctx, target)
     else:
-        return None
+        result = new_value + _ctx_get(ctx, target)
     _ctx_set(ctx, target, result)
     return target, result
 
 
-def _validate_condition(condition: Any, where: str) -> None:
+def clause_actions(clause: Any) -> list[dict[str, Any]]:
+    """Every action a branch or ``else`` clause runs, in order: its ``action``
+    then its ``extra_actions``. Non-dict entries are skipped."""
+    if not isinstance(clause, dict):
+        return []
+    out = [clause.get("action")]
+    extra = clause.get("extra_actions")
+    if isinstance(extra, list):
+        out.extend(extra)
+    return [a for a in out if isinstance(a, dict)]
+
+
+def action_override_key(branch: int | str, action_index: int) -> str:
+    """Key into ``action_value_overrides[rule_id]`` for one action of a branch
+    (``branch`` is the index or ``"else"``). The first action keeps the bare
+    key it always had; later ones append ``.K``.
+
+    MUST stay byte-identical to the TS twin ``actionOverrideKey`` in
+    ``src/extension/derivation-conditions.ts``.
+    """
+    return str(branch) if action_index == 0 else f"{branch}.{action_index}"
+
+
+def _explain_action(
+    action: dict[str, Any], pair: tuple[str, str | None] | None,
+) -> dict[str, Any]:
+    """What a fired branch did: the variable, how it wrote, and the result."""
+    return {
+        "target": str(action.get("target_var", "")),
+        "mode": str(action.get("mode", "replace")),
+        "value": str(action.get("value", "")),
+        "result": pair[1] if pair is not None else None,
+    }
+
+
+def _validate_condition(condition: Any, where: str, depth: int = 0) -> None:
     if not isinstance(condition, dict):
         raise ValueError(f"derivation {where}.condition must be an object")
+    if is_condition_group(condition):
+        if depth >= _MAX_CONDITION_DEPTH:
+            raise ValueError(
+                f"derivation {where}.condition nests deeper than "
+                f"{_MAX_CONDITION_DEPTH} groups"
+            )
+        if condition.get("match") not in _VALID_MATCHES:
+            raise ValueError(
+                f"derivation {where}.condition.match must be one of "
+                f"{sorted(_VALID_MATCHES)}"
+            )
+        children = condition.get("conditions")
+        if not isinstance(children, list) or not children:
+            raise ValueError(
+                f"derivation {where}.condition.conditions must be a non-empty list"
+            )
+        for ci, child in enumerate(children):
+            _validate_condition(child, f"{where}.condition.conditions[{ci}]", depth + 1)
+        return
     var = condition.get("var")
     if not isinstance(var, str) or not var:
         raise ValueError(f"derivation {where}.condition.var must be a non-empty string")
@@ -230,6 +488,16 @@ def _validate_action(action: Any, where: str) -> None:
         raise ValueError(f"derivation {where}.action.value must be a string")
 
 
+def _validate_extra_actions(clause: dict[str, Any], where: str) -> None:
+    extra = clause.get("extra_actions")
+    if extra is None:
+        return
+    if not isinstance(extra, list):
+        raise ValueError(f"derivation {where}.extra_actions must be a list")
+    for ai, action in enumerate(extra):
+        _validate_action(action, f"{where}.extra_actions[{ai}]")
+
+
 class DerivationHandler(ModuleHandler):
     """IF / ELIF / ELSE rule evaluator that mutates ctx."""
 
@@ -273,6 +541,7 @@ class DerivationHandler(ModuleHandler):
                     branch.get("condition"), f"rules[{ri}].branches[{bi}]"
                 )
                 _validate_action(branch.get("action"), f"rules[{ri}].branches[{bi}]")
+                _validate_extra_actions(branch, f"rules[{ri}].branches[{bi}]")
             else_clause = rule.get("else")
             if else_clause is not None:
                 if not isinstance(else_clause, dict):
@@ -280,6 +549,7 @@ class DerivationHandler(ModuleHandler):
                         f"derivation payload.rules[{ri}].else must be an object"
                     )
                 _validate_action(else_clause.get("action"), f"rules[{ri}].else")
+                _validate_extra_actions(else_clause, f"rules[{ri}].else")
 
     @classmethod
     def resolve(
@@ -363,10 +633,76 @@ class DerivationHandler(ModuleHandler):
             )
 
         out: dict[str, str] = {}
+        # WP Debug: which branch of each rule fired and why (explain runs only).
+        detail = module_detail(ctx)
+        explained: list[dict[str, Any]] | None = [] if detail is not None else None
+
+        def run_clause(
+            rule_id: str, key: int | str, clause: dict[str, Any],
+            rd: dict[str, Any] | None,
+        ) -> None:
+            """Run a fired branch's (or the else clause's) actions in order.
+            Each action sees the writes of the ones before it. Action-value
+            overrides are keyed per action (``action_override_key``)."""
+            carrier = branch_carrier_key(rule_id, key)
+            rule_overrides = action_overrides.get(rule_id)
+            b_ctx = _branch_resolve_ctx(carrier)
+            shown: list[dict[str, Any]] = []
+            saved: dict[str, Any] = {}
+            for ai, action in enumerate(clause_actions(clause)):
+                override = (
+                    rule_overrides.get(action_override_key(key, ai))
+                    if isinstance(rule_overrides, dict) else None
+                )
+                if isinstance(override, str):
+                    action = {**action, "value": override}
+                # Later actions key their negative stream apart so two
+                # "Add to negative" actions on one branch never share rolls.
+                pair = _apply_action(
+                    action, ctx, b_ctx,
+                    carrier_key=carrier,
+                    neg_seed=effective_seed,
+                    neg_key=carrier if ai == 0 else f"{carrier}.{ai}",
+                )
+                if pair is not None and pair[1] is not None:
+                    out[pair[0]] = pair[1]
+                    # The next action of this branch reads what this one
+                    # wrote. Scoped to the branch (restored below) so rules
+                    # keep resolving their values exactly as before.
+                    vars_view = getattr(b_ctx, "_vars", None)
+                    if isinstance(vars_view, dict):
+                        base = split_var_accessor(pair[0])[0]
+                        if base not in saved:
+                            saved[base] = vars_view.get(base, _MISSING)
+                        vars_view[base] = pair[1]
+                shown.append(_explain_action(action, pair))
+            vars_view = getattr(b_ctx, "_vars", None)
+            if isinstance(vars_view, dict):
+                for base, prev in saved.items():
+                    if prev is _MISSING:
+                        vars_view.pop(base, None)
+                    else:
+                        vars_view[base] = prev
+            if rd is not None:
+                rd["fired"] = key
+                if shown:
+                    rd["action"] = shown[0]
+                    rd["actions"] = shown
 
         for rule in rules:
             rule_id = rule.get("id", "")
+            rd: dict[str, Any] | None = None
+            if explained is not None:
+                rd = {
+                    "id": rule_id,
+                    "fired": None,
+                    "branches": [],
+                    "has_else": isinstance(rule.get("else"), dict),
+                }
+                explained.append(rd)
             if rule_id in disabled_rule_ids:
+                if rd is not None:
+                    rd["disabled"] = True
                 continue
 
             applied = False
@@ -375,59 +711,37 @@ class DerivationHandler(ModuleHandler):
                 # even when listed because disabling IF == disabling rule
                 # (the per-rule toggle handles that case cleanly).
                 if bi != 0 and branch_carrier_key(rule_id, bi) in disabled_branch_keys:
+                    if rd is not None:
+                        rd["branches"].append({"index": bi, "disabled": True})
                     continue
 
-                # Condition-value override per branch index.
+                # Condition-value overrides, one per test of the branch.
                 cond = branch.get("condition", {})
-                cond_override = (
-                    cond_overrides.get(rule_id, {}).get(str(bi))
-                    if isinstance(cond_overrides.get(rule_id), dict)
-                    else None
-                )
-                if isinstance(cond_override, str):
-                    cond = {**cond, "value": cond_override}
+                rule_cond_overrides = cond_overrides.get(rule_id)
+                if isinstance(rule_cond_overrides, dict) and rule_cond_overrides:
+                    cond = _with_value_overrides(cond, rule_cond_overrides, bi)
 
-                if _match_condition(cond, ctx):
-                    # Action-value override per branch index.
-                    action = branch.get("action", {})
-                    action_override = (
-                        action_overrides.get(rule_id, {}).get(str(bi))
-                        if isinstance(action_overrides.get(rule_id), dict)
-                        else None
-                    )
-                    if isinstance(action_override, str):
-                        action = {**action, "value": action_override}
-
-                    pair = _apply_action(
-                        action, ctx,
-                        _branch_resolve_ctx(branch_carrier_key(rule_id, bi)),
-                        carrier_key=branch_carrier_key(rule_id, bi),
-                    )
-                    if pair is not None:
-                        out[pair[0]] = pair[1]
+                matched = _eval_condition(cond, ctx)
+                if rd is not None:
+                    rd["branches"].append({
+                        "index": bi,
+                        "matched": matched,
+                        "condition": _explain_condition(cond, ctx),
+                    })
+                if matched:
+                    run_clause(rule_id, bi, branch, rd)
                     applied = True
                     break
 
             if not applied:
                 # ELSE skip when listed in disabled_branch_keys.
                 if branch_carrier_key(rule_id, "else") in disabled_branch_keys:
+                    if rd is not None:
+                        rd["else_disabled"] = True
                     continue
                 else_clause = rule.get("else")
                 if isinstance(else_clause, dict):
-                    action = else_clause.get("action", {})
-                    # ELSE action-value override under `else` key.
-                    action_override = (
-                        action_overrides.get(rule_id, {}).get("else")
-                        if isinstance(action_overrides.get(rule_id), dict)
-                        else None
-                    )
-                    if isinstance(action_override, str):
-                        action = {**action, "value": action_override}
-                    pair = _apply_action(
-                        action, ctx,
-                        _branch_resolve_ctx(branch_carrier_key(rule_id, "else")),
-                        carrier_key=branch_carrier_key(rule_id, "else"),
-                    )
-                    if pair is not None:
-                        out[pair[0]] = pair[1]
+                    run_clause(rule_id, "else", else_clause, rd)
+        if detail is not None:
+            detail["rules"] = explained
         return out

engine/modules/fixed_values_handler.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from engine import negatives
 from engine.modules import build_resolve_ctx
 from engine.modules._seed import derive_module_rng
 from engine.modules.dispatcher import ModuleHandler
@@ -84,6 +85,11 @@ class FixedValuesHandler(ModuleHandler):
                 raise ValueError(
                     f"fixed_values payload.values[{i}].value must be a string"
                 )
+            neg = v.get("negative")
+            if neg is not None and not isinstance(neg, str):
+                raise ValueError(
+                    f"fixed_values payload.values[{i}].negative must be a string"
+                )
 
     @classmethod
     def resolve(
@@ -134,7 +140,8 @@ class FixedValuesHandler(ModuleHandler):
         enabled = instance.get("enabled_options")
         if enabled is not None:
             allowed = set(enabled)
-            values = [v for v in values if v.get("id") in allowed]
+            keys = _row_keys(values)
+            values = [v for v, k in zip(values, keys, strict=True) if k in allowed]
 
         # Syntax-aware emission path. When ctx is missing required keys
         # for build_resolve_ctx (legacy callers passing None / minimal
@@ -158,6 +165,7 @@ class FixedValuesHandler(ModuleHandler):
             if isinstance(_hb, dict):
                 _names = [n for n in ((v.get("name") or "").strip() for v in values) if n]
                 if _names and all(n in _hb for n in _names):
+                    negatives.copy_from(ctx, _hb, _names)
                     return {n: _hb[n] for n in _names}
             chain_seed = int(
                 ctx.get("__wp_node_seed_hold__", ctx.get("__wp_node_seed__", 0)) or 0
@@ -179,6 +187,14 @@ class FixedValuesHandler(ModuleHandler):
         ctx_local = {**ctx, "__wp_rng__": rng}
         resolve_ctx = build_resolve_ctx(ctx_local, surface="fixed_values")
 
+        # Negatives are library content, like the value itself: an instance
+        # override list can re-word values but never re-words a negative, so
+        # look each one up on the library row (by id, then by name).
+        lib_rows = [v for v in payload.get("values", []) if isinstance(v, dict)]
+        lib_by_id = {v.get("id"): v for v in lib_rows if v.get("id")}
+        lib_by_name = {(v.get("name") or "").strip(): v for v in lib_rows}
+        n_rng = negatives.neg_rng(effective_seed, module_key)
+
         out_resolved: dict[str, str] = {}
         for v in values:
             name = (v.get("name") or "").strip()
@@ -186,9 +202,29 @@ class FixedValuesHandler(ModuleHandler):
                 continue
             raw = str(v.get("value", ""))
             out_resolved[name] = resolve_text(raw, resolve_ctx)
+            lib = lib_by_id.get(v.get("id")) or lib_by_name.get(name) or {}
+            own = negatives.clean_negative(lib.get("negative"))
+            negatives.set_entries(ctx, name, negatives.own_entries(
+                [own] if own else [], resolve_ctx, n_rng, pick=None, source=name,
+            ))
         return out_resolved
 
 
+def _row_keys(values: list[Any]) -> list[str]:
+    """The key each row is toggled by: its ``id``, or ``#<index>`` when the id
+    is missing, blank or repeats an earlier row's. Imported packs can carry
+    rows without ids. Mirrors ``withRowKeys`` in
+    src/components/context/editors/fixed-values/defaults.ts."""
+    seen: set[str] = set()
+    keys: list[str] = []
+    for i, v in enumerate(values):
+        rid = v.get("id") if isinstance(v, dict) else None
+        key = rid if isinstance(rid, str) and rid.strip() and rid not in seen else f"#{i}"
+        seen.add(key)
+        keys.append(key)
+    return keys
+
+
 def _ctx_supports_resolve(ctx: Any) -> bool:
     """build_resolve_ctx requires __wp_rng__ + __wp_warnings__ in ctx.
     Legacy test/usage passes None or minimal dicts — detect those and

engine/modules/wildcard_handler.py

@@ -20,7 +20,9 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from engine import negatives
 from engine.modules import build_resolve_ctx
+from engine.modules._detail import module_detail
 from engine.modules._seed import derive_module_rng as _derive_module_rng
 from engine.modules.dispatcher import ModuleHandler
 from engine.syntax import resolve_text
@@ -58,13 +60,51 @@ def _coerce_pick_int(value: Any, default: int) -> int:
         return default
 
 
+def _weight(o: dict[str, Any]) -> float:
+    try:
+        return max(0.0, float(o.get("weight", 1)))
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _explain_pool(detail: dict[str, Any], options: list[dict[str, Any]]) -> None:
+    """Pool size and how many options can still be drawn, for WP Debug."""
+    detail["pool"] = len(options)
+    detail["live"] = sum(1 for o in options if _weight(o) > 0)
+
+
+def _explain_constraints(
+    detail: dict[str, Any], applied: list[tuple[dict[str, Any], dict[str, Any]]],
+) -> None:
+    """The constraints that re-weighted this pick and the source value each
+    one keyed on."""
+    if not applied:
+        return
+    detail["constraints"] = [
+        {
+            "id": c.get("__constraint_library_id__") or "",
+            "uid": c.get("__constraint_module_id__") or "",
+            "name": c.get("__constraint_library_name__") or "",
+            "source": c.get("source_wildcard_id") or "",
+            "source_value": src.get("value") if isinstance(src, dict) else None,
+        }
+        for c, src in applied
+    ]
+
+
 def _pick_weighted(options: list[dict[str, Any]], rng) -> dict[str, Any] | None:
     """Pick one option weighted by `weight`. Uses rng (no module-global random)."""
     if not options:
         return None
     total = sum(max(0.0, float(o.get("weight", 1))) for o in options)
     if total <= 0:
-        return options[0]
+        # Nothing is selectable — every option is either weight 0 (documented
+        # as "disable without deleting") or was excluded by a constraint.
+        # Returning options[0] here looked like a working pick: a real option,
+        # right shape, right place, and wrong. It stayed wrong silently until
+        # the list was reordered. Callers turn None into an empty binding,
+        # which is what the null option already means.
+        return None
     r = rng.random() * total
     acc = 0.0
     for opt in options:
@@ -79,6 +119,7 @@ def _apply_constraint_to_options(
     constraint: dict[str, Any],
     source_pick: dict[str, Any],
     adjustment_warnings: list[dict[str, Any]] | None = None,
+    target_axes: dict[str, list[str]] | None = None,
 ) -> list[dict[str, Any]]:
     """Adjust option weights according to a single constraint, given the
     already-picked source option(s).
@@ -107,7 +148,7 @@ def _apply_constraint_to_options(
         combine fn treats as a no-op.
     These are diagnostic only; they never change the computed weight.
     """
-    from engine.modules._constraint_math import EXCLUDE, combine_constraint_factor
+    from engine.modules._constraint_math import combine_constraint_factor
 
     matrix = constraint.get("matrix") or {}
     exceptions = constraint.get("exceptions") or []
@@ -131,17 +172,33 @@ def _apply_constraint_to_options(
             picks, options, matrix, exceptions, adjustment_warnings,
         )
 
+    # A pick only carries an `axes` entry when the source declared that group
+    # `accepts` (see `_axis_menus`), so the pick record IS the kind map. This
+    # keeps `combine_constraint_factor` pure — it never looks up a payload —
+    # and a legacy pick with no `axes` yields an empty map, which takes the
+    # unchanged flat-product path.
+    axis_kinds = {
+        axis: "accepts"
+        for p in picks
+        for axis in (p.get("axes") or {})
+    }
+
     adjusted: list[dict[str, Any]] = []
     for opt in options:
         option = {"value": opt.get("value", ""), "tags": opt.get("sub_categories") or []}
-        f = combine_constraint_factor(picks, option, matrix, exceptions)
+        f = combine_constraint_factor(
+            picks, option, matrix, exceptions, axis_kinds, target_axes,
+        )
+        # `isinstance(f, float)` rather than `f is not EXCLUDE`: identity
+        # against a sentinel does not narrow the union, so the multiply below
+        # was unprovable. Same test, and the type checker can follow it.
         weight = float(opt.get("weight", 1))
-        weight = 0.0 if f is EXCLUDE else max(0.0, weight * float(f))
+        weight = max(0.0, weight * f) if isinstance(f, float) else 0.0
         adjusted.append({**opt, "weight": weight})
     return adjusted
 
 
-_KNOWN_CONSTRAINT_MODES = frozenset({"allow", "exclude", "boost", "reduce"})
+_KNOWN_CONSTRAINT_MODES = frozenset({"allow", "exclude", "boost", "reduce", "only"})
 
 
 def _exc_pair_index(exceptions: list[Any]) -> dict[tuple[str, str], dict[str, Any]]:
@@ -205,8 +262,8 @@ def _warn_for_rule(
     adjustment_warnings: list[dict[str, Any]],
 ) -> None:
     mode = rule.get("mode")
-    if mode == "allow":
-        # `allow` is a weight no-op; a non-1 factor is almost certainly a
+    if mode in ("allow", "only"):
+        # `allow` / `only` weigh 1.0; a non-1 factor is almost certainly a
         # user expecting weight×factor and silently getting full weight.
         try:
             factor = float(rule.get("factor", 1.0))
@@ -257,7 +314,213 @@ def _file_pick_by_origin(
     entry["by_origin"] = by_origin
 
 
-def _record_pick(ctx: Any, chosen: dict[str, Any]) -> None:
+def _axis_menus(
+    payload: dict[str, Any], tags: list[str] | None
+) -> dict[str, list[str]]:
+    """The option's tags, grouped by `accepts` axis, in registry order.
+
+    Only `accepts` groups appear — a `classify` group's tags stay in the flat
+    bag where the constraint fold multiplies them, which is today's behaviour.
+    An axis the option says nothing about is omitted rather than mapped to an
+    empty list, so callers can treat presence as meaning.
+    """
+    kinds = payload.get("tag_group_kinds") or {}
+    groups = payload.get("tag_groups") or {}
+    have = set(tags or [])
+    out: dict[str, list[str]] = {}
+    for axis, members in groups.items():
+        if kinds.get(axis) != "accepts":
+            continue
+        in_axis = [m for m in (members or []) if m in have]
+        if in_axis:
+            out[axis] = in_axis
+    return out
+
+
+def _accepts_axes(payload: dict[str, Any]) -> dict[str, list[str]]:
+    """Every ``accepts`` axis on this payload as group → full member list
+    (independent of any option). Fed to the constraint fold as the TARGET side:
+    a target option's tags inside one of these groups are ALTERNATIVES, so the
+    fold keeps the option viable when the source allows any of them (symmetric
+    to the source's rolled-winner collapse), and the target's own roll is later
+    restricted to the allowed members. Empty ⇒ the fold takes the flat product
+    path, i.e. today's behaviour.
+    """
+    kinds = payload.get("tag_group_kinds") or {}
+    groups = payload.get("tag_groups") or {}
+    return {
+        g: list(members or [])
+        for g, members in groups.items()
+        if kinds.get(g) == "accepts"
+    }
+
+
+def _roll_axes(menus: dict[str, list[str]], rng) -> dict[str, str]:
+    """One winner per axis, uniform over the option's own menu.
+
+    Uniform rather than weighted: option `weight` describes how often the
+    OPTION is chosen, and nothing in the payload expresses a preference between
+    an option's accepted tags. Inventing one would be a guess.
+
+    Axis order is the payload's group order, so the draw sequence is stable
+    across runs for a given seed.
+    """
+    return {
+        axis: members[int(rng.random() * len(members))]
+        for axis, members in menus.items()
+        if members
+    }
+
+
+def _pick_record_for_constraint(
+    chosen: dict[str, Any], payload: dict[str, Any], rolled: dict[str, str] | None
+) -> dict[str, Any]:
+    """The per-pick record a constraint reads. For an ``accepts`` axis the
+    option offers a menu but rolls ONE winner; the constraint keys on that
+    single winner (the value ``$var.AXIS`` exposes), NOT the whole menu —
+    otherwise a diagonal narrows the target to the entire accepted set instead
+    of the rolled tag, and ``$source.AXIS`` disagrees with the picked target
+    (the reported "picks are not good"). So each accepts axis collapses to its
+    winner: the axis members leave the flat ``tags`` bag and the winner is added
+    back, and ``axes`` carries only the winner. Classify tags are untouched
+    (they still multiply). An option with no accepts axis produces the same
+    record as before the feature.
+    """
+    sub = list(chosen.get("sub_categories") or [])
+    menus = _axis_menus(payload, sub)
+    rolled = rolled or {}
+    axis_members = {m for members in menus.values() for m in members}
+    winners = [rolled[a] for a in menus if a in rolled]
+    tags = [t for t in sub if t not in axis_members] + winners
+    axes = {a: [rolled[a]] for a in menus if a in rolled}
+    return {"value": chosen.get("value", ""), "tags": tags, "axes": axes}
+
+
+def _restrict_menus_by_constraints(
+    menus: dict[str, list[str]],
+    applied_constraints: list[tuple[dict[str, Any], dict[str, Any]]] | None,
+) -> dict[str, list[str]]:
+    """Drop from each accepts-axis menu the tags a FIRED constraint excludes, so
+    the target's own roll can only land on a constraint-allowed tag.
+
+    Under a diagonal from a source that rolled ``sandals``, the target's
+    ``{sandals, heels}`` option can no longer roll ``heels`` — so
+    ``$source.SHOES`` and ``$target.SHOES`` agree. A tag survives iff EVERY
+    fired constraint gives a single-tag option ``{tags: [t]}`` a positive
+    factor. Never empties an axis: if every member is excluded the menu is left
+    intact (the option itself survived the pool narrowing, so its axis must
+    still roll something) — reachable only with a pathological matrix.
+    """
+    if not applied_constraints or not menus:
+        return menus
+    from engine.modules._constraint_math import combine_constraint_factor
+    out: dict[str, list[str]] = {}
+    for axis, members in menus.items():
+        allowed: list[str] = []
+        for t in members:
+            ok = True
+            for c, src_pick in applied_constraints:
+                s_picks = src_pick.get("picks")
+                if not isinstance(s_picks, list):
+                    s_picks = [{
+                        "value": src_pick.get("value", ""),
+                        "tags": list(src_pick.get("sub_categories") or []),
+                    }]
+                axis_kinds = {
+                    ax: "accepts"
+                    for p in s_picks for ax in (p.get("axes") or {})
+                }
+                # The probe is a bare tag with no real value, so a
+                # value-level `only` would shut it out and leave the menu
+                # unrestricted. The option itself already passed that gate
+                # in the pool, so only the tag rules matter here.
+                probe_excs = [
+                    e for e in (c.get("exceptions") or [])
+                    if not (isinstance(e, dict) and e.get("mode") == "only")
+                ]
+                f = combine_constraint_factor(
+                    s_picks, {"value": "", "tags": [t]},
+                    c.get("matrix") or {}, probe_excs, axis_kinds,
+                )
+                if not (isinstance(f, float) and f > 0.0):
+                    ok = False
+                    break
+            if ok:
+                allowed.append(t)
+        out[axis] = allowed if allowed else members
+    return out
+
+
+def _record_axes(
+    ctx: Any, binding: str, rolled: Any, payload: dict[str, Any]
+) -> None:
+    """Publish the rolled axis choices under the VARIABLE binding.
+
+    Deliberately not on the pick record: `$outfit.SHOES` addresses by binding,
+    while `__wp_picks__` is keyed by module uuid. Keying each consumer the way
+    it addresses things means neither has to translate, and the axis read never
+    inherits the uuid-bucket collision (task_5200c1fc) that only reaches
+    consumers binding by uuid.
+    """
+    if not isinstance(ctx, dict) or not binding:
+        return
+    bucket = ctx.setdefault("__wp_axes__", {})
+    if isinstance(bucket, dict):
+        bucket[binding] = rolled
+    # Which accepts axes this binding's wildcard DECLARES, whatever the pick
+    # rolled. `__wp_axes__` alone cannot tell "the picked option has no SHOES
+    # tag" from "there is no SHOES axis", and the resolver's warning needs to
+    # say which one happened. Always written (even empty) so a later wildcard
+    # rebinding the same name replaces the earlier declaration.
+    decl = ctx.setdefault("__wp_axis_decl__", {})
+    if isinstance(decl, dict):
+        decl[binding] = list(_accepts_axes(payload))
+
+
+def _match_variable_option(
+    ctx: Any, options: list[dict[str, Any]], var_name: str,
+) -> tuple[dict[str, Any] | None, str]:
+    """Option for a ``match_variable`` instance, and how it was chosen
+    (``"match_variable"`` or ``"match_fallback"``). ``(None, "")`` means roll
+    normally; a ``match_variable_no_match`` warning says why."""
+    from engine.modules._fallback import find_fallback
+
+    name = var_name[1:] if var_name.startswith("$") else var_name
+    raw = ctx.get(name) if ctx is not None else None
+    wanted = "" if raw is None else str(raw).strip().lower()
+    if wanted:
+        for o in options:
+            if o.get("value") is None:
+                continue
+            if str(o.get("value", "")).strip().lower() == wanted:
+                return o, "match_variable"
+    fallback = find_fallback(options)
+    if fallback is not None:
+        return fallback, "match_fallback"
+    if ctx is not None and isinstance(ctx.get("__wp_warnings__"), list):
+        module_id = ctx.get("__wp_current_module_id__") or ""
+        ctx["__wp_warnings__"].append({
+            "type": "match_variable_no_match",
+            "severity": "warn",
+            "module_id": module_id,
+            "source_field": "",
+            "position": 0,
+            "token_index": None,
+            "detail": {"variable": name, "value": "" if raw is None else str(raw)},
+            "message": (
+                f"no option equals ${name} ({'' if raw is None else str(raw)!r}) "
+                "and none is marked fallback; rolled normally"
+            ),
+        })
+    return None, ""
+
+
+def _record_pick(
+    ctx: Any,
+    chosen: dict[str, Any],
+    payload: dict[str, Any],
+    rolled: dict[str, str] | None = None,
+) -> None:
     """Stash the picked option dict in `ctx["__wp_picks__"][module_id]` so a
     downstream constraint-aware wildcard can look up its source's value +
     sub_categories. Keyed by the active module id (set by pipeline.py).
@@ -282,10 +545,10 @@ def _record_pick(ctx: Any, chosen: dict[str, Any]) -> None:
             # SP3: per-pick list the combine fn reads. A single pick is a
             # one-element list so the multi-tag/multi-pick applier has a
             # uniform shape regardless of single- vs multi-select source.
-            "picks": [{
-                "value": chosen.get("value", ""),
-                "tags": list(chosen.get("sub_categories") or []),
-            }],
+            # An `accepts` axis is collapsed to its rolled winner here (see
+            # `_pick_record_for_constraint`) so the constraint keys on the one
+            # tag `$var.AXIS` exposes, not the whole menu.
+            "picks": [_pick_record_for_constraint(chosen, payload, rolled)],
         }
         # Additive per-instance view (task_5200c1fc). When this wildcard
         # carries a `bundle_origin`, ALSO file the pick under
@@ -298,7 +561,13 @@ def _record_pick(ctx: Any, chosen: dict[str, Any]) -> None:
         bucket[module_id] = entry
 
 
-def _record_pick_multi(ctx: Any, chosen_list: list[dict[str, Any]], sep: str) -> None:
+def _record_pick_multi(
+    ctx: Any,
+    chosen_list: list[dict[str, Any]],
+    sep: str,
+    payload: dict[str, Any],
+    rolled_list: list[dict[str, str]] | None = None,
+) -> None:
     """Multi-select counterpart to `_record_pick` (SP2a). Stash the joined
     value + the individual picked values + the union of their sub-categories,
     so the debug Picks view can render the list. Single-pick records (via
@@ -318,10 +587,15 @@ def _record_pick_multi(ctx: Any, chosen_list: list[dict[str, Any]], sep: str) ->
                 union.append(t)
     # SP3: per-pick list (value + that pick's own tags, NOT the union) so the
     # combine fn can apply the matrix per pick. The union above stays for the
-    # debug Picks view; `picks` is what constraint application reads.
+    # debug Picks view; `picks` is what constraint application reads. Each
+    # pick's `accepts` axis is collapsed to its own rolled winner (parallel to
+    # the single-pick path) so a multi-select source contributes one tag per
+    # pick, not each pick's whole menu.
     per_pick = [
-        {"value": str(c.get("value", "")), "tags": list(c.get("sub_categories") or [])}
-        for c in chosen_list
+        _pick_record_for_constraint(
+            c, payload, (rolled_list[i] if rolled_list and i < len(rolled_list) else None)
+        )
+        for i, c in enumerate(chosen_list)
     ]
     entry = {
         "value": sep.join(values),
@@ -335,6 +609,32 @@ def _record_pick_multi(ctx: Any, chosen_list: list[dict[str, Any]], sep: str) ->
     bucket[module_id] = entry
 
 
+def _file_negatives(
+    ctx: Any,
+    binding: str,
+    resolve_ctx: Any,
+    seed: int,
+    picks: list[tuple[dict[str, Any], list[str], int | None]],
+) -> None:
+    """File the negatives of this roll under `binding`.
+
+    Each pick contributes its option's own `negative` plus the negatives of
+    the options its nested `@{ref}`s picked, resolved quietly on the
+    binding's negative stream so the positive picks never shift. `slot` is
+    the multi-pick index (None for a single pick)."""
+    if not isinstance(ctx, dict):
+        return
+    rng = negatives.neg_rng(seed, binding)
+    entries: list[dict[str, Any]] = []
+    for opt, ref_negs, slot in picks:
+        own = negatives.clean_negative(opt.get("negative"))
+        texts = ([own] if own else []) + list(ref_negs)
+        entries += negatives.own_entries(
+            texts, resolve_ctx, rng, pick=slot, source=binding,
+        )
+    negatives.set_entries(ctx, binding, entries)
+
+
 class WildcardHandler(ModuleHandler):
     type_id = "wildcard"
 
@@ -421,8 +721,41 @@ class WildcardHandler(ModuleHandler):
                         )
                     seen_grouped.add(mem)
 
+        # Group KIND (2026-08 tag axes). Additive: absence means every group
+        # is `classify`, which is exactly today's behaviour, so no stored
+        # payload changes meaning. `accepts` marks the group's tags as
+        # alternatives the option offers — an OR-set the constraint fold reads
+        # with max, and which `$var.AXIS` rolls one winner from.
+        kinds = payload.get("tag_group_kinds")
+        if kinds is not None:
+            if not isinstance(kinds, dict):
+                raise ValueError(
+                    "wildcard payload.tag_group_kinds must be an object"
+                )
+            declared = tag_groups if isinstance(tag_groups, dict) else {}
+            for gname, kind in kinds.items():
+                if gname not in declared:
+                    raise ValueError(
+                        f"wildcard payload.tag_group_kinds[{gname!r}]: "
+                        f"not a declared tag group"
+                    )
+                if kind not in ("classify", "accepts"):
+                    raise ValueError(
+                        f"wildcard payload.tag_group_kinds[{gname!r}] must be "
+                        f"'classify' or 'accepts' (got {kind!r})"
+                    )
+                # Only an `accepts` axis is addressable as `$var.AXIS`, so only
+                # it has to survive the accessor grammar. A `classify` group
+                # keeps whatever name it has today.
+                if kind == "accepts" and not _IDENT_RE.match(gname):
+                    raise ValueError(
+                        f"wildcard payload.tag_group_kinds[{gname!r}]: an "
+                        f"'accepts' group name must be a valid identifier"
+                    )
+
         seen_ids: set[str] = set()
         null_count = 0
+        fallback_count = 0
         for i, opt in enumerate(options):
             if not isinstance(opt, dict):
                 raise ValueError(f"wildcard payload.options[{i}] must be an object")
@@ -466,6 +799,27 @@ class WildcardHandler(ModuleHandler):
                         f"wildcard payload.options[{i}].value must be a "
                         f"non-empty string (use is_null=True for the null option)"
                     )
+            # Send-to-negative (schema v8): optional words this option puts
+            # in the negative prompt of any Assembler that renders it.
+            neg = opt.get("negative")
+            if neg is not None and not isinstance(neg, str):
+                raise ValueError(
+                    f"wildcard payload.options[{i}].negative must be a string"
+                )
+            # Fallback (schema v9): the one option used when nothing else is
+            # left to pick. Stored only as `true`; absent means not.
+            fb = opt.get("fallback")
+            if fb is not None and not isinstance(fb, bool):
+                raise ValueError(
+                    f"wildcard payload.options[{i}].fallback must be a boolean"
+                )
+            if fb:
+                if is_null:
+                    raise ValueError(
+                        f"wildcard payload.options[{i}] null option "
+                        f"{opt_id!r} can't be the fallback"
+                    )
+                fallback_count += 1
             weight = opt.get("weight", 1)
             if not isinstance(weight, (int, float)) or isinstance(weight, bool):
                 raise ValueError(
@@ -496,6 +850,11 @@ class WildcardHandler(ModuleHandler):
                 f"wildcard payload may have at most one null option "
                 f"(found {null_count})"
             )
+        if fallback_count > 1:
+            raise ValueError(
+                f"wildcard payload may have at most one fallback option "
+                f"(found {fallback_count})"
+            )
         binding = payload.get("var_binding")
         if binding is not None:
             if not isinstance(binding, str):
@@ -542,20 +901,52 @@ class WildcardHandler(ModuleHandler):
         # has since removed. Honors enabled_options + weights normally
         # in every other mode.
         mode = instance.get("mode")
+        pinned: dict[str, Any] | None = None
+        pin_mode = "pinned"
         if mode == "pinned":
             pinned_id = instance.get("pinned_option_id")
             pinned = next((o for o in options if o.get("id") == pinned_id), None)
-            if pinned is not None:
-                # Track the pinned pick the same way as a random pick —
-                # downstream constraint-aware wildcards need source
-                # info regardless of how the source resolved its option.
-                _record_pick(ctx, pinned)
-                value = str(pinned.get("value", ""))
-                if not value:
-                    return {binding: ""}
-                resolve_ctx = build_resolve_ctx(ctx, surface="wildcard")
-                return {binding: resolve_text(value, resolve_ctx)}
-            # else: pinned target is missing — fall through to random.
+        # `match_variable`: take the option whose text equals another
+        # variable's value (case-insensitive), e.g. `$model_variant` from WP
+        # Model Info, so this wildcard's pick can drive constraints. No match →
+        # the fallback option if one is flagged, else a normal roll + warning.
+        match_var = instance.get("match_variable")
+        if pinned is None and isinstance(match_var, str) and match_var.strip():
+            pinned, pin_mode = _match_variable_option(ctx, options, match_var.strip())
+        if pinned is not None:
+            # A pinned option still rolls its axes: pinning fixes WHICH
+            # option fires, not which of the shoes it accepts. Roll BEFORE
+            # recording so the pick carries the single rolled winner (the
+            # constraint source-view a downstream target reads), same as the
+            # random path. Pinned bypasses this wildcard's own constraint
+            # application, so there's nothing to restrict the roll against.
+            pinned_rolled = _roll_axes(
+                _axis_menus(payload, pinned.get("sub_categories")),
+                _derive_module_rng(
+                    int(ctx.get("__wp_node_seed__", 0) or 0), f"{binding}::axes",
+                ),
+            )
+            # Track the pinned pick the same way as a random pick —
+            # downstream constraint-aware wildcards need source
+            # info regardless of how the source resolved its option.
+            _record_pick(ctx, pinned, payload, pinned_rolled)
+            _record_axes(ctx, binding, pinned_rolled, payload)
+            detail = module_detail(ctx)
+            if detail is not None:
+                detail.update({"mode": pin_mode, "option_id": pinned.get("id")})
+                if pin_mode != "pinned":
+                    detail["match_variable"] = match_var.strip()
+            value = str(pinned.get("value", ""))
+            resolve_ctx = build_resolve_ctx(ctx, surface="wildcard")
+            with negatives.collecting(resolve_ctx) as col:
+                out_value = resolve_text(value, resolve_ctx) if value else ""
+            _file_negatives(
+                ctx, binding, resolve_ctx,
+                int(ctx.get("__wp_node_seed__", 0) or 0),
+                [(pinned, col.ref_negatives, None)],
+            )
+            return {binding: out_value}
+        # else: nothing pinned or matched — fall through to random.
 
         # `category_filter` narrows the option pool to entries whose tag
         # set (`sub_categories`) satisfies a boolean expression
@@ -580,6 +971,25 @@ class WildcardHandler(ModuleHandler):
             allowed = set(enabled)
             options = [o for o in options if o.get("id") in allowed]
 
+        # Schema v9 fallback: the flagged option stays in the draw pool and
+        # is also taken when weights + constraints leave nothing to pick. Found
+        # after the node's filters + toggles, so a toggled-off one is gone.
+        from engine.modules._fallback import (
+            fallback_warning,
+            find_fallback,
+            pool_is_dead,
+        )
+        fallback = find_fallback(options)
+
+        detail = module_detail(ctx)
+        if detail is not None:
+            if isinstance(category_filter, str) and category_filter.strip():
+                detail["filter"] = category_filter.strip()
+            if exclude_null:
+                detail["exclude_null"] = True
+            if not options:
+                detail.update({"pool": 0, "live": 0})
+
         if not options:
             return {binding: ""}
 
@@ -614,6 +1024,11 @@ class WildcardHandler(ModuleHandler):
         )
         my_id = ctx.get("__wp_current_module_id__") if ctx is not None else None
         any_constraint_applied = False
+        # (constraint, source_pick) pairs that actually re-weighted this target.
+        # Used below to restrict this wildcard's OWN accepts-axis roll to tags
+        # those constraints allow, so `$source.AXIS` == `$target.AXIS` under a
+        # diagonal (A). Empty when nothing constrains this instance.
+        applied_constraints: list[tuple[dict[str, Any], dict[str, Any]]] = []
         if my_id:
             constraints = ctx.get("__wp_constraints__") if ctx is not None else None
             picks = ctx.get("__wp_picks__") if ctx is not None else None
@@ -633,9 +1048,27 @@ class WildcardHandler(ModuleHandler):
             options, any_constraint_applied = apply_constraints_for_target(
                 options, my_id, constraints, picks, ctx["__wp_warnings__"],
                 hits=hits, firing_uid=firing_uid,
+                applied_out=applied_constraints,
+                # TARGET-side accepts axes: a target option's tags in one of
+                # these groups are alternatives the option offers, so the fold
+                # keeps it viable when the source allows any of them (mirror of
+                # the source rolled-winner collapse). The roll is then pinned to
+                # the allowed member by `_restrict_menus_by_constraints`.
+                target_axes=_accepts_axes(payload),
             )
-        if any_constraint_applied:
+        if any_constraint_applied and fallback is None:
             warn_excludes_all(options, my_id or "", ctx["__wp_warnings__"])
+        if detail is not None:
+            _explain_pool(detail, options)
+            _explain_constraints(detail, applied_constraints)
+        use_fallback = fallback is not None and pool_is_dead(options)
+        if use_fallback:
+            assert fallback is not None
+            ctx["__wp_warnings__"].append(fallback_warning(
+                my_id or "", fallback, constrained=any_constraint_applied,
+            ))
+            if detail is not None:
+                detail["fallback"] = True
 
         # Effective seed selection:
         #   - locked_seed when present → reproducible per-instance
@@ -652,6 +1085,9 @@ class WildcardHandler(ModuleHandler):
             # whole run — "green jeans" on frame 1 stays "green jeans".
             _hb = ctx.get("__wp_hold_base_ctx__")
             if isinstance(_hb, dict) and binding in _hb:
+                if detail is not None:
+                    detail["held"] = True
+                negatives.copy_from(ctx, _hb, [binding])
                 return {binding: _hb[binding]}
             chain_seed = int(ctx.get("__wp_node_seed_hold__", ctx.get("__wp_node_seed__", 0)) or 0)
         else:
@@ -681,7 +1117,11 @@ class WildcardHandler(ModuleHandler):
             weights = [max(0.0, float(o.get("weight", 1))) for o in pool]
             pool_n = len(pool)
             independent = bool(instance.get("pick_independent", False))
-            if independent:
+            if use_fallback:
+                # One fallback, never repeated: it stands in for the whole
+                # pick, so a `2-3` range doesn't render "hair, hair".
+                picks = [fallback] if hi > 0 else []
+            elif independent:
                 # SP2c: independent multi-pick draws WITH replacement (repeats
                 # allowed), mirroring the inline `~` flag — so the count is the
                 # requested range and is NOT clamped to the pool size.
@@ -698,30 +1138,88 @@ class WildcardHandler(ModuleHandler):
             if not isinstance(sep, str):
                 sep = ", "
             items: list[str] = []
+            neg_picks: list[tuple[dict[str, Any], list[str], int | None]] = []
             saved_rng_multi = ctx.get("__wp_rng__")
             ctx["__wp_rng__"] = rng
             try:
                 multi_ctx = build_resolve_ctx(ctx, surface="wildcard")
-                for opt in picks:
-                    items.append(resolve_text(str(opt.get("value", "")), multi_ctx))
+                for slot, opt in enumerate(picks):
+                    with negatives.collecting(multi_ctx) as col:
+                        items.append(resolve_text(str(opt.get("value", "")), multi_ctx))
+                    neg_picks.append((opt, col.ref_negatives, slot))
             finally:
                 ctx["__wp_rng__"] = saved_rng_multi
-            _record_pick_multi(ctx, picks, sep)
+            _file_negatives(ctx, binding, multi_ctx, effective_seed, neg_picks)
+            # One roll per pick, in pick order, so `$outfit.SHOES` mirrors the
+            # shape of `$outfit` and `$outfit.1.SHOES` lines up with `$outfit.1`.
+            # Each pick's accepts menu is first restricted to the tags the fired
+            # constraints allow (A), then rolled; the winners feed BOTH the pick
+            # record (source view) and the accessor. Rolled before the record —
+            # the record draws no rng and the restriction consumes none + keeps
+            # one draw per axis, so downstream reproducibility is unchanged.
+            rolled_list = [
+                _roll_axes(
+                    _restrict_menus_by_constraints(
+                        _axis_menus(payload, o.get("sub_categories")),
+                        applied_constraints,
+                    ),
+                    rng,
+                )
+                for o in picks
+            ]
+            _record_pick_multi(ctx, picks, sep, payload, rolled_list)
+            if detail is not None:
+                detail["option_ids"] = [o.get("id") for o in picks]
+                detail["range"] = [lo, hi]
+                if independent:
+                    detail["independent"] = True
+            _record_axes(ctx, binding, rolled_list, payload)
             return {binding: ListVar(items, sep)}
 
-        chosen = _pick_weighted(options, rng)
+        # The fallback is taken without a draw, so no rng is consumed where
+        # the pre-v9 path returned empty.
+        chosen = fallback if use_fallback else _pick_weighted(options, rng)
         if chosen is None:
             return {binding: ""}
+        if detail is not None:
+            total = sum(_weight(o) for o in options)
+            detail["option_id"] = chosen.get("id")
+            # No draw happened for a fallback, so there is no chance to show
+            # (Debug reads `fallback` instead).
+            detail["chance"] = (
+                None if use_fallback
+                else _weight(chosen) / total if total > 0 else None
+            )
 
+        # Roll the accepts axes AFTER the option draw (same rng, so a locked
+        # seed still reproduces the option) but BEFORE recording the pick, so
+        # the pick a downstream target reads carries the single rolled winner
+        # per axis (source fix). This wildcard's OWN menu is first restricted to
+        # tags the constraints that fired on it allow (A) — so a constrained
+        # `$target.AXIS` agrees with the source. The restriction consumes no rng
+        # and keeps one draw per axis, so downstream reproducibility holds.
+        rolled = _roll_axes(
+            _restrict_menus_by_constraints(
+                _axis_menus(payload, chosen.get("sub_categories")),
+                applied_constraints,
+            ),
+            rng,
+        )
         # Record this wildcard's pick so a downstream constraint-aware
         # wildcard can read it. Done BEFORE resolve_text so even an
         # empty-string-value pick is registered (matters if a
         # constraint exception keys on the literal empty pick value).
-        _record_pick(ctx, chosen)
+        _record_pick(ctx, chosen, payload, rolled)
+        _record_axes(ctx, binding, rolled, payload)
 
         value = str(chosen.get("value", ""))
         if not value:
-            # Empty / null pick — no ref to resolve.
+            # Empty / null pick — no ref to resolve. Its own negative (a
+            # "none" option that rules something out) still files.
+            _file_negatives(
+                ctx, binding, build_resolve_ctx(ctx, surface="wildcard"),
+                effective_seed, [(chosen, [], None)],
+            )
             return {binding: ""}
 
         # Swap `ctx['__wp_rng__']` to the per-module rng for the
@@ -754,8 +1252,13 @@ class WildcardHandler(ModuleHandler):
                 set_carrier(
                     ctx.get("__wp_current_module_uid__"), chosen.get("id"),
                 )
-            resolved = resolve_text(value, resolve_ctx)
+            with negatives.collecting(resolve_ctx) as col:
+                resolved = resolve_text(value, resolve_ctx)
         finally:
             ctx["__wp_rng__"] = saved_rng
+        _file_negatives(
+            ctx, binding, resolve_ctx, effective_seed,
+            [(chosen, col.ref_negatives, None)],
+        )
 
         return {binding: resolved}

engine/negatives.py

@@ -0,0 +1,298 @@
+"""Per-variable negative prompts (schema v8, send-to-negative).
+
+A wildcard option, a fixed value, a combine and a derivation "Add to
+negative" action can carry negative text. The engine files it under the
+variable it belongs to, in ``ctx["__wp_negatives__"]``:
+
+    {binding: [{"text": str, "pick": int | None, "source": str}, ...]}
+
+``pick`` is the multi-pick slot the entry belongs to (``None`` = the whole
+value), so ``$props.1`` can carry only pick 1's negative while ``$props`` and
+``$props.AXIS`` carry every pick's. Text is stored already resolved.
+
+Negatives follow USAGE: an Assembler only emits the negatives of variables
+its positive template actually rendered. A combine (and a derivation value)
+inherits the negatives of the variables its text read.
+
+Seeds never shift: negative text resolves on its own stream,
+``derive_module_rng(seed, key + "::neg")``, and in QUIET mode (see
+:func:`quiet_resolve`) so an ``@{ref}`` inside a negative binds nothing,
+counts no constraint hits and writes nothing to the Test Runner ref log.
+
+Pure engine module: no ComfyUI imports.
+"""
+from __future__ import annotations
+
+import dataclasses
+import random
+import re
+from collections.abc import Callable, Iterable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+NEG_KEY = "__wp_negatives__"
+#: Bindings whose negatives a handler set during the current module. The
+#: pipeline clears the negatives of every OTHER binding the module wrote
+#: (a write replaces the value, so it replaces what the value carried).
+TOUCHED_KEY = "__wp_neg_touched__"
+
+Entry = dict[str, Any]
+
+
+def neg_rng(seed: int, key: str) -> random.Random:
+    """The negative stream for a module keyed ``key`` under ``seed``."""
+    from engine.modules._seed import derive_module_rng  # noqa: PLC0415 - cycle
+
+    return derive_module_rng(int(seed), f"{key}::neg")
+
+
+def clean_negative(raw: Any) -> str:
+    """A payload ``negative`` field as a stripped string ('' when absent)."""
+    return raw.strip() if isinstance(raw, str) else ""
+
+
+def table(ctx: dict[str, Any]) -> dict[str, list[Entry]]:
+    got = ctx.get(NEG_KEY)
+    if not isinstance(got, dict):
+        got = {}
+        ctx[NEG_KEY] = got
+    return got
+
+
+def get_entries(ctx: Any, binding: str) -> list[Entry]:
+    if not isinstance(ctx, dict):
+        return []
+    got = ctx.get(NEG_KEY)
+    if not isinstance(got, dict):
+        return []
+    rows = got.get(binding)
+    return [r for r in rows if isinstance(r, dict)] if isinstance(rows, list) else []
+
+
+def set_entries(
+    ctx: Any, binding: str, entries: Iterable[Entry], *, add: bool = False,
+) -> None:
+    """Replace (default) or extend ``binding``'s negatives and mark it touched
+    so the pipeline's write step keeps them."""
+    if not isinstance(ctx, dict) or not binding:
+        return
+    rows = [e for e in entries if isinstance(e, dict) and str(e.get("text", "")).strip()]
+    tbl = table(ctx)
+    if add:
+        rows = get_entries(ctx, binding) + rows
+    if rows:
+        tbl[binding] = rows
+    else:
+        tbl.pop(binding, None)
+    touched = ctx.get(TOUCHED_KEY)
+    if not isinstance(touched, list):
+        touched = []
+        ctx[TOUCHED_KEY] = touched
+    if binding not in touched:
+        touched.append(binding)
+
+
+def settle_writes(ctx: dict[str, Any], written: Iterable[str]) -> None:
+    """After a module's bindings land: a written binding the module did not
+    give negatives to loses its old ones (the value was replaced)."""
+    touched = ctx.pop(TOUCHED_KEY, None)
+    touched = set(touched) if isinstance(touched, list) else set()
+    tbl = ctx.get(NEG_KEY)
+    if not isinstance(tbl, dict):
+        return
+    for key in written:
+        if key not in touched:
+            tbl.pop(key, None)
+
+
+def copy_from(ctx: Any, source: Any, bindings: Iterable[str]) -> None:
+    """Held modules reuse their frame-0 value verbatim; reuse its negatives."""
+    for b in bindings:
+        set_entries(ctx, b, [dict(e) for e in get_entries(source, b)])
+
+
+def entries_for_reads(ctx: Any, reads: Iterable[tuple[str, Any]]) -> list[Entry]:
+    """The negatives a text inherits from the ``$var`` reads it made.
+
+    ``(name, None)`` takes every entry; ``(name, K)`` takes the entries of
+    pick K plus the whole-value ones. Order follows the reads; an entry is
+    taken once even when read twice. Inherited entries lose their pick slot:
+    they now belong to the reader as a whole.
+    """
+    out: list[Entry] = []
+    seen: set[tuple[str, int]] = set()
+    for name, index in reads:
+        for i, e in enumerate(get_entries(ctx, name)):
+            pick = e.get("pick")
+            if index is not None and pick is not None and pick != index:
+                continue
+            if (name, i) in seen:
+                continue
+            seen.add((name, i))
+            out.append({**e, "pick": None})
+    return out
+
+
+class Collector:
+    """What one resolve touched: ``$var`` reads and nested-ref option picks."""
+
+    def __init__(self) -> None:
+        self.reads: list[tuple[str, Any]] = []
+        self.ref_negatives: list[str] = []
+
+
+@contextmanager
+def collecting(resolve_ctx: Any) -> Iterator[Collector]:
+    """Point a resolve context's read/ref hooks at a fresh collector for the
+    duration of the block. Works on any ResolveContext; one without the hook
+    fields simply collects nothing."""
+    col = Collector()
+    has = hasattr(resolve_ctx, "_reads") and hasattr(resolve_ctx, "_ref_negs")
+    if not has:
+        yield col
+        return
+    saved = (resolve_ctx._reads, resolve_ctx._ref_negs)
+    resolve_ctx._reads = col.reads
+    resolve_ctx._ref_negs = col.ref_negatives
+    try:
+        yield col
+    finally:
+        resolve_ctx._reads, resolve_ctx._ref_negs = saved
+
+
+def quiet_resolve(text: str, resolve_ctx: Any, rng: random.Random) -> str:
+    """Resolve negative text without side effects on the positive run.
+
+    Draws from ``rng`` (the negative stream), applies no constraints and
+    counts no hits, writes no ref log, collects no reads, and ignores the
+    negatives of options its refs pick (no chaining). Warnings still land.
+    """
+    if not text:
+        return ""
+    from engine.syntax import resolve_text  # noqa: PLC0415 - import cycle
+
+    if dataclasses.is_dataclass(resolve_ctx) and not isinstance(resolve_ctx, type):
+        quiet = dataclasses.replace(
+            resolve_ctx,
+            rng=rng,
+            _constraints=[],
+            _hits={},
+            _ref_log=None,
+            _reads=None,
+            _ref_negs=None,
+        )
+    else:
+        quiet = resolve_ctx
+    return resolve_text(text, quiet).strip()
+
+
+def own_entries(
+    texts: Iterable[str], resolve_ctx: Any, rng: random.Random,
+    *, pick: int | None, source: str,
+) -> list[Entry]:
+    """Quietly resolve each raw negative text into an entry."""
+    out: list[Entry] = []
+    for raw in texts:
+        text = quiet_resolve(raw, resolve_ctx, rng) if raw else ""
+        if text:
+            out.append({"text": text, "pick": pick, "source": source})
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Tag handling (Assembler join + Cleaner dedupe)
+# ---------------------------------------------------------------------------
+
+_WEIGHT_WRAP = re.compile(r"^\(+\s*(.*?)\s*(?::\s*[0-9.]+)?\s*\)+$")
+
+
+def split_tags(text: str) -> list[str]:
+    """Split on commas that are not inside (), [] or {}."""
+    out: list[str] = []
+    depth = 0
+    cur: list[str] = []
+    for ch in text:
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}" and depth > 0:
+            depth -= 1
+        if ch == "," and depth == 0:
+            out.append("".join(cur).strip())
+            cur = []
+        else:
+            cur.append(ch)
+    out.append("".join(cur).strip())
+    return [t for t in out if t]
+
+
+def tag_key(tag: str) -> str:
+    """Comparison key: case-folded, whitespace-collapsed, and a single
+    ``(tag:1.2)`` / ``((tag))`` weight wrap removed so emphasis variants of
+    one tag compare equal."""
+    t = " ".join(tag.split()).casefold()
+    m = _WEIGHT_WRAP.match(t)
+    if m and "(" not in m.group(1) and ")" not in m.group(1):
+        t = m.group(1).strip()
+    return t
+
+
+def join_unique(texts: Iterable[str], skip: Iterable[str] = ()) -> str:
+    """Join negative texts tag by tag, dropping repeats (first one wins) and
+    any tag whose key is in ``skip``."""
+    seen = {tag_key(s) for s in skip}
+    out: list[str] = []
+    for text in texts:
+        for tag in split_tags(text):
+            k = tag_key(tag)
+            if k in seen:
+                continue
+            seen.add(k)
+            out.append(tag)
+    return ", ".join(out)
+
+
+NEGATIVES_SLOT = "$negatives"
+_SLOT_RE = re.compile(r"\$negatives(?![A-Za-z0-9_])")
+
+
+def has_slot(template: str) -> bool:
+    return bool(_SLOT_RE.search(template or ""))
+
+
+def render_negative(
+    template: str, collected: str, resolve_raw: Callable[[str], str],
+) -> str:
+    """Fill the Assembler's negative template.
+
+    ``$negatives`` marks where the collected words go. An empty template is
+    just the collected words; a template without the slot gets them appended.
+    ``resolve_raw`` renders the template's other text (its ``$vars``) without
+    tidying. Tags the template already contains are dropped from the
+    collected words so nothing is said twice.
+    """
+    tpl = template or ""
+    if not tpl.strip():
+        return collected
+    pieces = _SLOT_RE.split(tpl)
+    rendered = [resolve_raw(p) if p else "" for p in pieces]
+    fixed_tags: list[str] = []
+    for r in rendered:
+        fixed_tags.extend(split_tags(r))
+    words = join_unique([collected], skip=fixed_tags)
+    if len(pieces) == 1:
+        base = tidy(rendered[0])
+        if not words:
+            return base
+        return f"{base}, {words}" if base else words
+    return tidy(words.join(rendered))
+
+
+_COMMA_RUN = re.compile(r"\s*,(?:\s*,)*\s*")
+_WS_RUN = re.compile(r"[ \t]{2,}")
+
+
+def tidy(text: str) -> str:
+    """Collapse whitespace and empty comma slots; trim edge commas."""
+    out = _WS_RUN.sub(" ", text)
+    out = _COMMA_RUN.sub(", ", out)
+    return out.strip().strip(",").strip()

engine/pipeline.py

@@ -13,10 +13,13 @@ import random
 import re
 from typing import Any
 
+from engine import negatives, prefs
 from engine.context import Context
 from engine.modules import Module
+from engine.modules._detail import DETAIL_KEY, EXPLAIN_KEY
 from engine.modules.dispatcher import UnknownModuleType, resolve_module
 from engine.modules.snapshot import coerce_legacy_module
+from engine.sweep import apply_pin_override
 
 logger = logging.getLogger(__name__)
 
@@ -194,30 +197,31 @@ def _extract_static_meta(
             if b:
                 meta["binding"] = b
     elif m_type == "derivation":
-        # Derivation can write to MULTIPLE target_vars (one per branch
-        # `action.target_var`, plus the `else.action.target_var`).
-        # Collect every declared target so the disabled-derivation row
-        # shows all of them in the debug viewer instead of a uuid.
+        # Derivation can write to MULTIPLE target_vars (every action of
+        # every branch, plus the else clause's; a clause runs `action` then
+        # its `extra_actions`). Collect every declared target so the
+        # disabled-derivation row shows all of them in the debug viewer
+        # instead of a uuid.
         seen_targets: list[str] = []
         rules = payload.get("rules")
         if isinstance(rules, list):
             for rule in rules:
                 if not isinstance(rule, dict):
                     continue
-                for branch in rule.get("branches", []) or []:
-                    if not isinstance(branch, dict):
-                        continue
-                    action = branch.get("action")
-                    if isinstance(action, dict):
-                        target = action.get("target_var")
-                        if isinstance(target, str):
-                            target = target.lstrip("$").strip()
-                            if target and target not in seen_targets:
-                                seen_targets.append(target)
-                else_block = rule.get("else")
-                if isinstance(else_block, dict):
-                    action = else_block.get("action")
-                    if isinstance(action, dict):
+                clauses = [
+                    b for b in rule.get("branches", []) or []
+                    if isinstance(b, dict)
+                ]
+                if isinstance(rule.get("else"), dict):
+                    clauses.append(rule["else"])
+                for clause in clauses:
+                    extra = clause.get("extra_actions")
+                    actions = [clause.get("action")] + (
+                        extra if isinstance(extra, list) else []
+                    )
+                    for action in actions:
+                        if not isinstance(action, dict):
+                            continue
                         target = action.get("target_var")
                         if isinstance(target, str):
                             target = target.lstrip("$").strip()
@@ -248,6 +252,72 @@ def _module_seed_scope(module: object) -> str | None:
     return None
 
 
+def _module_binding(module: object) -> str | None:
+    """Read the variable name a wildcard binds to, instance override first.
+
+    Mirrors the precedence in `WildcardHandler.resolve`. Needed because rolled
+    axes are keyed by BINDING — the namespace `$outfit.SHOES` addresses — while
+    picks are keyed by module id, so the two carry-forwards cannot share a key.
+    """
+    inst = (
+        module.get("instance") if isinstance(module, dict)
+        else getattr(module, "instance", None)
+    )
+    if isinstance(inst, dict):
+        b = inst.get("variable_binding")
+        if isinstance(b, str) and b:
+            return b
+    payload = (
+        module.get("payload") if isinstance(module, dict)
+        else getattr(module, "payload", None)
+    )
+    if isinstance(payload, dict):
+        b = payload.get("var_binding")
+        if isinstance(b, str) and b:
+            return b
+    return None
+
+
+def _display_name(module: object, fallback: str) -> str:
+    """The name a user knows a module by: the stack row's `name`, else its
+    library `meta.name`."""
+    meta = module.get("meta") if isinstance(module, dict) else getattr(module, "meta", None)
+    if isinstance(meta, dict):
+        name = meta.get("name")
+        if isinstance(name, str) and name:
+            return fallback or name
+    return fallback
+
+
+def _finish_module(
+    ctx: dict[str, Any],
+    warn_mark: int,
+    module_id: str,
+    module_uid: str,
+    name: str,
+) -> dict[str, Any]:
+    """Explain-mode extras for one module's trace row.
+
+    Stamps every warning the module raised with its owner (resolver warnings
+    such as `unknown_ref` carry no module id of their own) and returns the
+    fields the trace row gains: the display name and whatever the handler put
+    in its detail sink. Only called when the run asked to explain itself.
+    """
+    warnings = ctx.get("__wp_warnings__")
+    if isinstance(warnings, list):
+        for w in warnings[warn_mark:]:
+            if isinstance(w, dict) and not w.get("owner_uid"):
+                w["owner_id"] = module_id
+                w["owner_uid"] = module_uid or module_id
+    extras: dict[str, Any] = {}
+    if name:
+        extras["name"] = name
+    detail = ctx.pop(DETAIL_KEY, None)
+    if isinstance(detail, dict) and detail:
+        extras["detail"] = detail
+    return extras
+
+
 class PipelineEngine:
     """Runs an ordered list of modules against a context dict."""
 
@@ -268,12 +338,23 @@ class PipelineEngine:
         ctx.setdefault("__wp_warnings__", [])
         ctx.setdefault("__wp_trace__", [])
         ctx.setdefault("__wp_internal_flags__", {})
+        # Send-to-negative: per-variable negatives (engine/negatives.py).
+        ctx.setdefault(negatives.NEG_KEY, {})
+        # `@{uuid}` nesting limit from Settings (engine/prefs.py). setdefault
+        # so a caller (or a test) that pinned a limit keeps it; set here
+        # rather than per surface so canvas runs, preview and the Test Runner
+        # all honor the same value. `__`-prefixed, so it never crosses a
+        # socket — each node re-reads it at its own run.
+        ctx.setdefault("__wp_max_ref_depth__", prefs.max_ref_depth())
         # SP3 reach selector: per-constraint firing count keyed by
         # `__constraint_module_id__`. Drives first/next/all/pick
         # coverage in apply_constraints_for_target + the never_applied /
         # partial_reach finalisation below. Replaces the pre-SP3
         # one-shot consumed-set.
         ctx.setdefault("__wp_constraint_hits__", {})
+        # Canvas runs ask for per-module detail (derivation branch results,
+        # pick odds, ...) for the WP Debug node; see engine/modules/_detail.py.
+        _explain = bool(ctx.get(EXPLAIN_KEY))
 
         # "Hold the value" base pass. A module on seed_scope=hold must resolve
         # to its frame-0 (loop_index=0) value on EVERY iteration — INCLUDING
@@ -326,6 +407,29 @@ class PipelineEngine:
                         )
                         if _mid and _mid in _base_picks and _mid not in _real_picks:
                             _real_picks[_mid] = _base_picks[_mid]
+            # Same carry-forward for rolled axes, but keyed by BINDING rather
+            # than module id — that is the namespace `$outfit.SHOES` addresses.
+            # Restricted to held modules, and `not in` rather than assignment,
+            # so a wildcard that never asked to hold still re-rolls this
+            # iteration.
+            # The declared-axes table travels with the rolls it describes.
+            for _table in ("__wp_axes__", "__wp_axis_decl__"):
+                _base_axes = base_ctx.get(_table)
+                if not isinstance(_base_axes, dict):
+                    continue
+                _real_axes = ctx.setdefault(_table, {})
+                if not isinstance(_real_axes, dict):
+                    continue
+                for _m in modules:
+                    if _module_seed_scope(_m) != "hold":
+                        continue
+                    _binding = _module_binding(_m)
+                    if (
+                        _binding
+                        and _binding in _base_axes
+                        and _binding not in _real_axes
+                    ):
+                        _real_axes[_binding] = _base_axes[_binding]
             _base_hits = base_ctx.get("__wp_constraint_hits__")
             if isinstance(_base_hits, dict):
                 _real_hits = ctx.setdefault("__wp_constraint_hits__", {})
@@ -372,6 +476,11 @@ class PipelineEngine:
                 _module_name = getattr(module, "name", "") or ""
                 _module_bundle_origin = getattr(module, "bundle_origin", "") or ""
 
+            _warn_mark = len(ctx["__wp_warnings__"])
+            if _explain:
+                _module_name = _display_name(module, _module_name)
+                ctx[DETAIL_KEY] = {}
+
             _k = int(ctx.get("__wp_loop_index__", 0))
             # Per-frame enable override. `frame_enabled[str(k)]` overrides the
             # base `enabled` flag for frame k in EITHER direction: a base-off
@@ -421,6 +530,9 @@ class PipelineEngine:
                     "writes": [],
                     "error": None,
                     **meta,
+                    **(_finish_module(
+                        ctx, _warn_mark, _module_id, _module_uid, _module_name,
+                    ) if _explain else {}),
                 })
                 continue
 
@@ -467,6 +579,11 @@ class PipelineEngine:
                         snapshot.get("instance"), dict
                     ):
                         snapshot["instance"] = {**snapshot["instance"], **_patch}
+                # Sweep mode (WP_ContextLoop): pin a swept wildcard to this
+                # frame's combination. Applied after the per-frame override so
+                # the sweep decides which option fires.
+                if isinstance(snapshot, dict):
+                    snapshot = apply_pin_override(snapshot, _module_uid, ctx)
             except Exception as e:
                 logger.warning(
                     "Failed to coerce module %r at index %s: %s", module, index, e
@@ -481,6 +598,9 @@ class PipelineEngine:
                     "writes": [],
                     "error": {"type": type(e).__name__, "message": str(e)},
                     **meta,
+                    **(_finish_module(
+                        ctx, _warn_mark, _module_id, _module_uid, _module_name,
+                    ) if _explain else {}),
                 })
                 continue
 
@@ -515,6 +635,7 @@ class PipelineEngine:
             # binding can match a constraint to its own bundle copy's pick.
             ctx["__wp_current_module_bundle_origin__"] = _module_bundle_origin
             meta = _extract_static_meta(module)
+            ctx.pop(negatives.TOUCHED_KEY, None)
             try:
                 bindings = resolve_module(snapshot, ctx)
             except UnknownModuleType:
@@ -532,6 +653,9 @@ class PipelineEngine:
                     "writes": [],
                     "error": None,
                     **meta,
+                    **(_finish_module(
+                        ctx, _warn_mark, _module_id, _module_uid, _module_name,
+                    ) if _explain else {}),
                 })
                 continue
             except Exception as e:
@@ -563,6 +687,9 @@ class PipelineEngine:
                     "writes": [],
                     "error": {"type": type(e).__name__, "message": str(e)},
                     **meta,
+                    **(_finish_module(
+                        ctx, _warn_mark, _module_id, _module_uid, _module_name,
+                    ) if _explain else {}),
                 })
                 continue
 
@@ -580,15 +707,37 @@ class PipelineEngine:
                 key = var.lstrip("$")
                 before = ctx.get(key)
                 ctx[key] = value
+                # Last-write-wins applies to the internal flag too: whichever
+                # module writes the var LAST decides whether it is internal. A
+                # public writer overriding an earlier internal one MUST clear
+                # the flag — otherwise the var stays hidden from the assembler
+                # forever, even though its final value came from a public
+                # module. (Mark $outfit internal, then override it with a
+                # public $outfit: the override should be visible.)
+                flags = ctx.setdefault("__wp_internal_flags__", {})
                 if mark_internal:
-                    flags = ctx.setdefault("__wp_internal_flags__", {})
                     flags[key] = True
+                else:
+                    flags.pop(key, None)
                 writes.append({
                     "variable": key,
                     "value": value,
                     "source": module_type,
                     "overwrite": before is not None and before != value,
                 })
+            # A write replaces the value, so it replaces what the value
+            # carried: bindings the handler gave no negatives lose theirs.
+            negatives.settle_writes(
+                ctx, [v.lstrip("$") for v in (bindings or {})],
+            )
+            # WP Debug's trace shows what each write now carries.
+            for w in writes:
+                texts = [
+                    str(e.get("text", ""))
+                    for e in negatives.get_entries(ctx, w["variable"])
+                ]
+                if texts:
+                    w["negative"] = ", ".join(texts)
 
             # `seed` on the trace entry: the effective seed THIS
             # module rolled with — `instance.locked_seed` if locked,
@@ -611,6 +760,9 @@ class PipelineEngine:
                 "error": None,
                 "seed": effective_seed,
                 **meta,
+                **(_finish_module(
+                        ctx, _warn_mark, _module_id, _module_uid, _module_name,
+                    ) if _explain else {}),
             })
 
         # Drop the active-module markers so they don't leak into the
@@ -621,6 +773,7 @@ class PipelineEngine:
         ctx.pop("__wp_current_module_uid__", None)
         ctx.pop("__wp_current_module_name__", None)
         ctx.pop("__wp_current_module_bundle_origin__", None)
+        ctx.pop(DETAIL_KEY, None)
 
         # SP3 reach selector finalisation: emit `constraint_never_applied`
         # for every registered constraint whose selector covered ZERO

engine/prefs.py

@@ -0,0 +1,195 @@
+"""Server-side user preferences (`settings.json`).
+
+Why a file and not the database: some of these settings govern the database
+itself (backups run before migrations and restores replace the DB file), so
+they must be readable before any connection opens — the same chicken-and-egg
+that put the DB location preference in `engine/db/config.py`'s sidecar.
+
+Why not the browser: the ref recursion limit applies to canvas runs, preview
+and the Test Runner alike, all of which execute server-side. A value living
+in localStorage would only reach whichever surface happened to send it.
+
+Location, highest priority first:
+
+1. ``WP_SETTINGS_PATH`` env var — used as-is (tests point it at tmp_path).
+2. ``<ComfyUI user dir>/wildcard-pipeline/settings.json`` — beside the
+   library, so it survives an extension reinstall.
+3. ``<plugin>/wp-settings.json`` — when the user dir can't be detected.
+
+Every read normalizes: a missing file, unreadable JSON or an out-of-range
+value all degrade to defaults instead of raising, because a broken settings
+file must never stop a prompt from rendering.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+import threading
+from pathlib import Path
+from typing import Any
+
+SETTINGS_FILENAME = "settings.json"
+FALLBACK_FILENAME = "wp-settings.json"
+
+MAX_REF_DEPTH_MIN = 1
+MAX_REF_DEPTH_MAX = 32
+BACKUP_KEEP_MIN = 1
+BACKUP_KEEP_MAX = 100
+
+DEFAULTS: dict[str, Any] = {
+    "max_ref_depth": 8,
+    "backups": {
+        "enabled": True,
+        "keep": 7,
+        "daily": True,
+    },
+}
+
+_lock = threading.Lock()
+#: ``(path, mtime_ns)`` → cached normalized prefs. `max_ref_depth()` runs once
+#: per pipeline run (every Context node execution, every Test Runner seed), so
+#: a stat beats a parse.
+_cache: tuple[tuple[str, int], dict[str, Any]] | None = None
+
+
+def settings_path() -> Path:
+    """Resolve where settings live (see module docstring for the order)."""
+    override = os.environ.get("WP_SETTINGS_PATH")
+    if override:
+        return Path(override)
+    from engine.db.connection import wp_data_dir
+
+    data_dir = wp_data_dir()
+    if data_dir is not None:
+        return data_dir / SETTINGS_FILENAME
+    from engine.db.config import plugin_root
+
+    return plugin_root() / FALLBACK_FILENAME
+
+
+def _clamp_int(value: Any, lo: int, hi: int, default: int) -> int:
+    """Clamp an int into range; non-ints (bools included) fall back to default.
+
+    Clamping rather than rejecting an out-of-range number: a user who typed 50
+    meant "as deep as allowed", not "reset to 8".
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return default
+    if isinstance(value, float) and not value.is_integer():
+        return default
+    return max(lo, min(hi, int(value)))
+
+
+def _bool(value: Any, default: bool) -> bool:
+    return value if isinstance(value, bool) else default
+
+
+def normalize(raw: Any) -> dict[str, Any]:
+    """Return the full prefs shape from any input, filling/repairing fields."""
+    src = raw if isinstance(raw, dict) else {}
+    backups_raw = src.get("backups")
+    backups_src = backups_raw if isinstance(backups_raw, dict) else {}
+    d_backups = DEFAULTS["backups"]
+    return {
+        "max_ref_depth": _clamp_int(
+            src.get("max_ref_depth"), MAX_REF_DEPTH_MIN, MAX_REF_DEPTH_MAX,
+            DEFAULTS["max_ref_depth"],
+        ),
+        "backups": {
+            "enabled": _bool(backups_src.get("enabled"), d_backups["enabled"]),
+            "keep": _clamp_int(
+                backups_src.get("keep"), BACKUP_KEEP_MIN, BACKUP_KEEP_MAX,
+                d_backups["keep"],
+            ),
+            "daily": _bool(backups_src.get("daily"), d_backups["daily"]),
+        },
+    }
+
+
+def _read_raw(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _stat_key(path: Path) -> tuple[str, int]:
+    try:
+        return (str(path), path.stat().st_mtime_ns)
+    except OSError:
+        return (str(path), -1)
+
+
+def load() -> dict[str, Any]:
+    """Current prefs, normalized. Cached on (path, mtime) so repeat calls are
+    a single ``stat``; an external edit to the file is picked up next call."""
+    global _cache
+    path = settings_path()
+    key = _stat_key(path)
+    with _lock:
+        if _cache is not None and _cache[0] == key:
+            return copy.deepcopy(_cache[1])
+    prefs = normalize(_read_raw(path))
+    with _lock:
+        _cache = (key, prefs)
+    return copy.deepcopy(prefs)
+
+
+def _deep_merge(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in patch.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _save(prefs: dict[str, Any], path: Path) -> None:
+    """Atomically write (temp file + rename) so a crash can't truncate it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_str = tempfile.mkstemp(prefix=".wp-settings-", dir=str(path.parent))
+    tmp_path = Path(tmp_str)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(prefs, f, indent=2)
+        os.replace(tmp_path, path)
+    except OSError:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def update(partial: dict[str, Any]) -> dict[str, Any]:
+    """Deep-merge ``partial`` over the current prefs, normalize, persist.
+
+    Unknown keys are dropped by `normalize`, so the file only ever holds the
+    documented shape. Returns the full normalized prefs.
+    """
+    global _cache
+    if not isinstance(partial, dict):
+        raise TypeError("prefs update must be a dict")
+    path = settings_path()
+    merged = normalize(_deep_merge(load(), partial))
+    _save(merged, path)
+    with _lock:
+        _cache = None
+    return copy.deepcopy(merged)
+
+
+def max_ref_depth() -> int:
+    """The configured ``@{uuid}`` nesting limit — cheap enough per run.
+
+    Never raises: a settings problem must degrade to the default limit, not
+    fail the prompt that asked for it.
+    """
+    try:
+        return int(load()["max_ref_depth"])
+    except Exception:  # noqa: BLE001 - see docstring
+        return int(DEFAULTS["max_ref_depth"])
+
+
+def backups() -> dict[str, Any]:
+    """The ``backups`` sub-section of the current prefs."""
+    return load()["backups"]

engine/scenario.py

@@ -0,0 +1,397 @@
+"""Scenario runs — the Test Runner's engine side.
+
+A scenario is an ordered module stack (the same list shape a WP_Context node
+feeds ``PipelineEngine.run``), optional pinned ``$var`` values standing in for
+whatever an upstream node would pass in, and a set of seeds. Running it means
+one real ``PipelineEngine.run`` per seed and a summary of what came out:
+
+  - per-variable value counts (fully expanded values, so ``{a|b}`` branches
+    and ``@{ref}`` expansions are counted separately),
+  - per-wildcard option pick counts (by option id, before expansion),
+  - per-constraint downstream hit totals,
+  - engine warnings grouped by (type, message) with the seeds they fired on,
+  - the first ``sample_limit`` samples in full, each with its trace and
+    each variable's negatives (send-to-negative),
+  - optionally, the rendered value of a few ``track`` variables for each of
+    the first ``track_limit`` seeds (what a stored baseline compares against).
+
+Every seed is a real chain seed: the same seed on a canvas Context node holding
+the same modules produces the same values. That is the point of running here
+instead of in a browser-side mirror of the engine.
+
+Pure Python, no ComfyUI or DB imports — the API layer resolves library rows
+into the module list + catalog and hands them in.
+"""
+from __future__ import annotations
+
+import copy
+import random
+import time
+from collections import Counter
+from typing import Any
+
+from engine import negatives as neg
+from engine.context import strip_engine_internals
+from engine.pipeline import PipelineEngine
+from engine.syntax.types import ListVar
+
+MAX_SEEDS = 10_000
+DEFAULT_SAMPLE_LIMIT = 200
+DEFAULT_VALUE_LIMIT = 500
+# Seeds that survive a round-trip through JavaScript numbers (2**53 - 1).
+_MAX_SEED = 2**53 - 1
+_WARNING_SEED_LIMIT = 20
+MAX_TRACK_VARS = 8
+DEFAULT_TRACK_LIMIT = 1000
+MAX_TRACK_LIMIT = 2000
+
+
+class ScenarioError(ValueError):
+    """A scenario request that can't run (bad seed spec, too many seeds)."""
+
+
+def resolve_seeds(spec: Any, *, rng: random.Random | None = None) -> list[int]:
+    """Turn a seed spec into the concrete list of chain seeds.
+
+    Accepted shapes:
+      - ``{"from": S, "count": N}`` → ``S, S+1, … S+N-1``
+      - ``{"random": true, "count": N}`` → N distinct random seeds
+      - ``{"list": [s1, s2, …]}`` → exactly those seeds, in order
+    """
+    if not isinstance(spec, dict):
+        raise ScenarioError("seeds must be an object")
+    if "list" in spec:
+        raw = spec["list"]
+        if not isinstance(raw, list) or not raw:
+            raise ScenarioError("seeds.list must be a non-empty list")
+        try:
+            seeds = [int(s) for s in raw]
+        except (TypeError, ValueError) as exc:
+            raise ScenarioError("seeds.list must hold integers") from exc
+    else:
+        try:
+            count = int(spec.get("count", 0))
+        except (TypeError, ValueError) as exc:
+            raise ScenarioError("seeds.count must be an integer") from exc
+        if count < 1:
+            raise ScenarioError("seeds.count must be at least 1")
+        if count > MAX_SEEDS:
+            raise ScenarioError(f"seeds.count must be at most {MAX_SEEDS}")
+        if spec.get("random"):
+            r = rng or random.SystemRandom()
+            picked: set[int] = set()
+            seeds = []
+            while len(seeds) < count:
+                s = r.randint(0, _MAX_SEED)
+                if s not in picked:
+                    picked.add(s)
+                    seeds.append(s)
+        else:
+            try:
+                start = int(spec.get("from", 0))
+            except (TypeError, ValueError) as exc:
+                raise ScenarioError("seeds.from must be an integer") from exc
+            seeds = list(range(start, start + count))
+    if len(seeds) > MAX_SEEDS:
+        raise ScenarioError(f"at most {MAX_SEEDS} seeds per run")
+    for s in seeds:
+        if s < 0 or s > _MAX_SEED:
+            raise ScenarioError(f"seed {s} is outside 0..{_MAX_SEED}")
+    return seeds
+
+
+def _render(value: Any) -> str:
+    """The string a value renders as in a prompt (a multi-pick joins)."""
+    if isinstance(value, ListVar):
+        return str(value)
+    return value if isinstance(value, str) else str(value)
+
+
+def _json_value(value: Any) -> Any:
+    """JSON-safe form of a resolved value; a multi-pick keeps its items so a
+    UI can index it the way ``$name.K`` does."""
+    if isinstance(value, ListVar):
+        return {"items": list(value.items), "sep": value.sep}
+    return value if isinstance(value, (str, int, float, bool)) or value is None else str(value)
+
+
+def _sample_negatives(ctx: Any, names: Any) -> dict[str, list[dict[str, Any]]]:
+    """Each public variable's negative entries (send-to-negative), as the
+    engine filed them: ``{binding: [{text, pick, source}]}``. Variables
+    without negatives are left out."""
+    out: dict[str, list[dict[str, Any]]] = {}
+    for name in names:
+        rows = [
+            {
+                "text": str(e.get("text", "")),
+                "pick": e.get("pick"),
+                "source": str(e.get("source") or ""),
+            }
+            for e in neg.get_entries(ctx, name)
+            if str(e.get("text", "")).strip()
+        ]
+        if rows:
+            out[name] = rows
+    return out
+
+
+def _joined_negative(ctx: Any, name: str) -> str:
+    """A variable's negatives as the one line an Assembler rendering only
+    ``$name`` would emit (tag-level dedupe)."""
+    return neg.join_unique(str(e.get("text", "")) for e in neg.get_entries(ctx, name))
+
+
+def _refs_by_owner(log: Any) -> dict[str, list[dict[str, Any]]]:
+    """Group the engine's nested-ref log by the stack uid whose resolve made
+    each pick, keeping pre-order so `depth` draws the tree."""
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    if not isinstance(log, list):
+        return grouped
+    for row in log:
+        if not isinstance(row, dict):
+            continue
+        grouped.setdefault(str(row.get("owner") or ""), []).append({
+            "uuid": row.get("uuid", ""),
+            "name": row.get("name", ""),
+            "option_id": row.get("option_id"),
+            "depth": int(row.get("depth") or 0),
+            "value": _json_value(row.get("value", row.get("raw", ""))),
+        })
+    return grouped
+
+
+def _slim_trace(
+    trace: Any, names: dict[str, str], refs: dict[str, list[dict[str, Any]]] | None = None,
+) -> list[dict[str, Any]]:
+    """The engine trace, trimmed to what a per-seed view needs. The engine
+    doesn't carry display names on trace rows, so they come from the stack
+    (keyed by `_uid`, falling back to the library id). ``refs`` adds the
+    nested `@{ref}` picks each row's resolve made, as a pre-order list."""
+    refs = refs or {}
+    out: list[dict[str, Any]] = []
+    if not isinstance(trace, list):
+        return out
+    for row in trace:
+        if not isinstance(row, dict):
+            continue
+        writes = []
+        for w in row.get("writes") or []:
+            if isinstance(w, dict):
+                write = {
+                    "variable": w.get("variable"),
+                    "value": _json_value(w.get("value")),
+                    "overwrite": bool(w.get("overwrite", False)),
+                }
+                # The negatives the variable carries after this write (the
+                # engine only stamps it when non-empty).
+                if isinstance(w.get("negative"), str) and w["negative"]:
+                    write["negative"] = w["negative"]
+                writes.append(write)
+        out.append({
+            "id": row.get("id", ""),
+            "_uid": row.get("_uid", ""),
+            "type": row.get("type", ""),
+            "name": names.get(row.get("_uid") or "") or names.get(row.get("id") or "", ""),
+            "binding": row.get("binding") or "",
+            "status": row.get("status", ""),
+            "seed": row.get("seed"),
+            "error": row.get("error"),
+            "writes": writes,
+            "refs": refs.get(str(row.get("_uid") or ""), []),
+        })
+    return out
+
+
+def _slim_warning(w: Any) -> dict[str, Any]:
+    if not isinstance(w, dict):
+        return {"type": "unknown", "message": str(w)}
+    return {k: _json_value(v) for k, v in w.items()}
+
+
+def _option_id_by_value(modules: list[dict[str, Any]]) -> dict[str, dict[str, str]]:
+    """module id → {option value → option id}, for counting multi-pick
+    records (which carry values, not ids) against their options."""
+    table: dict[str, dict[str, str]] = {}
+    for m in modules:
+        if not isinstance(m, dict) or m.get("type") != "wildcard":
+            continue
+        payload = m.get("payload")
+        options = payload.get("options") if isinstance(payload, dict) else None
+        if not isinstance(options, list):
+            continue
+        by_value: dict[str, str] = {}
+        for opt in options:
+            if isinstance(opt, dict) and isinstance(opt.get("id"), str):
+                by_value.setdefault(str(opt.get("value", "")), opt["id"])
+        table[str(m.get("id", ""))] = by_value
+    return table
+
+
+def run_scenario(
+    modules: list[dict[str, Any]],
+    *,
+    seeds: list[int],
+    catalog: dict[str, Any] | None = None,
+    pins: dict[str, str] | None = None,
+    sample_limit: int = DEFAULT_SAMPLE_LIMIT,
+    value_limit: int = DEFAULT_VALUE_LIMIT,
+    track: list[str] | None = None,
+    track_limit: int = DEFAULT_TRACK_LIMIT,
+) -> dict[str, Any]:
+    """Run ``modules`` once per seed and summarise the results.
+
+    ``pins`` are written into the context before each run, exactly like
+    values arriving from an upstream Context node; a module in the stack that
+    writes the same variable replaces the pin, as it would at run time.
+
+    A seed whose run raises is recorded as a failed sample (and counted in
+    ``failed``) rather than aborting the whole scenario.
+
+    ``track`` names variables whose rendered value is recorded per seed, for
+    the first ``track_limit`` seeds, under ``tracked``: ``{"seeds": [...],
+    "values": {name: [value or None, ...]}}``. ``None`` means the variable
+    wasn't set on that seed (or the seed failed).
+    """
+    catalog = catalog or {}
+    pins = {str(k): str(v) for k, v in (pins or {}).items()}
+    option_ids = _option_id_by_value(modules)
+    names: dict[str, str] = {}
+    for m in modules:
+        if isinstance(m, dict):
+            meta = m.get("meta") if isinstance(m.get("meta"), dict) else {}
+            name = str(m.get("name") or meta.get("name") or "")
+            for key in (m.get("_uid"), m.get("id")):
+                if isinstance(key, str) and key:
+                    names.setdefault(key, name)
+
+    var_counts: dict[str, Counter[str]] = {}
+    pick_counts: dict[str, Counter[str]] = {}
+    constraint_hits: Counter[str] = Counter()
+    warnings: dict[tuple[str, str], dict[str, Any]] = {}
+    internal_vars: set[str] = set()
+    samples: list[dict[str, Any]] = []
+    failed = 0
+    track = [str(t).lstrip("$") for t in (track or [])][:MAX_TRACK_VARS]
+    tracked_seeds: list[int] = []
+    tracked: dict[str, list[str | None]] = {name: [] for name in track}
+    tracked_neg: dict[str, list[str | None]] = {name: [] for name in track}
+
+    def record(seed: int, resolved: dict[str, Any] | None, run_ctx: Any = None) -> None:
+        if not track or len(tracked_seeds) >= track_limit:
+            return
+        tracked_seeds.append(seed)
+        for name in track:
+            if resolved is None or name not in resolved:
+                tracked[name].append(None)
+                tracked_neg[name].append(None)
+            else:
+                tracked[name].append(_render(resolved[name]))
+                tracked_neg[name].append(_joined_negative(run_ctx, name))
+
+    started = time.perf_counter()
+    for seed in seeds:
+        ctx: dict[str, Any] = dict(pins)
+        ctx["__wp_catalog__"] = catalog
+        # Ask the resolver to record nested @{ref} picks for the trace.
+        ctx["__wp_ref_log__"] = []
+        try:
+            # The engine mutates module dicts in places (coercion, per-run
+            # stamps); a deep copy keeps every seed starting from the same
+            # stack.
+            ctx = PipelineEngine().run(copy.deepcopy(modules), ctx=ctx, seed=seed)
+        except Exception as exc:  # noqa: BLE001 - one bad seed must not sink the run
+            failed += 1
+            record(seed, None)
+            if len(samples) < sample_limit:
+                samples.append({
+                    "seed": seed, "vars": {}, "trace": [], "warnings": [],
+                    "negatives": {},
+                    "error": f"{type(exc).__name__}: {exc}",
+                })
+            continue
+
+        resolved = strip_engine_internals(ctx)
+        record(seed, resolved, ctx)
+        flags = ctx.get("__wp_internal_flags__")
+        if isinstance(flags, dict):
+            internal_vars.update(k for k, v in flags.items() if v)
+        for name, value in resolved.items():
+            var_counts.setdefault(name, Counter())[_render(value)] += 1
+
+        picks = ctx.get("__wp_picks__")
+        if isinstance(picks, dict):
+            for mid, entry in picks.items():
+                if not isinstance(entry, dict):
+                    continue
+                bucket = pick_counts.setdefault(str(mid), Counter())
+                if isinstance(entry.get("values"), list):
+                    lookup = option_ids.get(str(mid), {})
+                    for v in entry["values"]:
+                        bucket[lookup.get(str(v), str(v))] += 1
+                elif entry.get("id") is not None:
+                    bucket[str(entry["id"])] += 1
+
+        # Nested @{ref} picks count toward their wildcard's option counts
+        # too, so a wildcard reached only through refs still shows up.
+        ref_log = ctx.get("__wp_ref_log__")
+        if isinstance(ref_log, list):
+            for row in ref_log:
+                if isinstance(row, dict) and row.get("uuid"):
+                    oid = row.get("option_id")
+                    key = str(oid) if oid is not None else str(row.get("raw", ""))
+                    pick_counts.setdefault(str(row["uuid"]), Counter())[key] += 1
+
+        hits = ctx.get("__wp_constraint_hits__")
+        if isinstance(hits, dict):
+            for cid, n in hits.items():
+                constraint_hits[str(cid)] += int(n or 0)
+
+        sample_warnings = [_slim_warning(w) for w in ctx.get("__wp_warnings__") or []]
+        for w in sample_warnings:
+            key = (str(w.get("type", "")), str(w.get("message", "")))
+            group = warnings.get(key)
+            if group is None:
+                group = warnings[key] = {**w, "count": 0, "seeds": []}
+            group["count"] += 1
+            if seed not in group["seeds"] and len(group["seeds"]) < _WARNING_SEED_LIMIT:
+                group["seeds"].append(seed)
+
+        if len(samples) < sample_limit:
+            samples.append({
+                "seed": seed,
+                "vars": {k: _json_value(v) for k, v in resolved.items()},
+                "trace": _slim_trace(
+                    ctx.get("__wp_trace__"), names, _refs_by_owner(ctx.get("__wp_ref_log__")),
+                ),
+                "warnings": sample_warnings,
+                "negatives": _sample_negatives(ctx, resolved.keys()),
+                "error": None,
+            })
+    elapsed_ms = round((time.perf_counter() - started) * 1000, 1)
+
+    variables: dict[str, Any] = {}
+    for name, counts in var_counts.items():
+        ranked = counts.most_common()
+        kept = ranked[:value_limit]
+        variables[name] = {
+            "counts": dict(kept),
+            "distinct": len(ranked),
+            "other": sum(n for _, n in ranked[value_limit:]),
+            "internal": name in internal_vars,
+        }
+
+    return {
+        "runs": len(seeds),
+        "failed": failed,
+        "elapsed_ms": elapsed_ms,
+        "seeds": {"first": seeds[0] if seeds else None, "count": len(seeds)},
+        "variables": variables,
+        "picks": {mid: dict(c) for mid, c in pick_counts.items()},
+        "constraint_hits": dict(constraint_hits),
+        "warnings": sorted(warnings.values(), key=lambda g: -g["count"]),
+        "samples": samples,
+        "tracked": (
+            {"seeds": tracked_seeds, "values": tracked, "negatives": tracked_neg}
+            if track else None
+        ),
+    }

engine/schemas/instance_schemas.py

@@ -51,6 +51,10 @@ INSTANCE_SCHEMAS: dict[str, dict[str, InstanceFieldType]] = {
         # SP2c: multi-pick draws WITH replacement (repeats allowed) when true,
         # without (unique) when false/absent. Mirrors the inline `~` flag.
         "pick_independent": "boolean",
+        # Model-aware pipelines: take the option whose text equals this
+        # variable's value (e.g. `model_variant`), else the fallback, else
+        # roll. Instance-local; makes the wildcard a constraint source.
+        "match_variable": "string",
         # `mode` and `pinned_option_id` removed in v2 — resolve mode is
         # implicit in pool state. Engine handler still reads them when
         # present in legacy snapshots; the schema validator now flags

engine/sweep.py

@@ -0,0 +1,122 @@
+"""Sweep mode for WP_ContextLoop: every combination of chosen wildcards.
+
+A sweep axis names one downstream wildcard instance (by its per-instance
+`_uid`) and the option ids to walk. The loop runs the cartesian product of
+the axes, one frame per combination, capped at `limit`. Each frame carries a
+`{uid: option_id}` pin map in `__wp_pin_overrides__`; the pipeline turns a
+matching wildcard instance into a `pinned` one for that frame (see
+`apply_pin_override`), so the existing pinned path does the picking.
+
+Ordering is row-major: the LAST axis changes fastest, so a two-axis sweep
+reads like a grid (row = first axis, column = second).
+
+Pure Python, no ComfyUI imports.
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any
+
+PIN_KEY = "__wp_pin_overrides__"
+HOLD_KEY = "__wp_sweep_hold__"
+
+DEFAULT_LIMIT = 64
+MAX_LIMIT = 999
+
+
+def parse_sweep(raw: object) -> dict[str, Any]:
+    """Recovery-friendly parse of the loop config's `sweep` block.
+
+    Axes without a uid or without any option ids are dropped; a uid listed
+    twice keeps its first axis; option ids are deduped in order. Mirrors
+    `parseSweep` in `src/components/context-loop/types.ts`.
+    """
+    out: dict[str, Any] = {
+        "enabled": False,
+        "limit": DEFAULT_LIMIT,
+        "hold_others": True,
+        "axes": [],
+    }
+    if not isinstance(raw, dict):
+        return out
+    out["enabled"] = raw.get("enabled") is True
+    limit = raw.get("limit")
+    if isinstance(limit, int) and not isinstance(limit, bool):
+        out["limit"] = min(MAX_LIMIT, max(1, limit))
+    hold = raw.get("hold_others")
+    if isinstance(hold, bool):
+        out["hold_others"] = hold
+    axes: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for axis in raw.get("axes") or []:
+        if not isinstance(axis, dict):
+            continue
+        uid = axis.get("uid")
+        if not isinstance(uid, str) or not uid or uid in seen:
+            continue
+        ids: list[str] = []
+        for oid in axis.get("option_ids") or []:
+            if isinstance(oid, str) and oid and oid not in ids:
+                ids.append(oid)
+        # An axis with nothing ticked is kept (the user cleared it to pick
+        # a few by hand) but sweeps nothing: see `live_axes`.
+        seen.add(uid)
+        clean: dict[str, Any] = {"uid": uid, "option_ids": ids}
+        label = axis.get("label")
+        if isinstance(label, str) and label:
+            clean["label"] = label
+        axes.append(clean)
+    out["axes"] = axes
+    return out
+
+
+def live_axes(axes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The axes with at least one option ticked; only these sweep."""
+    return [a for a in axes if a["option_ids"]]
+
+
+def sweep_total(axes: list[dict[str, Any]]) -> int:
+    """Number of combinations before the limit (1 for no axes)."""
+    total = 1
+    for axis in live_axes(axes):
+        total *= len(axis["option_ids"])
+    return total
+
+
+def sweep_frames(axes: list[dict[str, Any]], limit: int) -> list[dict[str, str]]:
+    """The first `limit` combinations as `{uid: option_id}` pin maps."""
+    axes = live_axes(axes)
+    if not axes:
+        return []
+    uids = [a["uid"] for a in axes]
+    combos = itertools.product(*(a["option_ids"] for a in axes))
+    capped = itertools.islice(combos, max(1, limit))
+    return [dict(zip(uids, combo, strict=True)) for combo in capped]
+
+
+def apply_pin_override(
+    snapshot: dict[str, Any], module_uid: str, ctx: dict[str, Any],
+) -> dict[str, Any]:
+    """Return `snapshot` with a swept wildcard pinned to this frame's option.
+
+    Only wildcards are pinned; the pin rides the existing `pinned` mode so
+    axes still roll and the pick is recorded for downstream constraints.
+    Returns a shallow copy rather than editing in place, because a snapshot
+    can be the caller's module dict itself (`coerce_legacy_module` passes
+    already-coerced modules through).
+    """
+    pins = ctx.get(PIN_KEY)
+    if not isinstance(pins, dict) or not module_uid or module_uid not in pins:
+        return snapshot
+    if snapshot.get("type") != "wildcard":
+        return snapshot
+    inst = snapshot.get("instance")
+    return {
+        **snapshot,
+        "instance": {
+            **(inst if isinstance(inst, dict) else {}),
+            "mode": "pinned",
+            "pinned_option_id": pins[module_uid],
+        },
+    }

engine/syntax/resolve.py

@@ -7,6 +7,7 @@ happens inside `_resolve_ref` (Task 9) and brace resolvers (Tasks 10–11).
 from __future__ import annotations
 
 import logging
+from typing import Any
 
 from engine.syntax.subcat_filter import matches as _subcat_matches
 from engine.syntax.subcat_filter import parse as _parse_subcat
@@ -42,6 +43,7 @@ def _resolve_tokens(
     visited: tuple[str, ...],
 ) -> str:
     parts: list[str] = []
+    empty_refs: list[int] = []
     for tok in tokens:
         if tok.kind == TokenKind.TEXT:
             parts.append(tok.raw)
@@ -50,7 +52,10 @@ def _resolve_tokens(
         elif tok.kind == TokenKind.VAR:
             parts.append(_resolve_var(tok, ctx))
         elif tok.kind == TokenKind.REF:
-            parts.append(_resolve_ref(tok, ctx, depth, visited))
+            resolved = _resolve_ref(tok, ctx, depth, visited)
+            if not resolved:
+                empty_refs.append(len(parts))
+            parts.append(resolved)
         elif tok.kind == TokenKind.DP_BRACE:
             parts.append(_resolve_inline_pick(tok, ctx, depth, visited))
         elif tok.kind == TokenKind.DP_MULTI:
@@ -62,7 +67,52 @@ def _resolve_tokens(
             raise AssertionError("DP_PIPE should never be top-level")
         else:
             raise AssertionError(f"unknown token kind: {tok.kind}")
-    return "".join(parts)
+    return _join_tidy(parts, empty_refs)
+
+
+_HWS = " \t"
+
+
+def _join_tidy(parts: list[str], empty_refs: list[int]) -> str:
+    """Join resolved parts, closing the gap each empty ``@{}`` ref leaves.
+
+    A ref that resolves to nothing (a placeholder or deleted module, a filter
+    that matched no option, an empty option) used to leave its surroundings
+    behind: ``red @{x} dress`` became ``red  dress`` and ``red, @{x}, dress``
+    became ``red, , dress``. At each such seam this drops one doubled comma,
+    then one side of doubled spaces/tabs, and at the start or end of the text
+    the dangling comma and spaces. Newlines and everything away from the seam
+    are left exactly as written. Mirrored in ``resolveTokens.ts``.
+    """
+    if not empty_refs:
+        return "".join(parts)
+    out = list(parts)
+    for i in empty_refs:
+        left = next((j for j in range(i - 1, -1, -1) if out[j]), None)
+        right = next((j for j in range(i + 1, len(out)) if out[j]), None)
+        if left is None and right is None:
+            continue
+        if left is None:
+            out[right] = _strip_lead(out[right])
+            continue
+        if right is None:
+            out[left] = _strip_trail(out[left])
+            continue
+        if out[left].rstrip(_HWS).endswith(",") and out[right].lstrip(_HWS).startswith(","):
+            out[right] = out[right].lstrip(_HWS)[1:]
+        if out[right] and out[left][-1:] in (" ", "\t") and out[right][0] in _HWS:
+            out[right] = out[right].lstrip(_HWS)
+    return "".join(out)
+
+
+def _strip_lead(text: str) -> str:
+    text = text.lstrip(_HWS)
+    return text[1:].lstrip(_HWS) if text.startswith(",") else text
+
+
+def _strip_trail(text: str) -> str:
+    text = text.rstrip(_HWS)
+    return text[:-1].rstrip(_HWS) if text.endswith(",") else text
 
 
 _VAR_SURFACES_ALLOWED = frozenset(["combine", "derivation", "assembler"])
@@ -103,6 +153,20 @@ def _resolve_var(tok: Token, ctx: ResolveContext) -> str:
             ),
         )
         return f"${name}"
+    # An axis read is a different lookup against a different bucket, so it
+    # branches BEFORE the var lookup — `$outfit.SHOES` must resolve even when
+    # nothing bound `$outfit` itself, and must not raise `unknown_var` on the
+    # way past.
+    axis = tok.meta.get("axis")
+    if axis == NEG_ACCESSOR:
+        # `$name.neg` reads the variable's negatives. Not a read of the
+        # variable itself: it carries no negatives along (that would echo
+        # them) and does not count as rendering `$name`.
+        return _resolve_negative(tok, ctx)
+    if axis:
+        out = _resolve_axis(tok, ctx, str(axis))
+        _note_read(ctx, name, tok.meta.get("index"), out)
+        return out
     value = ctx.get_var(name)
     if value is None:
         _push_warning(
@@ -122,7 +186,132 @@ def _resolve_var(tok: Token, ctx: ResolveContext) -> str:
     # as a 1-element list so `$str.0` == `$str` and `$str.1` == "". The
     # accessor + ListVar-fold contract lives in deref_var_value
     # (engine/syntax/types.py); the derivation + converter reads share it.
-    return deref_var_value(value, tok.meta.get("index"))
+    out = deref_var_value(value, tok.meta.get("index"))
+    _note_read(ctx, name, tok.meta.get("index"), out)
+    return out
+
+
+#: The accessor that reads a variable's negatives (`$name.neg`,
+#: `$name.K.neg`). Reserved: an `accepts` tag group cannot use this name.
+NEG_ACCESSOR = "neg"
+
+
+def _resolve_negative(tok: Token, ctx: ResolveContext) -> str:
+    """Render `$name.neg` / `$name.K.neg`: the negatives filed for `name`
+    (all of them, or pick K's plus the whole-value ones), tag-deduped.
+
+    A variable with no negatives renders empty without a warning, since most
+    variables have none. Only an unbound name that also has none warns."""
+    name = str(tok.meta.get("name", ""))
+    index = tok.meta.get("index")
+    getter = getattr(ctx, "get_negative", None)
+    got = getter(name, index if isinstance(index, int) else None) if callable(getter) else None
+    if got is None and ctx.get_var(name) is None:
+        _push_warning(
+            ctx,
+            type="unknown_var",
+            severity="warn",
+            module_id="",
+            source_field="",
+            position=tok.start,
+            token_index=None,
+            detail={"name": name, "surface": ctx.surface},
+            message=f"Unknown variable ${name}",
+        )
+    return got or ""
+
+
+def _note_read(ctx: ResolveContext, name: str, index: Any, out: str) -> None:
+    """Tell a collecting context (send-to-negative) which binding this read
+    rendered, and which pick. An indexed read that rendered nothing (out of
+    range) carries nothing."""
+    note = getattr(ctx, "note_var_read", None)
+    if not callable(note):
+        return
+    if index is not None and not out:
+        return
+    note(name, index if isinstance(index, int) else None)
+
+
+def _note_ref_negative(ctx: ResolveContext, option: dict | None) -> None:
+    note = getattr(ctx, "note_ref_negative", None)
+    if callable(note) and isinstance(option, dict):
+        note(option)
+
+
+def _resolve_axis(tok: Token, ctx: ResolveContext, axis: str) -> str:
+    """Render `$name.AXIS`, `$name.K.AXIS` and `$name.AXIS.K`.
+
+    Never re-rolls: the choice was made when the wildcard picked, and this
+    reads it back — that is what makes two modules, or two nodes, agree.
+
+    Deliberately does NOT route through `deref_var_value`. An axis value is not
+    a ListVar, and keeping it off that path leaves the SP2a accessor contract
+    untouched.
+    """
+    name = str(tok.meta.get("name", ""))
+    got = ctx.get_axis(name, axis)
+    if got is None:
+        declared = ctx.declared_axes(name)
+        if declared is not None and axis in declared:
+            # The axis exists; this roll's option just carries no tag on it.
+            # Legitimate (the editor already advises on such options), so it
+            # is an info note, and asking whether the group is marked
+            # `accepts` would send the user to fix something that is fine.
+            _push_warning(
+                ctx,
+                type="axis_untagged_pick",
+                severity="info",
+                module_id="",
+                source_field="",
+                position=tok.start,
+                token_index=None,
+                detail={"name": name, "axis": axis, "surface": ctx.surface},
+                message=(
+                    f"${name}.{axis} is empty: the picked ${name} option "
+                    f"has no '{axis}' tag"
+                ),
+            )
+            return ""
+        if declared:
+            hint = (
+                f"its wildcard's accepts groups are {', '.join(declared)}. "
+                f"Is '{axis}' a classify group, or misspelled?"
+            )
+        elif declared is not None:
+            hint = (
+                "its wildcard has no accepts groups. Is that tag group "
+                "marked 'accepts'?"
+            )
+        else:
+            hint = "is that tag group marked 'accepts'?"
+        _push_warning(
+            ctx,
+            type="unknown_tag_axis",
+            severity="warn",
+            module_id="",
+            source_field="",
+            position=tok.start,
+            token_index=None,
+            detail={
+                "name": name, "axis": axis, "surface": ctx.surface,
+                "declared": declared,
+            },
+            message=f"${name} has no '{axis}' axis — {hint}",
+        )
+        return ""
+    index = tok.meta.get("index")
+    if isinstance(got, list):
+        if index is None:
+            return ", ".join(g for g in got if g)
+        if isinstance(index, int) and 0 <= index < len(got):
+            return got[index] or ""
+        return ""
+    # A single pick behaves as a one-element list, mirroring deref_var_value so
+    # `$x.0.AXIS` == `$x.AXIS` and any higher index is empty.
+    if index is not None:
+        return str(got) if index == 0 else ""
+    return str(got)
 
 
 def _push_warning(ctx: ResolveContext, **fields) -> None:
@@ -140,7 +329,13 @@ def _pick_weighted(options: list[dict], rng) -> dict | None:
         return None
     total = sum(max(0.0, float(o.get("weight", 1))) for o in options)
     if total <= 0:
-        return options[0]
+        # Nothing is selectable — every option is either weight 0 (documented
+        # as "disable without deleting") or was excluded by a constraint.
+        # Returning options[0] here looked like a working pick: a real option,
+        # right shape, right place, and wrong. It stayed wrong silently until
+        # the list was reordered. Callers turn None into an empty binding,
+        # which is what the null option already means.
+        return None
     r = rng.random() * total
     acc = 0.0
     for opt in options:
@@ -309,13 +504,20 @@ def _resolve_multi_pick(
             if callable(set_carrier):
                 set_carrier(ref_uuid, None)
             try:
-                return sep.join(
-                    _resolve_tokens(
+                parts: list[str] = []
+                id_of = {str(o.get("value", "")): o.get("id") for o in pool}
+                opt_of = {str(o.get("value", "")): o for o in pool}
+                for v in chosen:
+                    _note_ref_negative(ctx, opt_of.get(v))
+                    logged = _log_ref_pick(ctx, ref_uuid, id_of.get(v), depth, v)
+                    out = _resolve_tokens(
                         tokenize_text(v), ctx, depth=depth + 1,
                         visited=visited + (ref_uuid,),
                     ) if v else ""
-                    for v in chosen
-                )
+                    if logged is not None:
+                        logged["value"] = out
+                    parts.append(out)
+                return sep.join(parts)
             finally:
                 if callable(set_carrier) and saved_carrier is not None:
                     set_carrier(*saved_carrier)
@@ -458,6 +660,13 @@ def ref_option_pool(tok: Token, ctx: ResolveContext) -> list[dict]:
             )
             return []
 
+    # Schema v9 fallback (engine/modules/_fallback.py): the flagged option
+    # rolls normally and returns as the whole pool when the constraints below
+    # leave nothing to pick.
+    from engine.modules._fallback import fallback_warning, find_fallback, pool_is_dead
+    fallback = find_fallback(options)
+    any_applied = False
+
     get_constraints = getattr(ctx, "get_constraints", None)
     get_picks = getattr(ctx, "get_picks", None)
     if callable(get_constraints) and callable(get_picks):
@@ -467,6 +676,7 @@ def ref_option_pool(tok: Token, ctx: ResolveContext) -> list[dict]:
                 apply_constraints_for_target,
                 warn_excludes_all,
             )
+            from engine.modules.wildcard_handler import _accepts_axes
             # SP3: share the ctx-resident hit counter so a nested-ref
             # target occurrence counts toward the same first/next
             # coverage as direct top-level instances. `carrier_ctx` is
@@ -484,12 +694,42 @@ def ref_option_pool(tok: Token, ctx: ResolveContext) -> list[dict]:
             options, any_applied = apply_constraints_for_target(
                 options, uuid, constraints, get_picks(), ctx.warnings,
                 hits=hits, firing_uid=None, carrier_ctx=carrier_ctx,
+                # TARGET-side accepts axes for a nested @{} target, so its
+                # multi-tag accepts option survives when the source allows any
+                # alternative (same as the top-level path).
+                target_axes=(
+                    _accepts_axes(payload_dict)
+                    if isinstance(payload_dict, dict) else {}
+                ),
             )
-            if any_applied:
+            if any_applied and fallback is None:
                 warn_excludes_all(options, uuid, ctx.warnings)
+    if fallback is not None and pool_is_dead(options):
+        ctx.warnings.append(fallback_warning(uuid, fallback, constrained=any_applied))
+        return [{**fallback, "weight": 1}]
     return options
 
 
+def _log_ref_pick(
+    ctx: ResolveContext, uuid: str, option_id: Any, depth: int, raw: str,
+) -> dict[str, Any] | None:
+    """Record one nested `@{uuid}` pick in the opt-in ref log, if the
+    context carries one (the Test Runner seeds it; canvas runs don't).
+    Returns the stored row so the caller can add the expanded `value`
+    after recursing, or None when nothing is being logged."""
+    log_ref = getattr(ctx, "log_ref", None)
+    if not callable(log_ref):
+        return None
+    module = ctx.get_module(uuid)
+    return log_ref({
+        "uuid": uuid,
+        "name": (module or {}).get("name") or uuid,
+        "option_id": option_id,
+        "depth": depth,
+        "raw": raw,
+    })
+
+
 def _resolve_ref(
     tok: Token,
     ctx: ResolveContext,
@@ -570,6 +810,11 @@ def _resolve_ref(
     if chosen is None:
         return ""
 
+    # Send-to-negative: the picked option's negative belongs to whatever this
+    # text resolves into (the carrier binding). Noted even for an empty pick,
+    # so a "none" option can still say what it rules out.
+    _note_ref_negative(ctx, chosen)
+
     chosen_value = str(chosen.get("value", ""))
     if not chosen_value:
         return ""
@@ -583,15 +828,22 @@ def _resolve_ref(
     # that's the expected deeper-than-one-hop behaviour (positional
     # first/next/all cover deeper nesting). Mirrors the rng save/restore.
     nested_tokens = tokenize_text(chosen_value)
+    # Opt-in ref log (Test Runner): record this pick before recursing so
+    # the log reads in pre-order, then fill in what it expanded to.
+    logged = _log_ref_pick(ctx, uuid, chosen.get("id"), depth, chosen_value)
     get_carrier = getattr(ctx, "get_carrier", None)
     set_carrier = getattr(ctx, "set_carrier", None)
     if callable(get_carrier) and callable(set_carrier):
         saved_carrier = get_carrier()
         set_carrier(uuid, chosen.get("id"))
         try:
-            return _resolve_tokens(
+            out = _resolve_tokens(
                 nested_tokens, ctx, depth=depth + 1, visited=visited + (uuid,)
             )
         finally:
             set_carrier(*saved_carrier)
-    return _resolve_tokens(nested_tokens, ctx, depth=depth + 1, visited=visited + (uuid,))
+    else:
+        out = _resolve_tokens(nested_tokens, ctx, depth=depth + 1, visited=visited + (uuid,))
+    if logged is not None:
+        logged["value"] = out
+    return out

engine/syntax/tokenize.py

@@ -13,10 +13,21 @@ import re
 
 from engine.syntax.types import Token, TokenKind
 
-# `$name` or `$name.K` — identifier starts with letter or underscore, then
-# word chars, with an optional `.K` list-index accessor (SP2a). Group 2 = the
-# index digits when present.
-_VAR_RE = re.compile(r"\$([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?")
+# `$name` with an optional accessor pair: at most one pick index and at most
+# one axis, in EITHER order (`$o.0.SHOES` == `$o.SHOES.0`). Two mirrored
+# alternatives, so `.0.1` and `.SHOES.BELTS` simply do not match the second
+# segment — the grammar rejects them without a validation pass, and the tail
+# stays literal text.
+#   group 1 — name
+#   group 2 — index, written first          ($o.0 / $o.0.SHOES)
+#   group 3 — axis after an index           ($o.0.SHOES)
+#   group 4 — axis, written first           ($o.SHOES / $o.SHOES.0)
+#   group 5 — index after an axis           ($o.SHOES.0)
+_VAR_RE = re.compile(
+    r"\$([A-Za-z_][A-Za-z0-9_]*)"
+    r"(?:\.(?:(\d+)(?:\.([A-Za-z_][A-Za-z0-9_]*))?"
+    r"|([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?))?"
+)
 # 4-segment ref grammar (fixed order): `@{8hex [#name] [:expr] [!null]}`.
 #   group 1 — uuid: exactly 8 lowercase hex chars.
 #   group 2 — optional `#name`: display label cached at write-time so a
@@ -186,8 +197,14 @@ def tokenize_text(text: str) -> list[Token]:
             if m:
                 _flush_text(i)
                 var_meta: dict[str, object] = {"name": m.group(1)}
-                if m.group(2) is not None:
-                    var_meta["index"] = int(m.group(2))
+                # Normalise both spellings here, so nothing downstream ever
+                # learns which order the user wrote.
+                _idx = m.group(2) or m.group(5)
+                _axis = m.group(3) or m.group(4)
+                if _idx is not None:
+                    var_meta["index"] = int(_idx)
+                if _axis is not None:
+                    var_meta["axis"] = _axis
                 out.append(Token(
                     kind=TokenKind.VAR,
                     raw=m.group(0),

engine/syntax/types.py

@@ -93,6 +93,36 @@ def split_var_accessor(name: str) -> tuple[str, int | None]:
     return (name, None)
 
 
+_VAR_REF_RE = re.compile(
+    r"^([A-Za-z_][A-Za-z0-9_]*)"
+    r"(?:\.(?:(\d+)(?:\.([A-Za-z_][A-Za-z0-9_]*))?"
+    r"|([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?))?$"
+)
+
+
+def parse_var_reference(name: str) -> tuple[str, int | None, str | None]:
+    """Split a bare var reference into ``(base, index, axis)``.
+
+    The string-path twin of the tokenizer's ``_VAR_RE`` — derivation conditions
+    store ``condition.var`` as text, not tokens. Kept separate from
+    :func:`split_var_accessor` so the SP2a list-accessor contract and its
+    existing callers are untouched.
+
+    Both accessor orders are accepted and normalise to the same triple:
+    ``outfit.0.SHOES`` and ``outfit.SHOES.0`` are the same reference. A name
+    that matches nothing is returned whole with both accessors ``None``, so an
+    unusual ctx key resolves as itself rather than being truncated.
+    """
+    if not isinstance(name, str):
+        return ("", None, None)
+    m = _VAR_REF_RE.match(name)
+    if not m:
+        return (name, None, None)
+    idx = m.group(2) or m.group(5)
+    axis = m.group(3) or m.group(4)
+    return (m.group(1), int(idx) if idx is not None else None, axis)
+
+
 def deref_var_value(value: str | ListVar | None, index: int | None) -> str:
     """Render a resolved var value to a string, honoring an optional ``.K``
     list accessor (SP2a). ListVar: bare -> ``sep.join(items)``; ``.K`` ->
@@ -134,6 +164,24 @@ class ResolveContext(Protocol):
         binds a ``str``."""
         ...
 
+    def get_axis(self, name: str, axis: str) -> str | list[str | None] | None:
+        """Return the tag rolled for `name`'s `axis`, or None if it has none.
+
+        A single-pick source yields a ``str``; a multi-select one yields a
+        list with one slot per pick in pick order (``None`` for a pick whose
+        option carries no tag on this axis, so indexes line up with the
+        variable's own). The value was rolled
+        when the wildcard picked — this only reads it back, which is what makes
+        two modules (or two nodes) agree.
+        """
+        ...
+
+    def declared_axes(self, name: str) -> list[str] | None:
+        """Return the ``accepts`` axes the wildcard bound to `name` declares,
+        or None when that is not known. Lets an empty axis read tell "this
+        pick carries no tag on the axis" apart from "there is no such axis"."""
+        ...
+
     def get_module(self, uuid: str) -> dict[str, Any] | None:
         """Return the module catalog row for `uuid`, or None if missing.
 

engine/template.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from engine import negatives
 from engine.modules import build_resolve_ctx
 from engine.syntax import resolve_text
 
@@ -17,13 +18,32 @@ _COMMA_GAP = re.compile(r",\s*,")
 _TRIM_PUNCT = re.compile(r"\s+([,.;:!?])")
 
 
-def resolve_variables(template: str, ctx: dict[str, Any]) -> str:
+def resolve_variables(
+    template: str,
+    ctx: dict[str, Any],
+    *,
+    reads: list[tuple[str, Any]] | None = None,
+) -> str:
     """Resolve `$var` / `@{uuid}` / `{a|b|c}` / `{N$$sep$$...}` against ctx.
 
     Surface defaults to "assembler" (matches wp_nodes/assembler_node.py
     usage). For a different surface, call resolve_text directly with a
     custom ResolveContext.
+
+    `reads`, when given, receives one `(name, index)` per `$var` the
+    template rendered — what send-to-negative collects negatives from.
     """
+    return tidy_prompt(resolve_variables_raw(template, ctx, reads=reads))
+
+
+def resolve_variables_raw(
+    template: str,
+    ctx: dict[str, Any],
+    *,
+    reads: list[tuple[str, Any]] | None = None,
+) -> str:
+    """`resolve_variables` without the whitespace cleanup, for callers that
+    splice several resolved pieces together before tidying once."""
     if not template:
         return ""
 
@@ -34,10 +54,17 @@ def resolve_variables(template: str, ctx: dict[str, Any]) -> str:
     ctx.setdefault("__wp_warnings__", [])
 
     rctx = build_resolve_ctx(ctx, surface="assembler")
-    out = resolve_text(template, rctx)
+    if reads is None:
+        return resolve_text(template, rctx)
+    with negatives.collecting(rctx) as col:
+        out = resolve_text(template, rctx)
+    reads.extend(col.reads)
+    return out
 
-    # Whitespace cleanup post-pass (preserves the original API's behavior
-    # for templates that drop missing variables)
+
+def tidy_prompt(out: str) -> str:
+    """Whitespace cleanup post-pass (preserves the original API's behavior
+    for templates that drop missing variables)."""
     out = _WS_RUN.sub(" ", out)
     out = _COMMA_GAP.sub(",", out)
     out = _TRIM_PUNCT.sub(r"\1", out)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "comfyui-wildcard-pipeline",
-  "version": "2.13.2",
+  "version": "2.20.0",
   "private": true,
   "description": "Modular procedural prompt generation for ComfyUI",
   "author": "DumiFlex",
@@ -9,10 +9,11 @@
   "packageManager": "pnpm@9.12.0",
   "scripts": {
     "dev": "vite build --watch --mode extension",
-    "build:extension": "vite build --mode extension && pnpm docs:copy",
-    "build:manager": "vite build --mode manager",
+    "build:extension": "vite build --mode extension && pnpm docs:copy && pnpm fonts:copy && node scripts/write-asset-manifest.mjs js",
+    "build:manager": "vite build --mode manager && node scripts/write-asset-manifest.mjs web",
     "build": "pnpm build:extension && pnpm build:manager",
     "docs:copy": "node scripts/copy-help-docs.mjs",
+    "fonts:copy": "node scripts/copy-fonts.mjs",
     "docs:figures": "node scripts/build-flow-figures.mjs",
     "typecheck": "vue-tsc --noEmit",
     "lint": "eslint \"src/**/*.{ts,vue}\"",

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfyui-wildcard-pipeline"
-version = "2.13.2"
+version = "2.20.0"
 description = "Modular procedural prompt generation for ComfyUI — wildcards, constraints, derivations, and context pipelines."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,8 @@ dev = [
     "pytest>=8.0",
     "pytest-aiohttp>=1.0",
     "pytest-asyncio>=0.23",
+    # ComfyUI ships PyYAML; the wildcard file importer reads .yaml packs with it.
+    "pyyaml>=6.0",
     "ruff>=0.5",
 ]
 

scripts/build_tag_list.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Build the booru tag list the optional value autocomplete reads.
+
+Output is the four-column shape `wp_api/_tag_index.py` parses:
+
+    name,category,post_count,"alias,alias"
+
+Run by `.github/workflows/tag-list.yml`, not at install time. The result ships
+as a release asset — never in the repository (it regenerates, and a 6 MB file
+per refresh would bloat history forever) and never in the package (a usable
+list dwarfs the whole gzipped JS budget).
+
+WHY A POST-COUNT FLOOR AND NOT A PAGE COUNT
+-------------------------------------------
+`search[order]=count` sorts strictly descending ACROSS pages, verified against
+the live API on 2026-08-06:
+
+    page    1: first 8,244,950   last 55,918
+    page  100: first        68   last     67
+    page  800: first         1   last      1
+
+So a popular tag cannot hide on a later page, and stopping once counts fall
+below the floor provably loses nothing — it is an early exit, not a filter.
+Walking all 1000 allowed pages spends ~900 requests and a quarter of an hour
+collecting single-post tags nobody will ever autocomplete.
+
+For reference, ComfyUI-Custom-Scripts ships ~100k tags, which lands around a
+floor of 68.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections import defaultdict
+
+BASE = "https://danbooru.donmai.us"
+# MUST stay in bare `product/version` form. Danbooru sits behind a bot filter
+# that 403s anything else, measured 2026-08-06:
+#
+#     wildcard-pipeline-taglist/1.0                      -> 200
+#     wp-tag-list/1.0                                    -> 200
+#     ComfyUI-Wildcard-Pipeline                          -> 403  (no version)
+#     ComfyUI-Wildcard-Pipeline/1.0                      -> 403
+#     wp-tag-list/1.0 (+https://github.com/DumiFlex/...) -> 403  (URL present)
+#
+# So do NOT "improve" this by adding a contact URL or a longer description.
+# That is the normal courtesy for a scraper and it is exactly what gets this
+# blocked; the version suffix is what makes it acceptable.
+USER_AGENT = "wildcard-pipeline-taglist/1.0"
+PAGE_LIMIT = 1000
+# The API refuses page > 1000 outright (HTTP 410, "You cannot go beyond page
+# 1000"), so this is the ceiling whatever the floor says.
+MAX_PAGE = 1000
+
+
+def fetch(path: str, params: dict[str, str], *, retries: int = 4) -> list[dict]:
+    """GET a JSON array, retrying on transient failures.
+
+    The original script this replaces aborted on the first non-200, which for
+    a 100-request run means one blip discards everything collected so far.
+    """
+    url = f"{BASE}{path}?{urllib.parse.urlencode(params)}"
+    delay = 2.0
+    for attempt in range(retries):
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as err:
+            # 410 is the deep-pagination refusal: retrying cannot help.
+            if err.code == 410:
+                return []
+            if err.code not in (429, 500, 502, 503, 504) or attempt == retries - 1:
+                raise
+        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError):
+            if attempt == retries - 1:
+                raise
+        print(f"  retry in {delay:.0f}s ...", flush=True)
+        time.sleep(delay)
+        delay *= 2
+    return []
+
+
+def fetch_tags(min_count: int, pause: float) -> list[dict]:
+    """Tags ordered by post count, stopping once they fall below `min_count`."""
+    out: list[dict] = []
+    for page in range(1, MAX_PAGE + 1):
+        rows = fetch("/tags.json", {
+            "limit": str(PAGE_LIMIT),
+            "search[hide_empty]": "yes",
+            "search[is_deprecated]": "no",
+            "search[order]": "count",
+            "page": str(page),
+        })
+        if not rows:
+            print(f"  page {page}: empty, stopping", flush=True)
+            break
+        kept = [r for r in rows if r.get("post_count", 0) >= min_count]
+        out.extend(kept)
+        print(
+            f"  page {page:>4}: +{len(kept):>4} "
+            f"(lowest {rows[-1].get('post_count', 0):,})  total {len(out):,}",
+            flush=True,
+        )
+        if len(kept) < len(rows):
+            # Descending order means everything after this point is below the
+            # floor too. Nothing worth having is left.
+            print(f"  reached the floor of {min_count} posts", flush=True)
+            break
+        time.sleep(pause)
+    return out
+
+
+def fetch_aliases(pause: float, max_pages: int) -> dict[str, list[str]]:
+    """`canonical -> [alias, ...]`, from the separate aliases endpoint.
+
+    `tags.json` carries no aliases, and they are what let someone type `hires`
+    and land on `highres` — the single most valuable thing in the file after
+    the names themselves.
+    """
+    mapping: dict[str, list[str]] = defaultdict(list)
+    for page in range(1, max_pages + 1):
+        rows = fetch("/tag_aliases.json", {
+            "limit": str(PAGE_LIMIT),
+            "search[status]": "active",
+            "page": str(page),
+        })
+        if not rows:
+            break
+        for row in rows:
+            antecedent = row.get("antecedent_name")
+            consequent = row.get("consequent_name")
+            if isinstance(antecedent, str) and isinstance(consequent, str):
+                mapping[consequent].append(antecedent)
+        print(f"  aliases page {page:>3}: {len(mapping):,} tags covered", flush=True)
+        time.sleep(pause)
+    return mapping
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument(
+        "--min-count", type=int, default=20,
+        help="stop once tags drop below this many posts (default: 20)",
+    )
+    ap.add_argument("--out", default="wildcard-pipeline-tags.csv")
+    ap.add_argument(
+        "--pause", type=float, default=1.0,
+        help="seconds between requests (default: 1.0)",
+    )
+    ap.add_argument(
+        "--alias-pages", type=int, default=60,
+        help="pages of aliases to fetch (default: 60)",
+    )
+    ap.add_argument("--no-aliases", action="store_true")
+    args = ap.parse_args()
+
+    print(f"Fetching tags with at least {args.min_count} posts ...", flush=True)
+    tags = fetch_tags(args.min_count, args.pause)
+    if not tags:
+        print("No tags fetched — refusing to write an empty list.", file=sys.stderr)
+        return 1
+
+    aliases: dict[str, list[str]] = {}
+    if not args.no_aliases:
+        print("Fetching aliases ...", flush=True)
+        aliases = fetch_aliases(args.pause, args.alias_pages)
+
+    with open(args.out, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        for tag in tags:
+            name = tag.get("name")
+            if not isinstance(name, str) or not name:
+                continue
+            writer.writerow([
+                name,
+                tag.get("category", 0),
+                tag.get("post_count", 0),
+                ",".join(aliases.get(name, [])),
+            ])
+
+    print(
+        f"\nWrote {len(tags):,} tags to {args.out} "
+        f"({sum(len(v) for v in aliases.values()):,} aliases)",
+        flush=True,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/check-bundle-size.mjs

@@ -247,7 +247,46 @@ const ENTRY_LIMIT = 30 * 1024;      // 30 KB
 // previous bump left 179 bytes free, which meant every subsequent change had
 // to argue with the gate. Explicitly approved by the maintainer, who asked for
 // the budget to be raised as needed rather than features trimmed to fit.
-const TOTAL_LIMIT = 490 * 1024;     // 490 KB
+// LOWERED 490 -> 420 KB on 2026-08-06, after the webfonts stopped being bundled.
+// Vite library mode ignores `assetsInlineLimit` and base64-inlined both woff2
+// files into a JS chunk; they are now copied to js/assets/fonts/ and <link>ed at
+// runtime (see src/extension/fonts.ts). Measured 492,407 -> 403,055 bytes.
+//
+// Tightened rather than banked, because the gate is what stops it silently
+// regressing: re-inlining the fonts would add ~90 KB, which fits under 490 KB
+// and would have passed unnoticed. It does not fit under 420 KB. The 17 KB of
+// headroom left is deliberate — enough for ordinary work, not enough to hide a
+// whole asset class coming back.
+// RAISED 420 -> 424 KB on 2026-10-02 for the wildcard fallback option (canvas
+// badge + Debug note): dev sat at 429,971 bytes, 109 under the gate, and the
+// feature needed ~200. Approved by the maintainer ("you are allowed to
+// increase the bundle budget if necessary"). 4 KB leaves room for a few more
+// small features while a re-inlined font (~90 KB) still trips the gate.
+// RAISED 424 -> 428 KB on 2026-10-05 for Context Loop sweep mode (Sweep
+// panel in the loop widget chunk, downstream-wildcard walk in boot): dev sat
+// at 430,134 bytes and the feature adds ~4.8 KB. The maintainer treats this
+// budget as a guide to raise when a needed feature does not fit.
+// RAISED 428 -> 436 KB on 2026-10-06 for model-aware pipelines (WP Model Info
+// walker branches + variant rules + its widget glue in boot, the Model Info
+// widget chunk with pins, Assembler toggles and the shared row-primitive
+// buttons, Match variable control in the wildcard modal chunk, LoRA by model
+// preset): the feature adds ~6 KB and tipped dev ~3.2 KB over. Same "guide,
+// not a cap" rule as above.
+// RAISED 436 -> 440 KB on 2026-10-06 for the constraint "rules out all"
+// warning (the constraint factor math and wildcard pool helpers now reach the
+// ContextWidget chunk): dev sat at 446,313 of 446,464 bytes and the check adds
+// ~2.2 KB. Same "guide, not a cap" rule as above.
+// RAISED 440 -> 452 KB on 2026-10-07 for WP Image Filter (pick-and-pass
+// node): its picker modal (~7.6 KB) and node widget (~3.4 KB) are lazy
+// chunks, plus ~1.5 KB of event + widget glue in boot. dev sat at 448,610
+// bytes. Same "guide, not a cap" rule as above.
+// RAISED 452 -> 464 KB on 2026-10-07 for the Image Filter refine step
+// (frame labels, sweep grid, compare, prompt edits, mask painter, Send to
+// Loop): the picker chunk grows ~8 KB and stays lazy. The branch sat at
+// 462,555 bytes before it. Same "guide, not a cap" rule as above.
+// RAISED 464 -> 468 KB on 2026-10-07 for the zoom's Details panel and the
+// frame-click zoom (lazy picker chunk); the branch sat at 476,239 bytes.
+const TOTAL_LIMIT = 468 * 1024;     // 468 KB
 
 function gzipSize(path) {
   return gzipSync(readFileSync(path)).length;
@@ -259,7 +298,7 @@ function allJsFiles(dir) {
     const full = join(dir, name);
     if (statSync(full).isDirectory()) {
       out.push(...allJsFiles(full));
-    } else if (name.endsWith(".js")) {
+    } else if (name.endsWith(".js") || name.endsWith(".mjs")) {
       out.push(full);
     }
   }
@@ -281,7 +320,9 @@ for (const file of files) {
   // content edit and would otherwise show every chunk as added/removed.
   // Normalize Windows backslashes so the manifest diffs cleanly against
   // CI runs (which always emit forward slashes on Linux).
-  const stable = rel.replace(/-[A-Za-z0-9_-]{8,}\.js$/, ".js").replaceAll("\\", "/");
+  // Lazy chunks are `.mjs` (see vite.config.mts); report them under `.js` so
+  // manifests from before that switch still diff chunk-for-chunk.
+  const stable = rel.replace(/-[A-Za-z0-9_-]{8,}\.m?js$/, ".js").replaceAll("\\", "/");
   manifest.files[stable] = size;
   console.log(`  ${rel.padEnd(40)}  ${(size / 1024).toFixed(2).padStart(7)} KB`);
 }

scripts/copy-fonts.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Copy the webfont directory verbatim from src/assets/fonts/ to
+// js/assets/fonts/, so ComfyUI serves it under
+// /extensions/<package>/assets/fonts/.
+//
+// These files deliberately do NOT go through Vite. Library mode always
+// base64-inlines assets — `build.assetsInlineLimit` is documented as ignored
+// when `build.lib` is set — so a woff2 reachable from the module graph ends up
+// ~33% larger, inside a JS chunk, parsed as JavaScript. Copying sidesteps the
+// bundler entirely; `src/extension/fonts.ts` <link>s the stylesheet at runtime
+// and the browser resolves the woff2 URLs relative to it.
+//
+// Run as part of `pnpm build:extension`, alongside copy-help-docs.mjs.
+
+import { readdirSync, mkdirSync, copyFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const SRC = join(ROOT, "src", "assets", "fonts");
+const DST = join(ROOT, "js", "assets", "fonts");
+
+try {
+  rmSync(DST, { recursive: true, force: true });
+  mkdirSync(DST, { recursive: true });
+  const files = readdirSync(SRC);
+  if (!files.some((f) => f.endsWith(".css"))) {
+    // A missing stylesheet is silent at runtime — the <link> 404s and text
+    // quietly falls back to the system stack. Fail the build instead.
+    throw new Error(`no stylesheet in ${SRC}; fonts.ts expects wp-fonts.css`);
+  }
+  for (const name of files) {
+    copyFileSync(join(SRC, name), join(DST, name));
+    console.log(`  src/assets/fonts/${name} → js/assets/fonts/${name}`);
+  }
+  console.log(`Copied ${files.length} font file(s).`);
+} catch (err) {
+  console.error("[copy-fonts] failed:", err);
+  process.exit(1);
+}

scripts/dump_engine_shapes.py

@@ -61,22 +61,36 @@ _SAMPLES: dict[str, tuple[type, dict]] = {
         {
             "var_binding": "mood",
             "sub_categories": ["soft", "bold"],
+            # Tag axes: an `accepts` group must survive the round-trip, so the
+            # sample carries both the group map and its kind. A stripped
+            # tag_group_kinds silently degrades the axis to classify.
+            "tag_groups": {"TEXTURE": ["soft", "bold"]},
+            "tag_group_kinds": {"TEXTURE": "accepts"},
             "options": [
-                {"id": "opt00001", "value": "serene", "weight": 1, "sub_category": "soft"},
+                # `negative` (send-to-negative, v8) must survive the
+                # strict validator like the value does.
+                {"id": "opt00001", "value": "serene", "weight": 1, "sub_categories": ["soft"],
+                 "negative": "angry, tense"},
                 # Null option: the is_null contract. Must round-trip
                 # through the validator or install rebuilds it as an
                 # invalid empty-value option.
-                {"id": "opt00002", "value": "", "weight": 1, "sub_category": None, "is_null": True},
+                {"id": "opt00002", "value": "", "weight": 1, "sub_categories": [], "is_null": True},
+                # Fallback (v9): the flag must survive the strict validator,
+                # or a shared pack's fallback rolls like any other option.
+                {"id": "opt00003", "value": "calm", "weight": 1, "sub_categories": [],
+                 "fallback": True},
             ],
         },
     ),
     "fixed_values": (
         FixedValuesHandler,
-        {"values": [{"id": "val00001", "name": "style", "value": "oil painting"}]},
+        {"values": [{"id": "val00001", "name": "style", "value": "oil painting",
+                     "negative": "photo, 3d render"}]},
     ),
     "combine": (
         CombineHandler,
-        {"template": "$mood $subject", "output_var": "scene", "input_vars": ["mood", "subject"]},
+        {"template": "$mood $subject", "output_var": "scene", "input_vars": ["mood", "subject"],
+         "negative": "cropped"},
     ),
     "derivation": (
         DerivationHandler,
@@ -93,12 +107,20 @@ _SAMPLES: dict[str, tuple[type, dict]] = {
                                 "target_var": "accent", "mode": "replace",
                                 "value": "cinematic lighting",
                             },
+                            # THEN ... AND ... (v8): runs after `action`.
+                            "extra_actions": [
+                                {
+                                    "target_var": "accent", "mode": "negative",
+                                    "value": "$mood.neg",
+                                },
+                            ],
                         },
                     ],
                     "else": {
+                        # "Add to negative" (v8): writes no value.
                         "action": {
-                            "target_var": "accent", "mode": "replace",
-                            "value": "soft lighting",
+                            "target_var": "accent", "mode": "negative",
+                            "value": "harsh shadows",
                         },
                     },
                 },
@@ -112,6 +134,9 @@ _SAMPLES: dict[str, tuple[type, dict]] = {
             "target_wildcard_id": "tgt00001",
             "exceptions": [],
             "matrix": {"soft": {"bold": {"mode": "boost", "factor": 3}}},
+            # SP3 reach selector — must survive the round-trip, not strip back
+            # to the {mode: "all"} default.
+            "target_select": {"mode": "next", "count": 2},
         },
     ),
 }

scripts/write-asset-manifest.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Record exactly which files a clean build produced, so the plugin can delete
+// everything else on the next ComfyUI start.
+//
+// WHY THIS EXISTS. Our chunks are content-hashed, so every release emits new
+// filenames. ComfyUI Manager updates by extracting the new package OVER the
+// installed folder — it never removes files the new version dropped. The two
+// behaviours are individually reasonable and together they leak: measured on a
+// real 2.13.1 install (2026-08-06), `js/` held 237 chunks where 58 were live
+// and `web/` held 1,256 files where 136 were, for 54.6 MB total.
+//
+// It goes unnoticed in development because `emptyOutDir` wipes the output
+// directory on every local build. Only installs that UPDATE accumulate.
+//
+// The manifest lists paths relative to the directory it sits in. Written last,
+// after the copy steps, so it captures docs and fonts as well as chunks.
+//
+// Usage: node scripts/write-asset-manifest.mjs <dir>
+
+import { readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const target = process.argv[2];
+if (!target) {
+  console.error("usage: write-asset-manifest.mjs <dir>   (e.g. js, web)");
+  process.exit(1);
+}
+
+const dir = join(ROOT, target);
+const MANIFEST = ".wp-assets.json";
+
+function walk(current) {
+  const out = [];
+  for (const name of readdirSync(current)) {
+    const full = join(current, name);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+try {
+  const files = walk(dir)
+    // Always use forward slashes: the manifest is written on whatever machine
+    // builds the release and read on the user's, which may not be the same OS.
+    .map((p) => relative(dir, p).split(sep).join("/"))
+    .filter((p) => p !== MANIFEST)
+    .sort();
+  writeFileSync(
+    join(dir, MANIFEST),
+    `${JSON.stringify({ files }, null, 0)}\n`,
+    "utf8",
+  );
+  console.log(`  ${target}/${MANIFEST} — ${files.length} files recorded`);
+} catch (err) {
+  console.error("[write-asset-manifest] failed:", err);
+  process.exit(1);
+}

src/assets/fonts/wp-fonts.css

@@ -0,0 +1,56 @@
+/* Webfonts for the canvas extension — JetBrains Mono, latin subset,
+ * variable axis 100-900.
+ *
+ * NO INTER HERE, deliberately. ComfyUI's own frontend serves an Inter that is
+ * identical to the one we used to ship — same family name, same
+ * `font-weight: 100 900` variable axis, same latin woff2, same
+ * `font-display: swap` — and it declares it in its MAIN stylesheet, so it is
+ * already loaded on every page a canvas widget can appear on. We were shipping
+ * and downloading a 48 KB duplicate.
+ *
+ * The coupling this creates is on the FAMILY NAME, not on their URL: our
+ * `--wp-font-sans` stack names `Inter` and the browser resolves it against
+ * whatever `Inter` face is loaded, so their file being renamed, re-subset or
+ * re-hashed is invisible to us. Their copy also lives in `public/fonts/`,
+ * which Vite serves un-hashed precisely so the URL stays stable — hashed
+ * assets go to `assets/`.
+ *
+ * Evidence for the bet, since "rely on a host asset" deserves some: added
+ * 2025-09-16 in Comfy-Org/ComfyUI_frontend 4ff18fd ("Add Inter font used by
+ * Figma designs", #5535) and untouched since — one commit in its whole
+ * history. It is the typeface of their entire UI, so removing it means
+ * restyling their product, not dropping an optional extra.
+ *
+ * And if they do remove it, nothing breaks loudly: the stack falls through to
+ * `-apple-system, Segoe UI, Roboto, sans-serif`, which is the behaviour
+ * `font-display: swap` already shows during every cold load.
+ *
+ * JetBrains Mono stays. ComfyUI ships no monospace face.
+ *
+ * This file is NOT processed by Vite. `scripts/copy-fonts.mjs` copies this
+ * directory verbatim into `js/assets/fonts/`, and `src/extension/fonts.ts`
+ * injects a <link> to it at runtime.
+ *
+ * Why not an import: Vite library mode ALWAYS base64-inlines assets and
+ * ignores `build.assetsInlineLimit` entirely, so any woff2 reachable from a
+ * module graph becomes ~33% larger and lands inside a JS chunk — parsed as
+ * JavaScript, re-downloaded whenever that chunk's hash changes, and counted
+ * against the bundle-size gate. Keeping the fonts outside the graph is the
+ * only way to ship them as fonts.
+ *
+ * The `src` URLs below are relative to THIS FILE, so the browser resolves
+ * them against the stylesheet's own location. No path arithmetic in JS.
+ *
+ * font-display: swap renders the system stack first and re-paints when the
+ * woff2 lands, so text is never invisible during the fetch.
+ */
+
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src:
+    url("./jetbrains-mono-latin.woff2") format("woff2-variations"),
+    url("./jetbrains-mono-latin.woff2") format("woff2");
+}

src/boot.ts

@@ -0,0 +1,62 @@
+// Everything `main.ts` needs before it can call `registerExtension`, gathered
+// behind ONE dynamic import so it ships as one chunk.
+//
+// WHY ONE CHUNK. `main.ts` used to `await Promise.all([...])` nineteen separate
+// `import()`s. Each became its own chunk, and every module two of them shared
+// (vue, `_shared`, `graph`, `reactive`, `graph-events`, …) became a chunk of
+// its own too, so an empty canvas fetched 43 files before the extension could
+// register. All of them were awaited up front anyway: nothing was actually
+// deferred, it was just split. Importing them from here lets Rollup put them in
+// a single chunk, and the lazy chunks (the widget SFCs, modals) import from it
+// because it is guaranteed to be loaded before they are.
+//
+// WHY IT STILL HAS TO BE AWAITED. `getCustomWidgets` factories must return
+// synchronously, so the widget glue has to be loaded before the first node is
+// built. ComfyUI does accept a Promise from `getCustomWidgets`, but it does not
+// wait for it (`extensionService.registerExtension` fires it and moves on,
+// marked for deprecation), so a workflow restored at startup could build its
+// nodes first. And `init`, the earliest hook ComfyUI does await, runs right
+// after extension loading, so moving the await there would buy nothing.
+//
+// Keep this list to what registration or node creation needs. Anything only a
+// user action reaches (a modal, the toast stack, the subgraph badge) belongs in
+// its own `import()` so it stays off the startup path. The widget SFCs are
+// already lazy through `defineAsyncComponent` in each `widgets/*.ts`.
+// Webfonts. The module only appends a <link> for the @font-face rules and
+// `font-display: swap` renders text in the system stack until they land, so
+// nothing here waits on a font. It resolves the stylesheet against its own
+// chunk's URL, which is `assets/` whether it ships alone or inside this chunk.
+import "./extension/fonts";
+
+export * as ctxMod from "./widgets/context";
+export * as dbgMod from "./widgets/debug";
+export * as asmMod from "./widgets/assembler";
+export * as tmplMod from "./widgets/templateEditor";
+export * as injMod from "./widgets/injector";
+export * as cleanerMod from "./widgets/cleaner";
+export * as varPickerMod from "./widgets/var_picker";
+export * as ctxLoopMod from "./widgets/context_loop";
+export * as seedListMod from "./widgets/seed_list";
+export * as modelInfoMod from "./widgets/model_info";
+export * as imageFilterWidgetMod from "./widgets/image_filter";
+export * as imageFilterMod from "./extension/image-filter";
+export * as graphEventsMod from "./extension/graph-events";
+export * as graphMod from "./extension/graph";
+export * as assemblerVarsMod from "./extension/assembler-vars";
+export * as toastStoreMod from "./components/shared/toast-store";
+export * as settingsMod from "./extension/settings";
+export * as aboutMod from "./extension/about-badges";
+export * as topbarMod from "./extension/topbar";
+export * as playgroundStoreMod from "./components/settings/playground-store";
+export { installClipboardShield } from "./widgets/clipboard-shield";
+export { dimWidgetsWhileSkipped } from "./extension/reactive";
+export { createApp, watch } from "vue";
+
+// Off the startup path, but imported from here rather than from `main.ts`: a
+// chunk loaded from this one can reuse everything this one already holds (vue,
+// the stores, `reactive`), whereas one loaded from `main.ts` makes Rollup split
+// those shared modules back out into files of their own.
+export const loadToast = () => import("./components/shared/Toast.vue");
+export const loadPlayground = () => import("./components/settings/DisplayPlaygroundModal.vue");
+export const loadSubgraphBadge = () => import("./extension/subgraph-badge");
+export const loadImageFilterPicker = () => import("./components/image-filter/PickerHost.vue");

src/components/assembler/AssemblerHelper.test.ts

@@ -452,3 +452,78 @@ describe("AssemblerHelper var-color rendering", () => {
     expect(wrapper.find('[data-test="asm-save-template"]').attributes("disabled")).toBeDefined();
   });
 });
+
+describe("AssemblerHelper $var.AXIS preview (tag axes)", () => {
+  const base = {
+    upstreamVars: ["outfit", "shoes"],
+    templateVars: ["outfit", "shoes"],
+    resolvedMap: { outfit: "robe", shoes: "red stilettos" },
+    varAxes: { outfit: { SHOES: "sandals" } },
+  };
+  const preview = (props: Record<string, unknown>) =>
+    mount(AssemblerHelper, { props: { ...base, ...props } as never })
+      .find('[data-test="asm-preview"]').text();
+
+  it("reads the tag the preview run rolled, not the axis's first tag", () => {
+    expect(preview({
+      template: "$outfit.SHOES | $outfit",
+      resolvedMap: { outfit: "summer dress", shoes: "red stilettos" },
+      rolledAxes: { outfit: { SHOES: "heels" } },
+    })).toBe("heels | summer dress");
+  });
+
+  it("renders empty when the picked option carries no tag on the axis", () => {
+    // The reported preview: "sandals | robe" while the prompt said "| robe".
+    expect(preview({ template: "$outfit.SHOES | $outfit", rolledAxes: { outfit: {} } }))
+      .toBe("| robe");
+  });
+
+  it("guesses the first tag only until the preview run answers", () => {
+    expect(preview({ template: "$outfit.SHOES" })).toBe("sandals");
+  });
+
+  it("keeps an undeclared axis raw so the gap stays visible", () => {
+    expect(preview({ template: "$outfit.BELTS", rolledAxes: { outfit: {} } }))
+      .toBe("$outfit.BELTS");
+  });
+
+  it("indexes a multi-pick positionally in either accessor order", () => {
+    const rolledAxes = { outfit: [{}, { SHOES: "boots" }] };
+    expect(preview({ template: "[$outfit.0.SHOES] [$outfit.1.SHOES] [$outfit.SHOES.1]", rolledAxes }))
+      .toBe("[] [boots] [boots]");
+    expect(preview({ template: "$outfit.SHOES", rolledAxes })).toBe("boots");
+  });
+});
+
+describe("AssemblerHelper negative preview", () => {
+  const base = {
+    upstreamVars: ["hair", "mood"],
+    resolvedMap: { hair: "red hair", mood: "happy" },
+    negatives: {
+      hair: [{ text: "blonde, lowres", pick: null }],
+      mood: [{ text: "sad", pick: null }],
+    },
+  };
+
+  it("builds the line from the variables the prompt uses, at $negatives", () => {
+    const wrapper = mount(AssemblerHelper, {
+      props: { ...base, template: "$hair", negativeTemplate: "lowres, not $mood, $negatives" },
+    });
+    const line = wrapper.find('[data-test="asm-neg-preview"]');
+    // $mood is only in the NEGATIVE template: its value, never its negatives.
+    expect(line.text()).toBe("lowres, not happy, blonde");
+    expect(wrapper.find('[data-test="asm-neg-count"]').text()).toBe("1 from variables");
+    expect(line.find(`.${varColorClass("hair")}`).text()).toBe("blonde");
+  });
+
+  it("empty negative template is just the words; hidden when nothing to show", () => {
+    const shown = mount(AssemblerHelper, {
+      props: { ...base, template: "$hair, $mood", negativeTemplate: "" },
+    });
+    expect(shown.find('[data-test="asm-neg-preview"]').text()).toBe("blonde, lowres, sad");
+    const hidden = mount(AssemblerHelper, {
+      props: { ...base, template: "a portrait", negativeTemplate: "" },
+    });
+    expect(hidden.find('[data-test="asm-neg-preview"]').exists()).toBe(false);
+  });
+});

src/components/assembler/AssemblerHelper.vue

@@ -1,9 +1,17 @@
 <script setup lang="ts">
 import { computed, ref, watch } from "vue";
 import { varColorClass } from "../shared/var-color";
+import { modelSyntaxHtml } from "../../widgets/richTokenize";
+import { buildNegativePreview, type NegativesTable } from "../../extension/negatives";
 import ContextMenu, { type ContextMenuItem } from "../shared/ContextMenu.vue";
 import { kindIcon, type WpKind } from "../shared/kind-icons";
-import { applyVarAccessor, type ResolvedValue } from "../../widgets/richTokenize";
+import {
+  applyVarAccessor,
+  readRolledAxis,
+  varAccessorParts,
+  type ResolvedValue,
+  type RolledAxes,
+} from "../../widgets/richTokenize";
 
 const props = defineProps<{
   /** Flat array of upstream variable names. Primary prop shape. */
@@ -17,6 +25,16 @@ const props = defineProps<{
    * precedence over `resolved`.
    */
   resolvedMap?: Record<string, ResolvedValue>;
+  /** `{ varName: { AXIS: firstTag } }`. A `$var.AXIS` read resolves against
+   *  this, never against `resolvedMap` — the axis names a tag menu, not the
+   *  variable's text. */
+  varAxes?: Record<string, Record<string, string>>;
+  /** What the preview run actually rolled, keyed by binding (the preview
+   *  endpoint's `axes`). Preferred over `varAxes` for any axis the chain
+   *  declares, because `varAxes` only knows the axis's first tag — it printed
+   *  "sandals" beside an option with no shoes and beside a pick whose
+   *  constrained target had rolled heels. */
+  rolledAxes?: Record<string, RolledAxes>;
   /**
    * Pre-resolved string — template with $var replaced by resolved values.
    * Legacy fallback when `resolvedMap` not provided. Suffers from
@@ -25,6 +43,11 @@ const props = defineProps<{
    */
   resolved?: string;
   template: string;
+  /** Send-to-negative: the node's `negative_template` value. */
+  negativeTemplate?: string;
+  /** Each variable's negatives (`{binding: [{text, pick}]}`) from the
+   *  preview run, injector rows already folded in. */
+  negatives?: NegativesTable;
   onInsert?: (token: string) => void;
   /** Strip every occurrence of `$varname` from the template. Wired
    *  to the UNRESOLVED chips so users can one-click drop a name
@@ -85,7 +108,12 @@ const VAR_RE = /\$([A-Za-z_][A-Za-z0-9_]*)/g;
 // SP2a: capture an optional `.K` list accessor (group 2) so `$mood.0` consumes
 // the whole token — `m[0].length` then advances past `.K` (no stranded ".0"
 // literal) and group 2 drives applyVarAccessor in the substitution below.
-const TEMPLATE_VAR_RE = /(?<!\$)\$([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?/g;
+// Groups: 1=name · 2=index · 3=axis. The accessor has to be part of the match
+// or the preview prints the resolved value and strands ".SHOES" after it.
+// Both accessor orders the engine accepts (`$o.0.SHOES`, `$o.SHOES.0`); the
+// match is re-split by `varAccessorParts`, the one canonical grammar.
+const TEMPLATE_VAR_RE =
+  /(?<!\$)\$([A-Za-z_][A-Za-z0-9_]*)(?:\.(?:\d+(?:\.[A-Za-z_][A-Za-z0-9_]*)?|[A-Za-z_][A-Za-z0-9_]*(?:\.\d+)?))?/g;
 
 /** Variable names referenced in the template. */
 const templateVarsInternal = computed(() => {
@@ -134,6 +162,22 @@ watch(
 
 interface PreviewToken { kind: "literal" | "var"; text: string; varName?: string }
 
+/** An axis read resolves to a TAG. Falling through to the value is what
+ *  rendered "a white t-shirt and denim skirt.SHOES". An axis the chain does not
+ *  declare stays raw so the gap is visible rather than silently dropped; a
+ *  declared one reads what the preview run rolled (empty when the picked
+ *  option carries no tag on it, exactly as the prompt will), and only guesses
+ *  the axis's first tag until that run has answered. */
+function axisText(name: string, axis: string, index: number | undefined, raw: string): string {
+  const guess = props.varAxes?.[name]?.[axis];
+  if (guess === undefined) return raw;
+  const rolled = props.rolledAxes;
+  if (rolled && Object.prototype.hasOwnProperty.call(rolled, name)) {
+    return readRolledAxis(rolled[name], axis, index);
+  }
+  return index != null && index > 0 ? "" : guess;
+}
+
 const previewTokens = computed<PreviewToken[]>(() => {
   if (!props.template) return [];
 
@@ -145,17 +189,14 @@ const previewTokens = computed<PreviewToken[]>(() => {
     for (const m of props.template.matchAll(TEMPLATE_VAR_RE)) {
       const idx = m.index ?? 0;
       if (idx > last) tokens.push({ kind: "literal", text: props.template.slice(last, idx) });
-      const name = m[1];
-      const idxStr = m[2];
-      const index = idxStr != null ? parseInt(idxStr, 10) : undefined;
+      const raw = m[0];
+      const { base: name, index, axis } = varAccessorParts(raw);
       const has = Object.prototype.hasOwnProperty.call(props.resolvedMap, name);
-      // Resolved → join (bare $name) or index (.K) via the shared accessor;
-      // unresolved → keep the raw `$name.K` so the user sees what's missing.
       tokens.push({
         kind: "var",
-        text: has
-          ? applyVarAccessor(props.resolvedMap[name], index)
-          : `$${name}${idxStr != null ? "." + idxStr : ""}`,
+        text: axis
+          ? axisText(name, axis, index, raw)
+          : (has ? applyVarAccessor(props.resolvedMap[name], index) : raw),
         varName: name,
       });
       last = idx + m[0].length;
@@ -221,6 +262,41 @@ const previewTokens = computed<PreviewToken[]>(() => {
   return [];
 });
 
+// ---------------------------------------------------------------------------
+// Negative preview (send-to-negative)
+// ---------------------------------------------------------------------------
+
+/** Render text's `$vars` the way the prompt preview does (value, index,
+ *  axis); a variable with no value renders nothing, as in the engine. */
+function renderVarsRaw(text: string): string {
+  const map = props.resolvedMap ?? {};
+  return text.replace(TEMPLATE_VAR_RE, (raw) => {
+    const { base, index, axis } = varAccessorParts(raw);
+    if (axis) {
+      const out = axisText(base, axis, index, raw);
+      return out === raw ? "" : out;
+    }
+    return Object.prototype.hasOwnProperty.call(map, base) ? applyVarAccessor(map[base], index) : "";
+  });
+}
+
+/** What the node's `negative` output will be, built locally from the
+ *  negatives of the variables the PROMPT template uses. */
+const negPreview = computed(() =>
+  buildNegativePreview({
+    template: props.template,
+    negativeTemplate: props.negativeTemplate ?? "",
+    resolved: props.resolvedMap ?? {},
+    negatives: props.negatives ?? {},
+    resolveRaw: renderVarsRaw,
+  }),
+);
+
+/** Only worth a row when there is something to show. */
+const showNegative = computed(
+  () => negPreview.value.text !== "" || (props.negativeTemplate ?? "").trim() !== "",
+);
+
 const isResolved = computed(() => {
   if (props.resolvedMap !== undefined) return Object.keys(props.resolvedMap).length > 0;
   return Boolean(props.resolved);
@@ -396,7 +472,6 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
             @click="onLoadTemplate"
           >
             <i class="pi pi-folder-open" aria-hidden="true" />
-            <span>Load</span>
           </button>
           <button
             v-if="onSaveTemplate"
@@ -409,7 +484,6 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
             @click="onSaveTemplate"
           >
             <i class="pi pi-save" aria-hidden="true" />
-            <span>Save</span>
           </button>
           <button
             v-if="onClearTemplate"
@@ -422,7 +496,6 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
             @click="onClearTemplate"
           >
             <i class="pi pi-trash" aria-hidden="true" />
-            <span>Clear template</span>
           </button>
         </div>
         <span class="wp-asm-section-stat">
@@ -490,18 +563,47 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
           </div>
           <div v-else key="tokens" class="wp-asm-preview__tokens">
             <template v-for="(tok, i) in previewTokens" :key="i">
-              <span v-if="tok.kind === 'literal'" class="literal">{{ tok.text }}</span>
+              <!-- Literal preview text still carries `<lora:…>` and
+                   `embedding:…`, which resolve to themselves rather than to a
+                   variable — so without this they were the only place the two
+                   syntaxes appeared uncoloured. Same function the editor uses,
+                   so the two cannot drift; it escapes everything it emits. -->
+              <span
+                v-if="tok.kind === 'literal'"
+                class="literal"
+                v-html="modelSyntaxHtml(tok.text)"
+              ></span>
               <span v-else :class="['res', varColorClass(tok.varName ?? '')]">{{ tok.text }}</span>
             </template>
           </div>
         </Transition>
       </div>
 
-      <!-- hint -->
-      <div class="wp-asm-hint">
-        <span>click → insert <kbd>$var</kbd> · <kbd>Ctrl</kbd>+click → remove · right-click → more</span>
-        <span style="margin-left: auto;">click missing → remove</span>
-      </div>
+      <template v-if="showNegative">
+        <div class="wp-asm-section">
+          <span>negative preview</span>
+          <span
+            v-if="negPreview.fromVars.length"
+            class="wp-asm-section-stat wp-asm-section-stat--neg"
+            data-test="asm-neg-count"
+          >{{ negPreview.fromVars.length }} from variables</span>
+        </div>
+        <div class="wp-asm-preview wp-asm-preview--neg" data-test="asm-neg-preview">
+          <span v-if="!negPreview.text" class="wp-asm-preview__ghost">
+            No negatives: none of the variables the prompt uses carries one.
+          </span>
+          <template v-for="(tag, i) in negPreview.tags" v-else :key="i">
+            <span v-if="i > 0" class="literal">, </span>
+            <span
+              v-if="tag.varName"
+              :class="['res', varColorClass(tag.varName)]"
+              :title="`from $${tag.varName}`"
+            >{{ tag.text }}</span>
+            <span v-else class="literal">{{ tag.text }}</span>
+          </template>
+        </div>
+      </template>
+
       </div>
     </Transition>
 
@@ -550,6 +652,12 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
 }
 .wp-asm-section-stat--warn { color: var(--wp-warn); }
 .wp-asm-section-stat.is-ok { color: var(--wp-green); }
+.wp-asm-section-stat--neg {
+  padding: 2px 6px;
+  border-radius: 3px;
+  color: var(--wp-danger);
+  background: color-mix(in srgb, var(--wp-danger) 14%, transparent);
+}
 
 /* Toolbar buttons (Load / Save / Clear) — sit in the variables
  * section header, centered between the label and the upstream-count
@@ -588,11 +696,15 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
   gap: 6px;
   justify-content: center;
 }
+/* Icon-only. Each button already carried a `title` and an `aria-label`, so the
+   visible word was the only thing dropped — and three words across the row
+   were most of its width. Square-ish padding keeps the tap target honest. */
 .wp-asm-toolbtn {
   display: inline-flex;
   align-items: center;
+  justify-content: center;
   gap: 6px;
-  padding: 3px 10px;
+  padding: 4px 7px;
   background: var(--wp-bg-deep, var(--wp-bg));
   border: 1px solid var(--wp-border);
   border-radius: 3px;
@@ -665,8 +777,11 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
 .wp-asm-vars {
   display: flex;
   flex-wrap: wrap;
-  gap: 4px;
-  padding: 6px;
+  /* On the project's own spacing scale rather than the bare 4/6 they were.
+     At 4px the chips ran together into one block of texture — the strip read
+     as a single control instead of a row of separate variables. */
+  gap: var(--wp-space-3);
+  padding: var(--wp-space-4);
   background: var(--wp-bg-deep, var(--wp-bg));
   border: 1px solid var(--wp-border);
   border-radius: var(--wp-radius);
@@ -729,6 +844,12 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
 }
 .wp-asm-preview .literal { color: var(--wp-text); }
 .wp-asm-preview .res { font-weight: 600; }
+/* Negative preview: same frame, negative accent. */
+.wp-asm-preview--neg {
+  border-color: color-mix(in srgb, var(--wp-danger) 35%, var(--wp-border));
+}
+.wp-asm-preview--neg .wp-asm-preview__ghost { font-style: italic; }
+
 /* Tokens wrapper is a block `<div>` (not inline, not display:contents)
  * so the Vue Transition can apply transform/opacity to it. Inline
  * elements ignore transform per CSS spec; `display: contents` makes
@@ -774,22 +895,4 @@ function openChipMenu(ev: MouseEvent, v: string, isMissing: boolean): void {
 }
 .wp-asm-preview__ghost-text { display: inline; }
 
-.wp-asm-hint {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  margin-top: 4px;
-  font: 11px/1.3 var(--wp-font-sans);
-  color: var(--wp-text-dim);
-}
-.wp-asm-hint kbd {
-  background: var(--wp-bg-1);
-  border: 1px solid var(--wp-border-soft);
-  border-bottom-width: 2px;
-  border-radius: 2px;
-  font: 10px/1 var(--wp-font-mono);
-  padding: 1px 4px;
-  color: var(--wp-text-muted);
-}
-
 </style>

src/components/assembler/LoadTemplateModal.test.ts

@@ -65,6 +65,23 @@ describe("LoadTemplateModal", () => {
     expect(w.find('[data-test="load-tpl-filter-trigger"]').exists()).toBe(true);
   });
 
+  it("shows a saved negative under the template", async () => {
+    const { api } = await import("../../manager/api/client");
+    (api.templates.list as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      items: [{
+        id: "n1", name: "neg", description: "", category_id: null, tags: [],
+        is_favorite: false, template_string: "$x", negative_template: "lowres, $negatives",
+        created_at: "", updated_at: "",
+      }],
+      total: 1,
+    });
+    const w = mount(LoadTemplateModal, { props: { open: true }, ...stubs });
+    await flushPromises();
+    expect(w.find('[data-test="load-tpl-row-neg"]').text()).toBe("neg: lowres, $negatives");
+    await w.find('[data-test="load-tpl-row"]').trigger("click");
+    expect(w.emitted("pick")?.[0]?.[0]).toMatchObject({ negative_template: "lowres, $negatives" });
+  });
+
   it("shows empty state when none", async () => {
     const { api } = await import("../../manager/api/client");
     (api.templates.list as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ items: [], total: 0 });

src/components/assembler/LoadTemplateModal.vue

@@ -253,6 +253,12 @@ function pick(row: TemplateRow) {
                 <i v-if="row.is_favorite" class="pi pi-star-fill wp-ltm__row-fav" aria-hidden="true" />
               </span>
               <span class="wp-ltm__row-preview" :title="row.template_string">{{ row.template_string || "(empty)" }}</span>
+              <span
+                v-if="row.negative_template"
+                class="wp-ltm__row-preview wp-ltm__row-preview--neg"
+                data-test="load-tpl-row-neg"
+                :title="row.negative_template"
+              >neg: {{ row.negative_template }}</span>
             </span>
             <span v-if="row.category_id && categoryNameById.get(row.category_id)" class="wp-ltm__row-cat">
               {{ categoryNameById.get(row.category_id) }}
@@ -505,6 +511,7 @@ function pick(row: TemplateRow) {
   color: var(--wp-text-muted);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
 }
+.wp-ltm__row-preview--neg { color: color-mix(in srgb, var(--wp-danger) 75%, var(--wp-text-muted)); }
 .wp-ltm__row-cat {
   font-size: 10px;
   color: var(--wp-text-dim);

src/components/assembler/NegativeTemplateBox.vue

@@ -0,0 +1,139 @@
+<script setup lang="ts">
+/**
+ * The Assembler's `negative_template` box: the same editor as the prompt
+ * template behind a collapsible header, with the negative (danger) accent.
+ *
+ * Heights are fixed on purpose (header 30px, open box 100px, both on the
+ * LiteGraph 10px grid) so the mount glue can report an exact content height
+ * and the node gives every spare pixel to the prompt editor above instead of
+ * leaving a dead band here.
+ */
+import { computed, defineAsyncComponent } from "vue";
+import type { VarProducer } from "../../extension/graph";
+
+const RichTextInput = defineAsyncComponent(() => import("../../manager/components/RichTextInput.vue"));
+
+const props = defineProps<{
+  modelValue: string;
+  collapsed: boolean;
+  /** Driven by a STRING link: read-only, like the prompt template. */
+  linked: boolean;
+  varSuggestions: string[];
+  varProducers: Map<string, VarProducer>;
+}>();
+
+const emit = defineEmits<{
+  (e: "update:modelValue", v: string): void;
+  (e: "toggle"): void;
+}>();
+
+/** One-line summary shown in the collapsed header. */
+const summary = computed(() => {
+  if (props.linked) return "driven by the connected input";
+  const t = props.modelValue.trim().replace(/\s+/g, " ");
+  return t || "empty: just the variables' negatives";
+});
+</script>
+
+<template>
+  <div
+    class="wp-negbox"
+    :class="{ 'wp-negbox--collapsed': collapsed }"
+    data-test="neg-template-box"
+  >
+    <button
+      type="button"
+      class="wp-negbox__head"
+      :aria-expanded="!collapsed"
+      aria-controls="wp-negbox-body"
+      data-test="neg-template-toggle"
+      :title="collapsed ? 'Show the negative template' : 'Hide the negative template'"
+      @click="emit('toggle')"
+    >
+      <i
+        :class="['pi', collapsed ? 'pi-chevron-right' : 'pi-chevron-down', 'wp-negbox__chev']"
+        aria-hidden="true"
+      />
+      <span class="wp-negbox__label">negative</span>
+      <span v-if="collapsed" class="wp-negbox__summary" data-test="neg-template-summary">{{ summary }}</span>
+      <span v-else-if="linked" class="wp-negbox__summary">driven by the connected input</span>
+    </button>
+    <div v-if="!collapsed" class="wp-negbox__body">
+      <RichTextInput
+        :model-value="modelValue"
+        surface="assembler"
+        multiline
+        :rows="2"
+        fill
+        :placeholder="linked
+          ? 'Driven by the connected input — disconnect it to edit here.'
+          : '$negatives'"
+        :disabled="linked"
+        :var-suggestions="varSuggestions"
+        :var-producers="varProducers"
+        graph-aware
+        aria-label="Negative template"
+        @update:model-value="(v: string) => emit('update:modelValue', v)"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* Tokens (`--wp-*`) resolve from the theme the Assembler helper already
+   loads; not @imported here so this chunk stays small (bundle gate). */
+.wp-negbox {
+  display: flex;
+  flex-direction: column;
+  height: 100px;
+  box-sizing: border-box;
+  padding: 0 6px;
+  font-family: var(--wp-font-sans);
+  color: var(--wp-text);
+}
+.wp-negbox--collapsed { height: 30px; }
+.wp-negbox__head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  height: 26px;
+  flex: 0 0 26px;
+  min-width: 0;
+  padding: 0 2px;
+  border: 0;
+  background: transparent;
+  color: var(--wp-danger);
+  font: 500 11px/1 var(--wp-font-sans);
+  text-transform: lowercase;
+  cursor: pointer;
+  text-align: left;
+}
+.wp-negbox__head:focus-visible {
+  outline: 1px solid var(--wp-danger);
+  outline-offset: 1px;
+}
+.wp-negbox__chev { font-size: 9px; }
+.wp-negbox__summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--wp-text-dim);
+  font: 11px/1 var(--wp-font-mono);
+  text-transform: none;
+}
+.wp-negbox__body {
+  flex: 1 1 0%;
+  min-height: 0;
+  padding-bottom: 4px;
+}
+/* Negative accent on the editor frame. The editor is a child component, so
+   reach its root through :deep(). */
+.wp-negbox__body :deep(.wp-rt) {
+  border-color: color-mix(in srgb, var(--wp-danger) 45%, var(--wp-border));
+  background: color-mix(in srgb, var(--wp-danger) 6%, var(--wp-bg-2, var(--wp-bg)));
+}
+.wp-negbox__body :deep(.wp-rt.wp-rt--focused) { border-color: var(--wp-danger); }
+.wp-negbox__body :deep(.wp-rt__host--multi) { min-height: 0; }
+</style>

src/components/assembler/SaveTemplateModal.test.ts

@@ -93,4 +93,34 @@ describe("SaveTemplateModal", () => {
     expect(api.templates.create).toHaveBeenCalled();
     expect(api.templates.update).not.toHaveBeenCalled();
   });
+
+  it("stores both boxes; an empty negative box saves as an empty string", async () => {
+    const { api } = await import("../../manager/api/client");
+    const create = api.templates.create as ReturnType<typeof vi.fn>;
+    create.mockClear();
+    const w = mount(SaveTemplateModal, {
+      props: { open: true, templateString: "$a", negativeTemplate: "lowres, $negatives" },
+      ...stubs,
+    });
+    await flushPromises();
+    expect(w.find('[data-test="save-tpl-neg-preview"]').text()).toBe("lowres, $negatives");
+    const input = w.find<HTMLInputElement>('[data-test="save-tpl-name"]');
+    input.element.value = "both";
+    await input.trigger("input");
+    await w.find('[data-test="save-tpl-submit"]').trigger("click");
+    await flushPromises();
+    expect(create).toHaveBeenLastCalledWith(expect.objectContaining({
+      template_string: "$a", negative_template: "lowres, $negatives",
+    }));
+
+    const w2 = mount(SaveTemplateModal, { props: { open: true, templateString: "$a" }, ...stubs });
+    await flushPromises();
+    expect(w2.find('[data-test="save-tpl-neg-preview"]').exists()).toBe(false);
+    const input2 = w2.find<HTMLInputElement>('[data-test="save-tpl-name"]');
+    input2.element.value = "blank";
+    await input2.trigger("input");
+    await w2.find('[data-test="save-tpl-submit"]').trigger("click");
+    await flushPromises();
+    expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ negative_template: "" }));
+  });
 });

src/components/assembler/SaveTemplateModal.vue

@@ -7,6 +7,10 @@ import { pushToast } from "../shared/toast-store";
 const props = defineProps<{
   open: boolean;
   templateString: string;
+  /** The Assembler's negative box. Saved alongside the prompt template
+   *  (an empty box saves as "", which loading applies; only templates saved
+   *  before negatives existed carry none). */
+  negativeTemplate?: string;
   /** Library identity of the template this assembler loaded, if any.
    *  Pre-fills the name and makes "Update existing" target that exact
    *  row even before the same-name collision map resolves. */
@@ -67,6 +71,7 @@ async function submit(mode: "update" | "new") {
     const body = {
       name: name.value.trim(),
       template_string: props.templateString,
+      negative_template: props.negativeTemplate ?? "",
       description: description.value,
       category_id: categoryId.value,
       tags: tagsParsed.value,
@@ -157,6 +162,14 @@ async function submit(mode: "update" | "new") {
           <pre class="wp-stm-preview" data-test="save-tpl-preview">{{ templateString || "(empty)" }}</pre>
         </div>
 
+        <div v-if="negativeTemplate" class="wp-stm-field">
+          <label class="wp-stm-field__label wp-stm-field__label--neg">Negative template</label>
+          <pre
+            class="wp-stm-preview wp-stm-preview--neg"
+            data-test="save-tpl-neg-preview"
+          >{{ negativeTemplate }}</pre>
+        </div>
+
         <p v-if="errorMsg" class="wp-stm-error" data-test="save-tpl-error">{{ errorMsg }}</p>
       </div>
 
@@ -276,6 +289,10 @@ async function submit(mode: "update" | "new") {
   max-height: 110px;
   color: var(--wp-text-muted, #a1a1ad);
 }
+.wp-stm-preview--neg {
+  border-color: color-mix(in srgb, var(--wp-danger) 40%, var(--wp-border, #2a2a3a));
+}
+.wp-stm-field__label--neg { color: var(--wp-danger); }
 .wp-stm-note {
   display: flex;
   align-items: flex-start;

src/components/cleaner/CleanerWidget.test.ts

@@ -21,7 +21,7 @@ describe("CleanerWidget", () => {
     expect(w.find('[data-test="cleaner-intensity-gentle"]').exists()).toBe(true);
     expect(w.find('[data-test="cleaner-intensity-balanced"]').exists()).toBe(true);
     expect(w.find('[data-test="cleaner-intensity-aggressive"]').exists()).toBe(true);
-    expect(w.findAll('[data-test^="cleaner-rule-"]:not([data-test$="-stat"])')).toHaveLength(5);
+    expect(w.findAll('[data-test^="cleaner-rule-"]:not([data-test$="-stat"])')).toHaveLength(8);
   });
 
   it("CUSTOM badge marked visible when modified", () => {
@@ -64,6 +64,29 @@ describe("CleanerWidget", () => {
     expect(w.find('[data-test="cleaner-rule-dedupe_exact-stat"]').text()).toContain("1");
   });
 
+  it("shows counts for the bracket and LoRA rules", () => {
+    const w = mount(CleanerWidget, {
+      props: makeProps({ intensity: "aggressive" }, {
+        lastRunReport: {
+          empty_groups: { removed: 2 },
+          merge_weights: { merged: 1 },
+          lora_spacing: { tidied: 4 },
+        },
+      }),
+    });
+    expect(w.find('[data-test="cleaner-rule-empty_groups-stat"]').text()).toBe("2");
+    expect(w.find('[data-test="cleaner-rule-merge_weights-stat"]').text()).toBe("1");
+    expect(w.find('[data-test="cleaner-rule-lora_spacing-stat"]').text()).toBe("4");
+  });
+
+  it("merge weights is off on balanced and on for aggressive", () => {
+    const balanced = mount(CleanerWidget, { props: makeProps() });
+    expect(balanced.find('[data-test="cleaner-rule-merge_weights"]').classes()).not.toContain("is-on");
+    expect(balanced.find('[data-test="cleaner-rule-empty_groups"]').classes()).toContain("is-on");
+    const aggressive = mount(CleanerWidget, { props: makeProps({ intensity: "aggressive" }) });
+    expect(aggressive.find('[data-test="cleaner-rule-merge_weights"]').classes()).toContain("is-on");
+  });
+
   it("blocklist button shows entry count when populated", () => {
     const w = mount(CleanerWidget, {
       props: makeProps({ blocklist: { kind: "list", entries: ["a", "b", "c"] } }),
@@ -78,3 +101,84 @@ describe("CleanerWidget", () => {
   });
 
 });
+
+describe("CleanerWidget — neg column (send-to-negative)", () => {
+  function lastEmit(w: ReturnType<typeof mount>): CleanerNodeConfig {
+    const emits = w.emitted("update:modelValue") ?? [];
+    return emits[emits.length - 1][0] as CleanerNodeConfig;
+  }
+
+  it("neg toggles default from the preset: fuzzy dedupe + blocklist off", () => {
+    const w = mount(CleanerWidget, {
+      props: makeProps({ intensity: "aggressive", blocklist: { kind: "list", entries: ["x"] } }),
+    });
+    const on = (rid: string) => w.find(`[data-test="cleaner-neg-rule-${rid}"]`).classes().includes("is-on");
+    expect(on("whitespace")).toBe(true);
+    expect(on("dedupe_exact")).toBe(true);
+    expect(on("fuzzy_dedupe")).toBe(false);
+    expect(on("blocklist")).toBe(false);
+    // The prompt column still has both on under aggressive + entries.
+    expect(w.find('[data-test="cleaner-rule-fuzzy_dedupe"]').classes()).toContain("is-on");
+  });
+
+  it("a neg toggle stores negative_rules_override only when it differs, and marks CUSTOM", async () => {
+    const w = mount(CleanerWidget, { props: makeProps() });
+    await w.find('[data-test="cleaner-neg-rule-fuzzy_dedupe"]').trigger("click");
+    const next = lastEmit(w);
+    expect(next.negative_rules_override).toEqual({ fuzzy_dedupe: true });
+    expect(next.rules_override).toEqual({});
+
+    const custom = mount(CleanerWidget, { props: makeProps({ negative_rules_override: { fuzzy_dedupe: true } }) });
+    expect(custom.find('[data-test="cleaner-custom-badge"]').classes()).not.toContain("is-hidden");
+    // Toggling back to the default drops the key entirely.
+    await custom.find('[data-test="cleaner-neg-rule-fuzzy_dedupe"]').trigger("click");
+    expect(lastEmit(custom)).not.toHaveProperty("negative_rules_override");
+  });
+
+  it("a preset prunes neg overrides that match its default", async () => {
+    const w = mount(CleanerWidget, {
+      props: makeProps({ intensity: "gentle", negative_rules_override: { dedupe_exact: true } }),
+    });
+    await w.find('[data-test="cleaner-intensity-balanced"]').trigger("click");
+    const next = lastEmit(w);
+    expect(next.intensity).toBe("balanced");
+    expect(next).not.toHaveProperty("negative_rules_override");
+  });
+
+  it("drop-overlap row is off by default and stored only when on", async () => {
+    const w = mount(CleanerWidget, { props: makeProps() });
+    const btn = w.find('[data-test="cleaner-drop-overlap"]');
+    expect(btn.classes()).not.toContain("is-on");
+    await btn.trigger("click");
+    expect(lastEmit(w).drop_prompt_overlap).toBe(true);
+    const on = mount(CleanerWidget, { props: makeProps({ drop_prompt_overlap: true }) });
+    await on.find('[data-test="cleaner-drop-overlap"]').trigger("click");
+    expect(lastEmit(on)).not.toHaveProperty("drop_prompt_overlap");
+  });
+
+  it("last run shows a negative line and the counter a negative count", () => {
+    const w = mount(CleanerWidget, {
+      props: makeProps({}, {
+        lastRunReport: { dedupe_exact: { dropped: ["a", "b"] }, blocklist: { dropped: ["c"] } },
+        wordCount: 42,
+        charCount: 187,
+        negativeReport: {
+          dedupe_exact: { dropped: ["x", "y", "z"] },
+          prompt_overlap: { tags: ["red"], dropped: false },
+        },
+        negativeWordCount: 11,
+      }),
+    });
+    expect(w.find('[data-test="cleaner-neg-count"]').text()).toBe("negative 11");
+    expect(w.find('[data-test="cleaner-last-run"]').text()).toContain("prompt: 2 duplicates, 1 blocklisted");
+    expect(w.find('[data-test="cleaner-last-run-neg"]').text()).toBe(
+      'negative: 3 duplicates · 1 tag also in prompt: "red"',
+    );
+  });
+
+  it("no negative report = no last-run block and no negative count", () => {
+    const w = mount(CleanerWidget, { props: makeProps() });
+    expect(w.find('[data-test="cleaner-last-run"]').exists()).toBe(false);
+    expect(w.find('[data-test="cleaner-neg-count"]').exists()).toBe(false);
+  });
+});

src/components/cleaner/CleanerWidget.vue

@@ -5,16 +5,27 @@
  * in code; per-node manual toggles + blocklist entries are persisted
  * via the widget JSON.
  *
+ * Send-to-negative: the rule list has a second "neg" column (the node's
+ * optional `negative` input is cleaned by it), plus a neg-only "drop
+ * negative tags also in prompt" row.
+ *
  * Tokens: uses canonical `--wp-*` theme variables from
  * src/components/shared/theme.css (and SPA's tokens.css which
  * overrides the same names with the SPA palette).
  */
 import { computed } from "vue";
-import { INTENSITY_TO_RULES, computeEffectiveRules, isPristine } from "./intensity";
+import {
+  INTENSITY_TO_NEG_RULES,
+  INTENSITY_TO_RULES,
+  computeEffectiveNegativeRules,
+  computeEffectiveRules,
+  isPristine,
+} from "./intensity";
 import type {
   CleanerNodeConfig,
   Intensity,
   Mode,
+  NegativeRunReport,
   RuleId,
   RunReport,
 } from "./types";
@@ -28,7 +39,11 @@ const props = withDefaults(defineProps<{
    *  dim overlay so muted/bypassed state matches litegraph's native
    *  title/border dim. */
   nodeMode?: number;
-}>(), { nodeMode: 0 });
+  /** Last run's negative report; null when the run had no negative. */
+  negativeReport?: NegativeRunReport | null;
+  /** Word count of the cleaned negative; null when there was none. */
+  negativeWordCount?: number | null;
+}>(), { nodeMode: 0, negativeReport: null, negativeWordCount: null });
 
 const isSkipped = computed(() => props.nodeMode === 2 || props.nodeMode === 4);
 
@@ -59,6 +74,24 @@ const ALL_RULES: {
     statKey: "stripped",
     tooltip: "Drop tags that are only punctuation (e.g. lone '.'). Strip leading/trailing punctuation from each tag (tags mode) or from the whole string (text mode).",
   },
+  {
+    id: "empty_groups",
+    label: "empty groups",
+    statKey: "removed",
+    tooltip: "Remove brackets with nothing inside: (), [], ( , ) and (:1.2), e.g. a weighted ref that resolved to nothing. Escaped \\( \\) and unbalanced brackets are left alone.",
+  },
+  {
+    id: "merge_weights",
+    label: "merge weights",
+    statKey: "merged",
+    tooltip: "Fold nested weights into one group the way ComfyUI multiplies them: ((a:1.1):1.2) → (a:1.32), ((a)) → (a:1.21). A weight of 1 is unwrapped: (a:1.0) → a. Rounded to 2 decimals.",
+  },
+  {
+    id: "lora_spacing",
+    label: "LoRA spacing",
+    statKey: "tidied",
+    tooltip: "Tidy <lora:…> tags: < lora : x : 0.8 > → <lora:x:0.8>, and give a tag touching a word a space (girl<lora:x:1> → girl <lora:x:1>). Spaces inside a file name stay.",
+  },
   {
     id: "dedupe_exact",
     label: "tag dedupe",
@@ -88,13 +121,14 @@ const MODE_TOOLTIPS = {
 
 const INTENSITY_TOOLTIPS = {
   gentle: "Gentle: whitespace cleanup only.",
-  balanced: "Balanced: whitespace + punctuation + exact tag dedupe.",
-  aggressive: "Aggressive: all rules including fuzzy dedupe.",
+  balanced: "Balanced: empty groups + LoRA spacing + whitespace + punctuation + exact tag dedupe.",
+  aggressive: "Aggressive: balanced plus merge weights and fuzzy dedupe.",
 };
 
 const INTENSITIES: Intensity[] = ["gentle", "balanced", "aggressive"];
 
 const effective = computed(() => new Set(computeEffectiveRules(props.modelValue)));
+const effectiveNeg = computed(() => new Set(computeEffectiveNegativeRules(props.modelValue)));
 const pristine = computed(() => isPristine(props.modelValue));
 
 /** Drop any override entry whose value matches the new intensity's
@@ -120,11 +154,42 @@ function patch(next: Partial<CleanerNodeConfig>): void {
   emit("update:modelValue", { ...props.modelValue, ...next });
 }
 
+/** The config with `negative_rules_override` set to `overrides`, or the key
+ *  dropped when nothing diverges (so an untouched column stays absent). */
+function withNegOverrides(
+  base: CleanerNodeConfig,
+  overrides: Partial<Record<RuleId, boolean>>,
+): CleanerNodeConfig {
+  const next = { ...base };
+  if (Object.keys(overrides).length > 0) next.negative_rules_override = overrides;
+  else delete next.negative_rules_override;
+  return next;
+}
+
+/** Neg-column twin of {@link pruneStaleOverrides} (no blocklist baseline). */
+function pruneStaleNegOverrides(
+  overrides: Partial<Record<RuleId, boolean>>,
+  intensity: Intensity,
+): Partial<Record<RuleId, boolean>> {
+  const defaults = new Set(INTENSITY_TO_NEG_RULES[intensity]);
+  const next: Partial<Record<RuleId, boolean>> = {};
+  for (const [rid, on] of Object.entries(overrides) as [RuleId, boolean][]) {
+    if (on !== defaults.has(rid)) next[rid] = on;
+  }
+  return next;
+}
+
 function setIntensity(intensity: Intensity): void {
-  patch({
+  // A preset sets both columns: overrides that now match its default drop.
+  const base: CleanerNodeConfig = {
+    ...props.modelValue,
     intensity,
     rules_override: pruneStaleOverrides(props.modelValue.rules_override, intensity),
-  });
+  };
+  emit("update:modelValue", withNegOverrides(
+    base,
+    pruneStaleNegOverrides(props.modelValue.negative_rules_override ?? {}, intensity),
+  ));
 }
 function setMode(mode: Mode): void { patch({ mode }); }
 
@@ -161,6 +226,68 @@ function toggleRule(rid: RuleId): void {
   patch({ rules_override: overrides });
 }
 
+function negBaseline(rid: RuleId): boolean {
+  return INTENSITY_TO_NEG_RULES[props.modelValue.intensity].includes(rid);
+}
+
+function toggleNegRule(rid: RuleId): void {
+  if (isRuleDisabled(rid)) return;
+  const nextOn = !effectiveNeg.value.has(rid);
+  const overrides = { ...(props.modelValue.negative_rules_override ?? {}) };
+  if (nextOn === negBaseline(rid)) delete overrides[rid];
+  else overrides[rid] = nextOn;
+  emit("update:modelValue", withNegOverrides(props.modelValue, overrides));
+}
+
+function isNegOverridden(rid: RuleId): boolean {
+  const v = props.modelValue.negative_rules_override?.[rid];
+  return v !== undefined && v !== negBaseline(rid);
+}
+
+function toggleDropOverlap(): void {
+  const next = { ...props.modelValue };
+  if (props.modelValue.drop_prompt_overlap) delete next.drop_prompt_overlap;
+  else next.drop_prompt_overlap = true;
+  emit("update:modelValue", next);
+}
+
+function droppedCount(report: RunReport | null | undefined, rids: RuleId[]): number {
+  let n = 0;
+  for (const rid of rids) {
+    const v = (report?.[rid] as Record<string, unknown> | undefined)?.dropped;
+    if (Array.isArray(v)) n += v.length;
+    else if (typeof v === "number") n += v;
+  }
+  return n;
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+/** "last run" lines, shown once a run cleaned a negative. */
+const promptRunLine = computed(() => {
+  const parts = [plural(droppedCount(props.lastRunReport, ["dedupe_exact", "fuzzy_dedupe"]), "duplicate")];
+  const blocked = droppedCount(props.lastRunReport, ["blocklist"]);
+  if (blocked > 0) parts.push(`${blocked} blocklisted`);
+  return `prompt: ${parts.join(", ")}`;
+});
+const negativeRunLine = computed(() => {
+  const r = props.negativeReport;
+  if (!r) return "";
+  const parts = [plural(droppedCount(r, ["dedupe_exact", "fuzzy_dedupe"]), "duplicate")];
+  const blocked = droppedCount(r, ["blocklist"]);
+  if (blocked > 0) parts[0] += `, ${blocked} blocklisted`;
+  const overlap = r.prompt_overlap;
+  if (overlap && overlap.tags.length > 0) {
+    const quoted = overlap.tags.map((t) => `"${t}"`).join(", ");
+    parts.push(
+      `${plural(overlap.tags.length, "tag")} also in prompt${overlap.dropped ? " (dropped)" : ""}: ${quoted}`,
+    );
+  }
+  return `negative: ${parts.join(" · ")}`;
+});
+
 function ruleStat(rid: RuleId): string {
   const stats = props.lastRunReport?.[rid];
   if (!stats) return "—";
@@ -201,7 +328,11 @@ function isOverridden(rid: RuleId): boolean {
       <span
         class="wp-cleaner__counter"
         :title="`${wordCount} words · ${charCount} characters in the cleaned output`"
-      >{{ wordCount }}w · {{ charCount }}c</span>
+      >{{ wordCount }}w · {{ charCount }}c<template v-if="negativeWordCount != null"> · <span
+        class="wp-cleaner__counter-neg"
+        data-test="cleaner-neg-count"
+        :title="`${negativeWordCount} words in the cleaned negative`"
+      >negative {{ negativeWordCount }}</span></template></span>
     </header>
 
     <section class="wp-cleaner__section">
@@ -226,11 +357,14 @@ function isOverridden(rid: RuleId): boolean {
     </section>
 
     <section class="wp-cleaner__section">
-      <span class="wp-cleaner__section-label">RULES</span>
+      <div class="wp-cleaner__rules-head">
+        <span class="wp-cleaner__section-label">RULES</span>
+        <span class="wp-cleaner__col-label">prompt</span>
+        <span class="wp-cleaner__col-label wp-cleaner__col-label--neg">neg</span>
+      </div>
       <div class="wp-cleaner__rules">
+        <div v-for="rule in ALL_RULES" :key="rule.id" class="wp-cleaner__rule-row">
         <button
-          v-for="rule in ALL_RULES"
-          :key="rule.id"
           :data-test="`cleaner-rule-${rule.id}`"
           :class="['wp-cleaner__rule', {
             'is-on': effective.has(rule.id) && !isRuleDisabled(rule.id),
@@ -256,9 +390,46 @@ function isOverridden(rid: RuleId): boolean {
             class="wp-cleaner__rule-stat"
           >{{ ruleStat(rule.id) }}</span>
         </button>
+        <button
+          :data-test="`cleaner-neg-rule-${rule.id}`"
+          :class="['wp-cleaner__neg-toggle', {
+            'is-on': effectiveNeg.has(rule.id) && !isRuleDisabled(rule.id),
+            'is-overridden': isNegOverridden(rule.id) && !isRuleDisabled(rule.id),
+            'is-disabled': isRuleDisabled(rule.id),
+          }]"
+          :title="`${rule.label} on the negative${isRuleDisabled(rule.id) ? ' (disabled in text mode)' : ''}`"
+          :aria-label="`${rule.label} on the negative`"
+          :aria-pressed="effectiveNeg.has(rule.id)"
+          :disabled="isRuleDisabled(rule.id)"
+          @click="toggleNegRule(rule.id)"
+        ><span class="wp-cleaner__rule-dot" /></button>
+        </div>
+        <div class="wp-cleaner__rule-row wp-cleaner__rule-row--overlap">
+          <span
+            class="wp-cleaner__rule wp-cleaner__rule--static"
+            title="Drop negative tags the cleaned prompt also contains (it would be told to draw them and not draw them). Negative only."
+          >
+            <span class="wp-cleaner__rule-dash" aria-hidden="true">–</span>
+            <span class="wp-cleaner__rule-label">drop negative tags also in prompt</span>
+          </span>
+          <button
+            data-test="cleaner-drop-overlap"
+            :class="['wp-cleaner__neg-toggle', { 'is-on': !!modelValue.drop_prompt_overlap }]"
+            title="Drop negative tags also in the prompt"
+            aria-label="drop negative tags also in the prompt"
+            :aria-pressed="!!modelValue.drop_prompt_overlap"
+            @click="toggleDropOverlap"
+          ><span class="wp-cleaner__rule-dot" /></button>
+        </div>
       </div>
     </section>
 
+    <div v-if="negativeReport" class="wp-cleaner__lastrun" data-test="cleaner-last-run">
+      <span class="wp-cleaner__section-label">LAST RUN</span>
+      <span class="wp-cleaner__lastrun-line">{{ promptRunLine }}</span>
+      <span class="wp-cleaner__lastrun-line wp-cleaner__lastrun-line--neg" data-test="cleaner-last-run-neg">{{ negativeRunLine }}</span>
+    </div>
+
     <div class="wp-cleaner__blocklist">
       <button
         data-test="cleaner-blocklist-btn"
@@ -373,6 +544,65 @@ function isOverridden(rid: RuleId): boolean {
 }
 
 .wp-cleaner__rules { display: grid; gap: 2px; }
+/* Two columns: the prompt rule button, then the neg-column toggle. */
+.wp-cleaner__rules-head,
+.wp-cleaner__rule-row {
+  display: grid;
+  grid-template-columns: 1fr 30px;
+  align-items: center;
+  gap: 4px;
+}
+.wp-cleaner__rules-head { grid-template-columns: 1fr auto 30px; }
+.wp-cleaner__col-label {
+  font: 600 9px var(--wp-font-sans, sans-serif);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--wp-text-dim, var(--wp-text3));
+  text-align: center;
+}
+.wp-cleaner__col-label--neg { color: var(--wp-danger, #ef4444); }
+.wp-cleaner__neg-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  min-height: 20px;
+  background: transparent;
+  border: 0;
+  border-radius: 3px;
+  cursor: pointer;
+}
+.wp-cleaner__neg-toggle:hover:not(.is-disabled) { background: var(--wp-row-hover, var(--wp-bg2)); }
+.wp-cleaner__neg-toggle.is-on .wp-cleaner__rule-dot { background: var(--wp-danger, #ef4444); }
+.wp-cleaner__neg-toggle.is-overridden .wp-cleaner__rule-dot {
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--wp-amber, var(--wp-warn, #fbbf24)) 70%, transparent);
+}
+.wp-cleaner__neg-toggle.is-disabled { opacity: 0.4; cursor: not-allowed; }
+.wp-cleaner__rule-row--overlap {
+  border-top: 1px solid var(--wp-border-soft, var(--wp-border));
+  padding-top: 2px;
+  margin-top: 2px;
+}
+.wp-cleaner__rule--static { cursor: default; }
+.wp-cleaner__rule-dash {
+  width: 8px;
+  text-align: center;
+  color: var(--wp-text-dim, var(--wp-text3));
+}
+.wp-cleaner__counter-neg { color: var(--wp-danger, #ef4444); }
+.wp-cleaner__lastrun {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 6px 8px;
+  background: var(--wp-bg-deep, var(--wp-bg));
+  border: 1px solid var(--wp-border);
+  border-radius: 3px;
+  font: 10px/1.5 var(--wp-font-mono, monospace);
+  color: var(--wp-text-muted, var(--wp-text2));
+}
+.wp-cleaner__lastrun-line { word-break: break-word; }
+.wp-cleaner__lastrun-line--neg { color: var(--wp-danger, #ef4444); }
 .wp-cleaner__rule {
   position: relative;
   display: grid;

src/components/cleaner/intensity.test.ts

@@ -1,19 +1,28 @@
 import { describe, it, expect } from "vitest";
-import { INTENSITY_TO_RULES, computeEffectiveRules, isPristine } from "./intensity";
+import {
+  INTENSITY_TO_NEG_RULES,
+  INTENSITY_TO_RULES,
+  computeEffectiveNegativeRules,
+  computeEffectiveRules,
+  isPristine,
+} from "./intensity";
 import { emptyCleanerConfig, type CleanerNodeConfig } from "./types";
 
 describe("intensity helpers", () => {
   it("INTENSITY_TO_RULES mirrors the Python pipeline", () => {
     expect(INTENSITY_TO_RULES.gentle).toEqual(["whitespace"]);
     expect(INTENSITY_TO_RULES.balanced).toEqual([
-      "whitespace", "punctuation", "dedupe_exact",
+      "empty_groups", "lora_spacing", "whitespace", "punctuation", "dedupe_exact",
+    ]);
+    expect(INTENSITY_TO_RULES.aggressive).toEqual([
+      "empty_groups", "merge_weights", "lora_spacing",
+      "whitespace", "punctuation", "dedupe_exact", "fuzzy_dedupe",
     ]);
-    expect(INTENSITY_TO_RULES.aggressive).toHaveLength(4);
   });
 
   it("computeEffectiveRules returns intensity rules when no overrides", () => {
     expect(computeEffectiveRules(emptyCleanerConfig())).toEqual([
-      "whitespace", "punctuation", "dedupe_exact",
+      "empty_groups", "lora_spacing", "whitespace", "punctuation", "dedupe_exact",
     ]);
   });
 
@@ -72,6 +81,37 @@ describe("intensity helpers", () => {
     })).toBe(true);
   });
 
+  it("INTENSITY_TO_NEG_RULES mirrors the Python pipeline's negative column", () => {
+    expect(INTENSITY_TO_NEG_RULES).toEqual({
+      gentle: ["whitespace"],
+      balanced: ["empty_groups", "lora_spacing", "whitespace", "punctuation", "dedupe_exact"],
+      aggressive: [
+        "empty_groups", "merge_weights", "lora_spacing",
+        "whitespace", "punctuation", "dedupe_exact",
+      ],
+    });
+  });
+
+  it("neg column: preset defaults + overrides, never auto-enables the blocklist", () => {
+    const cfg: CleanerNodeConfig = {
+      ...emptyCleanerConfig(),
+      intensity: "aggressive",
+      blocklist: { kind: "list", entries: ["x"] },
+    };
+    expect(computeEffectiveNegativeRules(cfg)).toEqual([
+      "empty_groups", "merge_weights", "lora_spacing", "whitespace", "punctuation", "dedupe_exact",
+    ]);
+    expect(computeEffectiveNegativeRules({
+      ...cfg, negative_rules_override: { dedupe_exact: false, fuzzy_dedupe: true, merge_weights: false },
+    })).toEqual(["empty_groups", "lora_spacing", "whitespace", "punctuation", "fuzzy_dedupe"]);
+  });
+
+  it("isPristine false when the neg column diverges from its preset", () => {
+    expect(isPristine({ ...emptyCleanerConfig(), negative_rules_override: { fuzzy_dedupe: true } })).toBe(false);
+    // Matching the neg default is not a modification.
+    expect(isPristine({ ...emptyCleanerConfig(), negative_rules_override: { whitespace: true } })).toBe(true);
+  });
+
   it("rules sorted by registry order regardless of toggle order", () => {
     const cfg: CleanerNodeConfig = {
       ...emptyCleanerConfig(),

src/components/cleaner/intensity.ts

@@ -5,12 +5,32 @@ import type { CleanerNodeConfig, Intensity, RuleId } from "./types";
 
 export const INTENSITY_TO_RULES: Record<Intensity, RuleId[]> = {
   gentle: ["whitespace"],
-  balanced: ["whitespace", "punctuation", "dedupe_exact"],
-  aggressive: ["whitespace", "punctuation", "dedupe_exact", "fuzzy_dedupe"],
+  // Empty groups + LoRA spacing never change what a prompt means; merging
+  // weights rewrites how it reads, so it waits for aggressive.
+  balanced: ["empty_groups", "lora_spacing", "whitespace", "punctuation", "dedupe_exact"],
+  aggressive: [
+    "empty_groups", "merge_weights", "lora_spacing",
+    "whitespace", "punctuation", "dedupe_exact", "fuzzy_dedupe",
+  ],
+};
+
+/** Mirrors `engine/cleaner/pipeline.INTENSITY_TO_NEG_RULES`: the "neg"
+ *  column's defaults. Fuzzy dedupe stays off (near-duplicates in a negative
+ *  are usually deliberate) and the blocklist never auto-enables. */
+export const INTENSITY_TO_NEG_RULES: Record<Intensity, RuleId[]> = {
+  gentle: ["whitespace"],
+  balanced: ["empty_groups", "lora_spacing", "whitespace", "punctuation", "dedupe_exact"],
+  aggressive: [
+    "empty_groups", "merge_weights", "lora_spacing",
+    "whitespace", "punctuation", "dedupe_exact",
+  ],
 };
 
 /** Same canonical order as engine/cleaner/rules/__init__.py:RULE_REGISTRY. */
 const REGISTRY_ORDER: RuleId[] = [
+  "empty_groups",
+  "merge_weights",
+  "lora_spacing",
   "whitespace",
   "punctuation",
   "dedupe_exact",
@@ -37,6 +57,17 @@ export function computeEffectiveRules(config: CleanerNodeConfig): RuleId[] {
   return REGISTRY_ORDER.filter((rid) => base.has(rid));
 }
 
+/** The "neg" column's rule list (mirrors `run_negative`): preset defaults
+ *  plus `negative_rules_override`, no blocklist auto-enable. */
+export function computeEffectiveNegativeRules(config: CleanerNodeConfig): RuleId[] {
+  const base = new Set<RuleId>(INTENSITY_TO_NEG_RULES[config.intensity]);
+  for (const [rid, on] of Object.entries(config.negative_rules_override ?? {}) as Array<[RuleId, boolean]>) {
+    if (on) base.add(rid);
+    else base.delete(rid);
+  }
+  return REGISTRY_ORDER.filter((rid) => base.has(rid));
+}
+
 /** True when no rule override diverges from the intensity baseline.
  *  Blocklist entries on their own do NOT count as "modification" —
  *  they're data, not a toggle. The CUSTOM badge appears only when the
@@ -48,5 +79,9 @@ export function isPristine(config: CleanerNodeConfig): boolean {
     const baseline = defaults.has(rid) || (rid === "blocklist" && hasEntries);
     if (on !== baseline) return false;
   }
+  const negDefaults = new Set(INTENSITY_TO_NEG_RULES[config.intensity]);
+  for (const [rid, on] of Object.entries(config.negative_rules_override ?? {}) as Array<[RuleId, boolean]>) {
+    if (on !== negDefaults.has(rid)) return false;
+  }
   return true;
 }

src/components/cleaner/types.ts

@@ -1,5 +1,8 @@
 /** Canonical rule ids. Must stay in sync with engine/cleaner/types.py:RuleId. */
 export type RuleId =
+  | "empty_groups"
+  | "merge_weights"
+  | "lora_spacing"
   | "whitespace"
   | "punctuation"
   | "dedupe_exact"
@@ -17,11 +20,25 @@ export interface CleanerNodeConfig {
   /** Sparse — only rules diverging from the intensity default. */
   rules_override: Partial<Record<RuleId, boolean>>;
   blocklist: { kind: BlocklistKind; entries: string[] };
+  /** Send-to-negative: the rule list's "neg" column. Sparse like
+   *  `rules_override`, against `INTENSITY_TO_NEG_RULES`. Absent on
+   *  workflows saved before the column existed. */
+  negative_rules_override?: Partial<Record<RuleId, boolean>>;
+  /** Drop negative tags the cleaned prompt also contains. Off (absent) by
+   *  default; stored only when on. */
+  drop_prompt_overlap?: boolean;
 }
 
 export type RuleStats = Record<string, unknown>;
 export type RunReport = Partial<Record<RuleId, RuleStats>>;
 
+/** `wp_cleaner_negative_report`: the negative column's per-rule stats plus
+ *  the tags the negative shares with the prompt (present only when some
+ *  do). */
+export type NegativeRunReport = RunReport & {
+  prompt_overlap?: { tags: string[]; dropped: boolean };
+};
+
 export function emptyCleanerConfig(): CleanerNodeConfig {
   return {
     mode: "tags",

src/components/context-loop/ContextLoopWidget.test.ts

@@ -198,9 +198,9 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
     return calls?.[calls.length - 1]?.[0] as ReturnType<typeof emptyContextLoopConfig>;
   };
 
-  it("shift-click locks the frame to the seed it would have used", async () => {
+  it("alt-click locks the frame to the seed it would have used", async () => {
     const w = fw();
-    await w.find('[data-test="loop-frame-3"]').trigger("click", { shiftKey: true });
+    await w.find('[data-test="loop-frame-3"]').trigger("click", { altKey: true });
     const next = lastEmit(w);
     // Frame index 2, and the value must be a real derived seed — not a
     // placeholder, or the lock would silently change the output it froze.
@@ -208,44 +208,44 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
     expect(Number.isInteger(next.seed_locks!["2"])).toBe(true);
   });
 
-  it("shift-click on a locked frame unlocks it", async () => {
+  it("alt-click on a locked frame unlocks it", async () => {
     const w = fw({ seed_locks: { "2": 777 } });
-    await w.find('[data-test="loop-frame-3"]').trigger("click", { shiftKey: true });
+    await w.find('[data-test="loop-frame-3"]').trigger("click", { altKey: true });
     expect(lastEmit(w).seed_locks).toEqual({});
   });
 
   it("the chip-lock value matches what the modal's Lock all would write", async () => {
     const w = fw();
-    await w.find('[data-test="loop-frame-2"]').trigger("click", { shiftKey: true });
+    await w.find('[data-test="loop-frame-2"]').trigger("click", { altKey: true });
     const chipValue = lastEmit(w).seed_locks!["1"];
     expect(chipValue).toBe(deriveLoopSeeds(42, 4, "hash_index")[1]);
   });
 
-  it("alt-click bypasses a frame, and again re-enables it", async () => {
+  it("ctrl-click bypasses a frame, and again re-enables it", async () => {
     const w = fw();
-    await w.find('[data-test="loop-frame-2"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-2"]').trigger("click", { ctrlKey: true });
     expect(lastEmit(w).bypass_frames).toEqual([1]);
 
     const w2 = fw({ bypass_frames: [1] });
-    await w2.find('[data-test="loop-frame-2"]').trigger("click", { altKey: true });
+    await w2.find('[data-test="loop-frame-2"]').trigger("click", { ctrlKey: true });
     expect(lastEmit(w2).bypass_frames).toEqual([]);
   });
 
   it("keeps bypassed indices sorted so the config does not churn", async () => {
     const w = fw({ bypass_frames: [3] });
-    await w.find('[data-test="loop-frame-2"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-2"]').trigger("click", { ctrlKey: true });
     expect(lastEmit(w).bypass_frames).toEqual([1, 3]);
   });
 
   it("refuses to bypass the last running frame — a loop needs one", async () => {
     const w = fw({ bypass_frames: [0, 1, 2] }, 4);
-    await w.find('[data-test="loop-frame-4"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-4"]').trigger("click", { ctrlKey: true });
     expect(w.emitted("update:modelValue")).toBeUndefined();
   });
 
   it("still lets the last running frame be re-enabled and locked", async () => {
     const w = fw({ bypass_frames: [0, 1, 2] }, 4);
-    await w.find('[data-test="loop-frame-1"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-1"]').trigger("click", { ctrlKey: true });
     expect(lastEmit(w).bypass_frames).toEqual([1, 2]);
   });
 
@@ -253,9 +253,9 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
   // kind of surprise that makes people stop trusting a shortcut.
   it("a modifier click never also moves the edit cursor", async () => {
     const w = fw();
-    await w.find('[data-test="loop-frame-3"]').trigger("click", { shiftKey: true });
+    await w.find('[data-test="loop-frame-3"]').trigger("click", { altKey: true });
     expect(currentFrame.value).toBe(null);
-    await w.find('[data-test="loop-frame-2"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-2"]').trigger("click", { ctrlKey: true });
     expect(currentFrame.value).toBe(null);
   });
 
@@ -268,8 +268,8 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
 
   it("base takes no modifiers — it has no seed and nothing to bypass", async () => {
     const w = fw();
-    await w.find('[data-test="loop-frame-base"]').trigger("click", { shiftKey: true });
     await w.find('[data-test="loop-frame-base"]').trigger("click", { altKey: true });
+    await w.find('[data-test="loop-frame-base"]').trigger("click", { ctrlKey: true });
     expect(w.emitted("update:modelValue")).toBeUndefined();
   });
 
@@ -293,7 +293,7 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
 
   it("advertises the combos in the widget, not just in tooltips", () => {
     const w = fw();
-    expect(w.find('[data-test="loop-frames-hint"]').text()).toMatch(/shift/i);
+    expect(w.find('[data-test="loop-frames-hint"]').text()).toMatch(/alt-click locks/i);
     expect(w.find('[data-test="loop-frames-hint"]').text()).toMatch(/alt|option/i);
   });
 
@@ -303,4 +303,13 @@ describe("ContextLoopWidget frame chip modifier-clicks", () => {
     expect(t).toMatch(/unlock/i);
     expect(t).toMatch(/re-enable/i);
   });
+
+  it("goes back to base when the edited frame no longer exists", async () => {
+    const w = mount(ContextLoopWidget, { props: { modelValue: emptyContextLoopConfig(), count: 6 } });
+    currentFrame.value = 4;
+    await w.setProps({ count: 5 });
+    expect(currentFrame.value).toBe(4);
+    await w.setProps({ count: 3 });
+    expect(currentFrame.value).toBeNull();
+  });
 });

src/components/context-loop/ContextLoopWidget.vue

@@ -12,8 +12,10 @@
  * host glue (`src/widgets/context_loop.ts`) serializes to JSON and
  * pushes via `host.setValue` so ComfyUI's widget value matches.
  */
-import { computed, ref } from "vue";
-import type { ContextLoopConfig, LoopStrategy } from "./types";
+import { computed, ref, watch } from "vue";
+import { remapSweepFrames, sweepFrameCount, type ContextLoopConfig, type LoopStrategy, type SweepConfig } from "./types";
+import { collectSweepCandidates, sweepSourcesFromRaw, type SweepSourceRaw } from "./sweep-candidates";
+import SweepModal from "./SweepModal.vue";
 import SeedListModal from "../shared/SeedListModal.vue";
 import { deriveLoopSeeds } from "../shared/seed-derive";
 import { pushToast } from "../shared/toast-store";
@@ -34,8 +36,11 @@ const props = withDefaults(
      *  executed `loop_seeds` UI payload by the host glue. Drives the seed
      *  modal's per-frame "lock previous" button. Null until a run lands. */
     previousSeeds?: number[] | null;
+    /** Downstream Context nodes (id + module JSON) the Sweep section
+     *  draws its wildcards from. */
+    sweepSources?: SweepSourceRaw[];
   }>(),
-  { nodeMode: 0, baseSeed: 0, count: 1, previousSeeds: null },
+  { nodeMode: 0, baseSeed: 0, count: 1, previousSeeds: null, sweepSources: () => [] },
 );
 
 const emit = defineEmits<{ "update:modelValue": [next: ContextLoopConfig] }>();
@@ -86,10 +91,10 @@ function onBypassFrames(next: number[]): void {
  * of frames is the common case; the modal earns its place for the bulk
  * operations (lock all, paste a series, out-of-range locks) and keeps them.
  *
- * Modifier choice: Alt and Shift both survive the trip. Ctrl is out because on
- * macOS Ctrl-click IS a right-click, so the combo would open a context menu
- * instead. Alt for bypass follows the seed modal's existing Alt-click-for-a-
- * variant idiom on its Copy button.
+ * Modifier choice: Alt-click locks a seed, Ctrl-click bypasses — the reflex
+ * pairing users reach for. On macOS Ctrl-click IS a right-click, so Cmd stands
+ * in for bypass there (see FrameChips `isBypassChord`); Alt/Option survives the
+ * trip on every platform.
  * ------------------------------------------------------------------------- */
 
 /** 0-based locked frame indices. Keys are strings in the config; anything
@@ -138,6 +143,26 @@ function toggleFrameBypass(i: number): void {
   onBypassFrames([...next].sort((a, b) => a - b));
 }
 
+const sweepCandidates = computed(() =>
+  collectSweepCandidates(sweepSourcesFromRaw(props.sweepSources)),
+);
+
+const sweepOpen = ref(false);
+/** Frames the sweep will run, or null when it is not driving the loop. */
+const sweepFrames = computed(() => sweepFrameCount(props.modelValue));
+
+// The frame being edited must still exist: a lower count drops it, and a
+// sweep edit changes what each frame number means, so both go back to base.
+watch(() => props.count, (n) => {
+  if (currentFrame.value !== null && currentFrame.value >= Math.max(1, n ?? 1)) setFrame(null);
+});
+
+function onSweep(next: SweepConfig): void {
+  if (currentFrame.value !== null) setFrame(null);
+  const cfg = { ...props.modelValue, sweep: next };
+  emit("update:modelValue", remapSweepFrames(props.modelValue, cfg, Math.max(1, props.count ?? 1)));
+}
+
 function pickStrategy(s: LoopStrategy): void {
   if (props.modelValue.strategy === s) return;
   emit("update:modelValue", { ...props.modelValue, strategy: s });
@@ -209,6 +234,21 @@ function toggleTotalInternal(): void {
       <svg class="wp-loop__seedbtn-chev" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M9 6l6 6-6 6" /></svg>
     </button>
 
+    <button
+      type="button"
+      class="wp-loop__seedbtn wp-loop__sweepbtn"
+      data-test="loop-sweep-btn"
+      title="Run every combination of the wildcards you pick, one frame each."
+      @click="sweepOpen = true"
+    >
+      <span class="wp-loop__seedbtn-ico"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><rect x="4" y="4" width="6" height="6" rx="1" /><rect x="14" y="4" width="6" height="6" rx="1" /><rect x="4" y="14" width="6" height="6" rx="1" /><rect x="14" y="14" width="6" height="6" rx="1" /></svg></span>
+      Sweep combinations
+      <span class="wp-loop__seedbtn-fill" />
+      <span v-if="sweepFrames != null" class="wp-loop__seedbtn-badge" data-test="loop-sweep-badge">{{ sweepFrames }} {{ sweepFrames === 1 ? "frame" : "frames" }}</span>
+      <span v-else-if="modelValue.sweep.enabled" class="wp-loop__seedbtn-badge wp-loop__seedbtn-badge--dim" data-test="loop-sweep-badge">on</span>
+      <svg class="wp-loop__seedbtn-chev" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M9 6l6 6-6 6" /></svg>
+    </button>
+
     <!-- `base` is not a frame: it has no seed to lock and nothing to bypass,
          so it takes no modifiers. -->
     <FrameChips
@@ -226,6 +266,7 @@ function toggleTotalInternal(): void {
       @toggle-bypass="toggleFrameBypass"
     />
 
+
     <div
       class="wp-loop__row"
       :title="OVERRIDE_SEED_TOOLTIP"
@@ -300,6 +341,15 @@ function toggleTotalInternal(): void {
       </button>
     </div>
 
+    <SweepModal
+      v-if="sweepOpen"
+      :model-value="modelValue.sweep"
+      :candidates="sweepCandidates"
+      :loop-bypassed="modelValue.bypass"
+      @update:model-value="onSweep"
+      @close="sweepOpen = false"
+    />
+
     <SeedListModal v-if="seedsOpen" :node-name="'WP Context Loop'" :base-seed="baseSeed"
       :count="count" :strategy="modelValue.strategy" :seed-locks="modelValue.seed_locks ?? {}"
       :previous-seeds="previousSeeds"
@@ -451,6 +501,8 @@ function toggleTotalInternal(): void {
   pointer-events: none;
 }
 
+.wp-loop__seedbtn-badge--dim { opacity: .6; }
+
 /* Mute / bypass dim — same convention as WP_VarTo* and WP_Cleaner. */
 .wp-loop--muted { opacity: 0.45; pointer-events: none; }
 .wp-loop--bypassed { opacity: 0.65; }

src/components/context-loop/SweepModal.vue

@@ -0,0 +1,133 @@
+<script setup lang="ts">
+/**
+ * SweepModal — the Context Loop's Sweep settings, opened from the node's
+ * "Sweep combinations" button (same pattern as Per-iteration seeds).
+ *
+ * Hosts SweepPanel for the controls and lists the frames the sweep will
+ * run, so the grid can be checked before anything is queued.
+ */
+import { computed } from "vue";
+import ModalShell from "../shared/ModalShell.vue";
+import SweepPanel from "./SweepPanel.vue";
+import { liveAxes, sweepTotal, type SweepConfig } from "./types";
+import type { SweepCandidate } from "./sweep-candidates";
+
+const props = withDefaults(
+  defineProps<{
+    modelValue: SweepConfig;
+    candidates?: SweepCandidate[];
+    loopBypassed?: boolean;
+  }>(),
+  { candidates: () => [], loopBypassed: false },
+);
+
+const emit = defineEmits<{
+  "update:modelValue": [next: SweepConfig];
+  close: [];
+}>();
+
+/** Frames shown in the preview; the rest are summarised in one line. */
+const PREVIEW_MAX = 40;
+
+const total = computed(() => sweepTotal(props.modelValue.axes));
+const frameCount = computed(() => Math.min(total.value, props.modelValue.limit));
+
+/** Option text per axis, in the axis's order (unknown ids keep their id). */
+const axisLabels = computed(() =>
+  liveAxes(props.modelValue.axes).map((a) => {
+    const c = props.candidates.find((x) => x.uid === a.uid);
+    return a.option_ids.map((id) => c?.options.find((o) => o.id === id)?.label || id);
+  }),
+);
+
+/** Row-major, last axis fastest: the same order the engine runs. */
+const preview = computed(() => {
+  if (!props.modelValue.enabled || !axisLabels.value.length) return [];
+  const labels = axisLabels.value;
+  const n = Math.min(frameCount.value, PREVIEW_MAX);
+  const rows: string[][] = [];
+  for (let f = 0; f < n; f++) {
+    let rest = f;
+    const row: string[] = new Array(labels.length);
+    for (let i = labels.length - 1; i >= 0; i--) {
+      const len = labels[i].length;
+      row[i] = labels[i][rest % len];
+      rest = Math.floor(rest / len);
+    }
+    rows.push(row);
+  }
+  return rows;
+});
+</script>
+
+<template>
+  <ModalShell :visible="true" @close="emit('close')">
+    <div class="wp-swm" data-test="sweep-modal">
+      <div class="wp-swm__head">
+        <span class="wp-swm__head-icon"><svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><rect x="4" y="4" width="6" height="6" rx="1" /><rect x="14" y="4" width="6" height="6" rx="1" /><rect x="4" y="14" width="6" height="6" rx="1" /><rect x="14" y="14" width="6" height="6" rx="1" /></svg></span>
+        <div class="wp-swm__title-block">
+          <div class="wp-swm__title-row"><span class="wp-swm__name">WP Context Loop</span><span class="wp-swm__chip">Sweep</span></div>
+          <div class="wp-swm__sub">Run every combination of the wildcards you pick, one frame each.</div>
+        </div>
+        <button type="button" class="wp-swm__close" data-test="sweep-modal-close" aria-label="Close" @click="emit('close')">
+          <svg width="12" height="12" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.4" stroke-linecap="round"><path d="M5 5l14 14M19 5L5 19" /></svg>
+        </button>
+      </div>
+
+      <div class="wp-swm__body">
+        <SweepPanel
+          :model-value="modelValue"
+          :candidates="candidates"
+          :loop-bypassed="loopBypassed"
+          @update:model-value="(v) => emit('update:modelValue', v)"
+        />
+
+        <div v-if="preview.length" class="wp-swm__frames" data-test="sweep-preview">
+          <div class="wp-swm__frames-label">Frames</div>
+          <div v-for="(row, i) in preview" :key="i" class="wp-swm__frame">
+            <span class="wp-swm__frame-n">#{{ i + 1 }}</span>
+            <span class="wp-swm__frame-vals">{{ row.join(" · ") }}</span>
+          </div>
+          <div v-if="frameCount > preview.length" class="wp-swm__frame-more">
+            … and {{ frameCount - preview.length }} more
+          </div>
+        </div>
+      </div>
+
+      <div class="wp-swm__foot">
+        <span class="wp-swm__foot-hint">Changes save as you make them.</span>
+        <span class="wp-swm__spacer" />
+        <button type="button" class="wp-swm__btn" data-test="sweep-modal-done" @click="emit('close')">Done</button>
+      </div>
+    </div>
+  </ModalShell>
+</template>
+
+<style scoped>
+@import "../shared/theme.css";
+
+.wp-swm { width: 520px; max-width: 100%; max-height: 86vh; display: flex; flex-direction: column; background: var(--wp-bg2); border: 1px solid var(--wp-border); border-radius: 6px; overflow: hidden; color: var(--wp-text); font-size: 12px; box-shadow: 0 18px 50px rgba(0,0,0,.55); }
+.wp-swm__head { display: flex; align-items: center; gap: 10px; padding: 12px 14px; flex-shrink: 0; border-bottom: 1px solid var(--wp-border); background: linear-gradient(180deg, color-mix(in srgb, var(--wp-accent) 18%, var(--wp-bg2)) 0%, var(--wp-bg2) 100%); }
+.wp-swm__head-icon { color: var(--wp-accent); width: 24px; display: flex; justify-content: center; }
+.wp-swm__title-block { flex: 1; min-width: 0; }
+.wp-swm__title-row { display: flex; align-items: center; gap: 8px; }
+.wp-swm__name { font: 600 13px var(--wp-font-sans); }
+.wp-swm__chip { font: 600 9px var(--wp-font-sans); text-transform: uppercase; letter-spacing: .06em; padding: 2px 6px; border-radius: 2px; background: color-mix(in srgb, var(--wp-accent) 22%, transparent); color: var(--wp-accent); }
+.wp-swm__sub { font: 10.5px var(--wp-font-sans); color: var(--wp-text-dim, var(--wp-text3)); margin-top: 3px; }
+.wp-swm__close { background: transparent; border: 0; color: var(--wp-text-dim, var(--wp-text3)); cursor: pointer; padding: 4px; display: flex; }
+.wp-swm__close:hover { color: var(--wp-text); }
+
+.wp-swm__body { overflow-y: auto; padding: 12px 14px; flex: 1; min-height: 0; display: flex; flex-direction: column; gap: 12px; font-size: 11px; }
+
+.wp-swm__frames { border: 1px solid var(--wp-border); border-radius: 4px; padding: 6px 8px; background: var(--wp-bg-deep, var(--wp-bg)); }
+.wp-swm__frames-label { font: 600 9px var(--wp-font-sans); text-transform: uppercase; letter-spacing: .08em; color: var(--wp-text-dim, var(--wp-text3)); margin-bottom: 4px; }
+.wp-swm__frame { display: flex; gap: 10px; padding: 2px 0; font: 11px var(--wp-font-mono, monospace); }
+.wp-swm__frame-n { width: 32px; flex-shrink: 0; color: var(--wp-text-dim, var(--wp-text3)); text-align: right; }
+.wp-swm__frame-vals { color: var(--wp-text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.wp-swm__frame-more { padding: 4px 0 0 42px; font: 10.5px var(--wp-font-sans); color: var(--wp-text-dim, var(--wp-text3)); }
+
+.wp-swm__foot { display: flex; align-items: center; gap: 12px; padding: 10px 14px; flex-shrink: 0; background: var(--wp-bg3); border-top: 1px solid var(--wp-border); }
+.wp-swm__foot-hint { font: 10px var(--wp-font-sans); color: var(--wp-text-dim, var(--wp-text3)); }
+.wp-swm__spacer { flex: 1; }
+.wp-swm__btn { padding: 6px 14px; border: 1px solid var(--wp-accent); border-radius: 3px; background: var(--wp-accent); color: #fff; font: 11px var(--wp-font-sans); cursor: pointer; }
+</style>

src/components/context-loop/SweepPanel.vue

@@ -0,0 +1,381 @@
+<script setup lang="ts">
+/**
+ * SweepPanel — the Sweep section of the Context Loop widget.
+ *
+ * Pick downstream wildcards and which of their options to walk; the loop
+ * then runs every combination, one frame each, up to `limit`. The panel
+ * shows the frame total before anything runs. Value contract mirrors the
+ * parent: `modelValue` is the `SweepConfig`, every change emits a new one.
+ */
+import { computed, ref } from "vue";
+import {
+  SWEEP_MAX_LIMIT,
+  liveAxes,
+  sweepTotal,
+  type SweepAxis,
+  type SweepConfig,
+} from "./types";
+import { axisStatus, type SweepCandidate } from "./sweep-candidates";
+
+const props = withDefaults(
+  defineProps<{
+    modelValue: SweepConfig;
+    candidates?: SweepCandidate[];
+    /** Whole-loop bypass is on, so the sweep is ignored this run. */
+    loopBypassed?: boolean;
+  }>(),
+  { candidates: () => [], loopBypassed: false },
+);
+
+const emit = defineEmits<{ "update:modelValue": [next: SweepConfig] }>();
+
+const HOLD_TOOLTIP =
+  "When ON, everything you are not sweeping keeps the same pick on every " +
+  "frame, so only the swept wildcards change. When OFF, the rest re-rolls " +
+  "per frame as in a normal loop.";
+
+/** uid of the axis whose option list is open. */
+const openUid = ref<string | null>(null);
+
+function patch(next: Partial<SweepConfig>): void {
+  emit("update:modelValue", { ...props.modelValue, ...next });
+}
+
+const rows = computed(() =>
+  props.modelValue.axes.map((axis) => ({ axis, ...axisStatus(axis, props.candidates) })),
+);
+
+const live = computed(() => liveAxes(props.modelValue.axes));
+const total = computed(() => sweepTotal(props.modelValue.axes));
+const frames = computed(() => Math.min(total.value, props.modelValue.limit));
+const capped = computed(() => total.value > props.modelValue.limit);
+
+const available = computed(() => {
+  const used = new Set(props.modelValue.axes.map((a) => a.uid));
+  return props.candidates.filter((c) => !used.has(c.uid));
+});
+
+function axisName(row: (typeof rows.value)[number]): string {
+  if (row.candidate) return `$${row.candidate.binding || row.candidate.name}`;
+  return row.axis.label ?? row.axis.uid;
+}
+
+function toggleEnabled(): void {
+  patch({ enabled: !props.modelValue.enabled });
+}
+
+function toggleHold(): void {
+  patch({ hold_others: !props.modelValue.hold_others });
+}
+
+function setLimit(n: number): void {
+  patch({ limit: Math.min(SWEEP_MAX_LIMIT, Math.max(1, n)) });
+}
+
+function onLimit(ev: Event): void {
+  const n = Math.round(Number((ev.target as HTMLInputElement).value));
+  if (!Number.isFinite(n)) return;
+  setLimit(n);
+}
+
+function addAxis(ev: Event): void {
+  const sel = ev.target as HTMLSelectElement;
+  const c = props.candidates.find((x) => x.uid === sel.value);
+  sel.value = "";
+  if (!c) return;
+  const axis: SweepAxis = {
+    uid: c.uid,
+    option_ids: [...c.defaultIds],
+    label: `$${c.binding || c.name}`,
+  };
+  patch({ axes: [...props.modelValue.axes, axis] });
+  openUid.value = c.uid;
+}
+
+function removeAxis(uid: string): void {
+  patch({ axes: props.modelValue.axes.filter((a) => a.uid !== uid) });
+  if (openUid.value === uid) openUid.value = null;
+}
+
+function setAxisIds(uid: string, ids: string[]): void {
+  // An empty axis is allowed: it sweeps nothing until an option is ticked.
+  patch({
+    axes: props.modelValue.axes.map((a) => (a.uid === uid ? { ...a, option_ids: ids } : a)),
+  });
+}
+
+function toggleOption(axis: SweepAxis, id: string, candidate: SweepCandidate): void {
+  const on = new Set(axis.option_ids);
+  if (on.has(id)) on.delete(id);
+  else on.add(id);
+  // Keep the wildcard's own option order so frames read top to bottom.
+  setAxisIds(axis.uid, candidate.options.map((o) => o.id).filter((x) => on.has(x)));
+}
+
+function selectAll(axis: SweepAxis, candidate: SweepCandidate): void {
+  setAxisIds(axis.uid, candidate.options.map((o) => o.id));
+}
+
+function selectNone(axis: SweepAxis): void {
+  setAxisIds(axis.uid, []);
+}
+
+function selectDefault(axis: SweepAxis, candidate: SweepCandidate): void {
+  setAxisIds(axis.uid, [...candidate.defaultIds]);
+}
+
+function moveAxis(uid: string, dir: -1 | 1): void {
+  const axes = [...props.modelValue.axes];
+  const i = axes.findIndex((a) => a.uid === uid);
+  const j = i + dir;
+  if (i < 0 || j < 0 || j >= axes.length) return;
+  [axes[i], axes[j]] = [axes[j], axes[i]];
+  patch({ axes });
+}
+</script>
+
+<template>
+  <div class="wp-sweep" :class="{ 'wp-sweep--on': modelValue.enabled }">
+    <div class="wp-sweep__row">
+      <span class="wp-sweep__row-label">Sweep combinations</span>
+      <button
+        type="button"
+        class="wp-sweep__switch"
+        :class="{ 'wp-sweep__switch--on': modelValue.enabled }"
+        data-test="sweep-toggle"
+        :aria-pressed="modelValue.enabled"
+        :aria-label="`Sweep combinations: ${modelValue.enabled ? 'on' : 'off'}`"
+        title="Run every combination of the wildcards you pick, one frame each."
+        @click="toggleEnabled"
+      >
+        <span class="wp-sweep__switch-thumb" />
+      </button>
+    </div>
+
+    <template v-if="modelValue.enabled">
+      <div v-if="modelValue.axes.length" class="wp-sweep__total" :class="{ 'wp-sweep__total--warn': capped }" data-test="sweep-total">
+        <template v-if="loopBypassed">Loop is bypassed, so the sweep is ignored.</template>
+        <template v-else-if="!live.length">Tick at least one option to sweep.</template>
+        <template v-else>
+          <template v-if="live.length > 1">
+            <span class="wp-sweep__math">{{ live.map((a) => a.option_ids.length).join(" × ") }}</span> =
+          </template>
+          <strong>{{ total }}</strong> {{ total === 1 ? "combination" : "combinations" }}<template v-if="capped">; the limit runs the first <strong>{{ frames }}</strong></template>
+        </template>
+      </div>
+      <div v-else class="wp-sweep__hint" data-test="sweep-empty">
+        {{ candidates.length
+          ? "Add a wildcard to sweep. Its options become the frames."
+          : "No wildcards downstream. Wire this loop into a WP Context that has one." }}
+      </div>
+
+      <div
+        v-for="(row, i) in rows"
+        :key="row.axis.uid"
+        class="wp-sweep__axis"
+        :class="{ 'wp-sweep__axis--missing': row.missing }"
+        :data-test="`sweep-axis-${row.axis.uid}`"
+      >
+        <div class="wp-sweep__axis-head">
+          <button
+            type="button"
+            class="wp-sweep__axis-name"
+            :disabled="row.missing"
+            :aria-expanded="openUid === row.axis.uid"
+            :title="row.missing ? 'This wildcard is no longer downstream of the loop.' : 'Choose which options to sweep'"
+            @click="openUid = openUid === row.axis.uid ? null : row.axis.uid"
+          >
+            <span class="wp-sweep__axis-var">{{ axisName(row) }}</span>
+            <span v-if="row.candidate" class="wp-sweep__axis-node">{{ row.candidate.nodeLabel }}</span>
+            <span v-if="row.missing" class="wp-sweep__axis-node">missing</span>
+          </button>
+          <span class="wp-sweep__axis-count" :title="row.staleIds.length ? `${row.staleIds.length} picked option(s) no longer exist; those frames roll normally` : ''">
+            {{ row.axis.option_ids.length }}<template v-if="row.candidate">/{{ row.candidate.options.length }}</template>
+            <i v-if="row.staleIds.length" class="pi pi-exclamation-triangle wp-sweep__warn-ico" aria-hidden="true" />
+          </span>
+          <button v-if="modelValue.axes.length > 1" type="button" class="wp-sweep__icon" :disabled="i === 0" title="Move up (changes slower)" @click="moveAxis(row.axis.uid, -1)">
+            <i class="pi pi-arrow-up" aria-hidden="true" />
+          </button>
+          <button type="button" class="wp-sweep__icon" title="Stop sweeping this wildcard" :data-test="`sweep-remove-${row.axis.uid}`" @click="removeAxis(row.axis.uid)">
+            <i class="pi pi-times" aria-hidden="true" />
+          </button>
+        </div>
+        <div v-if="openUid === row.axis.uid && row.candidate" class="wp-sweep__opts">
+          <div class="wp-sweep__opts-bar">
+            <button type="button" class="wp-sweep__link" data-test="sweep-all" @click="selectAll(row.axis, row.candidate)">all</button>
+            <button type="button" class="wp-sweep__link" data-test="sweep-none" @click="selectNone(row.axis)">none</button>
+            <button type="button" class="wp-sweep__link" @click="selectDefault(row.axis, row.candidate)">enabled only</button>
+          </div>
+          <div class="wp-sweep__opts-list">
+            <button
+              v-for="o in row.candidate.options"
+              :key="o.id"
+              type="button"
+              class="wp-sweep__opt"
+              :class="{ 'wp-sweep__opt--on': row.axis.option_ids.includes(o.id) }"
+              :aria-pressed="row.axis.option_ids.includes(o.id)"
+              :title="o.label"
+              :data-test="`sweep-opt-${o.id}`"
+              @click="toggleOption(row.axis, o.id, row.candidate)"
+            >
+              {{ o.label || "(empty)" }}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      <select
+        v-if="available.length"
+        class="wp-sweep__add"
+        data-test="sweep-add"
+        value=""
+        aria-label="Add a wildcard to sweep"
+        @change="addAxis"
+      >
+        <option value="" disabled>+ Sweep a wildcard…</option>
+        <option v-for="c in available" :key="c.uid" :value="c.uid">
+          ${{ c.binding || c.name }} · {{ c.nodeLabel }} ({{ c.options.length }})
+        </option>
+      </select>
+
+      <div class="wp-sweep__row">
+        <span class="wp-sweep__row-label">Limit</span>
+        <span class="wp-sweep__limit-wrap">
+          <input
+            type="number"
+            class="wp-sweep__limit"
+            min="1"
+            :max="SWEEP_MAX_LIMIT"
+            :value="modelValue.limit"
+            data-test="sweep-limit"
+            aria-label="Most frames a sweep runs"
+            @change="onLimit"
+          />
+          <span class="wp-sweep__spin">
+            <button type="button" class="wp-sweep__spin-btn" tabindex="-1" aria-label="Increase limit" data-test="sweep-limit-up" @click="setLimit(modelValue.limit + 1)">
+              <svg width="6" height="4" viewBox="0 0 8 5"><path d="M0 5 L4 0 L8 5 Z" fill="currentColor" /></svg></button>
+            <button type="button" class="wp-sweep__spin-btn" tabindex="-1" aria-label="Decrease limit" data-test="sweep-limit-down" @click="setLimit(modelValue.limit - 1)">
+              <svg width="6" height="4" viewBox="0 0 8 5"><path d="M0 0 L4 5 L8 0 Z" fill="currentColor" /></svg></button>
+          </span>
+        </span>
+      </div>
+      <div class="wp-sweep__row" :title="HOLD_TOOLTIP">
+        <span class="wp-sweep__row-label">Hold other picks</span>
+        <button
+          type="button"
+          class="wp-sweep__switch"
+          :class="{ 'wp-sweep__switch--on': modelValue.hold_others }"
+          data-test="sweep-hold-toggle"
+          :aria-pressed="modelValue.hold_others"
+          :aria-label="`Hold other picks: ${modelValue.hold_others ? 'on' : 'off'}`"
+          @click="toggleHold"
+        >
+          <span class="wp-sweep__switch-thumb" />
+        </button>
+      </div>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+@import "../shared/theme.css";
+
+.wp-sweep { display: flex; flex-direction: column; gap: 6px; }
+.wp-sweep--on {
+  padding: 6px 7px;
+  border: 1px solid color-mix(in srgb, var(--wp-accent, #c4b5fd) 35%, var(--wp-border, #353841));
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--wp-accent, #c4b5fd) 5%, transparent);
+}
+.wp-sweep__row { display: flex; justify-content: space-between; align-items: center; gap: 8px; }
+.wp-sweep__row-label { font: 10px var(--wp-font-sans, sans-serif); color: var(--wp-text-muted, #aeb1bb); }
+
+.wp-sweep__switch {
+  width: 32px; height: 18px; border-radius: 9px; position: relative; padding: 0; cursor: pointer; flex-shrink: 0;
+  background: var(--wp-bg-deep, var(--wp-bg, #0e1015));
+  border: 1px solid var(--wp-border, #353841);
+}
+.wp-sweep__switch-thumb {
+  position: absolute; top: 1px; left: 1px; width: 14px; height: 14px; border-radius: 50%;
+  background: var(--wp-text-dim, #7a7d88);
+  transition: left var(--wp-motion-hover, 120ms) ease;
+}
+.wp-sweep__switch--on {
+  background: color-mix(in srgb, var(--wp-accent, #c4b5fd) 22%, transparent);
+  border-color: var(--wp-accent, #c4b5fd);
+}
+.wp-sweep__switch--on .wp-sweep__switch-thumb { left: 15px; background: var(--wp-accent, #c4b5fd); }
+
+.wp-sweep__total { font: 10.5px var(--wp-font-sans, sans-serif); color: var(--wp-text); }
+.wp-sweep__total strong { color: var(--wp-accent, #c4b5fd); }
+.wp-sweep__total--warn strong:last-child { color: var(--wp-warning, #f59e0b); }
+.wp-sweep__math { font-family: var(--wp-font-mono, monospace); color: var(--wp-text-muted, #aeb1bb); }
+.wp-sweep__hint { font: 10px var(--wp-font-sans, sans-serif); color: var(--wp-text-dim, #7a7d88); }
+
+.wp-sweep__axis {
+  border: 1px solid var(--wp-border, #353841);
+  border-radius: 3px;
+  background: var(--wp-bg-deep, var(--wp-bg, #0e1015));
+}
+.wp-sweep__axis--missing { border-style: dashed; opacity: .75; }
+.wp-sweep__axis-head { display: flex; align-items: center; gap: 4px; padding: 3px 4px 3px 6px; }
+.wp-sweep__axis-name {
+  flex: 1; min-width: 0; display: flex; align-items: baseline; gap: 6px;
+  background: none; border: 0; padding: 0; cursor: pointer; text-align: left; color: var(--wp-text);
+}
+.wp-sweep__axis-name:disabled { cursor: default; }
+.wp-sweep__axis-var { font: 600 11px var(--wp-font-mono, monospace); color: var(--wp-accent, #c4b5fd); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.wp-sweep__axis-node { font: 9.5px var(--wp-font-sans, sans-serif); color: var(--wp-text-dim, #7a7d88); white-space: nowrap; }
+.wp-sweep__axis--missing .wp-sweep__axis-node { color: var(--wp-warning, #f59e0b); }
+.wp-sweep__axis-count { font: 10px var(--wp-font-mono, monospace); color: var(--wp-text-muted, #aeb1bb); white-space: nowrap; }
+.wp-sweep__warn-ico { font-size: 9px; color: var(--wp-warning, #f59e0b); margin-left: 2px; }
+.wp-sweep__icon {
+  width: 18px; height: 18px; display: inline-flex; align-items: center; justify-content: center; padding: 0;
+  background: transparent; border: 1px solid transparent; border-radius: 3px; cursor: pointer;
+  color: var(--wp-text-dim, #7a7d88);
+}
+.wp-sweep__icon:hover:not(:disabled) { color: var(--wp-text); border-color: var(--wp-border, #353841); }
+.wp-sweep__icon:disabled { opacity: .35; cursor: default; }
+.wp-sweep__icon .pi { font-size: 9px; }
+
+.wp-sweep__opts { border-top: 1px solid var(--wp-border, #353841); padding: 4px 6px 6px; }
+.wp-sweep__opts-bar { display: flex; gap: 10px; margin-bottom: 4px; }
+.wp-sweep__link {
+  background: none; border: 0; padding: 0; cursor: pointer;
+  font: 600 9px var(--wp-font-sans, sans-serif); text-transform: uppercase; letter-spacing: .06em;
+  color: var(--wp-text-dim, #7a7d88);
+}
+.wp-sweep__link:hover { color: var(--wp-accent, #c4b5fd); }
+.wp-sweep__opts-list { display: flex; flex-wrap: wrap; gap: 3px; max-height: 120px; overflow-y: auto; }
+.wp-sweep__opt {
+  max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  padding: 2px 6px; border-radius: 3px; cursor: pointer;
+  font: 10px var(--wp-font-sans, sans-serif);
+  background: transparent; border: 1px solid var(--wp-border, #353841); color: var(--wp-text-dim, #7a7d88);
+}
+.wp-sweep__opt--on {
+  background: color-mix(in srgb, var(--wp-accent, #c4b5fd) 16%, transparent);
+  border-color: var(--wp-accent, #c4b5fd);
+  color: var(--wp-text);
+}
+
+.wp-sweep__add, .wp-sweep__limit-wrap {
+  background: var(--wp-bg-deep, var(--wp-bg, #0e1015));
+  border: 1px solid var(--wp-border, #353841);
+  border-radius: 3px;
+  color: var(--wp-text-muted, #aeb1bb);
+  font: 10.5px var(--wp-font-sans, sans-serif);
+}
+.wp-sweep__add { width: 100%; padding: 4px 5px; cursor: pointer; }
+/* Custom ± arrows, same as the seed rows (SeedLockRow): the native spinner
+ * sat on top of the right-aligned value. */
+.wp-sweep__limit-wrap { display: inline-flex; align-items: stretch; width: 64px; height: 20px; overflow: hidden; }
+.wp-sweep__limit-wrap:focus-within { border-color: var(--wp-accent); }
+.wp-sweep__limit { flex: 1; min-width: 0; background: transparent; border: 0; padding: 0 5px; color: inherit; font: 10.5px var(--wp-font-mono, monospace); text-align: right; -moz-appearance: textfield; appearance: textfield; }
+.wp-sweep__limit:focus { outline: none; }
+.wp-sweep__limit::-webkit-outer-spin-button, .wp-sweep__limit::-webkit-inner-spin-button { -webkit-appearance: none; margin: 0; }
+.wp-sweep__spin { display: flex; flex-direction: column; width: 14px; flex-shrink: 0; border-left: 1px solid var(--wp-border, #353841); background: rgba(99,102,241,.04); }
+.wp-sweep__spin-btn { flex: 1; display: flex; align-items: center; justify-content: center; background: transparent; border: 0; padding: 0; color: var(--wp-text-dim, #7a7d88); cursor: pointer; line-height: 0; }
+.wp-sweep__spin-btn + .wp-sweep__spin-btn { border-top: 1px solid var(--wp-border, #353841); }
+.wp-sweep__spin-btn:hover { color: var(--wp-accent-text, var(--wp-text)); background: rgba(99,102,241,.12); }
+</style>

src/components/context-loop/sweep-candidates.ts

@@ -0,0 +1,119 @@
+/**
+ * Wildcards a Context Loop can sweep: every enabled wildcard instance in the
+ * WP_Context nodes downstream of the loop. Pure — the widget glue walks the
+ * graph and hands each node's parsed module list in here.
+ */
+import {
+  buildBundleEnabledMap,
+  isModuleEffectivelyEnabled,
+  parseWidgetJson,
+  type ContextWidgetValue,
+} from "../../widgets/_shared";
+import type { SweepAxis } from "./types";
+
+export interface SweepOption {
+  id: string;
+  /** Option text, or "(nothing)" for the null option. */
+  label: string;
+}
+
+export interface SweepCandidate {
+  uid: string;
+  /** Card title in the Context node. */
+  name: string;
+  /** The variable the wildcard writes, without `$`. */
+  binding: string;
+  /** Codename of the Context node holding it. */
+  nodeLabel: string;
+  options: SweepOption[];
+  /** What a new axis selects: the options this instance can roll today
+   *  (its enabled set, null option left out). */
+  defaultIds: string[];
+}
+
+/** A downstream Context node as the widget glue reads it off the graph. */
+export interface SweepSourceRaw {
+  /** Codename of the Context node. */
+  label: string;
+  /** The node's `wp_modules` widget value (module list JSON). */
+  raw: string;
+}
+
+/** Parse the raw downstream nodes' module lists. */
+export function sweepSourcesFromRaw(nodes: readonly SweepSourceRaw[]): SweepSourceNode[] {
+  return nodes.map((n) => ({
+    label: n.label,
+    value: parseWidgetJson<ContextWidgetValue>(n.raw, { version: 1, modules: [] }),
+  }));
+}
+
+export interface SweepSourceNode {
+  label: string;
+  value: ContextWidgetValue;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+export function collectSweepCandidates(nodes: readonly SweepSourceNode[]): SweepCandidate[] {
+  const out: SweepCandidate[] = [];
+  const seen = new Set<string>();
+  for (const n of nodes) {
+    const bundles = buildBundleEnabledMap(n.value.bundles);
+    for (const m of n.value.modules ?? []) {
+      if (m.type !== "wildcard" || !m._uid || seen.has(m._uid)) continue;
+      if (!isModuleEffectivelyEnabled(m, bundles)) continue;
+      const payload = m.payload ?? {};
+      const rawOptions = Array.isArray(payload.options) ? payload.options : [];
+      const options: SweepOption[] = [];
+      const defaults: string[] = [];
+      const enabled = m.instance?.enabled_options;
+      const enabledSet = Array.isArray(enabled) ? new Set(enabled) : null;
+      for (const o of rawOptions) {
+        if (!o || typeof o !== "object") continue;
+        const opt = o as Record<string, unknown>;
+        const id = str(opt.id);
+        if (!id) continue;
+        const isNull = opt.is_null === true;
+        options.push({ id, label: isNull ? "(nothing)" : str(opt.value) });
+        if (!isNull && (!enabledSet || enabledSet.has(id))) defaults.push(id);
+      }
+      if (!options.length) continue;
+      seen.add(m._uid);
+      out.push({
+        uid: m._uid,
+        name: m.meta?.name || str(payload.var_binding) || "wildcard",
+        binding: m.instance?.variable_binding || str(payload.var_binding),
+        nodeLabel: n.label,
+        options,
+        defaultIds: defaults.length ? defaults : options.map((o) => o.id),
+      });
+    }
+  }
+  return out;
+}
+
+/** How an axis lines up with what is downstream right now. `missing` means
+ *  its wildcard is gone (the loop would repeat frames for nothing);
+ *  `staleIds` are picked options the wildcard no longer has (those frames
+ *  roll normally instead of pinning). */
+export interface AxisStatus {
+  candidate: SweepCandidate | null;
+  missing: boolean;
+  staleIds: string[];
+}
+
+export function axisStatus(
+  axis: SweepAxis,
+  candidates: readonly SweepCandidate[],
+): AxisStatus {
+  const candidate = candidates.find((c) => c.uid === axis.uid) ?? null;
+  if (!candidate) return { candidate, missing: true, staleIds: [] };
+  const known = new Set(candidate.options.map((o) => o.id));
+  return {
+    candidate,
+    missing: false,
+    staleIds: axis.option_ids.filter((id) => !known.has(id)),
+  };
+}

src/components/context-loop/sweep.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from "vitest";
+import { mount } from "@vue/test-utils";
+import SweepPanel from "./SweepPanel.vue";
+import ContextLoopWidget from "./ContextLoopWidget.vue";
+import SweepModal from "./SweepModal.vue";
+import {
+  emptyContextLoopConfig,
+  emptySweepConfig,
+  parseContextLoopConfig,
+  parseSweep,
+  sweepFrameCount,
+  sweepTotal,
+  type SweepConfig,
+} from "./types";
+import {
+  axisStatus,
+  collectSweepCandidates,
+  sweepSourcesFromRaw,
+  type SweepCandidate,
+} from "./sweep-candidates";
+import type { ContextWidgetValue, ModuleEntry } from "../../widgets/_shared";
+
+function wildcard(uid: string, binding: string, values: string[], extra: Partial<ModuleEntry> = {}): ModuleEntry {
+  return {
+    id: `lib-${uid}`,
+    _uid: uid,
+    type: "wildcard",
+    enabled: true,
+    meta: { name: binding },
+    entries: [],
+    payload: {
+      var_binding: binding,
+      options: values.map((v, i) => ({ id: `${binding}${i}`, value: v, weight: 1 })),
+    },
+    ...extra,
+  } as ModuleEntry;
+}
+
+describe("parseSweep", () => {
+  it("defaults for garbage", () => {
+    for (const raw of [null, "x", [], 3]) expect(parseSweep(raw)).toEqual(emptySweepConfig());
+  });
+
+  it("matches the Python parser on bad axes", () => {
+    const out = parseSweep({
+      enabled: true,
+      limit: 5000,
+      hold_others: false,
+      axes: [
+        { uid: "a1", option_ids: ["x", "x", "", 3, "y"], label: "hair" },
+        { uid: "a1", option_ids: ["z"] },
+        { uid: "", option_ids: ["z"] },
+        { uid: "b2", option_ids: [] },
+        "junk",
+      ],
+    });
+    expect(out).toEqual({
+      enabled: true,
+      limit: 999,
+      hold_others: false,
+      axes: [{ uid: "a1", option_ids: ["x", "y"], label: "hair" }, { uid: "b2", option_ids: [] }],
+    });
+    expect(parseSweep({ limit: 0 }).limit).toBe(1);
+    expect(parseSweep({ limit: 2.5 }).limit).toBe(64);
+  });
+
+  it("survives a loop config round trip", () => {
+    const cfg = parseContextLoopConfig(JSON.stringify({
+      sweep: { enabled: true, axes: [{ uid: "u1", option_ids: ["a", "b"] }] },
+    }));
+    expect(cfg.sweep.axes).toEqual([{ uid: "u1", option_ids: ["a", "b"] }]);
+    expect(parseContextLoopConfig("{}").sweep).toEqual(emptySweepConfig());
+  });
+});
+
+describe("sweep frame count", () => {
+  const axes = [{ uid: "a", option_ids: ["1", "2"] }, { uid: "b", option_ids: ["1", "2", "3"] }];
+
+  it("multiplies the axes and caps at the limit", () => {
+    expect(sweepTotal(axes)).toBe(6);
+    const cfg = { ...emptyContextLoopConfig(), sweep: { ...emptySweepConfig(), enabled: true, axes } };
+    expect(sweepFrameCount(cfg)).toBe(6);
+    expect(sweepFrameCount({ ...cfg, sweep: { ...cfg.sweep, limit: 4 } })).toBe(4);
+  });
+
+  it("is null when off, empty or the loop is bypassed", () => {
+    const on = { ...emptyContextLoopConfig(), sweep: { ...emptySweepConfig(), enabled: true, axes } };
+    expect(sweepFrameCount(emptyContextLoopConfig())).toBeNull();
+    expect(sweepFrameCount({ ...on, sweep: { ...on.sweep, axes: [] } })).toBeNull();
+    expect(sweepFrameCount({ ...on, bypass: true })).toBeNull();
+  });
+});
+
+describe("collectSweepCandidates", () => {
+  it("lists enabled downstream wildcards with their enabled options preselected", () => {
+    const value: ContextWidgetValue = {
+      version: 1,
+      modules: [
+        wildcard("u1", "hair", ["red", "blue", "green"], {
+          instance: { enabled_options: ["hair0", "hair2"], variable_binding: "hair_color" },
+        }),
+        wildcard("u2", "mood", ["calm"], { enabled: false }),
+        { ...wildcard("u3", "pose", []), payload: { var_binding: "pose", options: [{ id: "n", value: "", is_null: true }, { id: "p0", value: "sit" }] } },
+        { id: "f", _uid: "f1", type: "fixed_values", enabled: true, meta: { name: "f" }, entries: [] } as ModuleEntry,
+      ],
+    };
+    const out = collectSweepCandidates([{ label: "amber-fox", value }]);
+    expect(out.map((c) => c.uid)).toEqual(["u1", "u3"]);
+    expect(out[0]).toMatchObject({ binding: "hair_color", nodeLabel: "amber-fox", defaultIds: ["hair0", "hair2"] });
+    expect(out[1].options).toEqual([{ id: "n", label: "(nothing)" }, { id: "p0", label: "sit" }]);
+    expect(out[1].defaultIds).toEqual(["p0"]);
+  });
+
+  it("reports missing wildcards and stale options", () => {
+    const cands = collectSweepCandidates([{ label: "x", value: { version: 1, modules: [wildcard("u1", "hair", ["a", "b"])] } }]);
+    expect(axisStatus({ uid: "gone", option_ids: ["a"] }, cands).missing).toBe(true);
+    expect(axisStatus({ uid: "u1", option_ids: ["hair0", "old"] }, cands).staleIds).toEqual(["old"]);
+  });
+});
+
+const CANDS: SweepCandidate[] = [
+  { uid: "u1", name: "hair", binding: "hair", nodeLabel: "amber-fox", options: [{ id: "h0", label: "red" }, { id: "h1", label: "blue" }, { id: "h2", label: "green" }], defaultIds: ["h0", "h1"] },
+  { uid: "u2", name: "mood", binding: "mood", nodeLabel: "amber-fox", options: [{ id: "m0", label: "calm" }, { id: "m1", label: "sad" }], defaultIds: ["m0", "m1"] },
+];
+
+function on(axes: SweepConfig["axes"] = [], extra: Partial<SweepConfig> = {}): SweepConfig {
+  return { ...emptySweepConfig(), enabled: true, axes, ...extra };
+}
+
+function lastEmit(w: ReturnType<typeof mount>): SweepConfig {
+  const all = w.emitted("update:modelValue") ?? [];
+  return all[all.length - 1][0] as SweepConfig;
+}
+
+describe("SweepPanel", () => {
+  it("is just a switch while off", async () => {
+    const w = mount(SweepPanel, { props: { modelValue: emptySweepConfig(), candidates: CANDS } });
+    expect(w.find('[data-test="sweep-add"]').exists()).toBe(false);
+    await w.find('[data-test="sweep-toggle"]').trigger("click");
+    expect(lastEmit(w).enabled).toBe(true);
+  });
+
+  it("explains an empty graph", () => {
+    const w = mount(SweepPanel, { props: { modelValue: on(), candidates: [] } });
+    expect(w.find('[data-test="sweep-empty"]').text()).toContain("No wildcards downstream");
+  });
+
+  it("adds a wildcard with its enabled options", async () => {
+    const w = mount(SweepPanel, { props: { modelValue: on(), candidates: CANDS } });
+    const sel = w.find('[data-test="sweep-add"]');
+    (sel.element as HTMLSelectElement).value = "u1";
+    await sel.trigger("change");
+    expect(lastEmit(w).axes).toEqual([{ uid: "u1", option_ids: ["h0", "h1"], label: "$hair" }]);
+  });
+
+  it("shows the total and the cap", () => {
+    const axes = [{ uid: "u1", option_ids: ["h0", "h1", "h2"] }, { uid: "u2", option_ids: ["m0", "m1"] }];
+    const w = mount(SweepPanel, { props: { modelValue: on(axes), candidates: CANDS } });
+    expect(w.find('[data-test="sweep-total"]').text()).toContain("3 × 2 = 6 combinations");
+    const capped = mount(SweepPanel, { props: { modelValue: on(axes, { limit: 4 }), candidates: CANDS } });
+    expect(capped.find('[data-test="sweep-total"]').text()).toContain("the limit runs the first 4");
+  });
+
+  it("toggles options in wildcard order; none clears an axis, all fills it", async () => {
+    const w = mount(SweepPanel, { props: { modelValue: on([{ uid: "u1", option_ids: ["h1"] }]), candidates: CANDS } });
+    await w.find('[data-test="sweep-axis-u1"] .wp-sweep__axis-name').trigger("click");
+    await w.find('[data-test="sweep-opt-h0"]').trigger("click");
+    expect(lastEmit(w).axes[0].option_ids).toEqual(["h0", "h1"]);
+    await w.find('[data-test="sweep-none"]').trigger("click");
+    expect(lastEmit(w).axes[0].option_ids).toEqual([]);
+    await w.setProps({ modelValue: on([{ uid: "u1", option_ids: [] }]) });
+    expect(w.find('[data-test="sweep-total"]').text()).toContain("Tick at least one option");
+    await w.find('[data-test="sweep-opt-h1"]').trigger("click");
+    expect(lastEmit(w).axes[0].option_ids).toEqual(["h1"]);
+    await w.find('[data-test="sweep-all"]').trigger("click");
+    expect(lastEmit(w).axes[0].option_ids).toEqual(CANDS[0].options.map((o) => o.id));
+  });
+
+  it("an empty axis doesn't count toward the frames", () => {
+    const cfg = parseContextLoopConfig(JSON.stringify({ sweep: { enabled: true, axes: [{ uid: "a", option_ids: [] }] } }));
+    expect(sweepFrameCount(cfg)).toBeNull();
+    expect(sweepTotal([{ uid: "a", option_ids: [] }, { uid: "b", option_ids: ["1", "2", "3"] }])).toBe(3);
+  });
+
+  it("removes an axis, edits the limit and the hold switch", async () => {
+    const w = mount(SweepPanel, { props: { modelValue: on([{ uid: "u1", option_ids: ["h1"] }]), candidates: CANDS } });
+    await w.find('[data-test="sweep-remove-u1"]').trigger("click");
+    expect(lastEmit(w).axes).toEqual([]);
+    const lim = w.find('[data-test="sweep-limit"]');
+    (lim.element as HTMLInputElement).value = "5000";
+    await lim.trigger("change");
+    expect(lastEmit(w).limit).toBe(999);
+    await w.find('[data-test="sweep-limit-up"]').trigger("click");
+    expect(lastEmit(w).limit).toBe(65);
+    await w.setProps({ modelValue: { ...on([]), limit: 1 } });
+    await w.find('[data-test="sweep-limit-down"]').trigger("click");
+    expect(lastEmit(w).limit).toBe(1);
+    await w.find('[data-test="sweep-hold-toggle"]').trigger("click");
+    expect(lastEmit(w).hold_others).toBe(false);
+  });
+
+  it("flags an axis whose wildcard is gone", () => {
+    const w = mount(SweepPanel, { props: { modelValue: on([{ uid: "zz", option_ids: ["a"], label: "$old" }]), candidates: CANDS } });
+    const row = w.find('[data-test="sweep-axis-zz"]');
+    expect(row.classes()).toContain("wp-sweep__axis--missing");
+    expect(row.text()).toContain("$old");
+  });
+});
+
+describe("ContextLoopWidget sweep wiring", () => {
+  it("parses the raw downstream nodes", () => {
+    const raw = JSON.stringify({ version: 1, modules: [wildcard("u1", "hair", ["red", "blue"])] });
+    const [src] = sweepSourcesFromRaw([{ label: "amber-fox", raw }]);
+    expect(src.value.modules[0]._uid).toBe("u1");
+    expect(sweepSourcesFromRaw([{ label: "x", raw: "{bad" }])[0].value.modules).toEqual([]);
+  });
+
+  it("keeps the sweep off the node and opens it in a modal", async () => {
+    const raw = JSON.stringify({ version: 1, modules: [wildcard("u1", "hair", ["red", "blue"])] });
+    const w = mount(ContextLoopWidget, {
+      props: { modelValue: emptyContextLoopConfig(), sweepSources: [{ label: "amber-fox", raw }] },
+      global: { stubs: { teleport: true } },
+    });
+    expect(w.find('[data-test="sweep-toggle"]').exists()).toBe(false);
+    expect(w.find('[data-test="loop-sweep-badge"]').exists()).toBe(false);
+    await w.find('[data-test="loop-sweep-btn"]').trigger("click");
+    const modal = w.findComponent(SweepModal);
+    expect(modal.exists()).toBe(true);
+    await modal.find('[data-test="sweep-toggle"]').trigger("click");
+    const cfg = w.emitted("update:modelValue")?.[0]?.[0] as { sweep: SweepConfig; strategy: string };
+    expect(cfg.sweep.enabled).toBe(true);
+    expect(cfg.strategy).toBe("hash_index");
+    await modal.find('[data-test="sweep-modal-done"]').trigger("click");
+    expect(w.findComponent(SweepModal).exists()).toBe(false);
+  });
+
+  it("shows the frame count on the node button", () => {
+    const axes = [{ uid: "u1", option_ids: ["h0", "h1", "h2"] }, { uid: "u2", option_ids: ["m0", "m1"] }];
+    const cfg = { ...emptyContextLoopConfig(), sweep: on(axes) };
+    const w = mount(ContextLoopWidget, { props: { modelValue: cfg } });
+    expect(w.find('[data-test="loop-sweep-badge"]').text()).toBe("6 frames");
+  });
+});
+
+describe("SweepModal", () => {
+  it("previews frames in run order with option names", () => {
+    const axes = [{ uid: "u1", option_ids: ["h0", "h2"] }, { uid: "u2", option_ids: ["m0", "m1"] }];
+    const w = mount(SweepModal, { props: { modelValue: on(axes), candidates: CANDS }, global: { stubs: { teleport: true } } });
+    const rows = w.findAll(".wp-swm__frame").map((r) => r.text());
+    expect(rows).toEqual(["#1red · calm", "#2red · sad", "#3green · calm", "#4green · sad"]);
+  });
+
+  it("summarises frames past the preview cap", () => {
+    const ids = Array.from({ length: 50 }, (_, i) => `x${i}`);
+    const w = mount(SweepModal, { props: { modelValue: on([{ uid: "zz", option_ids: ids }]) }, global: { stubs: { teleport: true } } });
+    expect(w.findAll(".wp-swm__frame")).toHaveLength(40);
+    expect(w.find(".wp-swm__frame-more").text()).toContain("10 more");
+  });
+});

src/components/context-loop/types.test.ts

@@ -1,6 +1,9 @@
 import { describe, it, expect } from "vitest";
 import {
   emptyContextLoopConfig,
+  emptySweepConfig,
+  keepFramesWithin,
+  remapSweepFrames,
   parseContextLoopConfig,
   serializeContextLoopConfig,
   type ContextLoopConfig,
@@ -32,6 +35,7 @@ describe("parseContextLoopConfig", () => {
       total_internal: false,
       seed_locks: {},
       bypass_frames: [],
+      sweep: emptySweepConfig(),
     };
     expect(parseContextLoopConfig(JSON.stringify(cfg))).toEqual(cfg);
   });
@@ -46,6 +50,7 @@ describe("parseContextLoopConfig", () => {
       total_internal: true,
       seed_locks: {},
       bypass_frames: [],
+      sweep: emptySweepConfig(),
     };
     expect(parseContextLoopConfig(JSON.stringify(cfg))).toEqual(cfg);
   });
@@ -71,6 +76,7 @@ describe("parseContextLoopConfig", () => {
       total_internal: true,
       seed_locks: {},
       bypass_frames: [],
+      sweep: emptySweepConfig(),
     };
     const round = parseContextLoopConfig(serializeContextLoopConfig(cfg));
     expect(round).toEqual(cfg);
@@ -111,3 +117,34 @@ describe("bypass_frames parse", () => {
     expect(parseContextLoopConfig("not json").bypass_frames).toEqual([]);
   });
 });
+
+describe("frame locks follow count and sweep edits", () => {
+  const base = () => ({ ...emptyContextLoopConfig(), seed_locks: { "1": 11, "4": 44 }, bypass_frames: [2, 5] });
+  const sweep = (opts: string[][], limit = 64) => ({
+    enabled: true, limit, hold_others: true,
+    axes: opts.map((ids, i) => ({ uid: `u${i}`, option_ids: ids })),
+  });
+
+  it("lowering the count drops locks and bypasses past it", () => {
+    const cfg = base();
+    expect(keepFramesWithin(cfg, 3)).toMatchObject({ seed_locks: { "1": 11 }, bypass_frames: [2] });
+    expect(keepFramesWithin(cfg, 9)).toBe(cfg);
+  });
+
+  it("a sweep edit moves locks with their combination and drops gone ones", () => {
+    // a×(x,y): frames ax, ay, bx, by. Lock "by" (3), bypass "ay" (1).
+    const prev = { ...emptyContextLoopConfig(), sweep: sweep([["a", "b"], ["x", "y"]]), seed_locks: { "3": 7 }, bypass_frames: [1] };
+    // Add option z: ax ay az bx by bz -> "by" is now 4, "ay" stays 1.
+    const added = remapSweepFrames(prev, { ...prev, sweep: sweep([["a", "b"], ["x", "y", "z"]]) }, 1);
+    expect(added).toMatchObject({ seed_locks: { "4": 7 }, bypass_frames: [1] });
+    // Drop y: ax bx -> both gone.
+    const dropped = remapSweepFrames(prev, { ...prev, sweep: sweep([["a", "b"], ["x"]]) }, 1);
+    expect(dropped).toMatchObject({ seed_locks: {}, bypass_frames: [] });
+  });
+
+  it("turning the sweep off keeps only frames within the count", () => {
+    const prev = { ...emptyContextLoopConfig(), sweep: sweep([["a", "b"], ["x", "y"]]), seed_locks: { "3": 7, "0": 1 }, bypass_frames: [1] };
+    const off = remapSweepFrames(prev, { ...prev, sweep: { ...prev.sweep, enabled: false } }, 2);
+    expect(off).toMatchObject({ seed_locks: { "0": 1 }, bypass_frames: [1] });
+  });
+});

src/components/context-loop/types.ts

@@ -8,6 +8,126 @@
 
 export type LoopStrategy = "sequential" | "hash_index" | "prime_stride";
 
+/** One swept wildcard: a downstream wildcard instance (`_uid`) and the
+ *  option ids the sweep walks. `label` is display-only, kept so an axis
+ *  whose wildcard has since been removed still reads as something. */
+export interface SweepAxis {
+  uid: string;
+  option_ids: string[];
+  label?: string;
+}
+
+/** Sweep mode: run every combination of the axes' options, one frame each,
+ *  capped at `limit`. Python mirror: `engine/sweep.py:parse_sweep`. */
+export interface SweepConfig {
+  enabled: boolean;
+  limit: number;
+  /** Roll every unswept module on the frame-0 seed so only the swept
+   *  wildcards change from frame to frame. */
+  hold_others: boolean;
+  axes: SweepAxis[];
+}
+
+export const SWEEP_DEFAULT_LIMIT = 64;
+export const SWEEP_MAX_LIMIT = 999;
+
+export function emptySweepConfig(): SweepConfig {
+  return { enabled: false, limit: SWEEP_DEFAULT_LIMIT, hold_others: true, axes: [] };
+}
+
+/** Recovery-friendly parse, identical to the Python `parse_sweep`: axes
+ *  without a uid or option ids are dropped, a repeated uid keeps its first
+ *  axis, option ids are deduped in order. */
+export function parseSweep(raw: unknown): SweepConfig {
+  const out = emptySweepConfig();
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  const obj = raw as Record<string, unknown>;
+  out.enabled = obj.enabled === true;
+  if (typeof obj.limit === "number" && Number.isInteger(obj.limit)) {
+    out.limit = Math.min(SWEEP_MAX_LIMIT, Math.max(1, obj.limit));
+  }
+  if (typeof obj.hold_others === "boolean") out.hold_others = obj.hold_others;
+  const seen = new Set<string>();
+  for (const a of Array.isArray(obj.axes) ? obj.axes : []) {
+    if (!a || typeof a !== "object" || Array.isArray(a)) continue;
+    const axis = a as Record<string, unknown>;
+    const uid = axis.uid;
+    if (typeof uid !== "string" || !uid || seen.has(uid)) continue;
+    const ids: string[] = [];
+    for (const id of Array.isArray(axis.option_ids) ? axis.option_ids : []) {
+      if (typeof id === "string" && id && !ids.includes(id)) ids.push(id);
+    }
+    // An axis with nothing ticked is kept (cleared to pick a few by hand)
+    // but sweeps nothing: see `liveAxes`.
+    seen.add(uid);
+    const clean: SweepAxis = { uid, option_ids: ids };
+    if (typeof axis.label === "string" && axis.label) clean.label = axis.label;
+    out.axes.push(clean);
+  }
+  return out;
+}
+
+/** The axes with at least one option ticked; only these sweep. */
+export function liveAxes(axes: readonly SweepAxis[]): SweepAxis[] {
+  return axes.filter((a) => a.option_ids.length > 0);
+}
+
+/** Combinations before the limit (1 with no axes). */
+export function sweepTotal(axes: readonly SweepAxis[]): number {
+  return liveAxes(axes).reduce((n, a) => n * a.option_ids.length, 1);
+}
+
+/** Frames the loop emits for this sweep, or null when the sweep is off,
+ *  has no axes, or the whole loop is bypassed (the Python node then
+ *  falls back to `count`). */
+export function sweepFrameCount(cfg: ContextLoopConfig): number | null {
+  const s = cfg.sweep;
+  if (!s.enabled || !liveAxes(s.axes).length || cfg.bypass) return null;
+  return Math.min(sweepTotal(s.axes), s.limit);
+}
+
+/** Drop seed locks and bypassed frames at or past `count`, so raising the
+ *  count again starts those frames fresh. Returns `cfg` when nothing changed. */
+export function keepFramesWithin(cfg: ContextLoopConfig, count: number): ContextLoopConfig {
+  const locks = Object.entries(cfg.seed_locks).filter(([k]) => Number(k) < count);
+  const bypass = cfg.bypass_frames.filter((i) => i < count);
+  if (locks.length === Object.keys(cfg.seed_locks).length && bypass.length === cfg.bypass_frames.length) return cfg;
+  return { ...cfg, seed_locks: Object.fromEntries(locks), bypass_frames: bypass };
+}
+
+/** Each frame's combination as a key, in run order (mirrors `sweep_frames`). */
+function sweepCombos(cfg: ContextLoopConfig): string[] | null {
+  const frames = sweepFrameCount(cfg);
+  if (frames === null) return null;
+  let combos = [""];
+  for (const a of liveAxes(cfg.sweep.axes)) {
+    combos = combos.flatMap((c) => a.option_ids.map((id) => `${c}${a.uid}=${id};`));
+  }
+  return combos.slice(0, frames);
+}
+
+/** After a sweep edit, keep each seed lock / bypass on the combination it
+ *  was set for: it moves with that combination, or goes when the
+ *  combination no longer runs. Without a sweep on both sides, frames past
+ *  the new frame count are dropped. */
+export function remapSweepFrames(prev: ContextLoopConfig, next: ContextLoopConfig, count: number): ContextLoopConfig {
+  const before = sweepCombos(prev);
+  const after = sweepCombos(next);
+  if (!before || !after) return keepFramesWithin(next, after?.length ?? count);
+  const at = new Map(after.map((c, i) => [c, i]));
+  const move = (i: number): number | undefined => {
+    const c = before[i];
+    return c === undefined ? undefined : at.get(c);
+  };
+  const locks: Record<string, number> = {};
+  for (const [k, seed] of Object.entries(next.seed_locks)) {
+    const to = move(Number(k));
+    if (to !== undefined) locks[String(to)] = seed;
+  }
+  const bypass = next.bypass_frames.map(move).filter((i): i is number => i !== undefined);
+  return { ...next, seed_locks: locks, bypass_frames: [...new Set(bypass)].sort((a, b) => a - b) };
+}
+
 export interface ContextLoopConfig {
   strategy: LoopStrategy;
   override_seed: boolean;
@@ -24,9 +144,12 @@ export interface ContextLoopConfig {
    *  indices re-derive from base+strategy. Empty by default. */
   seed_locks: Record<string, number>;
   /** 0-based iteration indices to bypass (skip generation + overrides).
-   *  Sorted, deduped, non-negative. Out-of-range (>= count) entries are
-   *  kept and re-apply if count grows. Empty by default. */
+   *  Sorted, deduped, non-negative. Lowering the count drops entries past
+   *  it, and a sweep change moves them with their combination
+   *  (`keepFramesWithin`, `remapSweepFrames`). Empty by default. */
   bypass_frames: number[];
+  /** Sweep mode; see `SweepConfig`. Off by default. */
+  sweep: SweepConfig;
 }
 
 const STRATEGIES = new Set<LoopStrategy>(["sequential", "hash_index", "prime_stride"]);
@@ -41,6 +164,7 @@ export function emptyContextLoopConfig(): ContextLoopConfig {
     total_internal: true,
     seed_locks: {},
     bypass_frames: [],
+    sweep: emptySweepConfig(),
   };
 }
 
@@ -88,6 +212,7 @@ export function parseContextLoopConfig(raw: string | null | undefined): ContextL
     }
     out.bypass_frames = [...frames].sort((a, b) => a - b);
   }
+  out.sweep = parseSweep(obj.sweep);
   return out;
 }
 

src/components/context/ContextWidget.vue

@@ -9,8 +9,10 @@ import {
 } from "../../widgets/_shared";
 import { type ResolvedValue } from "../../widgets/richTokenize";
 import { scanConflicts, labelFor as conflictLabelFor, shortConflictLabel, type Conflict } from "../../extension/conflicts";
+import { computeConstraintDeadEnds } from "../../extension/constraint-dead-ends";
 import type { ChainModule, PairingBadge, RowPairings } from "../../extension/constraint-pairs";
 import { baseCodename } from "../../extension/node-codename";
+import { derivationTargets } from "../../extension/derivation-conditions";
 import {
   getCollapseMode,
   getCollapsedByDefault,
@@ -795,6 +797,28 @@ const resolvedForEditing = computed<Record<string, ResolvedValue>>(() => {
  * Built in the same pass as the name list so the two cannot disagree about
  * which module owns a name.
  */
+/** The `accepts` axes a wildcard payload declares, with the tags each rolls
+ *  from. `hueIndex` counts EVERY group so a colour matches the wildcard
+ *  editor's. Mirrors `acceptsAxesOf` in `manager/utils/library-suggestions`;
+ *  duplicated rather than imported because that module pulls the whole module
+ *  store into the canvas bundle, which the size gate will not carry. */
+function acceptsAxesOfPayload(
+  payload: unknown,
+): { axis: string; tags: string[]; hueIndex: number }[] | undefined {
+  const p = (payload ?? {}) as {
+    tag_groups?: Record<string, string[]>;
+    tag_group_kinds?: Record<string, string>;
+  };
+  if (!p.tag_group_kinds) return undefined;
+  const out: { axis: string; tags: string[]; hueIndex: number }[] = [];
+  Object.entries(p.tag_groups ?? {}).forEach(([axis, tags], hueIndex) => {
+    if (p.tag_group_kinds?.[axis] === "accepts") {
+      out.push({ axis, tags: tags ?? [], hueIndex });
+    }
+  });
+  return out.length > 0 ? out : undefined;
+}
+
 const siblingVarInfo = computed<{
   names: string[];
   producers: Record<string, VarProducerLike>;
@@ -804,7 +828,10 @@ const siblingVarInfo = computed<{
   /** Last module to write each name, so repeat writes from one module (a
    *  derivation's branches) do not inflate the override count. */
   const lastWriter = new Map<string, string>();
-  let owner: { kind: string; moduleName: string; moduleId: string } | null = null;
+  let owner: {
+    kind: string; moduleName: string; moduleId: string;
+    axes?: { axis: string; tags: string[]; hueIndex: number }[];
+  } | null = null;
   function add(name: string | undefined | null): void {
     const trimmed = (name ?? "").replace(/^\$+/, "").trim();
     if (!trimmed) return;
@@ -825,6 +852,12 @@ const siblingVarInfo = computed<{
       // would be noise when every sibling gives the same answer.
       nodeLabel: "this node",
       shadowed: prev ? (sameWriter ? prev.shadowed : prev.shadowed + 1) : 0,
+      // `accepts` axes, so `$var.AXIS` completion works for a variable written
+      // in THIS node. Same-node writers replace the upstream entry wholesale
+      // in `allVarProducers`, so axes attached only during the graph walk were
+      // dropped for exactly the common case: the wildcard and the template
+      // that reads it sitting in one Context.
+      ...(owner.axes ? { axes: owner.axes } : {}),
     };
   }
   const editingM = editingModule.value;
@@ -840,6 +873,10 @@ const siblingVarInfo = computed<{
       kind: m.type,
       moduleName: m.meta?.name ?? m.type,
       moduleId: m.id,
+      // Read from the module's own payload snapshot — the node runs what it
+      // captured, so this is the truth for THIS node regardless of what the
+      // library says now.
+      ...(m.type === "wildcard" ? { axes: acceptsAxesOfPayload(m.payload) } : {}),
     };
     for (const e of m.entries) add(e.variable_name);
     const inst = (m.instance ?? {}) as {
@@ -867,10 +904,7 @@ const siblingVarInfo = computed<{
         for (const v of p.values ?? []) add(v.name);
       }
     } else if (m.type === "derivation") {
-      for (const rule of p.rules ?? []) {
-        for (const br of rule.branches ?? []) add(br.action?.target_var);
-        add(rule.else?.action?.target_var);
-      }
+      for (const name of derivationTargets(p)) add(name);
     }
   }
   owner = null;
@@ -900,8 +934,16 @@ const allVarProducers = computed<Record<string, VarProducerLike>>(() => {
   const merged: Record<string, VarProducerLike> = { ...upstream };
   for (const [name, sib] of Object.entries(siblingVarInfo.value.producers)) {
     const up = upstream[name];
+    // Same carry-forward as the graph walk: a same-node writer that declares
+    // no axes must not erase the ones an upstream wildcard declared for this
+    // binding — the engine keys `__wp_axes__` by binding, so the rolled axis
+    // outlives a rebind.
     merged[name] = up
-      ? { ...sib, shadowed: sib.shadowed + up.shadowed + 1 }
+      ? {
+          ...sib,
+          ...(sib.axes ?? up.axes ? { axes: sib.axes ?? up.axes } : {}),
+          shadowed: sib.shadowed + up.shadowed + 1,
+        }
       : sib;
   }
   return merged;
@@ -2183,6 +2225,20 @@ watch(() => props.initialJson, (raw) => {
   value.value = next.value;
 });
 
+// Constraints that can leave a target with nothing to pick (no fallback).
+// Cross-node: reads the flattened chain + reach coverage, keyed back to this
+// node's `_uid`s. Its own computed so a conflict-free edit elsewhere in the
+// widget doesn't redo the option × option walk.
+const deadEndsByUid = computed<Map<string, string[]>>(() => {
+  const out = new Map<string, string[]>();
+  if (!props.chainModules?.length || !props.pairings?.size) return out;
+  const prefix = `${props.nodeId}#`;
+  for (const [rowKey, d] of computeConstraintDeadEnds(props.chainModules, props.pairings)) {
+    if (rowKey.startsWith(prefix)) out.set(rowKey.slice(prefix.length), d.sourceValues);
+  }
+  return out;
+});
+
 const conflicts = computed<Conflict[]>(() => {
   // scanConflicts internally skips per-module via isModuleEffectivelyEnabled
   // (handles both child.enabled=false AND bundle.enabled=false). Passing the
@@ -2212,6 +2268,7 @@ const conflicts = computed<Conflict[]>(() => {
     // Live-library uuids — a nested @{} ref to any of these resolves at run
     // time (DB-expanded catalog), so it must not read as a broken ref.
     new Set(Object.keys(libraryHashes.value ?? {})),
+    deadEndsByUid.value,
   );
   // Filter by user's validation-strictness preference. The accessor
   // reads from the same module-level state map the panel onChange
@@ -2313,6 +2370,9 @@ function conflictTooltip(id: string): string {
     if (c.type.startsWith("constraint_")) {
       const name = lookupSiblingName(c.variable);
       const display = name ?? c.variable;
+      if (c.type === "constraint_excludes_all" && c.detail) {
+        return `${conflictLabelFor(c.type)}: $${display} when the source picks ${c.detail}`;
+      }
       return `${conflictLabelFor(c.type)}: $${display}`;
     }
     return `${conflictLabelFor(c.type)}: $${c.variable}`;
@@ -3013,6 +3073,7 @@ function isModified(m: ModuleEntry): boolean {
       if (nonEmptyObj(inst.option_weights)) return true;
       if (inst.mode && inst.mode !== "random") return true;
       if (inst.pinned_option_id) return true;
+      if (typeof inst.match_variable === "string" && inst.match_variable.trim() !== "") return true;
       // `category_filter` is a STRING expr — the old `nonEmptyArr()` test
       // never matched it, so toggling the pool filter never lit the dot.
       if (typeof inst.category_filter === "string" && inst.category_filter.trim() !== "") return true;
@@ -3268,6 +3329,9 @@ function modifiedTooltip(m: ModuleEntry): string {
   switch (m.type) {
     case "wildcard":
       if (inst.mode === "pinned") bits.push("pinned");
+      if (typeof inst.match_variable === "string" && inst.match_variable.trim()) {
+        bits.push(`matches $${inst.match_variable.trim()}`);
+      }
       else if (inst.mode === "subcategory") bits.push("subset");
       if (inst.category_filter) {
         bits.push(`cats: ${inst.category_filter}`);
@@ -6154,6 +6218,12 @@ provide(BundleFrameCtxKey, bundleFrameCtx);
  * size to 12 to match Module density. */
 .wp-row-type-icon { color: var(--wp-kind-wildcard); }
 .wp-row-type-icon .pi { font-size: 12px; }
+/* The bare rules above tie with row-primitives.css's grey default, and that
+ * file is copied into several lazy chunks: whichever chunk injects last wins,
+ * so opening a modal or adding an Injector turned wildcard icons grey. The
+ * [data-kind] selectors below outrank it whatever the load order. */
+.wp-module[data-kind="wildcard"]     .wp-row-type-icon { color: var(--wp-kind-wildcard); }
+.wp-module .wp-row-type-icon .pi { font-size: 12px; }
 .wp-module[data-kind="combine"]      .wp-row-type-icon { color: var(--wp-kind-combine); }
 .wp-module[data-kind="derivation"]   .wp-row-type-icon { color: var(--wp-kind-derivation); }
 .wp-module[data-kind="constraint"]   .wp-row-type-icon { color: var(--wp-kind-constraint); }

src/components/context/drift-store.ts

@@ -1,5 +1,6 @@
 import { ref, type Ref } from "vue";
 import type { ModuleEntry } from "../../widgets/_shared";
+import { checkInstalledVersion } from "./version-notice";
 
 /**
  * Shape of the SnapshotEntry returned by `POST /wp/api/modules/embed-bundle`
@@ -119,6 +120,7 @@ function sameModuleHashes(
 async function fetchModuleHashes(): Promise<void> {
   try {
     const res = await fetch("/wp/api/modules/hashes");
+    checkInstalledVersion(res);
     if (!res.ok) return;
     const body = (await res.json()) as {
       hashes?: Record<string, { type?: string; payload_hash: string }>;

src/components/context/editors/_shared/preview-tokens.ts

@@ -29,6 +29,11 @@ export interface PreviewToken {
   varName?: string;
   /** SP2a `.K` list accessor on a var token (`$mood.0` -> index 0). */
   index?: number;
+  /** Tag-axis accessor (`$outfit.SHOES` -> "SHOES"). Carried for the same
+   *  reason `index` is: without it the axis segment is not part of the var
+   *  token, so every consumer renders the variable and then the bare text
+   *  ".SHOES" beside it. */
+  axis?: string;
   refUuid?: string;
   branches?: string[];
   count?: number;
@@ -42,7 +47,11 @@ const REF_VALID_SURFACES = new Set<Surface>(["wildcard"]);
 // Group 2 = optional `.K` list accessor (SP2a) so `$mood.0` is ONE var token
 // (base name in m[1], index in m[2]) — mirrors engine tokenize.py +
 // richTokenize.ts, so the `.K` never strands as a separate text token.
-const VAR_RE = /\$([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?/y;
+// Groups: 1=name · 2=index-first · 3=axis-after-index · 4=axis-first ·
+// 5=index-after-axis. Two mirrored alternatives because the accessor order is
+// free (`$v.0.AXIS` and `$v.AXIS.0` both parse) — same shape as richTokenize.
+const VAR_RE =
+  /\$([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?(?:\.([A-Za-z_][A-Za-z0-9_]*))?|\$([A-Za-z_][A-Za-z0-9_]*)(?:\.([A-Za-z_][A-Za-z0-9_]*))?(?:\.(\d+))?/y;
 // Optional `:subcat[,subcat]` per-call sub-category filter — empty
 // filter is equivalent to no filter, sub-categories are stripped of
 // whitespace + comma-separated.
@@ -90,6 +99,7 @@ export function tokenize(text: string, surface: Surface): PreviewToken[] {
           raw: m[0],
           varName: m[1],
           index: m[2] !== undefined ? Number.parseInt(m[2], 10) : undefined,
+          axis: m[3],
           invalid: !VAR_VALID_SURFACES.has(surface),
         });
         i += m[0].length;

src/components/context/editors/_shell.test.ts

@@ -11,6 +11,7 @@ describe("INSTANCE_FIELDS_PER_KIND registry", () => {
       // SP2a multi-select (2026-06-08): per-instance count range + separator.
       // SP2c: pick_independent (allow repeats / with replacement).
       "pick_min", "pick_max", "pick_separator", "pick_independent",
+      "match_variable",
     ]);
     expect(INSTANCE_FIELDS_PER_KIND.fixed_values).toEqual([
       // `locked_seed` added in the combine + fixed_values syntax-parity

src/components/context/editors/_shell.ts

@@ -14,7 +14,7 @@ export type InstanceFieldKey =
   | "variable_binding" | "enabled_options" | "option_weights" | "category_filter"
   | "exclude_null"
   | "pick_min" | "pick_max" | "pick_separator" | "pick_independent"
-  | "mode" | "pinned_option_id" | "locked_seed" | "seed_scope" | "internal" | "values_overrides"
+  | "mode" | "pinned_option_id" | "match_variable" | "locked_seed" | "seed_scope" | "internal" | "values_overrides"
   | "template_override"
   | "disabled_rule_ids"
   // Derivation tier-D modal expansion (2026-05-10 cycle)
@@ -50,6 +50,8 @@ export const INSTANCE_FIELDS_PER_KIND: Record<ModuleEntryKind, readonly Instance
     // SP2a multi-select: count range + join separator (per-instance, local).
     // SP2c: pick_independent (allow repeats / with replacement).
     "pick_min", "pick_max", "pick_separator", "pick_independent",
+    // Model-aware pipelines: pick the option equal to `$<match_variable>`.
+    "match_variable",
   ],
   fixed_values: ["values_overrides", "enabled_options", "locked_seed", "seed_scope"],
   combine: ["template_override", "variable_binding", "locked_seed", "seed_scope", "internal"],

src/components/context/editors/combine/sections/TemplateSection.vue

@@ -146,6 +146,15 @@ interface ResolvedToken {
   kind: "literal" | "var-resolved" | "var-unresolved";
   varName?: string;
 }
+/** First tag of `axis` on whichever producer writes `name`, or undefined when
+ *  that producer declares no such `accepts` axis — in which case the read
+ *  stays unresolved rather than silently losing the accessor. */
+function producerAxisTag(name: string, axis: string): string | undefined {
+  const axes = varProducerMap.value.get(name)?.axes ?? [];
+  const hit = axes.find((a: { axis: string; tags: string[] }) => a.axis === axis);
+  return hit && hit.tags.length > 0 ? hit.tags[0] : undefined;
+}
+
 const resolvedTokens = computed<ResolvedToken[]>(() => {
   const tokens: ResolvedToken[] = [];
   const map = props.upstreamResolved;
@@ -159,6 +168,21 @@ const resolvedTokens = computed<ResolvedToken[]>(() => {
         // SP2a: resolve via the shared accessor so `$mood.0` indexes (and a
         // bare `$mood` joins a list) — the `.K` never strands as literal text.
         // Presence is keyed on the base name, not the value's type.
+        if (tok.axis) {
+          // An axis read resolves to a TAG, never to the variable's text.
+          // Resolving it as a plain `$var` and letting the tokenizer's axis
+          // segment fall through as literal is what produced
+          // "a white t-shirt and denim skirt.SHOES" in both preview lines.
+          // Runtime rolls one member per pick; with no rng here, show the
+          // first — same convention the rest of the static preview uses.
+          const tag = producerAxisTag(tok.varName, tok.axis);
+          tokens.push(
+            tag != null
+              ? { text: tag, kind: "var-resolved", varName: tok.varName }
+              : { text: tok.raw, kind: "var-unresolved", varName: tok.varName },
+          );
+          break;
+        }
         if (Object.prototype.hasOwnProperty.call(map, tok.varName)) {
           tokens.push({
             text: applyVarAccessor(map[tok.varName], tok.index),

src/components/context/editors/constraint/CellRulePopover.test.ts

@@ -3,22 +3,36 @@ import { describe, it, expect } from "vitest";
 import CellRulePopover from "../../../../../src/components/context/editors/constraint/CellRulePopover.vue";
 
 describe("CellRulePopover", () => {
-  it("renders four labeled state buttons", () => {
+  it("renders five labeled state buttons", () => {
     const wrap = mount(CellRulePopover, {
       props: { state: "neutral", factor: 1, srcLabel: "warm", tgtLabel: "positive_qa" },
     });
     const btns = wrap.findAll("button.pop-btn");
-    expect(btns).toHaveLength(4);
+    expect(btns).toHaveLength(5);
     expect(btns.map((b) => b.text())).toEqual(
       expect.arrayContaining([
         expect.stringMatching(/neutral/i),
         expect.stringMatching(/exclude/i),
         expect.stringMatching(/boost/i),
         expect.stringMatching(/reduce/i),
+        expect.stringMatching(/only/i),
       ]),
     );
   });
 
+  it("emits only and explains the row-wide effect when only is active", async () => {
+    const wrap = mount(CellRulePopover, {
+      props: { state: "neutral", factor: 1, srcLabel: "summer", tgtLabel: "open" },
+    });
+    expect(wrap.find(".pop-note").exists()).toBe(false);
+    await wrap.find("button.b-only").trigger("click");
+    expect(wrap.emitted("update:state")?.[0]).toEqual(["only"]);
+    await wrap.setProps({ state: "only" });
+    expect(wrap.find(".pop-note").text()).toMatch(/without a rule of its own is excluded when summer fires/);
+    // `only` weighs 1.0, so there is no factor to edit.
+    expect(wrap.find(".pop-factor").exists()).toBe(false);
+  });
+
   it("marks the current state button as active", () => {
     const wrap = mount(CellRulePopover, {
       props: { state: "boost", factor: 1.8, srcLabel: "warm", tgtLabel: "positive_qa" },

src/components/context/editors/constraint/CellRulePopover.vue

@@ -2,7 +2,7 @@
 /**
  * CellRulePopover — body of the constraint-matrix cell editor.
  *
- * Renders four labeled state buttons (NEUTRAL/EXCLUDE/BOOST/REDUCE) plus
+ * Renders five labeled state buttons (NEUTRAL/EXCLUDE/BOOST/REDUCE/ONLY) plus
  * a numeric factor input (boost / reduce only) and an optional "Reset"
  * button shown when the caller signals there's an override to clear.
  *
@@ -12,7 +12,7 @@
  */
 import { computed, nextTick, onMounted, ref, watch } from "vue";
 
-type RuleState = "neutral" | "exclude" | "boost" | "reduce";
+type RuleState = "neutral" | "exclude" | "boost" | "reduce" | "only";
 
 const props = withDefaults(
   defineProps<{
@@ -165,6 +165,19 @@ function onReset(): void {
       >
         <span class="b-glyph">↓</span> Reduce
       </button>
+      <button
+        type="button"
+        class="pop-btn b-only"
+        :class="{ active: state === 'only' }"
+        :aria-pressed="state === 'only'"
+        title="Link: when this source tag fires, only targets with a rule in this row can be picked"
+        @click="pickState('only')"
+      >
+        <span class="b-glyph">✓</span> Only
+      </button>
+    </div>
+    <div v-if="state === 'only'" class="pop-note">
+      Every target in this row without a rule of its own is excluded when {{ srcLabel }} fires.
     </div>
 
     <div v-if="showFactor" class="pop-factor">
@@ -274,6 +287,17 @@ function onReset(): void {
 }
 .pop-btn.b-exclude.active { background: color-mix(in srgb, var(--wp-danger, #ef4444) 22%, transparent); color: var(--wp-danger); border-color: color-mix(in srgb, var(--wp-danger, #ef4444) 50%, transparent); }
 .pop-btn.b-boost.active   { background: color-mix(in srgb, var(--wp-success, #22c55e) 22%, transparent); color: var(--wp-success); border-color: color-mix(in srgb, var(--wp-success, #22c55e) 50%, transparent); }
+.pop-btn.b-only {
+  /* Fifth button spans the grid so the 2-column layout stays even. */
+  grid-column: 1 / -1;
+}
+.pop-btn.b-only.active    { background: color-mix(in srgb, var(--wp-info, #3b82f6) 22%, transparent); color: var(--wp-info, #3b82f6); border-color: color-mix(in srgb, var(--wp-info, #3b82f6) 50%, transparent); }
+.pop-note {
+  margin: -2px 0 8px;
+  font: 10px var(--wp-font-sans, sans-serif);
+  color: var(--wp-text-muted, #8a8d99);
+  line-height: 1.4;
+}
 .pop-btn.b-reduce.active  { background: color-mix(in srgb, var(--wp-warn, #f97316) 22%, transparent); color: var(--wp-warn); border-color: color-mix(in srgb, var(--wp-warn, #f97316) 50%, transparent); }
 
 /* ── Factor input — wrap + stacked stepper, mirrors OptionRow's

src/components/context/editors/constraint/ConstraintInstanceModal.vue

@@ -101,6 +101,7 @@ interface WildcardPayload {
   sub_categories?: string[];
   options?: Array<{ value?: string }>;
   tag_groups?: Record<string, string[]>;
+  tag_group_kinds?: Record<string, string>;
 }
 
 /** Normalised module shape the resolution lookups consume. Unifies the
@@ -307,6 +308,14 @@ const targetGroups = computed<Record<string, string[]>>(() => {
   const pl = (props.module.payload ?? {}) as ConstraintPayload;
   return findWildcard(pl.target_wildcard_id)?.tag_groups ?? {};
 });
+const sourceGroupKinds = computed<Record<string, string>>(() => {
+  const pl = (props.module.payload ?? {}) as ConstraintPayload;
+  return findWildcard(pl.source_wildcard_id)?.tag_group_kinds ?? {};
+});
+const targetGroupKinds = computed<Record<string, string>>(() => {
+  const pl = (props.module.payload ?? {}) as ConstraintPayload;
+  return findWildcard(pl.target_wildcard_id)?.tag_group_kinds ?? {};
+});
 
 const sourceName = computed(() => {
   const pl = (props.module.payload ?? {}) as ConstraintPayload;
@@ -715,6 +724,8 @@ function onSpaClick(): void {
       :target-name="targetName"
       :source-groups="sourceGroups"
       :target-groups="targetGroups"
+      :source-group-kinds="sourceGroupKinds"
+      :target-group-kinds="targetGroupKinds"
       :stranded="hasDangling"
       @update="onUpdate"
     />