feat(compare): group contrast visibility L1+L2 (v2.1.0)

Raise ANALYSIS Amplitude, auto +Only on SAE, soft group Y gaps, and optional dim-sort by between-group |Δmean| so GROUP_* domains are readable in the matrix.

Co-authored-by: Cursor <cursoragent@cursor.com>

.agents/skills/dev-protocol/lessons-learned.md

@@ -224,6 +224,28 @@ User-editable hex anchors replace the former fixed dual ramp (no product mid-sto
 - Encode already had bucketing + inference_mode + autocast; MPS autocast attempted with FP32 fallback.
 - **Encode I/O bottleneck**: GPU matmul ~20ms; dense `.tolist()` of `[N, 8192]` JSON was the freeze. Fix: `encode_vectors_sparse` → `{format:topk_sparse, indices[N,K], values[N,K]}` + router `ORJSONResponse`; `RemoteProvider.saeEncode` densifies via `densifyTopKActivations`. `load_model()` is singleton (`model is not None` short-circuit) — do not `torch.load` per request.
 - **Train UI hang**: UI could sit on `Starting SAE training… · working Ns` while backend was already `success`. Causes: (1) poll started only after `POST /train` returned — large embeddings JSON could stall the POST; (2) `refreshSaeStatusUi` nulled status on fetch error → fallback label "Starting…"; (3) async `setInterval` overlap. Fix: poll immediately on busy; keep last status on error; fetch timeouts; ignore pre-POST `idle`; clear poll in `_stopSaeTrainBusy`.
+
+### 4.11. COMPARE group contrast visibility (v2.1.0)
+- **SAE + global z-score**: Top‑K densified matrix (~5% nonzero) → exact zeros normalize to \(t \approx -0.24\) (false negative “dust”). Mitigation in v1: auto **+ Only** on SAE encode success; restore previous filter on SAE OFF (`saeFilterBridge`). Do not change global z-score contract without an explicit D10.
+- **Amplitude floor**: `COMPARE|ANALYSIS|POINTS` at Amp `1.0` collapses relief even when math has signal — default Amp **16** (RIBBONS twin too).
+- **Dim sort**: optional client permutation by max pairwise `|mean_Gi − mean_Gj|`; session-only, OFF default; only when ≥2 `groupId`. Does not mutate backend payload.
+- **Cosine ▲/▼ vs groups**: disable while groups active — global cosine sort breaks GROUP_* contiguity and soft Y gaps.
+- Soft ANALYSIS Y gap: +1 empty slot between consecutive different `groupId` blocks (`groupStackLayout`).
+
+#### Handoff for predecessor / sister apps (architect brief)
+Portable findings from VectorLab 3D `v2.1.0` — apply if the older app shares ANALYSIS matrix paint + groups + SAE Top‑K:
+
+| Finding | Detail | Recommended fix |
+| :--- | :--- | :--- |
+| Sparse SAE + **global** z-score+tanh | Exact zeros → \(t\approx-0.24\) (painted as negative “dust”); nonzeros saturate near +1 | Prefer **+ Only** when SAE ON; optionally restore prior filter on SAE OFF. Avoid changing global norm unless product accepts colormap shift |
+| Flat relief | Amplitude default at slider floor (~1) hides real peaks (RAW peak \|a\|~0.22 → Y tiny) | Raise ANALYSIS Amplitude default (VL3D used **16**; ARITH often **40**) |
+| Unsorted X | Dim index order hides domain bands even when between-group signal exists | Client **dim permutation** by `max_{i,j} \|mean_Gi − mean_Gj\|`; toggle OFF = raw order |
+| Cosine list sort vs groups | Global cosine reorder breaks group contiguity on Y | Disable cosine ▲/▼ while ≥2 groups, or regroup after sort |
+| Expectation vs math | RAW G1↔G2 centroid cosine ~0.55 (not antipodal); SAE can improve (~0.22) but paint still hides it | Fix paint/order first; wider SAE train is L3, not required for readability |
+| Layout axes (ANALYSIS) | X=dim, Y=thread stack + val×amp, Z=0 | Soft Y gap between `GROUP_*` blocks (+1× spacing) aids domain reading |
+
+**Modules shipped (reference):** `saeFilterBridge.js`, `groupStackLayout.js`, `dimContrastSort.js`; wiring in Compare panel + Instancer layout. Diagnosis: `scripts/diagnose_group_separation.py`. Roadmap: `roadmap/compare-group-contrast-viz.md`.
+
 ---
 
 ## 5. Protocolo de Mantenimiento de Lecciones Aprendidas

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to VectorLab 3D will be documented in this file.
 
+## [2.1.0] - 2026-08-02
+
+### Added
+- **COMPARE group contrast visibility** (`feat/compare-group-contrast-viz`):
+  - Amplitude default **16** for `COMPARE|ANALYSIS|POINTS` and RIBBONS twin (was floor `1.0`).
+  - SAE ON auto-sets Visualization filter to **+ Only**; SAE OFF restores the previous filter.
+  - Soft Y gap (+1× Dist Y) between contiguous `GROUP_*` blocks in ANALYSIS.
+  - Toggle **Sort dims by group contrast** (session-only, OFF default; visible when ≥2 groups) — permutes X by max pairwise `|Δmean|`.
+  - Cosine ▲/▼ disabled while groups are active (preserves block layout).
+
+### Changed
+- Roadmap decisions D1–D12 closed (pack 1: L1+L2; L3 deferred; SemVer MINOR).
+
 ## [2.0.0] - 2026-08-02
 
 ### Added

manifest.json

@@ -1,6 +1,6 @@
 {
   "project": "vectorlab-3d",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "bootstrap_run": false,
   "state_schema": {
     "model_name": "all-mpnet-base-v2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorlab-3d",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

roadmap/compare-group-contrast-viz.md

@@ -1,6 +1,7 @@
 # Roadmap — COMPARE group contrast visibility (RAW vs SAE)
 
-**Status:** Planned (diagnosis complete; product decisions open)  
+**Status:** Implemented (awaiting APPROVAL GATE / merge) — D* pack 1; L1+L2; v2.1.0  
+
 **Date:** 2026-08-02  
 **Product:** VectorLab 3D (`lsv2`)  
 **Prompt companion:** [`PROMPT-compare-group-contrast-viz.md`](./PROMPT-compare-group-contrast-viz.md)  
@@ -119,18 +120,18 @@ Do **not** invent answers. Ask the human, record answers in this doc §3.1, then
 
 | ID | Answer | Date |
 | :--- | :--- | :--- |
-| D1 | _pending_ | |
-| D2 | _pending_ | |
-| D3 | _pending_ | |
-| D4 | _pending_ | |
-| D5 | _pending_ | |
-| D6 | _pending_ | |
-| D7 | _pending_ | |
-| D8 | _pending_ | |
-| D9 | _pending_ | |
-| D10 | _pending_ | |
-| D11 | _pending_ | |
-| D12 | _pending_ | |
+| D1 | **L1+L2** (pack 1 B) — L3 out | 2026-08-02 |
+| D2 | Amplitude **16** for `COMPARE\|ANALYSIS\|POINTS` **and** RIBBONS twin | 2026-08-02 |
+| D3 | **A** auto-set filter to `+ Only` (`positive`) on SAE encode success | 2026-08-02 |
+| D4 | **A** restore previous filter when SAE OFF | 2026-08-02 |
+| D5 | **B** soft Y gap: **+1×** `threadVectorDistance` between group blocks | 2026-08-02 |
+| D6 | **A** `\|mean_G1 − mean_G2\|` (for >2 groups: max pairwise \|Δmean\|) | 2026-08-02 |
+| D7 | **A** dim-sort toggle only when ≥2 distinct `groupId` | 2026-08-02 |
+| D8 | **A** session only, **OFF** by default (no localStorage) | 2026-08-02 |
+| D9 | **B** disable cosine ▲/▼ while groups active (reason in title) | 2026-08-02 |
+| D10 | **A** defer — keep global z-score; L1 `+ Only` mitigates dust | 2026-08-02 |
+| D11 | **A** out of v1 | 2026-08-02 |
+| D12 | **MINOR `2.1.0`** | 2026-08-02 |
 
 ---
 

src/main.js

@@ -27,9 +27,18 @@ import { resolveSpatialDefaults } from './ui/spatialSliderDefaults.js';
 import {
   visualizationControlsMarkup,
   wireVisualizationControls,
+  syncVisualizationControlsFromConfig,
   readVisualizationPanelCollapsed,
 } from './ui/VisualizationControls.js';
-import { loadVisualizationSettings } from './ui/visualizationControlsDefaults.js';
+import {
+  loadVisualizationSettings,
+  saveVisualizationSettings,
+} from './ui/visualizationControlsDefaults.js';
+import {
+  snapshotFilterForSae,
+  filterModeForSaeOn,
+  restoreFilterAfterSae,
+} from './ui/saeFilterBridge.js';
 import {
   loadSaeSettings,
   saveSaeSettings,
@@ -120,6 +129,10 @@ class VectorLabApp {
     this._saeTrainPollInFlight = false;
     this._saeTrainSeenRunning = false;
     this._saeTrainPostDone = false;
+    /** @type {{ previousMode: string }|null} */
+    this._saeFilterSnapshot = null;
+    /** Session-only dim contrast sort (Compare groups). */
+    this.dimSortByContrast = false;
 
     const saeHooks = {
       onSaeToggle: (enabled) => this.handleSaeToggle(enabled),
@@ -129,6 +142,10 @@ class VectorLabApp {
         this.saeSettings = s;
         saveSaeSettings(s);
       },
+      onDimSortChange: (enabled) => {
+        this.dimSortByContrast = !!enabled;
+        this.refreshRender();
+      },
     };
 
     this.sidebar = new Sidebar(
@@ -301,7 +318,8 @@ class VectorLabApp {
           state.renderMode,
           this.sliderConfig,
           this.viewMode,
-          this.vizConfig
+          this.vizConfig,
+          { dimSortByContrast: this.dimSortByContrast }
         );
         this.setCompareOverlayLabels(labels);
         this.comparePanel.updateGroupLegend(data.items);
@@ -733,6 +751,40 @@ class VectorLabApp {
     }
   }
 
+  /**
+   * Apply Visualization filter mode and sync right-dock radios + localStorage.
+   * @param {string} mode
+   */
+  applyVizFilterMode(mode) {
+    if (!this.vizConfig) return;
+    this.vizConfig.vizFilterMode = mode;
+    saveVisualizationSettings(this.vizConfig);
+    if (this.vizEl) {
+      syncVisualizationControlsFromConfig(this.vizEl, this.vizConfig);
+    }
+  }
+
+  /**
+   * D3: on SAE encode success, force + Only (snapshot once per SAE ON session).
+   */
+  applySaeOnFilterOverride() {
+    if (!this._saeFilterSnapshot) {
+      this._saeFilterSnapshot = snapshotFilterForSae(this.vizConfig?.vizFilterMode);
+    }
+    this.applyVizFilterMode(filterModeForSaeOn());
+  }
+
+  /**
+   * D4: restore pre-SAE filter when leaving SAE.
+   */
+  restoreSaeFilterOverride() {
+    const restored = restoreFilterAfterSae(this._saeFilterSnapshot);
+    this._saeFilterSnapshot = null;
+    if (restored != null) {
+      this.applyVizFilterMode(restored);
+    }
+  }
+
   clearSaeFraming() {
     this.instancer.setDimSpanScale(1);
     if (this._preSaeThreadWidth != null) {
@@ -746,6 +798,7 @@ class VectorLabApp {
 
   restoreRawWorkspace({ reframe = false } = {}) {
     this.clearSaeFraming();
+    this.restoreSaeFilterOverride();
     if (this.rawCompareData) {
       state.setCompareData(cloneCompareRaw(this.rawCompareData));
       this.comparePanel.updateCompareResults(state.compareData);
@@ -800,6 +853,7 @@ class VectorLabApp {
       }
       state.setCompareData(saeData);
       this.comparePanel.updateCompareResults(saeData);
+      this.applySaeOnFilterOverride();
 
       if (reframe) {
         await this.frameAfterSaeEncode(saeData, this.rawCompareData);
@@ -861,7 +915,8 @@ class VectorLabApp {
         state.renderMode,
         this.sliderConfig,
         this.viewMode,
-        this.vizConfig
+        this.vizConfig,
+        { dimSortByContrast: this.dimSortByContrast }
       );
       this.setCompareOverlayLabels(labels);
       this.comparePanel.updateCompareResults(withMeta);

src/style.css

@@ -210,6 +210,33 @@ canvas {
   text-transform: none;
 }
 
+.compare-dim-sort {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 10px;
+  padding: 6px 2px;
+  font-size: 0.78rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  color: rgba(230, 235, 245, 0.88);
+  cursor: pointer;
+  user-select: none;
+  flex-shrink: 0;
+}
+
+.compare-dim-sort[hidden] {
+  display: none !important;
+}
+
+.compare-dim-sort input {
+  accent-color: var(--accent-gold, #e8b84a);
+  width: 14px;
+  height: 14px;
+  margin: 0;
+  cursor: pointer;
+}
+
 /* COMPARE: cosine-vs-anchor list — scroll only inside the list (§4.1 panel invariant) */
 #compare-panel .compare-results {
   flex: 1 1 auto;

src/ui/ComparePanel.js

@@ -96,6 +96,7 @@ export class ComparePanel {
    *   onSaeTrain?: (settings: object) => void|Promise<void>,
    *   getSaeSettings?: () => object,
    *   setSaeSettings?: (s: object) => void,
+   *   onDimSortChange?: (enabled: boolean) => void,
    * }} [saeHooks]
    */
   constructor(containerElement, onCalculateCallback, onReorderCallback = null, saeHooks = {}) {
@@ -107,6 +108,10 @@ export class ComparePanel {
     /** @type {Array|null} */
     this.items = null;
     this.reorderLocked = false;
+    /** Session-only dim contrast sort (D8 OFF default). */
+    this.dimSortByContrast = false;
+    /** Cosine ▲/▼ blocked while ≥2 groups (D9). */
+    this.cosineSortBlockedByGroups = false;
 
     this.element = document.createElement('div');
     this.element.id = 'compare-panel';
@@ -139,6 +144,10 @@ export class ComparePanel {
           <span class="metric-item">Loaded Tokens: <strong id="token-count-val">0</strong></span>
         </div>
         <div id="compare-groups-legend" class="compare-groups-legend" hidden></div>
+        <label id="compare-dim-sort-row" class="compare-dim-sort" hidden>
+          <input type="checkbox" id="compare-dim-sort-toggle">
+          <span>Sort dims by group contrast</span>
+        </label>
 
         <div class="compare-cosine-header">
           <h3 id="compare-cosine-subtitle" class="compare-cosine-subtitle">COSINE SIMILARITY vs —</h3>
@@ -159,6 +168,8 @@ export class ComparePanel {
     this.textarea = this.element.querySelector('#compare-tokens');
     this.tokenCountVal = this.element.querySelector('#token-count-val');
     this.groupsLegend = this.element.querySelector('#compare-groups-legend');
+    this.dimSortRow = this.element.querySelector('#compare-dim-sort-row');
+    this.dimSortToggle = this.element.querySelector('#compare-dim-sort-toggle');
     this.cosineSubtitle = this.element.querySelector('#compare-cosine-subtitle');
     this.cosineList = this.element.querySelector('#compare-cosine-list');
     this.btnSortDesc = this.element.querySelector('#btn-sort-desc');
@@ -228,11 +239,20 @@ export class ComparePanel {
       btn.addEventListener('click', (e) => {
         e.preventDefault();
         e.stopPropagation();
-        if (this.reorderLocked) return;
+        if (this.reorderLocked || this.cosineSortBlockedByGroups) return;
         const direction = btn.getAttribute('data-sort');
         this.handleSort(direction);
       });
     });
+
+    if (this.dimSortToggle) {
+      this.dimSortToggle.addEventListener('change', () => {
+        this.dimSortByContrast = !!this.dimSortToggle.checked;
+        if (typeof this.saeHooks.onDimSortChange === 'function') {
+          this.saeHooks.onDimSortChange(this.dimSortByContrast);
+        }
+      });
+    }
   }
 
   applyReorderResult(result) {
@@ -254,15 +274,13 @@ export class ComparePanel {
   }
 
   handleSort(direction) {
-    if (!this.items || this.reorderLocked) return;
+    if (!this.items || this.reorderLocked || this.cosineSortBlockedByGroups) return;
     this.applyReorderResult(sortCompareItemsByCosine(this.items, direction));
   }
 
   setReorderLocked(locked) {
     this.reorderLocked = locked;
-    const hasItems = !!(this.items && this.items.length > 1);
-    if (this.btnSortDesc) this.btnSortDesc.disabled = locked || !hasItems;
-    if (this.btnSortAsc) this.btnSortAsc.disabled = locked || !hasItems;
+    this.syncCosineSortButtons();
 
     this.cosineList.querySelectorAll('.btn-reorder').forEach((btn) => {
       if (locked) {
@@ -276,6 +294,60 @@ export class ComparePanel {
     });
   }
 
+  /**
+   * Enable/disable cosine ▲/▼; when groups active, force off with reason title (D9).
+   */
+  syncCosineSortButtons() {
+    const hasItems = !!(this.items && this.items.length > 1);
+    const blocked = this.cosineSortBlockedByGroups;
+    const disabled = this.reorderLocked || !hasItems || blocked;
+    const title = blocked
+      ? 'Disabled while groups are active (preserves group blocks)'
+      : null;
+    if (this.btnSortDesc) {
+      this.btnSortDesc.disabled = disabled;
+      this.btnSortDesc.title = title || 'Highest → lowest';
+    }
+    if (this.btnSortAsc) {
+      this.btnSortAsc.disabled = disabled;
+      this.btnSortAsc.title = title || 'Lowest → highest';
+    }
+  }
+
+  /**
+   * Show dim-sort toggle only when ≥2 groups; sync cosine block (D7/D9).
+   * @param {Array<{ groupId?: string, groupLabel?: string }>|null|undefined} items
+   */
+  syncGroupLayoutControls(items) {
+    /** @type {Set<string>} */
+    const ids = new Set();
+    for (const it of items || []) {
+      if (it?.groupId) ids.add(it.groupId);
+    }
+    const multiGroup = ids.size >= 2;
+    this.cosineSortBlockedByGroups = multiGroup;
+    this.syncCosineSortButtons();
+
+    if (this.dimSortRow) {
+      if (multiGroup) {
+        this.dimSortRow.removeAttribute('hidden');
+      } else {
+        this.dimSortRow.setAttribute('hidden', '');
+        if (this.dimSortByContrast) {
+          this.dimSortByContrast = false;
+          if (this.dimSortToggle) this.dimSortToggle.checked = false;
+          if (typeof this.saeHooks.onDimSortChange === 'function') {
+            this.saeHooks.onDimSortChange(false);
+          }
+        }
+      }
+    }
+    if (this.dimSortToggle) {
+      this.dimSortToggle.checked = this.dimSortByContrast;
+      this.dimSortToggle.disabled = !multiGroup;
+    }
+  }
+
   setLoading(loading) {
     this.saeUi.setPrimaryLoading(loading);
   }
@@ -304,15 +376,16 @@ export class ComparePanel {
     if (!counts.size) {
       this.groupsLegend.setAttribute('hidden', '');
       this.groupsLegend.innerHTML = '';
-      return;
+    } else {
+      this.groupsLegend.removeAttribute('hidden');
+      this.groupsLegend.innerHTML = [...counts.values()]
+        .map(
+          (g) =>
+            `<span class="compare-group-chip" title="${g.count} tokens">${g.label}<em>${g.count}</em></span>`
+        )
+        .join('');
     }
-    this.groupsLegend.removeAttribute('hidden');
-    this.groupsLegend.innerHTML = [...counts.values()]
-      .map(
-        (g) =>
-          `<span class="compare-group-chip" title="${g.count} tokens">${g.label}<em>${g.count}</em></span>`
-      )
-      .join('');
+    this.syncGroupLayoutControls(items);
   }
 
   /**

src/ui/Navbar.js

@@ -16,7 +16,7 @@ export class Navbar {
         <div class="logo-icon">🌐</div>
         <div class="title-group">
           <h1>VECTORLAB <span class="accent-3d">3D</span></h1>
-          <span class="version-tag">v2.0.0</span>
+          <span class="version-tag">v2.1.0</span>
         </div>
       </div>
 

src/ui/saeFilterBridge.js

@@ -0,0 +1,38 @@
+/**
+ * SAE ↔ Visualization sign-filter bridge (D3/D4).
+ * On SAE ON: force + Only. On SAE OFF: restore the pre-SAE filter.
+ */
+
+import { normalizeFilterMode } from './visualizationControlsDefaults.js';
+
+/** @typedef {import('./visualizationControlsDefaults.js').VizFilterMode} VizFilterMode */
+/** @typedef {{ previousMode: VizFilterMode }} SaeFilterSnapshot */
+
+/** Filter applied automatically when SAE encode succeeds. */
+export const SAE_ON_FILTER_MODE = /** @type {VizFilterMode} */ ('positive');
+
+/**
+ * Snapshot current filter before overriding for SAE.
+ * @param {unknown} currentMode
+ * @returns {SaeFilterSnapshot}
+ */
+export function snapshotFilterForSae(currentMode) {
+  return { previousMode: normalizeFilterMode(currentMode) };
+}
+
+/**
+ * @returns {VizFilterMode}
+ */
+export function filterModeForSaeOn() {
+  return SAE_ON_FILTER_MODE;
+}
+
+/**
+ * Restore filter after SAE OFF. Null snapshot → null (caller no-ops).
+ * @param {SaeFilterSnapshot|null|undefined} snapshot
+ * @returns {VizFilterMode|null}
+ */
+export function restoreFilterAfterSae(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null;
+  return normalizeFilterMode(snapshot.previousMode);
+}

src/ui/spatialSliderDefaults.js

@@ -45,11 +45,19 @@ export const SPATIAL_DEFAULT_OVERRIDES = {
     threadWidth: 0.1,
     threadThickness: 0.01,
   },
-  // Captured COMPARE + ANALYSIS + POINTS (Spatial Controls + CAM POSE framing)
+  // COMPARE + ANALYSIS + POINTS — Amplitude 16 so activation peaks are readable (was floor 1.0)
   'COMPARE|ANALYSIS|POINTS': {
     threadSpacing: 1.45,
     threadVectorDistance: 1.0,
-    threadAmplitudeY: 1.0,
+    threadAmplitudeY: 16.0,
+    threadWidth: 0.2,
+    threadThickness: 0.01,
+  },
+  // COMPARE + ANALYSIS + RIBBONS — same Amplitude twin as POINTS
+  'COMPARE|ANALYSIS|RIBBONS': {
+    threadSpacing: 1.45,
+    threadVectorDistance: 1.0,
+    threadAmplitudeY: 16.0,
     threadWidth: 0.2,
     threadThickness: 0.01,
   },

src/visualizer/Instancer.js

@@ -3,6 +3,12 @@ import { MeshFactory } from './MeshFactory.js';
 import { LayoutEngine } from './LayoutEngine.js';
 import { arithmeticSequenceIndex, arithmeticThreadLabel } from '../ui/threadLabelFormat.js';
 import { normalizeRenderMode } from '../core/State.js';
+import { computeGroupAwareYSlots } from './groupStackLayout.js';
+import {
+  applyDimPermutation,
+  computeDimContrastPermutation,
+  hasEnoughGroupsForDimSort,
+} from './dimContrastSort.js';
 
 /**
  * Instancer Manager for rendering vector points, ribbons, and highlights in the Three.js scene.
@@ -222,9 +228,17 @@ export class Instancer {
    * @param {Object} [spatialConfig] - Real-time spatial slider configuration
    * @param {string} [viewMode="NAVIGATION"] - "NAVIGATION" | "ANALYSIS"
    * @param {Object} [vizConfig] - Global sign filter + color anchors
+   * @param {{ dimSortByContrast?: boolean }} [options]
    * @returns {Array<{ id: string, text: string, type: string, origin3D: THREE.Vector3 }>} Label metadata
    */
-  renderCompareData(compareResponse, renderMode = "POINTS", spatialConfig = null, viewMode = "NAVIGATION", vizConfig = null) {
+  renderCompareData(
+    compareResponse,
+    renderMode = "POINTS",
+    spatialConfig = null,
+    viewMode = "NAVIGATION",
+    vizConfig = null,
+    options = {}
+  ) {
     this.clear();
     renderMode = normalizeRenderMode(renderMode);
     this.renderMode = renderMode;
@@ -242,7 +256,8 @@ export class Instancer {
 
     if (!compareResponse || !compareResponse.items || compareResponse.items.length === 0) return [];
 
-    const totalThreads = compareResponse.items.length;
+    const items = compareResponse.items;
+    const totalThreads = items.length;
     const thicknessFactor = (spatialConfig && spatialConfig.threadThickness !== undefined)
       ? spatialConfig.threadThickness
       : 0.3;
@@ -255,6 +270,10 @@ export class Instancer {
       ? spatialConfig.threadAmplitudeY
       : 16.0;
 
+    const { slots: ySlots, span: ySlotSpan } = computeGroupAwareYSlots(items, { gapSlots: 1 });
+    const dimSortOn = options.dimSortByContrast === true && hasEnoughGroupsForDimSort(items);
+    const dimPerm = dimSortOn ? computeDimContrastPermutation(items) : null;
+
     const pointsData = [];
     const threadLabelItems = [];
     const threads = [];
@@ -262,21 +281,32 @@ export class Instancer {
     const surfaceRows = [];
     let pointOffset = 0;
 
-    compareResponse.items.forEach((item, idx) => {
-      const vec = item.embedding;
-      if (!vec || !vec.length) return;
+    items.forEach((item, idx) => {
+      const rawVec = item.embedding;
+      if (!rawVec || !rawVec.length) return;
 
+      const vec = dimPerm ? applyDimPermutation(rawVec, dimPerm) : rawVec;
       const threadId = item.id || `tok_${idx}`;
-      const vec3D = this.layoutEngine.mapVectorTo3DPoints(vec, idx, viewMode, totalThreads, spacingY, amplitudeY);
+      const layoutOpts = { ySlot: ySlots[idx] ?? idx, ySlotSpan };
+      const vec3D = this.layoutEngine.mapVectorTo3DPoints(
+        vec,
+        idx,
+        viewMode,
+        totalThreads,
+        spacingY,
+        amplitudeY,
+        layoutOpts
+      );
       const activations = [];
 
       vec3D.forEach((p, dimIdx) => {
         const val = vec[dimIdx];
+        const sourceDim = dimPerm ? dimPerm[dimIdx] : dimIdx;
         pointsData.push({
           position: p,
           activation: val,
           size: 10.0 * thicknessFactor,
-          meta: { type: "compare", token: item.text, dim: dimIdx, val }
+          meta: { type: "compare", token: item.text, dim: sourceDim, val }
         });
         activations.push(val);
       });
@@ -307,6 +337,8 @@ export class Instancer {
         pointOffset,
         dimCount: vec.length,
         sequenceIndex: idx,
+        ySlot: layoutOpts.ySlot,
+        ySlotSpan,
         _layoutPoints: vec3D,
         groupId: item.groupId,
         groupLabel: item.groupLabel,
@@ -350,6 +382,7 @@ export class Instancer {
       totalThreads,
       spacingY,
       amplitudeY,
+      ySlotSpan,
       pointsMesh,
       baselineMesh,
       threads,
@@ -364,13 +397,31 @@ export class Instancer {
    * @returns {THREE.Vector3|null} origin for floating labels
    */
   _applyCompareThreadLayout(thread, sequenceIndex, runtime, { updateBounds = false } = {}) {
+    // Settled layout uses stored group-gap slots; fractional tween uses sequenceIndex as Y.
+    const settled = Number.isInteger(sequenceIndex)
+      && sequenceIndex === thread.sequenceIndex
+      && thread.ySlot !== undefined;
+    const layoutOpts = settled
+      ? {
+          ySlot: thread.ySlot,
+          ySlotSpan: thread.ySlotSpan !== undefined
+            ? thread.ySlotSpan
+            : (runtime.ySlotSpan !== undefined
+              ? runtime.ySlotSpan
+              : Math.max(0, runtime.totalThreads - 1)),
+        }
+      : {
+          ySlot: sequenceIndex,
+          ySlotSpan: Math.max(0, runtime.totalThreads - 1),
+        };
     const vec3D = this.layoutEngine.mapVectorTo3DPoints(
       thread.embedding,
       sequenceIndex,
       runtime.viewMode,
       runtime.totalThreads,
       runtime.spacingY,
-      runtime.amplitudeY
+      runtime.amplitudeY,
+      layoutOpts
     );
     if (!vec3D.length) return null;
 
@@ -494,6 +545,34 @@ export class Instancer {
             }
           });
 
+          if (t >= 1) {
+            const ordered = [...runtime.threads].sort((a, b) => a.sequenceIndex - b.sequenceIndex);
+            const { slots, span } = computeGroupAwareYSlots(ordered, { gapSlots: 1 });
+            runtime.ySlotSpan = span;
+            ordered.forEach((th, i) => {
+              th.ySlot = slots[i];
+              th.ySlotSpan = span;
+            });
+            origins.length = 0;
+            labels.length = 0;
+            runtime.threads.forEach((thread) => {
+              const origin = this._applyCompareThreadLayout(thread, thread.sequenceIndex, runtime, {
+                updateBounds: true,
+              });
+              if (origin) {
+                origins.push(origin);
+                labels.push({
+                  id: thread.id,
+                  text: thread.text,
+                  type: "compare",
+                  origin3D: origin,
+                  groupId: thread.groupId,
+                  groupLabel: thread.groupLabel,
+                });
+              }
+            });
+          }
+
           this._syncCompareBaseline(origins);
 
           if (onFrame) onFrame(labels);

src/visualizer/LayoutEngine.js

@@ -95,8 +95,17 @@ export class LayoutEngine {
    * @param {number} [totalThreads=5] - Total number of threads for centering in ANALYSIS mode
    * @param {number} [spacingY=46.0] - Vertical Y separation between threads
    * @param {number} [amplitudeY=16.0] - Height scale factor for activation points (+1 / -1)
+   * @param {{ ySlot?: number, ySlotSpan?: number }} [layoutOpts] - Optional ANALYSIS slot override (group gaps)
    */
-  mapVectorTo3DPoints(vector, sequenceIndex = 0, viewMode = 'NAVIGATION', totalThreads = 5, spacingY = 46.0, amplitudeY = 16.0) {
+  mapVectorTo3DPoints(
+    vector,
+    sequenceIndex = 0,
+    viewMode = 'NAVIGATION',
+    totalThreads = 5,
+    spacingY = 46.0,
+    amplitudeY = 16.0,
+    layoutOpts = {}
+  ) {
     if (!vector || !vector.length) return [];
     const count = vector.length;
     const offsetCenterX = (count * this.scaleX) / 2.0;
@@ -104,7 +113,11 @@ export class LayoutEngine {
     if (viewMode === 'ANALYSIS') {
       // Stack threads vertically along Y axis with customizable separation (spacingY)
       const verticalSpacing = spacingY ?? 46.0;
-      const centeredYSlot = (totalThreads - 1) / 2.0 - sequenceIndex;
+      const ySlot = layoutOpts.ySlot !== undefined ? layoutOpts.ySlot : sequenceIndex;
+      const ySlotSpan = layoutOpts.ySlotSpan !== undefined
+        ? layoutOpts.ySlotSpan
+        : Math.max(0, totalThreads - 1);
+      const centeredYSlot = ySlotSpan / 2.0 - ySlot;
       const offsetY = centeredYSlot * verticalSpacing;
       const ampY = amplitudeY ?? 16.0; // Scaled activation amplitude for point Y peaks (+1 / -1)
 

src/visualizer/dimContrastSort.js

@@ -0,0 +1,116 @@
+/**
+ * Dimension permutation by between-group mean contrast (L2 / D6).
+ * Score per dim = max pairwise |mean_Gi − mean_Gj| across distinct groupIds.
+ */
+
+import { countDistinctGroups, listDistinctGroupIds } from './groupStackLayout.js';
+
+/**
+ * @param {Array<{ groupId?: string, embedding?: number[] }|null|undefined>|null|undefined} items
+ * @returns {boolean}
+ */
+export function hasEnoughGroupsForDimSort(items) {
+  return countDistinctGroups(items) >= 2;
+}
+
+/**
+ * Identity permutation [0, 1, …, dim-1].
+ * @param {number} dim
+ * @returns {number[]}
+ */
+export function identityPermutation(dim) {
+  const n = Math.max(0, Math.floor(Number(dim) || 0));
+  return Array.from({ length: n }, (_, i) => i);
+}
+
+/**
+ * Per-dimension contrast scores (max pairwise |Δmean|). Length = embedding dim.
+ * Returns [] if <2 groups or empty/mismatched embeddings.
+ *
+ * @param {Array<{ groupId?: string, embedding?: number[] }|null|undefined>|null|undefined} items
+ * @returns {number[]}
+ */
+export function computeDimContrastScores(items) {
+  const list = (items || []).filter((it) => it?.groupId && Array.isArray(it.embedding) && it.embedding.length);
+  const groupIds = listDistinctGroupIds(list);
+  if (groupIds.length < 2) return [];
+
+  const dim = list[0].embedding.length;
+  if (!list.every((it) => it.embedding.length === dim)) return [];
+
+  /** @type {Map<string, { sum: Float64Array, count: number }>} */
+  const acc = new Map();
+  for (const gid of groupIds) {
+    acc.set(gid, { sum: new Float64Array(dim), count: 0 });
+  }
+
+  for (const it of list) {
+    const bucket = acc.get(it.groupId);
+    if (!bucket) continue;
+    const emb = it.embedding;
+    for (let d = 0; d < dim; d++) {
+      bucket.sum[d] += emb[d];
+    }
+    bucket.count += 1;
+  }
+
+  /** @type {Float64Array[]} */
+  const means = [];
+  for (const gid of groupIds) {
+    const bucket = acc.get(gid);
+    if (!bucket || bucket.count < 1) continue;
+    const mean = new Float64Array(dim);
+    for (let d = 0; d < dim; d++) {
+      mean[d] = bucket.sum[d] / bucket.count;
+    }
+    means.push(mean);
+  }
+  if (means.length < 2) return [];
+
+  /** @type {number[]} */
+  const scores = new Array(dim);
+  for (let d = 0; d < dim; d++) {
+    let peak = 0;
+    for (let i = 0; i < means.length; i++) {
+      for (let j = i + 1; j < means.length; j++) {
+        const delta = Math.abs(means[i][d] - means[j][d]);
+        if (delta > peak) peak = delta;
+      }
+    }
+    scores[d] = peak;
+  }
+  return scores;
+}
+
+/**
+ * Permutation of dim indices sorted by contrast descending (stable on ties by index).
+ * Identity when contrast cannot be computed.
+ *
+ * @param {Array<{ groupId?: string, embedding?: number[] }|null|undefined>|null|undefined} items
+ * @returns {number[]}
+ */
+export function computeDimContrastPermutation(items) {
+  const scores = computeDimContrastScores(items);
+  if (!scores.length) {
+    const dim = items?.find((it) => Array.isArray(it?.embedding))?.embedding?.length ?? 0;
+    return identityPermutation(dim);
+  }
+  return scores
+    .map((score, index) => ({ score, index }))
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .map((row) => row.index);
+}
+
+/**
+ * Reorder vector components by permutation (displayIndex → sourceDim).
+ * @param {number[]} vector
+ * @param {number[]|null|undefined} permutation
+ * @returns {number[]}
+ */
+export function applyDimPermutation(vector, permutation) {
+  if (!Array.isArray(vector)) return [];
+  if (!Array.isArray(permutation) || permutation.length !== vector.length) {
+    return vector.slice();
+  }
+  return permutation.map((src) => vector[src]);
+}

src/visualizer/groupStackLayout.js

@@ -0,0 +1,60 @@
+/**
+ * ANALYSIS Y-stack slots with optional soft gap between GROUP_* blocks (D5).
+ */
+
+/**
+ * Distinct non-empty groupId values in item order.
+ * @param {Array<{ groupId?: string }|null|undefined>|null|undefined} items
+ * @returns {string[]}
+ */
+export function listDistinctGroupIds(items) {
+  /** @type {string[]} */
+  const out = [];
+  const seen = new Set();
+  for (const it of items || []) {
+    const id = it?.groupId;
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * @param {Array<{ groupId?: string }|null|undefined>|null|undefined} items
+ * @returns {number}
+ */
+export function countDistinctGroups(items) {
+  return listDistinctGroupIds(items).length;
+}
+
+/**
+ * Y slot indices for ANALYSIS stacking. When consecutive items have different
+ * non-empty groupIds, insert `gapSlots` empty slots between them (+1× spacing).
+ *
+ * @param {Array<{ groupId?: string }|null|undefined>|null|undefined} items
+ * @param {{ gapSlots?: number }} [opts]
+ * @returns {{ slots: number[], span: number }}
+ */
+export function computeGroupAwareYSlots(items, opts = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const gapSlots = Number.isFinite(opts.gapSlots) ? Math.max(0, Math.floor(opts.gapSlots)) : 1;
+
+  /** @type {number[]} */
+  const slots = [];
+  let slot = 0;
+  let prevGroup = /** @type {string|null} */ (null);
+
+  for (let i = 0; i < list.length; i++) {
+    const cur = list[i]?.groupId || null;
+    if (i > 0 && prevGroup && cur && prevGroup !== cur) {
+      slot += gapSlots;
+    }
+    slots.push(slot);
+    prevGroup = cur;
+    slot += 1;
+  }
+
+  const maxSlot = slots.length ? slots[slots.length - 1] : 0;
+  return { slots, span: maxSlot };
+}

tests/LayoutEngine.test.js

@@ -44,4 +44,18 @@ describe('LayoutEngine Math Tests', () => {
     // Slot 0 (centeredYSlot = 2.0) with spacing 80 should have double the vertical Y offset of spacing 40
     expect(pointsExpandedY[0].y).toBeCloseTo(pointsDefaultY[0].y * 2, 5);
   });
+
+  it('honors optional ySlot / ySlotSpan for group soft gaps', () => {
+    const engine = new LayoutEngine({ scaleX: 1.0 });
+    const vector = [0.0];
+    const noGap = engine.mapVectorTo3DPoints(vector, 2, 'ANALYSIS', 4, 10.0, 16.0);
+    const withGap = engine.mapVectorTo3DPoints(vector, 2, 'ANALYSIS', 4, 10.0, 16.0, {
+      ySlot: 3,
+      ySlotSpan: 4,
+    });
+    // slot 3 of span 4 → centered = 2-3 = -1 → y = -10
+    // slot 2 of span 3 → centered = 1.5-2 = -0.5 → y = -5
+    expect(noGap[0].y).toBeCloseTo(-5, 5);
+    expect(withGap[0].y).toBeCloseTo(-10, 5);
+  });
 });

tests/dimContrastSort.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import {
+  hasEnoughGroupsForDimSort,
+  computeDimContrastScores,
+  computeDimContrastPermutation,
+  applyDimPermutation,
+  identityPermutation,
+} from '../src/visualizer/dimContrastSort.js';
+
+describe('dimContrastSort', () => {
+  it('requires ≥2 groups', () => {
+    expect(hasEnoughGroupsForDimSort([{ groupId: 'G1', embedding: [1, 0] }])).toBe(false);
+    expect(hasEnoughGroupsForDimSort([
+      { groupId: 'G1', embedding: [1, 0] },
+      { groupId: 'G2', embedding: [0, 1] },
+    ])).toBe(true);
+  });
+
+  it('scores dims by max pairwise |Δmean|', () => {
+    // dim0: G1=1, G2=0 → contrast 1
+    // dim1: G1=0, G2=0 → contrast 0
+    // dim2: G1=0.5, G2=−0.5 → contrast 1
+    const items = [
+      { groupId: 'G1', embedding: [1, 0, 0.5] },
+      { groupId: 'G1', embedding: [1, 0, 0.5] },
+      { groupId: 'G2', embedding: [0, 0, -0.5] },
+      { groupId: 'G2', embedding: [0, 0, -0.5] },
+    ];
+    const scores = computeDimContrastScores(items);
+    expect(scores).toHaveLength(3);
+    expect(scores[0]).toBeCloseTo(1);
+    expect(scores[1]).toBeCloseTo(0);
+    expect(scores[2]).toBeCloseTo(1);
+  });
+
+  it('permutes high-contrast dims first (stable on ties)', () => {
+    const items = [
+      { groupId: 'G1', embedding: [1, 0, 2] },
+      { groupId: 'G2', embedding: [0, 0, 0] },
+    ];
+    // contrasts: dim0=1, dim1=0, dim2=2 → order [2, 0, 1]
+    expect(computeDimContrastPermutation(items)).toEqual([2, 0, 1]);
+  });
+
+  it('applyDimPermutation reorders components', () => {
+    expect(applyDimPermutation([10, 20, 30], [2, 0, 1])).toEqual([30, 10, 20]);
+    expect(applyDimPermutation([1, 2], null)).toEqual([1, 2]);
+    expect(identityPermutation(3)).toEqual([0, 1, 2]);
+  });
+
+  it('falls back to identity when <2 groups', () => {
+    const items = [{ groupId: 'G1', embedding: [1, 2, 3] }];
+    expect(computeDimContrastPermutation(items)).toEqual([0, 1, 2]);
+  });
+});

tests/groupStackLayout.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import {
+  countDistinctGroups,
+  computeGroupAwareYSlots,
+  listDistinctGroupIds,
+} from '../src/visualizer/groupStackLayout.js';
+
+describe('groupStackLayout', () => {
+  it('counts distinct groupIds', () => {
+    expect(countDistinctGroups([])).toBe(0);
+    expect(countDistinctGroups([{ groupId: 'G1' }, { groupId: 'G1' }])).toBe(1);
+    expect(countDistinctGroups([
+      { groupId: 'G1' },
+      { groupId: 'G2' },
+      { groupId: 'G1' },
+    ])).toBe(2);
+    expect(listDistinctGroupIds([
+      { groupId: 'GROUP_1' },
+      { groupId: 'GROUP_2' },
+    ])).toEqual(['GROUP_1', 'GROUP_2']);
+  });
+
+  it('uses contiguous slots when no group change', () => {
+    const items = [{ groupId: 'G1' }, { groupId: 'G1' }, { groupId: 'G1' }];
+    expect(computeGroupAwareYSlots(items)).toEqual({ slots: [0, 1, 2], span: 2 });
+  });
+
+  it('inserts soft gap (+1 slot) between different groups', () => {
+    const items = [
+      { groupId: 'G1' },
+      { groupId: 'G1' },
+      { groupId: 'G2' },
+      { groupId: 'G2' },
+    ];
+    // slots 0,1 | gap | 3,4 → span 4
+    expect(computeGroupAwareYSlots(items, { gapSlots: 1 })).toEqual({
+      slots: [0, 1, 3, 4],
+      span: 4,
+    });
+  });
+
+  it('skips gap when items lack groupId', () => {
+    const items = [{}, {}, {}];
+    expect(computeGroupAwareYSlots(items)).toEqual({ slots: [0, 1, 2], span: 2 });
+  });
+
+  it('honors gapSlots=0 (no extra separation)', () => {
+    const items = [{ groupId: 'A' }, { groupId: 'B' }];
+    expect(computeGroupAwareYSlots(items, { gapSlots: 0 })).toEqual({
+      slots: [0, 1],
+      span: 1,
+    });
+  });
+});

tests/saeFilterBridge.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import {
+  SAE_ON_FILTER_MODE,
+  snapshotFilterForSae,
+  filterModeForSaeOn,
+  restoreFilterAfterSae,
+} from '../src/ui/saeFilterBridge.js';
+
+describe('saeFilterBridge', () => {
+  it('SAE ON forces + Only (positive)', () => {
+    expect(filterModeForSaeOn()).toBe('positive');
+    expect(SAE_ON_FILTER_MODE).toBe('positive');
+  });
+
+  it('snapshots current filter and restores it after SAE OFF', () => {
+    const snap = snapshotFilterForSae('all');
+    expect(snap.previousMode).toBe('all');
+    expect(restoreFilterAfterSae(snap)).toBe('all');
+
+    const snapNeg = snapshotFilterForSae('negative');
+    expect(restoreFilterAfterSae(snapNeg)).toBe('negative');
+  });
+
+  it('normalizes invalid snapshot modes to all', () => {
+    expect(snapshotFilterForSae('bogus').previousMode).toBe('all');
+    expect(restoreFilterAfterSae(null)).toBeNull();
+    expect(restoreFilterAfterSae(undefined)).toBeNull();
+  });
+});

tests/spatialSliderDefaults.test.js

@@ -6,23 +6,33 @@ import {
 } from '../src/ui/spatialSliderDefaults.js';
 
 describe('resolveSpatialDefaults', () => {
+  /** @type {Array<{ key: string, previous: object|undefined }>} */
   const savedKeys = [];
 
   afterEach(() => {
-    for (const key of savedKeys.splice(0)) {
-      delete SPATIAL_DEFAULT_OVERRIDES[key];
+    for (const { key, previous } of savedKeys.splice(0)) {
+      if (previous === undefined) {
+        delete SPATIAL_DEFAULT_OVERRIDES[key];
+      } else {
+        SPATIAL_DEFAULT_OVERRIDES[key] = previous;
+      }
     }
   });
 
   function setOverride(key, partial) {
+    savedKeys.push({
+      key,
+      previous: SPATIAL_DEFAULT_OVERRIDES[key]
+        ? { ...SPATIAL_DEFAULT_OVERRIDES[key] }
+        : undefined,
+    });
     SPATIAL_DEFAULT_OVERRIDES[key] = partial;
-    savedKeys.push(key);
   }
 
   it('returns global mid defaults when no overrides exist', () => {
     const d = resolveSpatialDefaults({
-      workspaceMode: 'COMPARE',
-      viewMode: 'ANALYSIS',
+      workspaceMode: 'ARITHMETIC',
+      viewMode: 'NAVIGATION',
       renderMode: 'RIBBONS',
     });
     expect(d.threadSpacing).toBe(GLOBAL_SPATIAL_DEFAULTS.threadSpacing);
@@ -50,7 +60,7 @@ describe('resolveSpatialDefaults', () => {
   });
 
   it('does not leak overrides from a different context', () => {
-    setOverride('COMPARE|ANALYSIS|RIBBONS', { threadWidth: 0.25 });
+    setOverride('COMPARE|ANALYSIS|POINTS', { threadWidth: 0.25 });
 
     const d = resolveSpatialDefaults({
       workspaceMode: 'ARITHMETIC',
@@ -87,7 +97,7 @@ describe('resolveSpatialDefaults', () => {
     expect(d.threadThickness).toBe(0.01);
   });
 
-  it('applies captured COMPARE|ANALYSIS|POINTS preset', () => {
+  it('applies COMPARE|ANALYSIS|POINTS preset with Amplitude 16', () => {
     const d = resolveSpatialDefaults({
       workspaceMode: 'COMPARE',
       viewMode: 'ANALYSIS',
@@ -95,11 +105,22 @@ describe('resolveSpatialDefaults', () => {
     });
     expect(d.threadSpacing).toBe(1.45);
     expect(d.threadVectorDistance).toBe(1.0);
-    expect(d.threadAmplitudeY).toBe(1.0);
+    expect(d.threadAmplitudeY).toBe(16.0);
     expect(d.threadWidth).toBe(0.2);
     expect(d.threadThickness).toBe(0.01);
   });
 
+  it('applies COMPARE|ANALYSIS|RIBBONS twin with Amplitude 16', () => {
+    const d = resolveSpatialDefaults({
+      workspaceMode: 'COMPARE',
+      viewMode: 'ANALYSIS',
+      renderMode: 'RIBBONS',
+    });
+    expect(d.threadAmplitudeY).toBe(16.0);
+    expect(d.threadSpacing).toBe(1.45);
+    expect(d.threadVectorDistance).toBe(1.0);
+  });
+
   it('applies captured COMPARE|NAVIGATION|RIBBONS preset', () => {
     const d = resolveSpatialDefaults({
       workspaceMode: 'COMPARE',