Embedding Explorer: annotations fix, MDS normalization, light mode, design polish

- Switch from Scatter3d text to scene annotations (fixes Plotly WebGL text sizing bug)
- Normalize MDS output to [-1,1] with fixed axis ranges for consistent label sizes
- Force light mode via head script redirect
- Dark purple buttons (#63348d), light purple block backgrounds (#f3f0f7)
- Remove button-like styling from Gradio labels
- Per-word palette colors with lighter neighbor shades
- Add Lecture 7 design discussion (discussion.md)
- Add Embedding Explorer section to tools/CLAUDE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app.py

@@ -19,7 +19,6 @@ import re
 
 import numpy as np
 import plotly.graph_objects as go
-from sklearn.decomposition import PCA
 import gradio as gr
 
 # ── Configuration (all changeable via HF Space env vars) ─────
@@ -49,6 +48,32 @@ DARK = "#1a1a2e"
 GRAY = "#888888"
 BG = "#fafafa"
 
+# Categorical palette for up to 12 words (design-system first, then complements)
+PALETTE = [
+    "#63348d",  # purple (design primary)
+    "#2e86c1",  # blue
+    "#c0392b",  # red
+    "#f0c040",  # gold (design)
+    "#27ae60",  # green
+    "#de95a0",  # pink (design)
+    "#e67e22",  # orange
+    "#1abc9c",  # teal
+    "#8e44ad",  # violet
+    "#d4ac0d",  # dark gold
+    "#2980b9",  # steel blue
+    "#c0392b",  # crimson
+]
+
+
+def lighten(hex_color, amount=0.3):
+    """Lighten a hex color by blending toward white. amount=0.3 → 30% lighter."""
+    h = hex_color.lstrip("#")
+    r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    r = int(r + (255 - r) * amount)
+    g = int(g + (255 - g) * amount)
+    b = int(b + (255 - b) * amount)
+    return f"#{r:02x}{g:02x}{b:02x}"
+
 # ── Load GloVe embeddings on startup ─────────────────────────
 
 import time
@@ -114,32 +139,34 @@ def parse_expression(expr):
     return pos, neg, ordered
 
 
-def fit_pca_3d(vectors):
-    """PCA → 3D. Returns (coords, fitted_pca)."""
+def reduce_3d(vectors):
+    """MDS (cosine distance) → 3D. Normalizes to [-1, 1] for consistent label sizing."""
+    from sklearn.manifold import MDS
+    from sklearn.metrics.pairwise import cosine_distances
     n = len(vectors)
-    nc = min(3, n, vectors.shape[1])
-    pca = PCA(n_components=nc)
-    coords = pca.fit_transform(vectors)
+    if n < 2:
+        return np.zeros((n, 3))
+    dist = cosine_distances(vectors)
+    nc = min(3, n)
+    mds = MDS(n_components=nc, dissimilarity="precomputed",
+              random_state=42, normalized_stress="auto", max_iter=300)
+    coords = mds.fit_transform(dist)
     if nc < 3:
         coords = np.hstack([coords, np.zeros((n, 3 - nc))])
-    return coords, pca
-
-
-def project_3d(pca, vectors):
-    """Project new vectors into an existing PCA space."""
-    coords = pca.transform(vectors)
-    if coords.shape[1] < 3:
-        coords = np.hstack([coords, np.zeros((len(vectors), 3 - coords.shape[1]))])
+    # Normalize to [-1, 1] so axis ranges and label sizes are consistent
+    max_abs = np.abs(coords).max()
+    if max_abs > 1e-8:
+        coords = coords / max_abs
     return coords
 
 
 def _axis(title=""):
-    """Subtle 3D axis with gridlines for depth perception."""
+    """3D axis with visible gridlines for depth perception."""
     return dict(
         showgrid=True,
-        gridcolor="rgba(99,52,141,0.08)",   # very faint purple grid
+        gridcolor="rgba(99,52,141,0.18)",
         zeroline=True,
-        zerolinecolor="rgba(99,52,141,0.25)",
+        zerolinecolor="rgba(99,52,141,0.40)",
         zerolinewidth=2,
         showticklabels=False,
         title=title,
@@ -148,13 +175,19 @@ def _axis(title=""):
     )
 
 
-def layout_3d(height=560):
-    """Shared Plotly 3D layout."""
+def layout_3d(height=700):
+    """Shared Plotly 3D layout. Fixed [-1.3, 1.3] range; preserves camera between updates."""
+    ax_x, ax_y, ax_z = _axis(), _axis(), _axis()
+    # Fixed range since reduce_3d normalizes to [-1, 1]; padding for labels
+    fixed = [-1.3, 1.3]
+    ax_x["range"] = fixed
+    ax_y["range"] = fixed
+    ax_z["range"] = fixed
     return dict(
         scene=dict(
-            xaxis=_axis(),
-            yaxis=_axis(),
-            zaxis=_axis(),
+            xaxis=ax_x,
+            yaxis=ax_y,
+            zaxis=ax_z,
             bgcolor=BG,
             camera=dict(eye=dict(x=1.5, y=1.5, z=1.2)),
             aspectmode="cube",
@@ -163,7 +196,7 @@ def layout_3d(height=560):
         margin=dict(l=0, r=0, t=10, b=10),
         showlegend=True,
         legend=dict(
-            yanchor="top", y=0.99, xanchor="left", x=0.01,
+            yanchor="top", y=0.99, xanchor="right", x=0.99,
             bgcolor="rgba(255,255,255,0.85)",
             font=dict(family="Inter, sans-serif", size=12),
         ),
@@ -172,15 +205,18 @@ def layout_3d(height=560):
     )
 
 
-def add_vectors_from_origin(fig, coords, labels, color=PURPLE, width=3):
+def add_vectors_from_origin(fig, coords, labels, colors=None, widths=None,
+                            default_color=PURPLE, default_width=3):
     """Draw vector lines from origin to each point (words ARE vectors)."""
     for i, label in enumerate(labels):
+        c = colors[i] if colors else default_color
+        w = widths[i] if widths else default_width
         fig.add_trace(go.Scatter3d(
             x=[0, coords[i, 0]],
             y=[0, coords[i, 1]],
             z=[0, coords[i, 2]],
             mode="lines",
-            line=dict(color=color, width=width),
+            line=dict(color=c, width=w),
             showlegend=False, hoverinfo="none",
         ))
     # Origin marker
@@ -232,77 +268,141 @@ def explore(words_text, selected):
 
     valid = valid[:12]  # cap to keep plot readable
 
-    # Main word vectors — PCA fitted on these only (stable positions)
-    vecs = np.array([model[w] for w in valid])
-    main_coords, pca = fit_pca_3d(vecs)
-
-    # Neighbors (projected into the same PCA space)
-    nbr_data, nbr_coords = [], None
+    # Gather neighbors first so we can MDS everything together
+    nbr_data = []
     if selected and selected != "(clear)" and selected in VOCAB and selected in valid:
         nbrs = model.most_similar(selected, topn=N_NEIGHBORS)
         nbr_data = [(w, s) for w, s in nbrs if w not in valid]
-        if nbr_data:
-            nv = np.array([model[w] for w, _ in nbr_data])
-            nbr_coords = project_3d(pca, nv)
     else:
         selected = None
 
+    # Build combined word list and run MDS once
+    all_words = valid + [w for w, _ in nbr_data]
+    all_vecs = np.array([model[w] for w in all_words])
+    all_coords = reduce_3d(all_vecs)
+
+    main_coords = all_coords[:len(valid)]
+    nbr_coords = all_coords[len(valid):] if nbr_data else None
+
+    # ── Assign a distinct color to each word from the palette ──
+    word_colors = {w: PALETTE[i % len(PALETTE)] for i, w in enumerate(valid)}
+
     # ── Build figure ──
     fig = go.Figure()
+    # Collect 3D annotations (HTML overlays — immune to WebGL text sizing bug)
+    annotations = []
+
+    def add_label(x, y, z, text, size=16, color=DARK, opacity=1.0):
+        annotations.append(dict(
+            x=x, y=y, z=z, text=text, showarrow=False,
+            font=dict(size=size, color=color, family="Inter, sans-serif"),
+            opacity=opacity, yshift=18,
+        ))
 
-    # Vector lines from origin to each word
-    add_vectors_from_origin(fig, main_coords, valid)
-
-    # Main words (markers + labels at tips of vectors)
-    fig.add_trace(go.Scatter3d(
-        x=main_coords[:, 0].tolist(),
-        y=main_coords[:, 1].tolist(),
-        z=main_coords[:, 2].tolist(),
-        mode="markers+text",
-        text=valid,
-        textposition="top center",
-        textfont=dict(size=14, color=DARK),
-        marker=dict(
-            size=9, color=PURPLE, opacity=0.9,
-            line=dict(width=1, color="white"),
-        ),
-        name="Words",
-        hoverinfo="text",
-        hovertext=valid,
-    ))
+    if selected:
+        si = valid.index(selected)
+        sel_color = word_colors[selected]
+        nbr_color = lighten(sel_color, 0.3)
+
+        # Vector lines — selected word's line is bold, others are faded
+        vec_colors = [sel_color if w == selected else lighten(word_colors[w], 0.5)
+                      for w in valid]
+        vec_widths = [4 if w == selected else 1.5 for w in valid]
+        add_vectors_from_origin(fig, main_coords, valid,
+                                colors=vec_colors, widths=vec_widths)
+
+        # Dimmed words (not selected) — markers only
+        dim_idx = [i for i in range(len(valid)) if i != si]
+        if dim_idx:
+            fig.add_trace(go.Scatter3d(
+                x=[main_coords[i, 0] for i in dim_idx],
+                y=[main_coords[i, 1] for i in dim_idx],
+                z=[main_coords[i, 2] for i in dim_idx],
+                mode="markers",
+                marker=dict(
+                    size=8,
+                    color=[lighten(word_colors[valid[i]], 0.4) for i in dim_idx],
+                    opacity=0.5,
+                    line=dict(width=1, color="white"),
+                ),
+                name="Words",
+                hoverinfo="text",
+                hovertext=[valid[i] for i in dim_idx],
+            ))
+            for i in dim_idx:
+                add_label(main_coords[i, 0], main_coords[i, 1], main_coords[i, 2],
+                          valid[i], size=15,
+                          color=lighten(word_colors[valid[i]], 0.4), opacity=0.7)
 
-    # Neighbors + connection lines
-    if nbr_data and nbr_coords is not None:
+        # Selected word — bright, full color, markers only
         fig.add_trace(go.Scatter3d(
-            x=nbr_coords[:, 0].tolist(),
-            y=nbr_coords[:, 1].tolist(),
-            z=nbr_coords[:, 2].tolist(),
-            mode="markers+text",
-            text=[w for w, _ in nbr_data],
-            textposition="top center",
-            textfont=dict(size=11, color=GRAY),
+            x=[main_coords[si, 0]],
+            y=[main_coords[si, 1]],
+            z=[main_coords[si, 2]],
+            mode="markers",
             marker=dict(
-                size=5, color=PURPLE_LIGHT, opacity=0.8,
-                line=dict(width=1, color=PURPLE),
+                size=14, color=sel_color, opacity=1.0,
+                line=dict(width=2, color="white"),
             ),
-            name=f'Near "{selected}"',
+            name=f"Selected: {selected}",
             hoverinfo="text",
-            hovertext=[f"{w} ({s:.3f})" for w, s in nbr_data],
+            hovertext=[f"{selected} (selected)"],
         ))
+        add_label(main_coords[si, 0], main_coords[si, 1], main_coords[si, 2],
+                  f"<b>{selected}</b>", size=18, color=DARK)
 
-        # Dotted lines from selected word to its neighbors
-        si = valid.index(selected)
-        for i in range(len(nbr_data)):
+        # Neighbors — lighter shade of the selected word's color
+        if nbr_data and nbr_coords is not None:
             fig.add_trace(go.Scatter3d(
-                x=[main_coords[si, 0], nbr_coords[i, 0]],
-                y=[main_coords[si, 1], nbr_coords[i, 1]],
-                z=[main_coords[si, 2], nbr_coords[i, 2]],
-                mode="lines",
-                line=dict(color=PURPLE_LIGHT, width=2, dash="dot"),
-                showlegend=False, hoverinfo="none",
+                x=nbr_coords[:, 0].tolist(),
+                y=nbr_coords[:, 1].tolist(),
+                z=nbr_coords[:, 2].tolist(),
+                mode="markers",
+                marker=dict(
+                    size=9, color=nbr_color, opacity=0.9,
+                    line=dict(width=1, color=sel_color),
+                ),
+                name=f'Near "{selected}"',
+                hoverinfo="text",
+                hovertext=[f"{w} ({s:.3f})" for w, s in nbr_data],
             ))
+            for i, (w, s) in enumerate(nbr_data):
+                add_label(nbr_coords[i, 0], nbr_coords[i, 1], nbr_coords[i, 2],
+                          w, size=16, color=DARK)
+
+            # Dotted lines from selected word to its neighbors
+            for i in range(len(nbr_data)):
+                fig.add_trace(go.Scatter3d(
+                    x=[main_coords[si, 0], nbr_coords[i, 0]],
+                    y=[main_coords[si, 1], nbr_coords[i, 1]],
+                    z=[main_coords[si, 2], nbr_coords[i, 2]],
+                    mode="lines",
+                    line=dict(color=nbr_color, width=2, dash="dot"),
+                    showlegend=False, hoverinfo="none",
+                ))
+    else:
+        # No selection — each word gets its own color, markers only
+        colors = [word_colors[w] for w in valid]
+        add_vectors_from_origin(fig, main_coords, valid, colors=colors)
 
-    fig.update_layout(**layout_3d())
+        fig.add_trace(go.Scatter3d(
+            x=main_coords[:, 0].tolist(),
+            y=main_coords[:, 1].tolist(),
+            z=main_coords[:, 2].tolist(),
+            mode="markers",
+            marker=dict(
+                size=10, color=colors, opacity=0.9,
+                line=dict(width=1, color="white"),
+            ),
+            name="Words",
+            hoverinfo="text",
+            hovertext=valid,
+        ))
+        for i, w in enumerate(valid):
+            add_label(main_coords[i, 0], main_coords[i, 1], main_coords[i, 2],
+                      w, size=16, color=DARK)
+
+    fig.update_layout(**layout_3d(), scene_annotations=annotations)
 
     # Status
     status = f"**{len(valid)} words** in 3D"
@@ -358,14 +458,14 @@ def arithmetic(expression):
     for w in neg:
         rv -= model[w]
 
-    # Collect all words for PCA
+    # Collect all words for MDS
     result_words = [w for w, _ in result_entries]
     all_words = operands + result_words
     all_vecs = np.array([model[w] for w in all_words])
 
-    # Include result vector in PCA fit for best view
+    # Include result vector in MDS fit for best view
     combined = np.vstack([all_vecs, rv.reshape(1, -1)])
-    coords_all, _ = fit_pca_3d(combined)
+    coords_all = reduce_3d(combined)
 
     rv_coord = coords_all[-1]
     coords = coords_all[:-1]
@@ -409,7 +509,7 @@ def arithmetic(expression):
             mode="markers+text",
             text=[operands[i] for i in pi],
             textposition="top center",
-            textfont=dict(size=14, color=DARK),
+            textfont=dict(size=18, color=DARK),
             marker=dict(size=10, color=PURPLE, opacity=0.9),
             name="Positive (+)",
             hoverinfo="text",
@@ -426,7 +526,7 @@ def arithmetic(expression):
             mode="markers+text",
             text=[operands[i] for i in ni],
             textposition="top center",
-            textfont=dict(size=14, color=DARK),
+            textfont=dict(size=18, color=DARK),
             marker=dict(size=10, color=PINK, opacity=0.9),
             name="Negative (−)",
             hoverinfo="text",
@@ -440,7 +540,7 @@ def arithmetic(expression):
         mode="markers+text",
         text=[f"≈ {top_result[0]}"],
         textposition="top center",
-        textfont=dict(size=16, color=PURPLE),
+        textfont=dict(size=20, color=PURPLE),
         marker=dict(
             size=14, color=GOLD, opacity=1.0, symbol="diamond",
             line=dict(width=2, color=PURPLE),
@@ -460,8 +560,8 @@ def arithmetic(expression):
             mode="markers+text",
             text=[f"{w} ({s:.2f})" for w, s in other_results],
             textposition="top center",
-            textfont=dict(size=11, color=GRAY),
-            marker=dict(size=5, color=PURPLE_LIGHT, opacity=0.7),
+            textfont=dict(size=14, color=GRAY),
+            marker=dict(size=6, color=PURPLE_LIGHT, opacity=0.7),
             name="Other matches",
             hoverinfo="text",
             hovertext=[f"{w} ({s:.3f})" for w, s in other_results],
@@ -514,13 +614,58 @@ def arithmetic(expression):
 CSS = """
 .gradio-container { max-width: 1200px !important; }
 h1 { color: #63348d !important; }
+
+
+/* Remove button-like styling from labels */
+.gradio-container label span {
+    border: none !important;
+    background: transparent !important;
+    box-shadow: none !important;
+    padding-left: 0 !important;
+    font-weight: 600 !important;
+    color: #63348d !important;
+}
+
+/* Block backgrounds — light purple instead of near-white */
+.gradio-container .block {
+    background: #f3f0f7 !important;
+    border: 1px solid #ded9f4 !important;
+}
+
+/* Input fields should be white for contrast against purple blocks */
+.gradio-container textarea,
+.gradio-container input[type="text"] {
+    background: #ffffff !important;
+}
+
+/* Tab styling */
+.gradio-container button.tab-nav-button.selected {
+    color: #63348d !important;
+    border-bottom-color: #63348d !important;
+}
+
+/* Radio items — less boxy */
+.gradio-container .wrap .radio-group label {
+    border: none !important;
+    background: transparent !important;
+}
 """
 
+FORCE_LIGHT = '<script>if(!location.search.includes("__theme=light")){const u=new URL(location);u.searchParams.set("__theme","light");location.replace(u)}</script>'
+
 with gr.Blocks(
     title="Embedding Explorer",
+    head=FORCE_LIGHT,
     theme=gr.themes.Soft(
         primary_hue="purple",
         font=gr.themes.GoogleFont("Inter"),
+    ).set(
+        button_primary_background_fill="#63348d",
+        button_primary_background_fill_hover="#4a2769",
+        button_primary_text_color="#ffffff",
+        block_background_fill="#f3f0f7",
+        block_border_color="#ded9f4",
+        body_background_fill="#ffffff",
     ),
     css=CSS,
 ) as demo:
@@ -543,27 +688,27 @@ with gr.Blocks(
                 "Similar words cluster together. "
                 "Click a word below the plot to see its nearest neighbors.*"
             )
+            exp_plot = gr.Plot(label="Embedding Space")
             with gr.Row():
-                with gr.Column(scale=1):
+                with gr.Column(scale=2):
                     exp_in = gr.Textbox(
                         label="Words (space-separated, min 3)",
                         placeholder="dog cat fish car truck",
                         lines=1,
                     )
+                with gr.Column(scale=1):
                     exp_btn = gr.Button("Show in 3D", variant="primary")
-                    exp_status = gr.Markdown("")
-                    exp_radio = gr.Radio(
-                        label="Click to see nearest neighbors",
-                        choices=[], value=None,
-                        visible=False, interactive=True,
-                    )
-                    gr.Examples(
-                        examples=[[e] for e in EXPLORE_EXAMPLES],
-                        inputs=[exp_in],
-                        label="Try these",
-                    )
-                with gr.Column(scale=2):
-                    exp_plot = gr.Plot(label="Embedding Space")
+            exp_status = gr.Markdown("")
+            exp_radio = gr.Radio(
+                label="Click to see nearest neighbors",
+                choices=[], value=None,
+                visible=False, interactive=True,
+            )
+            gr.Examples(
+                examples=[[e] for e in EXPLORE_EXAMPLES],
+                inputs=[exp_in],
+                label="Try these",
+            )
 
             # Events
             exp_btn.click(
@@ -588,22 +733,22 @@ with gr.Blocks(
                 "*Word vectors can do math! "
                 "The results reveal hidden relationships between words.*"
             )
+            math_plot = gr.Plot(label="Vector Arithmetic")
             with gr.Row():
-                with gr.Column(scale=1):
+                with gr.Column(scale=2):
                     math_in = gr.Textbox(
                         label="Expression",
                         placeholder="king - man + woman",
                         lines=1,
                     )
+                with gr.Column(scale=1):
                     math_btn = gr.Button("Compute", variant="primary")
-                    math_status = gr.Markdown("")
-                    gr.Examples(
-                        examples=[[e] for e in ARITHMETIC_EXAMPLES],
-                        inputs=[math_in],
-                        label="Try these",
-                    )
-                with gr.Column(scale=2):
-                    math_plot = gr.Plot(label="Vector Arithmetic")
+            math_status = gr.Markdown("")
+            gr.Examples(
+                examples=[[e] for e in ARITHMETIC_EXAMPLES],
+                inputs=[math_in],
+                label="Try these",
+            )
 
             # Events
             math_btn.click(