Use actual scatter layout composition

.hyperview/extensions/fashion-search-readout/panel.js

@@ -67,6 +67,7 @@ function normalizeModels(value) {
       model.buttonLabel || model.button_label || `${model.displayName || model.key || "Model"} query`,
     ),
     layoutKey: model.layoutKey || model.layout_key || null,
+    spaceKey: model.spaceKey || model.space_key || null,
   }));
 }
 
@@ -316,6 +317,7 @@ function RankedResultStrip({ item, model, rows, targetRank, loadingKey, onSelect
 
 function SearchResultComparison({ item, models, loadingKey, onSelectResult }) {
   const proof = rankedResults[item.id];
+  const hasInspectableLayouts = models.some((model) => model.layoutKey);
   if (!proof) {
     return React.createElement(
       "div",
@@ -345,7 +347,9 @@ function SearchResultComparison({ item, models, loadingKey, onSelectResult }) {
       React.createElement(
         "div",
         { style: { color: colors.mutedText, fontSize: 10, marginTop: 3 } },
-        "Green card = exact product. Click any card to select it in Samples.",
+        hasInspectableLayouts
+          ? "Green card = exact product. Click a card to inspect it in Samples and the model neighborhood."
+          : "Green card = exact product. Click a card to select it in Samples.",
       ),
     ),
     models.map((model) =>
@@ -601,8 +605,11 @@ export default function FashionSearchComparisonPanel() {
   const panelProps = usePanelProps();
   const [panelError, setPanelError] = React.useState(null);
   const [loadingKey, setLoadingKey] = React.useState(null);
-  const [selectedExampleId, setSelectedExampleId] = React.useState(null);
+  const [selectedExampleId, setSelectedExampleId] = React.useState(() =>
+    typeof panelProps.initialExampleId === "string" ? panelProps.initialExampleId : null,
+  );
   const didApplyDemoLayout = React.useRef(false);
+  const didPrimeEvidence = React.useRef(false);
   const mode = panelProps.mode === "summary" ? "summary" : panelProps.mode === "results" ? "results" : "full";
 
   const models = React.useMemo(() => normalizeModels(panelProps.models), [panelProps.models]);
@@ -636,10 +643,42 @@ export default function FashionSearchComparisonPanel() {
     return () => window.removeEventListener("fashion-search-example-change", handleExampleChange);
   }, []);
 
-  const chooseExample = React.useCallback((exampleId) => {
-    setSelectedExampleId(exampleId);
-    window.dispatchEvent(new CustomEvent("fashion-search-example-change", { detail: exampleId }));
-  }, []);
+  const showExampleEvidence = React.useCallback(
+    async (item, model, source = "fashion-demo:query") => {
+      if (!item || !model?.layoutKey) return;
+      try {
+        await commands.setActiveLayout(model.layoutKey, { persist: false });
+        await commands.showSimilar({
+          sampleId: item.queryId,
+          layoutKey: model.layoutKey,
+          spaceKey: model.spaceKey,
+          k: 10,
+          source,
+          focus: "samples",
+          persist: false,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        setPanelError(`Could not load the sample evidence panel: ${message}`);
+      }
+    },
+    [commands],
+  );
+
+  const chooseExample = React.useCallback(
+    (exampleId) => {
+      setSelectedExampleId(exampleId);
+      window.dispatchEvent(new CustomEvent("fashion-search-example-change", { detail: exampleId }));
+      const item = examples.find((entry) => entry.id === exampleId);
+      const evidenceModel =
+        models.find((model) => model.key === "clip" && model.layoutKey) ||
+        models.find((model) => model.layoutKey);
+      if (item && evidenceModel) {
+        void showExampleEvidence(item, evidenceModel, "fashion-demo:query-picker");
+      }
+    },
+    [examples, models, showExampleEvidence],
+  );
 
   React.useEffect(() => {
     if (mode === "summary") return;
@@ -663,6 +702,23 @@ export default function FashionSearchComparisonPanel() {
     return () => window.clearInterval(timer);
   }, [commands, mode]);
 
+  React.useEffect(() => {
+    if (mode === "summary") return;
+    if (didPrimeEvidence.current) return;
+    if (!selectedExample) return;
+    const evidenceModel =
+      models.find((model) => model.key === "clip" && model.layoutKey) ||
+      models.find((model) => model.layoutKey);
+    if (!evidenceModel) return;
+    didPrimeEvidence.current = true;
+
+    const timer = window.setTimeout(() => {
+      void showExampleEvidence(selectedExample, evidenceModel, "fashion-demo:initial");
+    }, 700);
+
+    return () => window.clearTimeout(timer);
+  }, [mode, models, selectedExample, showExampleEvidence]);
+
   const clearSelection = async () => {
     if (commands.setLabelFilter) commands.setLabelFilter(null);
     setPanelError(null);
@@ -684,12 +740,12 @@ export default function FashionSearchComparisonPanel() {
       await commands.showSimilar({
         sampleId: item.queryId,
         layoutKey: model.layoutKey,
+        spaceKey: model.spaceKey,
         k: 10,
         source: `fashion-demo:${model.key}`,
-        focus: false,
+        focus: "samples",
         persist: false,
       });
-      commands.focusPanel?.(model.key === "candidate" ? "fashion-map-hyper3" : "fashion-map-clip");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       setPanelError(`Could not select target item: ${message}`);
@@ -715,12 +771,12 @@ export default function FashionSearchComparisonPanel() {
       await commands.showSimilar({
         sampleId: result.sampleId,
         layoutKey: model.layoutKey,
+        spaceKey: model.spaceKey,
         k: 10,
         source: `fashion-ranked-result:${model.key}`,
-        focus: false,
+        focus: "samples",
         persist: false,
       });
-      commands.focusPanel?.(model.key === "candidate" ? "fashion-map-hyper3" : "fashion-map-clip");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       setPanelError(`Could not select ranked result: ${message}`);

Dockerfile

@@ -42,9 +42,10 @@ COPY --chown=user . .
 
 ENV HYPERVIEW_HOST=0.0.0.0 \
     HYPERVIEW_PORT=7860 \
-    HYPERVIEW_WORKSPACE_ID=fashion-retail-search-clusters \
+    HYPERVIEW_WORKSPACE_ID=fashion-retail-search-actual-scatter \
     HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
     HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media \
+    FASHION_ENABLE_CONTEXT_MAPS=1 \
     DEEPFASHION_SAMPLES_PER_CATEGORY=10 \
     DEEPFASHION_MAX_SAMPLES=180 \
     HF_HUB_ETAG_TIMEOUT=30 \

README.md

@@ -26,7 +26,7 @@ The demo is not "another embedding map." The buyer-facing story is:
 - In the DeepFashion text-to-image probe, Hyper3-CLIP has a small aggregate edge and concrete examples where the exact item appears on the first screen while CLIP buries it.
 - The best example is a query for light denim leggings with skinny fit, zipper details, five-pocket construction, and pockets: Hyper3 ranks the exact target first; CLIP first surfaces it at rank 32.
 
-Use the ranked result strips first. Then use the compact map buttons to inspect the same target item under each embedding space. The text-search ranks are precomputed from the bounded DeepFashion probe; the maps provide visual neighborhood context for the same fashion items.
+Use the ranked result strips first. The Samples panel then shows the selected catalog item and nearest neighbors, while the smaller context maps show the same item in the actual CLIP and Hyper3-CLIP embedding layouts. The text-search ranks are precomputed from the bounded DeepFashion probe; the maps provide visual neighborhood context for the same fashion items.
 
 ## What Is In The Demo
 

demo.py

@@ -6,7 +6,6 @@ from __future__ import annotations
 import os
 import re
 import time
-import math
 from collections import Counter
 from pathlib import Path
 from typing import Any
@@ -19,7 +18,7 @@ import hyperview as hv
 SPACE_DIR = Path(__file__).resolve().parent
 SPACE_HOST = os.environ.get("HYPERVIEW_HOST", "127.0.0.1")
 SPACE_PORT = int(os.environ.get("HYPERVIEW_PORT", "6262"))
-WORKSPACE_ID = os.environ.get("HYPERVIEW_WORKSPACE_ID", "fashion-retail-search-clusters")
+WORKSPACE_ID = os.environ.get("HYPERVIEW_WORKSPACE_ID", "fashion-retail-search-actual-scatter")
 DATASET_NAME = os.environ.get("HYPERVIEW_DATASET_NAME", "deepfashion_text_search_clip_hyper3clip")
 EXTENSION_DIR = SPACE_DIR / ".hyperview" / "extensions" / "fashion-search-readout"
 
@@ -38,7 +37,7 @@ ALLOW_CANDIDATE_FALLBACK = os.environ.get("HYPERVIEW_ALLOW_CANDIDATE_FALLBACK",
     "true",
     "yes",
 }
-ENABLE_CONTEXT_MAPS = os.environ.get("FASHION_ENABLE_CONTEXT_MAPS", "").lower() in {
+ENABLE_CONTEXT_MAPS = os.environ.get("FASHION_ENABLE_CONTEXT_MAPS", "1").lower() in {
     "1",
     "true",
     "yes",
@@ -46,6 +45,7 @@ ENABLE_CONTEXT_MAPS = os.environ.get("FASHION_ENABLE_CONTEXT_MAPS", "").lower()
 EMBEDDING_MAX_ATTEMPTS = max(1, int(os.environ.get("HYPERVIEW_EMBEDDING_MAX_ATTEMPTS", "4")))
 EMBEDDING_RETRY_DELAY_SECONDS = float(os.environ.get("HYPERVIEW_EMBEDDING_RETRY_DELAY_SECONDS", "15"))
 RUNTIME_WARNINGS: list[str] = []
+DEFAULT_EXAMPLE_ID = os.environ.get("FASHION_DEFAULT_EXAMPLE_ID", "light-denim-leggings")
 
 MODEL_SPECS = [
     {
@@ -335,45 +335,12 @@ def ensure_layouts(dataset: hv.Dataset) -> dict[str, str]:
     return layouts
 
 
-def ensure_catalog_layout(dataset: hv.Dataset) -> str:
-    samples = dataset.samples
-    if not samples:
-        raise RuntimeError("DeepFashion demo has no samples to lay out.")
-
-    categories = sorted({str(sample.metadata.get("category") or sample.label or "unknown") for sample in samples})
-    category_index = {category: index for index, category in enumerate(categories)}
-    category_totals = Counter(str(sample.metadata.get("category") or sample.label or "unknown") for sample in samples)
-    category_seen: Counter[str] = Counter()
-    ids: list[str] = []
-    coords: list[list[float]] = []
-
-    for sample in samples:
-        category = str(sample.metadata.get("category") or sample.label or "unknown")
-        center_angle = (2.0 * math.pi * category_index[category]) / max(1, len(categories))
-        slot = category_seen[category]
-        category_seen[category] += 1
-
-        local_angle = (2.0 * math.pi * slot) / max(1, category_totals[category])
-        local_radius = 0.14 + 0.035 * (slot % 5)
-        center_radius = 4.0
-        coords.append(
-            [
-                center_radius * math.cos(center_angle) + local_radius * math.cos(local_angle),
-                center_radius * math.sin(center_angle) + local_radius * math.sin(local_angle),
-            ]
-        )
-        ids.append(sample.id)
-
-    return dataset.set_coords("euclidean", ids, coords)
-
-
 def build_dataset() -> tuple[hv.Dataset, dict[str, str]]:
     dataset = hv.Dataset(DATASET_NAME)
     add_deepfashion_samples(dataset)
     if ENABLE_CONTEXT_MAPS:
         layouts = ensure_layouts(dataset)
     else:
-        ensure_catalog_layout(dataset)
         layouts = {}
     return dataset, layouts
 
@@ -388,6 +355,7 @@ def model_panel_props(layouts: dict[str, str]) -> list[dict[str, Any]]:
                 "displayName": spec["display_name"],
                 "buttonLabel": spec["button_label"],
                 "layoutKey": layout_key,
+                "spaceKey": spec.get("space_key"),
             }
         )
     return props
@@ -450,6 +418,7 @@ def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
     shared_props = {
         "models": model_panel_props(layouts),
         "examples": build_examples(dataset),
+        "initialExampleId": DEFAULT_EXAMPLE_ID,
         "warnings": RUNTIME_WARNINGS,
         "metrics": {
             "typedQueryCount": 180,
@@ -475,16 +444,17 @@ def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
         title="Ranked Search Results",
         extension="fashion-search-readout",
         panel="fashion-comparison",
-        position="right",
+        position="center",
+        reference_panel_id="grid",
+        direction="left",
         props={
             **shared_props,
             "mode": "results",
             "dockview": {
                 "closeSamplesPanel": False,
                 "hideExplorerPanel": True,
-                "initialWidth": int(os.environ.get("FASHION_RESULTS_WIDTH", "780")),
+                "initialWidth": int(os.environ.get("FASHION_RESULTS_WIDTH", "760")),
                 "minimumWidth": 620,
-                "maximumWidth": int(os.environ.get("FASHION_RESULTS_MAX_WIDTH", "920")),
             },
         },
     )
@@ -494,36 +464,45 @@ def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
 
     clip_spec = MODEL_SPECS[0]
     candidate_spec = MODEL_SPECS[1]
-    context_dockview = {
-        "initialWidth": int(os.environ.get("FASHION_CONTEXT_WIDTH", "360")),
-        "minimumWidth": 260,
-        "maximumWidth": int(os.environ.get("FASHION_CONTEXT_MAX_WIDTH", "440")),
+    map_dockview = {
+        "initialHeight": int(os.environ.get("FASHION_MAP_HEIGHT", "280")),
+        "minimumHeight": 220,
     }
     clip_map = hv.ui.Scatter(
         id="fashion-map-clip",
         title="Context Map: CLIP",
         layout_key=layouts["clip"],
-        position="right",
-        reference_panel_id="fashion-ranked-results",
-        direction="within",
+        position="bottom",
+        reference_panel_id="grid",
+        direction="below",
         geometry=clip_spec["geometry"],
         layout_dimension=clip_spec["layout_dimension"],
-        props={"dockview": context_dockview},
+        props={"dockview": map_dockview},
     )
     candidate_map = hv.ui.Scatter(
         id="fashion-map-hyper3",
         title="Context Map: Hyper3",
         layout_key=layouts["candidate"],
-        position="right",
+        position="bottom",
         reference_panel_id="fashion-map-clip",
-        direction="within",
+        direction="right",
         geometry=candidate_spec["geometry"],
         layout_dimension=candidate_spec["layout_dimension"],
-        props={"dockview": context_dockview},
+        props={"dockview": map_dockview},
     )
     return hv.ui.View(results_panel, clip_map, candidate_map)
 
 
+def initial_target_sample_id() -> str | None:
+    example = next(
+        (item for item in TEXT_SEARCH_EXAMPLES if item["id"] == DEFAULT_EXAMPLE_ID),
+        TEXT_SEARCH_EXAMPLES[0] if TEXT_SEARCH_EXAMPLES else None,
+    )
+    if example is None:
+        return None
+    return safe_sample_id(example["targetItemId"])
+
+
 def launch_demo(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.Session:
     session = hv.launch(
         dataset,
@@ -537,11 +516,14 @@ def launch_demo(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.Session:
     session.ui.add_extension(EXTENSION_DIR, workspace_id=WORKSPACE_ID)
     print("Applying DeepFashion retail search demo view...", flush=True)
     session.ui.apply_view(build_demo_view(dataset, layouts), workspace_id=WORKSPACE_ID)
-    session.ui.set_active_layout(None, workspace_id=WORKSPACE_ID)
-    session.ui.set_selection([], workspace_id=WORKSPACE_ID)
+    if ENABLE_CONTEXT_MAPS and layouts:
+        session.ui.set_active_layout(layouts["clip"], workspace_id=WORKSPACE_ID)
+    sample_id = initial_target_sample_id()
+    if sample_id:
+        session.ui.set_selection([sample_id], workspace_id=WORKSPACE_ID)
     print(f"\nHyperView DeepFashion text-search demo is running at {session.url}", flush=True)
     if ENABLE_CONTEXT_MAPS:
-        print("   Samples stay visible; scatter maps are opt-in context tabs.", flush=True)
+        print("   Samples and nearest neighbors stay visible; scatter maps use the actual CLIP/Hyper3 layouts.", flush=True)
     else:
         print("   Samples stay visible; ranked text-search results are the main demo.", flush=True)
     return session