feat: add HyperView app for space

.dockerignore

@@ -0,0 +1,65 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv
+venv
+env
+.env
+*.egg-info
+dist
+build
+.eggs
+
+# Node
+node_modules
+.npm
+.pnpm-store
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# Testing
+.pytest_cache
+.coverage
+htmlcov
+.tox
+
+# Documentation (not needed in image)
+docs
+
+# Development files
+*.log
+.DS_Store
+Thumbs.db
+
+# Notebooks (not needed for deployment)
+notebooks
+*.ipynb
+
+# POC code
+poc
+
+# Local data
+*.lancedb
+data/
+
+# Frontend build output (we build fresh)
+frontend/out
+frontend/.next
+frontend/node_modules
+
+# hyper-scatter (built separately if present)
+hyper-scatter
+
+# Assets (README images)
+assets

.github/workflows/devin-review.yml

@@ -0,0 +1,23 @@
+name: Devin Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  devin-review:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Devin Review
+        run: npx devin-review ${{ github.event.pull_request.html_url }}

.github/workflows/require_frontend_export.yml

@@ -0,0 +1,53 @@
+name: Require Frontend Export
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "frontend/**"
+      - "scripts/export_frontend.sh"
+      - "src/hyperview/server/static/**"
+
+jobs:
+  require-frontend-export:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Verify static export updated when frontend changes
+        run: |
+          set -euo pipefail
+
+          base_sha="${{ github.event.pull_request.base.sha }}"
+          head_sha="${{ github.event.pull_request.head.sha }}"
+
+          changed_files="$(git diff --name-only "$base_sha" "$head_sha")"
+
+          echo "Changed files:"
+          echo "$changed_files"
+
+          frontend_changed="false"
+          static_changed="false"
+
+          if echo "$changed_files" | grep -qE '^(frontend/|scripts/export_frontend\.sh$)'; then
+            frontend_changed="true"
+          fi
+
+          if echo "$changed_files" | grep -q '^src/hyperview/server/static/'; then
+            static_changed="true"
+          fi
+
+          if [[ "$frontend_changed" == "true" && "$static_changed" != "true" ]]; then
+            echo ""
+            echo "ERROR: frontend/ changed but src/hyperview/server/static/ was not updated."
+            echo "Run: bash scripts/export_frontend.sh"
+            echo "Then commit the updated src/hyperview/server/static/ output."
+            exit 1
+          fi
+
+          echo "OK: export requirements satisfied."

.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+/uv.lock
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Jupyter Notebooks
+.ipynb_checkpoints
+
+# macOS
+.DS_Store
+
+# VS Code
+.vscode/
+
+# Generated assets
+assets/demo_animation_frames/
+*.gif
+
+# Frontend
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+
+# Bundled frontend in Python package (built with scripts/export_frontend.sh)
+# Not ignored - needed for pip install from git / sdist
+# src/hyperview/server/static/
+
+# Python package build
+dist/
+build/
+*.egg-info/
+
+# Data cache
+*.hf/
+.cache/
+
+# external repo (https://github.com/Hyper3Labs/hyper-scatter)
+hyper-scatter/
+
+# nohup
+nohup.out
+frontend/nohup.out
+
+# Local logs / tool artifacts
+.hyperview-*.log
+.hyperview-*.pid
+.playwright-mcp/
+frontend/tsconfig.tsbuildinfo
+
+# Hyperbolic model zoo (kept as a separate repo)
+hyper_model_zoo/
+hyper_models/
+scripts_ignored/
+
+# AI Context (Agent files)
+.claude/
+context/
+CLAUDE.md
+TASKS.md
+TESTS.md
+AGENTS.md
+**/AGENTS.md
+.github/agents/
+.specstory/

Dockerfile

@@ -0,0 +1,123 @@
+# =============================================================================
+# HyperView - Hugging Face Spaces Dockerfile
+# =============================================================================
+# Multi-stage build for deploying HyperView to HuggingFace Spaces.
+#
+# Features:
+# - CLIP embeddings (Euclidean) via embed-anything
+# - HyCoCLIP embeddings (Hyperbolic) via hyper-models ONNX
+# - Pre-computed demo dataset (300 CIFAR-10 samples)
+# - Torch-free runtime for minimal image size
+#
+# Deploy: https://huggingface.co/spaces/Hyper3Labs/HyperView
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Stage 1: Build Frontend (Next.js static export)
+# -----------------------------------------------------------------------------
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /app/frontend
+
+# Install dependencies first (better caching)
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci --prefer-offline
+
+# Build hyper-scatter (installed from source tarball, dist-lib not prebuilt)
+RUN cd node_modules/hyper-scatter \
+    && npm install \
+    && npm run build:lib
+
+# Copy frontend source and build
+COPY frontend/ ./
+RUN npm run build
+
+# Verify output exists
+RUN ls -la out/ && echo "Frontend build complete"
+
+# -----------------------------------------------------------------------------
+# Stage 2: Python Runtime
+# -----------------------------------------------------------------------------
+FROM python:3.11-slim AS runtime
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    git \
+    libssl-dev \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+# HuggingFace Spaces requirement: create user with UID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to user
+USER user
+
+# Set environment variables
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR $HOME/app
+
+# Upgrade pip
+RUN pip install --upgrade pip
+
+# Copy Python package files
+COPY --chown=user pyproject.toml README.md LICENSE ./
+COPY --chown=user src/ ./src/
+COPY --chown=user scripts/ ./scripts/
+
+# Install Python package (without ML extras - we use ONNX)
+RUN pip install -e .
+
+# Copy built frontend to static directory
+COPY --from=frontend-builder --chown=user /app/frontend/out ./src/hyperview/server/static/
+
+# Verify frontend is in place
+RUN ls -la src/hyperview/server/static/ && echo "Frontend copied successfully"
+
+# -----------------------------------------------------------------------------
+# Stage 3: Pre-compute Demo Dataset
+# -----------------------------------------------------------------------------
+# Create output directories
+RUN mkdir -p $HOME/app/demo_data/datasets $HOME/app/demo_data/media
+
+# Set environment for precomputation
+ENV HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
+    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media \
+    DEMO_SAMPLES=300
+
+# Pre-download HuggingFace models and compute embeddings
+# This runs during build to ensure fast startup
+RUN python scripts/precompute_hf_demo.py
+
+# Verify dataset was created
+RUN ls -la demo_data/ && echo "Demo dataset pre-computed successfully"
+
+# -----------------------------------------------------------------------------
+# Final Configuration
+# -----------------------------------------------------------------------------
+# Copy entrypoint
+COPY --chown=user app_hf.py ./
+
+# Set runtime environment
+ENV HOST=0.0.0.0 \
+    PORT=7860 \
+    DEMO_DATASET=cifar10_hf_demo \
+    HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
+    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media
+
+# Expose port (HuggingFace Spaces default)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/__hyperview__/health || exit 1
+
+# Start server
+CMD ["python", "app_hf.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matin Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,155 @@
 ---
 title: HyperView
-emoji: 😻
-colorFrom: blue
-colorTo: indigo
+emoji: 🔮
+colorFrom: purple
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
-license: apache-2.0
-short_description: 'dataset curation + embedding visualization '
+tags:
+  - data-visualization
+  - embeddings
+  - hyperbolic
+  - poincare
+  - clip
+  - dataset-curation
+  - computer-vision
+  - umap
+short_description: Dataset visualization with Euclidean & hyperbolic embeddings
+models:
+  - openai/clip-vit-base-patch32
+  - mnm-matin/hyperbolic-clip
+datasets:
+  - uoft-cs/cifar10
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HyperView
+
+> **Open-source dataset curation + embedding visualization (Euclidean + Poincaré disk)**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Hyper3Labs/HyperView) [![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Hyper3Labs/HyperView)
+
+<p align="center">
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">
+    <img src="https://raw.githubusercontent.com/Hyper3Labs/HyperView/main/assets/screenshot.png" alt="HyperView Screenshot" width="100%">
+  </a>
+  <br>
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">Watch the Demo Video</a>
+</p>
+
+---
+
+## Try it Online
+
+**[Launch HyperView on Hugging Face Spaces](https://huggingface.co/spaces/Hyper3Labs/HyperView)** - no installation required!
+
+The demo showcases:
+- 300 CIFAR-10 images with pre-computed embeddings
+- CLIP embeddings visualized in Euclidean space (UMAP)
+- HyCoCLIP embeddings visualized on the Poincaré disk
+
+---
+
+## Features
+
+- **Dual-Panel UI**: Image grid + scatter plot with bidirectional selection
+- **Euclidean/Poincaré Toggle**: Switch between standard 2D UMAP and Poincaré disk visualization
+- **HuggingFace Integration**: Load datasets directly from HuggingFace Hub
+- **Fast Embeddings**: Uses EmbedAnything for CLIP-based image embeddings
+
+## Quick Start
+
+**Docs:** [docs/datasets.md](docs/datasets.md) · [docs/colab.md](docs/colab.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [TESTS.md](TESTS.md)
+
+### Installation
+
+```bash
+git clone https://github.com/Hyper3Labs/HyperView.git
+cd HyperView
+
+# Install with uv
+uv venv .venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+### Run the Demo
+
+```bash
+hyperview demo --samples 500
+```
+
+This will:
+1. Load 500 samples from CIFAR-100
+2. Compute CLIP embeddings
+3. Generate Euclidean and Poincaré visualizations
+4. Start the server at **http://127.0.0.1:6262**
+
+### Python API
+
+```python
+import hyperview as hv
+
+# Create dataset
+dataset = hv.Dataset("my_dataset")
+
+# Load from HuggingFace
+dataset.add_from_huggingface(
+    "uoft-cs/cifar100",
+    split="train",
+    max_samples=1000
+)
+
+# Or load from local directory
+# dataset.add_images_dir("/path/to/images", label_from_folder=True)
+
+# Compute embeddings and visualization
+dataset.compute_embeddings()
+dataset.compute_visualization()
+
+# Launch the UI
+hv.launch(dataset)  # Opens http://127.0.0.1:6262
+```
+
+### Google Colab
+
+See [docs/colab.md](docs/colab.md) for a fast Colab smoke test and notebook-friendly launch behavior.
+
+### Save and Load Datasets
+
+```python
+# Save dataset with embeddings
+dataset.save("my_dataset.json")
+
+# Load later
+dataset = hv.Dataset.load("my_dataset.json")
+hv.launch(dataset)
+```
+
+## Why Hyperbolic?
+
+Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **Representation Collapse** where minority classes get crushed together.
+
+**Hyperbolic space** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Hyper3Labs/HyperView/main/assets/hyperview_infographic.png" alt="Euclidean vs Hyperbolic" width="100%">
+</p>
+
+## Contributing
+
+Development setup, frontend hot-reload, and backend API notes live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Related projects
+
+- **hyper-scatter**: High-performance WebGL scatterplot engine (Euclidean + Poincaré) used by the frontend: https://github.com/Hyper3Labs/hyper-scatter
+- **hyper-models**: Non-Euclidean model zoo + ONNX exports (e.g. for hyperbolic VLM experiments): https://github.com/Hyper3Labs/hyper-models
+
+## References
+
+- [Poincaré Embeddings for Learning Hierarchical Representations](https://arxiv.org/abs/1705.08039) (Nickel & Kiela, 2017)
+- [Hyperbolic Neural Networks](https://arxiv.org/abs/1805.09112) (Ganea et al., 2018)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

app_hf.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+"""Hugging Face Spaces entrypoint for HyperView.
+
+This script serves a pre-computed demo dataset stored in LanceDB.
+The dataset is computed at Docker build time by scripts/precompute_hf_demo.py.
+
+For HuggingFace Spaces deployment under Hyper3Labs/HyperView.
+"""
+
+import os
+
+# Configuration from environment
+HOST = os.environ.get("HOST", "0.0.0.0")
+PORT = int(os.environ.get("PORT", 7860))
+DATASET_NAME = os.environ.get("DEMO_DATASET", "cifar10_hf_demo")
+
+
+def main() -> None:
+    """Load pre-computed dataset and launch server."""
+    import hyperview as hv
+
+    dataset = hv.Dataset(DATASET_NAME)
+
+    spaces = dataset.list_spaces()
+    layouts = dataset.list_layouts()
+
+    if not spaces or not layouts:
+        print("Pre-computed embeddings not found in storage.")
+        print("Falling back to computing on startup (this will be slow)...")
+
+        from scripts.precompute_hf_demo import create_demo_dataset
+
+        dataset = create_demo_dataset()
+    else:
+        print(f"Loaded dataset '{DATASET_NAME}' with pre-computed embeddings")
+
+    print(f"\nStarting HyperView server on {HOST}:{PORT}")
+    print("=" * 50)
+
+    hv.launch(
+        dataset,
+        host=HOST,
+        port=PORT,
+        open_browser=False,
+    )
+
+
+if __name__ == "__main__":
+    main()

docs/architecture.md

@@ -0,0 +1,54 @@
+# HyperView System Architecture
+
+## The Integrated Pipeline Approach
+
+HyperView is built as a three-stage pipeline that turns raw multimodal data into an interactive, fairness-aware view of a dataset. Each stage uses the tool best suited for the job:
+
+*   **Ingestion – Python (PyTorch/Geoopt):** Differentiable manifold operations and training of the Hyperbolic Adapter.
+*   **Storage & Retrieval – Rust (Qdrant):** Low-latency vector search with a custom Poincaré distance metric.
+*   **Visualization – Browser (WebGL/Deck.gl):** GPU-accelerated rendering of the Poincaré disk in the browser.
+
+## System Diagram
+
+<p align="center">
+  <img src="../assets/hyperview_architecture.png" alt="HyperView System Architecture: The Integrated Pipeline Approach" width="100%">
+</p>
+
+## Component Breakdown
+
+### 1. Ingestion: Hyperbolic Adapter (Python)
+*   **Role:** The bridge between flat (Euclidean) model embeddings and curved (hyperbolic) space.
+*   **Input:** Raw data (images/text) → standard model embeddings (e.g. CLIP/ResNet vectors).
+*   **Tech:** PyTorch, Geoopt.
+*   **Function:**
+    * Learns a small Hyperbolic Adapter using differentiable manifold operations.
+    * Uses the exponential map (`expmap0`) to project Euclidean vectors into the Poincaré ball.
+    * This is where minority and rare cases are expanded away from the crowded center so they remain distinguishable.
+
+### 2. Storage & Retrieval: Vector Engine (Rust / Qdrant)
+*   **Role:** The memory that stores and retrieves hyperbolic embeddings at scale.
+*   **Tech:** Qdrant (forked/extended in Rust).
+*   **Challenge:** Standard vector DBs only support dot, cosine, or Euclidean distance.
+*   **Solution:**
+    * Implement a custom `PoincareDistance` metric in Rust:
+      $$d(u, v) = \text{arccosh}\left(1 + 2 \frac{\lVert u - v\rVert^2}{(1 - \lVert u\rVert^2)(1 - \lVert v\rVert^2)}\right)$$
+    * Plug this metric into Qdrant’s HNSW index for fast nearest-neighbor search in hyperbolic space.
+    * This allows search results to respect the hierarchy in the data instead of collapsing the long tail.
+
+### 3. Visualization: Poincaré Disk Viewer (WebGL)
+*   **Role:** The lens that lets humans explore the structure of the dataset.
+*   **Tech:** React, Deck.gl, custom WebGL shaders.
+*   **Challenge:** Rendering 1M points in non-Euclidean geometry directly in the browser.
+*   **Solution:**
+    * Send raw hyperbolic coordinates to the GPU and render them directly onto the Poincaré disk using a custom shader (no CPU-side projection).
+    * Provide pan/zoom/selection so curators can inspect minority clusters, isolate rare subgroups at the boundary, and export curated subsets.
+
+## Data Flow: The Fairness Pipeline
+
+1.  **Ingest:** User uploads a dataset (e.g. medical images, biodiversity data).
+2.  **Embed:** Standard models (CLIP/ResNet/Whisper) produce Euclidean embeddings.
+3.  **Expand:** The Hyperbolic Adapter projects them into the Poincaré ball; rare cases move towards the boundary instead of being crushed.
+4.  **Index:** Qdrant stores these hyperbolic vectors with the custom Poincaré distance metric.
+5.  **Query:** A user clicks on a minority example or defines a region of interest.
+6.  **Search:** Qdrant returns semantic neighbors according to Poincaré distance, preserving the hierarchy between majority, minority, and rare subgroups.
+7.  **Visualize & Curate:** The browser renders the Poincaré disk, highlighting clusters and long-tail regions so users can see gaps, remove duplicates, and build fairer training sets.

docs/colab.md

@@ -0,0 +1,37 @@
+# Running HyperView in Google Colab
+
+HyperView works natively in Google Colab. Because Colab runs on a remote VM, you cannot access `localhost` directly. HyperView handles this automatically.
+
+## Usage
+
+### 1. Install HyperView
+
+```bash
+!pip install -q git+https://github.com/Hyper3Labs/HyperView.git
+```
+
+### 2. Launch the visualizer
+
+When you run `hv.launch()`, a button labeled **“Open HyperView in a new tab”** will appear in the output. Click it to open the visualization.
+
+```python
+# Minimal example
+import numpy as np
+import hyperview as hv
+from hyperview.core.sample import SampleFromArray
+
+dataset = hv.Dataset("colab_smoke", persist=False)
+
+rng = np.random.default_rng(0)
+for i in range(200):
+    img = (rng.random((64, 64, 3)) * 255).astype(np.uint8)
+    sample = SampleFromArray.from_array(id=f"s{i}", image_array=img, label="demo")
+    sample.embedding_2d = [float(rng.normal()), float(rng.normal())] # Dummy 2D points
+    dataset.add_sample(sample)
+
+hv.launch(dataset)
+```
+
+## Technical Details
+
+To support Colab, HyperView uses `google.colab.kernel.proxyPort` to expose the backend server. The UI is opened via a specially constructed "launcher" page that embeds the proxied application in a full-page iframe. This workaround ensures compatibility with modern browser security policies (like third-party cookie blocking) that often break direct proxy URLs.

docs/datasets.md

@@ -0,0 +1,96 @@
+# Datasets
+
+## Creating a Dataset
+
+```python
+import hyperview as hv
+
+# Persistent dataset (default) - survives restarts
+dataset = hv.Dataset("my_dataset")
+
+# In-memory dataset - lost when process exits
+dataset = hv.Dataset("my_dataset", persist=False)
+```
+
+**Storage location:** `~/.hyperview/datasets/` (configurable via `HYPERVIEW_DATABASE_DIR`)
+
+Internally, each dataset is stored as two Lance tables (directories) inside that folder:
+- `hyperview_{dataset_name}.lance/` (samples)
+- `hyperview_{dataset_name}_meta.lance/` (metadata like label colors)
+
+## Adding Samples
+
+### From HuggingFace
+```python
+dataset.add_from_huggingface(
+    "uoft-cs/cifar100",
+    split="train",
+    image_key="img",
+    label_key="fine_label",
+    max_samples=1000,
+)
+```
+
+### From Directory
+```python
+dataset.add_images_dir("/path/to/images", label_from_folder=True)
+```
+
+## Persistence Model: Additive
+
+HyperView uses an **additive** persistence model:
+
+| Action | Behavior |
+|--------|----------|
+| Add samples | New samples inserted, existing skipped by ID |
+| Request fewer than exist | Existing samples preserved (no deletion) |
+| Request more than exist | Only new samples added |
+| Embeddings | Cached per-sample, reused across sessions |
+| Projections | Recomputed when new samples added (UMAP requires refit) |
+
+**Example:**
+```python
+dataset = hv.Dataset("my_dataset")
+
+dataset.add_from_huggingface(..., max_samples=200)  # 200 samples
+dataset.add_from_huggingface(..., max_samples=400)  # +200 new → 400 total
+dataset.add_from_huggingface(..., max_samples=300)  # no change → 400 total
+dataset.add_from_huggingface(..., max_samples=500)  # +100 new → 500 total
+```
+
+Samples are **never implicitly deleted**. Use `hv.Dataset.delete("name")` for explicit removal.
+
+## Computing Embeddings
+
+```python
+# High-dimensional embeddings (CLIP/ResNet)
+dataset.compute_embeddings(model="clip", show_progress=True)
+
+# 2D projections for visualization
+dataset.compute_visualization()  # UMAP to Euclidean + Hyperbolic
+```
+
+Embeddings are stored per-sample. If a sample already has embeddings, it's skipped.
+
+## Listing & Deleting Datasets
+
+```python
+# List all persistent datasets
+hv.Dataset.list_datasets()  # ['cifar100_demo', 'my_dataset', ...]
+
+# Delete a dataset
+hv.Dataset.delete("my_dataset")
+
+# Check existence
+hv.Dataset.exists("my_dataset")  # True/False
+```
+
+## Dataset Info
+
+```python
+len(dataset)           # Number of samples
+dataset.name           # Dataset name
+dataset.labels         # Unique labels
+dataset.samples        # Iterator over all samples
+dataset[sample_id]     # Get sample by ID
+```

docs/index.html

@@ -0,0 +1,465 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>HyperView: Interactive Poincaré Disk</title>
+    <style>
+        body {
+            margin: 0;
+            overflow: hidden;
+            background-color: #f0f2f5;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            height: 100vh;
+        }
+        canvas {
+            box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+            border-radius: 50%;
+            background: white;
+            cursor: grab;
+        }
+        canvas:active {
+            cursor: grabbing;
+        }
+        .controls {
+            position: absolute;
+            top: 20px;
+            left: 20px;
+            background: rgba(255, 255, 255, 0.9);
+            padding: 15px;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+            max-width: 300px;
+            z-index: 100;
+        }
+        h1 { margin: 0 0 10px 0; font-size: 18px; color: #333; }
+        p { margin: 0 0 10px 0; font-size: 14px; color: #666; line-height: 1.4; }
+        .legend { display: flex; gap: 10px; font-size: 12px; margin-top: 10px; }
+        .dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; margin-right: 5px; }
+        
+        .mode-btn {
+            margin-top: 15px;
+            padding: 8px 16px;
+            background: #333;
+            color: white;
+            border: none;
+            border-radius: 4px;
+            cursor: pointer;
+            font-weight: bold;
+            width: 100%;
+            transition: background 0.3s;
+        }
+        .mode-btn:hover { background: #555; }
+        .mode-btn.active { background: #d93025; } /* Red for danger/collapse */
+        
+        .status-box {
+            margin-top: 10px;
+            padding: 10px;
+            background: #f8f9fa;
+            border-left: 4px solid #ccc;
+            font-size: 13px;
+            transition: all 0.3s;
+        }
+        .status-box.collapse {
+            border-left-color: #d93025;
+            background: #fce8e6;
+            color: #a50e0e;
+        }
+        .status-box.expand {
+            border-left-color: #188038;
+            background: #e6f4ea;
+            color: #137333;
+        }
+
+        /* About Overlay Styles */
+        .about-btn {
+            position: absolute;
+            top: 20px;
+            right: 20px;
+            background: #fff;
+            border: 1px solid #ccc;
+            border-radius: 50%;
+            width: 40px;
+            height: 40px;
+            font-size: 20px;
+            cursor: pointer;
+            box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            color: #555;
+            transition: all 0.2s;
+            z-index: 100;
+        }
+        .about-btn:hover { background: #f0f0f0; color: #333; }
+
+        .overlay-backdrop {
+            position: fixed;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            background: rgba(0,0,0,0.5);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            z-index: 1000;
+            opacity: 0;
+            visibility: hidden;
+            transition: opacity 0.3s, visibility 0.3s;
+        }
+        .overlay-backdrop.visible {
+            opacity: 1;
+            visibility: visible;
+        }
+        .overlay-content {
+            background: white;
+            padding: 30px;
+            border-radius: 12px;
+            max-width: 600px;
+            width: 90%;
+            max-height: 80vh;
+            overflow-y: auto;
+            box-shadow: 0 10px 25px rgba(0,0,0,0.2);
+            position: relative;
+        }
+        .close-btn {
+            position: absolute;
+            top: 15px;
+            right: 15px;
+            background: none;
+            border: none;
+            font-size: 24px;
+            cursor: pointer;
+            color: #999;
+        }
+        .close-btn:hover { color: #333; }
+        
+        .overlay-content h2 { margin-top: 0; color: #333; }
+        .overlay-content h3 { color: #444; margin-top: 20px; margin-bottom: 10px; font-size: 16px; }
+        .overlay-content p { font-size: 15px; line-height: 1.6; color: #555; margin-bottom: 15px; }
+        
+        .faq-item {
+            background: #f9f9f9;
+            padding: 15px;
+            border-radius: 8px;
+            margin-bottom: 15px;
+            border-left: 4px solid #0066cc;
+        }
+        .faq-item h4 { margin: 0 0 8px 0; color: #0066cc; font-size: 15px; }
+        .faq-item p { margin: 0; font-size: 14px; }
+    </style>
+</head>
+<body>
+    <button id="aboutBtn" class="about-btn" title="About HyperView">?</button>
+
+    <div id="aboutOverlay" class="overlay-backdrop">
+        <div class="overlay-content">
+            <button id="closeOverlay" class="close-btn">&times;</button>
+            <h2>Why HyperView?</h2>
+            <p>
+                Modern AI curation tools rely on <strong>Euclidean geometry</strong> (flat space). 
+                But real-world data—like biological taxonomies, social hierarchies, and medical diagnoses—is 
+                complex and hierarchical.
+            </p>
+            <p>
+                When you force this complex data into a flat box, you run out of room. 
+                To fit the "Majority," the math crushes the "Minority" and "Rare" cases together. 
+                We call this <strong>Representation Collapse</strong>.
+            </p>
+
+            <h3>The Solution: Hyperbolic Space</h3>
+            <p>
+                HyperView uses the <strong>Poincaré disk</strong>, a model of hyperbolic geometry where space expands exponentially towards the edge. 
+                This gives "infinite" room for outliers, ensuring they remain distinct and visible.
+            </p>
+
+            <h3>FAQ: Why does this matter?</h3>
+            
+            <div class="faq-item">
+                <h4>The "Hidden Diagnosis" Problem</h4>
+                <p>
+                    Imagine training an AI doctor on 10,000 chest X-rays:
+                    <br>• <strong>9,000 Healthy</strong> (Majority)
+                    <br>• <strong>900 Common Pneumonia</strong> (Minority)
+                    <br>• <strong>100 Rare Early-Stage Tuberculosis</strong> (Rare Subgroup)
+                </p>
+                <p style="margin-top: 10px;">
+                    <strong>In Euclidean Space:</strong> The model runs out of room. It crushes the 100 Tuberculosis cases into the Pneumonia cluster. To the AI, they look like noise. The patient is misdiagnosed.
+                </p>
+                <p style="margin-top: 10px;">
+                    <strong>In HyperView:</strong> The Tuberculosis cases are pushed to the edge. They form a distinct, visible island. You can see them, select them, and ensure the AI learns to save those patients.
+                </p>
+            </div>
+        </div>
+    </div>
+
+    <div class="controls">
+        <h1>HyperView Interactive Demo</h1>
+        <p>
+            <strong>Drag to Pan.</strong> Experience the "infinite" space. 
+            Notice how the red "Rare" points expand and separate as you bring them towards the center.
+        </p>
+        <div class="legend">
+            <div><span class="dot" style="background: #ccc;"></span>Majority</div>
+            <div><span class="dot" style="background: #0066cc;"></span>Minority</div>
+            <div><span class="dot" style="background: #ff0000;"></span>Rare</div>
+        </div>
+        
+        <div id="statusBox" class="status-box expand">
+            <strong>Hyperbolic Mode:</strong><br>
+            Space expands exponentially.<br>
+            Rare items are distinct.
+        </div>
+        <button id="toggleBtn" class="mode-btn">Simulate Euclidean Collapse</button>
+    </div>
+    <canvas id="poincareCanvas"></canvas>
+
+    <script>
+        const canvas = document.getElementById('poincareCanvas');
+        const ctx = canvas.getContext('2d');
+        const toggleBtn = document.getElementById('toggleBtn');
+        const statusBox = document.getElementById('statusBox');
+        
+        // Configuration
+        const RADIUS = 300;
+        const WIDTH = RADIUS * 2;
+        const HEIGHT = RADIUS * 2;
+        
+        canvas.width = WIDTH;
+        canvas.height = HEIGHT;
+
+        // Complex Number Utilities
+        class Complex {
+            constructor(re, im) { this.re = re; this.im = im; }
+            
+            add(other) { return new Complex(this.re + other.re, this.im + other.im); }
+            sub(other) { return new Complex(this.re - other.re, this.im - other.im); }
+            mul(other) { 
+                return new Complex(
+                    this.re * other.re - this.im * other.im,
+                    this.re * other.im + this.im * other.re
+                );
+            }
+            div(other) {
+                const denom = other.re * other.re + other.im * other.im;
+                return new Complex(
+                    (this.re * other.re + this.im * other.im) / denom,
+                    (this.im * other.re - this.re * other.im) / denom
+                );
+            }
+            conj() { return new Complex(this.re, -this.im); }
+            modSq() { return this.re * this.re + this.im * this.im; }
+        }
+
+        // Mobius Transformation: (z + a) / (1 + conj(a)z)
+        function mobiusAdd(z, a) {
+            const num = z.add(a);
+            const den = new Complex(1, 0).add(a.conj().mul(z));
+            return num.div(den);
+        }
+
+        // Data Generation (Hierarchy)
+        const points = [];
+        
+        function addCluster(count, r_hyp, r_euc, theta_center, spread_hyp, spread_euc, type) {
+            for (let i = 0; i < count; i++) {
+                // Hyperbolic Position
+                const rh_noise = (Math.random() - 0.5) * spread_hyp;
+                const th_noise = (Math.random() - 0.5) * spread_hyp;
+                const rh = Math.min(0.99, Math.max(0, r_hyp + rh_noise));
+                const th = theta_center + th_noise;
+                
+                // Euclidean Position (Crushed)
+                const re_noise = (Math.random() - 0.5) * spread_euc; 
+                const re = Math.min(0.99, Math.max(0, r_euc + re_noise));
+                
+                const hypZ = new Complex(rh * Math.cos(th), rh * Math.sin(th));
+                const eucZ = new Complex(re * Math.cos(th), re * Math.sin(th));
+
+                points.push({
+                    hypZ: hypZ,
+                    eucZ: eucZ,
+                    currentZ: hypZ, // Start in Hyperbolic
+                    type: type
+                });
+            }
+        }
+
+        // 1. Majority (Center)
+        addCluster(300, 0.1, 0.1, 0, 0.5, 0.2, 'majority');
+        
+        // 2. Minority (Edge) - r=0.85 (Hyp) vs r=0.5 (Euc)
+        addCluster(50, 0.85, 0.5, Math.PI/4, 0.2, 0.1, 'minority');
+        
+        // 3. Rare (Deep Edge) - r=0.95 (Hyp) vs r=0.52 (Euc - Overlapping Minority)
+        addCluster(10, 0.95, 0.52, Math.PI/4, 0.05, 0.02, 'rare');
+
+        // View State
+        let isEuclidean = false;
+        let animationProgress = 0; // 0 = Hyperbolic, 1 = Euclidean
+        let viewOffset = new Complex(0, 0);
+        let isDragging = false;
+        let lastMouse = null;
+
+        function screenToComplex(x, y) {
+            const rect = canvas.getBoundingClientRect();
+            const cx = x - rect.left - RADIUS;
+            const cy = y - rect.top - RADIUS;
+            return new Complex(cx / RADIUS, cy / RADIUS);
+        }
+
+        function lerpComplex(a, b, t) {
+            return new Complex(
+                a.re + (b.re - a.re) * t,
+                a.im + (b.im - a.im) * t
+            );
+        }
+
+
+        function update() {
+            // Animate transition
+            const target = isEuclidean ? 1 : 0;
+            const speed = 0.05;
+            
+            if (Math.abs(animationProgress - target) > 0.001) {
+                animationProgress += (target - animationProgress) * speed;
+            } else {
+                animationProgress = target;
+            }
+
+            // Update point positions
+            points.forEach(p => {
+                // Interpolate between base positions
+                let basePos = lerpComplex(p.hypZ, p.eucZ, animationProgress);
+                
+                // Apply View Transformation
+                // As we move to Euclidean, we want to reset the view to center (0,0)
+                // effectively disabling the "infinite scroll"
+                const effectiveViewOffset = new Complex(
+                    viewOffset.re * (1 - animationProgress),
+                    viewOffset.im * (1 - animationProgress)
+                );
+                
+                p.currentZ = mobiusAdd(basePos, effectiveViewOffset);
+            });
+            
+            draw();
+            requestAnimationFrame(update);
+        }
+
+        function draw() {
+            ctx.clearRect(0, 0, WIDTH, HEIGHT);
+            
+            // Draw Disk Boundary
+            ctx.beginPath();
+            ctx.arc(RADIUS, RADIUS, RADIUS - 1, 0, Math.PI * 2);
+            ctx.strokeStyle = '#333';
+            ctx.lineWidth = 2;
+            ctx.stroke();
+            ctx.fillStyle = '#fff';
+            ctx.fill();
+
+            // Draw Grid (Geodesics)
+            ctx.strokeStyle = '#eee';
+            ctx.lineWidth = 1;
+            // Fade out grid in Euclidean mode
+            ctx.globalAlpha = 1 - animationProgress; 
+            for(let r=0.2; r<1.0; r+=0.2) {
+                ctx.beginPath();
+                ctx.arc(RADIUS, RADIUS, r * RADIUS, 0, Math.PI * 2);
+                ctx.stroke();
+            }
+            ctx.globalAlpha = 1.0;
+
+            // Draw Points
+            points.forEach(p => {
+                const px = p.currentZ.re * RADIUS + RADIUS;
+                const py = p.currentZ.im * RADIUS + RADIUS;
+                
+                ctx.beginPath();
+                ctx.arc(px, py, p.type === 'rare' ? 5 : 3, 0, Math.PI * 2);
+                
+                if (p.type === 'majority') ctx.fillStyle = 'rgba(150, 150, 150, 0.5)';
+                if (p.type === 'minority') ctx.fillStyle = 'rgba(0, 102, 204, 0.8)';
+                if (p.type === 'rare') ctx.fillStyle = 'rgba(255, 0, 0, 1.0)';
+                
+                ctx.fill();
+            });
+        }
+
+        // Interaction
+        canvas.addEventListener('mousedown', e => {
+            if (isEuclidean) return; // Disable drag in Euclidean mode
+            isDragging = true;
+            lastMouse = screenToComplex(e.clientX, e.clientY);
+            canvas.style.cursor = 'grabbing';
+        });
+
+        window.addEventListener('mouseup', () => {
+            isDragging = false;
+            canvas.style.cursor = isEuclidean ? 'not-allowed' : 'grab';
+        });
+
+        canvas.addEventListener('mousemove', e => {
+            if (!isDragging) return;
+            
+            const currentMouse = screenToComplex(e.clientX, e.clientY);
+            const delta = currentMouse.sub(lastMouse);
+            const move = new Complex(delta.re, delta.im); 
+            
+            viewOffset = mobiusAdd(viewOffset, move);
+            lastMouse = currentMouse;
+        });
+
+        // Toggle Logic
+        toggleBtn.addEventListener('click', () => {
+            isEuclidean = !isEuclidean;
+            
+            if (isEuclidean) {
+                toggleBtn.textContent = "Switch to Hyperbolic Mode";
+                toggleBtn.classList.add('active');
+                statusBox.innerHTML = "<strong>Euclidean Collapse:</strong><br>Rare items are crushed.<br>Indistinguishable from Minority.";
+                statusBox.className = "status-box collapse";
+                canvas.style.cursor = 'not-allowed';
+            } else {
+                toggleBtn.textContent = "Simulate Euclidean Collapse";
+                toggleBtn.classList.remove('active');
+                statusBox.innerHTML = "<strong>Hyperbolic Mode:</strong><br>Space expands exponentially.<br>Rare items are distinct.";
+                statusBox.className = "status-box expand";
+                canvas.style.cursor = 'grab';
+            }
+        });
+
+        // About Overlay Logic
+        const aboutBtn = document.getElementById('aboutBtn');
+        const aboutOverlay = document.getElementById('aboutOverlay');
+        const closeOverlay = document.getElementById('closeOverlay');
+
+        function openAbout() {
+            aboutOverlay.classList.add('visible');
+        }
+
+        function closeAbout() {
+            aboutOverlay.classList.remove('visible');
+        }
+
+        aboutBtn.addEventListener('click', openAbout);
+        closeOverlay.addEventListener('click', closeAbout);
+        
+        // Close on click outside
+        aboutOverlay.addEventListener('click', (e) => {
+            if (e.target === aboutOverlay) {
+                closeAbout();
+            }
+        });
+
+        // Start Loop
+        update();
+    </script>
+</body>
+</html>

frontend/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

frontend/eslint.config.mjs

@@ -0,0 +1,22 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Bridge legacy shareable configs (like `next/core-web-vitals`) into ESLint v9 flat config.
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const config = [
+  {
+    // Mirror Next.js defaults: never lint build artifacts.
+    ignores: ["**/.next/**", "**/out/**", "**/node_modules/**"],
+  },
+  ...compat.extends("next/core-web-vitals"),
+];
+
+export default config;

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

frontend/next.config.ts

@@ -0,0 +1,24 @@
+import type { NextConfig } from "next";
+import path from "path";
+
+const nextConfig: NextConfig = {
+  output: "export",
+  trailingSlash: true,
+  // Needed for Turbopack to resolve local linked/file dependencies in a monorepo.
+  outputFileTracingRoot: path.join(__dirname, ".."),
+  transpilePackages: ["hyper-scatter"],
+  images: {
+    unoptimized: true,
+  },
+  // Proxy API calls to backend during development
+  async rewrites() {
+    return [
+      {
+        source: "/api/:path*",
+        destination: "http://127.0.0.1:6262/api/:path*",
+      },
+    ];
+  },
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "hyperview-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "export": "next build && cp -r out/* ../src/hyperview/server/static/"
+  },
+  "dependencies": {
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-toggle": "^1.1.10",
+    "@radix-ui/react-toggle-group": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@tanstack/react-virtual": "^3.10.9",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "dockview": "^4.13.1",
+    "hyper-scatter": "https://github.com/Hyper3Labs/hyper-scatter/archive/14421d24ccf128392444175a23e74627c120905c.tar.gz",
+    "justified-layout": "^4.1.0",
+    "lucide-react": "^0.562.0",
+    "next": "^16.0.7",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss-animate": "^1.0.7",
+    "zustand": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/justified-layout": "^4.1.4",
+    "@types/node": "^22.9.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^9.14.0",
+    "eslint-config-next": "15.0.3",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
+    "typescript": "^5.6.3"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,9 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+
+export default config;

frontend/src/app/globals.css

@@ -0,0 +1,224 @@
+@import "dockview/dist/styles/dockview.css";
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  html,
+  body {
+    height: 100%;
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+  }
+
+  :root {
+    /* Rerun-inspired dark theme as default (dark-first) */
+    --background: 215 28% 7%;       /* #0d1117 */
+    --foreground: 213 27% 92%;      /* #e6edf3 */
+    
+    --card: 215 21% 11%;            /* #161b22 */
+    --card-foreground: 213 27% 92%;
+    
+    --popover: 215 21% 11%;
+    --popover-foreground: 213 27% 92%;
+    
+    --primary: 212 100% 67%;        /* #58a6ff */
+    --primary-foreground: 215 28% 7%;
+    
+    --secondary: 215 14% 17%;       /* #21262d */
+    --secondary-foreground: 213 27% 92%;
+    
+    --muted: 215 14% 17%;
+    --muted-foreground: 213 12% 58%;  /* #8b949e */
+    
+    --accent: 215 14% 17%;
+    --accent-foreground: 213 27% 92%;
+    
+    --destructive: 0 62% 50%;
+    --destructive-foreground: 0 0% 98%;
+    
+    --border: 215 14% 22%;          /* #30363d */
+    --input: 215 14% 22%;
+    --ring: 212 100% 67%;
+    
+    --radius: 0.375rem;
+    
+    /* Custom Rerun-specific tokens */
+    --surface: 215 21% 11%;         /* #161b22 */
+    --surface-light: 215 14% 17%;   /* #21262d */
+    --surface-elevated: 215 14% 22%; /* #30363d */
+    --border-subtle: 215 14% 17%;
+    --text: 213 27% 92%;            /* #e6edf3 */
+    --text-muted: 213 12% 58%;      /* #8b949e */
+    --text-subtle: 215 10% 46%;     /* #6e7681 */
+    --accent-cyan: 176 60% 53%;     /* #39d3cc */
+    --accent-orange: 27 86% 59%;    /* #f0883e */
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-size: 12px;
+    line-height: 16px;
+    letter-spacing: -0.15px;
+    font-weight: 500;
+    font-feature-settings: "liga" 1, "calt" 1;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}
+
+/* Custom scrollbar - Rerun style: 6px bar, 2px inner margin, 2px outer margin */
+::-webkit-scrollbar {
+  width: 10px;  /* 6px bar + 2px inner margin on each side */
+  height: 10px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: hsl(var(--muted-foreground) / 0.2);
+  border-radius: 3px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: hsl(var(--muted-foreground) / 0.35);
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+
+/* Firefox scrollbar */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: hsl(var(--muted-foreground) / 0.25) transparent;
+}
+
+/* Hide scrollbar for some elements */
+.hide-scrollbar::-webkit-scrollbar {
+  display: none;
+}
+
+.hide-scrollbar {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+/* Scroll containers inside panels should keep scrollbars inset */
+.panel-scroll {
+  scrollbar-gutter: stable;
+}
+
+/* Dockview theme overrides (match HyperView tokens) */
+.hyperview-dockview {
+  --dv-background-color: hsl(var(--background));
+  --dv-group-view-background-color: hsl(var(--card));
+  --dv-tabs-and-actions-container-background-color: hsl(var(--secondary));
+  --dv-activegroup-visiblepanel-tab-background-color: hsl(var(--card));
+  --dv-activegroup-hiddenpanel-tab-background-color: hsl(var(--secondary));
+  --dv-inactivegroup-visiblepanel-tab-background-color: hsl(var(--secondary));
+  --dv-inactivegroup-hiddenpanel-tab-background-color: hsl(var(--secondary));
+  --dv-activegroup-visiblepanel-tab-color: hsl(var(--foreground));
+  --dv-activegroup-hiddenpanel-tab-color: hsl(var(--muted-foreground));
+  --dv-inactivegroup-visiblepanel-tab-color: hsl(var(--muted-foreground));
+  --dv-inactivegroup-hiddenpanel-tab-color: hsl(var(--muted-foreground));
+  --dv-tabs-and-actions-container-font-size: 12px;
+  --dv-tabs-and-actions-container-height: 24px;
+  --dv-tab-font-size: 12px;
+  --dv-tabs-container-scrollbar-color: hsl(var(--muted-foreground) / 0.25);
+  --dv-scrollbar-background-color: hsl(var(--muted-foreground) / 0.25);
+  --dv-tab-divider-color: hsl(var(--border));
+  --dv-separator-border: transparent;
+  --dv-paneview-header-border-color: hsl(var(--border));
+  --dv-sash-color: hsl(var(--border));
+  --dv-icon-hover-background-color: hsl(var(--accent));
+  --dv-active-sash-color: hsl(var(--primary));
+  --dv-drag-over-background-color: hsl(var(--primary) / 0.15);
+  --dv-drag-over-border-color: hsl(var(--primary) / 0.6);
+  /* Remove tab margins for flush appearance */
+  --dv-tab-margin: 0;
+}
+
+/* Remove any gaps between panels - Rerun-style flush layout */
+.hyperview-dockview .dv-groupview {
+  border: none;
+}
+
+.hyperview-dockview .dv-tabs-and-actions-container {
+  border-bottom: 1px solid hsl(var(--border));
+}
+
+.hyperview-dockview .dv-tab {
+  padding: 0 8px;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  line-height: 16px;
+}
+
+.hyperview-dockview .dv-scrollable .dv-scrollbar-horizontal {
+  height: 6px;
+  border-radius: 3px;
+}
+
+/* Hide Dockview tab scrollbars (avoid extra bar under tabs) */
+.hyperview-dockview .dv-tabs-container {
+  scrollbar-width: none;
+}
+
+.hyperview-dockview .dv-tabs-container::-webkit-scrollbar {
+  height: 0;
+}
+
+.hyperview-dockview .dv-scrollable .dv-scrollbar-horizontal {
+  display: none;
+}
+
+/* Sash styling: transparent hit area with centered 1px visible line via pseudo-element */
+.hyperview-dockview .dv-split-view-container > .dv-sash-container > .dv-sash {
+  /* Keep the sash itself transparent - we'll draw the line with ::after */
+  background-color: transparent !important;
+}
+
+/* Horizontal sash (vertical divider line) */
+.hyperview-dockview .dv-split-view-container.dv-horizontal > .dv-sash-container > .dv-sash::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 1px;
+  background-color: hsl(var(--border));
+  pointer-events: none;
+}
+
+.hyperview-dockview .dv-split-view-container.dv-horizontal > .dv-sash-container > .dv-sash.dv-enabled:hover::after {
+  background-color: hsl(var(--primary));
+}
+
+/* Vertical sash (horizontal divider line) */
+.hyperview-dockview .dv-split-view-container.dv-vertical > .dv-sash-container > .dv-sash::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  height: 1px;
+  background-color: hsl(var(--border));
+  pointer-events: none;
+}
+
+.hyperview-dockview .dv-split-view-container.dv-vertical > .dv-sash-container > .dv-sash.dv-enabled:hover::after {
+  background-color: hsl(var(--primary));
+}

frontend/src/app/layout.tsx

@@ -0,0 +1,26 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import "./globals.css";
+
+const inter = Inter({
+  subsets: ["latin"],
+  display: "swap",
+  weight: ["400", "500"],
+});
+
+export const metadata: Metadata = {
+  title: "HyperView",
+  description: "Dataset visualization with hyperbolic embeddings",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" className="h-full">
+      <body className={`${inter.className} antialiased h-full`}>{children}</body>
+    </html>
+  );
+}

frontend/src/app/page.tsx

@@ -0,0 +1,277 @@
+"use client";
+
+import { useEffect, useCallback, useMemo, useRef, useState } from "react";
+import { Header } from "@/components";
+import { DockviewWorkspace, DockviewProvider } from "@/components/DockviewWorkspace";
+import { useStore } from "@/store/useStore";
+import type { Sample } from "@/types";
+import {
+  fetchDataset,
+  fetchSamples,
+  fetchSamplesBatch,
+  fetchLassoSelection,
+} from "@/lib/api";
+
+const SAMPLES_PER_PAGE = 100;
+
+export default function Home() {
+  const {
+    samples,
+    totalSamples,
+    samplesLoaded,
+    setSamples,
+    appendSamples,
+    addSamplesIfMissing,
+    setDatasetInfo,
+    setIsLoading,
+    isLoading,
+    error,
+    setError,
+    selectedIds,
+    isLassoSelection,
+    selectionSource,
+    lassoQuery,
+    lassoSamples,
+    lassoTotal,
+    lassoIsLoading,
+    setLassoResults,
+    labelFilter,
+  } = useStore();
+
+  const [loadingMore, setLoadingMore] = useState(false);
+  const labelFilterRef = useRef<string | null>(labelFilter ?? null);
+
+  // Initial data load - runs once on mount
+  // Store setters are stable and don't need to be in deps
+  useEffect(() => {
+    const loadData = async () => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        // Fetch dataset info and samples in parallel
+        const [datasetInfo, samplesRes] = await Promise.all([
+          fetchDataset(),
+          fetchSamples(0, SAMPLES_PER_PAGE),
+        ]);
+
+        setDatasetInfo(datasetInfo);
+        setSamples(samplesRes.samples, samplesRes.total);
+      } catch (err) {
+        console.error("Failed to load data:", err);
+        setError(err instanceof Error ? err.message : "Failed to load data");
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    loadData();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Fetch selected samples that aren't already loaded
+  useEffect(() => {
+    const fetchSelectedSamples = async () => {
+      if (isLassoSelection) return;
+      if (selectedIds.size === 0) return;
+      if (selectionSource === "label") return;
+
+      // Find IDs that are selected but not in our samples array
+      const loadedIds = new Set(samples.map((s) => s.id));
+      const missingIds = Array.from(selectedIds).filter((id) => !loadedIds.has(id));
+
+      if (missingIds.length === 0) return;
+
+      try {
+        const fetchedSamples = await fetchSamplesBatch(missingIds);
+        addSamplesIfMissing(fetchedSamples);
+      } catch (err) {
+        console.error("Failed to fetch selected samples:", err);
+      }
+    };
+
+    fetchSelectedSamples();
+  }, [selectedIds, samples, addSamplesIfMissing, isLassoSelection, selectionSource]);
+
+  // Refetch samples when label filter changes (non-lasso mode)
+  useEffect(() => {
+    if (labelFilterRef.current === labelFilter) return;
+    if (isLassoSelection) return;
+
+    labelFilterRef.current = labelFilter ?? null;
+
+    let cancelled = false;
+    const run = async () => {
+      try {
+        const res = await fetchSamples(0, SAMPLES_PER_PAGE, labelFilter ?? undefined);
+        if (cancelled) return;
+        setSamples(res.samples, res.total);
+      } catch (err) {
+        if (cancelled) return;
+        console.error("Failed to load filtered samples:", err);
+      }
+    };
+
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [isLassoSelection, labelFilter, setSamples]);
+
+  // Fetch initial lasso selection page when a new lasso query begins.
+  useEffect(() => {
+    if (!isLassoSelection) return;
+    if (!lassoQuery) return;
+    if (!lassoIsLoading) return;
+
+    const abort = new AbortController();
+
+    const run = async () => {
+      try {
+        const res = await fetchLassoSelection({
+          layoutKey: lassoQuery.layoutKey,
+          polygon: lassoQuery.polygon,
+          offset: 0,
+          limit: SAMPLES_PER_PAGE,
+          signal: abort.signal,
+        });
+        if (abort.signal.aborted) return;
+        setLassoResults(res.samples, res.total, false);
+      } catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        console.error("Failed to fetch lasso selection:", err);
+        setLassoResults([], 0, false);
+      }
+    };
+
+    run();
+
+    return () => abort.abort();
+  }, [isLassoSelection, lassoIsLoading, lassoQuery, setLassoResults]);
+
+  // Load more samples
+  const loadMore = useCallback(async () => {
+    if (loadingMore) return;
+
+    if (isLassoSelection) {
+      if (!lassoQuery) return;
+      if (lassoIsLoading) return;
+      if (!lassoIsLoading && lassoSamples.length >= lassoTotal) return;
+
+      setLoadingMore(true);
+      try {
+        const res = await fetchLassoSelection({
+          layoutKey: lassoQuery.layoutKey,
+          polygon: lassoQuery.polygon,
+          offset: lassoSamples.length,
+          limit: SAMPLES_PER_PAGE,
+        });
+        setLassoResults(res.samples, res.total, true);
+      } catch (err) {
+        console.error("Failed to load more lasso samples:", err);
+      } finally {
+        setLoadingMore(false);
+      }
+      return;
+    }
+
+    if (samplesLoaded >= totalSamples) return;
+
+    setLoadingMore(true);
+    try {
+      const res = await fetchSamples(samplesLoaded, SAMPLES_PER_PAGE, labelFilter ?? undefined);
+      appendSamples(res.samples);
+    } catch (err) {
+      console.error("Failed to load more samples:", err);
+    } finally {
+      setLoadingMore(false);
+    }
+  }, [
+    loadingMore,
+    appendSamples,
+    isLassoSelection,
+    lassoIsLoading,
+    lassoQuery,
+    lassoSamples.length,
+    lassoTotal,
+    samplesLoaded,
+    totalSamples,
+    setLassoResults,
+    labelFilter,
+  ]);
+
+  const displayedSamples = useMemo(() => {
+    if (isLassoSelection) return lassoSamples;
+
+    // When a selection comes from the scatter plot, bring selected samples to the top
+    // so the user immediately sees what they clicked.
+    if (selectionSource === "scatter" && selectedIds.size > 0) {
+      const byId = new Map<string, Sample>();
+      for (const s of samples) byId.set(s.id, s);
+
+      const pinned: Sample[] = [];
+      for (const id of selectedIds) {
+        const s = byId.get(id);
+        if (s) pinned.push(s);
+      }
+
+      if (pinned.length > 0) {
+        const rest = samples.filter((s) => !selectedIds.has(s.id));
+        return [...pinned, ...rest];
+      }
+    }
+
+    return samples;
+  }, [isLassoSelection, lassoSamples, samples, selectedIds, selectionSource]);
+
+  const displayedTotal = isLassoSelection ? lassoTotal : totalSamples;
+  const displayedHasMore = isLassoSelection ? displayedSamples.length < displayedTotal : samplesLoaded < totalSamples;
+
+  if (error) {
+    return (
+      <div className="h-screen flex flex-col bg-background">
+        <Header />
+        <div className="flex-1 flex items-center justify-center">
+          <div className="text-center">
+            <div className="text-destructive text-lg mb-2">Error</div>
+            <div className="text-muted-foreground">{error}</div>
+            <p className="text-muted-foreground mt-4 text-sm">
+              Make sure the HyperView backend is running on port 6262.
+            </p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  if (isLoading) {
+    return (
+      <div className="h-screen flex flex-col bg-background">
+        <Header />
+        <div className="flex-1 flex items-center justify-center">
+          <div className="text-center">
+            <div className="w-8 h-8 border-2 border-primary border-t-transparent rounded-full animate-spin mx-auto mb-4" />
+            <div className="text-muted-foreground">Loading dataset...</div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <DockviewProvider
+      samples={displayedSamples}
+      onLoadMore={loadMore}
+      hasMore={displayedHasMore}
+    >
+      <div className="h-screen flex flex-col bg-background">
+        <Header />
+
+        {/* Main content - dockable panels */}
+        <div className="flex-1 bg-background overflow-hidden">
+          <DockviewWorkspace />
+        </div>
+      </div>
+    </DockviewProvider>
+  );
+}

frontend/src/components/DockviewWorkspace.tsx

@@ -0,0 +1,765 @@
+"use client";
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  createContext,
+  useContext,
+  type ReactNode,
+} from "react";
+import {
+  DockviewReact,
+  type DockviewApi,
+  type DockviewReadyEvent,
+  type IDockviewPanelProps,
+  type IDockviewPanelHeaderProps,
+  type IWatermarkPanelProps,
+  themeAbyss,
+} from "dockview";
+import { Circle, Disc, Grid3X3 } from "lucide-react";
+
+import type { Geometry, Sample } from "@/types";
+import { useStore } from "@/store/useStore";
+import { findLayoutByGeometry } from "@/lib/layouts";
+import { ImageGrid } from "./ImageGrid";
+import { ScatterPanel } from "./ScatterPanel";
+import { ExplorerPanel } from "./ExplorerPanel";
+import { PlaceholderPanel } from "./PlaceholderPanel";
+import { HyperViewLogo } from "./icons";
+
+const LAYOUT_STORAGE_KEY = "hyperview:dockview-layout:v4";
+
+// Panel IDs
+const PANEL = {
+  EXPLORER: "explorer",
+  GRID: "grid",
+  SCATTER_EUCLIDEAN: "scatter-euclidean",
+  SCATTER_POINCARE: "scatter-poincare",
+  SCATTER_DEFAULT: "scatter-default",
+  RIGHT_PLACEHOLDER: "right-placeholder",
+  BOTTOM_PLACEHOLDER: "bottom-placeholder",
+} as const;
+
+const CENTER_PANEL_IDS = [
+  PANEL.GRID,
+  PANEL.SCATTER_EUCLIDEAN,
+  PANEL.SCATTER_POINCARE,
+  PANEL.SCATTER_DEFAULT,
+] as const;
+
+export const CENTER_PANEL_DEFS = [
+  { id: PANEL.GRID, label: "Samples", icon: Grid3X3 },
+  { id: PANEL.SCATTER_EUCLIDEAN, label: "Euclidean", icon: Circle },
+  { id: PANEL.SCATTER_POINCARE, label: "Hyperbolic", icon: Disc },
+] as const;
+
+const NON_ANCHOR_PANEL_IDS = new Set<string>([
+  PANEL.EXPLORER,
+  PANEL.RIGHT_PLACEHOLDER,
+  PANEL.BOTTOM_PLACEHOLDER,
+]);
+
+const DRAG_LOCKED_PANEL_IDS = new Set<string>([PANEL.EXPLORER]);
+
+const DEFAULT_CONTAINER_WIDTH = 1200;
+const DEFAULT_CONTAINER_HEIGHT = 800;
+const MIN_SIDE_PANEL_WIDTH = 120;
+const MIN_BOTTOM_PANEL_HEIGHT = 150;
+
+const getContainerWidth = (api?: DockviewApi | null) =>
+  api?.width ??
+  (typeof window === "undefined" ? DEFAULT_CONTAINER_WIDTH : window.innerWidth);
+const getContainerHeight = (api?: DockviewApi | null) =>
+  api?.height ??
+  (typeof window === "undefined" ? DEFAULT_CONTAINER_HEIGHT : window.innerHeight);
+
+const getDefaultLeftPanelWidth = (screenWidth: number) =>
+  Math.round(Math.min(0.35 * screenWidth, 200));
+const getDefaultRightPanelWidth = (screenWidth: number) =>
+  Math.round(Math.min(0.45 * screenWidth, 300));
+const getDefaultBottomPanelHeight = (containerHeight: number) =>
+  Math.round(
+    Math.min(Math.max(0.25 * containerHeight, MIN_BOTTOM_PANEL_HEIGHT), 250)
+  );
+const getBottomPanelMaxHeight = (containerHeight: number) =>
+  Math.round(
+    Math.max(containerHeight - MIN_BOTTOM_PANEL_HEIGHT, MIN_BOTTOM_PANEL_HEIGHT)
+  );
+
+function getCenterAnchorPanel(api: DockviewApi) {
+  for (const id of CENTER_PANEL_IDS) {
+    const panel = api.getPanel(id);
+    if (panel) return panel;
+  }
+
+  const fallback = api.panels.find((panel) => !NON_ANCHOR_PANEL_IDS.has(panel.id));
+  return fallback ?? api.activePanel;
+}
+
+function getZonePosition(zone: "left" | "right" | "bottom") {
+  return { direction: zone === "bottom" ? "below" : zone };
+}
+
+function getCenterTabPosition(api: DockviewApi) {
+  const anchor = getCenterAnchorPanel(api);
+  if (!anchor) return undefined;
+  return { referencePanel: anchor, direction: "within" as const };
+}
+
+// -----------------------------------------------------------------------------
+// Context for sharing dockview API across components
+// -----------------------------------------------------------------------------
+interface DockviewContextValue {
+  api: DockviewApi | null;
+  setApi: (api: DockviewApi) => void;
+  samples: Sample[];
+  onLoadMore: () => void;
+  hasMore: boolean;
+}
+
+const DockviewContext = createContext<DockviewContextValue | null>(null);
+
+function useDockviewContext() {
+  const ctx = useContext(DockviewContext);
+  if (!ctx) throw new Error("useDockviewContext must be used within DockviewProvider");
+  return ctx;
+}
+
+// Public hook for components like Header
+export function useDockviewApi() {
+  const ctx = useContext(DockviewContext);
+  const datasetInfo = useStore((state) => state.datasetInfo);
+  const {
+    leftPanelOpen,
+    rightPanelOpen,
+    bottomPanelOpen,
+    setLeftPanelOpen,
+    setRightPanelOpen,
+    setBottomPanelOpen,
+  } = useStore();
+
+  const addPanel = useCallback(
+    (panelId: string) => {
+      if (!ctx?.api) return;
+
+      const api = ctx.api;
+      const position = getCenterTabPosition(api);
+      const baseOptions = position ? { position } : {};
+
+      const layouts = datasetInfo?.layouts ?? [];
+      const euclideanLayout = findLayoutByGeometry(layouts, "euclidean");
+      const poincareLayout = findLayoutByGeometry(layouts, "poincare");
+
+      // Don't add if already exists - just focus it
+      if (api.getPanel(panelId)) {
+        api.getPanel(panelId)?.focus();
+        return;
+      }
+
+      switch (panelId) {
+        case PANEL.GRID:
+          api.addPanel({
+            id: PANEL.GRID,
+            component: "grid",
+            title: "Samples",
+            tabComponent: "samplesTab",
+            renderer: "always",
+            ...baseOptions,
+          });
+          break;
+
+        case PANEL.SCATTER_EUCLIDEAN:
+          api.addPanel({
+            id: PANEL.SCATTER_EUCLIDEAN,
+            component: "scatter",
+            title: "Euclidean",
+            tabComponent: "euclideanTab",
+            params: {
+              layoutKey: euclideanLayout?.layout_key,
+              geometry: "euclidean" as Geometry,
+            },
+            renderer: "always",
+            ...baseOptions,
+          });
+          break;
+
+        case PANEL.SCATTER_POINCARE:
+          api.addPanel({
+            id: PANEL.SCATTER_POINCARE,
+            component: "scatter",
+            title: "Hyperbolic",
+            tabComponent: "hyperbolicTab",
+            params: {
+              layoutKey: poincareLayout?.layout_key,
+              geometry: "poincare" as Geometry,
+            },
+            renderer: "always",
+            ...baseOptions,
+          });
+          break;
+      }
+    },
+    [ctx?.api, datasetInfo]
+  );
+
+  const resetLayout = useCallback(() => {
+    localStorage.removeItem(LAYOUT_STORAGE_KEY);
+    window.location.reload();
+  }, []);
+
+  // Toggle zone visibility
+  const toggleZone = useCallback(
+    (zone: "left" | "right" | "bottom") => {
+      if (!ctx?.api) return;
+
+      const api = ctx.api;
+      const panelId =
+        zone === "left"
+          ? PANEL.EXPLORER
+          : zone === "right"
+          ? PANEL.RIGHT_PLACEHOLDER
+          : PANEL.BOTTOM_PLACEHOLDER;
+      const setOpen =
+        zone === "left"
+          ? setLeftPanelOpen
+          : zone === "right"
+          ? setRightPanelOpen
+          : setBottomPanelOpen;
+      const isOpen =
+        zone === "left"
+          ? leftPanelOpen
+          : zone === "right"
+          ? rightPanelOpen
+          : bottomPanelOpen;
+
+      const existingPanel = api.getPanel(panelId);
+
+      if (isOpen && existingPanel) {
+        existingPanel.api.close();
+        setOpen(false);
+        return;
+      }
+
+      if (isOpen) return;
+
+      const containerWidth = getContainerWidth(api);
+      const containerHeight = getContainerHeight(api);
+      const position = getZonePosition(zone);
+
+      let newPanel;
+      if (zone === "left") {
+        const targetWidth = getDefaultLeftPanelWidth(containerWidth);
+        newPanel = api.addPanel({
+          id: panelId,
+          component: "explorer",
+          title: "Explorer",
+          position,
+          initialWidth: targetWidth,
+          minimumWidth: MIN_SIDE_PANEL_WIDTH,
+          maximumWidth: targetWidth,
+        });
+
+        if (newPanel) {
+          newPanel.group.locked = true;
+          newPanel.group.header.hidden = true;
+          // Explicitly set the width to ensure it's applied
+          newPanel.api.setSize({ width: targetWidth });
+        }
+      } else if (zone === "right") {
+        newPanel = api.addPanel({
+          id: panelId,
+          component: "placeholder",
+          title: "Blank",
+          position,
+          initialWidth: getDefaultRightPanelWidth(containerWidth),
+          minimumWidth: MIN_SIDE_PANEL_WIDTH,
+          maximumWidth: Math.round(containerWidth * 0.65),
+        });
+      } else {
+        newPanel = api.addPanel({
+          id: panelId,
+          component: "placeholder",
+          title: "Blank",
+          position,
+          initialHeight: getDefaultBottomPanelHeight(containerHeight),
+          minimumHeight: MIN_BOTTOM_PANEL_HEIGHT,
+          maximumHeight: getBottomPanelMaxHeight(containerHeight),
+        });
+      }
+
+      if (newPanel) {
+        setOpen(true);
+        // Activate the panel so its content renders immediately
+        newPanel.api.setActive();
+      }
+    },
+    [
+      ctx?.api,
+      leftPanelOpen,
+      rightPanelOpen,
+      bottomPanelOpen,
+      setLeftPanelOpen,
+      setRightPanelOpen,
+      setBottomPanelOpen,
+    ]
+  );
+
+  if (!ctx) return null;
+
+  return {
+    api: ctx.api,
+    addPanel,
+    resetLayout,
+    toggleZone,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Panel Components - stable references defined outside component
+// -----------------------------------------------------------------------------
+type ScatterPanelParams = {
+  layoutKey?: string;
+  geometry?: Geometry;
+};
+
+const ScatterDockPanel = React.memo(function ScatterDockPanel(
+  props: IDockviewPanelProps<ScatterPanelParams>
+) {
+  const params = props.params ?? {};
+  return (
+    <ScatterPanel
+      className="h-full"
+      layoutKey={params.layoutKey}
+      geometry={params.geometry}
+    />
+  );
+});
+
+// Custom tab component with icon (like Rerun's "Image and segmentation mask" tab)
+type TabWithIconProps = IDockviewPanelHeaderProps & {
+  icon: React.ReactNode;
+};
+
+const TabWithIcon = React.memo(function TabWithIcon({ api, icon }: TabWithIconProps) {
+  return (
+    <div className="flex items-center gap-1 text-[12px] leading-[16px] font-medium tracking-[-0.15px]">
+      <span className="flex-shrink-0">{icon}</span>
+      <span className="truncate">{api.title}</span>
+    </div>
+  );
+});
+
+// Tab components for different panel types
+const EuclideanTab = React.memo(function EuclideanTab(props: IDockviewPanelHeaderProps) {
+  return <TabWithIcon {...props} icon={<Circle className="h-3.5 w-3.5" />} />;
+});
+
+const HyperbolicTab = React.memo(function HyperbolicTab(props: IDockviewPanelHeaderProps) {
+  return <TabWithIcon {...props} icon={<Disc className="h-3.5 w-3.5" />} />;
+});
+
+const SamplesTab = React.memo(function SamplesTab(props: IDockviewPanelHeaderProps) {
+  return <TabWithIcon {...props} icon={<Grid3X3 className="h-3.5 w-3.5" />} />;
+});
+
+// Grid panel uses context to get samples
+const GridDockPanel = React.memo(function GridDockPanel() {
+  const ctx = useDockviewContext();
+  return (
+    <ImageGrid
+      samples={ctx.samples}
+      onLoadMore={ctx.onLoadMore}
+      hasMore={ctx.hasMore}
+    />
+  );
+});
+
+// Explorer panel for left zone
+const ExplorerDockPanel = React.memo(function ExplorerDockPanel() {
+  return <ExplorerPanel />;
+});
+
+// Placeholder panel for right/bottom zones
+const PlaceholderDockPanel = React.memo(function PlaceholderDockPanel(
+  props: IDockviewPanelProps
+) {
+  const handleClose = React.useCallback(() => {
+    props.api.close();
+  }, [props.api]);
+
+  return <PlaceholderPanel onClose={handleClose} />;
+});
+
+// Watermark shown when dock is empty - just the logo, no text
+const Watermark = React.memo(function Watermark(_props: IWatermarkPanelProps) {
+  return (
+    <div className="flex items-center justify-center h-full w-full">
+      <div className="text-muted-foreground/20">
+        <HyperViewLogo className="w-16 h-16" />
+      </div>
+    </div>
+  );
+});
+
+// Stable components object - never changes
+const COMPONENTS = {
+  grid: GridDockPanel,
+  scatter: ScatterDockPanel,
+  explorer: ExplorerDockPanel,
+  placeholder: PlaceholderDockPanel,
+};
+
+// Tab components with icons
+const TAB_COMPONENTS = {
+  euclideanTab: EuclideanTab,
+  hyperbolicTab: HyperbolicTab,
+  samplesTab: SamplesTab,
+};
+
+// -----------------------------------------------------------------------------
+// Provider Component
+// -----------------------------------------------------------------------------
+interface DockviewProviderProps {
+  children: ReactNode;
+  samples: Sample[];
+  onLoadMore: () => void;
+  hasMore: boolean;
+}
+
+export function DockviewProvider({
+  children,
+  samples,
+  onLoadMore,
+  hasMore,
+}: DockviewProviderProps) {
+  const [api, setApi] = useState<DockviewApi | null>(null);
+
+  const contextValue = useMemo(
+    () => ({
+      api,
+      setApi,
+      samples,
+      onLoadMore,
+      hasMore,
+    }),
+    [api, samples, onLoadMore, hasMore]
+  );
+
+  return (
+    <DockviewContext.Provider value={contextValue}>
+      {children}
+    </DockviewContext.Provider>
+  );
+}
+
+function applyZonePolicies(api: DockviewApi) {
+  const explorer = api.getPanel(PANEL.EXPLORER);
+  if (explorer) {
+    explorer.group.locked = true;
+    explorer.group.header.hidden = true;
+  }
+
+  // Hide tab headers for placeholder panels
+  const rightPlaceholder = api.getPanel(PANEL.RIGHT_PLACEHOLDER);
+  if (rightPlaceholder) {
+    rightPlaceholder.group.header.hidden = true;
+  }
+
+  const bottomPlaceholder = api.getPanel(PANEL.BOTTOM_PLACEHOLDER);
+  if (bottomPlaceholder) {
+    bottomPlaceholder.group.header.hidden = true;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Workspace Component - the actual dockview renderer
+// -----------------------------------------------------------------------------
+export function DockviewWorkspace() {
+  const ctx = useDockviewContext();
+  const datasetInfo = useStore((state) => state.datasetInfo);
+  const { setLeftPanelOpen, setRightPanelOpen, setBottomPanelOpen } = useStore();
+
+  const buildDefaultLayout = useCallback(
+    (api: DockviewApi) => {
+      const layouts = datasetInfo?.layouts ?? [];
+      const euclideanLayout = findLayoutByGeometry(layouts, "euclidean");
+      const poincareLayout = findLayoutByGeometry(layouts, "poincare");
+      const fallbackLayout = !euclideanLayout && !poincareLayout ? layouts[0] : null;
+      const hasLayouts = layouts.length > 0;
+
+      // Create the grid panel first (center zone)
+      const gridPanel =
+        api.getPanel(PANEL.GRID) ??
+        api.addPanel({
+          id: PANEL.GRID,
+          component: "grid",
+          title: "Samples",
+          tabComponent: "samplesTab",
+          renderer: "always",
+        });
+
+      let scatterPanel: typeof gridPanel | null = null;
+
+      if (hasLayouts && euclideanLayout) {
+        scatterPanel =
+          api.getPanel(PANEL.SCATTER_EUCLIDEAN) ??
+          api.addPanel({
+            id: PANEL.SCATTER_EUCLIDEAN,
+            component: "scatter",
+            title: "Euclidean",
+            tabComponent: "euclideanTab",
+            params: {
+              layoutKey: euclideanLayout.layout_key,
+              geometry: "euclidean" as Geometry,
+            },
+            position: {
+              referencePanel: gridPanel.id,
+              direction: "right",
+            },
+            renderer: "always",
+          });
+      }
+
+      if (hasLayouts && poincareLayout) {
+        const position = scatterPanel
+          ? { referencePanel: scatterPanel.id, direction: "within" as const }
+          : { referencePanel: gridPanel.id, direction: "right" as const };
+
+        const poincarePanel =
+          api.getPanel(PANEL.SCATTER_POINCARE) ??
+          api.addPanel({
+            id: PANEL.SCATTER_POINCARE,
+            component: "scatter",
+            title: "Hyperbolic",
+            tabComponent: "hyperbolicTab",
+            params: {
+              layoutKey: poincareLayout.layout_key,
+              geometry: "poincare" as Geometry,
+            },
+            position,
+            renderer: "always",
+          });
+
+        if (!scatterPanel) {
+          scatterPanel = poincarePanel;
+        }
+      }
+
+      if (!hasLayouts) {
+        const euclideanPanel =
+          api.getPanel(PANEL.SCATTER_EUCLIDEAN) ??
+          api.addPanel({
+            id: PANEL.SCATTER_EUCLIDEAN,
+            component: "scatter",
+            title: "Euclidean",
+            tabComponent: "euclideanTab",
+            params: {
+              geometry: "euclidean" as Geometry,
+            },
+            position: {
+              referencePanel: gridPanel.id,
+              direction: "right",
+            },
+            renderer: "always",
+          });
+
+        api.getPanel(PANEL.SCATTER_POINCARE) ??
+          api.addPanel({
+            id: PANEL.SCATTER_POINCARE,
+            component: "scatter",
+            title: "Hyperbolic",
+            tabComponent: "hyperbolicTab",
+            params: {
+              geometry: "poincare" as Geometry,
+            },
+            position: {
+              referencePanel: euclideanPanel.id,
+              direction: "within" as const,
+            },
+            renderer: "always",
+          });
+
+        scatterPanel = euclideanPanel;
+      }
+
+      if (fallbackLayout && !scatterPanel) {
+        api.getPanel(PANEL.SCATTER_DEFAULT) ??
+          api.addPanel({
+            id: PANEL.SCATTER_DEFAULT,
+            component: "scatter",
+            title: "Embeddings",
+            params: {
+              layoutKey: fallbackLayout.layout_key,
+            },
+            position: {
+              referencePanel: gridPanel.id,
+              direction: "right",
+            },
+            renderer: "always",
+          });
+      }
+
+      const containerWidth = getContainerWidth(api);
+      const explorerPanel =
+        api.getPanel(PANEL.EXPLORER) ??
+        api.addPanel({
+          id: PANEL.EXPLORER,
+          component: "explorer",
+          title: "Explorer",
+          position: getZonePosition("left"),
+          initialWidth: getDefaultLeftPanelWidth(containerWidth),
+          minimumWidth: MIN_SIDE_PANEL_WIDTH,
+          maximumWidth: getDefaultLeftPanelWidth(containerWidth),
+          inactive: true,
+        });
+
+      if (explorerPanel) {
+        explorerPanel.group.locked = true;
+        explorerPanel.group.header.hidden = true;
+      }
+
+      setLeftPanelOpen(!!explorerPanel);
+      setRightPanelOpen(false);
+      setBottomPanelOpen(false);
+    },
+    [datasetInfo, setLeftPanelOpen, setRightPanelOpen, setBottomPanelOpen]
+  );
+
+  const onReady = useCallback(
+    (event: DockviewReadyEvent) => {
+      ctx.setApi(event.api);
+
+      const stored = localStorage.getItem(LAYOUT_STORAGE_KEY);
+      if (stored) {
+        try {
+          event.api.fromJSON(JSON.parse(stored));
+          if (event.api.totalPanels === 0) {
+            localStorage.removeItem(LAYOUT_STORAGE_KEY);
+            buildDefaultLayout(event.api);
+          }
+
+          // Re-apply side-zone policies after restore (header hidden, no-drop targets, etc)
+          applyZonePolicies(event.api);
+          
+          // Sync store state with restored layout
+          setLeftPanelOpen(!!event.api.getPanel(PANEL.EXPLORER));
+          setRightPanelOpen(!!event.api.getPanel(PANEL.RIGHT_PLACEHOLDER));
+          setBottomPanelOpen(!!event.api.getPanel(PANEL.BOTTOM_PLACEHOLDER));
+          return;
+        } catch (err) {
+          console.warn("Failed to restore dock layout, resetting.", err);
+          localStorage.removeItem(LAYOUT_STORAGE_KEY);
+        }
+      }
+
+      if (event.api.totalPanels === 0) {
+        buildDefaultLayout(event.api);
+      }
+    },
+    [buildDefaultLayout, ctx, setLeftPanelOpen, setRightPanelOpen, setBottomPanelOpen]
+  );
+
+  // Save layout on changes
+  useEffect(() => {
+    const api = ctx.api;
+    if (!api) return;
+
+    const disposable = api.onDidLayoutChange(() => {
+      if (api.totalPanels === 0) return;
+      const layout = api.toJSON();
+      localStorage.setItem(LAYOUT_STORAGE_KEY, JSON.stringify(layout));
+    });
+
+    return () => disposable.dispose();
+  }, [ctx.api]);
+
+  // Sync panel state when panels are closed
+  useEffect(() => {
+    const api = ctx.api;
+    if (!api) return;
+
+    const disposable = api.onDidRemovePanel((e) => {
+      if (e.id === PANEL.EXPLORER) setLeftPanelOpen(false);
+      if (e.id === PANEL.RIGHT_PLACEHOLDER) setRightPanelOpen(false);
+      if (e.id === PANEL.BOTTOM_PLACEHOLDER) setBottomPanelOpen(false);
+    });
+
+    return () => disposable.dispose();
+  }, [ctx.api, setLeftPanelOpen, setRightPanelOpen, setBottomPanelOpen]);
+
+  // When a real panel is dropped into a placeholder group, close the placeholder
+  useEffect(() => {
+    const api = ctx.api;
+    if (!api) return;
+
+    const disposable = api.onDidAddPanel((e) => {
+      // Skip if the added panel is a placeholder itself
+      if (e.id === PANEL.RIGHT_PLACEHOLDER || e.id === PANEL.BOTTOM_PLACEHOLDER) {
+        return;
+      }
+
+      // Check if this panel was added to the same group as a placeholder
+      const group = e.group;
+      if (!group) return;
+
+      // Find and close any placeholder panels in the same group
+      const rightPlaceholder = api.getPanel(PANEL.RIGHT_PLACEHOLDER);
+      const bottomPlaceholder = api.getPanel(PANEL.BOTTOM_PLACEHOLDER);
+
+      if (rightPlaceholder && rightPlaceholder.group?.id === group.id) {
+        rightPlaceholder.api.close();
+      }
+      if (bottomPlaceholder && bottomPlaceholder.group?.id === group.id) {
+        bottomPlaceholder.api.close();
+      }
+    });
+
+    return () => disposable.dispose();
+  }, [ctx.api]);
+
+  // Prevent dragging locked panels (explorer only)
+  useEffect(() => {
+    const api = ctx.api;
+    if (!api) return;
+
+    const disposable = api.onWillDragPanel((event) => {
+      if (DRAG_LOCKED_PANEL_IDS.has(event.panel.id)) {
+        event.nativeEvent.preventDefault();
+      }
+    });
+
+    return () => disposable.dispose();
+  }, [ctx.api]);
+
+  // Rebuild layout when dataset info changes
+  useEffect(() => {
+    if (!ctx.api) return;
+    if (!datasetInfo) return;
+
+    const hasScatter =
+      ctx.api.getPanel(PANEL.SCATTER_EUCLIDEAN) ||
+      ctx.api.getPanel(PANEL.SCATTER_POINCARE) ||
+      ctx.api.getPanel(PANEL.SCATTER_DEFAULT);
+
+    if (!hasScatter) {
+      buildDefaultLayout(ctx.api);
+    }
+  }, [buildDefaultLayout, datasetInfo, ctx.api]);
+
+  return (
+    <div className="h-full w-full">
+      <DockviewReact
+        className="dockview-theme-abyss hyperview-dockview"
+        components={COMPONENTS}
+        tabComponents={TAB_COMPONENTS}
+        onReady={onReady}
+        theme={themeAbyss}
+        defaultRenderer="always"
+        scrollbars="native"
+        watermarkComponent={Watermark}
+      />
+    </div>
+  );
+}

frontend/src/components/ExplorerPanel.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import React from "react";
+import { useStore } from "@/store/useStore";
+import { Panel } from "./Panel";
+import { PanelHeader } from "./PanelHeader";
+import { Tag, Search, ChevronDown, ChevronRight } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { FALLBACK_LABEL_COLOR, MISSING_LABEL_COLOR, normalizeLabel } from "@/lib/labelColors";
+import { useLabelLegend } from "./useLabelLegend";
+
+interface ExplorerPanelProps {
+  className?: string;
+}
+
+export function ExplorerPanel({ className }: ExplorerPanelProps) {
+  const {
+    datasetInfo,
+    embeddingsByLayoutKey,
+    activeLayoutKey,
+    labelFilter,
+    setLabelFilter,
+  } = useStore();
+  const [labelSearch, setLabelSearch] = React.useState("");
+  const [isSearchOpen, setIsSearchOpen] = React.useState(false);
+  const [isLabelsExpanded, setIsLabelsExpanded] = React.useState(true);
+  const searchInputRef = React.useRef<HTMLInputElement>(null);
+
+  const resolvedLayoutKey =
+    activeLayoutKey ?? datasetInfo?.layouts?.[0]?.layout_key ?? null;
+  const embeddings = resolvedLayoutKey
+    ? embeddingsByLayoutKey[resolvedLayoutKey] ?? null
+    : null;
+
+  const {
+    labelCounts,
+    labelUniverse,
+    distinctLabelCount,
+    distinctColoringDisabled,
+    labelColorMap,
+    legendLabels,
+  } = useLabelLegend({ datasetInfo, embeddings, labelSearch, labelFilter });
+
+  const hasCounts = labelCounts.size > 0;
+  const baseLabelCount = labelUniverse.length > 0
+    ? labelUniverse.filter((label) => label !== "undefined").length
+    : distinctLabelCount;
+  const displayCount = labelSearch.trim().length > 0
+    ? legendLabels.length
+    : baseLabelCount;
+
+  const activeLabel = labelFilter ? normalizeLabel(labelFilter) : null;
+
+  // Focus search input when opened
+  React.useEffect(() => {
+    if (isSearchOpen && searchInputRef.current) {
+      searchInputRef.current.focus();
+    }
+  }, [isSearchOpen]);
+
+  const handleSearchToggle = () => {
+    setIsSearchOpen(!isSearchOpen);
+    if (isSearchOpen) {
+      setLabelSearch("");
+    }
+  };
+
+  return (
+    <Panel className={cn("h-full flex flex-col", className)}>
+      <PanelHeader title="Explorer" />
+      
+      {/* Scrollable content area */}
+      <div className="flex-1 min-h-0 overflow-auto panel-scroll">
+        {/* Labels section */}
+        <div className="border-b border-border">
+          {/* Section header - collapsible with search icon */}
+          <div className="flex items-center h-6 px-2 bg-secondary/50">
+            <button
+              onClick={() => setIsLabelsExpanded(!isLabelsExpanded)}
+              className="flex items-center gap-1.5 flex-1 min-w-0 text-left hover:bg-muted/30 rounded px-1 -ml-1"
+            >
+              {isLabelsExpanded ? (
+                <ChevronDown className="h-3 w-3 flex-shrink-0 text-muted-foreground" />
+              ) : (
+                <ChevronRight className="h-3 w-3 flex-shrink-0 text-muted-foreground" />
+              )}
+              <Tag className="h-3 w-3 flex-shrink-0 text-muted-foreground" />
+              <span className="text-xs text-muted-foreground truncate">
+                Labels
+              </span>
+              <span className="ml-auto text-xs text-muted-foreground/50 tabular-nums">
+                {displayCount}
+              </span>
+            </button>
+            
+            {/* Search toggle button */}
+            <button
+              onClick={handleSearchToggle}
+              className={cn(
+                "h-5 w-5 flex items-center justify-center rounded text-muted-foreground/60 hover:text-muted-foreground hover:bg-muted/50 transition-colors ml-1",
+                isSearchOpen && "text-muted-foreground bg-muted/50"
+              )}
+              title="Search labels"
+            >
+              <Search className="h-3 w-3" />
+            </button>
+          </div>
+
+          {/* Search input - shown when search is toggled */}
+          {isSearchOpen && (
+            <div className="px-2 py-1.5 bg-secondary/30 border-b border-border/50">
+              <input
+                ref={searchInputRef}
+                value={labelSearch}
+                onChange={(e) => setLabelSearch(e.target.value)}
+                placeholder="Filter labels..."
+                className="w-full h-6 px-2 rounded bg-background border border-border text-[12px] leading-[16px] text-foreground placeholder:text-muted-foreground/50 outline-none focus:ring-1 focus:ring-ring focus:border-ring"
+              />
+            </div>
+          )}
+
+          {/* Labels list - collapsible */}
+          {isLabelsExpanded && (
+            <div className="py-1">
+              {distinctColoringDisabled && (
+                <div className="px-3 py-1 text-[10px] text-muted-foreground/60">
+                  Too many labels ({distinctLabelCount}) to color distinctly; using one color.
+                </div>
+              )}
+
+              {legendLabels.length === 0 ? (
+                <div className="px-3 py-2 text-[11px] text-muted-foreground/50">
+                  No labels available
+                </div>
+              ) : (
+                <div className="space-y-px">
+                  {legendLabels.map((label) => {
+                    const color =
+                      label === "undefined"
+                        ? MISSING_LABEL_COLOR
+                        : labelColorMap[label] ?? FALLBACK_LABEL_COLOR;
+                    const normalized = normalizeLabel(label);
+                    const isActive = activeLabel === normalized;
+                    const isDimmed = activeLabel && !isActive;
+
+                    return (
+                      <button
+                        key={label}
+                        type="button"
+                        onClick={() => setLabelFilter(isActive ? null : normalized)}
+                        className={cn(
+                          "flex items-center gap-2 w-full h-6 px-3 text-[12px] leading-[16px] text-left text-muted-foreground hover:text-foreground",
+                          "hover:bg-muted/40 transition-colors",
+                          isActive && "bg-muted/60 text-foreground",
+                          isDimmed && "opacity-40"
+                        )}
+                      >
+                        <span
+                          className="w-2 h-2 rounded-full flex-shrink-0"
+                          style={{ backgroundColor: color }}
+                        />
+                        <span className="truncate flex-1" title={label}>
+                          {label}
+                        </span>
+                        {hasCounts && (
+                          <span className="text-[10px] text-muted-foreground/50 font-mono tabular-nums flex-shrink-0">
+                            {labelCounts.get(label) ?? 0}
+                          </span>
+                        )}
+                      </button>
+                    );
+                  })}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </Panel>
+  );
+}

frontend/src/components/Header.tsx

@@ -0,0 +1,244 @@
+"use client";
+
+import { useStore } from "@/store/useStore";
+import { Button } from "@/components/ui/button";
+import { HyperViewLogo, DiscordIcon } from "./icons";
+import { CENTER_PANEL_DEFS, useDockviewApi } from "./DockviewWorkspace";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  ChevronDown,
+  RotateCcw,
+  Check,
+  PanelLeft,
+  PanelBottom,
+  PanelRight,
+  Settings,
+  Search,
+} from "lucide-react";
+import { useState } from "react";
+import { cn } from "@/lib/utils";
+
+const PANEL_CONFIG = CENTER_PANEL_DEFS;
+const DISCORD_URL = process.env.NEXT_PUBLIC_DISCORD_URL ?? "https://discord.gg/Qf2pXtY4Vf";
+
+export function Header() {
+  const { datasetInfo, leftPanelOpen, rightPanelOpen, bottomPanelOpen } = useStore();
+  const dockview = useDockviewApi();
+  const [datasetPickerOpen, setDatasetPickerOpen] = useState(false);
+
+  const handlePanelToggle = (panelId: string) => {
+    if (!dockview?.api) return;
+    const panel = dockview.api.getPanel(panelId);
+    if (panel) {
+      panel.api.close();
+      return;
+    }
+    dockview.addPanel(panelId);
+  };
+
+  // Check which panels are currently open
+  const openPanels = new Set(
+    PANEL_CONFIG.map((p) => p.id).filter((id) => dockview?.api?.getPanel(id))
+  );
+
+  return (
+    <header className="h-7 min-h-[28px] bg-secondary border-b border-border flex items-center justify-between px-2">
+        {/* Left side: Logo + View menu */}
+        <div className="flex items-center gap-2">
+          {/* Logo */}
+          <div className="flex items-center justify-center h-6 w-6 text-primary">
+            <HyperViewLogo className="h-3.5 w-3.5" />
+          </div>
+
+          {/* View dropdown */}
+          {dockview && (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="h-6 px-2 text-[12px] leading-[16px] tracking-[-0.15px] text-muted-foreground hover:text-foreground hover:bg-muted/50"
+                >
+                  View
+                  <ChevronDown className="ml-0.5 h-2.5 w-2.5" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start" className="w-48">
+                {/* Panel toggles - no section header, similar to Rerun */}
+                {PANEL_CONFIG.map((panel) => {
+                  const Icon = panel.icon;
+                  const isOpen = openPanels.has(panel.id);
+                  return (
+                    <DropdownMenuItem
+                      key={panel.id}
+                      onClick={() => handlePanelToggle(panel.id)}
+                      className="flex items-center justify-between h-7 text-[12px] leading-[16px]"
+                    >
+                      <span className="flex items-center gap-2">
+                        <Icon className="h-3.5 w-3.5" />
+                        {panel.label}
+                      </span>
+                      {isOpen && <Check className="h-3.5 w-3.5 text-primary" />}
+                    </DropdownMenuItem>
+                  );
+                })}
+
+                {/* Spacer */}
+                <div className="h-2" />
+
+                {/* Reset layout */}
+                <DropdownMenuItem
+                  onClick={() => dockview.resetLayout()}
+                  className="flex items-center gap-2 h-7 text-[12px] leading-[16px]"
+                >
+                  <RotateCcw className="h-3.5 w-3.5" />
+                  Reset Layout
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          )}
+        </div>
+
+        {/* Center: Dataset picker (VS Code style command palette trigger) */}
+        <div className="flex-1 flex justify-center px-4">
+          <Popover open={datasetPickerOpen} onOpenChange={setDatasetPickerOpen}>
+            <PopoverTrigger asChild>
+              <Button
+                variant="ghost"
+                size="sm"
+                role="combobox"
+                aria-expanded={datasetPickerOpen}
+                className="h-6 min-w-[200px] max-w-[400px] px-3 text-[12px] leading-[16px] tracking-[-0.15px] text-muted-foreground hover:text-foreground bg-muted/40 hover:bg-muted/60 border border-border/50 rounded-md justify-start gap-2"
+              >
+                <Search className="h-3 w-3 flex-shrink-0 opacity-50" />
+                <span className="truncate flex-1 text-left">
+                  {datasetInfo?.name ?? "No dataset loaded"}
+                </span>
+              </Button>
+            </PopoverTrigger>
+            <PopoverContent className="w-[280px] p-0" align="center">
+              <Command>
+                <CommandInput
+                  placeholder="Search datasets..."
+                  className="h-6 text-[12px] leading-[16px]"
+                />
+                <CommandList>
+                  <CommandEmpty className="py-4 text-xs text-center">
+                    No datasets found.
+                  </CommandEmpty>
+                  <CommandGroup>
+                    {/* Currently only show the loaded dataset */}
+                    {datasetInfo && (
+                      <CommandItem
+                        value={datasetInfo.name}
+                        onSelect={() => setDatasetPickerOpen(false)}
+                        className="text-[12px] leading-[16px]"
+                      >
+                        <span className="flex-1 truncate">{datasetInfo.name}</span>
+                        <span className="text-[10px] text-muted-foreground ml-2">
+                          {datasetInfo.num_samples.toLocaleString()} samples
+                        </span>
+                        <Check className="h-3 w-3 ml-2 text-primary" />
+                      </CommandItem>
+                    )}
+                  </CommandGroup>
+                </CommandList>
+              </Command>
+            </PopoverContent>
+          </Popover>
+        </div>
+
+        {/* Right side: Discord + Panel toggles + Settings */}
+        <div className="flex items-center gap-0.5">
+          {/* Discord link */}
+          <a
+            href={DISCORD_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="h-6 w-6 p-0 flex items-center justify-center rounded-sm text-muted-foreground hover:text-foreground hover:bg-muted/40 transition-colors"
+            title="Join our Discord community"
+          >
+            <DiscordIcon className="h-3.5 w-3.5" />
+          </a>
+
+          {/* Separator */}
+          <div className="w-px h-3 bg-border mx-1" />
+
+          {/* Left panel toggle */}
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => dockview?.toggleZone("left")}
+            className={cn(
+              "h-6 w-6 p-0",
+              leftPanelOpen
+                ? "text-foreground bg-muted/50"
+                : "text-muted-foreground hover:text-foreground hover:bg-muted/40"
+            )}
+          >
+            <PanelLeft className="h-3.5 w-3.5" />
+          </Button>
+
+          {/* Bottom panel toggle */}
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => dockview?.toggleZone("bottom")}
+            className={cn(
+              "h-6 w-6 p-0",
+              bottomPanelOpen
+                ? "text-foreground bg-muted/50"
+                : "text-muted-foreground hover:text-foreground hover:bg-muted/40"
+            )}
+          >
+            <PanelBottom className="h-3.5 w-3.5" />
+          </Button>
+
+          {/* Right panel toggle */}
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => dockview?.toggleZone("right")}
+            className={cn(
+              "h-6 w-6 p-0",
+              rightPanelOpen
+                ? "text-foreground bg-muted/50"
+                : "text-muted-foreground hover:text-foreground hover:bg-muted/40"
+            )}
+          >
+            <PanelRight className="h-3.5 w-3.5" />
+          </Button>
+
+          {/* Separator */}
+          <div className="w-px h-3 bg-border mx-1" />
+
+          {/* Settings button */}
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-6 w-6 p-0 text-muted-foreground hover:text-foreground hover:bg-muted/40"
+          >
+            <Settings className="h-3.5 w-3.5" />
+          </Button>
+        </div>
+    </header>
+  );
+}

frontend/src/components/ImageGrid.tsx

@@ -0,0 +1,338 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import justifiedLayout from "justified-layout";
+import { useStore } from "@/store/useStore";
+import { Panel } from "./Panel";
+import { CheckIcon } from "./icons";
+import type { Sample } from "@/types";
+
+interface ImageGridProps {
+  samples: Sample[];
+  onLoadMore?: () => void;
+  hasMore?: boolean;
+}
+
+// Justified layout config
+const BOX_SPACING = 2; // Tight spacing between images
+const TARGET_ROW_HEIGHT = 180; // Target height for rows
+const DEFAULT_ASPECT_RATIO = 1; // Fallback for samples without dimensions
+
+/**
+ * Get aspect ratio from sample, with fallback
+ */
+function getAspectRatio(sample: Sample): number {
+  if (sample.width && sample.height && sample.height > 0) {
+    return sample.width / sample.height;
+  }
+  return DEFAULT_ASPECT_RATIO;
+}
+
+/**
+ * Compute justified layout geometry for samples
+ */
+function computeLayout(
+  samples: Sample[],
+  containerWidth: number
+): { boxes: Array<{ width: number; height: number; top: number; left: number }>; containerHeight: number } {
+  if (samples.length === 0 || containerWidth <= 0) {
+    return { boxes: [], containerHeight: 0 };
+  }
+
+  const aspectRatios = samples.map(getAspectRatio);
+
+  const geometry = justifiedLayout(aspectRatios, {
+    containerWidth,
+    containerPadding: 0,
+    boxSpacing: BOX_SPACING,
+    targetRowHeight: TARGET_ROW_HEIGHT,
+    targetRowHeightTolerance: 0.25,
+    showWidows: true, // Always show last row even if incomplete
+  });
+
+  return {
+    boxes: geometry.boxes,
+    containerHeight: geometry.containerHeight,
+  };
+}
+
+/**
+ * Group boxes into rows for virtualization
+ */
+interface RowData {
+  startIndex: number;
+  endIndex: number; // exclusive
+  top: number;
+  height: number;
+}
+
+function groupIntoRows(
+  boxes: Array<{ width: number; height: number; top: number; left: number }>
+): RowData[] {
+  if (boxes.length === 0) return [];
+
+  const rows: RowData[] = [];
+  let currentRowTop = boxes[0].top;
+  let currentRowStart = 0;
+  let currentRowHeight = boxes[0].height;
+
+  for (let i = 1; i < boxes.length; i++) {
+    const box = boxes[i];
+    // New row if top position changes significantly
+    if (Math.abs(box.top - currentRowTop) > 1) {
+      rows.push({
+        startIndex: currentRowStart,
+        endIndex: i,
+        top: currentRowTop,
+        height: currentRowHeight,
+      });
+      currentRowStart = i;
+      currentRowTop = box.top;
+      currentRowHeight = box.height;
+    } else {
+      // Same row - take max height in case of slight variations
+      currentRowHeight = Math.max(currentRowHeight, box.height);
+    }
+  }
+
+  // Push final row
+  rows.push({
+    startIndex: currentRowStart,
+    endIndex: boxes.length,
+    top: currentRowTop,
+    height: currentRowHeight,
+  });
+
+  return rows;
+}
+
+export function ImageGrid({ samples, onLoadMore, hasMore }: ImageGridProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  const {
+    selectedIds,
+    isLassoSelection,
+    selectionSource,
+    toggleSelection,
+    addToSelection,
+    setHoveredId,
+    hoveredId,
+    labelFilter,
+  } = useStore();
+
+  // Track container width for layout computation
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const updateWidth = () => {
+      const width = container.clientWidth;
+      if (width > 0 && width !== containerWidth) {
+        setContainerWidth(width);
+      }
+    };
+
+    updateWidth();
+
+    const resizeObserver = new ResizeObserver(() => {
+      requestAnimationFrame(updateWidth);
+    });
+    resizeObserver.observe(container);
+
+    return () => resizeObserver.disconnect();
+  }, [containerWidth]);
+
+  // Compute justified layout
+  const { boxes, containerHeight } = useMemo(
+    () => computeLayout(samples, containerWidth),
+    [samples, containerWidth]
+  );
+
+  // Group into rows for virtualization
+  const rows = useMemo(() => groupIntoRows(boxes), [boxes]);
+
+  // Virtualizer for rows
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => containerRef.current,
+    estimateSize: (index) => rows[index]?.height ?? TARGET_ROW_HEIGHT,
+    overscan: 3,
+    getItemKey: (index) => {
+      const row = rows[index];
+      if (!row) return `row-${index}`;
+      // Create stable key from sample IDs in this row
+      const rowSamples = samples.slice(row.startIndex, row.endIndex);
+      return rowSamples.map((s) => s.id).join("-") || `row-${index}`;
+    },
+  });
+
+  // Load more when scrolling near bottom
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !onLoadMore || !hasMore) return;
+
+    const handleScroll = () => {
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      if (scrollHeight - scrollTop - clientHeight < 500) {
+        onLoadMore();
+      }
+    };
+
+    container.addEventListener("scroll", handleScroll);
+    return () => container.removeEventListener("scroll", handleScroll);
+  }, [onLoadMore, hasMore]);
+
+  // Reset scroll on filter change
+  useEffect(() => {
+    containerRef.current?.scrollTo({ top: 0 });
+  }, [labelFilter]);
+
+  // Scroll to top when scatter selection made
+  useEffect(() => {
+    if (isLassoSelection) return;
+    if (selectionSource !== "scatter") return;
+    if (selectedIds.size === 0) return;
+
+    try {
+      virtualizer.scrollToIndex(0, { align: "start" });
+    } catch {
+      containerRef.current?.scrollTo({ top: 0 });
+    }
+  }, [isLassoSelection, selectedIds, selectionSource, virtualizer]);
+
+  // Handle click with selection logic
+  const handleClick = useCallback(
+    (sample: Sample, event: React.MouseEvent) => {
+      if (event.metaKey || event.ctrlKey) {
+        toggleSelection(sample.id);
+      } else if (event.shiftKey && selectedIds.size > 0) {
+        const selectedArray = Array.from(selectedIds);
+        const lastSelected = selectedArray[selectedArray.length - 1];
+        const lastIndex = samples.findIndex((s) => s.id === lastSelected);
+        const currentIndex = samples.findIndex((s) => s.id === sample.id);
+
+        if (lastIndex !== -1 && currentIndex !== -1) {
+          const start = Math.min(lastIndex, currentIndex);
+          const end = Math.max(lastIndex, currentIndex);
+          const rangeIds = samples.slice(start, end + 1).map((s) => s.id);
+          addToSelection(rangeIds);
+        }
+      } else {
+        const newSet = new Set<string>();
+        newSet.add(sample.id);
+        useStore.getState().setSelectedIds(newSet, "grid");
+      }
+    },
+    [samples, selectedIds, toggleSelection, addToSelection]
+  );
+
+  const virtualRows = virtualizer.getVirtualItems();
+
+  return (
+    <Panel>
+      <div className="flex-1 min-h-0 overflow-hidden">
+        <div ref={containerRef} className="panel-scroll h-full min-h-0 overflow-auto">
+          <div
+            style={{
+              height: containerHeight || "100%",
+              width: "100%",
+              position: "relative",
+            }}
+          >
+            {virtualRows.map((virtualRow) => {
+              const row = rows[virtualRow.index];
+              if (!row) return null;
+
+              const rowSamples = samples.slice(row.startIndex, row.endIndex);
+              const rowBoxes = boxes.slice(row.startIndex, row.endIndex);
+
+              return (
+                <div
+                  key={virtualRow.key}
+                  style={{
+                    position: "absolute",
+                    top: 0,
+                    left: 0,
+                    width: "100%",
+                    height: row.height,
+                    transform: `translateY(${row.top}px)`,
+                  }}
+                >
+                  {rowSamples.map((sample, i) => {
+                    const box = rowBoxes[i];
+                    if (!box) return null;
+
+                    const isSelected = isLassoSelection ? true : selectedIds.has(sample.id);
+                    const isHovered = hoveredId === sample.id;
+
+                    return (
+                      <div
+                        key={sample.id}
+                        style={{
+                          position: "absolute",
+                          left: box.left,
+                          top: 0,
+                          width: box.width,
+                          height: box.height,
+                        }}
+                        className={`
+                          overflow-hidden cursor-pointer
+                          transition-shadow duration-150 ease-out
+                          ${isSelected ? "ring-2 ring-inset ring-primary" : ""}
+                          ${isHovered && !isSelected ? "ring-2 ring-inset ring-primary/50" : ""}
+                        `}
+                        onClick={(e) => handleClick(sample, e)}
+                        onMouseEnter={() => setHoveredId(sample.id)}
+                        onMouseLeave={() => setHoveredId(null)}
+                      >
+                        {/* Image container - justified layout sizes tile to preserve aspect ratio */}
+                        {/* Future: overlays (segmentations, bboxes) will be absolutely positioned here */}
+                        {sample.thumbnail ? (
+                          // eslint-disable-next-line @next/next/no-img-element
+                          <img
+                            src={`data:image/jpeg;base64,${sample.thumbnail}`}
+                            alt={sample.filename}
+                            className="w-full h-full object-cover"
+                            loading="lazy"
+                          />
+                        ) : (
+                          <div className="w-full h-full bg-muted flex items-center justify-center">
+                            <span className="text-muted-foreground text-xs">No image</span>
+                          </div>
+                        )}
+
+                        {/* Label badge */}
+                        {sample.label && (
+                          <div className="absolute bottom-0.5 left-0.5 right-0.5">
+                            <span
+                              className="inline-block px-1 py-0.5 text-[10px] leading-tight truncate max-w-full"
+                              style={{
+                                backgroundColor: "rgba(0,0,0,0.7)",
+                                color: "#fff",
+                              }}
+                            >
+                              {sample.label}
+                            </span>
+                          </div>
+                        )}
+
+                        {/* Selection indicator */}
+                        {isSelected && (
+                          <div className="absolute top-0.5 right-0.5 w-4 h-4 rounded-full bg-primary flex items-center justify-center">
+                            <CheckIcon />
+                          </div>
+                        )}
+                      </div>
+                    );
+                  })}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </Panel>
+  );
+}

frontend/src/components/Panel.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+interface PanelProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Base panel container with consistent Rerun-style appearance.
+ * No borders or rounded corners - panels should be flush against each other.
+ */
+export function Panel({ children, className }: PanelProps) {
+  return (
+    <div className={cn(
+      "flex flex-col h-full bg-card overflow-hidden",
+      className
+    )}>
+      {children}
+    </div>
+  );
+}
+
+interface PanelFooterProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Panel footer for keyboard shortcuts/hints.
+ */
+export function PanelFooter({ children, className }: PanelFooterProps) {
+  return (
+    <div className={cn(
+      "px-3 py-1 text-[11px] text-muted-foreground/70 border-t border-border bg-card font-mono",
+      className
+    )}>
+      {children}
+    </div>
+  );
+}

frontend/src/components/PanelHeader.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+interface PanelHeaderProps {
+  icon?: ReactNode;
+  title: string;
+  subtitle?: string;
+  children?: ReactNode; // Toolbar actions slot
+  className?: string;
+}
+
+/**
+ * Rerun-style panel header with icon, title, and optional toolbar.
+ * 
+ * Design tokens (from Rerun):
+ * - Title bar height: 24px
+ * - Icon size: 14px (3.5 tailwind units)
+ * - Icon-to-text gap: 4px (gap-1)
+ * - Font size: 12px with -0.15px tracking
+ * - Section header font: 11px uppercase
+ */
+export function PanelHeader({ icon, title, subtitle, children, className }: PanelHeaderProps) {
+  return (
+    <div className={cn(
+      // 24px height matches Rerun's title_bar_height()
+      "h-6 min-h-[24px] flex items-center justify-between px-3 border-b border-border bg-secondary select-none",
+      className
+    )}>
+      <div className="flex items-center gap-1 min-w-0">
+        {icon && (
+          // 14px icon (3.5 tailwind units) with 4px gap to text
+          <span className="flex-shrink-0 w-3.5 h-3.5 text-muted-foreground">{icon}</span>
+        )}
+        {/* 12px font, medium weight, tight tracking */}
+        <span className="text-[12px] leading-[16px] font-medium tracking-[-0.15px] text-foreground truncate">{title}</span>
+        {subtitle && (
+          <span className="text-[11px] leading-4 text-muted-foreground truncate">{subtitle}</span>
+        )}
+      </div>
+      {children && (
+        <div className="flex items-center gap-1">{children}</div>
+      )}
+    </div>
+  );
+}

frontend/src/components/PlaceholderPanel.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import React from "react";
+import { HyperViewLogo } from "./icons";
+import { Panel } from "./Panel";
+import { cn } from "@/lib/utils";
+import { X } from "lucide-react";
+
+interface PlaceholderPanelProps {
+  className?: string;
+  onClose?: () => void;
+}
+
+/**
+ * Empty placeholder panel with centered HyperView logo and a close button.
+ * Used for right and bottom zones that are reserved for future features.
+ * The close button is always visible in the top-right corner of the panel content.
+ */
+export function PlaceholderPanel({ className, onClose }: PlaceholderPanelProps) {
+  return (
+    <Panel className={cn("h-full w-full relative", className)}>
+      {/* Close button always visible in top right */}
+      {onClose && (
+        <button
+          onClick={onClose}
+          className="absolute top-3 right-3 p-1.5 rounded-md text-muted-foreground/60 hover:text-muted-foreground hover:bg-muted/60 transition-colors z-10"
+          aria-label="Close panel"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      )}
+      <div className="flex-1 flex items-center justify-center">
+        <div className="text-muted-foreground/20">
+          <HyperViewLogo className="w-12 h-12" />
+        </div>
+      </div>
+    </Panel>
+  );
+}

frontend/src/components/ScatterPanel.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useStore } from "@/store/useStore";
+import { Panel } from "./Panel";
+import { useHyperScatter } from "./useHyperScatter";
+import { useLabelLegend } from "./useLabelLegend";
+import type { Geometry } from "@/types";
+import { findLayoutByGeometry, listAvailableGeometries } from "@/lib/layouts";
+import { fetchEmbeddings } from "@/lib/api";
+
+interface ScatterPanelProps {
+  className?: string;
+  layoutKey?: string;
+  geometry?: Geometry;
+}
+
+export function ScatterPanel({
+  className = "",
+  layoutKey,
+  geometry,
+}: ScatterPanelProps) {
+  const {
+    datasetInfo,
+    embeddingsByLayoutKey,
+    setEmbeddingsForLayout,
+    selectedIds,
+    setSelectedIds,
+    beginLassoSelection,
+    hoveredId,
+    setHoveredId,
+    setActiveLayoutKey,
+    labelFilter,
+  } = useStore();
+
+  const [localGeometry, setLocalGeometry] = useState<Geometry>("euclidean");
+
+  // Check which geometries are available
+  const availableGeometries = useMemo(() => {
+    return listAvailableGeometries(datasetInfo?.layouts ?? []);
+  }, [datasetInfo?.layouts]);
+
+  useEffect(() => {
+    if (geometry) return;
+    if (availableGeometries.length === 0) return;
+    if (!availableGeometries.includes(localGeometry)) {
+      setLocalGeometry(availableGeometries[0]);
+    }
+  }, [availableGeometries, geometry, localGeometry]);
+
+  const resolvedGeometry = geometry ?? localGeometry;
+
+  const resolvedLayoutKey = useMemo(() => {
+    if (!datasetInfo) return layoutKey ?? null;
+
+    if (layoutKey) {
+      const exists = datasetInfo.layouts.some((layout) => layout.layout_key === layoutKey);
+      if (exists) return layoutKey;
+    }
+
+    const layout = findLayoutByGeometry(datasetInfo.layouts, resolvedGeometry);
+    return layout?.layout_key ?? datasetInfo.layouts[0]?.layout_key ?? null;
+  }, [datasetInfo, layoutKey, resolvedGeometry]);
+
+  const embeddings = resolvedLayoutKey ? embeddingsByLayoutKey[resolvedLayoutKey] ?? null : null;
+
+  useEffect(() => {
+    if (!resolvedLayoutKey) return;
+    setActiveLayoutKey(resolvedLayoutKey);
+  }, [resolvedLayoutKey, setActiveLayoutKey]);
+
+  useEffect(() => {
+    if (!resolvedLayoutKey) return;
+    if (embeddingsByLayoutKey[resolvedLayoutKey]) return;
+
+    let cancelled = false;
+
+    fetchEmbeddings(resolvedLayoutKey)
+      .then((data) => {
+        if (cancelled) return;
+        setEmbeddingsForLayout(resolvedLayoutKey, data);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error("Failed to load embeddings:", err);
+      })
+
+    return () => {
+      cancelled = true;
+    };
+  }, [embeddingsByLayoutKey, resolvedLayoutKey, setEmbeddingsForLayout]);
+
+  const { labelsInfo } = useLabelLegend({ datasetInfo, embeddings, labelFilter });
+
+  const {
+    canvasRef,
+    overlayCanvasRef,
+    containerRef,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handlePointerLeave,
+    handleDoubleClick,
+    rendererError,
+  } = useHyperScatter({
+    embeddings,
+    labelsInfo,
+    selectedIds,
+    hoveredId,
+    setSelectedIds,
+    beginLassoSelection,
+    setHoveredId,
+    hoverEnabled: !labelFilter,
+  });
+
+  const focusLayout = useCallback(() => {
+    if (!resolvedLayoutKey) return;
+    setActiveLayoutKey(resolvedLayoutKey);
+  }, [resolvedLayoutKey, setActiveLayoutKey]);
+
+  const loadingLabel = resolvedLayoutKey
+    ? "Loading embeddings..."
+    : "No embeddings layout available";
+
+  return (
+    <Panel className={className}>
+      {/* Main content area - min-h-0 prevents flex overflow */}
+      <div className="flex-1 flex min-h-0">
+        {/* Canvas container */}
+        <div ref={containerRef} className="flex-1 relative min-w-0">
+          <canvas
+            ref={canvasRef}
+            className="absolute inset-0"
+            style={{ zIndex: 1 }}
+            onPointerDown={(e) => {
+              focusLayout();
+              handlePointerDown(e);
+            }}
+            onPointerMove={handlePointerMove}
+            onPointerUp={handlePointerUp}
+            onPointerCancel={handlePointerUp}
+            onPointerLeave={handlePointerLeave}
+            onDoubleClick={handleDoubleClick}
+            onPointerEnter={focusLayout}
+          />
+
+          {/* Lasso overlay (screen-space) */}
+          <canvas
+            ref={overlayCanvasRef}
+            className="absolute inset-0 pointer-events-none"
+            style={{ zIndex: 20 }}
+          />
+
+          {/* Loading overlay */}
+          {rendererError ? (
+            <div className="absolute inset-0 flex items-center justify-center bg-card/85 z-10 p-6">
+              <div className="max-w-md text-center">
+                <div className="text-sm font-semibold text-foreground mb-2">Browser not supported</div>
+                <div className="text-sm text-muted-foreground">{rendererError}</div>
+              </div>
+            </div>
+          ) : (
+            !embeddings && (
+              <div className="absolute inset-0 flex items-center justify-center bg-card/80 z-10">
+                <div className="text-muted-foreground">{loadingLabel}</div>
+              </div>
+            )
+          )}
+        </div>
+
+      </div>
+    </Panel>
+  );
+}

frontend/src/components/icons.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * Shared icons for HyperView UI.
+ * Using inline SVGs for simplicity (no extra icon library dependency).
+ */
+
+export const GridIcon = () => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="w-4 h-4">
+    <rect x="3" y="3" width="7" height="7" />
+    <rect x="14" y="3" width="7" height="7" />
+    <rect x="3" y="14" width="7" height="7" />
+    <rect x="14" y="14" width="7" height="7" />
+  </svg>
+);
+
+export const ScatterIcon = () => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" className="w-4 h-4">
+    <circle cx="8" cy="8" r="2" />
+    <circle cx="16" cy="16" r="2" />
+    <circle cx="18" cy="8" r="2" />
+    <circle cx="6" cy="16" r="2" />
+    <circle cx="12" cy="12" r="2" />
+  </svg>
+);
+
+export const HyperViewLogo = ({ className = "w-5 h-5" }: { className?: string }) => (
+  <svg viewBox="0 0 24 24" fill="none" className={className}>
+    <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="1.5" />
+    <circle cx="12" cy="12" r="6" stroke="currentColor" strokeWidth="1.5" opacity="0.6" />
+    <circle cx="12" cy="12" r="2" fill="currentColor" />
+  </svg>
+);
+
+export const CheckIcon = () => (
+  <svg className="w-3 h-3 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M5 13l4 4L19 7" />
+  </svg>
+);
+
+/** Euclidean geometry icon - flat grid */
+export const EuclideanIcon = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.25" className="w-3.5 h-3.5">
+    <rect x="2" y="2" width="12" height="12" rx="1" />
+    <line x1="2" y1="8" x2="14" y2="8" />
+    <line x1="8" y1="2" x2="8" y2="14" />
+  </svg>
+);
+
+/** Poincaré disk icon - hyperbolic geometry */
+export const PoincareIcon = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.25" className="w-3.5 h-3.5">
+    <circle cx="8" cy="8" r="6" />
+    <ellipse cx="8" cy="8" rx="3" ry="5.5" />
+    <ellipse cx="8" cy="8" rx="5.5" ry="3" />
+  </svg>
+);
+
+/** Spherical geometry icon - for future use */
+export const SphericalIcon = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.25" className="w-3.5 h-3.5">
+    <circle cx="8" cy="8" r="6" />
+    <ellipse cx="8" cy="8" rx="6" ry="2.5" />
+    <path d="M8 2 Q12 8 8 14" />
+  </svg>
+);
+
+/** Discord icon - official simplified logo */
+export const DiscordIcon = ({ className = "w-4 h-4" }: { className?: string }) => (
+  <svg viewBox="0 0 24 24" fill="currentColor" className={className}>
+    <path d="M19.27 5.33C17.94 4.71 16.5 4.26 15 4a.09.09 0 0 0-.07.03c-.18.33-.39.76-.53 1.09a16.09 16.09 0 0 0-4.8 0c-.14-.34-.35-.76-.54-1.09c-.01-.02-.04-.03-.07-.03c-1.5.26-2.93.71-4.27 1.33c-.01 0-.02.01-.03.02c-2.72 4.07-3.47 8.03-3.1 11.95c0 .02.01.04.03.05c1.8 1.32 3.53 2.12 5.24 2.65c.03.01.06 0 .07-.02c.4-.55.76-1.13 1.07-1.74c.02-.04 0-.08-.04-.09c-.57-.22-1.11-.48-1.64-.78c-.04-.02-.04-.08-.01-.11c.11-.08.22-.17.33-.25c.02-.02.05-.02.07-.01c3.44 1.57 7.15 1.57 10.55 0c.02-.01.05-.01.07.01c.11.09.22.17.33.26c.04.03.04.09-.01.11c-.52.31-1.07.56-1.64.78c-.04.01-.05.06-.04.09c.32.61.68 1.19 1.07 1.74c.03.01.06.02.09.01c1.72-.53 3.45-1.33 5.25-2.65c.02-.01.03-.03.03-.05c.44-4.53-.73-8.46-3.1-11.95c-.01-.01-.02-.02-.04-.02zM8.52 14.91c-1.03 0-1.89-.95-1.89-2.12s.84-2.12 1.89-2.12c1.06 0 1.9.96 1.89 2.12c0 1.17-.84 2.12-1.89 2.12zm6.97 0c-1.03 0-1.89-.95-1.89-2.12s.84-2.12 1.89-2.12c1.06 0 1.9.96 1.89 2.12c0 1.17-.83 2.12-1.89 2.12z"/>
+  </svg>
+);

frontend/src/components/index.ts

@@ -0,0 +1,9 @@
+export { ImageGrid } from "./ImageGrid";
+export { ScatterPanel } from "./ScatterPanel";
+export { DockviewWorkspace } from "./DockviewWorkspace";
+export { Header } from "./Header";
+export { Panel, PanelFooter } from "./Panel";
+export { PanelHeader } from "./PanelHeader";
+export { ExplorerPanel } from "./ExplorerPanel";
+export { PlaceholderPanel } from "./PlaceholderPanel";
+export * from "./icons";

frontend/src/components/ui/button.tsx

@@ -0,0 +1,57 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

frontend/src/components/ui/collapsible.tsx

@@ -0,0 +1,11 @@
+"use client"
+
+import * as CollapsiblePrimitive from "@radix-ui/react-collapsible"
+
+const Collapsible = CollapsiblePrimitive.Root
+
+const CollapsibleTrigger = CollapsiblePrimitive.CollapsibleTrigger
+
+const CollapsibleContent = CollapsiblePrimitive.CollapsibleContent
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent }

frontend/src/components/ui/command.tsx

@@ -0,0 +1,153 @@
+"use client"
+
+import * as React from "react"
+import { type DialogProps } from "@radix-ui/react-dialog"
+import { Command as CommandPrimitive } from "cmdk"
+import { Search } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+import { Dialog, DialogContent } from "@/components/ui/dialog"
+
+const Command = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive
+    ref={ref}
+    className={cn(
+      "flex h-full w-full flex-col overflow-hidden rounded-md bg-popover text-popover-foreground",
+      className
+    )}
+    {...props}
+  />
+))
+Command.displayName = CommandPrimitive.displayName
+
+const CommandDialog = ({ children, ...props }: DialogProps) => {
+  return (
+    <Dialog {...props}>
+      <DialogContent className="overflow-hidden p-0">
+        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+          {children}
+        </Command>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+const CommandInput = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Input>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
+>(({ className, ...props }, ref) => (
+  <div className="flex items-center border-b px-3" cmdk-input-wrapper="">
+    <Search className="mr-2 h-4 w-4 shrink-0 opacity-50" />
+    <CommandPrimitive.Input
+      ref={ref}
+      className={cn(
+        "flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  </div>
+))
+
+CommandInput.displayName = CommandPrimitive.Input.displayName
+
+const CommandList = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.List
+    ref={ref}
+    className={cn("max-h-[300px] overflow-y-auto overflow-x-hidden", className)}
+    {...props}
+  />
+))
+
+CommandList.displayName = CommandPrimitive.List.displayName
+
+const CommandEmpty = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Empty>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Empty>
+>((props, ref) => (
+  <CommandPrimitive.Empty
+    ref={ref}
+    className="py-6 text-center text-sm"
+    {...props}
+  />
+))
+
+CommandEmpty.displayName = CommandPrimitive.Empty.displayName
+
+const CommandGroup = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Group>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Group>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Group
+    ref={ref}
+    className={cn(
+      "overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground",
+      className
+    )}
+    {...props}
+  />
+))
+
+CommandGroup.displayName = CommandPrimitive.Group.displayName
+
+const CommandSeparator = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Separator
+    ref={ref}
+    className={cn("-mx-1 h-px bg-border", className)}
+    {...props}
+  />
+))
+CommandSeparator.displayName = CommandPrimitive.Separator.displayName
+
+const CommandItem = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Item
+    ref={ref}
+    className={cn(
+      "relative flex cursor-default gap-2 select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      className
+    )}
+    {...props}
+  />
+))
+
+CommandItem.displayName = CommandPrimitive.Item.displayName
+
+const CommandShortcut = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) => {
+  return (
+    <span
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+CommandShortcut.displayName = "CommandShortcut"
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+}

frontend/src/components/ui/dialog.tsx

@@ -0,0 +1,122 @@
+"use client"
+
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { X } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+const Dialog = DialogPrimitive.Root
+
+const DialogTrigger = DialogPrimitive.Trigger
+
+const DialogPortal = DialogPrimitive.Portal
+
+const DialogClose = DialogPrimitive.Close
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/80  data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    )}
+    {...props}
+  />
+))
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DialogPortal>
+))
+DialogContent.displayName = DialogPrimitive.Content.displayName
+
+const DialogHeader = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col space-y-1.5 text-center sm:text-left",
+      className
+    )}
+    {...props}
+  />
+)
+DialogHeader.displayName = "DialogHeader"
+
+const DialogFooter = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+      className
+    )}
+    {...props}
+  />
+)
+DialogFooter.displayName = "DialogFooter"
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "text-lg font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+))
+DialogTitle.displayName = DialogPrimitive.Title.displayName
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+DialogDescription.displayName = DialogPrimitive.Description.displayName
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogTrigger,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+}

frontend/src/components/ui/dropdown-menu.tsx

@@ -0,0 +1,201 @@
+"use client"
+
+import * as React from "react"
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu"
+import { Check, ChevronRight, Circle } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+const DropdownMenu = DropdownMenuPrimitive.Root
+
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
+
+const DropdownMenuGroup = DropdownMenuPrimitive.Group
+
+const DropdownMenuPortal = DropdownMenuPrimitive.Portal
+
+const DropdownMenuSub = DropdownMenuPrimitive.Sub
+
+const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup
+
+const DropdownMenuSubTrigger = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubTrigger>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubTrigger> & {
+    inset?: boolean
+  }
+>(({ className, inset, children, ...props }, ref) => (
+  <DropdownMenuPrimitive.SubTrigger
+    ref={ref}
+    className={cn(
+      "flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent data-[state=open]:bg-accent [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      inset && "pl-8",
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto" />
+  </DropdownMenuPrimitive.SubTrigger>
+))
+DropdownMenuSubTrigger.displayName =
+  DropdownMenuPrimitive.SubTrigger.displayName
+
+const DropdownMenuSubContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.SubContent
+    ref={ref}
+    className={cn(
+      "z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-dropdown-menu-content-transform-origin]",
+      className
+    )}
+    {...props}
+  />
+))
+DropdownMenuSubContent.displayName =
+  DropdownMenuPrimitive.SubContent.displayName
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 max-h-[var(--radix-dropdown-menu-content-available-height)] min-w-[8rem] overflow-y-auto overflow-x-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-dropdown-menu-content-transform-origin]",
+        className
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+))
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
+
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean
+  }
+>(({ className, inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0",
+      inset && "pl-8",
+      className
+    )}
+    {...props}
+  />
+))
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName
+
+const DropdownMenuCheckboxItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.CheckboxItem>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.CheckboxItem>
+>(({ className, children, checked, ...props }, ref) => (
+  <DropdownMenuPrimitive.CheckboxItem
+    ref={ref}
+    className={cn(
+      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className
+    )}
+    checked={checked}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.CheckboxItem>
+))
+DropdownMenuCheckboxItem.displayName =
+  DropdownMenuPrimitive.CheckboxItem.displayName
+
+const DropdownMenuRadioItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.RadioItem>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.RadioItem>
+>(({ className, children, ...props }, ref) => (
+  <DropdownMenuPrimitive.RadioItem
+    ref={ref}
+    className={cn(
+      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Circle className="h-2 w-2 fill-current" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.RadioItem>
+))
+DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName
+
+const DropdownMenuLabel = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Label>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Label> & {
+    inset?: boolean
+  }
+>(({ className, inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Label
+    ref={ref}
+    className={cn(
+      "px-2 py-1.5 text-sm font-semibold",
+      inset && "pl-8",
+      className
+    )}
+    {...props}
+  />
+))
+DropdownMenuLabel.displayName = DropdownMenuPrimitive.Label.displayName
+
+const DropdownMenuSeparator = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.Separator
+    ref={ref}
+    className={cn("-mx-1 my-1 h-px bg-muted", className)}
+    {...props}
+  />
+))
+DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName
+
+const DropdownMenuShortcut = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) => {
+  return (
+    <span
+      className={cn("ml-auto text-xs tracking-widest opacity-60", className)}
+      {...props}
+    />
+  )
+}
+DropdownMenuShortcut.displayName = "DropdownMenuShortcut"
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+}

frontend/src/components/ui/popover.tsx

@@ -0,0 +1,33 @@
+"use client"
+
+import * as React from "react"
+import * as PopoverPrimitive from "@radix-ui/react-popover"
+
+import { cn } from "@/lib/utils"
+
+const Popover = PopoverPrimitive.Root
+
+const PopoverTrigger = PopoverPrimitive.Trigger
+
+const PopoverAnchor = PopoverPrimitive.Anchor
+
+const PopoverContent = React.forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
+>(({ className, align = "center", sideOffset = 4, ...props }, ref) => (
+  <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-popover-content-transform-origin]",
+        className
+      )}
+      {...props}
+    />
+  </PopoverPrimitive.Portal>
+))
+PopoverContent.displayName = PopoverPrimitive.Content.displayName
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor }

frontend/src/components/ui/radio-group.tsx

@@ -0,0 +1,44 @@
+"use client"
+
+import * as React from "react"
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
+import { Circle } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+const RadioGroup = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
+>(({ className, ...props }, ref) => {
+  return (
+    <RadioGroupPrimitive.Root
+      className={cn("grid gap-2", className)}
+      {...props}
+      ref={ref}
+    />
+  )
+})
+RadioGroup.displayName = RadioGroupPrimitive.Root.displayName
+
+const RadioGroupItem = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
+>(({ className, ...props }, ref) => {
+  return (
+    <RadioGroupPrimitive.Item
+      ref={ref}
+      className={cn(
+        "aspect-square h-4 w-4 rounded-full border border-primary text-primary shadow focus:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
+        <Circle className="h-3.5 w-3.5 fill-primary" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  )
+})
+RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName
+
+export { RadioGroup, RadioGroupItem }

frontend/src/components/ui/scroll-area.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import * as React from "react"
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"
+
+import { cn } from "@/lib/utils"
+
+const ScrollArea = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(({ className, children, ...props }, ref) => (
+  <ScrollAreaPrimitive.Root
+    ref={ref}
+    className={cn("relative overflow-hidden", className)}
+    {...props}
+  >
+    <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]">
+      {children}
+    </ScrollAreaPrimitive.Viewport>
+    <ScrollBar />
+    <ScrollAreaPrimitive.Corner />
+  </ScrollAreaPrimitive.Root>
+))
+ScrollArea.displayName = ScrollAreaPrimitive.Root.displayName
+
+const ScrollBar = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(({ className, orientation = "vertical", ...props }, ref) => (
+  <ScrollAreaPrimitive.ScrollAreaScrollbar
+    ref={ref}
+    orientation={orientation}
+    className={cn(
+      "flex touch-none select-none transition-colors",
+      // Rerun style: 6px bar width, 2px inner/outer margin
+      orientation === "vertical" &&
+        "h-full w-[10px] border-l border-l-transparent p-[2px]",
+      orientation === "horizontal" &&
+        "h-[10px] flex-col border-t border-t-transparent p-[2px]",
+      className
+    )}
+    {...props}
+  >
+    <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-[3px] bg-muted-foreground/25 hover:bg-muted-foreground/40" />
+  </ScrollAreaPrimitive.ScrollAreaScrollbar>
+))
+ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName
+
+export { ScrollArea, ScrollBar }

frontend/src/components/ui/separator.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+import * as SeparatorPrimitive from "@radix-ui/react-separator"
+
+import { cn } from "@/lib/utils"
+
+const Separator = React.forwardRef<
+  React.ElementRef<typeof SeparatorPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>
+>(
+  (
+    { className, orientation = "horizontal", decorative = true, ...props },
+    ref
+  ) => (
+    <SeparatorPrimitive.Root
+      ref={ref}
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border",
+        orientation === "horizontal" ? "h-[1px] w-full" : "h-full w-[1px]",
+        className
+      )}
+      {...props}
+    />
+  )
+)
+Separator.displayName = SeparatorPrimitive.Root.displayName
+
+export { Separator }

frontend/src/components/ui/toggle-group.tsx

@@ -0,0 +1,61 @@
+"use client"
+
+import * as React from "react"
+import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group"
+import { type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { toggleVariants } from "@/components/ui/toggle"
+
+const ToggleGroupContext = React.createContext<
+  VariantProps<typeof toggleVariants>
+>({
+  size: "default",
+  variant: "default",
+})
+
+const ToggleGroup = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root> &
+    VariantProps<typeof toggleVariants>
+>(({ className, variant, size, children, ...props }, ref) => (
+  <ToggleGroupPrimitive.Root
+    ref={ref}
+    className={cn("flex items-center justify-center gap-1", className)}
+    {...props}
+  >
+    <ToggleGroupContext.Provider value={{ variant, size }}>
+      {children}
+    </ToggleGroupContext.Provider>
+  </ToggleGroupPrimitive.Root>
+))
+
+ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName
+
+const ToggleGroupItem = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> &
+    VariantProps<typeof toggleVariants>
+>(({ className, children, variant, size, ...props }, ref) => {
+  const context = React.useContext(ToggleGroupContext)
+
+  return (
+    <ToggleGroupPrimitive.Item
+      ref={ref}
+      className={cn(
+        toggleVariants({
+          variant: context.variant || variant,
+          size: context.size || size,
+        }),
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </ToggleGroupPrimitive.Item>
+  )
+})
+
+ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName
+
+export { ToggleGroup, ToggleGroupItem }

frontend/src/components/ui/toggle.tsx

@@ -0,0 +1,45 @@
+"use client"
+
+import * as React from "react"
+import * as TogglePrimitive from "@radix-ui/react-toggle"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const toggleVariants = cva(
+  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-primary data-[state=on]:text-primary-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline:
+          "border border-input bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground data-[state=on]:border-primary",
+      },
+      size: {
+        default: "h-9 px-2 min-w-9",
+        sm: "h-8 px-1.5 min-w-8",
+        lg: "h-10 px-2.5 min-w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+const Toggle = React.forwardRef<
+  React.ElementRef<typeof TogglePrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root> &
+    VariantProps<typeof toggleVariants>
+>(({ className, variant, size, ...props }, ref) => (
+  <TogglePrimitive.Root
+    ref={ref}
+    className={cn(toggleVariants({ variant, size, className }))}
+    {...props}
+  />
+))
+
+Toggle.displayName = TogglePrimitive.Root.displayName
+
+export { Toggle, toggleVariants }

frontend/src/components/ui/tooltip.tsx

@@ -0,0 +1,32 @@
+"use client"
+
+import * as React from "react"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+
+import { cn } from "@/lib/utils"
+
+const TooltipProvider = TooltipPrimitive.Provider
+
+const Tooltip = TooltipPrimitive.Root
+
+const TooltipTrigger = TooltipPrimitive.Trigger
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 overflow-hidden rounded-md bg-primary px-3 py-1.5 text-xs text-primary-foreground animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-tooltip-content-transform-origin]",
+        className
+      )}
+      {...props}
+    />
+  </TooltipPrimitive.Portal>
+))
+TooltipContent.displayName = TooltipPrimitive.Content.displayName
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

frontend/src/components/useHyperScatter.ts

@@ -0,0 +1,614 @@
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import type { EmbeddingsData } from "@/types";
+import type { ScatterLabelsInfo } from "@/lib/labelLegend";
+import type { Dataset, GeometryMode, Modifiers, Renderer } from "hyper-scatter";
+
+type HyperScatterModule = typeof import("hyper-scatter");
+
+const MAX_LASSO_VERTS = 512;
+
+function supportsWebGL2(): boolean {
+  try {
+    if (typeof document === "undefined") return false;
+    const canvas = document.createElement("canvas");
+    return !!canvas.getContext("webgl2");
+  } catch {
+    return false;
+  }
+}
+
+function capInterleavedXY(points: ArrayLike<number>, maxVerts: number): number[] {
+  const n = Math.floor(points.length / 2);
+  if (n <= maxVerts) return Array.from(points as ArrayLike<number>);
+
+  const out = new Array<number>(maxVerts * 2);
+  for (let i = 0; i < maxVerts; i++) {
+    const src = Math.floor((i * n) / maxVerts);
+    out[i * 2] = points[src * 2];
+    out[i * 2 + 1] = points[src * 2 + 1];
+  }
+  return out;
+}
+
+
+interface UseHyperScatterArgs {
+  embeddings: EmbeddingsData | null;
+  labelsInfo: ScatterLabelsInfo | null;
+  selectedIds: Set<string>;
+  hoveredId: string | null;
+  setSelectedIds: (ids: Set<string>, source?: "scatter" | "grid") => void;
+  beginLassoSelection: (query: { layoutKey: string; polygon: number[] }) => void;
+  setHoveredId: (id: string | null) => void;
+  hoverEnabled?: boolean;
+}
+
+function toModifiers(e: { shiftKey: boolean; ctrlKey: boolean; altKey: boolean; metaKey: boolean }): Modifiers {
+  return {
+    shift: e.shiftKey,
+    ctrl: e.ctrlKey,
+    alt: e.altKey,
+    meta: e.metaKey,
+  };
+}
+
+function clearOverlay(canvas: HTMLCanvasElement | null): void {
+  if (!canvas) return;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+}
+
+function drawLassoOverlay(canvas: HTMLCanvasElement | null, points: number[]): void {
+  if (!canvas) return;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+
+  clearOverlay(canvas);
+  if (points.length < 6) return;
+
+  ctx.save();
+  ctx.lineWidth = 2;
+  ctx.strokeStyle = "rgba(79,70,229,0.9)"; // indigo-ish
+  ctx.fillStyle = "rgba(79,70,229,0.15)";
+
+  ctx.beginPath();
+  ctx.moveTo(points[0], points[1]);
+  for (let i = 2; i < points.length; i += 2) {
+    ctx.lineTo(points[i], points[i + 1]);
+  }
+  ctx.closePath();
+  ctx.fill();
+  ctx.stroke();
+  ctx.restore();
+}
+
+export function useHyperScatter({
+  embeddings,
+  labelsInfo,
+  selectedIds,
+  hoveredId,
+  setSelectedIds,
+  beginLassoSelection,
+  setHoveredId,
+  hoverEnabled = true,
+}: UseHyperScatterArgs) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const overlayCanvasRef = useRef<HTMLCanvasElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const rendererRef = useRef<Renderer | null>(null);
+
+  const [rendererError, setRendererError] = useState<string | null>(null);
+
+  const rafPendingRef = useRef(false);
+
+  // Interaction state (refs to avoid rerender churn)
+  const isPanningRef = useRef(false);
+  const isLassoingRef = useRef(false);
+  const pointerDownXRef = useRef(0);
+  const pointerDownYRef = useRef(0);
+  const lastPointerXRef = useRef(0);
+  const lastPointerYRef = useRef(0);
+  const lassoPointsRef = useRef<number[]>([]);
+  const persistentLassoRef = useRef<number[] | null>(null);
+
+  const hoveredIndexRef = useRef<number>(-1);
+
+  const idToIndex = useMemo(() => {
+    if (!embeddings) return null;
+    const m = new Map<string, number>();
+    for (let i = 0; i < embeddings.ids.length; i++) {
+      m.set(embeddings.ids[i], i);
+    }
+    return m;
+  }, [embeddings]);
+
+  const requestRender = useCallback(() => {
+    if (rafPendingRef.current) return;
+    rafPendingRef.current = true;
+
+    requestAnimationFrame(() => {
+      rafPendingRef.current = false;
+      const renderer = rendererRef.current;
+      if (!renderer) return;
+
+      try {
+        renderer.render();
+      } catch (err) {
+        // Avoid an exception storm that would permanently prevent the UI from updating.
+        console.error("hyper-scatter renderer.render() failed:", err);
+        try {
+          renderer.destroy();
+        } catch {
+          // ignore
+        }
+        rendererRef.current = null;
+        setRendererError(
+          "This browser can't render the scatter plot (WebGL2 is required). Please use Chrome/Edge/Firefox."
+        );
+        clearOverlay(overlayCanvasRef.current);
+        return;
+      }
+
+      if (isLassoingRef.current) {
+        drawLassoOverlay(overlayCanvasRef.current, lassoPointsRef.current);
+      }
+    });
+  }, []);
+
+  const getCanvasPos = useCallback((e: { clientX: number; clientY: number }) => {
+    const canvas = canvasRef.current;
+    if (!canvas) return { x: 0, y: 0 };
+    const rect = canvas.getBoundingClientRect();
+    return {
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top,
+    };
+  }, []);
+
+  const redrawOverlay = useCallback(() => {
+    if (!overlayCanvasRef.current) return;
+    clearOverlay(overlayCanvasRef.current);
+    const persistent = persistentLassoRef.current;
+    if (persistent && persistent.length >= 6) {
+      drawLassoOverlay(overlayCanvasRef.current, persistent);
+    }
+  }, []);
+
+  const clearPersistentLasso = useCallback(() => {
+    persistentLassoRef.current = null;
+    clearOverlay(overlayCanvasRef.current);
+  }, []);
+
+  const stopInteraction = useCallback(() => {
+    isPanningRef.current = false;
+    isLassoingRef.current = false;
+    lassoPointsRef.current = [];
+    if (persistentLassoRef.current) {
+      redrawOverlay();
+      return;
+    }
+    clearOverlay(overlayCanvasRef.current);
+  }, [redrawOverlay]);
+
+  // Initialize renderer when embeddings change.
+  useEffect(() => {
+    if (!embeddings || !labelsInfo) return;
+    if (!canvasRef.current || !containerRef.current) return;
+
+    let cancelled = false;
+
+    const init = async () => {
+      // Clear any previous renderer errors when we attempt to re-init.
+      setRendererError(null);
+
+      if (!supportsWebGL2()) {
+        setRendererError(
+          "This browser doesn't support WebGL2, so the scatter plot can't be displayed. Please use Chrome/Edge/Firefox."
+        );
+        return;
+      }
+
+      try {
+        const viz = (await import("hyper-scatter")) as HyperScatterModule;
+        if (cancelled) return;
+
+        const container = containerRef.current;
+        const canvas = canvasRef.current;
+        if (!container || !canvas) return;
+
+        // Destroy existing renderer (if any)
+        if (rendererRef.current) {
+          rendererRef.current.destroy();
+          rendererRef.current = null;
+        }
+
+        const rect = container.getBoundingClientRect();
+        const width = Math.floor(rect.width);
+        const height = Math.floor(rect.height);
+        if (overlayCanvasRef.current) {
+          overlayCanvasRef.current.width = Math.max(1, width);
+          overlayCanvasRef.current.height = Math.max(1, height);
+          overlayCanvasRef.current.style.width = `${width}px`;
+          overlayCanvasRef.current.style.height = `${height}px`;
+          redrawOverlay();
+        }
+
+        // Use coords from embeddings response directly
+        const coords = embeddings.coords;
+        const positions = new Float32Array(coords.length * 2);
+        for (let i = 0; i < coords.length; i++) {
+          positions[i * 2] = coords[i][0];
+          positions[i * 2 + 1] = coords[i][1];
+        }
+
+        const geometry = embeddings.geometry as GeometryMode;
+        const dataset: Dataset = viz.createDataset(geometry, positions, labelsInfo.categories);
+
+        const opts = {
+          width,
+          height,
+          devicePixelRatio: window.devicePixelRatio,
+          pointRadius: 4,
+          colors: labelsInfo.palette,
+          backgroundColor: "#161b22", // Match HyperView theme: --card is #161b22
+        };
+
+        const renderer: Renderer =
+          geometry === "euclidean" ? new viz.EuclideanWebGLCandidate() : new viz.HyperbolicWebGLCandidate();
+
+        renderer.init(canvas, opts);
+
+        renderer.setDataset(dataset);
+        rendererRef.current = renderer;
+
+        // Force a first render to surface WebGL2 context creation failures early.
+        try {
+          renderer.render();
+        } catch (err) {
+          console.error("hyper-scatter initial render failed:", err);
+          rendererRef.current = null;
+          try {
+            renderer.destroy();
+          } catch {
+            // ignore
+          }
+          setRendererError(
+            "This browser can't render the scatter plot (WebGL2 is required). Please use Chrome/Edge/Firefox."
+          );
+          return;
+        }
+
+        hoveredIndexRef.current = -1;
+        renderer.setHovered(-1);
+
+        requestRender();
+      } catch (err) {
+        console.error("Failed to initialize hyper-scatter renderer:", err);
+        setRendererError(
+          "Failed to initialize the scatter renderer in this browser. Please use Chrome/Edge/Firefox."
+        );
+      }
+    };
+
+    init();
+
+    return () => {
+      cancelled = true;
+      stopInteraction();
+      if (rendererRef.current) {
+        rendererRef.current.destroy();
+        rendererRef.current = null;
+      }
+    };
+  }, [embeddings, labelsInfo, redrawOverlay, requestRender, stopInteraction]);
+
+  // Store -> renderer sync
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !embeddings || !idToIndex) return;
+
+    const indices = new Set<number>();
+    for (const id of selectedIds) {
+      const idx = idToIndex.get(id);
+      if (typeof idx === "number") indices.add(idx);
+    }
+
+    renderer.setSelection(indices);
+
+    if (!hoverEnabled) {
+      renderer.setHovered(-1);
+      hoveredIndexRef.current = -1;
+      requestRender();
+      return;
+    }
+
+    const hoveredIdx = hoveredId ? (idToIndex.get(hoveredId) ?? -1) : -1;
+    renderer.setHovered(hoveredIdx);
+    hoveredIndexRef.current = hoveredIdx;
+
+    requestRender();
+  }, [embeddings, hoveredId, hoverEnabled, idToIndex, requestRender, selectedIds]);
+
+  // Resize handling
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const resize = () => {
+      const rect = container.getBoundingClientRect();
+      const width = Math.floor(rect.width);
+      const height = Math.floor(rect.height);
+      if (!(width > 0) || !(height > 0)) return;
+
+      if (overlayCanvasRef.current) {
+        overlayCanvasRef.current.width = Math.max(1, width);
+        overlayCanvasRef.current.height = Math.max(1, height);
+        overlayCanvasRef.current.style.width = `${width}px`;
+        overlayCanvasRef.current.style.height = `${height}px`;
+        redrawOverlay();
+      }
+
+      const renderer = rendererRef.current;
+      if (renderer) {
+        renderer.resize(width, height);
+        requestRender();
+      }
+    };
+
+    resize();
+
+    const ro = new ResizeObserver(resize);
+    ro.observe(container);
+    return () => ro.disconnect();
+  }, [redrawOverlay, requestRender]);
+
+  // Wheel zoom (native listener so we can set passive:false)
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const onWheel = (e: WheelEvent) => {
+      const renderer = rendererRef.current;
+      if (!renderer) return;
+      e.preventDefault();
+
+      const pos = getCanvasPos(e);
+      const delta = -e.deltaY / 100;
+      renderer.zoom(pos.x, pos.y, delta, toModifiers(e));
+      requestRender();
+    };
+
+    canvas.addEventListener("wheel", onWheel, { passive: false });
+    return () => canvas.removeEventListener("wheel", onWheel);
+  }, [getCanvasPos, requestRender]);
+
+  // Pointer interactions
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent<HTMLCanvasElement>) => {
+      const renderer = rendererRef.current;
+      if (!renderer) return;
+
+      // Left button only
+      if (typeof e.button === "number" && e.button !== 0) return;
+
+      const pos = getCanvasPos(e);
+      pointerDownXRef.current = pos.x;
+      pointerDownYRef.current = pos.y;
+      lastPointerXRef.current = pos.x;
+      lastPointerYRef.current = pos.y;
+
+      if (persistentLassoRef.current) {
+        clearPersistentLasso();
+      }
+
+      // Shift-drag = lasso, otherwise pan.
+      if (e.shiftKey) {
+        isLassoingRef.current = true;
+        isPanningRef.current = false;
+        lassoPointsRef.current = [pos.x, pos.y];
+        drawLassoOverlay(overlayCanvasRef.current, lassoPointsRef.current);
+      } else {
+        isPanningRef.current = true;
+        isLassoingRef.current = false;
+      }
+
+      try {
+        e.currentTarget.setPointerCapture(e.pointerId);
+      } catch {
+        // ignore
+      }
+
+      e.preventDefault();
+    },
+    [clearPersistentLasso, getCanvasPos]
+  );
+
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent<HTMLCanvasElement>) => {
+      const renderer = rendererRef.current;
+      if (!renderer) return;
+
+      const pos = getCanvasPos(e);
+
+      if (isPanningRef.current) {
+        const dx = pos.x - lastPointerXRef.current;
+        const dy = pos.y - lastPointerYRef.current;
+        lastPointerXRef.current = pos.x;
+        lastPointerYRef.current = pos.y;
+
+        renderer.pan(dx, dy, toModifiers(e));
+        requestRender();
+        return;
+      }
+
+      if (isLassoingRef.current) {
+        const pts = lassoPointsRef.current;
+        const lastX = pts[pts.length - 2] ?? pos.x;
+        const lastY = pts[pts.length - 1] ?? pos.y;
+        const ddx = pos.x - lastX;
+        const ddy = pos.y - lastY;
+        const distSq = ddx * ddx + ddy * ddy;
+
+        // Sample at ~2px spacing
+        if (distSq >= 4) {
+          pts.push(pos.x, pos.y);
+          drawLassoOverlay(overlayCanvasRef.current, pts);
+        }
+        return;
+      }
+
+      if (!hoverEnabled) {
+        if (hoveredIndexRef.current !== -1) {
+          hoveredIndexRef.current = -1;
+          renderer.setHovered(-1);
+          requestRender();
+        }
+        return;
+      }
+
+      // Hover
+      const hit = renderer.hitTest(pos.x, pos.y);
+      const nextIndex = hit ? hit.index : -1;
+      if (nextIndex === hoveredIndexRef.current) return;
+      hoveredIndexRef.current = nextIndex;
+      renderer.setHovered(nextIndex);
+
+      if (!embeddings) return;
+      if (nextIndex >= 0 && nextIndex < embeddings.ids.length) {
+        setHoveredId(embeddings.ids[nextIndex]);
+      } else {
+        setHoveredId(null);
+      }
+
+      requestRender();
+    },
+    [embeddings, getCanvasPos, hoverEnabled, requestRender, setHoveredId]
+  );
+
+  const handlePointerUp = useCallback(
+    async (e: React.PointerEvent<HTMLCanvasElement>) => {
+      const renderer = rendererRef.current;
+      if (!renderer || !embeddings) {
+        stopInteraction();
+        return;
+      }
+
+      if (isLassoingRef.current) {
+        const pts = lassoPointsRef.current.slice();
+        persistentLassoRef.current = pts.length >= 6 ? pts : null;
+        stopInteraction();
+        redrawOverlay();
+
+        if (pts.length >= 6) {
+          try {
+            const polyline = new Float32Array(pts);
+            const result = renderer.lassoSelect(polyline);
+
+            // Enter server-driven lasso mode by sending a data-space polygon.
+            // Backend selection runs in the same coordinate system returned by /api/embeddings.
+            const dataCoords = result.geometry?.coords;
+            if (!dataCoords || dataCoords.length < 6) return;
+
+            // Clear any existing manual selection highlights immediately.
+            renderer.setSelection(new Set());
+
+            // Cap vertex count to keep request payload + backend runtime bounded.
+            const polygon = capInterleavedXY(dataCoords, MAX_LASSO_VERTS);
+            if (polygon.length < 6) return;
+
+            beginLassoSelection({ layoutKey: embeddings.layout_key, polygon });
+          } catch (err) {
+            console.error("Lasso selection failed:", err);
+          }
+        }
+
+        requestRender();
+        return;
+      }
+
+      // Click-to-select (scatter -> image grid)
+      // Only treat as a click if the pointer didn't move much (otherwise it's a pan).
+      const pos = getCanvasPos(e);
+      const dx = pos.x - pointerDownXRef.current;
+      const dy = pos.y - pointerDownYRef.current;
+      const CLICK_MAX_DIST_SQ = 36; // ~6px
+      const isClick = dx * dx + dy * dy <= CLICK_MAX_DIST_SQ;
+
+      if (isClick) {
+        const hit = renderer.hitTest(pos.x, pos.y);
+        const idx = hit ? hit.index : -1;
+
+        if (idx >= 0 && idx < embeddings.ids.length) {
+          const id = embeddings.ids[idx];
+
+          if (e.metaKey || e.ctrlKey) {
+            const next = new Set(selectedIds);
+            if (next.has(id)) next.delete(id);
+            else next.add(id);
+            setSelectedIds(next, "scatter");
+          } else {
+            setSelectedIds(new Set([id]), "scatter");
+          }
+        }
+      }
+
+      stopInteraction();
+      requestRender();
+    },
+    [
+      beginLassoSelection,
+      embeddings,
+      getCanvasPos,
+      redrawOverlay,
+      requestRender,
+      selectedIds,
+      setSelectedIds,
+      stopInteraction,
+    ]
+  );
+
+  const handlePointerLeave = useCallback(
+    (_e: React.PointerEvent<HTMLCanvasElement>) => {
+      const renderer = rendererRef.current;
+      if (renderer) {
+        hoveredIndexRef.current = -1;
+        setHoveredId(null);
+        renderer.setHovered(-1);
+        requestRender();
+      }
+      stopInteraction();
+    },
+    [requestRender, setHoveredId, stopInteraction]
+  );
+
+  const handleDoubleClick = useCallback(
+    (_e: React.MouseEvent<HTMLCanvasElement>) => {
+      const renderer = rendererRef.current;
+      if (!renderer) return;
+      clearPersistentLasso();
+      stopInteraction();
+
+      renderer.setSelection(new Set());
+      setSelectedIds(new Set<string>(), "scatter");
+
+      requestRender();
+    },
+    [clearPersistentLasso, requestRender, setSelectedIds, stopInteraction]
+  );
+
+  return {
+    canvasRef,
+    overlayCanvasRef,
+    containerRef,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handlePointerLeave,
+    handleDoubleClick,
+    rendererError,
+  };
+}

frontend/src/components/useLabelLegend.ts

@@ -0,0 +1,85 @@
+import { useMemo } from "react";
+
+import type { DatasetInfo, EmbeddingsData } from "@/types";
+import {
+  MAX_DISTINCT_LABEL_COLORS,
+  buildLabelColorMap,
+  buildLabelCounts,
+  buildLabelUniverse,
+  buildLabelsInfo,
+  buildLegendLabels,
+  getDistinctLabelCount,
+} from "@/lib/labelLegend";
+
+interface UseLabelLegendArgs {
+  datasetInfo: DatasetInfo | null;
+  embeddings: EmbeddingsData | null;
+  labelSearch?: string;
+  labelFilter?: string | null;
+}
+
+export function useLabelLegend({
+  datasetInfo,
+  embeddings,
+  labelSearch = "",
+  labelFilter = null,
+}: UseLabelLegendArgs) {
+  const labelCounts = useMemo(() => buildLabelCounts(embeddings), [embeddings]);
+
+  const labelUniverse = useMemo(
+    () => buildLabelUniverse(datasetInfo?.labels ?? [], embeddings?.labels ?? null),
+    [datasetInfo?.labels, embeddings?.labels]
+  );
+
+  const distinctLabelCount = useMemo(() => {
+    const fromCounts = getDistinctLabelCount(labelCounts);
+    if (fromCounts > 0) return fromCounts;
+    let n = labelUniverse.length;
+    if (labelUniverse.includes("undefined")) n -= 1;
+    return n;
+  }, [labelCounts, labelUniverse]);
+
+  const distinctColoringDisabled = distinctLabelCount > MAX_DISTINCT_LABEL_COLORS;
+
+  const labelsInfo = useMemo(
+    () =>
+      buildLabelsInfo({
+        datasetLabels: datasetInfo?.labels ?? [],
+        embeddings,
+        distinctColoringDisabled,
+        labelFilter,
+      }),
+    [datasetInfo?.labels, embeddings, distinctColoringDisabled, labelFilter]
+  );
+
+  const labelColorMap = useMemo(
+    () =>
+      buildLabelColorMap({
+        labelsInfo,
+        labelUniverse,
+        distinctColoringDisabled,
+        labelFilter,
+      }),
+    [labelsInfo, labelUniverse, distinctColoringDisabled, labelFilter]
+  );
+
+  const legendLabels = useMemo(
+    () =>
+      buildLegendLabels({
+        labelUniverse,
+        labelCounts,
+        query: labelSearch,
+      }),
+    [labelUniverse, labelCounts, labelSearch]
+  );
+
+  return {
+    labelCounts,
+    labelUniverse,
+    distinctLabelCount,
+    distinctColoringDisabled,
+    labelsInfo,
+    labelColorMap,
+    legendLabels,
+  };
+}

frontend/src/lib/api.ts

@@ -0,0 +1,103 @@
+import type { DatasetInfo, EmbeddingsData, Sample, SamplesResponse } from "@/types";
+
+const API_BASE = process.env.NODE_ENV === "development" ? "http://127.0.0.1:6262" : "";
+
+export async function fetchDataset(): Promise<DatasetInfo> {
+  const res = await fetch(`${API_BASE}/api/dataset`);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch dataset: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+export async function fetchSamples(
+  offset: number = 0,
+  limit: number = 100,
+  label?: string
+): Promise<SamplesResponse> {
+  const params = new URLSearchParams({
+    offset: offset.toString(),
+    limit: limit.toString(),
+  });
+  if (label) {
+    params.set("label", label);
+  }
+
+  const res = await fetch(`${API_BASE}/api/samples?${params}`);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch samples: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+export async function fetchEmbeddings(layoutKey?: string): Promise<EmbeddingsData> {
+  const params = new URLSearchParams();
+  if (layoutKey) {
+    params.set("layout_key", layoutKey);
+  }
+  const query = params.toString();
+  const res = await fetch(`${API_BASE}/api/embeddings${query ? `?${query}` : ""}`);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch embeddings: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+export async function fetchSample(sampleId: string): Promise<Sample> {
+  const res = await fetch(`${API_BASE}/api/samples/${sampleId}`);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch sample: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+export async function fetchSamplesBatch(sampleIds: string[]): Promise<Sample[]> {
+  const res = await fetch(`${API_BASE}/api/samples/batch`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ sample_ids: sampleIds }),
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch samples batch: ${res.statusText}`);
+  }
+  const data = await res.json();
+  return data.samples;
+}
+
+export interface LassoSelectionResponse {
+  total: number;
+  offset: number;
+  limit: number;
+  sample_ids: string[];
+  samples: Sample[];
+}
+
+export async function fetchLassoSelection(args: {
+  layoutKey: string;
+  polygon: ArrayLike<number>;
+  offset?: number;
+  limit?: number;
+  includeThumbnails?: boolean;
+  signal?: AbortSignal;
+}): Promise<LassoSelectionResponse> {
+  const res = await fetch(`${API_BASE}/api/selection/lasso`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      layout_key: args.layoutKey,
+      polygon: Array.from(args.polygon),
+      offset: args.offset ?? 0,
+      limit: args.limit ?? 100,
+      include_thumbnails: args.includeThumbnails ?? true,
+    }),
+    signal: args.signal,
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch lasso selection: ${res.statusText}`);
+  }
+  return res.json();
+}

frontend/src/lib/labelColors.ts

@@ -0,0 +1,153 @@
+const MISSING_LABEL_SENTINEL = "undefined";
+
+export const MISSING_LABEL_COLOR = "#39d3cc"; // matches --accent-cyan
+export const FALLBACK_LABEL_COLOR = "#8b949e"; // matches --muted-foreground
+
+// Rerun-style auto colors: distribute hues by golden ratio conjugate.
+// See: context/repos/rerun/crates/viewer/re_viewer_context/src/utils/color.rs
+const GOLDEN_RATIO_CONJUGATE = (Math.sqrt(5) - 1) / 2; // ~0.61803398875
+
+function fnv1a32(input: string): number {
+  // 32-bit FNV-1a hash
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+function clamp01(v: number): number {
+  if (v < 0) return 0;
+  if (v > 1) return 1;
+  return v;
+}
+
+function hsvToHex(h: number, s: number, v: number): string {
+  // h/s/v in [0, 1]
+  const hh = ((h % 1) + 1) % 1;
+  const ss = clamp01(s);
+  const vv = clamp01(v);
+
+  const x = hh * 6;
+  const i = Math.floor(x);
+  const f = x - i;
+
+  const p = vv * (1 - ss);
+  const q = vv * (1 - ss * f);
+  const t = vv * (1 - ss * (1 - f));
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+
+  switch (i % 6) {
+    case 0:
+      r = vv;
+      g = t;
+      b = p;
+      break;
+    case 1:
+      r = q;
+      g = vv;
+      b = p;
+      break;
+    case 2:
+      r = p;
+      g = vv;
+      b = t;
+      break;
+    case 3:
+      r = p;
+      g = q;
+      b = vv;
+      break;
+    case 4:
+      r = t;
+      g = p;
+      b = vv;
+      break;
+    case 5:
+      r = vv;
+      g = p;
+      b = q;
+      break;
+  }
+
+  const toHex = (x: number) => {
+    const n = Math.round(clamp01(x) * 255);
+    return n.toString(16).padStart(2, "0");
+  };
+
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+export function labelToColor(label: string): string {
+  if (!label) return FALLBACK_LABEL_COLOR;
+  if (label === MISSING_LABEL_SENTINEL) return MISSING_LABEL_COLOR;
+
+  return colorForKey(label);
+}
+
+function colorForKey(key: string): string {
+  const seed = fnv1a32(key);
+  const val = seed & 0xffff; // map to u16
+  const h = (val * GOLDEN_RATIO_CONJUGATE) % 1;
+
+  // Match Rerun's defaults: saturation 0.85, value 0.5
+  return hsvToHex(h, 0.85, 0.5);
+}
+
+function stableLabelSort(a: string, b: string): number {
+  if (a === MISSING_LABEL_SENTINEL && b !== MISSING_LABEL_SENTINEL) return 1;
+  if (b === MISSING_LABEL_SENTINEL && a !== MISSING_LABEL_SENTINEL) return -1;
+  return a.localeCompare(b);
+}
+
+/**
+ * Builds a deterministic, collision-free label → color mapping for the given
+ * label universe.
+ *
+ * Notes:
+ * - No modulo/cycling: if there are N labels, we produce N colors.
+ * - Deterministic: same input set yields same mapping.
+ * - Collision-free within the provided set via deterministic rehashing.
+ */
+export function createLabelColorMap(labels: string[]): Record<string, string> {
+  const unique = Array.from(new Set(labels.map((l) => normalizeLabel(l)))).sort(stableLabelSort);
+
+  const colors: Record<string, string> = {};
+  const used = new Set<string>();
+
+  for (const label of unique) {
+    if (label === MISSING_LABEL_SENTINEL) {
+      colors[label] = MISSING_LABEL_COLOR;
+      used.add(MISSING_LABEL_COLOR.toLowerCase());
+      continue;
+    }
+
+    let attempt = 0;
+    // Deterministic collision resolution (should be extremely rare).
+    while (attempt < 32) {
+      const candidate = colorForKey(attempt === 0 ? label : `${label}#${attempt}`);
+      const normalized = candidate.toLowerCase();
+      if (!used.has(normalized)) {
+        colors[label] = candidate;
+        used.add(normalized);
+        break;
+      }
+      attempt++;
+    }
+
+    if (!colors[label]) {
+      // Should never happen, but keep UI resilient.
+      colors[label] = FALLBACK_LABEL_COLOR;
+    }
+  }
+
+  return colors;
+}
+
+export function normalizeLabel(label: string | null | undefined): string {
+  return label && label.length > 0 ? label : MISSING_LABEL_SENTINEL;
+}

frontend/src/lib/labelLegend.ts

@@ -0,0 +1,248 @@
+import type { EmbeddingsData } from "@/types";
+import {
+  FALLBACK_LABEL_COLOR,
+  MISSING_LABEL_COLOR,
+  createLabelColorMap,
+  normalizeLabel,
+} from "@/lib/labelColors";
+
+// Past ~20-30 categories, color-as-encoding becomes unreliable for most users.
+// We choose a conservative upper bound and fall back to a single color.
+export const MAX_DISTINCT_LABEL_COLORS = 20;
+export const UNSELECTED_LABEL_ALPHA = 0.12;
+
+export interface ScatterLabelsInfo {
+  uniqueLabels: string[];
+  categories: Uint16Array;
+  palette: string[];
+}
+
+function clamp01(v: number): number {
+  if (v < 0) return 0;
+  if (v > 1) return 1;
+  return v;
+}
+
+function applyAlphaToHex(color: string, alpha: number): string {
+  if (!color.startsWith("#")) return color;
+  const hex = Math.round(clamp01(alpha) * 255)
+    .toString(16)
+    .padStart(2, "0");
+
+  if (color.length === 7) {
+    return `${color}${hex}`;
+  }
+
+  if (color.length === 9) {
+    return `${color.slice(0, 7)}${hex}`;
+  }
+
+  return color;
+}
+
+function applyLabelFilterToPalette(params: {
+  palette: string[];
+  labels: string[];
+  labelFilter: string | null;
+  unselectedAlpha: number;
+}): string[] {
+  const { palette, labels, labelFilter, unselectedAlpha } = params;
+  if (!labelFilter) return palette;
+  if (!labels.includes(labelFilter)) return palette;
+
+  return palette.map((color, idx) =>
+    labels[idx] === labelFilter ? color : applyAlphaToHex(color, unselectedAlpha)
+  );
+}
+
+export function buildLabelCounts(embeddings: EmbeddingsData | null): Map<string, number> {
+  const counts = new Map<string, number>();
+  if (!embeddings) return counts;
+  for (const raw of embeddings.labels) {
+    const l = normalizeLabel(raw);
+    counts.set(l, (counts.get(l) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export function getDistinctLabelCount(labelCounts: Map<string, number>): number {
+  let n = labelCounts.size;
+  if (labelCounts.has("undefined")) n -= 1;
+  return n;
+}
+
+export function buildLabelUniverse(
+  datasetLabels: string[],
+  embeddingsLabels: (string | null)[] | null
+): string[] {
+  const universe: string[] = [];
+  const seen = new Set<string>();
+  let hasMissing = false;
+
+  const baseLabels = datasetLabels.map((l) => normalizeLabel(l));
+  for (const l of baseLabels) {
+    if (l === "undefined") {
+      hasMissing = true;
+      continue;
+    }
+    if (seen.has(l)) continue;
+    seen.add(l);
+    universe.push(l);
+  }
+
+  if (embeddingsLabels) {
+    const extras = new Set<string>();
+    for (const raw of embeddingsLabels) {
+      const l = normalizeLabel(raw);
+      if (l === "undefined") {
+        hasMissing = true;
+        continue;
+      }
+      if (!seen.has(l)) extras.add(l);
+    }
+
+    if (extras.size > 0) {
+      const extraSorted = Array.from(extras).sort((a, b) => a.localeCompare(b));
+      for (const l of extraSorted) {
+        seen.add(l);
+        universe.push(l);
+      }
+    }
+  }
+
+  if (hasMissing) universe.push("undefined");
+  return universe;
+}
+
+export function buildLabelsInfo(params: {
+  datasetLabels: string[];
+  embeddings: EmbeddingsData | null;
+  distinctColoringDisabled: boolean;
+  labelFilter?: string | null;
+  unselectedAlpha?: number;
+}): ScatterLabelsInfo | null {
+  const {
+    datasetLabels,
+    embeddings,
+    distinctColoringDisabled,
+    labelFilter = null,
+    unselectedAlpha = UNSELECTED_LABEL_ALPHA,
+  } = params;
+  if (!embeddings) return null;
+
+  const universe = buildLabelUniverse(datasetLabels, embeddings.labels);
+
+  // Guard: hyper-scatter categories are Uint16.
+  if (universe.length > 65535) {
+    console.warn(
+      `Too many labels (${universe.length}) for uint16 categories; collapsing to a single color.`
+    );
+    return {
+      uniqueLabels: ["undefined"],
+      categories: new Uint16Array(embeddings.labels.length),
+      palette: [FALLBACK_LABEL_COLOR],
+    };
+  }
+
+  const labelToCategory: Record<string, number> = {};
+  for (let i = 0; i < universe.length; i++) {
+    labelToCategory[universe[i]] = i;
+  }
+
+  const undefinedIndex = labelToCategory["undefined"] ?? 0;
+  const categories = new Uint16Array(embeddings.labels.length);
+  for (let i = 0; i < embeddings.labels.length; i++) {
+    const key = normalizeLabel(embeddings.labels[i]);
+    categories[i] = labelToCategory[key] ?? undefinedIndex;
+  }
+
+  let palette: string[];
+  if (distinctColoringDisabled) {
+    palette = universe.map((l) => (l === "undefined" ? MISSING_LABEL_COLOR : FALLBACK_LABEL_COLOR));
+  } else {
+    const colors = createLabelColorMap(universe);
+    palette = universe.map((l) => colors[l] ?? FALLBACK_LABEL_COLOR);
+  }
+
+  const filteredPalette = applyLabelFilterToPalette({
+    palette,
+    labels: universe,
+    labelFilter,
+    unselectedAlpha,
+  });
+
+  return { uniqueLabels: universe, categories, palette: filteredPalette };
+}
+
+export function buildLabelColorMap(params: {
+  labelsInfo: ScatterLabelsInfo | null;
+  labelUniverse: string[];
+  distinctColoringDisabled: boolean;
+  labelFilter?: string | null;
+  unselectedAlpha?: number;
+}): Record<string, string> {
+  const {
+    labelsInfo,
+    labelUniverse,
+    distinctColoringDisabled,
+    labelFilter = null,
+    unselectedAlpha = UNSELECTED_LABEL_ALPHA,
+  } = params;
+  const map: Record<string, string> = {};
+
+  if (labelsInfo) {
+    for (let i = 0; i < labelsInfo.uniqueLabels.length; i++) {
+      map[labelsInfo.uniqueLabels[i]] = labelsInfo.palette[i] ?? FALLBACK_LABEL_COLOR;
+    }
+    return map;
+  }
+
+  if (labelUniverse.length === 0) return map;
+
+  if (distinctColoringDisabled) {
+    for (const label of labelUniverse) {
+      map[label] = label === "undefined" ? MISSING_LABEL_COLOR : FALLBACK_LABEL_COLOR;
+    }
+    return map;
+  }
+
+  const colors = createLabelColorMap(labelUniverse);
+  for (const label of labelUniverse) {
+    map[label] = colors[label] ?? FALLBACK_LABEL_COLOR;
+  }
+
+  if (!labelFilter || !labelUniverse.includes(labelFilter)) return map;
+
+  for (const label of labelUniverse) {
+    if (label !== labelFilter) {
+      map[label] = applyAlphaToHex(map[label], unselectedAlpha);
+    }
+  }
+
+  return map;
+}
+
+export function buildLegendLabels(params: {
+  labelUniverse: string[];
+  labelCounts: Map<string, number>;
+  query: string;
+}): string[] {
+  const { labelUniverse, labelCounts, query } = params;
+  const all = labelUniverse.length > 0 ? [...labelUniverse] : Array.from(labelCounts.keys());
+  const q = query.trim().toLowerCase();
+  const filtered = q ? all.filter((l) => l.toLowerCase().includes(q)) : all;
+  const hasCounts = labelCounts.size > 0;
+
+  return filtered.sort((a, b) => {
+    if (a === "undefined" && b !== "undefined") return 1;
+    if (b === "undefined" && a !== "undefined") return -1;
+
+    if (hasCounts) {
+      const ca = labelCounts.get(a) ?? 0;
+      const cb = labelCounts.get(b) ?? 0;
+      if (cb !== ca) return cb - ca;
+    }
+
+    return a.localeCompare(b);
+  });
+}

frontend/src/lib/layouts.ts

@@ -0,0 +1,17 @@
+import type { Geometry, LayoutInfo } from "@/types";
+
+export function listAvailableGeometries(layouts: LayoutInfo[]): Geometry[] {
+  const geometries = new Set<Geometry>();
+  for (const layout of layouts) {
+    geometries.add(layout.geometry);
+  }
+  return Array.from(geometries);
+}
+
+export function findLayoutByGeometry(layouts: LayoutInfo[], geometry: Geometry): LayoutInfo | undefined {
+  return layouts.find((l) => l.geometry === geometry);
+}
+
+export function findLayoutByKey(layouts: LayoutInfo[], layoutKey: string): LayoutInfo | undefined {
+  return layouts.find((l) => l.layout_key === layoutKey);
+}