local: phase 5 arena and text highlighter

.geminirules

@@ -0,0 +1,7 @@
+# Agent Behavioral Rules
+
+1. NEVER write, edit, or modify any backend code files (Python, FastAPI, databases, engines, schemas, etc.) directly on your own.
+2. The user is in charge of the backend implementation.
+3. Instead of editing backend files, explain the concepts, algorithms, and provide code blocks in your responses so the user can review and implement them.
+4. DO NOT provide full copy-pasteable files of backend code to the user. Instead, provide architectural guidance, conceptual breakdowns, schema designs, key functions, and partial snippets/pseudocode not actual python code so that the user writes and completes the actual code, reinforcing their hands-on learning.
+5. Only edit frontend files (HTML, CSS, JS) if explicitly requested, but NEVER touch backend files.

.gitignore

@@ -0,0 +1,3 @@
+.venv
+store/
+__pycache__

.python-version

@@ -0,0 +1 @@
+3.11

backend/__init__.py

@@ -0,0 +1 @@
+# Backend package for RAG Visualizer

backend/constants.py

@@ -0,0 +1,93 @@
+system_instructions = """
+# ROLE
+You are a strict, unbiased RAG evaluation judge. Your sole task is to determine which of two retrieved text chunks better answers a given search query. You have no preference for either chunk.
+
+# BLINDING RULE (critical)
+The chunks are labelled "Chunk A" and "Chunk B". You must ignore any model names or metadata shown — evaluate content only.
+
+# SCORING CRITERIA (score each 1–10)
+Score each dimension independently. Do not let one dimension influence another.
+
+1. Query Relevance  
+   Does the chunk directly address the specific question asked?  
+   10 = precisely on-topic, 1 = entirely off-topic.  
+   Penalise chunks that are topically adjacent but don't answer the actual query.
+
+2. Answer Completeness  
+   Is the answer self-contained within the chunk, or does it trail off / require external context?  
+   10 = standalone complete answer, 1 = fragment with no usable answer.  
+   Do NOT reward length. A concise, complete answer scores higher than a verbose partial one.
+
+3. Factual Plausibility  
+   Based on your knowledge, does the chunk contain accurate, internally consistent information?  
+   10 = no detectable errors, 1 = clearly wrong or contradictory.  
+   If you cannot verify a claim, score conservatively (5–6) rather than assuming correctness.  
+   Do not penalise a chunk for information you simply don't recognise.
+
+4. Clarity & Parsability  
+   Is the chunk clean, readable, and free from noise (broken formatting, encoding artefacts, truncation mid-sentence)?  
+   10 = polished and easy to parse, 1 = heavily noisy or unreadable.
+
+# OVERALL SCORE
+overall = (relevance + completeness + plausibility + clarity) / 4
+Round to two decimal places.
+
+# WINNER DECLARATION
+- Declare "chunk_a" or "chunk_b" based on overall score.
+- Declare "tie" ONLY if overall scores are within 0.5 of each other AND no single dimension differs by more than 2 points. Ties should be rare.
+- If you declare a tie, the winner_reason must explicitly state why the gap is insufficient to prefer either chunk.
+
+# CONFIDENCE
+0.9–1.0: One chunk is clearly superior across most dimensions.  
+0.7–0.89: One chunk wins, but with a notable weakness.  
+0.5–0.69: Close call; winner has only a marginal edge.  
+Below 0.5: Reserve for genuine ties.
+
+---
+
+Search Query: {search_query}
+
+--- Chunk A ---
+{chunk_a}
+
+--- Chunk B ---
+{chunk_b}
+
+---
+
+# OUTPUT RULE
+OUTPUT: respond with this exact JSON structure and nothing else:
+{{
+  "winner": "chunk_a" | "chunk_b" | "tie",
+  "confidence": float,
+  "chunk_a_score": {{
+    "query_relevance": int,
+    "answer_completeness": int,
+    "factual_plausibility": int,
+    "clarity": int,
+    "overall": float
+  }},
+  "chunk_b_score": {{
+    "query_relevance": int,
+    "answer_completeness": int,
+    "factual_plausibility": int,
+    "clarity": int,
+    "overall": float
+  }},
+  "winner_reason": "2-3 sentences",
+  "deciding_dimension": "e.g. query_relevance",
+  "chunk_a_strengths": ["..."],
+  "chunk_a_weaknesses": ["..."],
+  "chunk_b_strengths": ["..."],
+  "chunk_b_weaknesses": ["..."]
+}}
+"""
+
+
+hyde_prompt = """Generate a concise, factual passage that directly answers the query below.
+Write as if excerpted from a authoritative document or textbook — no intro, no filler, no meta-commentary.
+Match the tone and vocabulary a subject-matter expert would use when writing about this topic.
+
+Query: {search_text}
+
+Passage:"""

backend/engines/__init__.py

@@ -0,0 +1 @@
+# Engines package — ChunkingEngine, EmbeddingEngine, etc.

backend/engines/chunking.py

@@ -0,0 +1,251 @@
+import math
+import tiktoken
+from typing import List
+from nltk.tokenize import sent_tokenize
+import numpy as np
+
+from backend.engines.embedding import EmbeddingEngine
+
+from langchain_text_splitters import (
+    RecursiveCharacterTextSplitter,
+    NLTKTextSplitter,
+    CharacterTextSplitter,
+)
+
+from backend.models.schemas import ChunkConfig, ChunkNode
+
+
+def count_token(text: str, tokenizer) -> int:
+    _encoder = tiktoken.get_encoding(tokenizer)
+    return len(_encoder.encode(text))
+
+
+def fixed_size_strategy(text, config: ChunkConfig) -> List[ChunkNode]:
+    splitter = CharacterTextSplitter.from_tiktoken_encoder(
+        encoding_name=config.tokenizer,
+        chunk_size=config.chunk_size,
+        chunk_overlap=config.chunk_overlap,
+    )
+    result = splitter.split_text(text)
+    result = construct_chunk_node(text, result, config.tokenizer)
+    return result
+
+
+def sentence_strategy(text, config: ChunkConfig) -> List[ChunkNode]:
+    text_splitter = NLTKTextSplitter.from_tiktoken_encoder(
+        encoding_name=config.tokenizer,
+        chunk_size=config.chunk_size,
+        chunk_overlap=config.chunk_overlap,
+    )
+    result = text_splitter.split_text(text)
+    result = construct_chunk_node(text, result, config.tokenizer)
+    return result
+
+
+def recursive_strategy(text, config: ChunkConfig) -> List[ChunkNode]:
+    splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
+        encoding_name=config.tokenizer,
+        chunk_size=config.chunk_size,
+        chunk_overlap=config.chunk_overlap,
+        separators=config.separators,
+    )
+    result = splitter.split_text(text)
+    result = construct_chunk_node(text, result, config.tokenizer)
+    return result
+
+
+def parent_child_strategy(text, config) -> List[ChunkNode]:
+    parent_splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
+        encoding_name=config.tokenizer,
+        chunk_size=config.parent_chunk_size,
+        chunk_overlap=config.parent_chunk_overlap,
+        separators=config.separators,
+    )
+    parent_chunks = parent_splitter.split_text(text)
+    result = construct_parent_child_nodes(text, parent_chunks, config)
+    return result
+
+
+def construct_chunk_node(text, chunks, tokenizer):
+    nodes = []
+    current_position = 0
+    for i, chunk in enumerate(chunks):
+        # 1. Try exact find first
+        start = text.find(chunk, current_position)
+
+        # 2. If exact find fails, try a clean stripped version
+        if start == -1:
+            clean_anchor = chunk.strip()[:40]
+            if clean_anchor:
+                start = text.find(clean_anchor, current_position)
+
+        # 3. If it still fails, park it at current_position
+        if start == -1:
+            start = current_position
+
+        end = start + len(chunk)
+        node = ChunkNode(
+            id=f"chunk_{i}",
+            order=i,
+            text=chunk,
+            token_count=count_token(chunk, tokenizer),
+            start_char=start,
+            end_char=end,
+        )
+        nodes.append(node)
+
+        # Safely advance position but allow overlaps
+        current_position = max(current_position, start + 1)
+
+    return nodes
+
+
+def construct_parent_child_nodes(text, parent_chunks, config):
+    all_nodes = []
+    current_position = 0
+    for parent_index, parent_chunk in enumerate(parent_chunks):
+        parent_start = text.find(parent_chunk, current_position)
+        parent_end = parent_start + len(parent_chunk)
+
+        parent_id = f"parent_{parent_index}"
+
+        parent_node = ChunkNode(
+            id=parent_id,
+            order=parent_index,
+            text=parent_chunk,
+            token_count=count_token(parent_chunk, config.tokenizer),
+            start_char=parent_start,
+            end_char=parent_end,
+            level=0,
+            child_ids=[],
+        )
+        all_nodes.append(parent_node)
+
+        child_splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
+            encoding_name=config.tokenizer,
+            chunk_size=config.child_chunk_size,
+            chunk_overlap=config.child_chunk_overlap,
+            separators=config.separators,
+        )
+        child_chunks = child_splitter.split_text(parent_chunk)
+
+        child_position = parent_start
+
+        for child_index, child_chunk in enumerate(child_chunks):
+
+            child_start = text.find(child_chunk, child_position)
+            child_end = child_start + len(child_chunk)
+
+            child_id = f"{parent_id}_child_{child_index}"
+
+            child_node = ChunkNode(
+                id=child_id,
+                order=child_index,
+                text=child_chunk,
+                token_count=count_token(child_chunk, config.tokenizer),
+                start_char=child_start,
+                end_char=child_end,
+                level=1,
+                parent_id=parent_id,
+            )
+
+            parent_node.child_ids.append(child_id)
+
+            all_nodes.append(child_node)
+
+            child_position = child_start + 1
+
+        current_position = parent_start + 1
+
+    return all_nodes
+
+
+def cosine_similarity(v1, v2):
+    dot_product = sum(x * y for x, y in zip(v1, v2))
+    norm_v1 = math.sqrt(sum(x * x for x in v1))
+    norm_v2 = math.sqrt(sum(x * x for x in v2))
+    if not norm_v1 or not norm_v2:
+        return 0.0
+    return dot_product / (norm_v1 * norm_v2)
+
+
+async def semantic_strategy(text, config: ChunkConfig, embedding_model):
+    sentences = sent_tokenize(text)
+    embedding_engine = EmbeddingEngine(embedding_model)
+
+    if not sentences:
+        return []
+
+    temp_nodes = [
+        ChunkNode(
+            id=f"temp_{i}", order=i, text=s, token_count=0, start_char=0, end_char=0
+        )
+        for i, s in enumerate(sentences)
+    ]
+
+    sentence_embeddings = await embedding_engine.generate_embeddings(temp_nodes)
+
+    similarities = []
+
+    for i in range(len(sentence_embeddings) - 1):
+        sim = cosine_similarity(sentence_embeddings[i], sentence_embeddings[i + 1])
+        similarities.append(sim)
+
+    distances = [1 - s for s in similarities]
+
+    if not distances:
+        return construct_chunk_node(text, sentences, config.tokenizer)
+
+    mean_distance = np.mean(distances)
+    std_deviation = np.std(distances)
+
+    z_score_multiplier = 2.5 - (config.semantic_threshold * 3.0)
+    dynamic_threshold = mean_distance + (z_score_multiplier * std_deviation)
+
+    chunks = []
+    current_chunks = [sentences[0]]
+
+    for i in range(len(distances)):
+        current_dist = distances[i]
+
+        if current_dist > dynamic_threshold:
+            is_greater_than_prev = (i == 0) or (current_dist > distances[i - 1])
+            is_greater_than_or_equal_next = (i == len(distances) - 1) or (
+                current_dist >= distances[i + 1]
+            )
+
+            if is_greater_than_prev and is_greater_than_or_equal_next:
+                chunks.append(" ".join(current_chunks))
+                current_chunks = [sentences[i + 1]]
+            else:
+                current_chunks.append(sentences[i + 1])
+        else:
+            current_chunks.append(sentences[i + 1])
+
+    if current_chunks:
+        chunks.append(" ".join(current_chunks))
+
+    return construct_chunk_node(text, chunks, config.tokenizer)
+
+
+class ChunkingEngine:
+
+    async def chunk(self, text, strategy, config, embedding_model) -> List[ChunkNode]:
+        strategy_func = self.available_strategy(strategy)
+        if not strategy_func:
+            raise ValueError(f"Unknown strategy: {strategy}")
+
+        if strategy == "semantic":
+            return await strategy_func(text, config, embedding_model)
+
+        return strategy_func(text, config)
+
+    def available_strategy(self, strategy):
+        STRATEGY = {
+            "fixed_size": fixed_size_strategy,
+            "sentence": sentence_strategy,
+            "recursive": recursive_strategy,
+            "parent_child": parent_child_strategy,
+            "semantic": semantic_strategy,
+        }
+        return STRATEGY.get(strategy)

backend/engines/embedding.py

@@ -0,0 +1,29 @@
+from typing import Sequence
+import httpx
+
+from backend.models.schemas import ChunkNode, EmbeddingModel
+
+
+class EmbeddingEngine:
+    def __init__(self, embedding_model):
+        self.embedding_model = embedding_model
+        self.client = httpx.AsyncClient(timeout=60)
+
+    async def generate_embeddings(self, chunks: Sequence[ChunkNode | str]):
+        texts = [c if isinstance(c, str) else c.text for c in chunks]
+        res = await self.client.post(
+            "http://localhost:11434/api/embed",
+            json={
+                "model": self.embedding_model,
+                "input": texts,
+            },
+        )
+
+        res_json = res.json()
+
+        if "embeddings" not in res_json or not res_json["embeddings"]:
+            raise ValueError(
+                f"Ollama failed to generate embeddings for {self.embedding_model}. Response: {res_json}"
+            )
+
+        return res_json["embeddings"]

backend/engines/llm_client.py

@@ -0,0 +1,17 @@
+from typing import Optional
+import ollama
+
+
+class OllamaClient:
+    def __init__(self):
+        self.model = "gemma4:e2b"
+        self.client = ollama.AsyncClient()
+
+    async def generate(self, prompt: str, response_format: Optional[str] = "json"):
+        args = {"model": self.model, "prompt": prompt}
+
+        if response_format:
+            args["format"] = response_format
+
+        response = await self.client.generate(**args)  # type: ignore
+        return response["response"]

backend/engines/reducer.py

@@ -0,0 +1,43 @@
+import numpy as np
+from numpy.typing import NDArray
+from typing import List
+import umap
+
+
+class ReducerEngine:
+    _last_fitted_reducer = None
+
+    def __init__(self, n_neighbors, min_dist):
+        self.n_neighbors = n_neighbors
+        self.min_dist = min_dist
+
+    def reduce(self, embeddings: List[List[float]]) -> List[List[float]]:
+        n_samples = len(embeddings)
+
+        if n_samples == 0:
+            return []
+
+        if n_samples == 1:
+            return [[0.0, 0.1]]
+
+        if n_samples < 5:
+            return [[0.0, i * 0.1] for i in range(n_samples)]
+
+        data = np.array(embeddings)
+
+        safe_n_neighbors = min(self.n_neighbors, n_samples - 1)
+        safe_n_neighbors = max(2, safe_n_neighbors)
+
+        reducer = umap.UMAP(
+            n_neighbors=safe_n_neighbors,
+            min_dist=self.min_dist,
+            metric="cosine",
+            random_state=42,
+            n_components=2,
+        )
+
+        coords_2d: NDArray[np.float32] = np.asarray(reducer.fit_transform(data))
+
+        ReducerEngine._last_fitted_reducer = reducer
+
+        return coords_2d.tolist()

backend/main.py

@@ -0,0 +1,60 @@
+import os
+import nltk
+from pathlib import Path
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+
+def initialize_nltk():
+    nltk_data_dir = os.path.expanduser("~/nltk_data")
+    os.makedirs(nltk_data_dir, exist_ok=True)
+
+    if nltk_data_dir not in nltk.data.path:
+        nltk.data.path.append(nltk_data_dir)
+
+    resources = {
+        "tokenizers/punkt": "punkt",
+        "tokenizers/punkt_tab": "punkt_tab",
+        "corpora/stopwords": "stopwords",
+    }
+
+    for path, package in resources.items():
+        try:
+            nltk.data.find(path)
+            print(f"Found NLTK resource: {package}")
+        except LookupError:
+            print(f"Downloading missing NLTK resource: {package} to {nltk_data_dir}...")
+            nltk.download(package, download_dir=nltk_data_dir)
+
+
+initialize_nltk()
+
+from backend.routers.retrieval_router import router as retrieval_router
+from backend.routers.chunk_router import router as chunk_router
+
+app = FastAPI(
+    title="RAG Visualizer",
+    description="An X-Ray machine for RAG pipelines",
+    version="0.1.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(chunk_router)
+app.include_router(retrieval_router)
+
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
+app.mount("/static", StaticFiles(directory=str(FRONTEND_DIR)), name="static")
+
+
+@app.get("/")
+def serve_frontend():
+    return FileResponse(str(FRONTEND_DIR / "index.html"))

backend/models/__init__.py

@@ -0,0 +1 @@
+# Models package — Pydantic schemas (API contracts)

backend/models/schemas.py

@@ -0,0 +1,184 @@
+from enum import Enum
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, Field, model_validator
+
+
+# --- Chunk-related schemas ---
+
+
+class Strategy(str, Enum):
+    FIXED_SIZE = "fixed_size"
+    SENTENCE = "sentence"
+    RECURSIVE = "recursive"
+    PARENT_CHILD = "parent_child"
+    SEMANTIC = "semantic"
+
+
+class EmbeddingModel(str, Enum):
+    NOMIC_EMBED_TEXT = "nomic-embed-text"
+    EMBEDDING_GEMMA = "EmbeddingGemma"
+    QWEN_EMBEDDING = "qwen3-embedding:0.6b"
+
+
+class RetrievalMode(str, Enum):
+    DENSE = "dense"
+    SPARSE = "sparse"
+    HYBRID = "hybrid"
+
+
+class ChunkConfig(BaseModel):
+    chunk_size: int = 500
+    chunk_overlap: int = 20
+    semantic_threshold: float = 0.5
+    separators: Optional[List[str]] = None
+    tokenizer: str = "cl100k_base"
+    parent_chunk_size: Optional[int] = None
+    parent_chunk_overlap: Optional[int] = None
+    child_chunk_size: Optional[int] = None
+    child_chunk_overlap: Optional[int] = None
+
+
+class ChunkNode(BaseModel):
+    id: str
+    order: int
+    text: str
+    token_count: int
+    start_char: int
+    end_char: int
+    level: int = 0
+    parent_id: Optional[str] = None
+    child_ids: List[str] = []
+    metadata: Dict[str, Any] = {}
+    embeddings: Optional[List[float]] = None
+    coords_2d: Optional[List[float]] = None
+
+
+class StrategyRun(BaseModel):
+    strategy: Strategy
+    config: ChunkConfig
+
+
+class StrategyResult(BaseModel):
+    strategy: Strategy
+    chunks: List[ChunkNode]
+    total_chunks: int
+    avg_token_count: int
+    total_tokens: int
+
+
+class ChunkRequest(BaseModel):
+    text: str
+    runs: List[StrategyRun]
+    embedding_model: EmbeddingModel = EmbeddingModel.NOMIC_EMBED_TEXT
+    n_neighbors: int = 15
+    min_dist: float = 0.1
+
+
+class ChunkResponse(BaseModel):
+    results: List[StrategyResult]
+
+
+class QueryRequest(BaseModel):
+    search_text: str
+    embedding_model: EmbeddingModel
+    strategy: Strategy
+    top_k: int = 3
+    retrieval_mode: RetrievalMode = RetrievalMode.DENSE
+    use_hyde: bool = False
+    use_reranking: bool = False
+
+
+class RetrievedChunk(BaseModel):
+    id: str
+    text: str
+    score: float
+    start_char: int
+    end_char: int
+    parent_id: Optional[str] = None
+    level: int = 0
+    text_highlighted: Optional[str] = None
+
+
+class QueryResponse(BaseModel):
+    query_text: str
+    query_coords: List[float] = [0.0, 0.0]
+    results: List[RetrievedChunk]
+    hypothetical_answer: Optional[str] = None
+
+
+class CompareRequest(BaseModel):
+    search_text: str
+    top_k: int = 3
+    model_a: EmbeddingModel
+    strategy_a: Strategy
+    model_b: EmbeddingModel
+    strategy_b: Strategy
+
+    retrieval_mode: RetrievalMode = RetrievalMode.DENSE
+    use_hyde: bool = False
+    use_reranking: bool = False
+
+
+class CompareResponse(BaseModel):
+    search_text: str
+    results_a: List[RetrievedChunk]
+    results_b: List[RetrievedChunk]
+    hypothetical_answer: Optional[str] = None
+
+
+class JudgeRequest(BaseModel):
+    search_query: str
+    chunk_a: str
+    chunk_b: str
+
+
+class ChunkScore(BaseModel):
+    query_relevance: int = Field(ge=1, le=10)
+    answer_completeness: int = Field(ge=1, le=10)
+    factual_plausibility: int = Field(ge=1, le=10)
+    clarity: int = Field(ge=1, le=10)
+    overall: float
+
+    @model_validator(mode="after")
+    def check_overall(self) -> "ChunkScore":
+        expected = round(
+            (
+                self.query_relevance
+                + self.answer_completeness
+                + self.factual_plausibility
+                + self.clarity
+            )
+            / 4,
+            2,
+        )
+        self.overall = expected
+        return self
+
+
+class JudgeResponse(BaseModel):
+    winner: Literal["chunk_a", "chunk_b", "tie"]
+    confidence: float = Field(ge=0, le=1)
+
+    chunk_a_score: ChunkScore
+    chunk_b_score: ChunkScore
+
+    winner_reason: str
+    chunk_a_strengths: List[str]
+    chunk_b_strengths: List[str]
+    chunk_a_weaknesses: List[str]
+    chunk_b_weaknesses: List[str]
+    deciding_dimension: str
+
+    @model_validator(mode="after")
+    def check_winner_consistency(self) -> "JudgeResponse":
+        a = self.chunk_a_score.overall
+        b = self.chunk_b_score.overall
+        gap = abs(a - b)
+
+        if gap <= 0.5:
+            self.winner = "tie"
+        elif a > b:
+            self.winner = "chunk_a"
+        else:
+            self.winner = "chunk_b"
+        return self

backend/routers/__init__.py

@@ -0,0 +1 @@
+# Routers package — API endpoint definitions

backend/routers/chunk_router.py

@@ -0,0 +1,95 @@
+from typing import List
+from fastapi import APIRouter, responses
+from pydantic import config
+
+from backend.engines.chunking import ChunkingEngine
+from backend.engines.embedding import EmbeddingEngine
+from backend.engines.reducer import ReducerEngine
+from backend.models.schemas import (
+    ChunkNode,
+    ChunkRequest,
+    ChunkResponse,
+    Strategy,
+    StrategyResult,
+)
+from backend.storage.vector_store import VectorStore
+
+# TODO: import your schemas and engine
+
+router = APIRouter(prefix="/api", tags=["chunking"])
+
+
+# TODO: GET /strategies endpoint
+@router.get("/strategies", response_model=List[Strategy])
+def get_strategies():
+    return list(Strategy)
+
+
+# TODO: POST /chunk endpoint
+@router.post("/chunk", response_model=ChunkResponse)
+async def create_chunk(request: ChunkRequest):
+    chunk_engine = ChunkingEngine()
+    embedding_engine = EmbeddingEngine(request.embedding_model.value)
+    reducer_engine = ReducerEngine(request.n_neighbors, request.min_dist)
+    vector_store = VectorStore()
+    response = []
+    all_chunks = []
+    strategy_results_map = {}
+
+    for run in request.runs:
+        strategy = run.strategy
+        config = run.config
+        chunks: List[ChunkNode] = await chunk_engine.chunk(
+            text=request.text,
+            strategy=strategy,
+            config=config,
+            embedding_model=request.embedding_model.value,
+        )
+        strategy_results_map[strategy] = chunks
+        all_chunks.extend(chunks)
+
+    embeddings = await embedding_engine.generate_embeddings(all_chunks)
+
+    ids = [c.id for c in all_chunks]
+    documents = [c.text for c in all_chunks]
+
+    chunk_metadatas = [
+        {
+            "start_char": c.start_char,
+            "end_char": c.end_char,
+            "token_count": c.token_count,
+            "level": c.level,
+            "parent_id": c.parent_id or "",
+        }
+        for c in all_chunks
+    ]
+
+    await vector_store.upsert(
+        collection_name=f"{request.embedding_model.value}_{request.runs[0].strategy.value}".replace(":", "-"),
+        ids=ids,
+        documents=documents,
+        embeddings=embeddings,
+        metadatas=chunk_metadatas,
+    )
+
+    coords_2d = reducer_engine.reduce(embeddings)
+
+    for chunk, coords in zip(all_chunks, coords_2d):
+        chunk.coords_2d = coords
+
+    for strategy, chunks in strategy_results_map.items():
+        total_chunks = len(chunks)
+        total_tokens = sum(node.token_count for node in chunks)
+        avg_tokens = total_tokens / total_chunks if total_chunks > 0 else 0
+
+        response.append(
+            StrategyResult(
+                strategy=strategy,
+                chunks=chunks,
+                total_chunks=total_chunks,
+                total_tokens=total_tokens,
+                avg_token_count=int(avg_tokens),
+            )
+        )
+
+    return ChunkResponse(results=response)

backend/routers/retrieval_router.py

@@ -0,0 +1,191 @@
+from backend.constants import hyde_prompt
+from backend.engines import llm_client
+from backend.engines.llm_client import OllamaClient
+from backend.constants import system_instructions
+import asyncio
+from typing import Any, Optional
+from fastapi import APIRouter
+import json
+import re
+from backend.engines.embedding import EmbeddingEngine
+from backend.engines.reducer import ReducerEngine
+from backend.models.schemas import (
+    CompareRequest,
+    CompareResponse,
+    JudgeResponse,
+    JudgeRequest,
+    QueryRequest,
+    QueryResponse,
+    RetrievedChunk,
+)
+from backend.storage.vector_store import VectorStore
+
+from nltk.tokenize import RegexpTokenizer
+from nltk.corpus import stopwords
+
+router = APIRouter(prefix="/api", tags=["retrieval"])
+
+
+tokenizer = RegexpTokenizer(r"\w+")
+stop_words = set(stopwords.words("english"))
+
+
+@router.post("/retrieve", response_model=QueryResponse)
+async def retrieve(request: QueryRequest):
+
+    search_text = (
+        await get_hyde_text(request.search_text)
+        if request.use_hyde
+        else request.search_text
+    )
+
+    if request.use_reranking == True:
+        "" ""
+
+    retrieved_chunks, embeddings = await process_retrieval(
+        request.embedding_model,
+        search_text,
+        request.strategy,
+        request.top_k,
+        request.search_text,
+    )
+
+    query_coords = [0.0, 0.0]
+    if ReducerEngine._last_fitted_reducer is not None:
+        projected: Any = ReducerEngine._last_fitted_reducer.transform(embeddings)
+        query_coords = projected[0].tolist()
+
+    response_kwargs = {
+        "query_text": request.search_text,
+        "query_coords": query_coords,
+        "results": retrieved_chunks,
+    }
+
+    if request.use_hyde:
+        response_kwargs["hypothetical_answer"] = search_text
+
+    return QueryResponse(**response_kwargs)
+
+
+@router.post("/compare", response_model=CompareResponse)
+async def compare(request: CompareRequest):
+    retrieval_text = (
+        await get_hyde_text(request.search_text)
+        if request.use_hyde
+        else request.search_text
+    )
+    (
+        (retrieved_chunks_a, _),
+        (retrieved_chunks_b, _),
+    ) = await asyncio.gather(
+        process_retrieval(
+            request.model_a,
+            retrieval_text,
+            request.strategy_a,
+            request.top_k,
+            request.search_text,
+        ),
+        process_retrieval(
+            request.model_b,
+            retrieval_text,
+            request.strategy_b,
+            request.top_k,
+            request.search_text,
+        ),
+    )
+
+    response_kwargs = {
+        "search_text": request.search_text,
+        "results_a": retrieved_chunks_a,
+        "results_b": retrieved_chunks_b,
+    }
+    if request.use_hyde:
+        response_kwargs["hypothetical_answer"] = retrieval_text
+
+    return CompareResponse(**response_kwargs)
+
+
+@router.post("/judge", response_model=JudgeResponse)
+async def judge(request: JudgeRequest):
+    prompt = system_instructions.format(
+        search_query=request.search_query,
+        chunk_a=request.chunk_a,
+        chunk_b=request.chunk_b,
+    )
+
+    llm_client = OllamaClient()
+    result = await llm_client.generate(prompt=prompt)
+
+    print(f"res:res: {result}")
+
+    result_dict = json.loads(result)
+
+    return JudgeResponse(**result_dict)
+
+
+async def process_retrieval(
+    model, search_text, strategy, top_k, original_query: Optional[str] = None
+):
+    vector_store = VectorStore()
+    embedding_engine = EmbeddingEngine(model.value)
+    embeddings = await embedding_engine.generate_embeddings([search_text])
+    result: Any = await vector_store.retrieve(
+        collection_name=f"{model.value}_{strategy.value}".replace(":", "-"),
+        embeddings=embeddings,
+        n_results=top_k,
+    )
+
+    retrieved_chunks = []
+
+    highlight_text = original_query if original_query is not None else search_text
+
+    # Check if result contains valid data
+    if result and "ids" in result and result["ids"]:
+        ids = result["ids"][0]
+        documents = result["documents"][0]
+        distances = result["distances"][0]
+        metadatas = result["metadatas"][0]
+
+        for i in range(len(ids)):
+            text_highlighted = get_text_highlights(documents[i], highlight_text)
+            meta = metadatas[i] or {}
+            retrieved_chunks.append(
+                RetrievedChunk(
+                    id=ids[i],
+                    text=documents[i],
+                    score=distances[i],
+                    start_char=meta.get("start_char", 0),
+                    end_char=meta.get("end_char", 0),
+                    parent_id=meta.get("parent_id") or None,
+                    level=meta.get("level", 0),
+                    text_highlighted=text_highlighted,
+                )
+            )
+
+    return retrieved_chunks, embeddings
+
+
+def get_text_highlights(original_text, search_text):
+    query_keywords = get_keywords(search_text)
+    if not query_keywords:
+        return original_text
+
+    query_keywords.sort(key=len, reverse=True)
+
+    safe_keywords = [f"{re.escape(w)}(?:'s)?" for w in query_keywords]
+
+    pattern_string = r"\b(" + "|".join(safe_keywords) + r")\b"
+    pattern = re.compile(pattern_string, re.IGNORECASE)
+
+    return pattern.sub(r"<mark>\1</mark>", original_text)
+
+
+def get_keywords(text: str):
+    token = tokenizer.tokenize(text.lower())
+    return [word for word in token if word not in stop_words]
+
+
+async def get_hyde_text(search_text):
+    llm_client = OllamaClient()
+    hyde_prompt.format(search_text=search_text)
+    return await llm_client.generate(hyde_prompt, response_format=None)

backend/storage/vector_store.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+from chromadb import PersistentClient
+import asyncio
+
+
+class VectorStore:
+    def __init__(self):
+        base_dir = Path(__file__).resolve().parent.parent.parent
+        store_path = base_dir / "store"
+        self.client = PersistentClient(path=str(store_path))
+
+    def get_collection(self, name: str):
+        return self.client.get_or_create_collection(
+            name=name, metadata={"hnsw:space": "cosine"}
+        )
+
+    async def upsert(self, collection_name, ids, documents, embeddings, metadatas=None):
+        collection = self.get_collection(collection_name)
+
+        await asyncio.to_thread(
+            collection.upsert,
+            ids=ids,
+            documents=documents,
+            embeddings=embeddings,
+            metadatas=metadatas,
+        )
+
+    async def retrieve(self, collection_name, embeddings, n_results=3):
+        collection = self.get_collection(collection_name)
+
+        return await asyncio.to_thread(
+            collection.query, query_embeddings=embeddings, n_results=n_results
+        )

dev.bat

@@ -0,0 +1 @@
+uv run uvicorn backend.main:app --reload --port 8080

frontend/app.js

@@ -0,0 +1,1652 @@
+/**
+ * RAG Visualizer — Chunking Lab
+ * Frontend logic: API calls, chunk highlighting, and interactive inspection.
+ */
+
+// ============================================================
+// State
+// ============================================================
+const state = {
+  text: "",
+  strategy: "fixed_size",
+  config: {
+    chunk_size: 500,
+    chunk_overlap: 20,
+    tokenizer: "cl100k_base",
+    separators: null,
+    parent_chunk_size: 1000,
+    parent_chunk_overlap: 100,
+    child_chunk_size: 200,
+    child_chunk_overlap: 20,
+    embedding_model: "nomic-embed-text",
+    n_neighbors: 15,
+    min_dist: 0.1,
+    semantic_threshold: 0.5,
+  },
+  activeTab: "xray-tab",
+  results: null, // StrategyResult from API
+  activeChunkId: null, // Currently highlighted chunk
+  isLoading: false,
+};
+
+// ============================================================
+// DOM References
+// ============================================================
+const $ = (sel) => document.querySelector(sel);
+const $$ = (sel) => document.querySelectorAll(sel);
+
+const dom = {
+  textInput: $("#text-input"),
+  charCount: $("#char-count"),
+  strategyGrid: $("#strategy-grid"),
+  btnRun: $("#btn-run"),
+  xrayEmpty: $("#xray-empty"),
+  xrayText: $("#xray-text"),
+  chunkList: $("#chunk-list"),
+  statTotal: $("#stat-total"),
+  statAvgTokens: $("#stat-avg-tokens"),
+  statTotalTokens: $("#stat-total-tokens"),
+  statStrategy: $("#stat-strategy"),
+  standardConfig: $("#standard-config"),
+  parentChildConfig: $("#parent-child-config"),
+  semanticConfig: $("#semantic-config"),
+  separatorsSection: $("#separators-section"),
+  separatorTags: $("#separator-tags"),
+  separatorInput: $("#separator-input"),
+
+  // Vector & UMAP config elements
+  embeddingModel: $("#embedding-model"),
+  nNeighbors: $("#n-neighbors"),
+  minDist: $("#min-dist"),
+  nNeighborsValue: $("#n-neighbors-value"),
+  minDistValue: $("#min-dist-value"),
+
+  // Tab elements
+  tabButtons: $$(".tab-btn"),
+  tabContents: $$(".tab-content"),
+
+  // Canvas elements
+  vectorCanvas: $("#vector-canvas"),
+  vectorTooltip: $("#vector-tooltip"),
+
+  // Query Simulator elements
+  queryInput: $("#query-input"),
+  btnQuery: $("#btn-query"),
+  queryResultsDrawer: $("#query-results-drawer"),
+  queryResultsList: $("#query-results-list"),
+  closeDrawer: $("#close-drawer"),
+};
+
+// ============================================================
+// Slider & Selection Bindings
+// ============================================================
+const sliders = [
+  { id: "chunk-size", stateKey: "chunk_size", valueId: "chunk-size-value" },
+  { id: "overlap", stateKey: "chunk_overlap", valueId: "overlap-value" },
+  {
+    id: "parent-size",
+    stateKey: "parent_chunk_size",
+    valueId: "parent-size-value",
+  },
+  {
+    id: "parent-overlap",
+    stateKey: "parent_chunk_overlap",
+    valueId: "parent-overlap-value",
+  },
+  {
+    id: "child-size",
+    stateKey: "child_chunk_size",
+    valueId: "child-size-value",
+  },
+  {
+    id: "child-overlap",
+    stateKey: "child_chunk_overlap",
+    valueId: "child-overlap-value",
+  },
+  { id: "n-neighbors", stateKey: "n_neighbors", valueId: "n-neighbors-value" },
+  {
+    id: "min-dist",
+    stateKey: "min_dist",
+    valueId: "min-dist-value",
+    isFloat: true,
+  },
+  {
+    id: "semantic-threshold",
+    stateKey: "semantic_threshold",
+    valueId: "semantic-threshold-value",
+    isFloat: true,
+  },
+];
+
+sliders.forEach(({ id, stateKey, valueId, isFloat }) => {
+  const slider = $(`#${id}`);
+  const badge = $(`#${valueId}`);
+  if (!slider || !badge) return;
+
+  slider.addEventListener("input", () => {
+    const val = isFloat ? parseFloat(slider.value) : parseInt(slider.value, 10);
+    state.config[stateKey] = val;
+    badge.textContent = isFloat ? val.toFixed(2) : val;
+  });
+});
+
+if (dom.embeddingModel) {
+  dom.embeddingModel.addEventListener("change", () => {
+    state.config.embedding_model = dom.embeddingModel.value;
+  });
+}
+
+// ============================================================
+// Interactive Tab Switching
+// ============================================================
+dom.tabButtons.forEach((btn) => {
+  btn.addEventListener("click", () => {
+    const targetTab = btn.dataset.tab;
+    state.activeTab = targetTab;
+
+    // Toggle active classes on buttons
+    dom.tabButtons.forEach((b) => b.classList.toggle("active", b === btn));
+
+    // Toggle active content panels
+    dom.tabContents.forEach((content) => {
+      const isTarget = content.id === targetTab;
+      content.classList.toggle("active", isTarget);
+      content.style.display = isTarget ? "flex" : "none";
+    });
+
+    // If switching to vector tab, let the canvas redraw itself
+    if (
+      targetTab === "vector-tab" &&
+      typeof window.drawVectorSpace === "function"
+    ) {
+      window.drawVectorSpace();
+    }
+  });
+});
+
+// ============================================================
+// Text Input
+// ============================================================
+dom.textInput.addEventListener("input", () => {
+  state.text = dom.textInput.value;
+  dom.charCount.textContent = `${state.text.length} chars`;
+});
+
+// ============================================================
+// Strategy Selector
+// ============================================================
+dom.strategyGrid.addEventListener("click", (e) => {
+  const card = e.target.closest(".strategy-card");
+  if (!card) return;
+
+  $$(".strategy-card").forEach((c) => c.classList.remove("active"));
+  card.classList.add("active");
+  card.querySelector('input[type="radio"]').checked = true;
+
+  state.strategy = card.dataset.strategy;
+  updateConfigVisibility();
+});
+
+function updateConfigVisibility() {
+  const isParentChild = state.strategy === "parent_child";
+  const isRecursive = state.strategy === "recursive";
+  const isSemantic = state.strategy === "semantic";
+
+  // Show/hide standard config (hide for parent_child and semantic)
+  dom.standardConfig.style.display =
+    isParentChild || isSemantic ? "none" : "block";
+
+  // Show/hide parent-child config
+  dom.parentChildConfig.classList.toggle("visible", isParentChild);
+
+  // Show/hide semantic config
+  if (dom.semanticConfig) {
+    dom.semanticConfig.style.display = isSemantic ? "block" : "none";
+  }
+
+  // Show/hide separators (for recursive and parent_child)
+  dom.separatorsSection.style.display =
+    isRecursive || isParentChild ? "block" : "none";
+}
+
+// ============================================================
+// Separator Tags
+// ============================================================
+function getSeparators() {
+  const tags = dom.separatorTags.querySelectorAll(".separator-tag");
+  if (tags.length === 0) return null;
+  return Array.from(tags).map((tag) => {
+    const raw = tag.dataset.sep;
+    // Convert escaped sequences back to real characters
+    return raw.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
+  });
+}
+
+// Remove separator tag
+dom.separatorTags.addEventListener("click", (e) => {
+  if (e.target.classList.contains("remove")) {
+    e.target.closest(".separator-tag").remove();
+  }
+});
+
+// Add separator tag
+dom.separatorInput.addEventListener("keydown", (e) => {
+  if (e.key === "Enter" && dom.separatorInput.value.trim()) {
+    e.preventDefault();
+    const val = dom.separatorInput.value;
+    const displayVal = val
+      .replace(/\n/g, "\\n")
+      .replace(/\t/g, "\\t")
+      .replace(/ /g, "⎵");
+    const tag = document.createElement("span");
+    tag.className = "separator-tag";
+    tag.dataset.sep = val;
+    tag.innerHTML = `<code>${escapeHtml(displayVal)}</code><span class="remove">&times;</span>`;
+    dom.separatorTags.insertBefore(tag, dom.separatorInput);
+    dom.separatorInput.value = "";
+  }
+});
+
+// ============================================================
+// API Call
+// ============================================================
+async function runChunking() {
+  if (state.isLoading || !state.text.trim()) return;
+
+  // Reset visualizer and search highlights
+  state.results = [];
+  state.activeChunkId = null;
+  unhighlightChunk();
+  dom.xrayText.classList.remove("search-active");
+
+  state.isLoading = true;
+  dom.btnRun.classList.add("loading");
+  dom.btnRun.classList.remove("ready");
+  dom.btnRun.disabled = true;
+
+  // Build request payload
+  const runConfig = { tokenizer: state.config.tokenizer };
+
+  if (state.strategy === "parent_child") {
+    runConfig.parent_chunk_size = state.config.parent_chunk_size;
+    runConfig.parent_chunk_overlap = state.config.parent_chunk_overlap;
+    runConfig.child_chunk_size = state.config.child_chunk_size;
+    runConfig.child_chunk_overlap = state.config.child_chunk_overlap;
+  } else if (state.strategy === "semantic") {
+    runConfig.semantic_threshold = state.config.semantic_threshold;
+  } else {
+    runConfig.chunk_size = state.config.chunk_size;
+    runConfig.chunk_overlap = state.config.chunk_overlap;
+  }
+
+  // Add separators if applicable
+  const separators = getSeparators();
+  if (
+    separators &&
+    (state.strategy === "recursive" || state.strategy === "parent_child")
+  ) {
+    runConfig.separators = separators;
+  }
+
+  const payload = {
+    text: state.text,
+    runs: [
+      {
+        strategy: state.strategy,
+        config: runConfig,
+      },
+    ],
+    embedding_model: state.config.embedding_model,
+    n_neighbors: state.config.n_neighbors,
+    min_dist: state.config.min_dist,
+  };
+
+  try {
+    const res = await fetch("/api/chunk", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (!res.ok) {
+      const err = await res.json();
+      console.error("API Error:", err);
+      alert(`API Error: ${JSON.stringify(err.detail || err)}`);
+      return;
+    }
+
+    const data = await res.json();
+    state.results = data.results[0]; // Single strategy for now
+    state.activeChunkId = null;
+
+    renderResults();
+  } catch (err) {
+    console.error("Network error:", err);
+    alert("Failed to connect to the API. Is the server running?");
+  } finally {
+    state.isLoading = false;
+    dom.btnRun.classList.remove("loading");
+    dom.btnRun.disabled = false;
+    dom.btnRun.classList.add("ready");
+  }
+}
+
+dom.btnRun.addEventListener("click", runChunking);
+
+// ============================================================
+// Rendering
+// ============================================================
+function renderResults() {
+  if (!state.results) return;
+
+  const { chunks, total_chunks, avg_token_count, total_tokens, strategy } =
+    state.results;
+
+  // Compute stats if backend returned 0s
+  const computedTotal = total_chunks || chunks.length;
+  const computedTotalTokens =
+    total_tokens || chunks.reduce((sum, c) => sum + c.token_count, 0);
+  const computedAvg =
+    avg_token_count ||
+    (computedTotal > 0 ? Math.round(computedTotalTokens / computedTotal) : 0);
+
+  // Update stats
+  dom.statTotal.textContent = computedTotal;
+  dom.statAvgTokens.textContent = computedAvg;
+  dom.statTotalTokens.textContent = computedTotalTokens;
+  dom.statStrategy.textContent = strategy;
+
+  // Render X-Ray viewer
+  renderXrayText(chunks);
+
+  // Render chunk list
+  renderChunkList(chunks);
+
+  // Initialize and draw Vector Space (Phase 2)
+  if (typeof window.initVectorSpace === "function") {
+    window.initVectorSpace(chunks);
+  }
+}
+
+// ============================================================
+// X-Ray Text Viewer — Highlight chunks in the original text
+// ============================================================
+function renderXrayText(chunks) {
+  dom.xrayEmpty.style.display = "none";
+  dom.xrayText.style.display = "block";
+
+  const text = state.text;
+  if (!text) return;
+
+  // 1. Create an array of "markers" for every character in the text
+  // Each marker will store which chunks "own" this character
+  const markers = Array.from({ length: text.length }, () => []);
+
+  chunks.forEach((chunk) => {
+    for (let i = chunk.start_char; i < chunk.end_char; i++) {
+      if (i >= 0 && i < markers.length) {
+        markers[i].push(chunk.id);
+      }
+    }
+  });
+
+  // 2. Build the HTML by grouping characters with the same "owners"
+  let html = "";
+  let currentOwnersId = null;
+  let currentBuffer = "";
+
+  for (let i = 0; i <= text.length; i++) {
+    const owners = markers[i] || [];
+    const ownersId = owners.join(",");
+
+    if (ownersId !== currentOwnersId) {
+      if (currentBuffer) {
+        if (!currentOwnersId) {
+          html += escapeHtml(currentBuffer);
+        } else {
+          const ownerList = currentOwnersId.split(",");
+          const isOverlap = ownerList.length > 1;
+          const primaryOwner = ownerList[0];
+          const colorIdx = (ownerList.length % 4) + 1;
+
+          html +=
+            `<span class="chunk-highlight${isOverlap ? " overlap-region" : ""}" ` +
+            `data-chunk-id="${primaryOwner}" ` +
+            `data-all-chunks="${currentOwnersId}" ` +
+            `data-color="${colorIdx}">` +
+            escapeHtml(currentBuffer) +
+            `</span>`;
+        }
+      }
+      currentOwnersId = ownersId;
+      currentBuffer = "";
+    }
+
+    if (i < text.length) {
+      currentBuffer += text[i];
+    }
+  }
+
+  dom.xrayText.innerHTML = html;
+
+  // Add hover/click listeners to highlights
+  dom.xrayText.querySelectorAll(".chunk-highlight").forEach((el) => {
+    el.addEventListener("mouseenter", () => highlightChunk(el.dataset.chunkId));
+    el.addEventListener("mouseleave", () => unhighlightChunk());
+    el.addEventListener("click", () => selectChunk(el.dataset.chunkId));
+  });
+}
+
+// ============================================================
+// Chunk List (Right Panel)
+// ============================================================
+function renderChunkList(chunks) {
+  let html = "";
+  let currentParentId = null;
+
+  chunks.forEach((chunk, index) => {
+    // Add parent label for parent-child strategy
+    if (chunk.level === 0 && state.strategy === "parent_child") {
+      html += `<div class="parent-child-label">📦 Parent</div>`;
+      currentParentId = chunk.id;
+    } else if (chunk.level === 1 && chunk.parent_id !== currentParentId) {
+      currentParentId = chunk.parent_id;
+    }
+
+    const preview =
+      chunk.text.length > 120 ? chunk.text.slice(0, 120) + "…" : chunk.text;
+
+    html += `
+      <div class="chunk-item" data-chunk-id="${chunk.id}" data-level="${chunk.level}" data-index="${index + 1}">
+        <div class="chunk-item-header">
+          <span class="chunk-item-id">${chunk.id}</span>
+          <div class="chunk-item-badges">
+            <span class="chunk-badge tokens">${chunk.token_count} tok</span>
+            <span class="chunk-badge">${chunk.end_char - chunk.start_char} chars</span>
+          </div>
+        </div>
+        <div class="chunk-item-text">${escapeHtml(preview)}</div>
+        <div class="chunk-item-meta">
+          <span>start: ${chunk.start_char}</span>
+          <span>end: ${chunk.end_char}</span>
+          ${chunk.parent_id ? `<span>parent: ${chunk.parent_id}</span>` : ""}
+        </div>
+      </div>
+    `;
+  });
+
+  dom.chunkList.innerHTML = html;
+
+  // Add click/hover listeners
+  dom.chunkList.querySelectorAll(".chunk-item").forEach((el) => {
+    el.addEventListener("mouseenter", () => highlightChunk(el.dataset.chunkId));
+    el.addEventListener("mouseleave", () => unhighlightChunk());
+    el.addEventListener("click", () => selectChunk(el.dataset.chunkId));
+  });
+}
+
+// ============================================================
+// Highlight / Selection Logic
+// ============================================================
+function highlightChunk(chunkId) {
+  // Highlight in X-ray viewer
+  dom.xrayText.querySelectorAll(".chunk-highlight").forEach((el) => {
+    el.classList.toggle("active", el.dataset.chunkId === chunkId);
+  });
+
+  // Highlight in chunk list
+  dom.chunkList.querySelectorAll(".chunk-item").forEach((el) => {
+    el.classList.toggle("active", el.dataset.chunkId === chunkId);
+  });
+}
+
+function unhighlightChunk() {
+  if (state.activeChunkId) {
+    // If a chunk is "selected" (clicked), keep it highlighted
+    highlightChunk(state.activeChunkId);
+    return;
+  }
+
+  dom.xrayText.querySelectorAll(".chunk-highlight.active").forEach((el) => {
+    el.classList.remove("active");
+  });
+  dom.chunkList.querySelectorAll(".chunk-item.active").forEach((el) => {
+    el.classList.remove("active");
+  });
+}
+
+window.selectChunk = function selectChunk(chunkId) {
+  // Toggle selection
+  state.activeChunkId = state.activeChunkId === chunkId ? null : chunkId;
+  if (state.activeChunkId) {
+    highlightChunk(state.activeChunkId);
+
+    // Scroll the chunk into view in the X-ray panel
+    const xrayEl = dom.xrayText.querySelector(`[data-chunk-id="${chunkId}"]`);
+    if (xrayEl) {
+      xrayEl.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+
+    // Scroll the chunk into view in the list
+    const listEl = dom.chunkList.querySelector(`[data-chunk-id="${chunkId}"]`);
+    if (listEl) {
+      listEl.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+  } else {
+    unhighlightChunk();
+  }
+};
+
+function escapeHtml(str) {
+  const div = document.createElement("div");
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+document.addEventListener("keydown", (e) => {
+  // Ctrl/Cmd + Enter to run
+  if ((e.ctrlKey || e.metaKey) && e.key === "Enter") {
+    e.preventDefault();
+    runChunking();
+  }
+});
+
+updateConfigVisibility();
+
+// Local visual state for canvas physics and scaling
+const vectorState = {
+  chunks: [], // Holds our active chunks
+  zoom: 1.0, // Scroll scale
+  pan: { x: 0, y: 0 }, // Drag offset
+  hoveredChunk: null, // Chunk under mouse cursor
+  selectedChunk: null, // Active clicked chunk
+  isDragging: false, // Drag state flag
+  dragStart: { x: 0, y: 0 },
+  activeQuery: null, // Active search query or sonar probe click
+
+  // High/low UMAP coordinates (for scaling math)
+  bounds: {
+    minX: 0,
+    maxX: 0,
+    minY: 0,
+    maxY: 0,
+  },
+};
+
+// Stubs for you to implement the magical vector space rendering:
+window.initVectorSpace = function (chunks) {
+  console.log("Initializing Vector Space with chunks:", chunks);
+  vectorState.chunks = chunks;
+
+  if (chunks.length > 0) {
+    const xs = chunks.map((c) => (c.coords_2d ? c.coords_2d[0] : 0));
+    const ys = chunks.map((c) => (c.coords_2d ? c.coords_2d[1] : 0));
+
+    vectorState.bounds.minX = Math.min(...xs);
+    vectorState.bounds.maxX = Math.max(...xs);
+    vectorState.bounds.minY = Math.min(...ys);
+    vectorState.bounds.maxY = Math.max(...ys);
+  }
+  const canvas = dom.vectorCanvas;
+  if (!canvas) return;
+
+  // Set logical dimensions matching the bounding box
+  const rect = canvas.parentNode.getBoundingClientRect();
+  canvas.width = rect.width * window.devicePixelRatio;
+  canvas.height = rect.height * window.devicePixelRatio;
+  canvas.style.width = "100%";
+  canvas.style.height = "100%";
+
+  // Center alignment resetting
+  vectorState.pan = { x: 0, y: 0 };
+  vectorState.zoom = 1.0;
+  vectorState.hoveredChunk = null;
+  vectorState.selectedChunk = null;
+  vectorState.activeQuery = null;
+
+  // Bind custom interactive event handlers
+  if (!canvas.dataset.listenersAttached) {
+    setupCanvasListeners(canvas);
+    canvas.dataset.listenersAttached = "true";
+  }
+
+  // Active smooth render animation loop
+  if (!window.animationLoopActive) {
+    startAnimationLoop();
+  }
+};
+
+window.animationLoopActive = false;
+function startAnimationLoop() {
+  window.animationLoopActive = true;
+  function tick() {
+    window.drawVectorSpace();
+    requestAnimationFrame(tick);
+  }
+  requestAnimationFrame(tick);
+}
+
+// Maps UMAP coordinates [x, y] to Canvas pixel coordinates [x, y]
+function mapToCanvas(umapX, umapY, width, height) {
+  const padding = 50; // Keeps dots from clipping the canvas edges
+  const { minX, maxX, minY, maxY } = vectorState.bounds;
+
+  // Avoid division by zero if all coordinates are identical
+  const rangeX = maxX - minX || 1;
+  const rangeY = maxY - minY || 1;
+
+  // 1. Normalize UMAP value to a percentage (0.0 to 1.0)
+  const pctX = (umapX - minX) / rangeX;
+  const pctY = (umapY - minY) / rangeY;
+
+  // 2. Map percentage to canvas size (with padding)
+  const canvasX = padding + pctX * (width - padding * 2);
+  const canvasY = padding + pctY * (height - padding * 2);
+
+  return { x: canvasX, y: canvasY };
+}
+
+window.drawVectorSpace = function () {
+  const canvas = dom.vectorCanvas;
+  if (!canvas) return;
+  const ctx = canvas.getContext("2d");
+
+  // Self-healing resize guard (handles hidden container init and window resizing)
+  const rect = canvas.parentNode.getBoundingClientRect();
+  const targetWidth = Math.floor(rect.width * window.devicePixelRatio);
+  const targetHeight = Math.floor(rect.height * window.devicePixelRatio);
+
+  if (canvas.width !== targetWidth || canvas.height !== targetHeight) {
+    if (rect.width > 0 && rect.height > 0) {
+      canvas.width = targetWidth;
+      canvas.height = targetHeight;
+      ctx.scale(window.devicePixelRatio, window.devicePixelRatio);
+    }
+  }
+
+  const width = canvas.width / window.devicePixelRatio;
+  const height = canvas.height / window.devicePixelRatio;
+
+  // Clear canvas
+  ctx.clearRect(0, 0, width, height);
+
+  // Apply Panning and Zooming transformations
+  ctx.save();
+  ctx.translate(vectorState.pan.x, vectorState.pan.y);
+  ctx.scale(vectorState.zoom, vectorState.zoom);
+
+  // A. DRAW GRID IN TRANSFORMED SPACE
+  ctx.strokeStyle = "rgba(15, 23, 42, 0.05)";
+  ctx.lineWidth = 1 / vectorState.zoom;
+  const gridSize = 40;
+
+  // Calculate bounding box in transformed space to draw grid infinite-scrolling
+  const startX = -vectorState.pan.x / vectorState.zoom;
+  const endX = (width - vectorState.pan.x) / vectorState.zoom;
+  const startY = -vectorState.pan.y / vectorState.zoom;
+  const endY = (height - vectorState.pan.y) / vectorState.zoom;
+
+  for (
+    let x = Math.floor(startX / gridSize) * gridSize;
+    x < endX;
+    x += gridSize
+  ) {
+    ctx.beginPath();
+    ctx.moveTo(x, startY);
+    ctx.lineTo(x, endY);
+    ctx.stroke();
+  }
+  for (
+    let y = Math.floor(startY / gridSize) * gridSize;
+    y < endY;
+    y += gridSize
+  ) {
+    ctx.beginPath();
+    ctx.moveTo(startX, y);
+    ctx.lineTo(endX, y);
+    ctx.stroke();
+  }
+
+  // B. DRAW PARENT-CHILD CONNECTION LINES
+  if (state.strategy === "parent_child") {
+    vectorState.chunks.forEach((chunk) => {
+      if (chunk.level === 1 && chunk.parent_id) {
+        const parent = vectorState.chunks.find((c) => c.id === chunk.parent_id);
+        if (parent && chunk.coords_2d && parent.coords_2d) {
+          const cpos = mapToCanvas(
+            chunk.coords_2d[0],
+            chunk.coords_2d[1],
+            width,
+            height,
+          );
+          const ppos = mapToCanvas(
+            parent.coords_2d[0],
+            parent.coords_2d[1],
+            width,
+            height,
+          );
+
+          ctx.beginPath();
+          ctx.strokeStyle = "rgba(245, 158, 11, 0.2)";
+          ctx.lineWidth = 1.5 / vectorState.zoom;
+          ctx.moveTo(ppos.x, ppos.y);
+          ctx.lineTo(cpos.x, cpos.y);
+          ctx.stroke();
+        }
+      }
+    });
+  } // C. DRAW ACTIVE RETRIEVAL LINES AND ANIMATIONS
+  if (vectorState.activeQuery) {
+    // Increment pulse radius for animation
+    vectorState.activeQuery.pulseRadius += 0.8;
+    if (vectorState.activeQuery.pulseRadius > 50) {
+      vectorState.activeQuery.pulseRadius = 0;
+    }
+
+    const qpos = mapToCanvas(
+      vectorState.activeQuery.x,
+      vectorState.activeQuery.y,
+      width,
+      height,
+    );
+
+    if (
+      vectorState.activeQuery.state === "fetching" ||
+      vectorState.activeQuery.state === "loaded"
+    ) {
+      // Flowing lines or loaded lines to topK
+      const topK = vectorState.activeQuery.topK || [];
+      if (vectorState.activeQuery.state === "fetching") {
+        vectorState.activeQuery.flowOffset =
+          (vectorState.activeQuery.flowOffset || 0) - 2;
+      }
+
+      topK.forEach((item, index) => {
+        if (item.chunk.coords_2d) {
+          const cpos = mapToCanvas(
+            item.chunk.coords_2d[0],
+            item.chunk.coords_2d[1],
+            width,
+            height,
+          );
+          ctx.beginPath();
+          ctx.strokeStyle = "rgba(245, 158, 11, 0.6)"; // Stronger gold
+          ctx.lineWidth = 2 / vectorState.zoom;
+          ctx.setLineDash([5, 5]);
+          ctx.lineDashOffset =
+            vectorState.activeQuery.state === "fetching"
+              ? vectorState.activeQuery.flowOffset
+              : 0;
+          ctx.moveTo(qpos.x, qpos.y);
+          ctx.lineTo(cpos.x, cpos.y);
+          ctx.stroke();
+          ctx.setLineDash([]);
+        }
+      });
+    }
+  }
+  // D. DRAW CHUNK PARTICLES
+  vectorState.chunks.forEach((chunk) => {
+    if (!chunk.coords_2d) return;
+
+    const cpos = mapToCanvas(
+      chunk.coords_2d[0],
+      chunk.coords_2d[1],
+      width,
+      height,
+    );
+
+    // Style according to strategy and highlights
+    let radius = 6;
+    let color = "#2563eb"; // Superman Blue default
+    let glowColor = "rgba(37, 99, 235, 0.15)";
+
+    const isHovered =
+      vectorState.hoveredChunk && vectorState.hoveredChunk.id === chunk.id;
+    const isSelected = state.activeChunkId === chunk.id;
+
+    if (state.strategy === "parent_child") {
+      if (chunk.level === 0) {
+        radius = 8;
+        color = "#f59e0b"; // Superman Gold Parent
+        glowColor = "rgba(245, 158, 11, 0.2)";
+      } else {
+        radius = 4.5;
+        color = "#2563eb"; // Superman Blue Child
+        glowColor = "rgba(37, 99, 235, 0.15)";
+      }
+    } else {
+      // Standard styles
+      radius = 5.5;
+      color = "#2563eb";
+      glowColor = "rgba(37, 99, 235, 0.15)";
+    }
+
+    // Dynamic scale-up on hover or selection (glowing Superman Red)
+    if (isHovered || isSelected) {
+      radius += 3;
+      color = "#ef4444"; // Superman Red
+      glowColor = isSelected
+        ? "rgba(239, 68, 68, 0.45)"
+        : "rgba(239, 68, 68, 0.25)";
+    }
+
+    // 1. Draw glowing background shadow ring
+    ctx.beginPath();
+    ctx.arc(cpos.x, cpos.y, radius + 4, 0, Math.PI * 2);
+    ctx.fillStyle = glowColor;
+    ctx.fill();
+
+    // 2. Draw solid particle
+    ctx.beginPath();
+    ctx.arc(cpos.x, cpos.y, radius, 0, Math.PI * 2);
+    ctx.fillStyle = color;
+    ctx.strokeStyle = "#ffffff"; // Clean white border outline for Light Mode
+    ctx.lineWidth = 1.5;
+    ctx.fill();
+    ctx.stroke();
+
+    // 3. Draw highlighted white core on selection
+    if (isSelected) {
+      ctx.beginPath();
+      ctx.arc(cpos.x, cpos.y, 2, 0, Math.PI * 2);
+      ctx.fillStyle = "#ffffff";
+      ctx.fill();
+    }
+
+    // 4. Rank 1 Sun Glow if loaded
+    if (
+      vectorState.activeQuery &&
+      vectorState.activeQuery.state === "loaded" &&
+      vectorState.activeQuery.topK &&
+      vectorState.activeQuery.topK.length > 0
+    ) {
+      if (chunk.id === vectorState.activeQuery.topK[0].chunk.id) {
+        // Pulsing sun glow radius
+        const sunRadius = 15 + Math.sin(Date.now() / 300) * 5;
+        ctx.beginPath();
+        ctx.arc(cpos.x, cpos.y, sunRadius, 0, Math.PI * 2);
+        ctx.fillStyle = "rgba(245, 158, 11, 0.3)";
+        ctx.fill();
+        ctx.beginPath();
+        ctx.arc(cpos.x, cpos.y, radius + 2, 0, Math.PI * 2);
+        ctx.fillStyle = "#f59e0b"; // Solid gold core
+        ctx.fill();
+      }
+    }
+  });
+
+  // E. DRAW ACTIVE QUERY & SONAR PING SHOCKWAVES
+  if (vectorState.activeQuery) {
+    const qpos = mapToCanvas(
+      vectorState.activeQuery.x,
+      vectorState.activeQuery.y,
+      width,
+      height,
+    );
+
+    // 1. Draw Sonar ripple pulse rings (Superman Red wave)
+    ctx.beginPath();
+    ctx.arc(
+      qpos.x,
+      qpos.y,
+      vectorState.activeQuery.pulseRadius,
+      0,
+      Math.PI * 2,
+    );
+    ctx.strokeStyle = `rgba(239, 68, 68, ${1 - vectorState.activeQuery.pulseRadius / 50})`;
+    ctx.lineWidth = 1.5 / vectorState.zoom;
+    ctx.stroke();
+
+    // 2. Draw outer glowing ring (Superman Red base)
+    ctx.beginPath();
+    ctx.arc(qpos.x, qpos.y, 8, 0, Math.PI * 2);
+    ctx.fillStyle = "rgba(239, 68, 68, 0.15)";
+    ctx.strokeStyle = "#ef4444";
+    ctx.lineWidth = 1.5 / vectorState.zoom;
+    ctx.fill();
+    ctx.stroke();
+
+    // 3. Draw crosshair target center
+    ctx.beginPath();
+    ctx.arc(qpos.x, qpos.y, 2, 0, Math.PI * 2);
+    ctx.fillStyle = "#ef4444";
+    ctx.fill();
+
+    // 4. Draw a small floating text label for the query
+    ctx.fillStyle = "#475569"; // Dark muted slate text for excellent light mode readability
+    ctx.font = `${Math.max(8, 10 / vectorState.zoom)}px var(--font-sans)`;
+    ctx.textAlign = "center";
+    ctx.fillText(
+      vectorState.activeQuery.label || "Sonar Query",
+      qpos.x,
+      qpos.y - 12,
+    );
+  }
+
+  ctx.restore();
+};
+
+function setupCanvasListeners(canvas) {
+  const getMousePos = (e) => {
+    const rect = canvas.getBoundingClientRect();
+    return {
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top,
+    };
+  };
+
+  canvas.addEventListener("mousedown", (e) => {
+    const pos = getMousePos(e);
+    vectorState.isDragging = true;
+    vectorState.dragStart = {
+      x: pos.x - vectorState.pan.x,
+      y: pos.y - vectorState.pan.y,
+    };
+  });
+
+  canvas.addEventListener("mousemove", (e) => {
+    const pos = getMousePos(e);
+    const width = canvas.width / window.devicePixelRatio;
+    const height = canvas.height / window.devicePixelRatio;
+
+    if (vectorState.isDragging) {
+      // Pan canvas
+      vectorState.pan.x = pos.x - vectorState.dragStart.x;
+      vectorState.pan.y = pos.y - vectorState.dragStart.y;
+    } else {
+      // Hover detection
+      const tx = (pos.x - vectorState.pan.x) / vectorState.zoom;
+      const ty = (pos.y - vectorState.pan.y) / vectorState.zoom;
+
+      let found = null;
+      let minDistance = Infinity;
+
+      vectorState.chunks.forEach((chunk) => {
+        if (!chunk.coords_2d) return;
+        const cpos = mapToCanvas(
+          chunk.coords_2d[0],
+          chunk.coords_2d[1],
+          width,
+          height,
+        );
+        const dist = Math.hypot(cpos.x - tx, cpos.y - ty);
+
+        if (dist < 12 && dist < minDistance) {
+          minDistance = dist;
+          found = chunk;
+        }
+      });
+
+      if (found !== vectorState.hoveredChunk) {
+        vectorState.hoveredChunk = found;
+        if (found) {
+          highlightChunk(found.id);
+          showTooltip(found, pos.x, pos.y);
+        } else {
+          unhighlightChunk();
+          hideTooltip();
+        }
+      }
+    }
+  });
+
+  canvas.addEventListener("mouseup", () => {
+    vectorState.isDragging = false;
+  });
+
+  canvas.addEventListener("mouseleave", () => {
+    vectorState.isDragging = false;
+    vectorState.hoveredChunk = null;
+    unhighlightChunk();
+    hideTooltip();
+  });
+
+  canvas.addEventListener(
+    "wheel",
+    (e) => {
+      e.preventDefault();
+      const pos = getMousePos(e);
+
+      // Decreased sensitivity with a smooth exponential multiplier
+      const zoomFactor = 1 - e.deltaY * 0.0006;
+      const prevZoom = vectorState.zoom;
+
+      // Smoothly clamp zoom scale between 0.15 and 8.0
+      vectorState.zoom = Math.min(
+        Math.max(vectorState.zoom * zoomFactor, 0.15),
+        8.0,
+      );
+
+      // Zoom centering physics
+      vectorState.pan.x =
+        pos.x - (pos.x - vectorState.pan.x) * (vectorState.zoom / prevZoom);
+      vectorState.pan.y =
+        pos.y - (pos.y - vectorState.pan.y) * (vectorState.zoom / prevZoom);
+    },
+    { passive: false },
+  );
+
+  canvas.addEventListener("click", (e) => {
+    if (vectorState.isDragging) return;
+    const pos = getMousePos(e);
+    const width = canvas.width / window.devicePixelRatio;
+    const height = canvas.height / window.devicePixelRatio;
+
+    const tx = (pos.x - vectorState.pan.x) / vectorState.zoom;
+    const ty = (pos.y - vectorState.pan.y) / vectorState.zoom;
+
+    let clickedNode = null;
+    let minDistance = Infinity;
+
+    vectorState.chunks.forEach((chunk) => {
+      if (!chunk.coords_2d) return;
+      const cpos = mapToCanvas(
+        chunk.coords_2d[0],
+        chunk.coords_2d[1],
+        width,
+        height,
+      );
+      const dist = Math.hypot(cpos.x - tx, cpos.y - ty);
+      if (dist < 12 && dist < minDistance) {
+        minDistance = dist;
+        clickedNode = chunk;
+      }
+    });
+
+    if (clickedNode) {
+      selectChunk(clickedNode.id);
+    } else {
+      // Probe click to trigger Sonar RAG retrieval!
+      triggerSonarProbe(tx, ty);
+    }
+  });
+}
+
+function showTooltip(chunk, x, y) {
+  const tooltip = dom.vectorTooltip;
+  if (!tooltip) return;
+
+  const snippet =
+    chunk.text.length > 80 ? chunk.text.slice(0, 80) + "..." : chunk.text;
+  const coordsStr = `[${chunk.coords_2d[0].toFixed(2)}, ${chunk.coords_2d[1].toFixed(2)}]`;
+
+  tooltip.style.display = "block";
+  tooltip.style.left = `${x + 15}px`;
+  tooltip.style.top = `${y + 15}px`;
+  tooltip.innerHTML = `
+    <div class="vector-tooltip-title">
+      <span>${chunk.id}</span>
+      <span class="vector-tooltip-coords">${coordsStr}</span>
+    </div>
+    <div style="font-size: 0.65rem; color: var(--text-tertiary); margin-bottom: var(--space-xs);">
+      ${chunk.token_count} tokens | ${chunk.text.length} chars
+    </div>
+    <div class="vector-tooltip-text">${escapeHtml(snippet)}</div>
+  `;
+}
+
+function hideTooltip() {
+  const tooltip = dom.vectorTooltip;
+  if (tooltip) tooltip.style.display = "none";
+}
+
+function triggerSonarProbe(tx, ty) {
+  const canvas = dom.vectorCanvas;
+  const width = canvas.width / window.devicePixelRatio;
+  const height = canvas.height / window.devicePixelRatio;
+
+  // Convert canvas position [tx, ty] back to UMAP [x, y] coordinates
+  const padding = 50;
+  const { minX, maxX, minY, maxY } = vectorState.bounds;
+  const rangeX = maxX - minX || 1;
+  const rangeY = maxY - minY || 1;
+
+  const pctX = (tx - padding) / (width - padding * 2);
+  const pctY = (ty - padding) / (height - padding * 2);
+
+  const umapX = minX + pctX * rangeX;
+  const umapY = minY + pctY * rangeY;
+
+  // Perform similarity distance in 2D space to prepare topK
+  const scoredChunks = vectorState.chunks
+    .map((chunk) => {
+      if (!chunk.coords_2d) return { chunk, dist: Infinity };
+      const dist = Math.hypot(
+        chunk.coords_2d[0] - umapX,
+        chunk.coords_2d[1] - umapY,
+      );
+      return { chunk, dist };
+    })
+    .sort((a, b) => a.dist - b.dist);
+
+  const topK = scoredChunks.slice(0, 3);
+
+  // Set active query crosshair
+  vectorState.activeQuery = {
+    x: umapX,
+    y: umapY,
+    tx: tx,
+    ty: ty,
+    pulseRadius: 0,
+    label: "Sonar Probe",
+    state: "loaded",
+    topK: topK,
+  };
+
+  // Render RAG results drawer
+  dom.queryResultsDrawer.style.display = "block";
+  dom.queryResultsList.innerHTML = topK
+    .map((item, index) => {
+      const similarity = Math.max(0, 1 - item.dist / 1.5).toFixed(2); // Normalised distance
+      const snippet =
+        item.chunk.text.length > 100
+          ? item.chunk.text.slice(0, 100) + "..."
+          : item.chunk.text;
+      const rankClass = index === 0 ? "rank-1" : "";
+      return `
+      <div class="retrieved-chunk-card ${rankClass}" onclick="selectChunk('${item.chunk.id}')">
+        <div class="retrieved-chunk-meta">
+          <span class="retrieved-chunk-rank">Rank ${index + 1} (${item.chunk.id})</span>
+          <span class="retrieved-chunk-score">Match Score: ${similarity}</span>
+        </div>
+        <div class="retrieved-chunk-text">${escapeHtml(snippet)}</div>
+      </div>
+    `;
+    })
+    .join("");
+}
+
+async function runQuerySimulator() {
+  const queryText = dom.queryInput.value.trim();
+  if (!queryText || !state.results || vectorState.chunks.length === 0) return;
+
+  dom.btnQuery.disabled = true;
+  dom.btnQuery.textContent = "⚡ Search...";
+
+  try {
+    console.log("Running Query against ChromaDB:", queryText);
+
+    // Reset camera view so the user can see the entire map
+    vectorState.zoom = 1.0;
+    vectorState.pan = { x: 0, y: 0 };
+
+    // Setup active query skeleton state (fetching)
+    // We start at [0,0] and will update the actual coordinates once the server responds
+    vectorState.activeQuery = {
+      x: 0,
+      y: 0,
+      tx: 0,
+      ty: 0,
+      pulseRadius: 0,
+      label: `Query: "${queryText.substring(0, 15)}"`,
+      state: "fetching",
+      flowOffset: 0,
+      topK: [],
+    };
+
+    dom.queryResultsDrawer.style.display = "block";
+    dom.queryResultsList.innerHTML = `
+      <div class="skeleton-loader"></div>
+      <div class="skeleton-loader"></div>
+      <div class="skeleton-loader"></div>
+    `;
+
+    // Make the actual API call to the backend
+    const res = await fetch("/api/retrieve", {
+      method: "POST", // Needs to be POST to send a JSON body!
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        search_text: queryText,
+        embedding_model: state.config.embedding_model,
+        strategy: state.strategy,
+        top_k: 3,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP error! status: ${res.status}`);
+    }
+
+    const data = await res.json();
+
+    // Parse the query coordinates returned by UMAP
+    const targetX = data.query_coords[0];
+    const targetY = data.query_coords[1];
+
+    const canvas = dom.vectorCanvas;
+    const width = canvas.width / window.devicePixelRatio;
+    const height = canvas.height / window.devicePixelRatio;
+
+    // Dynamically expand bounds to fit the query dot if it lands far away
+    if (vectorState.chunks.length > 0) {
+      vectorState.bounds.minX = Math.min(vectorState.bounds.minX, targetX);
+      vectorState.bounds.maxX = Math.max(vectorState.bounds.maxX, targetX);
+      vectorState.bounds.minY = Math.min(vectorState.bounds.minY, targetY);
+      vectorState.bounds.maxY = Math.max(vectorState.bounds.maxY, targetY);
+    }
+
+    const screenPos = mapToCanvas(targetX, targetY, width, height);
+
+    // Link the retrieved results back to the frontend chunks for drawing lines
+    const topK = data.results.map((result) => {
+      // Find the corresponding chunk in the frontend's loaded chunks
+      const chunk = vectorState.chunks.find((c) => c.id === result.id) || {
+        id: result.id,
+        text: result.text,
+        coords_2d: null, // Fallback if chunk somehow isn't loaded
+      };
+      return {
+        chunk: chunk,
+        dist: result.score,
+        text_highlighted: result.text_highlighted,
+      };
+    });
+
+    // Update the active query with the final data
+    vectorState.activeQuery = {
+      x: targetX,
+      y: targetY,
+      tx: screenPos.x,
+      ty: screenPos.y,
+      pulseRadius: 0,
+      label: `Query: "${queryText.substring(0, 15)}"`,
+      state: "loaded",
+      flowOffset: 0,
+      topK: topK,
+    };
+
+    // Render results in the drawer
+    dom.queryResultsList.innerHTML = topK
+      .map((item, index) => {
+        return `
+        <div class="query-result-item" style="border-left-color: ${index === 0 ? "var(--warning-color)" : "var(--info-color)"}">
+          <div class="query-result-header">
+            <span class="rank-badge" style="color: ${index === 0 ? "var(--warning-color)" : "var(--info-color)"}">Rank ${index + 1} (${item.chunk.id})</span>
+            <span class="dist-badge">Dist: ${item.dist.toFixed(3)}</span>
+          </div>
+          <div class="query-result-text">${item.text_highlighted || escapeHtml(item.chunk.text.substring(0, 100)) + "..."}</div>
+        </div>
+      `;
+      })
+      .join("");
+
+    // --- TASK 3.4: X-RAY DOCUMENT HIGHLIGHTING ---
+    // 1. Activate the search mode on the X-Ray text to dim non-retrieved chunks
+    dom.xrayText.classList.add("search-active");
+
+    // 2. Clear any previous search rankings
+    dom.xrayText.querySelectorAll(".chunk-highlight").forEach((el) => {
+      el.classList.remove(
+        "retrieved-rank-1",
+        "retrieved-rank-2",
+        "retrieved-rank-3",
+      );
+    });
+
+    // 3. Highlight the new Top-K chunks in the Document Viewer
+    topK.forEach((item, index) => {
+      const rank = index + 1;
+      const chunkId = item.chunk.id;
+      const span = dom.xrayText.querySelector(`[data-chunk-id="${chunkId}"]`);
+
+      if (span) {
+        span.classList.add(`retrieved-rank-${rank}`);
+        // If it's the #1 hit, scroll the Document Viewer straight to it!
+        if (rank === 1) {
+          span.scrollIntoView({ behavior: "smooth", block: "center" });
+        }
+      }
+    });
+    // ----------------------------------------------
+  } catch (err) {
+    console.error("Query failed:", err);
+    dom.queryResultsList.innerHTML = `<div style="color: #ef4444; padding: 1rem;">Failed to fetch results. Check console.</div>`;
+  } finally {
+    dom.btnQuery.disabled = false;
+    dom.btnQuery.innerHTML = "🔍 Query";
+  }
+}
+
+// Bind Query events
+if (dom.btnQuery) {
+  dom.btnQuery.addEventListener("click", runQuerySimulator);
+}
+if (dom.queryInput) {
+  dom.queryInput.addEventListener("keydown", (e) => {
+    if (e.key === "Enter") {
+      runQuerySimulator();
+    }
+  });
+}
+if (dom.closeDrawer) {
+  dom.closeDrawer.addEventListener("click", () => {
+    dom.queryResultsDrawer.style.display = "none";
+  });
+}
+
+// ============================================================
+// TASK 3.5: ARENA COMPARISON LOGIC
+// ============================================================
+const domArena = {
+  modal: document.getElementById("arena-modal"),
+  btnOpen: document.getElementById("btn-open-arena"),
+  btnClose: document.getElementById("btn-close-arena"),
+  btnFight: document.getElementById("btn-arena-fight"),
+  queryInput: document.getElementById("arena-query-input"),
+  modelA: document.getElementById("arena-model-a"),
+  strategyA: document.getElementById("arena-strategy-a"),
+  resultsA: document.getElementById("arena-results-a"),
+  modelB: document.getElementById("arena-model-b"),
+  strategyB: document.getElementById("arena-strategy-b"),
+  resultsB: document.getElementById("arena-results-b"),
+};
+
+if (domArena.btnOpen) {
+  domArena.btnOpen.addEventListener("click", () => {
+    domArena.modal.style.display = "flex";
+    if (dom.queryInput && dom.queryInput.value) {
+      domArena.queryInput.value = dom.queryInput.value;
+    }
+  });
+}
+
+if (domArena.btnClose) {
+  domArena.btnClose.addEventListener("click", () => {
+    domArena.modal.style.display = "none";
+  });
+}
+
+if (domArena.btnFight) {
+  domArena.btnFight.addEventListener("click", async () => {
+    const query = domArena.queryInput.value.trim();
+    if (!query) return;
+
+    domArena.btnFight.disabled = true;
+    domArena.btnFight.textContent = "FIGHTING...";
+
+    // Reset AI Referee if active
+    if (typeof domReferee !== "undefined" && domReferee.panel) {
+      domReferee.panel.style.display = "none";
+      domReferee.verdictBox.style.display = "none";
+      domReferee.loadingBox.style.display = "none";
+      domReferee.triggerBox.style.display = "block";
+    }
+
+    domArena.resultsA.innerHTML =
+      '<div class="skeleton-loader"></div><div class="skeleton-loader"></div>';
+    domArena.resultsB.innerHTML =
+      '<div class="skeleton-loader"></div><div class="skeleton-loader"></div>';
+
+    try {
+      const res = await fetch("/api/compare", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          search_text: query,
+          top_k: 3,
+          model_a: domArena.modelA.value,
+          strategy_a: domArena.strategyA.value,
+          model_b: domArena.modelB.value,
+          strategy_b: domArena.strategyB.value,
+        }),
+      });
+
+      if (!res.ok)
+        throw new Error(
+          "Comparison failed. Check if server is running and /api/compare exists.",
+        );
+
+      const data = await res.json();
+
+      // Render Column A
+      domArena.resultsA.innerHTML = data.results_a
+        .map(
+          (chunk, i) => `
+        <div class="query-result-item" style="border-left-color: var(--warning-color)">
+          <div class="query-result-header">
+            <span class="rank-badge" style="color: var(--warning-color)">Rank ${i + 1}</span>
+            <span class="dist-badge">Dist: ${chunk.score.toFixed(3)}</span>
+          </div>
+          <div class="query-result-text">${chunk.text_highlighted || escapeHtml(chunk.text)}</div>
+        </div>
+      `,
+        )
+        .join("");
+
+      // Render Column B
+      domArena.resultsB.innerHTML = data.results_b
+        .map(
+          (chunk, i) => `
+        <div class="query-result-item" style="border-left-color: var(--info-color)">
+          <div class="query-result-header">
+            <span class="rank-badge" style="color: var(--info-color)">Rank ${i + 1}</span>
+            <span class="dist-badge">Dist: ${chunk.score.toFixed(3)}</span>
+          </div>
+          <div class="query-result-text">${chunk.text_highlighted || escapeHtml(chunk.text)}</div>
+        </div>
+      `,
+        )
+        .join("");
+
+      // Activate AI Referee if both sides retrieved chunks
+      if (
+        typeof domReferee !== "undefined" &&
+        domReferee.panel &&
+        data.results_a.length > 0 &&
+        data.results_b.length > 0
+      ) {
+        domReferee.panel.style.display = "block";
+        domReferee.btnCall.dataset.query = query;
+        domReferee.btnCall.dataset.chunkA = data.results_a[0].text;
+        domReferee.btnCall.dataset.chunkB = data.results_b[0].text;
+      }
+    } catch (err) {
+      console.error(err);
+      domArena.resultsA.innerHTML = `<div style="color: var(--superman-red); padding: 1rem;">Error: ${err.message}</div>`;
+      domArena.resultsB.innerHTML = `<div style="color: var(--superman-red); padding: 1rem;">Error: ${err.message}</div>`;
+    } finally {
+      domArena.btnFight.disabled = false;
+      domArena.btnFight.textContent = "🔥 FIGHT!";
+    }
+  });
+}
+
+// ============================================================
+// TASK 5.1: AI REFEREE / LLM-AS-A-JUDGE LOGIC
+// ============================================================
+const domReferee = {
+  panel: document.getElementById("arena-referee-panel"),
+  triggerBox: document.getElementById("referee-trigger-box"),
+  btnCall: document.getElementById("btn-call-referee"),
+  loadingBox: document.getElementById("referee-loading-box"),
+  statusText: document.getElementById("referee-status-text"),
+  verdictBox: document.getElementById("referee-verdict-box"),
+};
+
+if (domReferee.btnCall) {
+  domReferee.btnCall.addEventListener("click", async () => {
+    const query = domReferee.btnCall.dataset.query;
+    const chunkA = domReferee.btnCall.dataset.chunkA;
+    const chunkB = domReferee.btnCall.dataset.chunkB;
+    if (!query || !chunkA || !chunkB) return;
+
+    // Capture user-selected model names for clean revealed scorecard display
+    const labelA = domArena.modelA.options[domArena.modelA.selectedIndex].text;
+    const labelB = domArena.modelB.options[domArena.modelB.selectedIndex].text;
+
+    domReferee.triggerBox.style.display = "none";
+    domReferee.loadingBox.style.display = "block";
+    domReferee.verdictBox.style.display = "none";
+
+    const statuses = [
+      "⚖️ Summoning Gemma evaluation referee...",
+      "🔍 Blinding model names and metadata...",
+      "🧠 Auditing Corner A relevance and clarity...",
+      "🧠 Auditing Corner B completeness and truthfulness...",
+      "📊 Aggregating overall dimensional scores...",
+      "✍️ Draft verdict and writing final card...",
+    ];
+    let statusIdx = 0;
+    domReferee.statusText.textContent = statuses[0];
+    const statusInterval = setInterval(() => {
+      statusIdx = (statusIdx + 1) % statuses.length;
+      domReferee.statusText.textContent = statuses[statusIdx];
+    }, 1500);
+
+    try {
+      const res = await fetch("/api/judge", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          search_query: query,
+          chunk_a: chunkA,
+          chunk_b: chunkB,
+        }),
+      });
+
+      if (!res.ok)
+        throw new Error(
+          "Gemma evaluation failed. Check if local Ollama server is running.",
+        );
+
+      const data = await res.json();
+      clearInterval(statusInterval);
+
+      renderRefereeScorecard(data, labelA, labelB);
+    } catch (err) {
+      clearInterval(statusInterval);
+      console.error(err);
+      domReferee.verdictBox.innerHTML = `
+        <div style="color: var(--superman-red); text-align: center; padding: 1.5rem; border: 1px solid var(--superman-red-glow); border-radius: 6px; background-color: var(--superman-red-muted);">
+          <strong>Referee Error:</strong> ${err.message}
+        </div>
+      `;
+      domReferee.verdictBox.style.display = "block";
+    } finally {
+      domReferee.loadingBox.style.display = "none";
+    }
+  });
+}
+
+function renderRefereeScorecard(data, labelA, labelB) {
+  const isA = data.winner === "chunk_a";
+  const isB = data.winner === "chunk_b";
+  const isTie = data.winner === "tie";
+
+  let winnerColor = "var(--superman-yellow)";
+  let winnerBanner = "⚖️ IT'S A TIE";
+  if (isA) {
+    winnerColor = "var(--superman-yellow)";
+    winnerBanner = `🏆 ${labelA.toUpperCase()} WINS`;
+  } else if (isB) {
+    winnerColor = "var(--superman-blue)";
+    winnerBanner = `🏆 ${labelB.toUpperCase()} WINS`;
+  }
+
+  // Dynamically replace blinded chunk labels with actual bolded model names
+  const boldLabelA = `<strong>${labelA}</strong>`;
+  const boldLabelB = `<strong>${labelB}</strong>`;
+
+  let cleanedReason = data.winner_reason.trim();
+  // Strip leading/trailing quote characters
+  cleanedReason = cleanedReason
+    .replace(/^["']/, "")
+    .replace(/["']$/, "")
+    .trim();
+  // Collapse any newlines or multiple whitespace characters to a single space for single-line display
+  cleanedReason = cleanedReason.replace(/\r?\n|\r/g, " ").replace(/\s+/g, " ");
+
+  cleanedReason = cleanedReason
+    .replace(/\b(Chunk A|chunk_a|chunk A)\b/g, boldLabelA)
+    .replace(/\b(Chunk B|chunk_b|chunk B)\b/g, boldLabelB);
+
+  const scoreCardHtml = `
+    <div class="verdict-banner" style="background-color: ${winnerColor}-muted; border-color: ${winnerColor};">
+      <div class="verdict-title" style="color: ${winnerColor}">${winnerBanner}</div>
+      <div class="verdict-confidence">Confidence: ${(data.confidence * 100).toFixed(0)}%</div>
+    </div>
+    
+    <div class="verdict-reason">
+      <strong>Verdict Reason:</strong>
+      <p>${cleanedReason}</p>
+      <div class="deciding-factor">Deciding Factor: <code>${data.deciding_dimension}</code></div>
+    </div>
+
+    <!-- Comparative Table of dimensions -->
+    <div class="referee-scores-table">
+      <div class="scores-table-header">
+        <span class="score-col-label">Criterion</span>
+        <span class="score-col-val" style="font-size: 0.65rem; color: var(--superman-yellow);">${labelA}</span>
+        <span class="score-col-bar">Comparison</span>
+        <span class="score-col-val" style="font-size: 0.65rem; color: var(--superman-blue);">${labelB}</span>
+      </div>
+      
+      ${renderScoreRow("Query Relevance", data.chunk_a_score.query_relevance, data.chunk_b_score.query_relevance)}
+      ${renderScoreRow("Completeness", data.chunk_a_score.answer_completeness, data.chunk_b_score.answer_completeness)}
+      ${renderScoreRow("Plausibility", data.chunk_a_score.factual_plausibility, data.chunk_b_score.factual_plausibility)}
+      ${renderScoreRow("Clarity & Style", data.chunk_a_score.clarity, data.chunk_b_score.clarity)}
+      
+      <div class="scores-table-row overall-row">
+        <span class="score-col-label"><strong>Overall Average</strong></span>
+        <span class="score-col-val" style="color: var(--superman-yellow)"><strong>${data.chunk_a_score.overall.toFixed(2)}</strong></span>
+        <span class="score-col-bar">
+          <div class="overall-progress-bar">
+            <div class="overall-val-a" style="width: ${data.chunk_a_score.overall * 10}%"></div>
+            <div class="overall-val-b" style="width: ${data.chunk_b_score.overall * 10}%"></div>
+          </div>
+        </span>
+        <span class="score-col-val" style="color: var(--superman-blue)"><strong>${data.chunk_b_score.overall.toFixed(2)}</strong></span>
+      </div>
+    </div>
+
+    <!-- Strengths & Weaknesses Column -->
+    <div class="verdict-details-grid">
+      <div class="verdict-details-col">
+        <h4>${labelA} Analysis</h4>
+        <div class="verdict-list-title strength-list-title">🟢 Strengths</div>
+        <ul>
+          ${data.chunk_a_strengths.map((s) => `<li>${escapeHtml(s)}</li>`).join("")}
+        </ul>
+        <div class="verdict-list-title weakness-list-title">🔴 Weaknesses</div>
+        <ul>
+          ${data.chunk_a_weaknesses.map((w) => `<li>${escapeHtml(w)}</li>`).join("")}
+        </ul>
+      </div>
+      
+      <div class="verdict-details-col">
+        <h4>${labelB} Analysis</h4>
+        <div class="verdict-list-title strength-list-title">🟢 Strengths</div>
+        <ul>
+          ${data.chunk_b_strengths.map((s) => `<li>${escapeHtml(s)}</li>`).join("")}
+        </ul>
+        <div class="verdict-list-title weakness-list-title">🔴 Weaknesses</div>
+        <ul>
+          ${data.chunk_b_weaknesses.map((w) => `<li>${escapeHtml(w)}</li>`).join("")}
+        </ul>
+      </div>
+    </div>
+  `;
+
+  domReferee.verdictBox.innerHTML = scoreCardHtml;
+  domReferee.verdictBox.style.display = "block";
+}
+
+function renderScoreRow(label, valA, valB) {
+  const pctA = valA * 10;
+  const pctB = valB * 10;
+
+  return `
+    <div class="scores-table-row">
+      <span class="score-col-label">${label}</span>
+      <span class="score-col-val">${valA}/10</span>
+      <span class="score-col-bar">
+        <div class="score-progress-bar">
+          <div class="score-val-a" style="width: ${pctA}%"></div>
+          <div class="score-val-b" style="width: ${pctB}%"></div>
+        </div>
+      </span>
+      <span class="score-col-val">${valB}/10</span>
+    </div>
+  `;
+}

frontend/index.html

@@ -0,0 +1,391 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="description" content="RAG Visualizer — An X-Ray machine for RAG pipelines. Visualize and compare chunking strategies." />
+  <title>RAG Visualizer — Chunking Lab</title>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body>
+  <div class="app-wrapper">
+
+    <!-- ========== HEADER ========== -->
+    <header class="app-header">
+      <div class="app-logo">
+        <div class="app-logo-icon">🔬</div>
+        <div class="app-logo-text">RAG <span>Visualizer</span></div>
+      </div>
+    </header>
+
+    <!-- ========== MAIN 3-COLUMN LAYOUT ========== -->
+    <main class="app-main">
+
+      <!-- ===== LEFT PANEL: Configuration ===== -->
+      <aside class="panel" id="config-panel">
+        <div class="panel-header">
+          <h2><span class="icon">⚙️</span> Configuration</h2>
+        </div>
+        <div class="panel-body">
+
+          <!-- Text Input -->
+          <div class="config-section">
+            <div class="config-section-title">Input Text</div>
+            <div class="text-input-wrapper">
+              <textarea
+                id="text-input"
+                class="text-input"
+                placeholder="Paste your text here to visualize chunking strategies..."
+                spellcheck="false"
+              ></textarea>
+              <span class="char-count" id="char-count">0 chars</span>
+            </div>
+          </div>
+
+          <!-- Strategy Selector -->
+          <div class="config-section">
+            <div class="config-section-title">Chunking Strategy</div>
+            <div class="strategy-grid" id="strategy-grid">
+              <label class="strategy-card active" data-strategy="fixed_size">
+                <input type="radio" name="strategy" value="fixed_size" checked />
+                <div class="strategy-card-icon">📏</div>
+                <div class="strategy-card-name">Fixed Size</div>
+                <div class="strategy-card-desc">Cut every N tokens</div>
+              </label>
+              <label class="strategy-card" data-strategy="sentence">
+                <input type="radio" name="strategy" value="sentence" />
+                <div class="strategy-card-icon">💬</div>
+                <div class="strategy-card-name">Sentence</div>
+                <div class="strategy-card-desc">Split on boundaries</div>
+              </label>
+              <label class="strategy-card" data-strategy="recursive">
+                <input type="radio" name="strategy" value="recursive" />
+                <div class="strategy-card-icon">🔄</div>
+                <div class="strategy-card-name">Recursive</div>
+                <div class="strategy-card-desc">Hierarchy of separators</div>
+              </label>
+              <label class="strategy-card" data-strategy="parent_child">
+                <input type="radio" name="strategy" value="parent_child" />
+                <div class="strategy-card-icon">🌳</div>
+                <div class="strategy-card-name">Parent-Child</div>
+                <div class="strategy-card-desc">Nested chunking</div>
+              </label>
+              <label class="strategy-card" data-strategy="semantic">
+                <input type="radio" name="strategy" value="semantic" />
+                <div class="strategy-card-icon">🧠</div>
+                <div class="strategy-card-name">Semantic</div>
+                <div class="strategy-card-desc">Split on topic shifts</div>
+              </label>
+            </div>
+          </div>
+
+          <!-- Standard Config Sliders -->
+          <div class="config-section" id="standard-config">
+            <div class="config-section-title">Parameters</div>
+            <div class="config-field">
+              <label>
+                Chunk Size (tokens)
+                <span class="value-badge" id="chunk-size-value">500</span>
+              </label>
+              <input type="range" id="chunk-size" min="50" max="2000" step="50" value="500" />
+            </div>
+            <div class="config-field">
+              <label>
+                Overlap (tokens)
+                <span class="value-badge" id="overlap-value">20</span>
+              </label>
+              <input type="range" id="overlap" min="0" max="500" step="10" value="20" />
+            </div>
+          </div>
+
+          <!-- Parent-Child Config (Hidden by default) -->
+          <div class="parent-child-config" id="parent-child-config">
+            <div class="pc-section-label parent">🔵 Parent Config</div>
+            <div class="config-field">
+              <label>
+                Parent Chunk Size
+                <span class="value-badge" id="parent-size-value">1000</span>
+              </label>
+              <input type="range" id="parent-size" min="100" max="4000" step="100" value="1000" />
+            </div>
+            <div class="config-field">
+              <label>
+                Parent Overlap
+                <span class="value-badge" id="parent-overlap-value">100</span>
+              </label>
+              <input type="range" id="parent-overlap" min="0" max="500" step="10" value="100" />
+            </div>
+            <div class="pc-section-label child">🟢 Child Config</div>
+            <div class="config-field">
+              <label>
+                Child Chunk Size
+                <span class="value-badge" id="child-size-value">200</span>
+              </label>
+              <input type="range" id="child-size" min="50" max="1000" step="50" value="200" />
+            </div>
+            <div class="config-field">
+              <label>
+                Child Overlap
+                <span class="value-badge" id="child-overlap-value">20</span>
+              </label>
+              <input type="range" id="child-overlap" min="0" max="200" step="10" value="20" />
+            </div>
+          </div>
+
+          <!-- Semantic Config (Hidden by default) -->
+          <div class="config-section" id="semantic-config" style="display: none;">
+            <div class="config-section-title">Semantic Settings</div>
+            <div class="config-field">
+              <label>
+                Similarity Threshold
+                <span class="value-badge" id="semantic-threshold-value">0.50</span>
+              </label>
+              <input type="range" id="semantic-threshold" min="0.1" max="1.0" step="0.05" value="0.5" />
+            </div>
+          </div>
+
+          <!-- Separators (for recursive) -->
+          <div class="config-section" id="separators-section" style="display: none;">
+            <div class="config-section-title">Separators</div>
+            <div class="separator-tags" id="separator-tags">
+              <span class="separator-tag" data-sep="\n\n"><code>\\n\\n</code><span class="remove">&times;</span></span>
+              <span class="separator-tag" data-sep="\n"><code>\\n</code><span class="remove">&times;</span></span>
+              <span class="separator-tag" data-sep=". "><code>. </code><span class="remove">&times;</span></span>
+              <span class="separator-tag" data-sep=" "><code>⎵</code><span class="remove">&times;</span></span>
+              <input type="text" class="separator-input" id="separator-input" placeholder="Add..." />
+            </div>
+          </div>
+
+          <!-- Embedding & Vector Space Config -->
+          <div class="config-section">
+            <div class="config-section-title">Vector Space Settings</div>
+            
+            <div class="config-field">
+              <label for="embedding-model">Embedding Model</label>
+              <select id="embedding-model" class="select-input">
+                <option value="nomic-embed-text" selected>Nomic Embed Text</option>
+                <option value="EmbeddingGemma">Embedding Gemma</option>
+                <option value="qwen3-embedding:0.6b">Qwen3 Embedding</option>
+              </select>
+            </div>
+
+            <div class="config-field">
+              <label>
+                UMAP n_neighbors
+                <span class="value-badge" id="n-neighbors-value">15</span>
+              </label>
+              <input type="range" id="n-neighbors" min="2" max="100" step="1" value="15" />
+            </div>
+
+            <div class="config-field">
+              <label>
+                UMAP min_dist
+                <span class="value-badge" id="min-dist-value">0.10</span>
+              </label>
+              <input type="range" id="min-dist" min="0.01" max="1.0" step="0.05" value="0.1" />
+            </div>
+          </div>
+
+          <!-- Run Button -->
+          <button class="btn-run ready" id="btn-run">
+            <span class="spinner"></span>
+            <span class="btn-text">⚡ Run Chunking</span>
+          </button>
+
+        </div>
+      </aside>
+
+      <!-- ===== CENTER PANEL: X-Ray Text Viewer & Vector Space ===== -->
+      <section class="panel xray-viewer" id="xray-panel">
+        <div class="panel-header tabs-header">
+          <div class="tab-buttons">
+            <button class="tab-btn active" data-tab="xray-tab">
+              <span class="icon">🔍</span> Document Viewer
+            </button>
+            <button class="tab-btn" data-tab="vector-tab">
+              <span class="icon">🌌</span> Vector Space 2D
+            </button>
+          </div>
+        </div>
+        
+        <!-- Tab Content 1: X-Ray Text Viewer -->
+        <div class="panel-body tab-content active" id="xray-tab">
+          <div class="empty-state" id="xray-empty">
+            <div class="empty-state-icon">🔬</div>
+            <div class="empty-state-title">Ready to Analyze</div>
+            <div class="empty-state-desc">
+              Paste your text, choose a chunking strategy, and hit <strong>Run</strong> to see how your text gets sliced.
+            </div>
+          </div>
+          <div class="xray-text-container" id="xray-text" style="display: none;"></div>
+        </div>
+
+        <!-- Tab Content 2: Vector Space 2D -->
+        <div class="panel-body tab-content" id="vector-tab" style="display: none;">
+          <div class="vector-space-container">
+            <div class="canvas-wrapper">
+              <canvas id="vector-canvas"></canvas>
+              <!-- Floating Tooltip inside canvas -->
+              <div id="vector-tooltip" class="vector-tooltip" style="display: none;"></div>
+              
+              <!-- Help overlay for canvas controls -->
+              <div class="canvas-help-overlay">
+                <span>🖱️ Drag to Pan</span>
+                <span>☸️ Scroll to Zoom</span>
+                <span>✨ Click node to select</span>
+              </div>
+            </div>
+            
+            <!-- Sonar Query Simulator Section -->
+            <div class="query-simulator-section">
+              <div class="query-section-title" style="display: flex; justify-content: space-between; align-items: center;">
+                <span>🔮 Sonar Query Simulator (RAG Retrieval)</span>
+                <button id="btn-open-arena" class="btn-sm" style="background: var(--superman-red); color: white; border: none; padding: 4px 12px; border-radius: 4px; cursor: pointer; font-weight: bold; font-family: var(--font-sans);">⚔️ Arena Comparison</button>
+              </div>
+              <div class="query-input-wrapper">
+                <input type="text" id="query-input" placeholder="Type a concept query to fetch semantically similar chunks (e.g. 'linear regression')..." />
+                <button id="btn-query" class="btn-query">🔍 Query</button>
+              </div>
+              <div class="query-results-drawer" id="query-results-drawer" style="display: none;">
+                <div class="drawer-header">
+                  <h3>Retrieved Context</h3>
+                  <span class="close-drawer" id="close-drawer">&times;</span>
+                </div>
+                <div class="query-results-list" id="query-results-list">
+                  <!-- Retrieved chunks will go here -->
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ===== RIGHT PANEL: Chunk Inspector ===== -->
+      <aside class="panel" id="inspector-panel">
+        <div class="panel-header">
+          <h2><span class="icon">📊</span> Chunk Inspector</h2>
+        </div>
+        <div class="panel-body">
+          <!-- Stats -->
+          <div class="stats-grid" id="stats-grid">
+            <div class="stat-card">
+              <div class="stat-value" id="stat-total">—</div>
+              <div class="stat-label">Total Chunks</div>
+            </div>
+            <div class="stat-card">
+              <div class="stat-value" id="stat-avg-tokens">—</div>
+              <div class="stat-label">Avg Tokens</div>
+            </div>
+            <div class="stat-card">
+              <div class="stat-value" id="stat-total-tokens">—</div>
+              <div class="stat-label">Total Tokens</div>
+            </div>
+            <div class="stat-card">
+              <div class="stat-value" id="stat-strategy">—</div>
+              <div class="stat-label">Strategy</div>
+            </div>
+          </div>
+
+          <!-- Chunk List -->
+          <div class="config-section-title">Chunks</div>
+          <div class="chunk-list" id="chunk-list">
+            <div class="empty-state" style="min-height: 200px;">
+              <div class="empty-state-desc">Run chunking to see results here</div>
+            </div>
+          </div>
+        </div>
+      </aside>
+
+      <!-- ===== THE ARENA MODAL ===== -->
+      <div id="arena-modal" class="arena-modal-overlay" style="display: none;">
+        <div class="arena-modal-content">
+          <div class="arena-header">
+            <h2>⚔️ The Grand Comparison Arena</h2>
+            <button id="btn-close-arena" class="btn-close-arena">&times;</button>
+          </div>
+          
+          <div class="arena-query-bar">
+            <input type="text" id="arena-query-input" placeholder="Type a query to compare configurations (e.g., 'What is Clark Kent's weakness?')..." />
+            <button class="btn-run" id="btn-arena-fight" style="width: 150px; flex-shrink: 0;">🔥 FIGHT!</button>
+          </div>
+
+          <div class="arena-body">
+            <div class="arena-columns">
+              <!-- COLUMN A -->
+              <div class="arena-col">
+                <div class="arena-col-header">
+                  <h3>Corner A</h3>
+                  <div class="arena-config-row">
+                    <select id="arena-model-a" class="select-input">
+                      <option value="nomic-embed-text">Nomic Embed</option>
+                      <option value="EmbeddingGemma">Gemma Embed</option>
+                      <option value="qwen3-embedding:0.6b">Qwen3 Embed</option>
+                    </select>
+                    <select id="arena-strategy-a" class="select-input">
+                      <option value="fixed_size">Fixed Size</option>
+                      <option value="sentence">Sentence</option>
+                      <option value="recursive">Recursive</option>
+                      <option value="semantic">Semantic</option>
+                    </select>
+                  </div>
+                </div>
+                <div class="arena-results-list" id="arena-results-a">
+                  <div style="text-align: center; color: var(--text-tertiary); padding: 2rem;">Awaiting challengers...</div>
+                </div>
+              </div>
+
+              <!-- COLUMN B -->
+              <div class="arena-col">
+                <div class="arena-col-header" style="border-bottom-color: var(--info-color);">
+                  <h3>Corner B</h3>
+                  <div class="arena-config-row">
+                    <select id="arena-model-b" class="select-input">
+                      <option value="nomic-embed-text">Nomic Embed</option>
+                      <option value="EmbeddingGemma">Gemma Embed</option>
+                      <option value="qwen3-embedding:0.6b">Qwen3 Embed</option>
+                    </select>
+                    <select id="arena-strategy-b" class="select-input">
+                      <option value="fixed_size">Fixed Size</option>
+                      <option value="sentence">Sentence</option>
+                      <option value="recursive">Recursive</option>
+                      <option value="semantic">Semantic</option>
+                    </select>
+                  </div>
+                </div>
+                <div class="arena-results-list" id="arena-results-b">
+                  <div style="text-align: center; color: var(--text-tertiary); padding: 2rem;">Awaiting challengers...</div>
+                </div>
+              </div>
+            </div>
+
+            <!-- THE AI REFEREE PANEL (TASK 5.1) -->
+            <div class="arena-referee-panel" id="arena-referee-panel" style="display: none;">
+              <div class="referee-divider">
+                <span class="referee-badge">⚖️ THE AI REFEREE</span>
+              </div>
+              
+              <div class="referee-trigger-box" id="referee-trigger-box">
+                <p class="referee-prompt-text">Call upon the local Gemma model to analyze, score, and judge both contexts!</p>
+                <button class="btn-run" id="btn-call-referee" style="margin: 0 auto; display: block; max-width: 250px;">⚖️ CALL THE REFEREE</button>
+              </div>
+
+              <!-- Loading scanner status -->
+              <div class="referee-loading-box" id="referee-loading-box" style="display: none;">
+                <div class="skeleton-loader" style="max-width: 400px; margin: 0 auto 1rem; border-radius: 6px;"></div>
+                <div class="referee-status-text" id="referee-status-text">Summoning Gemma to review the case...</div>
+              </div>
+
+              <!-- Scorecard Verdict Display -->
+              <div class="referee-verdict-box" id="referee-verdict-box" style="display: none;"></div>
+            </div>
+          </div>
+
+        </div>
+      </div>
+
+    </main>
+  </div>
+
+  <script src="/static/app.js"></script>
+</body>
+</html>

frontend/styles.css

@@ -0,0 +1,1899 @@
+/* ============================================================
+   RAG Visualizer — Chunking Lab Design System
+   Theme: Superman High-Contrast Color-Blocked Light Mode
+   Palette: Blue #2563eb | Red #ef4444 | Gold #f59e0b
+   ============================================================ */
+
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Roboto+Condensed:wght@400;700&display=swap');
+
+/* --- Design Tokens --- */
+:root {
+  /* Surface Colors */
+  --bg-root: #f8fafc;
+  --bg-surface: #ffffff;
+  --bg-surface-raised: #f1f5f9;
+  --bg-surface-overlay: #e2e8f0;
+  --bg-input: #f8fafc;
+
+  /* Borders */
+  --border-subtle: rgba(15, 23, 42, 0.05);
+  --border-default: rgba(15, 23, 42, 0.09);
+  --border-active: rgba(37, 99, 235, 0.35);
+
+  /* Text Colors */
+  --text-primary: #0f172a;
+  --text-secondary: #475569;
+  --text-tertiary: #64748b;
+  --text-inverse: #ffffff;
+
+  /* Superman Blue — Structural (borders, headers, outlines, secondary data) */
+  --superman-blue: #2563eb;
+  --superman-blue-hover: #1d4ed8;
+  --superman-blue-muted: rgba(37, 99, 235, 0.08);
+  --superman-blue-glow: rgba(37, 99, 235, 0.2);
+
+  /* Superman Red — Action/Attention (CTA buttons, active states, query nodes) */
+  --superman-red: #ef4444;
+  --superman-red-hover: #dc2626;
+  --superman-red-muted: rgba(239, 68, 68, 0.08);
+  --superman-red-glow: rgba(239, 68, 68, 0.2);
+
+  /* Superman Gold — Interactive/Highlight (slider thumbs, Rank 1, connecting lines) */
+  --superman-yellow: #f59e0b;
+  --superman-yellow-hover: #d97706;
+  --superman-yellow-muted: rgba(245, 158, 11, 0.08);
+  --superman-yellow-glow: rgba(245, 158, 11, 0.2);
+
+  /* Functional Accent — Default to Blue for structural context */
+  --accent: var(--superman-blue);
+  --accent-hover: var(--superman-blue-hover);
+  --accent-muted: var(--superman-blue-muted);
+  --accent-glow: var(--superman-blue-glow);
+
+  /* Chunk Highlight Colors */
+  --chunk-color-1: var(--superman-blue);
+  --chunk-color-2: var(--superman-red);
+  --chunk-color-3: var(--superman-yellow);
+  --chunk-color-4: #818cf8;
+
+  /* Semantic */
+  --success: #16a34a;
+  --warning: #d97706;
+  --error: #dc2626;
+  --info: #2563eb;
+
+  /* Spacing */
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 16px;
+  --space-lg: 24px;
+  --space-xl: 32px;
+  --space-2xl: 48px;
+
+  /* Radius */
+  --radius-sm: 6px;
+  --radius-md: 10px;
+  --radius-lg: 16px;
+  --radius-xl: 20px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 3px rgba(15, 23, 42, 0.05);
+  --shadow-md: 0 4px 16px rgba(15, 23, 42, 0.06);
+  --shadow-lg: 0 10px 36px rgba(15, 23, 42, 0.08);
+  --shadow-glow-red: 0 0 20px var(--superman-red-glow);
+  --shadow-glow-blue: 0 0 20px var(--superman-blue-glow);
+  --shadow-glow-gold: 0 0 20px var(--superman-yellow-glow);
+
+  /* Transitions */
+  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-base: 250ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-slow: 400ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Typography */
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+  --font-heading: 'Roboto Condensed', 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+}
+
+/* --- Kryptonite Protocol (Error States) --- */
+.text-kryptonite {
+  color: #22c55e !important;
+}
+.bg-kryptonite-wash {
+  background-color: rgba(34, 197, 94, 0.1) !important;
+  border: 1px solid #22c55e !important;
+}
+
+/* --- Reset & Base --- */
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html {
+  font-size: 14px;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font-family: var(--font-sans);
+  background: var(--bg-root);
+  color: var(--text-primary);
+  line-height: 1.6;
+  min-height: 100vh;
+  overflow-x: hidden;
+}
+
+/* Subtle dot grid texture */
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  background-image:
+    radial-gradient(circle at 1px 1px, rgba(148, 163, 184, 0.03) 1px, transparent 0);
+  background-size: 32px 32px;
+  pointer-events: none;
+  z-index: 0;
+}
+
+/* --- Scrollbar --- */
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--text-tertiary); border-radius: 99px; }
+::-webkit-scrollbar-thumb:hover { background: var(--text-secondary); }
+
+/* --- Layout --- */
+.app-wrapper {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+/* ============================================================
+   1. HEADER — Blue-to-Red gradient logo, frosted glass bar
+   ============================================================ */
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--space-md) var(--space-xl);
+  border-bottom: 1px solid var(--border-default);
+  background: rgba(255, 255, 255, 0.85);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+  position: sticky;
+  top: 0;
+  z-index: 100;
+}
+
+.app-logo {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+/* Logo icon: Blue-to-Red gradient */
+.app-logo-icon {
+  width: 32px;
+  height: 32px;
+  background: linear-gradient(90deg, #2563eb 0%, #ef4444 100%);
+  border-radius: var(--radius-sm);
+  display: grid;
+  place-items: center;
+  font-size: 16px;
+}
+
+.app-logo-text {
+  font-weight: 700;
+  font-size: 1.15rem;
+  letter-spacing: -0.02em;
+}
+
+/* "Visualizer" span in Blue */
+.app-logo-text span {
+  color: var(--superman-blue);
+}
+
+.app-header-badge {
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--superman-blue);
+  background: var(--superman-blue-muted);
+  padding: 2px 10px;
+  border-radius: 99px;
+  border: 1px solid rgba(37, 99, 235, 0.2);
+}
+
+/* ============================================================
+   2. MAIN CONTENT — 3 Column Grid
+   ============================================================ */
+.app-main {
+  display: grid;
+  grid-template-columns: 300px 1fr 340px;
+  gap: 0;
+  flex: 1;
+  overflow: hidden;
+}
+
+/* --- Panels --- */
+.panel {
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid var(--border-default);
+  overflow-y: auto;
+  height: calc(100vh - 57px);
+}
+
+.panel:last-child {
+  border-right: none;
+}
+
+.panel-header {
+  padding: var(--space-md) var(--space-lg);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-surface);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.panel-header h2 {
+  font-family: var(--font-heading);
+  font-size: 1rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-secondary);
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+.panel-header h2 .icon {
+  font-size: 1rem;
+}
+
+/* Sidebar Panel Header Overrides */
+#config-panel .panel-header,
+#inspector-panel .panel-header {
+  border-bottom: none;
+  background: transparent;
+  padding-bottom: var(--space-xs);
+}
+
+#config-panel .panel-header h2,
+#inspector-panel .panel-header h2 {
+  font-family: var(--font-heading);
+  font-size: 1.15rem;
+  font-weight: 700;
+  text-transform: none;
+  letter-spacing: normal;
+  color: var(--text-primary);
+}
+
+.panel-body {
+  padding: var(--space-lg);
+  flex: 1;
+  overflow-y: auto;
+}
+
+/* ============================================================
+   3. CONFIG PANEL (Left Sidebar)
+   ============================================================ */
+.config-section {
+  margin-bottom: var(--space-xl);
+}
+
+.config-section-title {
+  font-family: var(--font-heading);
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--text-tertiary);
+  margin-bottom: var(--space-md);
+}
+
+/* --- Strategy Selector Cards --- */
+.strategy-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--space-sm);
+}
+
+.strategy-card {
+  position: relative;
+  padding: var(--space-md);
+  background-color: #ffffff;
+  border: 1px solid #e5e7eb;
+  border-top: 4px solid var(--superman-blue);
+  border-radius: 10px;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+  text-align: center;
+  overflow: hidden;
+}
+
+.strategy-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 10px 15px -3px rgba(37, 99, 235, 0.15);
+  border-color: var(--superman-blue);
+}
+
+/* Active strategy card: White background, thicker blue border, corner badge */
+.strategy-card.active {
+  border: 2px solid var(--superman-blue);
+  border-top: 4px solid var(--superman-blue);
+  background-color: #ffffff;
+  box-shadow: 0 10px 15px -3px rgba(37, 99, 235, 0.25), var(--shadow-glow-blue);
+}
+
+/* Corner badge for active strategy */
+.strategy-card.active::after {
+  content: '✓';
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: 24px;
+  height: 24px;
+  background-color: var(--superman-red);
+  color: #ffffff;
+  font-size: 12px;
+  font-weight: bold;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-bottom-left-radius: 4px;
+}
+
+.strategy-card input[type="radio"] {
+  display: none;
+}
+
+.strategy-card-icon {
+  font-size: 1.4rem;
+  margin-bottom: var(--space-xs);
+}
+
+.strategy-card-name {
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.strategy-card-desc {
+  font-size: 0.65rem;
+  color: var(--text-tertiary);
+  margin-top: 2px;
+}
+
+/* --- Sliders (Blue track, Gold thumb) --- */
+.config-field {
+  margin-bottom: var(--space-lg);
+}
+
+.config-field label {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  font-family: var(--font-heading);
+  font-size: 0.85rem;
+  font-weight: 700;
+  color: var(--text-secondary);
+  margin-bottom: var(--space-sm);
+}
+
+/* Value badges in Blue */
+.config-field .value-badge {
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  font-weight: 500;
+  color: var(--superman-blue);
+  background: var(--superman-blue-muted);
+  padding: 1px 8px;
+  border-radius: 99px;
+}
+
+/* Slider track: thin Blue */
+input[type="range"] {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 100%;
+  height: 4px;
+  background: linear-gradient(90deg, var(--superman-blue-muted) 0%, rgba(37, 99, 235, 0.15) 100%);
+  border-radius: 99px;
+  outline: none;
+  cursor: pointer;
+}
+
+/* Slider thumb: Superman Gold */
+input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--superman-yellow);
+  border: 2px solid var(--bg-surface);
+  box-shadow: 0 0 8px var(--superman-yellow-glow);
+  cursor: pointer;
+  transition: transform var(--transition-fast);
+}
+
+input[type="range"]::-webkit-slider-thumb:hover {
+  transform: scale(1.2);
+  box-shadow: 0 0 12px var(--superman-yellow-glow);
+}
+
+input[type="range"]::-moz-range-thumb {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--superman-yellow);
+  border: 2px solid var(--bg-surface);
+  box-shadow: 0 0 8px var(--superman-yellow-glow);
+  cursor: pointer;
+}
+
+/* --- Text Input --- */
+.text-input-wrapper {
+  position: relative;
+}
+
+.text-input {
+  width: 100%;
+  min-height: 120px;
+  padding: var(--space-md);
+  background: var(--bg-input);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 0.78rem;
+  line-height: 1.7;
+  resize: vertical;
+  outline: none;
+  transition: border-color var(--transition-base), box-shadow var(--transition-base);
+}
+
+.text-input:focus {
+  border-color: var(--superman-blue);
+  box-shadow: 0 0 0 3px var(--superman-blue-muted);
+}
+
+.text-input::placeholder {
+  color: var(--text-tertiary);
+}
+
+.char-count {
+  position: absolute;
+  bottom: var(--space-sm);
+  right: var(--space-md);
+  font-size: 0.65rem;
+  font-family: var(--font-mono);
+  color: var(--text-tertiary);
+}
+
+/* --- Separators Input --- */
+.separator-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs);
+  padding: var(--space-sm);
+  background: var(--bg-input);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  min-height: 36px;
+  cursor: text;
+}
+
+.separator-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  background: var(--bg-surface-overlay);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  color: var(--text-secondary);
+}
+
+.separator-tag .remove {
+  cursor: pointer;
+  color: var(--text-tertiary);
+  font-size: 0.85rem;
+  line-height: 1;
+  transition: color var(--transition-fast);
+}
+
+.separator-tag .remove:hover {
+  color: var(--superman-red);
+}
+
+.separator-input {
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  flex: 1;
+  min-width: 60px;
+}
+
+/* ============================================================
+   4. RUN BUTTON — Superman Red CTA (primary action)
+   ============================================================ */
+.btn-run {
+  width: 100%;
+  padding: var(--space-md) var(--space-lg);
+  background: linear-gradient(135deg, var(--superman-red), var(--superman-red-hover));
+  color: var(--text-inverse);
+  font-family: var(--font-sans);
+  font-size: 0.85rem;
+  font-weight: 700;
+  border: none;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: all var(--transition-base);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  position: relative;
+  overflow: hidden;
+}
+
+.btn-run::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(135deg, transparent, rgba(255, 255, 255, 0.15));
+  opacity: 0;
+  transition: opacity var(--transition-base);
+}
+
+.btn-run:hover::before {
+  opacity: 1;
+}
+
+.btn-run:hover {
+  transform: translateY(-1px);
+  box-shadow: var(--shadow-glow-red), var(--shadow-md);
+}
+
+.btn-run:active {
+  transform: translateY(0);
+}
+
+.btn-run:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
+}
+
+.btn-run:disabled:hover::before {
+  opacity: 0;
+}
+
+.btn-run .spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-top-color: var(--text-inverse);
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+  display: none;
+}
+
+.btn-run.loading .spinner {
+  display: block;
+}
+
+.btn-run.loading .btn-text {
+  display: none;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Pulse animation for Run button — Red glow */
+@keyframes pulse-glow-red {
+  0%, 100% { box-shadow: 0 0 8px var(--superman-red-glow); }
+  50% { box-shadow: 0 0 20px var(--superman-red-glow), 0 0 40px rgba(239, 68, 68, 0.1); }
+}
+
+.btn-run.ready {
+  animation: pulse-glow-red 2s ease-in-out infinite;
+}
+
+/* ============================================================
+   5. CENTER PANEL — Tabs (Document Viewer / Vector Space 2D)
+   ============================================================ */
+.xray-viewer {
+  position: relative;
+}
+
+/* --- Interactive Tabs Navigation --- */
+.tabs-header {
+  padding: 0 !important;
+}
+.tab-buttons {
+  display: flex;
+  height: 56px;
+  width: 100%;
+}
+
+/* Tab button: Blue text, no background highlight */
+.tab-btn {
+  flex: 1;
+  background: transparent;
+  border: none;
+  border-bottom: 3px solid transparent;
+  color: var(--text-secondary);
+  font-family: var(--font-sans);
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm);
+  transition: all var(--transition-base);
+}
+
+.tab-btn:hover {
+  color: var(--text-primary);
+  background: transparent;
+}
+
+/* Active tab: 3px solid Red bottom border, Red text, NO background tint */
+.tab-btn.active {
+  color: var(--superman-red);
+  border-bottom-color: var(--superman-red);
+  background: transparent;
+}
+
+/* --- Tab Content Visibility --- */
+.tab-content {
+  display: none !important;
+}
+.tab-content.active {
+  display: flex !important;
+  flex-direction: column;
+}
+
+/* --- X-Ray Text Container --- */
+.xray-text-container {
+  font-family: var(--font-mono);
+  font-size: 0.8rem;
+  line-height: 2;
+  white-space: pre-wrap;
+  word-break: break-word;
+  padding: var(--space-lg);
+  position: relative;
+}
+
+/* Chunk highlights in the text */
+.chunk-highlight {
+  position: relative;
+  border-radius: 3px;
+  padding: 1px 0;
+  border-left: 3px solid var(--superman-red); /* "Cape" Accent */
+  transition: all var(--transition-fast);
+  cursor: pointer;
+}
+
+/* ============================================================
+   RETRIEVAL X-RAY HIGHLIGHTS (TASK 3.4)
+   ============================================================ */
+.xray-content.search-active .chunk-highlight {
+  opacity: 0.3;
+  transition: all 0.3s ease;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-1 {
+  opacity: 1.0;
+  background-color: rgba(255, 165, 0, 0.4);
+  box-shadow: 0 0 12px rgba(255, 165, 0, 0.6);
+  border-top: 2px solid var(--warning-color);
+  border-bottom: 2px solid var(--warning-color);
+  z-index: 10;
+  position: relative;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-2 {
+  opacity: 0.9;
+  background-color: rgba(255, 165, 0, 0.25);
+  border-top: 2px dashed rgba(255, 165, 0, 0.6);
+  border-bottom: 2px dashed rgba(255, 165, 0, 0.6);
+  z-index: 9;
+  position: relative;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-3 {
+  opacity: 0.8;
+  background-color: rgba(255, 165, 0, 0.15);
+  border-top: 2px dotted rgba(255, 165, 0, 0.4);
+  border-bottom: 2px dotted rgba(255, 165, 0, 0.4);
+  z-index: 8;
+  position: relative;
+}
+
+/* Lexical Heatmap Highlights */
+.query-result-text mark,
+.retrieved-chunk-text mark {
+  background-color: rgba(245, 158, 11, 0.22); /* Superman Gold Muted */
+  color: #b45309; /* Highly readable deep amber */
+  border-bottom: 2px solid var(--superman-yellow);
+  font-weight: 600;
+  padding: 1px 3px;
+  border-radius: 3px;
+  transition: all 0.2s ease;
+}
+
+.query-result-text mark:hover,
+.retrieved-chunk-text mark:hover {
+  background-color: rgba(245, 158, 11, 0.35);
+  color: #78350f;
+  cursor: help;
+}
+
+
+/* ============================================================
+   THE GRAND COMPARISON ARENA (TASK 3.5)
+   ============================================================ */
+.arena-modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(15, 23, 42, 0.9);
+  backdrop-filter: blur(8px);
+  z-index: 9999;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.arena-modal-content {
+  background: var(--bg-surface);
+  width: 90vw;
+  height: 90vh;
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-xl);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid var(--border-default);
+}
+
+.arena-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: var(--space-md) var(--space-xl);
+  background: var(--bg-surface-elevated);
+  border-bottom: 1px solid var(--border-default);
+}
+
+.arena-header h2 {
+  margin: 0;
+  font-size: 1.25rem;
+  color: var(--superman-red);
+}
+
+.btn-close-arena {
+  background: none;
+  border: none;
+  color: var(--text-secondary);
+  font-size: 1.5rem;
+  cursor: pointer;
+}
+
+.btn-close-arena:hover {
+  color: var(--superman-red);
+}
+
+.arena-query-bar {
+  display: flex;
+  padding: var(--space-lg) var(--space-xl);
+  gap: var(--space-md);
+  background: var(--bg-surface-elevated);
+  border-bottom: 1px solid var(--border-default);
+}
+
+.arena-query-bar input {
+  flex: 1;
+  padding: var(--space-md) var(--space-lg);
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-default);
+  background: var(--bg-surface);
+  color: var(--text-primary);
+  font-size: 1rem;
+}
+
+.arena-columns {
+  display: flex;
+  height: 385px;
+  flex-shrink: 0;
+  border-bottom: 1px solid var(--border-default);
+}
+
+.arena-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0 0 var(--space-xl) 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.arena-col {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid var(--border-default);
+}
+.arena-col:last-child {
+  border-right: none;
+}
+
+.arena-col-header {
+  padding: var(--space-md) var(--space-xl);
+  border-bottom: 2px solid var(--warning-color);
+  background: rgba(255, 255, 255, 0.02);
+}
+
+.arena-col-header h3 {
+  margin: 0 0 var(--space-sm) 0;
+  font-size: 1.1rem;
+  font-weight: 700;
+  color: var(--text-primary);
+}
+
+.arena-config-row {
+  display: flex;
+  gap: var(--space-sm);
+}
+
+.arena-config-row select {
+  flex: 1;
+}
+
+.arena-results-list {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--space-xl);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-md);
+}
+
+/* Low opacity wash of primary colors, no underlines */
+.chunk-highlight[data-color="1"] { background: rgba(37, 99, 235, 0.1); }
+.chunk-highlight[data-color="2"] { background: rgba(239, 68, 68, 0.1); }
+.chunk-highlight[data-color="3"] { background: rgba(245, 158, 11, 0.1); }
+.chunk-highlight[data-color="4"] { background: rgba(129, 140, 248, 0.1); }
+
+.chunk-highlight.active[data-color="1"] { background: rgba(37, 99, 235, 0.25); box-shadow: 0 0 12px rgba(37, 99, 235, 0.15); }
+.chunk-highlight.active[data-color="2"] { background: rgba(239, 68, 68, 0.25); box-shadow: 0 0 12px rgba(239, 68, 68, 0.15); }
+.chunk-highlight.active[data-color="3"] { background: rgba(245, 158, 11, 0.25); box-shadow: 0 0 12px rgba(245, 158, 11, 0.15); }
+.chunk-highlight.active[data-color="4"] { background: rgba(129, 140, 248, 0.25); box-shadow: 0 0 12px rgba(129, 140, 248, 0.15); }
+
+/* Chunk boundary marker */
+.chunk-boundary {
+  display: inline-block;
+  width: 0;
+  height: 1em;
+  border-left: 2px dashed var(--text-tertiary);
+  margin: 0 2px;
+  vertical-align: middle;
+  opacity: 0.5;
+}
+
+/* Overlap region */
+.overlap-region {
+  background: repeating-linear-gradient(
+    -45deg,
+    transparent,
+    transparent 2px,
+    rgba(251, 146, 60, 0.15) 2px,
+    rgba(251, 146, 60, 0.15) 4px
+  ) !important;
+  border-bottom: 2px dashed var(--warning) !important;
+}
+
+/* Empty state */
+.empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  min-height: 400px;
+  color: var(--text-tertiary);
+  text-align: center;
+  gap: var(--space-md);
+}
+
+.empty-state-icon {
+  font-size: 3rem;
+  opacity: 0.8;
+  color: #22c55e; /* Kryptonite Green */
+}
+
+.empty-state-title {
+  font-size: 1rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+}
+
+.empty-state-desc {
+  font-size: 0.78rem;
+  max-width: 280px;
+  line-height: 1.6;
+}
+
+/* ============================================================
+   6. VECTOR SPACE TAB (Phase 2)
+   ============================================================ */
+.vector-space-container {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  position: relative;
+  gap: var(--space-md);
+  padding: var(--space-lg);
+}
+
+/* Canvas wrapper: Fortress of Solitude Grid */
+.canvas-wrapper {
+  flex: 1;
+  position: relative;
+  border: 1px solid var(--superman-blue);
+  border-radius: var(--radius-lg);
+  background-color: #fafafa;
+  background-image: 
+    linear-gradient(rgba(37, 99, 235, 0.05) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(37, 99, 235, 0.05) 1px, transparent 1px);
+  background-size: 24px 24px;
+  overflow: hidden;
+  box-shadow: inset 0 2px 8px rgba(15, 23, 42, 0.04);
+  min-height: 380px;
+}
+
+#vector-canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  cursor: grab;
+}
+#vector-canvas:active {
+  cursor: grabbing;
+}
+
+/* Canvas Help Overlay */
+.canvas-help-overlay {
+  position: absolute;
+  top: var(--space-md);
+  right: var(--space-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+  background: rgba(255, 255, 255, 0.85);
+  backdrop-filter: blur(4px);
+  padding: 6px 12px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-default);
+  pointer-events: none;
+}
+.canvas-help-overlay span {
+  font-size: 0.68rem;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+}
+
+/* Floating Tooltip inside Canvas — Blue left accent bar */
+.vector-tooltip {
+  position: absolute;
+  pointer-events: none;
+  background: rgba(255, 255, 255, 0.95);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border: 1px solid var(--border-default);
+  border-left: 3px solid var(--superman-blue);
+  border-radius: var(--radius-md);
+  padding: var(--space-md);
+  color: var(--text-primary);
+  max-width: 280px;
+  font-size: 0.75rem;
+  box-shadow: var(--shadow-lg);
+  z-index: 50;
+  transition: opacity 100ms ease;
+}
+.vector-tooltip-title {
+  font-family: var(--font-mono);
+  font-weight: 700;
+  color: var(--superman-blue);
+  margin-bottom: var(--space-xs);
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  display: flex;
+  justify-content: space-between;
+}
+.vector-tooltip-coords {
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+  font-size: 0.65rem;
+}
+.vector-tooltip-text {
+  font-family: var(--font-mono);
+  color: var(--text-secondary);
+  line-height: 1.5;
+  margin-top: var(--space-xs);
+  border-top: 1px solid var(--border-subtle);
+  padding-top: var(--space-xs);
+}
+
+/* ============================================================
+   7. SONAR QUERY SIMULATOR
+   ============================================================ */
+.query-simulator-section {
+  background: var(--bg-surface);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-lg);
+  padding: var(--space-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+  box-shadow: var(--shadow-md);
+}
+
+.query-section-title {
+  font-family: var(--font-heading);
+  font-size: 0.9rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--superman-blue);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.query-section-title .radar-icon {
+  color: var(--superman-yellow);
+}
+
+.query-input-wrapper {
+  display: flex;
+  gap: var(--space-sm);
+}
+
+/* Query input: Blue focus ring */
+#query-input {
+  flex: 1;
+  padding: 10px 14px;
+  background: var(--bg-input);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  color: var(--text-primary);
+  font-size: 0.8rem;
+  outline: none;
+  transition: all var(--transition-base);
+}
+#query-input:focus {
+  border-color: var(--superman-blue);
+  box-shadow: 0 0 0 2px var(--superman-blue-muted);
+}
+
+/* Query button: Red CTA style */
+.btn-query {
+  padding: 10px var(--space-lg);
+  background: var(--superman-red);
+  border: 1px solid var(--superman-red);
+  color: var(--text-inverse);
+  font-family: var(--font-heading);
+  font-weight: 700;
+  font-size: 0.9rem;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: all var(--transition-base);
+}
+.btn-query:hover {
+  background: var(--superman-red-hover);
+  box-shadow: var(--shadow-glow-red);
+}
+
+/* Retrieved Results Drawer */
+.query-results-drawer {
+  border-top: 1px solid var(--border-subtle);
+  padding-top: var(--space-sm);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+  max-height: 200px;
+  overflow-y: auto;
+}
+
+.drawer-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+.drawer-header h3 {
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-secondary);
+}
+.close-drawer {
+  cursor: pointer;
+  font-size: 1.2rem;
+  color: var(--text-tertiary);
+  line-height: 1;
+  transition: color var(--transition-fast);
+}
+.close-drawer:hover {
+  color: var(--superman-red);
+}
+
+.query-results-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+}
+
+.retrieved-chunk-card {
+  display: flex;
+  flex-direction: column;
+  padding: var(--space-sm) var(--space-md);
+  background-color: #ffffff;
+  border: 1px solid var(--border-subtle);
+  border-left: 4px solid var(--superman-blue);
+  border-radius: var(--radius-md);
+  gap: 2px;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+.retrieved-chunk-card:hover {
+  border-color: var(--superman-blue);
+  background: var(--superman-blue-muted);
+}
+
+/* Rank 1 card: Gold left accent border */
+.retrieved-chunk-card.rank-1 {
+  border-left: 4px solid var(--superman-yellow);
+  background: #ffffff;
+}
+
+.retrieved-chunk-card.rank-1:hover {
+  background: var(--superman-yellow-muted);
+}
+
+.retrieved-chunk-meta {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.65rem;
+  font-family: var(--font-mono);
+}
+
+/* Rank label: Gold for Rank 1, Blue for others */
+.retrieved-chunk-rank {
+  font-weight: 700;
+  color: var(--superman-blue);
+}
+.retrieved-chunk-card.rank-1 .retrieved-chunk-rank {
+  color: var(--superman-yellow);
+}
+
+/* Score badge: Red pill */
+.retrieved-chunk-score {
+  color: var(--text-inverse);
+  background-color: var(--superman-red);
+  font-weight: bold;
+  padding: 1px 8px;
+  border-radius: 99px;
+}
+
+.retrieved-chunk-text {
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  color: var(--text-secondary);
+  line-height: 1.4;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ============================================================
+   8. CHUNK INSPECTOR (Right Panel)
+   ============================================================ */
+
+/* --- Stat Cards: Frosted glass with Blue top accent border --- */
+.stats-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--space-sm);
+  margin-bottom: var(--space-lg);
+}
+
+.stat-card {
+  padding: var(--space-md);
+  background: rgba(255, 255, 255, 0.7);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  border: 1px solid var(--border-default);
+  border-top: 3px solid var(--superman-blue);
+  border-radius: var(--radius-md);
+  text-align: center;
+  box-shadow: var(--shadow-sm);
+  transition: all var(--transition-base);
+}
+
+.stat-card:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-1px);
+}
+
+/* Stat values: Red/Gold monospace */
+.stat-card .stat-value {
+  font-family: var(--font-heading);
+  font-size: 1.8rem;
+  font-weight: 700;
+  color: var(--superman-red);
+}
+
+.stat-card:nth-child(even) .stat-value {
+  color: var(--superman-yellow);
+}
+
+.stat-card .stat-label {
+  font-family: var(--font-heading);
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-tertiary);
+  margin-top: 2px;
+}
+
+/* --- Chunk List --- */
+.chunk-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+}
+
+.chunk-item {
+  padding: var(--space-md);
+  padding-left: calc(var(--space-md) + 28px); /* Room for the index circle */
+  background-color: #ffffff;
+  border: 1px solid #e5e7eb;
+  border-left: 4px solid var(--superman-blue); /* Default alternating later */
+  border-radius: 4px;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+  position: relative;
+  overflow: hidden;
+}
+
+/* Alternate Left Borders */
+.chunk-item:nth-child(3n+1) { border-left-color: var(--superman-blue); }
+.chunk-item:nth-child(3n+2) { border-left-color: var(--superman-red); }
+.chunk-item:nth-child(3n+3) { border-left-color: var(--superman-yellow); }
+
+.chunk-item:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 10px 15px -3px rgba(37, 99, 235, 0.15);
+}
+
+/* Active chunk */
+.chunk-item.active {
+  background: rgba(37, 99, 235, 0.05);
+}
+
+.chunk-item.active::before {
+  background: var(--superman-red);
+}
+
+/* Parent chunk styling */
+.chunk-item[data-level="0"] {
+  border-left: 3px solid var(--superman-blue);
+}
+
+.chunk-item[data-level="0"]::before {
+  background: var(--superman-blue);
+}
+
+/* Child chunk styling */
+.chunk-item[data-level="1"] {
+  margin-left: var(--space-lg);
+  border-left: 3px solid var(--superman-yellow);
+  opacity: 0.85;
+}
+
+.chunk-item[data-level="1"]::before {
+  background: var(--superman-yellow);
+}
+
+.chunk-item-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(--space-sm);
+}
+
+/* Chunk ID: Blue mono label */
+.chunk-item-id {
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--superman-blue);
+}
+
+.chunk-item.active .chunk-item-id {
+  color: var(--superman-red);
+}
+
+.chunk-item-badges {
+  display: flex;
+  gap: var(--space-xs);
+}
+
+.chunk-badge {
+  font-family: var(--font-mono);
+  font-size: 0.6rem;
+  padding: 1px 6px;
+  border-radius: 99px;
+  background: var(--bg-surface-overlay);
+  color: var(--text-tertiary);
+  border: 1px solid var(--border-subtle);
+}
+
+/* Token badge: Blue tinted */
+.chunk-badge.tokens {
+  color: var(--superman-blue);
+  background: var(--superman-blue-muted);
+  border-color: rgba(37, 99, 235, 0.2);
+}
+
+.chunk-item-text {
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  color: var(--text-secondary);
+  line-height: 1.6;
+  max-height: 60px;
+  overflow: hidden;
+  position: relative;
+}
+
+.chunk-item-text::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 24px;
+  background: linear-gradient(transparent, var(--bg-surface));
+  pointer-events: none;
+}
+
+.chunk-item.active .chunk-item-text::after {
+  background: linear-gradient(transparent, rgba(239, 68, 68, 0.06));
+}
+
+.chunk-item-meta {
+  display: flex;
+  gap: var(--space-md);
+  margin-top: var(--space-sm);
+  font-size: 0.65rem;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+}
+
+/* Parent-child connector label */
+.parent-child-label {
+  font-size: 0.6rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--superman-blue);
+  padding: var(--space-xs) 0;
+  margin-top: var(--space-sm);
+}
+
+/* --- Config: Parent-Child Fields --- */
+.parent-child-config {
+  display: none;
+  flex-direction: column;
+  gap: var(--space-md);
+  padding: var(--space-md);
+  background: var(--bg-surface);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  margin-top: var(--space-sm);
+}
+
+.parent-child-config.visible {
+  display: flex;
+}
+
+.pc-section-label {
+  font-size: 0.65rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  padding-bottom: var(--space-xs);
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+.pc-section-label.parent { color: var(--superman-blue); }
+.pc-section-label.child { color: var(--superman-yellow); }
+
+/* ============================================================
+   9. SELECT INPUT
+   ============================================================ */
+.select-input {
+  width: 100%;
+  padding: 8px 12px;
+  background: var(--bg-input);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  color: var(--text-primary);
+  outline: none;
+  font-family: var(--font-sans);
+  font-size: 0.85rem;
+  cursor: pointer;
+  transition: border-color var(--transition-base);
+}
+.select-input:focus {
+  border-color: var(--superman-blue);
+}
+
+/* ============================================================
+   10. ANIMATIONS & SKELETONS
+   ============================================================ */
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.chunk-item {
+  animation: fadeInUp var(--transition-slow) both;
+}
+
+.chunk-item:nth-child(1) { animation-delay: 0ms; }
+.chunk-item:nth-child(2) { animation-delay: 40ms; }
+.chunk-item:nth-child(3) { animation-delay: 80ms; }
+.chunk-item:nth-child(4) { animation-delay: 120ms; }
+.chunk-item:nth-child(5) { animation-delay: 160ms; }
+.chunk-item:nth-child(6) { animation-delay: 200ms; }
+.chunk-item:nth-child(7) { animation-delay: 240ms; }
+.chunk-item:nth-child(8) { animation-delay: 280ms; }
+
+/* 1. Heat Vision Pulse (Applied to the Sonar Probe node in Canvas via JS, but CSS provided if DOM used) */
+@keyframes radar-pulse {
+  0% { transform: scale(0.95); box-shadow: 0 0 0 0 rgba(239, 68, 68, 0.7); }
+  70% { transform: scale(1); box-shadow: 0 0 0 20px rgba(239, 68, 68, 0); }
+  100% { transform: scale(0.95); box-shadow: 0 0 0 0 rgba(239, 68, 68, 0); }
+}
+.sonar-probe {
+  background-color: #ef4444;
+  border-radius: 50%;
+  animation: radar-pulse 2s infinite;
+}
+
+/* 2. Super Speed Data Flow (Applied to the SVG connecting lines if DOM used) */
+@keyframes data-flow {
+  to { stroke-dashoffset: -20; }
+}
+.connection-line {
+  stroke: #f59e0b;
+  stroke-width: 2;
+  stroke-dasharray: 5, 5;
+  animation: data-flow 0.8s linear infinite;
+}
+
+/* 3. Yellow Sun Glow (Applied to the Rank 1 retrieved node if DOM used) */
+@keyframes sun-glow {
+  0%, 100% { box-shadow: 0 0 5px rgba(245, 158, 11, 0.6); }
+  50% { box-shadow: 0 0 15px #f59e0b, 0 0 25px rgba(245, 158, 11, 0.4); }
+}
+.rank-1-node {
+  background-color: #f59e0b;
+  border-radius: 50%;
+  animation: sun-glow 3s ease-in-out infinite;
+}
+
+/* Heat Vision Skeleton Animation */
+@keyframes heat-sweep {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+.skeleton-loader {
+  height: 60px; /* Adjust based on your text line height */
+  border-radius: 4px;
+  /* Sweeps a soft red gradient over a standard grey skeleton base */
+  background: linear-gradient(90deg, #f3f4f6 25%, rgba(239, 68, 68, 0.15) 50%, #f3f4f6 75%);
+  background-size: 200% 100%;
+  animation: heat-sweep 1.5s infinite linear;
+}
+
+/* ============================================================
+   11. RESPONSIVE
+   ============================================================ */
+@media (max-width: 1200px) {
+  .app-main {
+    grid-template-columns: 260px 1fr 300px;
+  }
+}
+
+@media (max-width: 900px) {
+  .app-main {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto 1fr auto;
+  }
+
+  .panel {
+    height: auto;
+    max-height: 50vh;
+    border-right: none;
+    border-bottom: 1px solid var(--border-default);
+  }
+}
+
+/* ============================================================
+   12. AI REFEREE (TASK 5.1)
+   ============================================================ */
+.arena-referee-panel {
+  margin-top: 2rem;
+  padding: 1.5rem;
+  border-radius: 8px;
+  background-color: var(--bg-surface-raised);
+  border: 1px solid var(--border-default);
+  box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.02);
+}
+
+.referee-divider {
+  display: flex;
+  align-items: center;
+  text-align: center;
+  margin-bottom: 1.5rem;
+}
+
+.referee-divider::before,
+.referee-divider::after {
+  content: '';
+  flex: 1;
+  border-bottom: 1px dashed var(--border-default);
+}
+
+.referee-badge {
+  padding: 0.25rem 0.75rem;
+  font-family: 'Roboto Condensed', sans-serif;
+  font-weight: 700;
+  font-size: 0.85rem;
+  color: var(--superman-blue);
+  background-color: var(--superman-blue-muted);
+  border-radius: 50px;
+  border: 1px solid rgba(37, 99, 235, 0.2);
+  letter-spacing: 0.05em;
+  margin: 0 1rem;
+}
+
+.referee-prompt-text {
+  text-align: center;
+  color: var(--text-secondary);
+  font-size: 0.9rem;
+  margin-bottom: 1rem;
+}
+
+.referee-status-text {
+  text-align: center;
+  font-weight: 500;
+  color: var(--superman-blue);
+  font-size: 0.9rem;
+  animation: pulse 1.5s infinite ease-in-out;
+}
+
+.referee-verdict-box {
+  animation: fadeIn 0.4s ease-out;
+}
+
+/* Verdict banner */
+.verdict-banner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 1.5rem;
+  border-radius: 6px;
+  border: 1.5px solid;
+  margin-bottom: 1.5rem;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.03);
+}
+
+.verdict-title {
+  font-family: 'Roboto Condensed', sans-serif;
+  font-weight: 700;
+  font-size: 1.2rem;
+  letter-spacing: 0.02em;
+}
+
+.verdict-confidence {
+  font-size: 0.85rem;
+  font-weight: 600;
+  background-color: rgba(255, 255, 255, 0.7);
+  padding: 0.2rem 0.5rem;
+  border-radius: 4px;
+  border: 1px solid rgba(0, 0, 0, 0.05);
+}
+
+/* Verdict reason */
+.verdict-reason {
+  background-color: var(--bg-surface);
+  padding: 1.25rem;
+  border-radius: 6px;
+  border: 1px solid var(--border-default);
+  margin-bottom: 1.5rem;
+}
+
+.verdict-reason > strong {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 0.5rem;
+}
+
+.verdict-reason p {
+  font-size: 0.95rem;
+  color: var(--text-primary);
+  line-height: 1.5;
+  margin-bottom: 0.75rem;
+  font-style: italic;
+}
+
+.deciding-factor {
+  font-size: 0.8rem;
+  color: var(--text-tertiary);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.deciding-factor code {
+  background-color: var(--bg-surface-raised);
+  padding: 0.1rem 0.4rem;
+  border-radius: 4px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--superman-red);
+  font-weight: 600;
+}
+
+/* Scorecard Table */
+.referee-scores-table {
+  background-color: var(--bg-surface);
+  border: 1px solid var(--border-default);
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 1.5rem;
+}
+
+.scores-table-header {
+  display: grid;
+  grid-template-columns: 150px 70px 1fr 70px;
+  padding: 0.75rem 1rem;
+  background-color: var(--bg-surface-raised);
+  border-bottom: 1px solid var(--border-default);
+  font-weight: 600;
+  font-size: 0.8rem;
+  color: var(--text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.scores-table-row {
+  display: grid;
+  grid-template-columns: 150px 70px 1fr 70px;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border-default);
+  font-size: 0.9rem;
+}
+
+.scores-table-row:last-child {
+  border-bottom: none;
+}
+
+.overall-row {
+  background-color: rgba(37, 99, 235, 0.02);
+  border-top: 1.5px solid var(--border-default);
+}
+
+.score-col-label {
+  font-weight: 500;
+  color: var(--text-primary);
+}
+
+.score-col-val {
+  text-align: center;
+  font-weight: 600;
+}
+
+.score-col-bar {
+  padding: 0 1rem;
+}
+
+.score-progress-bar {
+  height: 6px;
+  background-color: #e2e8f0;
+  border-radius: 10px;
+  overflow: hidden;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2px;
+}
+
+.score-val-a {
+  background-color: var(--superman-yellow);
+  height: 100%;
+  border-radius: 10px 0 0 10px;
+  justify-self: end;
+}
+
+.score-val-b {
+  background-color: var(--superman-blue);
+  height: 100%;
+  border-radius: 0 10px 10px 0;
+  justify-self: start;
+}
+
+.overall-progress-bar {
+  height: 10px;
+  background-color: #e2e8f0;
+  border-radius: 10px;
+  overflow: hidden;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2px;
+}
+
+.overall-val-a {
+  background-color: var(--superman-yellow);
+  height: 100%;
+  border-radius: 10px 0 0 10px;
+  justify-self: end;
+}
+
+.overall-val-b {
+  background-color: var(--superman-blue);
+  height: 100%;
+  border-radius: 0 10px 10px 0;
+  justify-self: start;
+}
+
+/* Strengths & Weaknesses Columns */
+.verdict-details-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+}
+
+.verdict-details-col {
+  background-color: var(--bg-surface);
+  border: 1px solid var(--border-default);
+  padding: 1.25rem;
+  border-radius: 6px;
+}
+
+.verdict-details-col h4 {
+  font-family: 'Roboto Condensed', sans-serif;
+  font-weight: 700;
+  margin-bottom: 1rem;
+  font-size: 1rem;
+  border-bottom: 1.5px solid var(--border-default);
+  padding-bottom: 0.5rem;
+}
+
+.verdict-details-col:first-child h4 {
+  color: var(--warning-color);
+  border-bottom-color: rgba(245, 158, 11, 0.2);
+}
+
+.verdict-details-col:last-child h4 {
+  color: var(--info-color);
+  border-bottom-color: rgba(59, 130, 246, 0.2);
+}
+
+.verdict-list-title {
+  font-size: 0.75rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 0.5rem;
+}
+
+.strength-list-title {
+  color: #16a34a;
+}
+
+.weakness-list-title {
+  color: #dc2626;
+  margin-top: 1rem;
+}
+
+.verdict-details-col ul {
+  padding-left: 1.25rem;
+  margin: 0;
+}
+
+.verdict-details-col li {
+  font-size: 0.85rem;
+  color: var(--text-secondary);
+  line-height: 1.4;
+  margin-bottom: 0.4rem;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(10px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+
+/* ============================================================
+   RETRIEVAL X-RAY HIGHLIGHTS (TASK 3.4)
+   ============================================================ */
+.xray-content.search-active .chunk-highlight {
+  opacity: 0.3;
+  transition: all 0.3s ease;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-1 {
+  opacity: 1.0;
+  background-color: rgba(255, 165, 0, 0.4);
+  box-shadow: 0 0 12px rgba(255, 165, 0, 0.6);
+  border-top: 2px solid var(--warning-color);
+  border-bottom: 2px solid var(--warning-color);
+  z-index: 10;
+  position: relative;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-2 {
+  opacity: 0.9;
+  background-color: rgba(255, 165, 0, 0.25);
+  border-top: 2px dashed rgba(255, 165, 0, 0.6);
+  border-bottom: 2px dashed rgba(255, 165, 0, 0.6);
+  z-index: 9;
+  position: relative;
+}
+
+.xray-content.search-active .chunk-highlight.retrieved-rank-3 {
+  opacity: 0.8;
+  background-color: rgba(255, 165, 0, 0.15);
+  border-top: 2px dotted rgba(255, 165, 0, 0.4);
+  border-bottom: 2px dotted rgba(255, 165, 0, 0.4);
+  z-index: 8;
+  position: relative;
+}
+
+
+

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "rag-visualizer"
+version = "0.1.0"
+description = "An X-Ray machine for RAG — visualize and compare chunking, embeddings, and retrieval across local models."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "pydantic>=2.0",
+    "chromadb>=1.0.0",
+    "tiktoken>=0.9.0",
+    "httpx>=0.28.0",
+    "langchain-text-splitters>=1.1.2",
+    "nltk>=3.9.4",
+    "umap-learn>=0.5.12",
+    "numpy>=2.4.4",
+    "ollama>=0.6.2",
+]