Embedding Explorer: add visibility toggles, camera persistence, and share URLs

- Visibility CheckboxGroup to show/hide items without recomputing MDS
(for progressive slide screenshots)
- Camera persistence across re-renders via JS polling of Plotly camera
state into hidden textbox
- Share button encodes input, visibility, camera into URL params
(Rebrandly shortening on HF Spaces, full URL on localhost)
- Share URL loading restores full state including camera angle
- Loading flag suppresses cascading Gradio events during share restore
- Fixed Gradio 6.x: moved theme/css/head to launch(), buttons=["copy"]

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

app.py

@@ -15,6 +15,8 @@ import os
 import json
 import re
 import warnings
+import urllib.parse
+import subprocess
 
 import pandas  # noqa: F401 — import before plotly to avoid circular import
 import numpy as np
@@ -36,6 +38,16 @@ EXAMPLES = json.loads(os.environ.get("EXAMPLES", json.dumps([
 
 N_NEIGHBORS = int(os.environ.get("N_NEIGHBORS", "8"))
 
+# ── Share URL infrastructure ─────────────────────────────────
+
+REBRANDLY_API_KEY = os.environ.get("REBRANDLY_API_KEY", "")
+_SPACE_ID = os.environ.get("SPACE_ID", "")
+if _SPACE_ID:
+    _owner, _name = _SPACE_ID.split("/")
+    _BASE_URL = f"https://{_owner}-{_name}.hf.space/"
+else:
+    _BASE_URL = "http://localhost:7860/"
+
 # ── Course design system colors ──────────────────────────────
 
 PURPLE = "#63348d"
@@ -247,20 +259,21 @@ def _axis(title=""):
     )
 
 
-def layout_3d(height=700, axis_range=1.3):
-    """Shared Plotly 3D layout. Preserves camera between updates."""
+def layout_3d(height=700, axis_range=1.3, camera=None):
+    """Shared Plotly 3D layout. Uses uirevision to preserve camera across updates."""
     ax_x, ax_y, ax_z = _axis(), _axis(), _axis()
     fixed = [-axis_range, axis_range]
     ax_x["range"] = fixed
     ax_y["range"] = fixed
     ax_z["range"] = fixed
+    default_camera = dict(eye=dict(x=1.5, y=1.5, z=1.2))
     return dict(
         scene=dict(
             xaxis=ax_x,
             yaxis=ax_y,
             zaxis=ax_z,
             bgcolor="white",
-            camera=dict(eye=dict(x=1.5, y=1.5, z=1.2)),
+            camera=camera or default_camera,
             aspectmode="cube",
         ),
         paper_bgcolor="white",
@@ -273,6 +286,7 @@ def layout_3d(height=700, axis_range=1.3):
         ),
         height=height,
         font=dict(family="Inter, sans-serif"),
+        uirevision="keep",
     )
 
 
@@ -393,15 +407,86 @@ def blank(msg):
     return fig
 
 
+# ── Share URL helpers ────────────────────────────────────────
+
+def _shorten_url(long_url):
+    """Shorten a URL via Rebrandly API (using curl). Falls back to long URL."""
+    if not REBRANDLY_API_KEY or "localhost" in long_url:
+        return long_url
+    try:
+        payload = json.dumps({
+            "destination": long_url,
+            "domain": {"fullName": "go.ropavieja.org"},
+        })
+        result = subprocess.run(
+            [
+                "curl", "-s", "-X", "POST",
+                "https://api.rebrandly.com/v1/links",
+                "-H", "Content-Type: application/json",
+                "-H", f"apikey: {REBRANDLY_API_KEY}",
+                "-d", payload,
+            ],
+            capture_output=True, text=True, timeout=10,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return long_url
+        data = json.loads(result.stdout)
+        return f"https://{data['shortUrl']}"
+    except (subprocess.TimeoutExpired, KeyError, json.JSONDecodeError, OSError) as exc:
+        print(f"[share] Rebrandly error: {exc}")
+        return long_url
+
+
+def _parse_camera(cam_str):
+    """Parse compact camera string (ex,ey,ez[,cx,cy,cz,ux,uy,uz]) to Plotly camera dict."""
+    if not cam_str:
+        return None
+    try:
+        vals = [float(v) for v in cam_str.split(",")]
+        if len(vals) >= 3:
+            camera = dict(eye=dict(x=vals[0], y=vals[1], z=vals[2]))
+            if len(vals) >= 6:
+                camera["center"] = dict(x=vals[3], y=vals[4], z=vals[5])
+            if len(vals) >= 9:
+                camera["up"] = dict(x=vals[6], y=vals[7], z=vals[8])
+            return camera
+    except (ValueError, IndexError):
+        pass
+    return None
+
+
+def _encode_camera(camera_json):
+    """Encode Plotly camera JSON to compact string for URL params."""
+    if not camera_json:
+        return ""
+    try:
+        cam = json.loads(camera_json)
+        eye = cam.get("eye", {})
+        center = cam.get("center", {})
+        up = cam.get("up", {})
+        vals = [
+            eye.get("x", 1.5), eye.get("y", 1.5), eye.get("z", 1.2),
+            center.get("x", 0), center.get("y", 0), center.get("z", 0),
+            up.get("x", 0), up.get("y", 0), up.get("z", 1),
+        ]
+        return ",".join(f"{v:.2f}" for v in vals)
+    except (json.JSONDecodeError, TypeError):
+        return ""
+
+
 # ── Main visualization ───────────────────────────────────────
 
-def explore(input_text, selected):
+def explore(input_text, selected, hidden=None, camera=None):
     """Unified 3D visualization of words and vector expressions.
 
-    Expressions show geometric construction:
-      a - b  → operand arrows from origin + gold arrow from b to a
-      a + b  → a from origin, b from a's tip, gold result from origin
-      a - b + c → chain arrows + gold result from origin
+    Args:
+        input_text: Comma-separated words and/or expressions.
+        selected: Currently selected item for neighbor display (or None).
+        hidden: Set of labels to hide from rendering (MDS still uses all items).
+        camera: Plotly camera dict to set initial view.
+
+    Returns:
+        (fig, status_md, radio_update, all_labels)
     """
 
     if not input_text or not input_text.strip():
@@ -409,6 +494,7 @@ def explore(input_text, selected):
             blank("Enter words or expressions above to visualize in 3D"),
             "",
             gr.update(choices=[], value=None, visible=False),
+            [],
         )
 
     items, bad = parse_items(input_text)
@@ -417,13 +503,17 @@ def explore(input_text, selected):
         msg = "No valid items found."
         if bad:
             msg += f"<br>Not in vocabulary: {', '.join(bad)}"
-        return blank(msg), "", gr.update(choices=[], value=None, visible=False)
+        return blank(msg), "", gr.update(choices=[], value=None, visible=False), []
 
     items = items[:12]
     labels = [item[0] for item in items]
+    hidden = hidden or set()
+
+    # Visible labels for radio choices (exclude hidden)
+    visible_labels = [l for l in labels if l not in hidden]
 
     # No auto-select — user clicks radio to see neighbors
-    if selected and selected != "(clear)" and selected in labels:
+    if selected and selected != "(clear)" and selected in visible_labels:
         sel_idx = labels.index(selected)
     else:
         selected = None
@@ -476,7 +566,7 @@ def explore(input_text, selected):
                 if len(all_words) >= 3:
                     break
 
-    # Gather neighbors if something is selected
+    # Gather neighbors if something is selected (and not hidden)
     nbr_data = []
     if selected is not None:
         sel_item = items[sel_idx]
@@ -496,7 +586,7 @@ def explore(input_text, selected):
     mds_words = all_words + [w for w, _ in nbr_data]
     if not mds_words:
         return blank("No valid words found."), "", gr.update(
-            choices=[], value=None, visible=False)
+            choices=[], value=None, visible=False), []
 
     mds_vecs = np.array([model[w] for w in mds_words])
     mds_coords = reduce_3d(mds_vecs)
@@ -536,7 +626,7 @@ def explore(input_text, selected):
                 extra_points.append(cursor.copy())
             expr_info[label] = ('chain', chain, cursor.copy())
 
-    # ── Dynamic axis range ──
+    # ── Dynamic axis range (computed from ALL items, not just visible) ──
     all_rendered = [word_3d[w] for w in all_words] + extra_points
     if nbr_coords is not None:
         all_rendered.extend(nbr_coords)
@@ -569,6 +659,10 @@ def explore(input_text, selected):
         ))
 
     for idx, (label, vec, is_expr, ops, ordered) in enumerate(items):
+        # Skip hidden items
+        if label in hidden:
+            continue
+
         color = item_colors[idx]
         is_sel = (sel_idx is not None and idx == sel_idx)
         is_dim = (sel_idx is not None and idx != sel_idx)
@@ -701,31 +795,37 @@ def explore(input_text, selected):
             add_label(nbr_coords[i, 0], nbr_coords[i, 1], nbr_coords[i, 2],
                       w, size=16, color=DARK)
 
-    fig.update_layout(**layout_3d(axis_range=axis_range),
+    fig.update_layout(**layout_3d(axis_range=axis_range, camera=camera),
                       scene_annotations=annotations)
 
     # ── Status text ──
-    n_words = sum(1 for _, _, ie, _, _ in items if not ie)
-    n_expr = sum(1 for _, _, ie, _, _ in items if ie)
+    n_visible = sum(1 for l, _, ie, _, _ in items if l not in hidden)
+    n_hidden = len(hidden & set(labels))
+    n_words = sum(1 for l, _, ie, _, _ in items if not ie and l not in hidden)
+    n_expr = sum(1 for l, _, ie, _, _ in items if ie and l not in hidden)
     parts = []
     if n_words:
         parts.append(f"**{n_words} word{'s' if n_words != 1 else ''}**")
     if n_expr:
         parts.append(f"**{n_expr} expression{'s' if n_expr != 1 else ''}**")
-    status = " + ".join(parts) + " in 3D"
+    status = " + ".join(parts) + " in 3D" if parts else "Nothing visible"
+    if n_hidden:
+        status += f" · {n_hidden} hidden"
     if bad:
         status += f" · Not found: {', '.join(bad)}"
     for label in expr_nearest:
-        w, s = expr_nearest[label]
-        status += f" · **{label} ≈ {w}** ({s:.3f})"
+        if label not in hidden:
+            w, s = expr_nearest[label]
+            status += f" · **{label} ≈ {w}** ({s:.3f})"
     if nbr_data:
         status += f" · {len(nbr_data)} neighbors of **{selected}**"
 
-    choices = ["(clear)"] + labels
+    choices = ["(clear)"] + visible_labels
     return (
         fig,
         status,
         gr.update(choices=choices, value=selected or "(clear)", visible=True),
+        labels,
     )
 
 
@@ -760,13 +860,77 @@ h1 { color: #63348d !important; }
     color: #ffffff !important;
 }
 
+/* Visibility checkboxes — compact */
+.vis-cbg label {
+    color: #63348d !important;
+    border: 1px solid #63348d !important;
+    border-radius: 6px !important;
+}
+.vis-cbg label.selected {
+    background: #63348d !important;
+    color: #ffffff !important;
+}
+.vis-cbg label.selected * {
+    color: #ffffff !important;
+}
+
 /* Input fields — white for contrast */
 textarea, input[type="text"] {
     background: #ffffff !important;
 }
 """
 
-FORCE_LIGHT = '<script>if(!location.search.includes("__theme=light")){const u=new URL(location);u.searchParams.set("__theme","light");location.replace(u)}</script>'
+FORCE_LIGHT = """
+<script>
+if(!location.search.includes("__theme=light")){
+    const u=new URL(location);u.searchParams.set("__theme","light");location.replace(u);
+}
+</script>
+<script>
+// Camera tracker — polls Plotly camera into hidden textbox for Gradio to read
+(function() {
+    console.log('[cam] Camera tracker script loaded');
+    var attempts = 0;
+    var interval = setInterval(function() {
+        attempts++;
+        var plots = document.querySelectorAll('.js-plotly-plot');
+        if (plots.length === 0) {
+            if (attempts % 20 === 0) console.log('[cam] waiting for plot...', attempts);
+            return;
+        }
+        var plot = plots[0];
+        if (!plot._fullLayout || !plot._fullLayout.scene || !plot._fullLayout.scene._scene) {
+            if (attempts % 20 === 0) console.log('[cam] plot found but no scene yet');
+            return;
+        }
+        try {
+            var cam = plot._fullLayout.scene._scene.getCamera();
+            var el = document.querySelector('#camera_txt textarea, #camera_txt input');
+            if (!el) {
+                console.log('[cam] cannot find #camera_txt element');
+                return;
+            }
+            var val = JSON.stringify(cam);
+            if (el.value !== val) {
+                el.value = val;
+                var nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+                    window.HTMLTextAreaElement.prototype, 'value'
+                ) || Object.getOwnPropertyDescriptor(
+                    window.HTMLInputElement.prototype, 'value'
+                );
+                if (nativeInputValueSetter && nativeInputValueSetter.set) {
+                    nativeInputValueSetter.set.call(el, val);
+                }
+                el.dispatchEvent(new Event('input', {bubbles: true}));
+                el.dispatchEvent(new Event('change', {bubbles: true}));
+            }
+        } catch(e) {
+            console.log('[cam] error:', e);
+        }
+    }, 500);
+})();
+</script>
+"""
 
 _LIGHT = {
     "button_primary_background_fill": "#63348d",
@@ -800,9 +964,15 @@ THEME = gr.themes.Soft(
     font=gr.themes.GoogleFont("Inter"),
 ).set(**_ALL)
 
-with gr.Blocks(title="Embedding Explorer", theme=THEME, css=CSS, head=FORCE_LIGHT) as demo:
+with gr.Blocks(title="Embedding Explorer") as demo:
 
-    # Force light mode — head param doesn't execute on HF Spaces
+    # ── State ──
+    all_labels_state = gr.State([])
+    loading_share = gr.State(False)  # suppress cascading events during share load
+    camera_txt = gr.Textbox(visible=False, elem_id="camera_txt")
+    share_params = gr.State({})
+
+    # Force light mode fallback (head param covers most cases, this catches HF Spaces)
     gr.HTML('<script>if(!location.search.includes("__theme=light"))'
             '{const u=new URL(location);u.searchParams.set("__theme","light");'
             'location.replace(u)}</script>')
@@ -830,7 +1000,12 @@ with gr.Blocks(title="Embedding Explorer", theme=THEME, css=CSS, head=FORCE_LIGH
                 lines=1,
             )
         with gr.Column(scale=1):
-            exp_btn = gr.Button("Explore", variant="primary")
+            with gr.Row():
+                exp_btn = gr.Button("Explore", variant="primary")
+                share_btn = gr.Button("Share", variant="secondary",
+                                      scale=0, min_width=80)
+    share_url = gr.Textbox(label="Share URL", visible=False,
+                           interactive=False, buttons=["copy"])
     with gr.Column(elem_classes=["purple-examples"]):
         gr.Examples(
             examples=[[e] for e in EXAMPLES],
@@ -839,6 +1014,12 @@ with gr.Blocks(title="Embedding Explorer", theme=THEME, css=CSS, head=FORCE_LIGH
         )
     exp_plot = gr.Plot(label="Embedding Space")
     exp_status = gr.Markdown("")
+    vis_cbg = gr.CheckboxGroup(
+        label="Visible items (uncheck to hide)",
+        choices=[], value=[],
+        visible=False, interactive=True,
+        elem_classes=["vis-cbg"],
+    )
     exp_radio = gr.Radio(
         label="Click to see nearest neighbors",
         choices=[], value=None,
@@ -846,21 +1027,177 @@ with gr.Blocks(title="Embedding Explorer", theme=THEME, css=CSS, head=FORCE_LIGH
         elem_classes=["nbr-radio"],
     )
 
-    # Events
+    # ── Event handlers ──
+
+    def _parse_camera_json(camera_json):
+        """Parse camera JSON string (from JS bridge) into Plotly camera dict."""
+        if not camera_json:
+            return None
+        try:
+            return json.loads(camera_json)
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    def on_explore(input_text):
+        """Fresh explore — compute MDS, show all items, reset checkboxes."""
+        fig, status, radio, labels = explore(input_text, None)
+        cbg = gr.update(choices=labels, value=labels, visible=bool(labels))
+        return fig, status, radio, labels, cbg
+
+    def on_radio(input_text, selected, all_labels, visible, camera_json, is_loading):
+        """Neighbor selection — re-render with current visibility + camera."""
+        if is_loading:
+            return gr.update(), gr.update(), gr.update(), False
+        hidden = set(all_labels) - set(visible) if all_labels and visible else set()
+        camera = _parse_camera_json(camera_json)
+        fig, status, radio, _ = explore(input_text, selected, hidden=hidden or None, camera=camera)
+        return fig, status, radio, False
+
+    def on_visibility(input_text, selected, all_labels, visible, camera_json, is_loading):
+        """Visibility toggle — re-render with updated hidden set + camera."""
+        if is_loading:
+            return gr.update(), gr.update(), gr.update(), False
+        hidden = set(all_labels) - set(visible) if all_labels else set()
+        # If selected item is now hidden, clear selection
+        if selected and selected != "(clear)" and selected in hidden:
+            selected = None
+        camera = _parse_camera_json(camera_json)
+        fig, status, radio, _ = explore(input_text, selected, hidden=hidden or None, camera=camera)
+        return fig, status, radio, False
+
+    def on_share(input_text, selected, visible, camera_json, request: gr.Request):
+        """Build share URL encoding current state."""
+        params = {}
+        if input_text and input_text.strip():
+            params["q"] = input_text.strip()
+        if selected and selected != "(clear)":
+            params["sel"] = selected
+        # Only encode visibility if some items are hidden
+        if visible is not None and isinstance(visible, list):
+            params["vis"] = ",".join(visible)
+        if camera_json:
+            encoded = _encode_camera(camera_json)
+            if encoded:
+                params["cam"] = encoded
+        if not params.get("q"):
+            return gr.update(value="Nothing to share", visible=True)
+        # Build base URL from request (gets correct port for local dev)
+        base_url = _BASE_URL
+        if request:
+            host = request.headers.get("host", "")
+            if host:
+                scheme = "https" if _SPACE_ID else "http"
+                base_url = f"{scheme}://{host}/"
+        long_url = base_url + "?" + urllib.parse.urlencode(params)
+        # On localhost, just return the full URL (Rebrandly rejects non-public URLs)
+        if "localhost" in long_url or "127.0.0.1" in long_url:
+            return gr.update(value=long_url, visible=True)
+        short = _shorten_url(long_url)
+        return gr.update(value=short, visible=True)
+
+    # ── Wire up events ──
+
     exp_btn.click(
-        lambda w: explore(w, None),
+        on_explore,
         inputs=[exp_in],
-        outputs=[exp_plot, exp_status, exp_radio],
+        outputs=[exp_plot, exp_status, exp_radio, all_labels_state, vis_cbg],
     )
     exp_in.submit(
-        lambda w: explore(w, None),
+        on_explore,
         inputs=[exp_in],
-        outputs=[exp_plot, exp_status, exp_radio],
+        outputs=[exp_plot, exp_status, exp_radio, all_labels_state, vis_cbg],
     )
+    # Radio + visibility: camera_txt is kept up-to-date by polling script
     exp_radio.change(
-        explore,
-        inputs=[exp_in, exp_radio],
-        outputs=[exp_plot, exp_status, exp_radio],
+        on_radio,
+        inputs=[exp_in, exp_radio, all_labels_state, vis_cbg, camera_txt, loading_share],
+        outputs=[exp_plot, exp_status, exp_radio, loading_share],
+    )
+    vis_cbg.change(
+        on_visibility,
+        inputs=[exp_in, exp_radio, all_labels_state, vis_cbg, camera_txt, loading_share],
+        outputs=[exp_plot, exp_status, exp_radio, loading_share],
+    )
+
+    # Share: camera_txt kept up-to-date by polling script
+    share_btn.click(
+        fn=on_share,
+        inputs=[exp_in, exp_radio, vis_cbg, camera_txt],
+        outputs=[share_url],
+    )
+
+    # ── Share URL loading ──
+
+    def load_share_params(request: gr.Request):
+        """Step 1: Parse query params from URL."""
+        qp = dict(request.query_params) if request else {}
+        return qp
+
+    def apply_share_params(params):
+        """Step 2: Apply share params — set input, run explore, apply visibility + camera."""
+        if not params or "q" not in params:
+            return (
+                gr.update(),  # exp_in
+                gr.update(),  # exp_plot
+                gr.update(),  # exp_status
+                gr.update(),  # exp_radio
+                gr.update(),  # vis_cbg
+                [],           # all_labels_state
+                gr.update(),  # camera_txt
+                False,        # loading_share
+            )
+
+        input_text = params.get("q", "")
+        selected = params.get("sel")
+        if selected == "":
+            selected = None
+        vis_str = params.get("vis")
+        cam_str = params.get("cam")
+
+        camera = _parse_camera(cam_str)
+
+        # First explore with all items visible to get labels
+        _, _, _, labels = explore(input_text, None, camera=camera)
+
+        # Apply visibility
+        if vis_str:
+            visible = [v.strip() for v in vis_str.split(",")]
+            hidden = set(labels) - set(visible)
+        else:
+            visible = labels
+            hidden = set()
+
+        fig, status, radio, _ = explore(
+            input_text, selected, hidden=hidden or None, camera=camera
+        )
+
+        cbg = gr.update(
+            choices=labels,
+            value=visible,
+            visible=bool(labels),
+        )
+
+        # Pre-populate camera_txt so subsequent re-renders preserve camera
+        camera_json = json.dumps(camera) if camera else ""
+
+        return (
+            gr.update(value=input_text),
+            fig,
+            status,
+            radio,
+            cbg,
+            labels,
+            gr.update(value=camera_json),
+            True,  # loading_share — suppress cascading events
+        )
+
+    demo.load(
+        fn=load_share_params,
+        outputs=[share_params],
+    ).then(
+        fn=apply_share_params,
+        inputs=[share_params],
+        outputs=[exp_in, exp_plot, exp_status, exp_radio, vis_cbg, all_labels_state, camera_txt, loading_share],
     )
 
-demo.launch()
+demo.launch(theme=THEME, css=CSS, head=FORCE_LIGHT)