feat(v7-f56b): DimEnvEditor proposes single-knob snap fixes inline

Per the architect's request: when the editor surfaces a mismatch, it
should not just warn — it should suggest a valid replacement and let
one click accept the fix, rather than leaving the user to mentally
solve nh*head_dim=H.

vbgui/src/components/DimEnvEditor.tsx:
- Two new buttons appear next to the inline mismatch indicator:
  * 'Snap H → N' (data-testid='dim-env-fix-set-H') — sets H to
    nh*head_dim. Always available when there's a mismatch.
  * 'Snap head_dim → N' (data-testid='dim-env-fix-set-head_dim') —
    sets head_dim to H/nh, but ONLY when H is cleanly divisible by
    nh (otherwise the snap would itself be fractional).
- Apply button now turns amber when there's a mismatch (color +
  border + title) so the architect notices before committing.
- applyDraft() factored out so both Apply and Snap-* buttons share
  one path that reflects the override back into the visible draft.

The decoupled-Q convention (H ≠ nh*head_dim with internal projection)
is still accepted — the architect can ignore the snap and press
Apply consciously; the warning persists as a yellow banner.

vbgui/tests/DimEnvEditor.test.tsx — 3 new cases (8 total):
- Snap H → forwards 150 when nh=3, head_dim=50.
- Snap head_dim → shows "16" when H=128, nh=8.
- Snap head_dim hidden when H % nh != 0 (only Snap H shown).

15/15 vitest (DimEnvEditor + App.integration). F56b Playwright e2e
unaffected — uses the Apply path which still works the same way.

Ref: cppmega-mlx-j3qa.2

Author: apstenku123

vbgui/src/components/DimEnvEditor.tsx

@@ -20,15 +20,45 @@ export function DimEnvEditor({ value, onApply }: DimEnvEditorProps): JSX.Element
     return out;
   });
 
-  const mismatch = (() => {
+  const parsed = (() => {
     const H = Number(draft.H);
     const nh = Number(draft.nh);
     const hd = Number(draft.head_dim);
     if (!Number.isFinite(H) || !Number.isFinite(nh) ||
         !Number.isFinite(hd)) return null;
-    if (nh * hd === H) return null;
-    return `nh*head_dim = ${nh * hd} ≠ H = ${H}`;
+    return { H, nh, hd };
   })();
+  const mismatch = parsed && parsed.nh * parsed.hd !== parsed.H
+    ? `nh*head_dim = ${parsed.nh * parsed.hd} ≠ H = ${parsed.H}`
+    : null;
+  // Two single-knob fixes that snap to consistency: change H to
+  // nh*head_dim, or change head_dim to H/nh when H is cleanly
+  // divisible by nh. The architect can also accept the mismatch
+  // consciously (the codebase supports decoupled Q via projection).
+  const fixSetH = mismatch && parsed
+    ? { H: parsed.nh * parsed.hd } : null;
+  const fixSetHeadDim = mismatch && parsed && parsed.nh > 0
+                      && parsed.H % parsed.nh === 0
+    ? { head_dim: parsed.H / parsed.nh } : null;
+
+  function applyDraft(overrides: Record<string, number> = {}) {
+    const next: Record<string, number> = { ...value };
+    for (const k of EDITABLE_KEYS) {
+      const n = Number(draft[k]);
+      if (Number.isFinite(n)) next[k] = n;
+    }
+    Object.assign(next, overrides);
+    // Reflect the override back into the visible draft so the user
+    // sees the suggestion they accepted.
+    if (Object.keys(overrides).length > 0) {
+      setDraft({
+        ...draft,
+        ...Object.fromEntries(
+          Object.entries(overrides).map(([k, v]) => [k, String(v)])),
+      });
+    }
+    onApply(next);
+  }
 
   return (
     <div data-testid="dim-env-editor"
@@ -51,15 +81,13 @@ export function DimEnvEditor({ value, onApply }: DimEnvEditorProps): JSX.Element
       ))}
       <button
         data-testid="dim-env-apply"
-        onClick={() => {
-          const next: Record<string, number> = { ...value };
-          for (const k of EDITABLE_KEYS) {
-            const n = Number(draft[k]);
-            if (Number.isFinite(n)) next[k] = n;
-          }
-          onApply(next);
-        }}
-        style={{ padding: "2px 8px" }}
+        onClick={() => applyDraft()}
+        style={{ padding: "2px 8px",
+                 background: mismatch ? "#fef3c7" : undefined,
+                 borderColor: mismatch ? "#d97706" : undefined }}
+        title={mismatch
+          ? "dim_env is inconsistent — see the suggestions on the right"
+          : "Push dim_env to verify"}
       >
         Apply
       </button>
@@ -69,6 +97,26 @@ export function DimEnvEditor({ value, onApply }: DimEnvEditorProps): JSX.Element
           ⚠ {mismatch}
         </span>
       )}
+      {fixSetH && (
+        <button data-testid="dim-env-fix-set-H"
+                onClick={() => applyDraft(fixSetH)}
+                title={`Snap H to ${fixSetH.H} (= nh*head_dim)`}
+                style={{ padding: "2px 8px", background: "#dbeafe",
+                         border: "1px solid #2563eb",
+                         color: "#1e40af" }}>
+          Snap H → {fixSetH.H}
+        </button>
+      )}
+      {fixSetHeadDim && (
+        <button data-testid="dim-env-fix-set-head_dim"
+                onClick={() => applyDraft(fixSetHeadDim)}
+                title={`Snap head_dim to ${fixSetHeadDim.head_dim} (= H/nh)`}
+                style={{ padding: "2px 8px", background: "#dbeafe",
+                         border: "1px solid #2563eb",
+                         color: "#1e40af" }}>
+          Snap head_dim → {fixSetHeadDim.head_dim}
+        </button>
+      )}
     </div>
   );
 }

vbgui/tests/DimEnvEditor.test.tsx

@@ -62,4 +62,37 @@ describe("V7-F56b/F53 DimEnvEditor", () => {
     const warn = screen.getByTestId("dim-env-inline-mismatch");
     expect(warn.textContent).toContain("192");
   });
+
+  it("offers Snap H → fix that applies the consistent value", () => {
+    const onApply = vi.fn();
+    render(<DimEnvEditor
+      value={{ H: 128, nh: 3, head_dim: 50, B: 1, S: 8 }}
+      onApply={onApply}
+    />);
+    const snap = screen.getByTestId("dim-env-fix-set-H");
+    expect(snap.textContent).toContain("150");
+    fireEvent.click(snap);
+    expect(onApply).toHaveBeenCalledTimes(1);
+    expect(onApply.mock.calls[0]?.[0]).toMatchObject({ H: 150 });
+  });
+
+  it("offers Snap head_dim → fix only when H is divisible by nh", () => {
+    // H=128 / nh=8 = 16 → head_dim snap available.
+    render(<DimEnvEditor
+      value={{ H: 128, nh: 8, head_dim: 32, B: 1, S: 8 }}
+      onApply={() => {}}
+    />);
+    const snap = screen.getByTestId("dim-env-fix-set-head_dim");
+    expect(snap.textContent).toContain("16");
+  });
+
+  it("hides Snap head_dim when H is not divisible by nh", () => {
+    // H=128 / nh=3 = 42.66 → head_dim snap NOT available; only H snap.
+    render(<DimEnvEditor
+      value={{ H: 128, nh: 3, head_dim: 50, B: 1, S: 8 }}
+      onApply={() => {}}
+    />);
+    expect(screen.queryByTestId("dim-env-fix-set-head_dim")).toBeNull();
+    expect(screen.getByTestId("dim-env-fix-set-H")).toBeDefined();
+  });
 });