Super-squash branch 'main' using huggingface_hub

Co-authored-by: Luis Chaves Rodriguez <Luis Chaves Rodriguez@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,2 @@
+*.duckdb filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,51 @@
+# Etymology Graph Explorer
+# Multi-stage build: uv for building, plain Python for runtime
+
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+
+WORKDIR /app
+
+# Copy dependency files first for layer caching
+COPY pyproject.toml uv.lock ./
+
+# Install production dependencies only (no dev, no project yet)
+RUN uv sync --locked --no-install-project --no-dev
+
+# Copy application code
+COPY backend/ backend/
+COPY frontend/ frontend/
+
+# Production stage - plain Python, no uv needed at runtime
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+
+# Install zstd for decompression (only needed if DB is compressed)
+RUN apt-get update && apt-get install -y --no-install-recommends zstd && rm -rf /var/lib/apt/lists/*
+
+# Copy only what we need from builder
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/backend /app/backend
+COPY --from=builder /app/frontend /app/frontend
+COPY --from=builder /app/pyproject.toml /app/pyproject.toml
+
+# Copy database (compressed or uncompressed) and decompress if needed
+COPY backend/data/etymdb.duckdb* /app/backend/data/
+RUN if [ -f /app/backend/data/etymdb.duckdb.zst ]; then \
+        echo "Decompressing database..." && \
+        zstd -d /app/backend/data/etymdb.duckdb.zst -o /app/backend/data/etymdb.duckdb && \
+        rm /app/backend/data/etymdb.duckdb.zst; \
+    fi
+
+# Use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Port configuration (HF Spaces uses 7860)
+ENV PORT=7860
+EXPOSE ${PORT}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:${PORT}/health')" || exit 1
+
+CMD uvicorn backend.main:app --host 0.0.0.0 --port ${PORT}

README.md

@@ -0,0 +1,90 @@
+---
+title: Etymology Graph Explorer
+emoji: 🌳
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+---
+
+# Etymology Graph Explorer
+
+A visual tool for exploring the origins and historical relationships between words. Search for any word and see its etymological journey through time, from modern usage back to ancient roots.
+
+## Quick Start
+
+### Using uv (recommended for development)
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the server
+uv run uvicorn backend.main:app --reload
+
+# Open http://localhost:8000 in your browser
+```
+
+### Using Docker
+
+```bash
+# Build the image
+docker build -t etymology .
+
+# Run the container
+docker run -p 7860:7860 etymology
+
+# Open http://localhost:7860 in your browser
+```
+
+## Features
+
+- **Search any word** to see its etymological tree
+- **Random word** button for exploration and discovery
+- **Interactive graph** - zoom, pan, and click on nodes
+- **Color-coded languages** to visualize word evolution across language families
+- **Mobile-friendly** responsive design
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | Web interface |
+| `GET /graph/{word}` | Etymology graph for a word (JSON) |
+| `GET /search?q=<query>&limit=<n>` | Search/autocomplete for words |
+| `GET /random` | Random English word |
+| `GET /version` | App version and database stats |
+| `GET /health` | Health check |
+
+## Data Source
+
+Etymology data comes from [EtymDB 2.1](https://github.com/clefourrier/EtymDB), an open etymological database derived from Wiktionary.
+
+> Fourrier & Sagot (2020), "Methodological Aspects of Developing and Managing an Etymological Lexical Resource: Introducing EtymDB-2.0", Proceedings of the LREC Conference.
+
+## Tech Stack
+
+- **Backend**: FastAPI + DuckDB
+- **Frontend**: Vanilla JS + Cytoscape.js
+- **Data**: EtymDB 2.1 (auto-downloaded on first run)
+
+## Development
+
+```bash
+uv sync                        # Install dependencies
+uv run prek install            # Set up pre-commit hooks
+uv run pytest backend/tests -q # Run tests
+```
+
+Linting (ruff) runs automatically on commit via prek.
+
+## Deploy
+
+```bash
+make hf-deploy  # Deploy to HF Spaces (stages, pushes, squashes history)
+make cf-deploy  # Deploy Cloudflare Worker (custom domain proxy)
+```
+
+## License
+
+GPL-3.0 - see [LICENSE](LICENSE)

backend/data/etymdb.duckdb.zst

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a9d682f0cba4f9f1a118007906c58d3b446c5b4e9aaf6eadbbde775a672c8d12
+size 92564012

backend/database.py

@@ -0,0 +1,357 @@
+"""Database helpers for the FastAPI application."""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+import duckdb
+
+try:
+    from .sql_loader import load_sql
+except ImportError:  # pragma: no cover - fallback for direct execution
+    from sql_loader import load_sql
+
+BASE_DIR = Path(__file__).resolve().parent
+DEFAULT_DATA_DIR = BASE_DIR / "data"
+
+
+def _resolve_path(env_var: str, default: Path) -> Path:
+    value = os.environ.get(env_var)
+    return Path(value) if value else default
+
+
+def _data_dir() -> Path:
+    return _resolve_path("ETYM_DATA_DIR", DEFAULT_DATA_DIR)
+
+
+@lru_cache(maxsize=1)
+def database_path() -> Path:
+    """Return the configured DuckDB path, creating parent directories."""
+    path = _resolve_path("ETYM_DB_PATH", _data_dir() / "etymdb.duckdb")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _ensure_database() -> Path:
+    db_path = database_path()
+    if db_path.exists():
+        return db_path
+
+    try:
+        from . import ingest  # type: ignore[attr-defined]
+    except ImportError:  # pragma: no cover - fallback for direct execution
+        import ingest
+
+    try:
+        ingest.main()
+    except Exception as exc:  # pragma: no cover - propagation with context
+        raise RuntimeError("Failed to ingest the EtymDB dataset") from exc
+
+    if not db_path.exists():
+        raise RuntimeError(f"Expected DuckDB database at {db_path} after ingestion")
+    return db_path
+
+
+class _ConnectionManager:
+    """Lazily open DuckDB connections when required."""
+
+    def __init__(self) -> None:
+        self._conn: duckdb.DuckDBPyConnection | None = None
+
+    def __enter__(self) -> duckdb.DuckDBPyConnection:
+        db_path = _ensure_database()
+        self._conn = duckdb.connect(db_path.as_posix(), read_only=True)
+        return self._conn
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._conn is not None:
+            self._conn.close()
+
+
+def _normalize_depth(depth: int) -> int:
+    return max(depth, 0)
+
+
+def _get_language_families(conn) -> dict[str, dict[str, str]]:
+    """Load language families into a lookup dict."""
+    rows = conn.execute(load_sql("queries/get_language_families.sql")).fetchall()
+    return {row[0]: {"name": row[1], "family": row[2], "branch": row[3]} for row in rows}
+
+
+def _get_definitions_for_lexemes(conn, lexemes: list[str]) -> dict[str, str]:
+    """Fetch primary definitions for the specified lexemes.
+
+    Returns dict mapping lowercase lexeme -> definition string.
+    Uses the first definition (entry_idx=0, meaning_idx=0, def_idx=0).
+    """
+    if not lexemes:
+        return {}
+    try:
+        placeholders = ",".join(["?" for _ in lexemes])
+        rows = conn.execute(
+            f"""
+            SELECT lexeme, definition
+            FROM definitions
+            WHERE lexeme IN ({placeholders})
+              AND definition IS NOT NULL
+              AND entry_idx = 0 AND meaning_idx = 0 AND def_idx = 0
+            """,
+            [lex.lower() for lex in lexemes],
+        ).fetchall()
+        return {row[0]: row[1].strip('"') if row[1] else None for row in rows}
+    except Exception:
+        return {}
+
+
+def _make_node_id(lexeme: str, lang: str) -> str:
+    """Create a unique node ID combining lexeme and language."""
+    return f"{lexeme}|{lang}"
+
+
+def _build_node(
+    lexeme: str,
+    lang: str,
+    sense: str,
+    lang_families: dict,
+    enriched_defs: dict[str, str] | None = None,
+) -> dict:
+    """Build a rich node with all available metadata.
+
+    Args:
+        lexeme: The word
+        lang: Language code
+        sense: EtymDB sense/definition
+        lang_families: Language family lookup dict
+        enriched_defs: Optional dict of enriched definitions from Free Dictionary API
+    """
+    node = {
+        "id": _make_node_id(lexeme, lang),  # Unique ID includes language
+        "lexeme": lexeme,  # Display name
+        "lang": lang,
+    }
+
+    # Determine best definition to use
+    # Priority: enriched definition (for English) > EtymDB sense
+    definition = None
+    if enriched_defs and lang == "en" and lexeme.lower() in enriched_defs:
+        definition = enriched_defs[lexeme.lower()]
+    elif sense and sense.lower() != lexeme.lower():
+        definition = sense
+
+    if definition:
+        node["sense"] = definition
+
+    # Add language metadata if available
+    lang_info = lang_families.get(lang)
+    if lang_info:
+        node["lang_name"] = lang_info["name"]
+        node["family"] = lang_info["family"]
+        node["branch"] = lang_info["branch"]
+    else:
+        # Fallback: use lang code as name
+        node["lang_name"] = lang
+    return node
+
+
+def get_db_stats() -> dict:
+    """Return row counts for key tables."""
+    with _ConnectionManager() as conn:
+        words = conn.execute("SELECT COUNT(*) FROM v_english_curated").fetchone()[0]
+        try:
+            definitions = conn.execute("SELECT COUNT(*) FROM definitions").fetchone()[0]
+        except Exception:
+            definitions = 0
+        return {"words": words, "definitions": definitions}
+
+
+def fetch_etymology(word: str, depth: int = 5) -> dict | None:
+    """Return an etymology graph for *word* or ``None`` if absent."""
+    if not word:
+        return None
+
+    depth = _normalize_depth(depth)
+    with _ConnectionManager() as conn:
+        # Load language families (small table, 53 rows)
+        lang_families = _get_language_families(conn)
+
+        # Find starting word (prefer English, then most etymology links)
+        start = conn.execute(
+            load_sql("queries/find_start_word.sql"),
+            [word],
+        ).fetchone()
+        if not start:
+            return None
+
+        start_ix, start_lang, start_lexeme, start_sense = start
+
+        # Collect all node data first (without definitions)
+        raw_nodes: dict[int, tuple] = {start_ix: (start_lexeme, start_lang, start_sense)}
+        edges = []
+        seen_edges: set[tuple[str, str]] = set()
+
+        if depth > 0:
+            # Recursive traversal that handles both simple links and compound etymologies
+            # When target < 0, it's a sequence ID that resolves to multiple parent words
+            # Track is_compound to style compound edges differently in the UI
+            records = conn.execute(
+                load_sql("queries/traverse_etymology.sql"),
+                [start_ix, depth],
+            ).fetchall()
+
+            for row in records:
+                child_ix, child_lexeme, child_lang, child_sense = row[:4]
+                parent_ix, parent_lexeme, parent_lang, parent_sense = row[4:8]
+                is_compound = row[8]
+                link_type = row[9]
+
+                raw_nodes.setdefault(child_ix, (child_lexeme, child_lang, child_sense))
+                raw_nodes.setdefault(parent_ix, (parent_lexeme, parent_lang, parent_sense))
+
+                # Build edges with compound flag and link type for UI styling
+                child_id = _make_node_id(child_lexeme, child_lang)
+                parent_id = _make_node_id(parent_lexeme, parent_lang)
+                if child_id != parent_id:
+                    edge_key = (child_id, parent_id)
+                    if edge_key not in seen_edges:
+                        seen_edges.add(edge_key)
+                        edge = {"source": child_id, "target": parent_id}
+                        if is_compound:
+                            edge["compound"] = True
+                        if link_type:
+                            edge["type"] = link_type
+                        edges.append(edge)
+
+        # Fetch definitions only for English lexemes in this graph
+        english_lexemes = [lex for lex, lang, _ in raw_nodes.values() if lang == "en"]
+        enriched_defs = _get_definitions_for_lexemes(conn, english_lexemes)
+
+        # Build final nodes with all metadata
+        nodes = {
+            ix: _build_node(lexeme, lang, sense, lang_families, enriched_defs)
+            for ix, (lexeme, lang, sense) in raw_nodes.items()
+        }
+
+        # Word exists but has no etymology links
+        if not edges:
+            return {
+                "nodes": list(nodes.values()),
+                "edges": [],
+                "no_etymology": True,
+                "lexeme": start_lexeme,
+            }
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+
+def fetch_random_word(include_compound: bool = True) -> dict[str, str | None]:
+    """Return a random curated English word (has etymology, no phrases/proper nouns).
+
+    Args:
+        include_compound: If True, include compound-only words (e.g., "acquaintanceship").
+                         If False, only return words with "deep" etymology chains.
+    """
+    view = "v_english_curated" if include_compound else "v_english_deep"
+    # Guard against SQL injection (view name is interpolated)
+    assert view in ("v_english_curated", "v_english_deep"), f"Invalid view: {view}"
+    with _ConnectionManager() as conn:
+        row = conn.execute(f"SELECT lexeme FROM {view} ORDER BY random() LIMIT 1").fetchone()
+        return {"word": row[0] if row else None}
+
+
+def fetch_language_info(lang_code: str) -> dict[str, str] | None:
+    """Return language family info for a language code."""
+    with _ConnectionManager() as conn:
+        row = conn.execute(
+            load_sql("queries/get_language_info.sql"),
+            [lang_code],
+        ).fetchone()
+        if row:
+            return {"name": row[0], "family": row[1], "branch": row[2]}
+        return None
+
+
+def fetch_all_language_families() -> dict[str, dict[str, str]]:
+    """Return all language family mappings."""
+    with _ConnectionManager() as conn:
+        rows = conn.execute(load_sql("queries/get_language_families.sql")).fetchall()
+        return {row[0]: {"name": row[1], "family": row[2], "branch": row[3]} for row in rows}
+
+
+def _is_useful_sense(sense: str | None, lexeme: str) -> bool:
+    """Check if a sense provides useful information beyond the lexeme itself.
+
+    NULL senses are filtered out - they're structural entries without
+    meaningful definitions. We prefer entries where sense differs from lexeme.
+    """
+    if sense is None:
+        return False
+    sense_lower = sense.lower().strip('"')
+    lexeme_lower = lexeme.lower()
+    # Not useful: NULL, empty string, or equals lexeme
+    return sense_lower != "" and sense_lower != lexeme_lower
+
+
+def _format_sense_for_display(sense: str) -> str:
+    """Format a sense for display in the UI."""
+    return sense.strip('"')
+
+
+def search_words(query: str, limit: int = 10) -> list[dict[str, str]]:
+    """Search for English words matching the query (fuzzy prefix search).
+
+    Returns words with etymology data. Shows EtymDB sense when it differs
+    from lexeme, otherwise falls back to Free Dictionary definition.
+    When multiple senses exist for a word, shows all of them.
+
+    For words with multiple Free Dictionary definitions, shows the primary
+    definition with a count indicator (e.g., "+3 more").
+
+    TODO: The subquery for def_count could be optimized by pre-computing
+    definition counts into a materialized column or separate table. This
+    would require a schema change to the definitions table.
+    """
+    if not query or len(query) < 2:
+        return []
+
+    with _ConnectionManager() as conn:
+        # Get primary definitions (entry=0, meaning=0, def=0) with total count
+        rows = conn.execute(
+            load_sql("queries/search_words.sql"),
+            [query, query],
+        ).fetchall()
+
+        # Group by lexeme to handle duplicates
+        seen_lexemes: dict[str, list[tuple]] = {}
+        for lexeme, sense, definition, pos, def_count in rows:
+            if lexeme not in seen_lexemes:
+                seen_lexemes[lexeme] = []
+            seen_lexemes[lexeme].append((sense, definition, pos, def_count or 0))
+
+        # Build results
+        results = []
+        for lexeme, entries in seen_lexemes.items():
+            useful_senses = [s for s, _, _, _ in entries if _is_useful_sense(s, lexeme)]
+
+            if useful_senses:
+                # Show all entries with useful senses
+                for sense in useful_senses:
+                    display = _format_sense_for_display(sense)
+                    results.append({"word": lexeme, "sense": display})
+            else:
+                # No useful senses - show Free Dictionary definition with count
+                _, definition, pos, def_count = entries[0]
+                display = definition.strip('"') if definition else None
+
+                # Add count indicator for polysemous words
+                if display and def_count > 1:
+                    pos_str = f"({pos}) " if pos else ""
+                    display = f"{pos_str}{display} (+{def_count - 1} more)"
+
+                results.append({"word": lexeme, "sense": display})
+
+            if len(results) >= limit:
+                break
+
+        return results[:limit]

backend/download_data.py

@@ -0,0 +1,52 @@
+"""Utilities to download the EtymDB CSV files on demand."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+import httpx
+
+BASE_DIR = Path(__file__).resolve().parent
+DEFAULT_DATA_DIR = BASE_DIR / "data"
+
+DATA_DIR = Path(os.environ.get("ETYM_DATA_DIR", DEFAULT_DATA_DIR))
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+FILES: dict[str, str] = {
+    "etymdb_values.csv": "https://raw.githubusercontent.com/clefourrier/EtymDB/master/data/split_etymdb/etymdb_values.csv",
+    "etymdb_links_info.csv": "https://raw.githubusercontent.com/clefourrier/EtymDB/master/data/split_etymdb/etymdb_links_info.csv",
+    "etymdb_links_index.csv": "https://raw.githubusercontent.com/clefourrier/EtymDB/master/data/split_etymdb/etymdb_links_index.csv",
+}
+
+_CHUNK_SIZE = 1 << 20  # 1 MiB
+
+
+def _iter_download(client: httpx.Client, url: str) -> Iterable[bytes]:
+    """Stream a download from *url* yielding binary chunks."""
+    with client.stream("GET", url) as response:
+        response.raise_for_status()
+        for chunk in response.iter_bytes(_CHUNK_SIZE):
+            if chunk:
+                yield chunk
+
+
+def download() -> None:
+    """Download the EtymDB CSVs into :data:`DATA_DIR` if missing."""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    with httpx.Client(follow_redirects=True, timeout=httpx.Timeout(60.0)) as client:
+        for name, url in FILES.items():
+            destination = DATA_DIR / name
+            if destination.exists():
+                continue
+            destination_tmp = destination.with_suffix(destination.suffix + ".tmp")
+            destination_tmp.parent.mkdir(parents=True, exist_ok=True)
+            with destination_tmp.open("wb") as fh:
+                for chunk in _iter_download(client, url):
+                    fh.write(chunk)
+            destination_tmp.replace(destination)
+
+
+if __name__ == "__main__":  # pragma: no cover - manual utility
+    download()

backend/download_language_codes.py

@@ -0,0 +1,80 @@
+"""Download language code mappings from ISO 639-3 and Wiktionary.
+
+Sources:
+- ISO 639-3: https://iso639-3.sil.org/code_tables/download_tables
+- Wiktionary: etymology languages and families modules
+
+Usage:
+    python -m backend.download_language_codes
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import re
+from io import StringIO
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+DATA_DIR = Path(__file__).parent / "data"
+OUTPUT_FILE = DATA_DIR / "language_codes.json"
+
+
+def fetch(url: str) -> str:
+    """Fetch URL content."""
+    req = Request(url, headers={"User-Agent": "etymology-for-all/1.0"})
+    with urlopen(req, timeout=30) as r:
+        return r.read().decode("utf-8")
+
+
+def main() -> None:
+    """Download and combine language codes into JSON."""
+    codes: dict[str, str] = {}
+
+    # 1. ISO 639-3 (official registry - ~8000 codes)
+    print("Fetching ISO 639-3...")
+    content = fetch("https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab")
+    for row in csv.DictReader(StringIO(content), delimiter="\t"):
+        codes[row["Id"]] = row["Ref_Name"]
+
+    # 2. ISO 639-1 (two-letter codes)
+    print("Fetching ISO 639-1...")
+    content = fetch(
+        "https://raw.githubusercontent.com/datasets/language-codes/master/data/language-codes.csv"
+    )
+    for row in csv.DictReader(StringIO(content)):
+        codes[row["alpha2"]] = row["English"]
+
+    # 3. Wiktionary main languages (code to name JSON)
+    print("Fetching Wiktionary languages JSON...")
+    content = fetch(
+        "https://en.wiktionary.org/w/index.php?title=Module:languages/code_to_canonical_name.json&action=raw"
+    )
+    codes.update(json.loads(content))
+
+    # 4. Wiktionary etymology languages (dialects, variants) - JSON
+    print("Fetching Wiktionary etymology codes...")
+    content = fetch(
+        "https://en.wiktionary.org/w/index.php?title=Module:etymology_languages/code_to_canonical_name.json&action=raw"
+    )
+    codes.update(json.loads(content))
+
+    # 5. Wiktionary families -> proto-languages
+    print("Fetching Wiktionary families...")
+    content = fetch("https://en.wiktionary.org/w/index.php?title=Module:families/data&action=raw")
+    for m in re.finditer(r'm\["([^"]+)"\]\s*=\s*\{\s*\n\s*"([^"]+)"', content):
+        codes[m.group(1)] = m.group(2)
+        codes[f"{m.group(1)}-pro"] = f"Proto-{m.group(2)}"
+
+    # Write output
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    data = [
+        {"code": c, "name": n, "family": None, "branch": None} for c, n in sorted(codes.items())
+    ]
+    OUTPUT_FILE.write_text(json.dumps(data, indent=2, ensure_ascii=False))
+    print(f"Wrote {len(data)} codes to {OUTPUT_FILE}")
+
+
+if __name__ == "__main__":
+    main()

backend/enrich_definitions.py

@@ -0,0 +1,228 @@
+"""Enrich etymology database with definitions from Free Dictionary API.
+
+Usage:
+    uv run python -m backend.enrich_definitions          # Run full enrichment
+    uv run python -m backend.enrich_definitions --stats  # Check progress
+    uv run python -m backend.enrich_definitions --test 50  # Test with 50 words
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import time
+from datetime import datetime
+
+import duckdb
+
+try:
+    import aiohttp
+except ImportError:
+    print("aiohttp is required. Install with: uv add aiohttp")
+    sys.exit(1)
+
+try:
+    from .database import database_path
+    from .sql_loader import load_sql
+except ImportError:
+    from database import database_path
+    from sql_loader import load_sql
+
+API_BASE = "https://api.dictionaryapi.dev/api/v2/entries/en"
+DELAY_MS = 300  # Delay between requests
+COMMIT_EVERY = 100  # Commit to DB every N words
+
+
+async def fetch_definition(
+    session: aiohttp.ClientSession, word: str
+) -> tuple[str, str, str | None]:
+    """Fetch definition for a single word with retry logic."""
+    url = f"{API_BASE}/{word}"
+
+    for attempt in range(3):
+        try:
+            async with session.get(url) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return (word, "success", json.dumps(data))
+                elif resp.status == 404:
+                    return (word, "not_found", None)
+                elif resp.status == 429:  # Rate limited
+                    await asyncio.sleep(2**attempt)
+                    continue
+                else:
+                    if attempt < 2:
+                        await asyncio.sleep(1)
+                        continue
+                    return (word, "error", None)
+        except Exception as e:
+            if attempt < 2:
+                await asyncio.sleep(1)
+                continue
+            print(f"  Error fetching '{word}': {e}")
+            return (word, "error", None)
+
+    return (word, "error", None)
+
+
+def get_words_to_enrich(conn: duckdb.DuckDBPyConnection) -> list[str]:
+    """Get curated English words that haven't been enriched yet."""
+    tables = conn.execute(
+        load_sql("enrichment/check_table_exists.sql"), ["definitions_raw"]
+    ).fetchall()
+
+    if not tables:
+        rows = conn.execute(load_sql("enrichment/words_to_enrich_initial.sql")).fetchall()
+    else:
+        rows = conn.execute(load_sql("enrichment/words_to_enrich.sql")).fetchall()
+
+    return [row[0] for row in rows]
+
+
+def ensure_definitions_table(conn: duckdb.DuckDBPyConnection) -> None:
+    """Create definitions_raw table if it doesn't exist."""
+    conn.execute(load_sql("ingestion/09_create_definitions_raw.sql"))
+
+
+def materialize_definitions(conn: duckdb.DuckDBPyConnection) -> None:
+    """Materialize parsed definitions into a proper table.
+
+    Extracts ALL definitions from the Free Dictionary API response,
+    not just the first one. Each row represents one definition with
+    indexes for entry, meaning, and definition within the JSON structure.
+
+    The raw JSON is kept in definitions_raw for debugging/reprocessing.
+    Lexeme is stored lowercase for fast equality joins.
+    """
+    print("Materializing definitions table...")
+    for stmt in load_sql("enrichment/materialize_definitions.sql").strip().split(";"):
+        if stmt.strip():
+            conn.execute(stmt)
+
+    for stmt in load_sql("enrichment/create_definition_indexes.sql").strip().split(";"):
+        if stmt.strip():
+            conn.execute(stmt)
+
+    count = conn.execute("SELECT COUNT(*) FROM definitions").fetchone()[0]
+    unique_words = conn.execute("SELECT COUNT(DISTINCT lexeme) FROM definitions").fetchone()[0]
+    print(f"  Materialized {count:,} definitions for {unique_words:,} words")
+
+
+def store_result(
+    conn: duckdb.DuckDBPyConnection, word: str, status: str, api_response: str | None
+) -> None:
+    """Store a single result in the database."""
+    conn.execute(
+        "INSERT OR REPLACE INTO definitions_raw (lexeme, api_response, fetched_at, status) VALUES (?, ?::JSON, ?, ?)",
+        [word, api_response, datetime.now().isoformat(), status],
+    )
+
+
+async def enrich_definitions(max_words: int | None = None) -> None:
+    """Fetch definitions for all curated English words."""
+    db_path = database_path()
+    print(f"Database: {db_path}\n")
+
+    # Get words to enrich
+    with duckdb.connect(db_path.as_posix(), read_only=True) as conn:
+        words = get_words_to_enrich(conn)
+
+    if max_words:
+        words = words[:max_words]
+
+    total = len(words)
+    if total == 0:
+        print("All words already enriched!")
+        return
+
+    print(f"Words to enrich: {total:,}")
+    print(f"Estimated time: {(total * DELAY_MS) / 1000 / 60:.1f} minutes\n")
+
+    stats = {"success": 0, "not_found": 0, "error": 0}
+    start_time = time.time()
+
+    with duckdb.connect(db_path.as_posix()) as conn:
+        ensure_definitions_table(conn)
+
+        async with aiohttp.ClientSession() as session:
+            for i, word in enumerate(words):
+                result = await fetch_definition(session, word)
+                _, status, api_response = result
+                stats[status] += 1
+                store_result(conn, word, status, api_response)
+
+                # Progress every 50 words
+                if (i + 1) % 50 == 0 or i + 1 == total:
+                    elapsed = time.time() - start_time
+                    rate = (i + 1) / elapsed if elapsed > 0 else 0
+                    remaining = (total - i - 1) / rate if rate > 0 else 0
+                    print(
+                        f"[{i + 1:,}/{total:,}] {100 * (i + 1) / total:.1f}% - {rate:.1f}/sec - ETA: {remaining / 60:.1f}m"
+                    )
+
+                # Commit periodically
+                if (i + 1) % COMMIT_EVERY == 0:
+                    conn.commit()
+
+                # Rate limiting
+                if i < total - 1:
+                    await asyncio.sleep(DELAY_MS / 1000)
+
+            conn.commit()
+
+    elapsed = time.time() - start_time
+    print(f"\nDone! {total:,} words in {elapsed / 60:.1f}m ({total / elapsed:.1f}/sec)")
+    print(
+        f"  Success: {stats['success']:,}, Not found: {stats['not_found']:,}, Errors: {stats['error']:,}"
+    )
+
+    # Materialize the definitions table for fast queries
+    with duckdb.connect(db_path.as_posix()) as conn:
+        materialize_definitions(conn)
+
+
+def get_stats() -> None:
+    """Show current enrichment statistics."""
+    db_path = database_path()
+
+    with duckdb.connect(db_path.as_posix(), read_only=True) as conn:
+        tables = conn.execute(
+            load_sql("enrichment/check_table_exists.sql"), ["definitions_raw"]
+        ).fetchall()
+
+        if not tables:
+            print("No definitions_raw table yet. Run enrichment first.")
+            return
+
+        total_curated = conn.execute(
+            "SELECT COUNT(DISTINCT lexeme) FROM v_english_curated"
+        ).fetchone()[0]
+        stats = conn.execute(load_sql("enrichment/enrichment_stats.sql")).fetchall()
+
+        total_enriched = sum(s[1] for s in stats)
+        remaining = total_curated - total_enriched
+
+        print(f"Curated English words: {total_curated:,}")
+        print(f"Enriched: {total_enriched:,} ({100 * total_enriched / total_curated:.1f}%)")
+        print(f"Remaining: {remaining:,}\n")
+        print("By status:")
+        for status, count in stats:
+            print(f"  {status}: {count:,}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Enrich etymology database with definitions")
+    parser.add_argument("--stats", action="store_true", help="Show enrichment statistics")
+    parser.add_argument("--test", type=int, metavar="N", help="Test mode: only process N words")
+    args = parser.parse_args()
+
+    if args.stats:
+        get_stats()
+    else:
+        asyncio.run(enrich_definitions(max_words=args.test))
+
+
+if __name__ == "__main__":
+    main()

backend/ingest.py

@@ -0,0 +1,112 @@
+"""Load EtymDB CSV files into a DuckDB database."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import duckdb
+
+try:  # Local execution vs. package import
+    from .download_data import DATA_DIR, download
+    from .sql_loader import load_sql
+except ImportError:  # pragma: no cover - fallback for direct execution
+    from download_data import DATA_DIR, download
+    from sql_loader import load_sql
+
+DEFAULT_DB_PATH = DATA_DIR / "etymdb.duckdb"
+DEFAULT_VALUES = DATA_DIR / "etymdb_values.csv"
+DEFAULT_LINKS = DATA_DIR / "etymdb_links_info.csv"
+DEFAULT_LINKS_INDEX = DATA_DIR / "etymdb_links_index.csv"
+
+DB_PATH = Path(os.environ.get("ETYM_DB_PATH", DEFAULT_DB_PATH))
+VALUES_CSV = Path(os.environ.get("ETYM_VALUES_CSV", DEFAULT_VALUES))
+LINKS_CSV = Path(os.environ.get("ETYM_LINKS_CSV", DEFAULT_LINKS))
+LINKS_INDEX_CSV = Path(os.environ.get("ETYM_LINKS_INDEX_CSV", DEFAULT_LINKS_INDEX))
+
+
+def _ensure_csvs() -> None:
+    required = [VALUES_CSV, LINKS_CSV, LINKS_INDEX_CSV]
+    if all(f.exists() for f in required):
+        return
+    download()
+    if not all(f.exists() for f in required):  # pragma: no cover - defensive
+        raise FileNotFoundError("Failed to download required CSV files")
+
+
+def main() -> None:
+    """Create or refresh the DuckDB database from the CSV files."""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _ensure_csvs()
+
+    with duckdb.connect(DB_PATH.as_posix()) as conn:
+        # Drop and recreate core tables
+        for stmt in load_sql("ingestion/01_drop_tables.sql").strip().split(";"):
+            if stmt.strip():
+                conn.execute(stmt)
+
+        conn.execute(load_sql("ingestion/02_create_words.sql"), [VALUES_CSV.as_posix()])
+        conn.execute(load_sql("ingestion/03_create_links.sql"), [LINKS_CSV.as_posix()])
+        conn.execute(load_sql("ingestion/04_create_sequences.sql"))
+
+        # Parse and insert sequences (handles variable-length rows)
+        with open(LINKS_INDEX_CSV, encoding="utf-8") as f:
+            for line in f:
+                parts = line.strip().split("\t")
+                if len(parts) < 2:
+                    continue
+                seq_ix = int(parts[0])
+                for position, parent in enumerate(parts[1:]):
+                    if parent:
+                        conn.execute(
+                            "INSERT INTO sequences VALUES (?, ?, ?)",
+                            [seq_ix, position, int(parent)],
+                        )
+
+        # Create indexes
+        for stmt in load_sql("ingestion/05_create_indexes.sql").strip().split(";"):
+            if stmt.strip():
+                conn.execute(stmt)
+
+        # Gold Layer: Macros, Views, and Reference Tables
+        for stmt in load_sql("ingestion/06_create_macros.sql").strip().split(";"):
+            if stmt.strip():
+                conn.execute(stmt)
+
+        for stmt in load_sql("ingestion/07_create_views.sql").strip().split(";"):
+            if stmt.strip():
+                conn.execute(stmt)
+
+        # Language families reference table
+        language_codes_path = DATA_DIR / "language_codes.json"
+        if not language_codes_path.exists():
+            raise FileNotFoundError(
+                f"Missing {language_codes_path}. "
+                "Run `python -m backend.download_language_codes` first."
+            )
+
+        for stmt in load_sql("ingestion/08_create_language_families.sql").strip().split(";"):
+            if stmt.strip():
+                conn.execute(stmt)
+
+        with open(language_codes_path, encoding="utf-8") as f:
+            language_data = json.load(f)
+        for entry in language_data:
+            conn.execute(
+                "INSERT INTO language_families VALUES (?, ?, ?, ?)",
+                [
+                    entry["code"],
+                    entry["name"],
+                    entry.get("family"),
+                    entry.get("branch"),
+                ],
+            )
+
+        # Definition enrichment tables
+        conn.execute(load_sql("ingestion/09_create_definitions_raw.sql"))
+
+
+if __name__ == "__main__":  # pragma: no cover - manual utility
+    main()

backend/main.py

@@ -0,0 +1,108 @@
+"""FastAPI application exposing the etymology graph endpoints."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
+
+try:  # Support execution via `python backend/main.py`
+    from .database import (
+        fetch_etymology,
+        fetch_random_word,
+        get_db_stats,
+        search_words,
+    )
+except ImportError:  # pragma: no cover - fallback when run as a script
+    from database import fetch_etymology, fetch_random_word, get_db_stats, search_words
+
+limiter = Limiter(key_func=get_remote_address)
+app = FastAPI(title="Etymology Graph API")
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# Resolve frontend directory relative to this file
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
+
+
+@app.get("/health")
+def health_check():
+    """Health check endpoint for container orchestration."""
+    try:
+        stats = get_db_stats()
+        return {"status": "healthy", "db": stats}
+    except Exception as exc:
+        return JSONResponse(
+            status_code=503,
+            content={"status": "unhealthy", "reason": str(exc)},
+        )
+
+
+def _get_version() -> str:
+    """Read version from package metadata, falling back to pyproject.toml."""
+    try:
+        return importlib.metadata.version("etymology-for-all")
+    except importlib.metadata.PackageNotFoundError:
+        # Fallback: parse pyproject.toml directly
+        toml_path = Path(__file__).resolve().parent.parent / "pyproject.toml"
+        for line in toml_path.read_text().splitlines():
+            if line.strip().startswith("version"):
+                return line.split("=", 1)[1].strip().strip('"')
+        return "unknown"
+
+
+@app.get("/version")
+def version():
+    """Return the application version and database statistics."""
+    return {"version": _get_version(), "db_stats": get_db_stats()}
+
+
+@app.get("/graph/{word}")
+@limiter.limit("20/minute")
+def get_graph(request: Request, word: str, depth: int = 5):
+    """Fetch etymology graph for a word."""
+    # Clamp depth to reasonable bounds
+    depth = max(1, min(depth, 10))
+    graph = fetch_etymology(word, depth=depth)
+    if graph is None:
+        raise HTTPException(status_code=404, detail="Word not found in the database")
+    return graph
+
+
+@app.get("/random")
+@limiter.limit("50/minute")
+def get_random_word(request: Request, include_compound: bool = True):
+    """Return a random English word from the dataset.
+
+    Args:
+        include_compound: If True (default), include compound-only words.
+                         If False, only return words with deep etymology chains.
+    """
+    return fetch_random_word(include_compound=include_compound)
+
+
+@app.get("/search")
+@limiter.limit("120/minute")
+def search(request: Request, q: str = "", limit: int = 10):
+    """Search for words matching the query (autocomplete)."""
+    if len(q) < 2:
+        return {"results": []}
+    results = search_words(q, min(limit, 20))  # Cap at 20
+    return {"results": results}
+
+
+# Serve frontend static files (must be after API routes)
+if FRONTEND_DIR.exists():
+
+    @app.get("/")
+    def serve_index():
+        """Serve the main HTML page."""
+        return FileResponse(FRONTEND_DIR / "index.html")
+
+    app.mount("/", StaticFiles(directory=FRONTEND_DIR), name="frontend")

backend/sql/enrichment/check_table_exists.sql

@@ -0,0 +1,3 @@
+SELECT table_name
+FROM information_schema.tables
+WHERE table_name = ?

backend/sql/enrichment/create_definition_indexes.sql

@@ -0,0 +1,2 @@
+CREATE INDEX idx_definitions_lexeme ON definitions(lexeme);
+CREATE INDEX idx_definitions_primary ON definitions(lexeme, entry_idx, meaning_idx, def_idx);

backend/sql/enrichment/enrichment_stats.sql

@@ -0,0 +1,3 @@
+SELECT status, COUNT(*) as count
+FROM definitions_raw
+GROUP BY status

backend/sql/enrichment/materialize_definitions.sql

@@ -0,0 +1,36 @@
+DROP TABLE IF EXISTS definitions;
+DROP VIEW IF EXISTS v_definitions;
+
+CREATE TABLE definitions AS
+WITH entries AS (
+    SELECT
+        lower(lexeme) as lexeme,
+        unnest(from_json(api_response, '["json"]')) as entry,
+        generate_subscripts(from_json(api_response, '["json"]'), 1) - 1 as entry_idx
+    FROM definitions_raw
+    WHERE status = 'success'
+),
+meanings AS (
+    SELECT
+        lexeme, entry_idx,
+        unnest(from_json(json_extract(entry, '$.meanings'), '["json"]')) as meaning,
+        generate_subscripts(from_json(json_extract(entry, '$.meanings'), '["json"]'), 1) - 1 as meaning_idx
+    FROM entries
+),
+defs AS (
+    SELECT
+        lexeme, entry_idx, meaning_idx,
+        json_extract_string(meaning, '$.partOfSpeech') as part_of_speech,
+        unnest(from_json(json_extract(meaning, '$.definitions'), '["json"]')) as def,
+        generate_subscripts(from_json(json_extract(meaning, '$.definitions'), '["json"]'), 1) - 1 as def_idx
+    FROM meanings
+)
+SELECT
+    lexeme,
+    json_extract_string(def, '$.definition') as definition,
+    part_of_speech,
+    entry_idx,
+    meaning_idx,
+    def_idx
+FROM defs
+WHERE json_extract_string(def, '$.definition') IS NOT NULL

backend/sql/enrichment/words_to_enrich.sql

@@ -0,0 +1,5 @@
+SELECT DISTINCT c.lexeme
+FROM v_english_curated c
+LEFT JOIN definitions_raw d ON c.lexeme = d.lexeme
+WHERE d.lexeme IS NULL
+ORDER BY c.lexeme

backend/sql/enrichment/words_to_enrich_initial.sql

@@ -0,0 +1,3 @@
+SELECT DISTINCT lexeme
+FROM v_english_curated
+ORDER BY lexeme

backend/sql/ingestion/01_drop_tables.sql

@@ -0,0 +1,3 @@
+DROP TABLE IF EXISTS words;
+DROP TABLE IF EXISTS links;
+DROP TABLE IF EXISTS sequences;

backend/sql/ingestion/02_create_words.sql

@@ -0,0 +1,13 @@
+CREATE TABLE words AS
+SELECT
+    word_ix::BIGINT AS word_ix,
+    lang,
+    lexeme,
+    sense
+FROM read_csv_auto(?, delim='\t', header=false, columns={
+    'word_ix': 'BIGINT',
+    'lang': 'VARCHAR',
+    'dummy': 'INTEGER',
+    'lexeme': 'VARCHAR',
+    'sense': 'VARCHAR'
+})

backend/sql/ingestion/03_create_links.sql

@@ -0,0 +1,10 @@
+CREATE TABLE links AS
+SELECT
+    type,
+    source::BIGINT AS source,
+    target::BIGINT AS target
+FROM read_csv_auto(?, delim='\t', header=false, columns={
+    'type': 'VARCHAR',
+    'source': 'BIGINT',
+    'target': 'BIGINT'
+})

backend/sql/ingestion/04_create_sequences.sql

@@ -0,0 +1,5 @@
+CREATE TABLE sequences (
+    seq_ix BIGINT,
+    position INT,
+    parent_ix BIGINT
+)

backend/sql/ingestion/05_create_indexes.sql

@@ -0,0 +1,6 @@
+CREATE INDEX idx_words_word_ix ON words(word_ix);
+CREATE INDEX idx_words_lexeme ON words(lexeme);
+CREATE INDEX idx_links_source ON links(source);
+CREATE INDEX idx_links_target ON links(target);
+CREATE INDEX idx_sequences_seq_ix ON sequences(seq_ix);
+CREATE INDEX idx_sequences_parent_ix ON sequences(parent_ix);

backend/sql/ingestion/06_create_macros.sql

@@ -0,0 +1,11 @@
+CREATE OR REPLACE MACRO is_phrase(lexeme) AS
+    lexeme LIKE '% %';
+
+CREATE OR REPLACE MACRO is_proper_noun(lexeme) AS
+    regexp_matches(lexeme, '^[A-Z][a-z]');
+
+CREATE OR REPLACE MACRO is_clean_word(lexeme) AS
+    NOT is_phrase(lexeme) AND NOT is_proper_noun(lexeme);
+
+CREATE OR REPLACE MACRO has_etymology(word_ix) AS
+    word_ix IN (SELECT DISTINCT source FROM links);

backend/sql/ingestion/07_create_views.sql

@@ -0,0 +1,23 @@
+-- Curated view: English words with etymology, no phrases/proper nouns
+-- Filter out sense=NULL entries which are often garbage (e.g., suffix entries
+-- like "-er" with corrupted links to unrelated words like "asteroid belt")
+-- Paper notes 40% of EtymDB lacks glosses; our curated set is 99% with sense
+CREATE OR REPLACE VIEW v_english_curated AS
+SELECT DISTINCT w.*
+FROM words w
+JOIN links l ON w.word_ix = l.source
+WHERE w.lang = 'en'
+  AND is_clean_word(w.lexeme)
+  AND w.sense IS NOT NULL;
+
+-- View for words with "deep" etymology (at least one link to a real word)
+-- Excludes compound-only words where all links point to sequences (negative IDs)
+-- Also excludes sense=NULL entries (same rationale as v_english_curated)
+CREATE OR REPLACE VIEW v_english_deep AS
+SELECT DISTINCT w.*
+FROM words w
+JOIN links l ON w.word_ix = l.source
+WHERE w.lang = 'en'
+  AND is_clean_word(w.lexeme)
+  AND w.sense IS NOT NULL
+  AND l.target > 0;

backend/sql/ingestion/08_create_language_families.sql

@@ -0,0 +1,8 @@
+DROP TABLE IF EXISTS language_families;
+
+CREATE TABLE language_families (
+    lang_code VARCHAR PRIMARY KEY,
+    lang_name VARCHAR,
+    family VARCHAR,
+    branch VARCHAR
+)

backend/sql/ingestion/09_create_definitions_raw.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS definitions_raw (
+    lexeme VARCHAR PRIMARY KEY,
+    api_response JSON,
+    fetched_at TIMESTAMP,
+    status VARCHAR
+)

backend/sql/queries/find_start_word.sql

@@ -0,0 +1,10 @@
+SELECT w.word_ix, w.lang, w.lexeme, w.sense
+FROM words w
+LEFT JOIN links l ON l.source = w.word_ix
+WHERE lower(w.lexeme) = lower(?)
+GROUP BY w.word_ix, w.lang, w.lexeme, w.sense
+ORDER BY
+    CASE WHEN w.lang = 'en' THEN 0 ELSE 1 END,
+    COUNT(l.target) DESC,
+    w.word_ix
+LIMIT 1

backend/sql/queries/get_language_families.sql

@@ -0,0 +1,2 @@
+SELECT lang_code, lang_name, family, branch
+FROM language_families

backend/sql/queries/get_language_info.sql

@@ -0,0 +1,3 @@
+SELECT lang_name, family, branch
+FROM language_families
+WHERE lang_code = ?

backend/sql/queries/search_words.sql

@@ -0,0 +1,15 @@
+SELECT w.lexeme, w.sense, d.definition, d.part_of_speech, dc.def_count
+FROM v_english_curated w
+LEFT JOIN definitions d ON d.lexeme = lower(w.lexeme)
+    AND d.entry_idx = 0 AND d.meaning_idx = 0 AND d.def_idx = 0
+LEFT JOIN (
+    SELECT lexeme, COUNT(*) as def_count
+    FROM definitions
+    GROUP BY lexeme
+) dc ON dc.lexeme = lower(w.lexeme)
+WHERE lower(w.lexeme) LIKE lower(?) || '%'
+ORDER BY
+    CASE WHEN lower(w.lexeme) = lower(?) THEN 0 ELSE 1 END,
+    length(w.lexeme),
+    w.lexeme,
+    w.word_ix

backend/sql/queries/traverse_etymology.sql

@@ -0,0 +1,42 @@
+WITH RECURSIVE
+-- Resolve negative targets through sequences table
+resolved_links AS (
+    -- Simple links (positive target = direct word reference)
+    SELECT source, target AS parent_ix, FALSE AS is_compound, type
+    FROM links
+    WHERE target > 0
+    UNION ALL
+    -- Compound links (negative target = sequence, resolve to parents)
+    SELECT l.source, s.parent_ix, TRUE AS is_compound, l.type
+    FROM links l
+    JOIN sequences s ON s.seq_ix = l.target
+    WHERE l.target < 0
+),
+traversal(child_ix, parent_ix, is_compound, type, lvl) AS (
+    SELECT source, parent_ix, is_compound, type, 1
+    FROM resolved_links
+    WHERE source = ?
+    UNION ALL
+    -- Only follow FROM parents that have valid sense (non-NULL for English)
+    -- This keeps sense=NULL entries as nodes but doesn't traverse their garbage links
+    SELECT rl.source, rl.parent_ix, rl.is_compound, rl.type, lvl + 1
+    FROM traversal t
+    JOIN resolved_links rl ON rl.source = t.parent_ix
+    JOIN words parent_word ON parent_word.word_ix = t.parent_ix
+    WHERE lvl < ?
+      AND (parent_word.lang != 'en' OR parent_word.sense IS NOT NULL)
+)
+SELECT
+    child.word_ix AS child_ix,
+    child.lexeme AS child_lexeme,
+    child.lang AS child_lang,
+    child.sense AS child_sense,
+    parent.word_ix AS parent_ix,
+    parent.lexeme AS parent_lexeme,
+    parent.lang AS parent_lang,
+    parent.sense AS parent_sense,
+    tr.is_compound,
+    tr.type
+FROM traversal tr
+JOIN words child ON child.word_ix = tr.child_ix
+JOIN words parent ON parent.word_ix = tr.parent_ix

backend/sql_loader.py

@@ -0,0 +1,19 @@
+"""Load SQL files from the backend/sql/ directory."""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+SQL_DIR = Path(__file__).parent / "sql"
+
+
+@cache
+def load_sql(filename: str) -> str:
+    """Read and cache a SQL file from backend/sql/.
+
+    Args:
+        filename: Relative path within the sql/ directory,
+                  e.g. "queries/find_start_word.sql"
+    """
+    return (SQL_DIR / filename).read_text()

cloudflare-worker/worker.js

@@ -0,0 +1,7 @@
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+    url.hostname = 'lucharo-etymology.hf.space';
+    return fetch(url, request);
+  }
+}

cloudflare-worker/wrangler.toml

@@ -0,0 +1,8 @@
+name = "etymology-proxy"
+main = "worker.js"
+compatibility_date = "2025-12-21"
+
+# Custom domain - Cloudflare handles DNS + SSL automatically
+routes = [
+  { pattern = "etymology.luischav.es", custom_domain = true }
+]

frontend/index.html

@@ -0,0 +1,456 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Etymology Graph Explorer</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=EB+Garamond:ital,wght@0,400;0,600;1,400&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="styles.css?v=60">
+    <script src="https://unpkg.com/cytoscape@3.28.1/dist/cytoscape.min.js"></script>
+    <script src="https://unpkg.com/dagre@0.8.5/dist/dagre.min.js"></script>
+    <script src="https://unpkg.com/cytoscape-dagre@2.5.0/cytoscape-dagre.js"></script>
+</head>
+<body>
+    <main>
+        <header>
+            <h1>Etymology Explorer</h1>
+            <p class="subtitle">Trace the origins of words through time</p>
+            <div class="header-buttons">
+                <!-- Desktop: individual buttons -->
+                <a href="https://github.com/lucharo/etymology-for-all/issues/new/choose" target="_blank" rel="noopener" class="header-btn desktop-only" title="Report an issue">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <circle cx="12" cy="12" r="10"></circle>
+                        <line x1="12" y1="8" x2="12" y2="12"></line>
+                        <line x1="12" y1="16" x2="12.01" y2="16"></line>
+                    </svg>
+                    <span class="btn-label">Issue</span>
+                </a>
+                <button id="about-btn" class="header-btn desktop-only" title="About this project">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <circle cx="12" cy="12" r="10"></circle>
+                        <path d="M12 16v-4"></path>
+                        <path d="M12 8h.01"></path>
+                    </svg>
+                    <span class="btn-label">About</span>
+                </button>
+                <div class="settings-wrapper desktop-only">
+                    <button id="settings-btn" class="header-btn" title="Settings" aria-label="Settings">
+                        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                            <path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"></path>
+                            <circle cx="12" cy="12" r="3"></circle>
+                        </svg>
+                    </button>
+                    <div id="settings-popover" class="settings-popover hidden">
+                        <label class="settings-option" title="Include compound words in random selection and graph display">
+                            <input type="checkbox" id="include-compound" checked>
+                            <span>Include compound words</span>
+                        </label>
+                        <label class="settings-option" title="Color edges by link type (inherited, borrowed, derived, cognate)">
+                            <input type="checkbox" id="show-link-types">
+                            <span>Show link types</span>
+                        </label>
+                    </div>
+                </div>
+                <!-- Mobile: single menu button -->
+                <div class="mobile-menu-wrapper mobile-only">
+                    <button id="mobile-menu-btn" class="header-btn" title="Menu" aria-label="Menu">
+                        <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                            <circle cx="5" cy="12" r="1"></circle>
+                            <circle cx="12" cy="12" r="1"></circle>
+                            <circle cx="19" cy="12" r="1"></circle>
+                        </svg>
+                    </button>
+                    <div id="mobile-menu" class="mobile-menu hidden">
+                        <button id="mobile-about-btn" class="mobile-menu-item mobile-about-link">About &rsaquo;</button>
+                        <div class="mobile-menu-divider"></div>
+                        <label class="mobile-menu-item settings-option" title="Include compound words">
+                            <input type="checkbox" id="mobile-include-compound" checked>
+                            <span>Include compound words</span>
+                        </label>
+                        <label class="mobile-menu-item settings-option" title="Color edges by link type">
+                            <input type="checkbox" id="mobile-show-link-types">
+                            <span>Show link types</span>
+                        </label>
+                        <div class="mobile-menu-divider"></div>
+                        <a href="https://github.com/lucharo/etymology-for-all/issues/new/choose" target="_blank" rel="noopener" class="mobile-menu-item mobile-external-link">Report an issue <span class="external-icon">↗</span></a>
+                    </div>
+                </div>
+            </div>
+        </header>
+
+        <div class="search-container">
+            <div class="search-wrapper">
+                <input
+                    type="text"
+                    id="word-input"
+                    placeholder="Enter a word..."
+                    autocomplete="off"
+                    autofocus
+                >
+                <div id="suggestions" class="suggestions hidden"></div>
+            </div>
+            <button id="search-btn" title="Search">
+                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                    <circle cx="11" cy="11" r="8"></circle>
+                    <path d="m21 21-4.3-4.3"></path>
+                </svg>
+            </button>
+            <button id="random-btn" title="Random word" aria-label="Random word">
+                <span style="font-size: 1.3em; line-height: 1;">&#x1F3B2;</span>
+            </button>
+        </div>
+        <p class="search-hint">Click any word in the graph to see its definition</p>
+
+        <!-- Backdrop for expanded graph -->
+        <div id="graph-backdrop" class="graph-backdrop"></div>
+
+        <!-- Graph options -->
+        <div id="graph-options" class="graph-options hidden">
+            <div class="view-toggle">
+                <button id="view-graph" class="view-btn active" title="Graph view">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <circle cx="12" cy="12" r="3"></circle>
+                        <circle cx="19" cy="5" r="2"></circle>
+                        <circle cx="5" cy="19" r="2"></circle>
+                        <circle cx="5" cy="5" r="2"></circle>
+                        <line x1="12" y1="9" x2="12" y2="5"></line>
+                        <line x1="6.5" y1="17.5" x2="9.5" y2="14.5"></line>
+                        <line x1="17.5" y1="6.5" x2="14.5" y2="9.5"></line>
+                    </svg>
+                    Graph
+                </button>
+                <button id="view-tree" class="view-btn" title="Tree view">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <path d="M12 3v18"></path>
+                        <path d="M5 8h14"></path>
+                        <path d="M5 16h14"></path>
+                    </svg>
+                    Tree
+                </button>
+            </div>
+            <div class="depth-control">
+                <span class="depth-label">Depth:</span>
+                <button id="depth-minus" class="depth-btn" title="Decrease depth">−</button>
+                <span id="depth-value" class="depth-value">5</span>
+                <button id="depth-plus" class="depth-btn" title="Increase depth">+</button>
+            </div>
+        </div>
+
+        <div id="graph-container">
+            <!-- Expand/minimize toggle -->
+            <button id="expand-btn" class="expand-btn hidden" title="Expand graph (Esc to minimize)">
+                <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="expand-icon">
+                    <polyline points="15 3 21 3 21 9"></polyline>
+                    <polyline points="9 21 3 21 3 15"></polyline>
+                    <line x1="21" y1="3" x2="14" y2="10"></line>
+                    <line x1="3" y1="21" x2="10" y2="14"></line>
+                </svg>
+                <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="minimize-icon">
+                    <polyline points="4 14 10 14 10 20"></polyline>
+                    <polyline points="20 10 14 10 14 4"></polyline>
+                    <line x1="14" y1="10" x2="21" y2="3"></line>
+                    <line x1="3" y1="21" x2="10" y2="14"></line>
+                </svg>
+            </button>
+
+            <div id="loading" class="hidden">
+                <div class="spinner"></div>
+                <span>Tracing etymology...</span>
+            </div>
+            <div id="empty-state">
+                <p>Search for a word to see its etymological tree, or press <span style="font-size: 1.5em; vertical-align: middle; line-height: 1;">&#x1F3B2;</span> to get a random word</p>
+            </div>
+            <div id="error-state" class="hidden">
+                <p id="error-message"></p>
+                <div id="error-actions" class="error-actions"></div>
+            </div>
+            <div id="cy"></div>
+
+            <!-- Tree view (alternative to graph) -->
+            <div id="tree-view" class="tree-view hidden"></div>
+
+            <!-- Graph legend -->
+            <div class="graph-legend hidden" id="graph-legend">
+                <div class="edge-legend" id="edge-legend-simple">
+                    <span class="legend-item">
+                        <span class="legend-line regular"></span>
+                        <span>Etymology</span>
+                    </span>
+                    <span class="legend-item">
+                        <span class="legend-line compound"></span>
+                        <span>Compound</span>
+                    </span>
+                </div>
+                <div class="edge-legend hidden" id="edge-legend-detailed">
+                    <span class="legend-item">
+                        <span class="legend-line link-inh"></span>
+                        <span>Inherited</span>
+                    </span>
+                    <span class="legend-item">
+                        <span class="legend-line link-bor"></span>
+                        <span>Borrowed</span>
+                    </span>
+                    <span class="legend-item">
+                        <span class="legend-line link-der"></span>
+                        <span>Derived</span>
+                    </span>
+                    <span class="legend-item">
+                        <span class="legend-line link-cog"></span>
+                        <span>Cognate</span>
+                    </span>
+                    <span class="legend-item">
+                        <span class="legend-line link-cmpd"></span>
+                        <span>Compound</span>
+                    </span>
+                </div>
+                <span class="legend-divider">|</span>
+                <div id="direction-indicator">
+                    <span class="direction-label direction-recent">Recent</span>
+                    <span class="direction-arrow">→</span>
+                    <span class="direction-label direction-ancient">Ancient</span>
+                </div>
+            </div>
+
+            <!-- Node detail panel -->
+            <div id="node-detail" class="hidden">
+                <button id="detail-close" title="Close" aria-label="Close">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <line x1="18" y1="6" x2="6" y2="18"></line>
+                        <line x1="6" y1="6" x2="18" y2="18"></line>
+                    </svg>
+                </button>
+                <div class="detail-header">
+                    <span id="detail-lang" class="detail-lang"></span>
+                    <span id="detail-word" class="detail-word"></span>
+                </div>
+                <div class="detail-row">
+                    <span class="detail-label">
+                        Family
+                        <span class="info-btn" role="button" tabindex="0">i<span class="tooltip">Language family tree showing historical relationships</span></span>
+                    </span>
+                    <span id="detail-family" class="detail-value"></span>
+                </div>
+                <div class="detail-row">
+                    <span class="detail-label">Meaning</span>
+                    <span id="detail-sense" class="detail-value"></span>
+                </div>
+            </div>
+        </div>
+
+        <div id="word-info" class="hidden">
+            <span id="current-word"></span>
+            <span class="info-divider"></span>
+            <div id="lang-breakdown"></div>
+            <button id="stats-toggle" class="stats-toggle" title="Toggle graph statistics">
+                <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                    <line x1="18" y1="20" x2="18" y2="10"></line>
+                    <line x1="12" y1="20" x2="12" y2="4"></line>
+                    <line x1="6" y1="20" x2="6" y2="14"></line>
+                </svg>
+                Graph Stats
+            </button>
+        </div>
+
+        <!-- Stats panel expands below word-info, pushing footer down -->
+        <div id="stats-panel" class="stats-panel hidden">
+            <div class="stats-grid">
+                <div class="stat-item">
+                    <span class="stat-value" id="stat-nodes">0</span>
+                    <span class="stat-label">nodes</span>
+                </div>
+                <div class="stat-item">
+                    <span class="stat-value" id="stat-edges">0</span>
+                    <span class="stat-label">edges</span>
+                </div>
+                <div class="stat-item">
+                    <span class="stat-value" id="stat-langs">0</span>
+                    <span class="stat-label">languages</span>
+                </div>
+                <div class="stat-item">
+                    <span class="stat-value" id="stat-depth">0</span>
+                    <span class="stat-label">depth</span>
+                </div>
+            </div>
+        </div>
+
+        <!-- About Modal -->
+        <div id="about-modal" class="modal hidden">
+            <div class="modal-backdrop"></div>
+            <div class="modal-content">
+                <button id="about-close" class="modal-close" aria-label="Close">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <line x1="18" y1="6" x2="6" y2="18"></line>
+                        <line x1="6" y1="6" x2="18" y2="18"></line>
+                    </svg>
+                </button>
+
+                <div class="modal-tabs">
+                    <button class="modal-tab active" data-tab="about">About</button>
+                    <button class="modal-tab" data-tab="glossary">Glossary</button>
+                    <button class="modal-tab" data-tab="how">How It Works</button>
+                </div>
+
+                <div id="tab-about" class="tab-content active">
+                    <h2>Etymology for All</h2>
+                    <p class="philosophy">
+                        Etymology should be a <strong>public good</strong>.
+                    </p>
+                    <p>
+                        Many apps gatekeep etymological knowledge behind paywalls or proprietary databases.
+                        We believe the history of language belongs to everyone.
+                    </p>
+                    <p>
+                        This project exists to make word origins accessible, explorable, and free.
+                        Every word has a story—discover where yours came from.
+                    </p>
+                    <h3>Data Sources</h3>
+                    <p>
+                        <strong>Etymology:</strong> <a href="https://github.com/clefourrier/EtymDB" target="_blank" rel="noopener">EtymDB 2.1</a>,
+                        an open etymological database derived from Wiktionary containing 1.9 million words across 2,500+ languages.
+                    </p>
+                    <p class="citation">
+                        <a href="https://aclanthology.org/2020.lrec-1.392/" target="_blank" rel="noopener">Fourrier & Sagot (2020)</a>, "Methodological Aspects of Developing and Managing an Etymological Lexical Resource", LREC 2020
+                    </p>
+                    <p>
+                        <strong>Definitions:</strong> <a href="https://dictionaryapi.dev/" target="_blank" rel="noopener">Free Dictionary API</a>,
+                        a community-driven dictionary service also sourced from Wiktionary.
+                    </p>
+                </div>
+
+                <div id="tab-glossary" class="tab-content">
+                    <h2>Glossary</h2>
+                    <h3>Etymology</h3>
+                    <p>
+                        The study of word origins and how their meanings have changed throughout history.
+                        An etymology traces a word back through time to its earliest known form.
+                    </p>
+                    <h3>Ancestors</h3>
+                    <p>
+                        Words that a modern word <strong>inherited from</strong> or <strong>derived from</strong>.
+                        These form the direct lineage of a word through time.
+                    </p>
+                    <p class="example">
+                        Example: English "mother" ← Old English "mōdor" ← Proto-Germanic "*mōdēr" ← Proto-Indo-European "*méh₂tēr"
+                    </p>
+                    <h3>Cognates</h3>
+                    <p>
+                        Words in <strong>different languages</strong> that share a common ancestor.
+                        They evolved separately but have the same root.
+                    </p>
+                    <p class="example">
+                        Example: English "friend", German "Freund", Dutch "vriend", Gothic "frijōnds"
+                        — all from Proto-Germanic "*frijōndz"
+                    </p>
+                    <h3>Compound Etymology</h3>
+                    <p>
+                        When a word is formed from <strong>multiple source words</strong> or morphemes combined together.
+                        These are shown with blue edges in the graph.
+                    </p>
+                    <p class="example">
+                        Example: "uplander" = "upland" + "-er" (the suffix meaning "one who")
+                    </p>
+                    <h3>Morpheme</h3>
+                    <p>
+                        The smallest meaningful unit of language. Words are built from morphemes,
+                        including roots, prefixes, and suffixes.
+                    </p>
+                    <p class="example">
+                        Example: "unhappiness" contains three morphemes: "un-" (not) + "happy" (root) + "-ness" (state of)
+                    </p>
+                    <h3>Graph Traversal</h3>
+                    <p>
+                        The graph follows etymology connections recursively up to 5 levels deep,
+                        including both ancestors and cognates.
+                    </p>
+                    <p class="example">
+                        Example: "friend" connects to 12 words directly. Following each of those
+                        recursively for 5 levels yields 28 total nodes in the graph.
+                    </p>
+                    <h3>Language Family</h3>
+                    <p>
+                        A group of languages descended from a common ancestral language.
+                    </p>
+                    <p class="example">
+                        Example: English, German, Dutch, and Swedish are all part of the <strong>Germanic</strong> branch
+                        of the <strong>Indo-European</strong> family.
+                    </p>
+                    <h3>Proto-language</h3>
+                    <p>
+                        A reconstructed ancestral language that existed before writing.
+                        Linguists use the prefix "Proto-" and asterisks (*) for reconstructed forms.
+                    </p>
+                    <p class="example">
+                        Example: Proto-Indo-European (*méh₂tēr) is the reconstructed ancestor of words for "mother"
+                        across many languages, from English to Hindi.
+                    </p>
+                    <h3>Language Codes</h3>
+                    <p>
+                        Languages are identified by standardized codes from <a href="https://en.wikipedia.org/wiki/ISO_639-3" target="_blank" rel="noopener">ISO 639</a>,
+                        similar to how countries have two-letter codes (US, UK, DE).
+                        These codes help linguists and researchers categorize the world's ~7,000 languages consistently.
+                    </p>
+                    <p class="example">
+                        Examples: <code>en</code> = English, <code>la</code> = Latin, <code>grc</code> = Ancient Greek,
+                        <code>ang</code> = Old English, <code>gem-pro</code> = Proto-Germanic, <code>ine-pro</code> = Proto-Indo-European
+                    </p>
+                    <h3>Why Random Words Are Obscure</h3>
+                    <p>
+                        Word usage follows <a href="https://en.wikipedia.org/wiki/Zipf%27s_law" target="_blank" rel="noopener">Zipf's Law</a>—a
+                        small number of words make up most of what we read, while thousands of rare words form a "long tail."
+                        Our random button samples uniformly, giving you equal chances of discovering hidden gems like "cystolithic" or "auxotrophy."
+                    </p>
+                </div>
+
+                <div id="tab-how" class="tab-content">
+                    <h2>How It Works</h2>
+                    <h3>The Data Pipeline</h3>
+                    <ol>
+                        <li><strong>Source:</strong> EtymDB extracts etymology data from Wiktionary</li>
+                        <li><strong>Curation:</strong> We filter for clean English words with valid etymology links (~40K words)</li>
+                        <li><strong>Language metadata:</strong> Each word is tagged with its language family (e.g., "Germanic → Indo-European")</li>
+                        <li><strong>Definitions:</strong> Enriched from Free Dictionary API (~21K definitions)</li>
+                    </ol>
+                    <h3>Reading the Graph</h3>
+                    <ul>
+                        <li><strong>Arrows</strong> point from modern words to their ancestors</li>
+                        <li><strong>Click any word</strong> to see its language family and definition</li>
+                        <li><strong>Language families</strong> show how languages are historically related</li>
+                    </ul>
+                    <h3>Definition Matching</h3>
+                    <p>
+                        EtymDB provides a <strong>sense</strong> field for each word entry (e.g., "bank" might have
+                        senses like "financial institution" or "side of a river"). When the sense differs from
+                        the word itself, we display it directly.
+                    </p>
+                    <p>
+                        <strong>Key assumption:</strong> When a word's sense equals its lexeme (e.g., sense="bank"
+                        for word "bank"), we fall back to the <strong>first definition</strong> from the Free Dictionary API.
+                        We assume this primary definition corresponds to the word's main etymological meaning.
+                        This may not always be accurate for words with multiple distinct origins.
+                    </p>
+                    <h3>Limitations</h3>
+                    <p>
+                        Not all words have definitions available. Some etymology connections may be incomplete
+                        or reflect Wiktionary's editorial choices. Compound word breakdowns (e.g., "magn-animus")
+                        are not yet supported. Definition matching between EtymDB senses and dictionary entries
+                        is approximate—there is no shared identifier between the two data sources.
+                    </p>
+                </div>
+            </div>
+        </div>
+    </main>
+
+    <footer>
+        <p>Etymology from <a href="https://github.com/clefourrier/EtymDB" target="_blank" rel="noopener">EtymDB 2.1</a>. Definitions from <a href="https://dictionaryapi.dev/" target="_blank" rel="noopener">Free Dictionary API</a>.</p>
+        <p>Built by <a href="https://github.com/lucharo" target="_blank" rel="noopener">@lucharo</a> · <a href="https://github.com/lucharo/etymology-for-all" target="_blank" rel="noopener">Source code</a></p>
+        <details id="version-details" class="version-details">
+            <summary id="version-summary">Version info</summary>
+            <div id="version-content" class="version-content">Loading...</div>
+        </details>
+    </footer>
+
+    <script type="module" src="js/app.js?v=6"></script>
+</body>
+</html>

frontend/js/app.js

@@ -0,0 +1,600 @@
+/**
+ * Etymology Graph Explorer - Main Application
+ * Interactive visualization of word origins using Cytoscape.js
+ */
+
+import { getLangName, checkNoEtymology } from './utils.js';
+import {
+    initCytoscape,
+    getCy,
+    filterGraphByDepth,
+    filterCompoundEdges,
+    calculateMaxGraphDepth,
+    calculateGraphDepth,
+    renderGraphElements,
+    setShowLinkTypes,
+} from './graph.js';
+import {
+    fetchEtymology,
+    fetchRandomWord,
+    fetchSuggestions,
+    hideSuggestions,
+    navigateSuggestions,
+    getSelectedSuggestion,
+} from './search.js';
+import {
+    showNodeDetail,
+    hideNodeDetail,
+    showLoading,
+    showError,
+    showGraph,
+    updateStats,
+    updateInfoSummary,
+    updateDepthUI,
+    createExpandHandlers,
+    setupModal,
+} from './ui.js';
+import { buildTree, renderTreeHTML } from './tree.js';
+
+// DOM elements
+const elements = {
+    wordInput: document.getElementById('word-input'),
+    searchBtn: document.getElementById('search-btn'),
+    randomBtn: document.getElementById('random-btn'),
+    includeCompound: document.getElementById('include-compound'),
+    graphContainer: document.getElementById('graph-container'),
+    cyContainer: document.getElementById('cy'),
+    loadingEl: document.getElementById('loading'),
+    emptyState: document.getElementById('empty-state'),
+    errorState: document.getElementById('error-state'),
+    errorMessage: document.getElementById('error-message'),
+    wordInfo: document.getElementById('word-info'),
+    currentWord: document.getElementById('current-word'),
+    langBreakdown: document.getElementById('lang-breakdown'),
+    nodeDetail: document.getElementById('node-detail'),
+    detailWord: document.getElementById('detail-word'),
+    detailLang: document.getElementById('detail-lang'),
+    detailFamily: document.getElementById('detail-family'),
+    detailSense: document.getElementById('detail-sense'),
+    detailClose: document.getElementById('detail-close'),
+    suggestions: document.getElementById('suggestions'),
+    graphLegend: document.getElementById('graph-legend'),
+    directionIndicator: document.getElementById('direction-indicator'),
+    depthMinus: document.getElementById('depth-minus'),
+    depthPlus: document.getElementById('depth-plus'),
+    depthValue: document.getElementById('depth-value'),
+    graphOptions: document.getElementById('graph-options'),
+    expandBtn: document.getElementById('expand-btn'),
+    graphBackdrop: document.getElementById('graph-backdrop'),
+    statsToggle: document.getElementById('stats-toggle'),
+    statsPanel: document.getElementById('stats-panel'),
+    statNodes: document.getElementById('stat-nodes'),
+    statEdges: document.getElementById('stat-edges'),
+    statLangs: document.getElementById('stat-langs'),
+    statDepth: document.getElementById('stat-depth'),
+    viewGraphBtn: document.getElementById('view-graph'),
+    viewTreeBtn: document.getElementById('view-tree'),
+    treeView: document.getElementById('tree-view'),
+};
+
+// State
+let fullGraphData = null;
+let currentSearchedWord = null;
+let currentDepth = 5;
+let graphMaxDepth = 10;
+const MIN_DEPTH = 1;
+let searchTimeout = null;
+let serverReady = false;
+let graphAvailable = false;
+let currentView = 'graph'; // 'graph' or 'tree'
+
+// Server health check with retry (HF Spaces sleep after inactivity)
+async function checkServerHealth(maxWaitMs = 120000) {
+    const startTime = Date.now();
+    const emptyState = document.getElementById('empty-state');
+    const originalText = emptyState?.querySelector('p')?.textContent;
+    let attempt = 0;
+
+    while (Date.now() - startTime < maxWaitMs) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+
+            const response = await fetch('/health', { signal: controller.signal });
+            clearTimeout(timeout);
+
+            if (response.ok) {
+                // Server is ready
+                if (emptyState?.querySelector('p')) {
+                    emptyState.querySelector('p').textContent = originalText || 'Search for a word to see its etymological journey.';
+                }
+                serverReady = true;
+                return true;
+            }
+        } catch (e) {
+            // Server not ready yet
+        }
+
+        attempt++;
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        const remaining = Math.round((maxWaitMs - (Date.now() - startTime)) / 1000);
+
+        if (emptyState?.querySelector('p')) {
+            emptyState.querySelector('p').innerHTML =
+                `<span style="color: var(--accent);">Server waking up...</span><br>` +
+                `<small style="color: var(--text-muted);">Free tier sleeps after inactivity. Please wait (~${remaining}s remaining)</small>`;
+        }
+
+        // Wait before retry (1s, then 2s intervals)
+        await new Promise(r => setTimeout(r, attempt === 1 ? 1000 : 2000));
+    }
+
+    // Timeout reached
+    if (emptyState?.querySelector('p')) {
+        emptyState.querySelector('p').innerHTML =
+            `<span style="color: var(--error);">Server unavailable</span><br>` +
+            `<small>Please try refreshing the page.</small>`;
+    }
+    return false;
+}
+
+// Expand handlers
+const { toggleExpandGraph, minimizeGraph, getIsExpanded } = createExpandHandlers(
+    elements.graphContainer,
+    elements.graphBackdrop
+);
+
+// View toggle
+function setView(view) {
+    currentView = view;
+
+    // Update button states
+    if (elements.viewGraphBtn) {
+        elements.viewGraphBtn.classList.toggle('active', view === 'graph');
+    }
+    if (elements.viewTreeBtn) {
+        elements.viewTreeBtn.classList.toggle('active', view === 'tree');
+    }
+
+    // Toggle visibility
+    if (view === 'tree') {
+        elements.cyContainer.classList.add('hidden');
+        elements.treeView.classList.remove('hidden');
+        if (elements.graphLegend) {
+            elements.graphLegend.classList.add('hidden');
+        }
+        renderTreeView();
+    } else {
+        elements.treeView.classList.add('hidden');
+        elements.cyContainer.classList.remove('hidden');
+        // Re-render graph fully (may have been skipped while in tree view)
+        if (fullGraphData && currentSearchedWord) {
+            renderGraph(fullGraphData, currentSearchedWord, true);
+        }
+    }
+}
+
+// Render tree view
+function renderTreeView() {
+    if (!fullGraphData || !currentSearchedWord) {
+        elements.treeView.innerHTML = '<div class="tree-empty">Search for a word to see its etymology tree</div>';
+        return;
+    }
+
+    // Apply filters: depth first, then compound
+    const includeCompound = elements.includeCompound?.checked ?? true;
+    let displayData = filterGraphByDepth(fullGraphData, currentDepth, currentSearchedWord);
+    displayData = filterCompoundEdges(displayData, includeCompound, currentSearchedWord);
+
+    const tree = buildTree(displayData.nodes, displayData.edges, currentSearchedWord, currentDepth);
+    const treeHTML = renderTreeHTML(tree);
+    elements.treeView.innerHTML = treeHTML;
+
+    // Add click handlers for tree nodes
+    elements.treeView.querySelectorAll('.tree-node').forEach(node => {
+        node.addEventListener('click', () => {
+            const data = {
+                word: node.dataset.lexeme,
+                lang: node.dataset.lang,
+                langName: node.dataset.langName,
+                sense: node.dataset.sense || null,
+                family: node.dataset.family || null,
+                branch: node.dataset.branch || null,
+            };
+            showNodeDetail(data, elements);
+        });
+    });
+}
+
+// Render graph with current depth
+function renderGraph(data, searchedWord, filterByDepth = true) {
+    // Check for no-etymology response
+    const noEtym = checkNoEtymology(data);
+    if (noEtym) {
+        const word = noEtym.lexeme || searchedWord;
+        showError(
+            `'${word}' was found but has no etymology data in EtymDB`,
+            elements,
+            minimizeGraph,
+            { wiktionaryWord: word, searchedWord: word }
+        );
+        return;
+    }
+
+    if (!data.nodes || data.nodes.length === 0) {
+        showError('No etymology data available for this word', elements, minimizeGraph, { searchedWord });
+        return;
+    }
+
+    if (!filterByDepth || !fullGraphData || currentSearchedWord !== searchedWord) {
+        fullGraphData = data;
+        currentSearchedWord = searchedWord;
+        graphMaxDepth = calculateMaxGraphDepth(data.nodes, data.edges, searchedWord);
+        currentDepth = graphMaxDepth;
+    }
+
+    // Apply filters: depth first, then compound
+    const includeCompound = elements.includeCompound?.checked ?? true;
+    let displayData = filterByDepth
+        ? filterGraphByDepth(fullGraphData, currentDepth, searchedWord)
+        : data;
+    displayData = filterCompoundEdges(displayData, includeCompound, searchedWord);
+
+    if (elements.graphOptions) elements.graphOptions.classList.remove('hidden');
+    updateDepthUI(currentDepth, graphMaxDepth, elements);
+
+    hideNodeDetail(elements.nodeDetail);
+
+    elements.currentWord.textContent = searchedWord;
+    elements.wordInfo.classList.remove('hidden');
+    showGraph(elements);
+
+    if (currentView === 'tree') {
+        // In tree view, only render tree — skip expensive graph layout
+        renderTreeView();
+    } else {
+        // Render graph and legend
+        const { seenLangs, langCounts, langCodes } = renderGraphElements(displayData, elements.graphLegend, elements.directionIndicator);
+        updateInfoSummary(langCounts, langCodes, elements.langBreakdown);
+
+        // Re-fit after browser has reflowed layout (double-RAF ensures reflow is complete)
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                const cy = getCy();
+                if (cy) {
+                    cy.resize();
+                    cy.fit(undefined, 40);
+                }
+            });
+        });
+
+        setTimeout(() => {
+            const graphDepth = calculateGraphDepth(searchedWord);
+            updateStats(displayData.nodes.length, displayData.edges.length, langCounts.size, graphDepth, elements);
+        }, 50);
+    }
+}
+
+// Search handler
+async function handleSearch() {
+    const word = elements.wordInput.value.trim();
+    if (!word) return;
+
+    if (!graphAvailable) {
+        showError('Graph engine is not available. Try refreshing the page.', elements, minimizeGraph);
+        return;
+    }
+
+    showLoading(elements);
+
+    try {
+        const data = await fetchEtymology(word);
+        renderGraph(data, word);
+    } catch (err) {
+        showError(err.message, elements, minimizeGraph, { searchedWord: word });
+    }
+}
+
+// Random word handler
+async function handleRandom() {
+    if (!graphAvailable) {
+        showError('Graph engine is not available. Try refreshing the page.', elements, minimizeGraph);
+        return;
+    }
+
+    showLoading(elements);
+
+    try {
+        const includeCompound = elements.includeCompound?.checked ?? true;
+        const word = await fetchRandomWord(includeCompound);
+        if (!word) {
+            showError('Could not get a random word', elements, minimizeGraph);
+            return;
+        }
+        elements.wordInput.value = word;
+        const data = await fetchEtymology(word);
+        renderGraph(data, word);
+    } catch (err) {
+        showError(err.message, elements, minimizeGraph, { searchedWord: elements.wordInput.value.trim() });
+    }
+}
+
+// Depth change
+function changeDepth(delta) {
+    const newDepth = currentDepth + delta;
+    if (newDepth < MIN_DEPTH || newDepth > graphMaxDepth) return;
+
+    currentDepth = newDepth;
+    updateDepthUI(currentDepth, graphMaxDepth, elements);
+
+    if (fullGraphData && currentSearchedWord) {
+        renderGraph(fullGraphData, currentSearchedWord, true);
+    }
+}
+
+// Suggestion selection
+function selectSuggestion(word) {
+    elements.wordInput.value = word;
+    hideSuggestions(elements.suggestions);
+    handleSearch();
+}
+
+// Initialize on DOM ready
+document.addEventListener('DOMContentLoaded', async () => {
+    // Check server health first (HF Spaces may be sleeping)
+    checkServerHealth(120000); // 2 minutes max wait, runs in background
+
+    // Initialize Cytoscape (wrapped so UI still works if CDN scripts failed to load)
+    try {
+        initCytoscape(
+            elements.cyContainer,
+            (data) => showNodeDetail(data, elements),
+            () => hideNodeDetail(elements.nodeDetail),
+            (node, container) => {
+                const sense = node.data('sense');
+                const langName = node.data('langName') || getLangName(node.data('lang'));
+                let tip = `${node.data('word')} (${langName})`;
+                if (sense) tip += `\n"${sense}"`;
+                container.title = tip;
+                container.style.cursor = 'pointer';
+            },
+            (container) => {
+                container.title = '';
+                container.style.cursor = 'default';
+            }
+        );
+        graphAvailable = true;
+    } catch (e) {
+        console.error('Failed to initialize graph engine:', e);
+        showError(
+            'Graph engine failed to load. Try refreshing the page.',
+            elements,
+            minimizeGraph
+        );
+    }
+
+    // Detail panel close
+    if (elements.detailClose) {
+        elements.detailClose.addEventListener('click', () => hideNodeDetail(elements.nodeDetail));
+    }
+
+    // Search buttons
+    elements.searchBtn.addEventListener('click', handleSearch);
+    elements.randomBtn.addEventListener('click', handleRandom);
+
+    // Depth buttons
+    if (elements.depthMinus) {
+        elements.depthMinus.addEventListener('click', () => changeDepth(-1));
+    }
+    if (elements.depthPlus) {
+        elements.depthPlus.addEventListener('click', () => changeDepth(1));
+    }
+
+    // Compound filter checkbox - re-renders graph when toggled
+    if (elements.includeCompound) {
+        elements.includeCompound.addEventListener('change', () => {
+            const mobileCompound = document.getElementById('mobile-include-compound');
+            if (mobileCompound) mobileCompound.checked = elements.includeCompound.checked;
+            if (fullGraphData && currentSearchedWord) {
+                renderGraph(fullGraphData, currentSearchedWord, true);
+            }
+        });
+    }
+
+    // Stats toggle
+    if (elements.statsToggle && elements.statsPanel) {
+        elements.statsToggle.addEventListener('click', () => {
+            const isHidden = elements.statsPanel.classList.toggle('hidden');
+            elements.statsToggle.classList.toggle('active', !isHidden);
+        });
+    }
+
+    // View toggle buttons
+    if (elements.viewGraphBtn) {
+        elements.viewGraphBtn.addEventListener('click', () => setView('graph'));
+    }
+    if (elements.viewTreeBtn) {
+        elements.viewTreeBtn.addEventListener('click', () => setView('tree'));
+    }
+
+    // Expand button
+    if (elements.expandBtn) {
+        elements.expandBtn.addEventListener('click', toggleExpandGraph);
+    }
+    if (elements.graphBackdrop) {
+        elements.graphBackdrop.addEventListener('click', minimizeGraph);
+    }
+
+    // Autocomplete input
+    elements.wordInput.addEventListener('input', (e) => {
+        clearTimeout(searchTimeout);
+        searchTimeout = setTimeout(() => {
+            fetchSuggestions(e.target.value.trim(), elements.suggestions, selectSuggestion);
+        }, 150);
+    });
+
+    // Keyboard navigation
+    elements.wordInput.addEventListener('keydown', (e) => {
+        const isOpen = elements.suggestions && !elements.suggestions.classList.contains('hidden');
+
+        if (e.key === 'Enter') {
+            if (isOpen) {
+                const selected = getSelectedSuggestion(elements.suggestions);
+                if (selected) {
+                    selectSuggestion(selected);
+                } else {
+                    hideSuggestions(elements.suggestions);
+                    handleSearch();
+                }
+            } else {
+                handleSearch();
+            }
+            e.preventDefault();
+        } else if (e.key === 'ArrowDown' && isOpen) {
+            navigateSuggestions(elements.suggestions, 1);
+            e.preventDefault();
+        } else if (e.key === 'ArrowUp' && isOpen) {
+            navigateSuggestions(elements.suggestions, -1);
+            e.preventDefault();
+        } else if (e.key === 'Escape') {
+            if (isOpen) {
+                hideSuggestions(elements.suggestions);
+            } else if (getIsExpanded()) {
+                minimizeGraph();
+            }
+        }
+    });
+
+    // Hide suggestions on outside click
+    document.addEventListener('click', (e) => {
+        if (!e.target.closest('.search-wrapper')) {
+            hideSuggestions(elements.suggestions);
+        }
+    });
+
+    // Settings popover toggle
+    const settingsBtn = document.getElementById('settings-btn');
+    const settingsPopover = document.getElementById('settings-popover');
+    if (settingsBtn && settingsPopover) {
+        settingsBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            settingsPopover.classList.toggle('hidden');
+        });
+        document.addEventListener('click', (e) => {
+            if (!e.target.closest('.settings-wrapper')) {
+                settingsPopover.classList.add('hidden');
+            }
+        });
+    }
+
+    // Setup modal
+    const aboutBtn = document.getElementById('about-btn');
+    const aboutModal = document.getElementById('about-modal');
+    const aboutClose = document.getElementById('about-close');
+    const modalBackdrop = aboutModal?.querySelector('.modal-backdrop');
+    const modalTabs = aboutModal?.querySelectorAll('.modal-tab');
+
+    const { closeAboutModal } = setupModal(aboutBtn, aboutModal, aboutClose, modalBackdrop, modalTabs);
+
+    // Escape for modal
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && aboutModal && !aboutModal.classList.contains('hidden')) {
+            closeAboutModal();
+        }
+    });
+
+    // Version info in footer
+    const versionDetails = document.getElementById('version-details');
+    const versionContent = document.getElementById('version-content');
+    const versionSummary = document.getElementById('version-summary');
+    if (versionDetails && versionContent) {
+        async function fetchVersion() {
+            try {
+                const response = await fetch('/version');
+                if (!response.ok) return;
+                const data = await response.json();
+                const version = data.version || 'unknown';
+                const stats = data.db_stats || {};
+                versionSummary.textContent = `v${version}`;
+                versionContent.innerHTML =
+                    `<span>Version: ${version}</span>` +
+                    (stats.words ? `<span>Words: ${stats.words.toLocaleString()}</span>` : '') +
+                    (stats.definitions ? `<span>Definitions: ${stats.definitions.toLocaleString()}</span>` : '');
+            } catch (e) {
+                versionContent.textContent = 'Could not load version info';
+            }
+        }
+        // Fetch on toggle or on load
+        versionDetails.addEventListener('toggle', () => {
+            if (versionDetails.open) fetchVersion();
+        });
+        // Also fetch eagerly so the summary shows the version
+        fetchVersion();
+    }
+
+    // Link types toggle - shared handler for both desktop and mobile checkboxes
+    const showLinkTypesCheckbox = document.getElementById('show-link-types');
+    const mobileShowLinkTypes = document.getElementById('mobile-show-link-types');
+    const simpleLegend = document.getElementById('edge-legend-simple');
+    const detailedLegend = document.getElementById('edge-legend-detailed');
+
+    function handleLinkTypesToggle(enabled) {
+        setShowLinkTypes(enabled);
+        if (simpleLegend) simpleLegend.classList.toggle('hidden', enabled);
+        if (detailedLegend) detailedLegend.classList.toggle('hidden', !enabled);
+        // Re-render to apply/remove link type colors
+        if (fullGraphData && currentSearchedWord) {
+            renderGraph(fullGraphData, currentSearchedWord, true);
+        }
+    }
+
+    if (showLinkTypesCheckbox) {
+        showLinkTypesCheckbox.addEventListener('change', () => {
+            const enabled = showLinkTypesCheckbox.checked;
+            if (mobileShowLinkTypes) mobileShowLinkTypes.checked = enabled;
+            handleLinkTypesToggle(enabled);
+        });
+    }
+
+    // Mobile menu
+    const mobileMenuBtn = document.getElementById('mobile-menu-btn');
+    const mobileMenu = document.getElementById('mobile-menu');
+    const mobileAboutBtn = document.getElementById('mobile-about-btn');
+    const mobileIncludeCompound = document.getElementById('mobile-include-compound');
+
+    if (mobileMenuBtn && mobileMenu) {
+        mobileMenuBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            mobileMenu.classList.toggle('hidden');
+        });
+        document.addEventListener('click', (e) => {
+            if (!e.target.closest('.mobile-menu-wrapper')) {
+                mobileMenu.classList.add('hidden');
+            }
+        });
+    }
+
+    if (mobileAboutBtn) {
+        mobileAboutBtn.addEventListener('click', () => {
+            mobileMenu?.classList.add('hidden');
+            if (aboutModal) aboutModal.classList.remove('hidden');
+        });
+    }
+
+    // Sync mobile compound checkbox with desktop
+    if (mobileIncludeCompound && elements.includeCompound) {
+        mobileIncludeCompound.addEventListener('change', () => {
+            elements.includeCompound.checked = mobileIncludeCompound.checked;
+            elements.includeCompound.dispatchEvent(new Event('change'));
+        });
+    }
+
+    // Sync mobile link types checkbox with desktop
+    if (mobileShowLinkTypes) {
+        mobileShowLinkTypes.addEventListener('change', () => {
+            const enabled = mobileShowLinkTypes.checked;
+            if (showLinkTypesCheckbox) showLinkTypesCheckbox.checked = enabled;
+            handleLinkTypesToggle(enabled);
+        });
+    }
+});

frontend/js/graph.js

@@ -0,0 +1,375 @@
+/**
+ * Graph rendering and Cytoscape functionality
+ */
+
+import { getLangName, buildNodeLabel } from './utils.js';
+
+let cy = null;
+let showLinkTypes = false;
+
+export function getCy() {
+    return cy;
+}
+
+// Link type color mapping
+const LINK_TYPE_COLORS = {
+    inh: '#059669',   // green - inherited
+    bor: '#d97706',   // amber - borrowed
+    der: '#7c3aed',   // purple - derived
+    cog: '#0284c7',   // blue - cognate
+    cmpd: '#0c4a6e',  // dark blue - compound
+};
+
+function getLinkTypeColor(type) {
+    if (!type) return null;
+    // Handle compound types like "cmpd+bor", "der(s)", "der(p)"
+    if (type.startsWith('cmpd')) return LINK_TYPE_COLORS.cmpd;
+    if (type.startsWith('der')) return LINK_TYPE_COLORS.der;
+    return LINK_TYPE_COLORS[type] || null;
+}
+
+export function setShowLinkTypes(value) {
+    showLinkTypes = value;
+    if (!cy) return;
+    cy.edges().forEach(edge => {
+        const type = edge.data('linkType');
+        if (showLinkTypes && type) {
+            const color = getLinkTypeColor(type);
+            if (color) {
+                edge.style('line-color', color);
+                edge.style('target-arrow-color', color);
+            }
+        } else if (edge.data('compound')) {
+            edge.style('line-color', '#0c4a6e');
+            edge.style('target-arrow-color', '#0c4a6e');
+        } else {
+            edge.style('line-color', '#d6d3d1');
+            edge.style('target-arrow-color', '#d6d3d1');
+        }
+    });
+}
+
+export function getLayoutDirection() {
+    return window.innerWidth > window.innerHeight ? 'LR' : 'TB';
+}
+
+export function initCytoscape(container, onNodeTap, onBackgroundTap, onNodeHover, onNodeOut) {
+    cy = cytoscape({
+        container,
+        style: [
+            {
+                selector: 'node',
+                style: {
+                    'label': 'data(label)',
+                    'text-valign': 'center',
+                    'text-halign': 'center',
+                    'text-wrap': 'wrap',
+                    'text-max-width': '140px',
+                    'background-color': '#f8fafc',
+                    'color': '#1c1917',
+                    'font-size': '13px',
+                    'font-family': 'system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif',
+                    'width': 'label',
+                    'height': 'label',
+                    'padding': '12px',
+                    'shape': 'round-rectangle',
+                    'border-width': '1px',
+                    'border-color': '#cbd5e1',
+                },
+            },
+            {
+                selector: 'node:selected',
+                style: {
+                    'border-width': '2px',
+                    'border-color': '#0284c7',
+                    'background-color': '#f0f9ff',
+                },
+            },
+            {
+                selector: 'edge',
+                style: {
+                    'width': 2,
+                    'line-color': '#d6d3d1',
+                    'target-arrow-color': '#d6d3d1',
+                    'target-arrow-shape': 'triangle',
+                    'curve-style': 'bezier',
+                    'arrow-scale': 1.2,
+                },
+            },
+            {
+                selector: 'edge:selected',
+                style: {
+                    'line-color': '#78716c',
+                    'target-arrow-color': '#78716c',
+                },
+            },
+            {
+                selector: 'edge[compound]',
+                style: {
+                    'line-color': '#0c4a6e',
+                    'target-arrow-color': '#0c4a6e',
+                },
+            },
+        ],
+        layout: { name: 'preset' },
+        minZoom: 0.3,
+        maxZoom: 3,
+        wheelSensitivity: 0.3,
+    });
+
+    cy.on('tap', 'node', (e) => onNodeTap(e.target.data()));
+    cy.on('tap', (e) => {
+        if (e.target === cy) onBackgroundTap();
+    });
+    cy.on('mouseover', 'node', (e) => onNodeHover(e.target, container));
+    cy.on('mouseout', 'node', () => onNodeOut(container));
+
+    return cy;
+}
+
+// Compute depth of each node from the starting word using BFS
+export function computeNodeDepths(nodes, edges, startWord) {
+    const nodeDepths = new Map();
+    const adjacency = new Map();
+
+    edges.forEach(edge => {
+        if (!adjacency.has(edge.source)) adjacency.set(edge.source, []);
+        adjacency.get(edge.source).push(edge.target);
+    });
+
+    const startNode = nodes.find(n =>
+        n.lexeme && n.lexeme.toLowerCase() === startWord.toLowerCase() && n.lang === 'en'
+    );
+
+    if (!startNode) {
+        nodes.forEach(n => nodeDepths.set(n.id, 0));
+        return nodeDepths;
+    }
+
+    const queue = [{ id: startNode.id, depth: 0 }];
+    nodeDepths.set(startNode.id, 0);
+
+    while (queue.length > 0) {
+        const { id, depth } = queue.shift();
+        const neighbors = adjacency.get(id) || [];
+
+        neighbors.forEach(neighborId => {
+            if (!nodeDepths.has(neighborId)) {
+                nodeDepths.set(neighborId, depth + 1);
+                queue.push({ id: neighborId, depth: depth + 1 });
+            }
+        });
+    }
+
+    // Handle disconnected nodes
+    nodes.forEach(n => {
+        if (!nodeDepths.has(n.id)) nodeDepths.set(n.id, 999);
+    });
+
+    return nodeDepths;
+}
+
+export function filterGraphByDepth(data, maxDepth, searchedWord) {
+    const nodeDepths = computeNodeDepths(data.nodes, data.edges, searchedWord);
+    const filteredNodes = data.nodes.filter(n => nodeDepths.get(n.id) <= maxDepth);
+    const filteredNodeIds = new Set(filteredNodes.map(n => n.id));
+    const filteredEdges = data.edges.filter(e =>
+        filteredNodeIds.has(e.source) && filteredNodeIds.has(e.target)
+    );
+    return { nodes: filteredNodes, edges: filteredEdges };
+}
+
+export function filterCompoundEdges(data, includeCompound, searchedWord) {
+    if (includeCompound) {
+        return data;  // No filtering needed
+    }
+
+    // Filter out compound edges
+    const nonCompoundEdges = data.edges.filter(e => !e.compound);
+
+    // Find the start node (searched word, English)
+    const startNode = data.nodes.find(n =>
+        n.lexeme && n.lexeme.toLowerCase() === searchedWord.toLowerCase() && n.lang === 'en'
+    );
+
+    if (!startNode) {
+        // Fallback: return only non-compound connected components
+        const connectedNodeIds = new Set();
+        nonCompoundEdges.forEach(e => {
+            connectedNodeIds.add(e.source);
+            connectedNodeIds.add(e.target);
+        });
+        const filteredNodes = data.nodes.filter(n => connectedNodeIds.has(n.id));
+        return { nodes: filteredNodes, edges: nonCompoundEdges };
+    }
+
+    // BFS to find all nodes reachable from start via non-compound edges
+    const reachableNodeIds = new Set([startNode.id]);
+    const adjacency = new Map();
+    nonCompoundEdges.forEach(e => {
+        if (!adjacency.has(e.source)) adjacency.set(e.source, []);
+        adjacency.get(e.source).push(e.target);
+    });
+
+    const queue = [startNode.id];
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        const neighbors = adjacency.get(nodeId) || [];
+        neighbors.forEach(neighborId => {
+            if (!reachableNodeIds.has(neighborId)) {
+                reachableNodeIds.add(neighborId);
+                queue.push(neighborId);
+            }
+        });
+    }
+
+    // Keep only reachable nodes and edges between them
+    const filteredNodes = data.nodes.filter(n => reachableNodeIds.has(n.id));
+    const filteredEdges = nonCompoundEdges.filter(e =>
+        reachableNodeIds.has(e.source) && reachableNodeIds.has(e.target)
+    );
+
+    return { nodes: filteredNodes, edges: filteredEdges };
+}
+
+export function calculateMaxGraphDepth(nodes, edges, startWord) {
+    const nodeDepths = computeNodeDepths(nodes, edges, startWord);
+    let maxDepth = 0;
+    nodeDepths.forEach(depth => {
+        if (depth < 999 && depth > maxDepth) maxDepth = depth;
+    });
+    return maxDepth;
+}
+
+export function calculateGraphDepth(startWord) {
+    if (!cy || cy.nodes().length === 0) return 0;
+
+    const startNode = cy.nodes().filter(n => {
+        const word = n.data('word');
+        const lang = n.data('lang');
+        return word && word.toLowerCase() === startWord.toLowerCase() && lang === 'en';
+    }).first();
+
+    if (!startNode || startNode.length === 0) return 0;
+
+    const visited = new Set();
+    const queue = [{ node: startNode, depth: 0 }];
+    let maxDepth = 0;
+
+    while (queue.length > 0) {
+        const { node, depth } = queue.shift();
+        const nodeId = node.id();
+
+        if (visited.has(nodeId)) continue;
+        visited.add(nodeId);
+        maxDepth = Math.max(maxDepth, depth);
+
+        const outgoers = node.outgoers('node');
+        outgoers.forEach(neighbor => {
+            if (!visited.has(neighbor.id())) {
+                queue.push({ node: neighbor, depth: depth + 1 });
+            }
+        });
+    }
+
+    return maxDepth;
+}
+
+export function renderGraphElements(displayData, graphLegend, directionIndicator) {
+    const elements = [];
+    const seenLangs = new Map();  // lang code -> lang name
+    const langCounts = new Map(); // lang name -> count
+    const langCodes = new Map();  // lang name -> lang code (for display)
+
+    displayData.nodes.forEach((node) => {
+        const langName = node.lang_name || getLangName(node.lang);
+        const displayWord = node.lexeme || node.id;
+        seenLangs.set(node.lang, langName);
+        langCounts.set(langName, (langCounts.get(langName) || 0) + 1);
+        if (!langCodes.has(langName)) {
+            langCodes.set(langName, node.lang);
+        }
+
+        elements.push({
+            group: 'nodes',
+            data: {
+                id: node.id,
+                word: displayWord,
+                label: buildNodeLabel(node),
+                lang: node.lang,
+                langName: langName,
+                sense: node.sense || null,
+                hasSense: !!node.sense,
+                family: node.family || null,
+                branch: node.branch || null,
+            },
+        });
+    });
+
+    displayData.edges.forEach((edge) => {
+        if (edge.source === edge.target) return;
+        const edgeData = {
+            id: `${edge.source}-${edge.target}`,
+            source: edge.source,
+            target: edge.target,
+        };
+        if (edge.compound) {
+            edgeData.compound = true;
+        }
+        if (edge.type) {
+            edgeData.linkType = edge.type;
+        }
+        elements.push({
+            group: 'edges',
+            data: edgeData,
+        });
+    });
+
+    cy.elements().remove();
+    cy.add(elements);
+
+    const direction = getLayoutDirection();
+    cy.layout({
+        name: 'dagre',
+        rankDir: direction,
+        nodeSep: direction === 'LR' ? 40 : 30,
+        rankSep: direction === 'LR' ? 80 : 60,
+        padding: 30,
+        animate: false,
+    }).run();
+
+    cy.fit(undefined, 40);
+
+    // Apply link type colors if enabled
+    if (showLinkTypes) {
+        cy.edges().forEach(edge => {
+            const type = edge.data('linkType');
+            if (type) {
+                const color = getLinkTypeColor(type);
+                if (color) {
+                    edge.style('line-color', color);
+                    edge.style('target-arrow-color', color);
+                }
+            }
+        });
+    }
+
+    // Show the graph legend container
+    if (graphLegend) {
+        graphLegend.classList.remove('hidden');
+    }
+
+    // Update direction indicator arrow based on layout
+    if (directionIndicator) {
+        directionIndicator.classList.remove('vertical');
+        const arrow = directionIndicator.querySelector('.direction-arrow');
+        if (direction === 'TB') {
+            directionIndicator.classList.add('vertical');
+            if (arrow) arrow.textContent = '↓';
+        } else {
+            if (arrow) arrow.textContent = '→';
+        }
+    }
+
+    return { seenLangs, langCounts, langCodes };
+}

frontend/js/search.js

@@ -0,0 +1,93 @@
+/**
+ * Search and autocomplete functionality
+ */
+
+import { handleApiResponse, truncate, escapeHtml } from './utils.js';
+
+const FETCH_DEPTH = 10;
+
+export async function fetchEtymology(word) {
+    const response = await fetch(`/graph/${encodeURIComponent(word)}?depth=${FETCH_DEPTH}`);
+    await handleApiResponse(response, 'etymology lookup');
+    const data = await response.json();
+    return data;
+}
+
+export async function fetchRandomWord(includeCompound = true) {
+    const response = await fetch(`/random?include_compound=${includeCompound}`);
+    await handleApiResponse(response, 'random word');
+    const data = await response.json();
+    return data.word;
+}
+
+export async function fetchSuggestions(query, suggestionsEl, onSelect) {
+    if (query.length < 2) {
+        hideSuggestions(suggestionsEl);
+        return;
+    }
+
+    try {
+        const response = await fetch(`/search?q=${encodeURIComponent(query)}`);
+        if (response.status === 429) return;
+        if (!response.ok) return;
+        const data = await response.json();
+        showSuggestions(data.results, suggestionsEl, onSelect);
+    } catch (err) {
+        console.error('Search error:', err);
+    }
+}
+
+let selectedSuggestionIndex = -1;
+
+export function showSuggestions(results, suggestionsEl, onSelect) {
+    if (!suggestionsEl || results.length === 0) {
+        hideSuggestions(suggestionsEl);
+        return;
+    }
+
+    selectedSuggestionIndex = -1;
+    suggestionsEl.innerHTML = results
+        .map(
+            (r, i) => `
+            <div class="suggestion-item" data-index="${i}" data-word="${escapeHtml(r.word)}">
+                <span class="suggestion-word">${escapeHtml(r.word)}</span>
+                ${r.sense ? `<div class="suggestion-sense">${escapeHtml(truncate(r.sense, 60))}</div>` : ''}
+            </div>
+        `
+        )
+        .join('');
+
+    suggestionsEl.classList.remove('hidden');
+
+    suggestionsEl.querySelectorAll('.suggestion-item').forEach((item) => {
+        item.addEventListener('click', () => onSelect(item.dataset.word));
+    });
+}
+
+export function hideSuggestions(suggestionsEl) {
+    if (suggestionsEl) {
+        suggestionsEl.classList.add('hidden');
+        suggestionsEl.innerHTML = '';
+    }
+    selectedSuggestionIndex = -1;
+}
+
+export function navigateSuggestions(suggestionsEl, direction) {
+    const items = suggestionsEl.querySelectorAll('.suggestion-item');
+    if (items.length === 0) return;
+
+    items.forEach((item) => item.classList.remove('selected'));
+
+    selectedSuggestionIndex += direction;
+    if (selectedSuggestionIndex < 0) selectedSuggestionIndex = items.length - 1;
+    if (selectedSuggestionIndex >= items.length) selectedSuggestionIndex = 0;
+
+    items[selectedSuggestionIndex].classList.add('selected');
+    items[selectedSuggestionIndex].scrollIntoView({ block: 'nearest' });
+}
+
+export function getSelectedSuggestion(suggestionsEl) {
+    if (selectedSuggestionIndex < 0) return null;
+    const items = suggestionsEl.querySelectorAll('.suggestion-item');
+    return items[selectedSuggestionIndex]?.dataset.word || null;
+}

frontend/js/tree.js

@@ -0,0 +1,118 @@
+/**
+ * Tree View Module
+ * Renders etymology data as a text-based tree using Unicode box-drawing characters
+ */
+
+import { getLangName, escapeHtml } from './utils.js';
+
+/**
+ * Build a tree structure from nodes and edges
+ * @param {Object[]} nodes - Array of node objects
+ * @param {Object[]} edges - Array of edge objects (source → target means child → parent)
+ * @param {string} startWord - The searched word to start from
+ * @param {number} maxDepth - Maximum depth to traverse
+ * @returns {Object|null} Tree structure or null if start node not found
+ */
+export function buildTree(nodes, edges, startWord, maxDepth) {
+    if (!nodes || !edges || nodes.length === 0) return null;
+
+    // Create lookup maps
+    const nodeMap = new Map(nodes.map(n => [n.id, n]));
+
+    // Build child → parents adjacency (edges go child → parent)
+    const childToParents = new Map();
+    for (const edge of edges) {
+        if (!childToParents.has(edge.source)) {
+            childToParents.set(edge.source, []);
+        }
+        childToParents.get(edge.source).push(edge.target);
+    }
+
+    // Find the starting node (English version of searched word)
+    const startNodeId = `${startWord.toLowerCase()}|en`;
+    let startNode = nodeMap.get(startNodeId);
+
+    // Fallback: find any node with matching lexeme
+    if (!startNode) {
+        startNode = nodes.find(n =>
+            n.lexeme && n.lexeme.toLowerCase() === startWord.toLowerCase()
+        );
+    }
+
+    if (!startNode) return null;
+
+    // Recursive tree builder
+    function buildSubtree(nodeId, depth, visited) {
+        if (depth > maxDepth || visited.has(nodeId)) {
+            return null;
+        }
+
+        const node = nodeMap.get(nodeId);
+        if (!node) return null;
+
+        visited.add(nodeId);
+
+        const children = [];
+        const parentIds = childToParents.get(nodeId) || [];
+
+        for (const parentId of parentIds) {
+            const childTree = buildSubtree(parentId, depth + 1, new Set(visited));
+            if (childTree) {
+                children.push(childTree);
+            }
+        }
+
+        return {
+            id: nodeId,
+            lexeme: node.lexeme,
+            lang: node.lang,
+            langName: node.lang_name || getLangName(node.lang),
+            sense: node.sense,
+            family: node.family,
+            branch: node.branch,
+            children,
+        };
+    }
+
+    return buildSubtree(startNode.id, 0, new Set());
+}
+
+/**
+ * Render a tree structure as Unicode text
+ * @param {Object} tree - Tree structure from buildTree()
+ * @returns {string} HTML string of the rendered tree
+ */
+export function renderTreeHTML(tree) {
+    if (!tree) return '<div class="tree-empty">No tree data available</div>';
+
+    const lines = [];
+
+    function renderNode(node, prefix, isLast, isRoot) {
+        // Build the connector prefix
+        const connector = isRoot ? '' : (isLast ? '└── ' : '├── ');
+        const langDisplay = node.langName || node.lang;
+
+        // Create clickable node HTML
+        const nodeId = `tree-node-${node.id.replace(/[^a-zA-Z0-9]/g, '-')}`;
+        const senseAttr = node.sense ? ` data-sense="${escapeHtml(node.sense)}"` : '';
+        const familyAttr = node.family ? ` data-family="${escapeHtml(node.family)}"` : '';
+        const branchAttr = node.branch ? ` data-branch="${escapeHtml(node.branch)}"` : '';
+
+        const nodeHtml = `<span class="tree-node" id="${nodeId}" data-lexeme="${escapeHtml(node.lexeme)}" data-lang="${escapeHtml(node.lang)}" data-lang-name="${escapeHtml(langDisplay)}"${senseAttr}${familyAttr}${branchAttr}><span class="tree-word">${escapeHtml(node.lexeme)}</span> <span class="tree-lang">(${escapeHtml(langDisplay)})</span></span>`;
+
+        lines.push(`<div class="tree-line">${escapeHtml(prefix)}${connector}${nodeHtml}</div>`);
+
+        // Render children
+        const newPrefix = isRoot ? '' : (prefix + (isLast ? '    ' : '│   '));
+        node.children.forEach((child, i) => {
+            const childIsLast = i === node.children.length - 1;
+            renderNode(child, newPrefix, childIsLast, false);
+        });
+    }
+
+    renderNode(tree, '', true, true);
+
+    return `<div class="tree-content">${lines.join('')}</div>`;
+}
+
+

frontend/js/ui.js

@@ -0,0 +1,226 @@
+/**
+ * UI state management and controls
+ */
+
+import { getLangName, truncate, escapeHtml } from './utils.js';
+import { getCy } from './graph.js';
+
+// Show node detail panel
+export function showNodeDetail(data, elements) {
+    const { nodeDetail, detailWord, detailLang, detailFamily, detailSense } = elements;
+    if (!nodeDetail || !detailWord || !detailLang) return;
+
+    detailWord.textContent = data.word;
+    detailLang.textContent = data.langName || getLangName(data.lang);
+
+    if (detailFamily && detailFamily.parentElement) {
+        if (data.family) {
+            detailFamily.textContent = `${data.family}${data.branch ? ' → ' + data.branch : ''}`;
+            detailFamily.parentElement.classList.remove('hidden');
+        } else {
+            detailFamily.parentElement.classList.add('hidden');
+        }
+    }
+
+    if (detailSense && detailSense.parentElement) {
+        if (data.sense) {
+            detailSense.textContent = truncate(data.sense, 150);
+            detailSense.parentElement.classList.remove('hidden');
+        } else {
+            detailSense.parentElement.classList.add('hidden');
+        }
+    }
+
+    nodeDetail.classList.remove('hidden');
+}
+
+export function hideNodeDetail(nodeDetail) {
+    if (nodeDetail) nodeDetail.classList.add('hidden');
+}
+
+// State management
+export function showLoading(elements) {
+    const { loadingEl, emptyState, errorState, wordInfo, graphOptions, statsPanel, statsToggle, graphLegend, expandBtn, treeView } = elements;
+    const cy = getCy();
+
+    loadingEl.classList.remove('hidden');
+    emptyState.classList.add('hidden');
+    errorState.classList.add('hidden');
+    wordInfo.classList.add('hidden');
+    if (graphOptions) graphOptions.classList.add('hidden');
+    if (statsPanel) statsPanel.classList.add('hidden');
+    if (statsToggle) statsToggle.classList.remove('active');
+    if (graphLegend) graphLegend.classList.add('hidden');
+    if (expandBtn) expandBtn.classList.add('hidden');
+    if (treeView) treeView.innerHTML = '';
+    if (cy) cy.elements().remove();
+}
+
+export function showError(message, elements, minimizeGraph, options = {}) {
+    const { loadingEl, emptyState, errorState, errorMessage, wordInfo, graphLegend, expandBtn } = elements;
+    const errorActions = document.getElementById('error-actions');
+
+    loadingEl.classList.add('hidden');
+    emptyState.classList.add('hidden');
+    errorState.classList.remove('hidden');
+    errorMessage.textContent = message;
+    wordInfo.classList.add('hidden');
+    if (graphLegend) graphLegend.classList.add('hidden');
+    if (expandBtn) expandBtn.classList.add('hidden');
+    minimizeGraph();
+
+    // Build action buttons
+    if (errorActions) {
+        errorActions.innerHTML = '';
+
+        // Wiktionary link (for no-etymology case)
+        if (options.wiktionaryWord) {
+            const wiktLink = document.createElement('a');
+            wiktLink.href = `https://en.wiktionary.org/wiki/${encodeURIComponent(options.wiktionaryWord)}`;
+            wiktLink.target = '_blank';
+            wiktLink.rel = 'noopener';
+            wiktLink.className = 'error-action-btn';
+            wiktLink.textContent = 'Look up on Wiktionary';
+            errorActions.appendChild(wiktLink);
+        }
+
+        // Report issue button
+        if (options.searchedWord) {
+            const reportLink = document.createElement('a');
+            const title = encodeURIComponent(`Issue with word: ${options.searchedWord}`);
+            const body = encodeURIComponent(
+                `**Word:** ${options.searchedWord}\n**Error:** ${message}\n\n**Additional context:**\n(Please describe what you expected to see)`
+            );
+            reportLink.href = `https://github.com/lucharo/etymology-for-all/issues/new?title=${title}&body=${body}`;
+            reportLink.target = '_blank';
+            reportLink.rel = 'noopener';
+            reportLink.className = 'error-action-btn error-action-report';
+            reportLink.textContent = 'Report issue with this word';
+            errorActions.appendChild(reportLink);
+        }
+    }
+}
+
+export function showGraph(elements) {
+    const { loadingEl, emptyState, errorState, expandBtn } = elements;
+
+    loadingEl.classList.add('hidden');
+    emptyState.classList.add('hidden');
+    errorState.classList.add('hidden');
+    if (expandBtn) expandBtn.classList.remove('hidden');
+}
+
+// Stats
+export function updateStats(nodeCount, edgeCount, langCount, depth, elements) {
+    const { statNodes, statEdges, statLangs, statDepth } = elements;
+    if (statNodes) statNodes.textContent = nodeCount;
+    if (statEdges) statEdges.textContent = edgeCount;
+    if (statLangs) statLangs.textContent = langCount;
+    if (statDepth) statDepth.textContent = depth;
+}
+
+// Language breakdown
+export function updateInfoSummary(langCounts, langCodes, langBreakdown) {
+    if (!langBreakdown) return;
+
+    const sorted = Array.from(langCounts.entries()).sort((a, b) => {
+        if (b[1] !== a[1]) return b[1] - a[1];
+        return a[0].localeCompare(b[0]);
+    });
+
+    langBreakdown.innerHTML = sorted
+        .map(([langName, count]) => {
+            const code = langCodes.get(langName) || '';
+            // Show code in tooltip on hover, keep UI clean
+            return `
+            <span class="lang-chip" title="${escapeHtml(code)}">
+                <span class="lang-chip-name">${escapeHtml(langName)}</span>
+                <span class="lang-chip-count">${escapeHtml(String(count))}</span>
+            </span>
+        `;
+        })
+        .join('');
+}
+
+// Depth UI
+export function updateDepthUI(currentDepth, graphMaxDepth, elements) {
+    const { depthValue, depthMinus, depthPlus } = elements;
+    const MIN_DEPTH = 1;
+    if (depthValue) depthValue.textContent = currentDepth;
+    if (depthMinus) depthMinus.disabled = currentDepth <= MIN_DEPTH;
+    if (depthPlus) depthPlus.disabled = currentDepth >= graphMaxDepth;
+}
+
+// Expand/minimize
+export function createExpandHandlers(graphContainer, graphBackdrop) {
+    let isExpanded = false;
+
+    function toggleExpandGraph() {
+        isExpanded = !isExpanded;
+        graphContainer.classList.toggle('expanded', isExpanded);
+        if (graphBackdrop) graphBackdrop.classList.toggle('visible', isExpanded);
+
+        setTimeout(() => {
+            const cyInstance = getCy();
+            if (cyInstance) {
+                cyInstance.resize();
+                cyInstance.animate({
+                    fit: { eles: cyInstance.elements(), padding: 40 }
+                }, { duration: 200, easing: 'ease-out' });
+            }
+        }, 320);
+    }
+
+    function minimizeGraph() {
+        if (isExpanded) {
+            isExpanded = false;
+            graphContainer.classList.remove('expanded');
+            if (graphBackdrop) graphBackdrop.classList.remove('visible');
+
+            setTimeout(() => {
+                const cyInstance = getCy();
+                if (cyInstance) {
+                    cyInstance.resize();
+                    cyInstance.animate({
+                        fit: { eles: cyInstance.elements(), padding: 40 }
+                    }, { duration: 200, easing: 'ease-out' });
+                }
+            }, 320);
+        }
+    }
+
+    function getIsExpanded() {
+        return isExpanded;
+    }
+
+    return { toggleExpandGraph, minimizeGraph, getIsExpanded };
+}
+
+// Modal
+export function setupModal(aboutBtn, aboutModal, aboutClose, modalBackdrop, modalTabs) {
+    function openAboutModal() {
+        if (aboutModal) aboutModal.classList.remove('hidden');
+    }
+
+    function closeAboutModal() {
+        if (aboutModal) aboutModal.classList.add('hidden');
+    }
+
+    function switchTab(tabName) {
+        modalTabs?.forEach((tab) => {
+            tab.classList.toggle('active', tab.dataset.tab === tabName);
+        });
+        document.querySelectorAll('.tab-content').forEach((content) => {
+            content.classList.toggle('active', content.id === `tab-${tabName}`);
+        });
+    }
+
+    if (aboutBtn) aboutBtn.addEventListener('click', openAboutModal);
+    if (aboutClose) aboutClose.addEventListener('click', closeAboutModal);
+    if (modalBackdrop) modalBackdrop.addEventListener('click', closeAboutModal);
+    modalTabs?.forEach((tab) => {
+        tab.addEventListener('click', () => switchTab(tab.dataset.tab));
+    });
+
+    return { openAboutModal, closeAboutModal };
+}

frontend/js/utils.js

@@ -0,0 +1,59 @@
+/**
+ * Utility functions for Etymology Explorer
+ */
+
+export function getLangName(lang) {
+    // API provides lang_name from 2400+ code database
+    // This is only called as fallback when API doesn't return lang_name
+    if (!lang) return 'Unknown';
+    return lang;  // Return raw code if no name available
+}
+
+export function escapeHtml(str) {
+    if (!str) return '';
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+
+export function truncate(text, maxLength) {
+    if (!text || text.length <= maxLength) return text;
+    return text.slice(0, maxLength).trim() + '…';
+}
+
+export async function handleApiResponse(response, context = 'request') {
+    if (response.ok) return response;
+
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After') || '60';
+        throw new Error(`Too many requests. Please wait ${retryAfter} seconds and try again.`);
+    }
+    if (response.status === 404) {
+        throw new Error(`Word not found in the database`);
+    }
+    if (response.status >= 500) {
+        throw new Error(`Server is temporarily unavailable. Please try again in a moment.`);
+    }
+    throw new Error(`Failed to complete ${context}`);
+}
+
+/**
+ * Check if a graph API response indicates the word exists but has no etymology.
+ * Returns { noEtymology: true, lexeme } if so, null otherwise.
+ */
+export function checkNoEtymology(data) {
+    if (data && data.no_etymology === true) {
+        return { noEtymology: true, lexeme: data.lexeme || '' };
+    }
+    return null;
+}
+
+export function buildNodeLabel(node) {
+    const langName = node.lang_name || getLangName(node.lang);
+    const displayWord = node.lexeme || node.id;
+    // Keep nodes clean: just word + language name
+    return displayWord + '\n(' + langName.toLowerCase() + ')';
+}

frontend/styles.css

@@ -0,0 +1,1423 @@
+/* Reset and base styles */
+*, *::before, *::after {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+:root {
+    /* Color palette - soft, muted tones */
+    --bg: #fafaf9;
+    --text: #1c1917;
+    --text-muted: #78716c;
+    --border: #e7e5e4;
+    --accent: #0c4a6e;
+    --accent-light: #e0f2fe;
+    --error: #dc2626;
+
+    /* Language family colors - earthy, distinct */
+    --lang-modern: #0284c7;      /* Modern languages (en, fr, de, etc.) */
+    --lang-latin: #7c3aed;       /* Latin and Romance */
+    --lang-greek: #059669;       /* Greek */
+    --lang-germanic: #ea580c;    /* Proto-Germanic */
+    --lang-pie: #dc2626;         /* Proto-Indo-European */
+    --lang-semitic: #d97706;     /* Semitic languages */
+    --lang-other: #64748b;       /* Other/unknown */
+
+    /* Spacing */
+    --space-xs: 0.25rem;
+    --space-sm: 0.5rem;
+    --space-md: 1rem;
+    --space-lg: 2rem;
+    --space-xl: 4rem;
+
+    /* Typography */
+    --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    --font-serif: 'EB Garamond', Garamond, 'Times New Roman', serif;
+    --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace;
+}
+
+html {
+    font-size: 16px;
+}
+
+body {
+    font-family: var(--font-sans);
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.6;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+}
+
+main {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    padding: var(--space-sm) var(--space-lg) var(--space-lg);
+    max-width: 1200px;
+    margin: 0 auto;
+    width: 100%;
+}
+
+/* Header */
+header {
+    text-align: center;
+    margin-bottom: var(--space-lg);
+    position: relative;
+}
+
+h1 {
+    font-size: 2rem;
+    font-weight: 600;
+    letter-spacing: -0.02em;
+    color: var(--text);
+    margin-top: 0;
+}
+
+.subtitle {
+    color: var(--text-muted);
+    font-size: 1rem;
+    margin-top: var(--space-xs);
+}
+
+/* Search */
+.search-container {
+    display: flex;
+    gap: var(--space-sm);
+    max-width: 480px;
+    margin: 0 auto var(--space-xs);
+    width: 100%;
+}
+
+.search-hint {
+    text-align: center;
+    font-size: 0.8rem;
+    color: var(--text-muted);
+    margin-bottom: var(--space-xs);
+}
+
+/* Graph options */
+.graph-options {
+    display: flex;
+    justify-content: center;
+    gap: var(--space-md);
+    margin-bottom: var(--space-sm);
+    max-width: 480px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+.depth-control {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    font-size: 0.8rem;
+    color: var(--text-muted);
+}
+
+.depth-label {
+    font-weight: 500;
+    margin-right: var(--space-xs);
+}
+
+.depth-btn {
+    width: 28px;
+    height: 28px;
+    padding: 0;
+    font-size: 1rem;
+    font-weight: 500;
+    line-height: 1;
+    border-radius: 6px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.depth-btn:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+}
+
+.depth-value {
+    min-width: 1.5em;
+    text-align: center;
+    font-weight: 600;
+    font-size: 0.9rem;
+    color: var(--text);
+}
+
+/* Settings popover */
+.settings-wrapper {
+    position: relative;
+}
+
+.settings-popover {
+    position: absolute;
+    top: calc(100% + 6px);
+    right: 0;
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: var(--space-sm);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+    z-index: 20;
+    min-width: 200px;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+}
+
+.settings-option {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    font-size: 0.8rem;
+    color: var(--text-muted);
+    cursor: pointer;
+    padding: 4px 0;
+    white-space: nowrap;
+}
+
+.settings-option input[type="checkbox"] {
+    width: 14px;
+    height: 14px;
+    cursor: pointer;
+    accent-color: var(--accent);
+}
+
+.settings-option:hover {
+    color: var(--text);
+}
+
+.search-wrapper {
+    flex: 1;
+    position: relative;
+}
+
+#word-input {
+    width: 100%;
+    padding: var(--space-sm) var(--space-md);
+    font-size: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: white;
+    color: var(--text);
+    outline: none;
+    transition: border-color 0.2s, box-shadow 0.2s;
+}
+
+/* Autocomplete suggestions */
+.suggestions {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    background: white;
+    border: 1px solid var(--border);
+    border-top: none;
+    border-radius: 0 0 8px 8px;
+    max-height: 300px;
+    overflow-y: auto;
+    z-index: 100;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+.suggestion-item {
+    padding: var(--space-sm) var(--space-md);
+    cursor: pointer;
+    border-bottom: 1px solid var(--border);
+}
+
+.suggestion-item:last-child {
+    border-bottom: none;
+}
+
+.suggestion-item:hover,
+.suggestion-item.selected {
+    background: var(--accent-light);
+}
+
+.suggestion-word {
+    font-weight: 500;
+    color: var(--text);
+}
+
+.suggestion-sense {
+    font-size: 0.875rem;
+    color: var(--text-muted);
+    margin-top: 2px;
+}
+
+#word-input:focus {
+    border-color: var(--accent);
+    box-shadow: 0 0 0 3px var(--accent-light);
+}
+
+#word-input::placeholder {
+    color: var(--text-muted);
+}
+
+button {
+    padding: var(--space-sm) var(--space-md);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: white;
+    color: var(--text);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: background 0.2s, border-color 0.2s;
+}
+
+button:hover {
+    background: var(--bg);
+    border-color: var(--text-muted);
+}
+
+button:active {
+    transform: translateY(1px);
+}
+
+#search-btn {
+    background: var(--accent);
+    border-color: var(--accent);
+    color: white;
+}
+
+#search-btn:hover {
+    background: #0369a1;
+    border-color: #0369a1;
+}
+
+/* Graph container */
+#graph-container {
+    flex: 1;
+    min-height: 400px;
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    position: relative;
+    overflow: hidden;
+}
+
+/* Expanded graph state */
+#graph-container.expanded {
+    position: fixed;
+    top: var(--space-md);
+    left: var(--space-md);
+    right: var(--space-md);
+    bottom: var(--space-md);
+    z-index: 50;
+    min-height: auto;
+    box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
+    transition: all 0.3s ease;
+}
+
+/* Expand/minimize button */
+.expand-btn {
+    position: absolute;
+    top: var(--space-sm);
+    right: var(--space-sm);
+    z-index: 15;
+    padding: var(--space-xs);
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    cursor: pointer;
+    color: var(--text-muted);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all 0.2s;
+}
+
+.expand-btn:hover {
+    background: var(--bg);
+    color: var(--text);
+    border-color: var(--text-muted);
+}
+
+.expand-btn .minimize-icon {
+    display: none;
+}
+
+#graph-container.expanded .expand-btn .expand-icon {
+    display: none;
+}
+
+#graph-container.expanded .expand-btn .minimize-icon {
+    display: block;
+}
+
+/* Backdrop when expanded */
+.graph-backdrop {
+    position: fixed;
+    inset: 0;
+    background: rgba(250, 250, 249, 0.9);
+    z-index: 40;
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.3s ease;
+}
+
+.graph-backdrop.visible {
+    opacity: 1;
+    pointer-events: auto;
+}
+
+#cy {
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    top: 0;
+    left: 0;
+}
+
+/* Cytoscape HTML node labels */
+.cy-node-html-label {
+    pointer-events: none;
+}
+
+.cy-node-label {
+    text-align: center;
+    padding: 8px 12px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+}
+
+.node-lang {
+    font-family: system-ui, -apple-system, sans-serif;
+    font-size: 10px;
+    font-weight: 600;
+    color: #78716c;
+    text-transform: lowercase;
+    margin-bottom: 4px;
+}
+
+.node-word {
+    font-family: 'EB Garamond', Garamond, serif;
+    font-size: 18px;
+    font-weight: 600;
+    color: #1c1917;
+    line-height: 1.2;
+}
+
+.node-sense {
+    font-family: 'EB Garamond', Garamond, serif;
+    font-size: 11px;
+    font-style: italic;
+    color: #78716c;
+    margin-top: 4px;
+    line-height: 1.3;
+    max-width: 140px;
+}
+
+/* States */
+#empty-state,
+#error-state,
+#loading {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    text-align: center;
+    color: var(--text-muted);
+}
+
+#empty-state p,
+#error-state p {
+    font-size: 1rem;
+}
+
+#error-state {
+    color: #dc2626;
+}
+
+/* Error action buttons */
+.error-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-sm);
+    justify-content: center;
+    margin-top: var(--space-md);
+}
+
+.error-action-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-xs);
+    padding: var(--space-xs) var(--space-md);
+    font-size: 0.8rem;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    background: white;
+    color: var(--accent);
+    text-decoration: none;
+    cursor: pointer;
+    transition: background 0.2s, border-color 0.2s;
+}
+
+.error-action-btn:hover {
+    background: var(--accent-light);
+    border-color: var(--accent);
+}
+
+.error-action-report {
+    color: var(--text-muted);
+}
+
+.error-action-report:hover {
+    color: var(--text);
+}
+
+.hidden {
+    display: none !important;
+}
+
+/* Loading spinner */
+#loading {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--space-sm);
+}
+
+.spinner {
+    width: 32px;
+    height: 32px;
+    border: 3px solid var(--border);
+    border-top-color: var(--accent);
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+
+/* Word info bar */
+#word-info {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--space-sm) var(--space-md);
+    margin-top: var(--space-md);
+    padding: var(--space-sm) var(--space-md);
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+}
+
+#current-word {
+    font-family: var(--font-serif);
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--text);
+}
+
+.info-divider {
+    width: 1px;
+    height: 1.25rem;
+    background: var(--border);
+}
+
+#lang-breakdown {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-xs) var(--space-sm);
+    font-size: 0.8rem;
+    color: var(--text-muted);
+}
+
+.lang-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    padding: 2px 8px;
+    background: var(--bg);
+    border-radius: 12px;
+}
+
+.lang-chip-name {
+    color: var(--text);
+}
+
+.lang-chip-count {
+    color: var(--text-muted);
+    font-size: 0.75rem;
+}
+
+/* Stats toggle button */
+.stats-toggle {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    margin-left: auto;
+    padding: var(--space-xs) var(--space-sm);
+    font-size: 0.75rem;
+    background: transparent;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    color: var(--text-muted);
+    cursor: pointer;
+}
+
+.stats-toggle:hover {
+    background: var(--bg);
+    color: var(--text);
+}
+
+.stats-toggle.active {
+    background: var(--accent-light);
+    border-color: var(--accent);
+    color: var(--accent);
+}
+
+/* Stats panel (below word-info) */
+.stats-panel {
+    margin-top: var(--space-sm);
+    padding: var(--space-sm) var(--space-md);
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+}
+
+.stats-grid {
+    display: flex;
+    justify-content: center;
+    gap: var(--space-lg);
+}
+
+.stat-item {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 2px;
+}
+
+.stat-value {
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--text);
+    font-family: var(--font-mono);
+}
+
+.stat-label {
+    font-size: 0.7rem;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+
+/* Node detail panel */
+#node-detail {
+    position: absolute;
+    top: var(--space-md);
+    right: var(--space-md);
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: var(--space-md);
+    min-width: 220px;
+    max-width: 300px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+    z-index: 10;
+    font-family: var(--font-serif);
+}
+
+#detail-close {
+    position: absolute;
+    top: var(--space-xs);
+    right: var(--space-xs);
+    padding: var(--space-xs);
+    border: none;
+    background: transparent;
+    cursor: pointer;
+    color: var(--text-muted);
+    border-radius: 4px;
+}
+
+#detail-close:hover {
+    background: var(--bg);
+    color: var(--text);
+}
+
+.detail-header {
+    margin-bottom: var(--space-sm);
+    padding-right: var(--space-lg);
+}
+
+.detail-lang {
+    display: block;
+    font-size: 0.8rem;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-bottom: var(--space-xs);
+}
+
+.detail-word {
+    display: block;
+    font-size: 1.5rem;
+    font-weight: 600;
+    color: var(--text);
+    line-height: 1.2;
+}
+
+.detail-row {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding: var(--space-sm) 0;
+    border-top: 1px solid var(--border);
+}
+
+.detail-row .detail-label {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    font-family: var(--font-sans);
+    font-size: 0.7rem;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+.detail-value {
+    font-size: 1rem;
+    color: var(--text);
+}
+
+.detail-row:last-child .detail-value {
+    font-style: italic;
+}
+
+/* Info tooltip button */
+.info-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: var(--border);
+    color: var(--text-muted);
+    font-size: 0.6rem;
+    font-weight: 600;
+    font-family: var(--font-sans);
+    cursor: help;
+    border: none;
+    padding: 0;
+    position: relative;
+}
+
+.info-btn:hover {
+    background: var(--text-muted);
+    color: white;
+}
+
+.info-btn .tooltip {
+    display: none;
+    position: absolute;
+    bottom: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    background: var(--text);
+    color: white;
+    font-size: 0.75rem;
+    font-weight: 400;
+    text-transform: none;
+    letter-spacing: normal;
+    padding: var(--space-xs) var(--space-sm);
+    border-radius: 4px;
+    white-space: nowrap;
+    margin-bottom: 4px;
+    z-index: 20;
+}
+
+.info-btn:hover .tooltip {
+    display: block;
+}
+
+/* Graph legend */
+.graph-legend {
+    position: absolute;
+    bottom: var(--space-md);
+    left: var(--space-md);
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+    padding: var(--space-xs) var(--space-sm);
+    background: rgba(255, 255, 255, 0.9);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    font-size: 0.7rem;
+    color: var(--text-muted);
+    z-index: 5;
+    backdrop-filter: blur(4px);
+}
+
+/* Direction indicator within legend */
+#direction-indicator {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-xs);
+}
+
+#direction-indicator.vertical {
+    flex-direction: column;
+}
+
+.direction-label {
+    font-family: var(--font-sans);
+    letter-spacing: 0.02em;
+    color: var(--text-muted);
+}
+
+.direction-arrow {
+    color: var(--text-muted);
+    font-size: 1rem;
+    line-height: 1;
+}
+
+/* Legend divider */
+.legend-divider {
+    color: var(--border);
+    font-weight: 300;
+}
+
+/* Edge type legend */
+.edge-legend {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+}
+
+.legend-item {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+}
+
+.legend-line {
+    display: inline-block;
+    width: 20px;
+    height: 2px;
+    vertical-align: middle;
+}
+
+.legend-line.regular {
+    background: #d6d3d1;
+}
+
+.legend-line.compound {
+    background: var(--accent);
+}
+
+.legend-line.link-inh {
+    background: #059669;
+}
+
+.legend-line.link-bor {
+    background: #d97706;
+}
+
+.legend-line.link-der {
+    background: #7c3aed;
+}
+
+.legend-line.link-cog {
+    background: #0284c7;
+}
+
+.legend-line.link-cmpd {
+    background: #0c4a6e;
+}
+
+/* Header buttons */
+.header-buttons {
+    position: absolute;
+    top: 0.15em;
+    right: 0;
+    display: grid;
+    grid-template-columns: auto auto;
+    gap: var(--space-xs);
+    justify-items: end;
+}
+
+.header-buttons .settings-wrapper {
+    grid-column: 2;
+}
+
+.header-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-xs);
+    padding: var(--space-xs) var(--space-sm);
+    font-size: 0.875rem;
+    background: transparent;
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    color: var(--text-muted);
+    cursor: pointer;
+    text-decoration: none;
+}
+
+.header-btn:hover {
+    background: var(--bg);
+    color: var(--text);
+}
+
+/* Mobile menu (hidden on desktop by default) */
+.mobile-only {
+    display: none;
+}
+
+.mobile-menu-wrapper {
+    position: relative;
+}
+
+#mobile-menu-btn {
+    min-width: 44px;
+    min-height: 44px;
+}
+
+.mobile-menu {
+    position: absolute;
+    top: calc(100% + 6px);
+    right: 0;
+    background: white;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: var(--space-xs) 0;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+    z-index: 20;
+    min-width: 200px;
+}
+
+.mobile-menu-item {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+    width: 100%;
+    padding: var(--space-sm) var(--space-md);
+    font-size: 0.875rem;
+    color: var(--text);
+    background: none;
+    border: none;
+    border-radius: 0;
+    cursor: pointer;
+    text-decoration: none;
+    text-align: left;
+}
+
+.mobile-menu-item:hover {
+    background: var(--bg);
+}
+
+.mobile-about-link {
+    color: var(--accent);
+    font-weight: 500;
+    justify-content: flex-start;
+}
+
+.mobile-external-link {
+    justify-content: space-between;
+}
+
+.mobile-external-link .external-icon {
+    color: var(--text-muted);
+    font-size: 0.75rem;
+}
+
+.mobile-menu-divider {
+    height: 1px;
+    background: var(--border);
+    margin: var(--space-xs) 0;
+}
+
+/* Modal */
+.modal {
+    position: fixed;
+    inset: 0;
+    z-index: 100;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--space-md);
+}
+
+.modal-backdrop {
+    position: absolute;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.5);
+}
+
+.modal-content {
+    position: relative;
+    background: white;
+    border-radius: 12px;
+    max-width: 600px;
+    max-height: 80vh;
+    overflow-y: auto;
+    padding: var(--space-lg);
+    box-shadow: 0 20px 40px rgba(0, 0, 0, 0.2);
+}
+
+.modal-close {
+    position: absolute;
+    top: var(--space-sm);
+    right: var(--space-sm);
+    padding: var(--space-xs);
+    background: transparent;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    border-radius: 4px;
+}
+
+.modal-close:hover {
+    background: var(--bg);
+    color: var(--text);
+}
+
+.modal-tabs {
+    display: flex;
+    gap: var(--space-xs);
+    margin-bottom: var(--space-md);
+    border-bottom: 1px solid var(--border);
+    padding-bottom: var(--space-sm);
+}
+
+.modal-tab {
+    padding: var(--space-xs) var(--space-sm);
+    background: transparent;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    font-size: 0.875rem;
+    border-radius: 4px;
+}
+
+.modal-tab:hover {
+    background: var(--bg);
+}
+
+.modal-tab.active {
+    background: var(--accent-light);
+    color: var(--accent);
+    font-weight: 500;
+}
+
+.tab-content {
+    display: none;
+}
+
+.tab-content.active {
+    display: block;
+}
+
+.tab-content h2 {
+    font-family: var(--font-serif);
+    font-size: 1.5rem;
+    margin-bottom: var(--space-md);
+}
+
+.tab-content h3 {
+    font-size: 1rem;
+    margin-top: var(--space-md);
+    margin-bottom: var(--space-sm);
+    color: var(--text);
+}
+
+.tab-content p {
+    margin-bottom: var(--space-sm);
+    line-height: 1.7;
+    color: var(--text);
+}
+
+.tab-content .philosophy {
+    font-family: var(--font-serif);
+    font-size: 1.25rem;
+    font-style: italic;
+    margin-bottom: var(--space-md);
+}
+
+.tab-content .citation {
+    font-size: 0.875rem;
+    color: var(--text-muted);
+    font-style: italic;
+}
+
+.tab-content .example {
+    font-size: 0.875rem;
+    color: var(--text-muted);
+    background: var(--bg);
+    padding: var(--space-sm) var(--space-md);
+    border-radius: 6px;
+    border-left: 3px solid var(--accent);
+}
+
+.tab-content code {
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    background: var(--border);
+    padding: 1px 5px;
+    border-radius: 3px;
+    font-size: 0.85em;
+}
+
+.tab-content ol,
+.tab-content ul {
+    margin-bottom: var(--space-sm);
+    padding-left: var(--space-lg);
+    line-height: 1.8;
+}
+
+.tab-content li {
+    margin-bottom: var(--space-xs);
+}
+
+.tab-content a {
+    color: var(--accent);
+}
+
+/* View toggle buttons */
+.view-toggle {
+    display: flex;
+    align-items: center;
+    gap: 0;
+}
+
+.view-btn {
+    padding: 2px var(--space-xs);
+    font-size: 0.75rem;
+    background: transparent;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: color 0.15s ease;
+}
+
+.view-btn:hover {
+    color: var(--text);
+}
+
+.view-btn.active {
+    color: var(--text);
+    font-weight: 600;
+}
+
+.view-btn svg {
+    display: none;
+}
+
+.view-toggle .view-btn + .view-btn {
+    border-left: 1px solid var(--border);
+}
+
+/* Tree view container */
+.tree-view {
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    top: 0;
+    left: 0;
+    overflow: auto;
+    padding: var(--space-md);
+    background: white;
+}
+
+.tree-view.hidden {
+    display: none;
+}
+
+.tree-content {
+    font-family: var(--font-mono);
+    font-size: 0.875rem;
+    line-height: 1.6;
+    white-space: pre;
+}
+
+.tree-line {
+    display: block;
+}
+
+.tree-node {
+    cursor: pointer;
+    padding: 2px 4px;
+    border-radius: 4px;
+    transition: background 0.15s ease;
+}
+
+.tree-node:hover {
+    background: var(--accent-light);
+}
+
+.tree-word {
+    font-family: var(--font-serif);
+    font-weight: 600;
+    color: var(--text);
+}
+
+.tree-lang {
+    color: var(--text-muted);
+    font-family: var(--font-sans);
+    font-size: 0.8em;
+}
+
+.tree-empty {
+    text-align: center;
+    color: var(--text-muted);
+    padding: var(--space-xl);
+}
+
+/* Footer */
+footer {
+    text-align: center;
+    padding: var(--space-md);
+    color: var(--text-muted);
+    font-size: 0.875rem;
+}
+
+footer a {
+    color: var(--accent);
+    text-decoration: none;
+}
+
+footer a:hover {
+    text-decoration: underline;
+}
+
+/* Version details in footer */
+.version-details {
+    margin-top: var(--space-sm);
+    font-size: 0.75rem;
+    color: var(--text-muted);
+}
+
+.version-details summary {
+    cursor: pointer;
+    user-select: none;
+    display: inline;
+}
+
+.version-details summary:hover {
+    color: var(--text);
+}
+
+.version-content {
+    display: flex;
+    justify-content: center;
+    gap: var(--space-md);
+    margin-top: var(--space-xs);
+    font-size: 0.75rem;
+    color: var(--text-muted);
+}
+
+/* Responsive */
+@media (max-width: 640px) {
+    main {
+        padding: var(--space-sm);
+    }
+
+    header {
+        margin-bottom: var(--space-md);
+    }
+
+    h1 {
+        font-size: 1.5rem;
+        padding-right: 0;
+    }
+
+    .subtitle {
+        font-size: 0.875rem;
+    }
+
+    .desktop-only {
+        display: none !important;
+    }
+
+    .mobile-only {
+        display: block;
+    }
+
+    .header-buttons {
+        grid-template-columns: auto;
+    }
+
+    /* Keep search on one row with compact buttons */
+    .search-container {
+        gap: var(--space-xs);
+        margin-bottom: var(--space-xs);
+        flex-wrap: nowrap;
+    }
+
+    .search-hint {
+        font-size: 0.7rem;
+        margin-bottom: var(--space-xs);
+    }
+
+    .graph-options {
+        margin-bottom: var(--space-xs);
+        flex-wrap: wrap;
+    }
+
+    .view-toggle {
+        order: -1;
+        justify-content: center;
+        margin-bottom: var(--space-xs);
+    }
+
+    .depth-control {
+        font-size: 0.75rem;
+    }
+
+    .tree-content {
+        font-size: 0.75rem;
+    }
+
+    .depth-btn {
+        width: 32px;
+        height: 32px;
+    }
+
+    #word-input {
+        padding: var(--space-xs) var(--space-sm);
+        font-size: 16px; /* Prevent iOS auto-zoom on focus */
+    }
+
+    #search-btn,
+    #random-btn {
+        padding: var(--space-xs) var(--space-sm);
+        min-width: 44px;
+    }
+
+    #search-btn svg,
+    #random-btn svg {
+        width: 18px;
+        height: 18px;
+    }
+
+    /* Graph takes more space */
+    #graph-container {
+        min-height: 50vh;
+        flex: 1;
+    }
+
+    /* Legend vertical on mobile - top-left to avoid overlapping leaf nodes */
+    .graph-legend {
+        font-size: 0.6rem;
+        padding: 4px 6px;
+        top: var(--space-sm);
+        bottom: auto;
+        left: var(--space-sm);
+        gap: 2px;
+        flex-direction: column;
+        align-items: flex-start;
+    }
+
+    .edge-legend {
+        gap: 2px;
+        flex-direction: column;
+    }
+
+    .legend-divider {
+        display: none;
+    }
+
+    .legend-line {
+        width: 14px;
+    }
+
+    /* Direction indicator vertical on mobile */
+    #direction-indicator {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+
+    /* Detail panel full width at bottom on mobile */
+    #node-detail {
+        position: fixed;
+        top: auto;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        max-width: none;
+        min-width: auto;
+        border-radius: 12px 12px 0 0;
+        padding: var(--space-sm) var(--space-md);
+        box-shadow: 0 -4px 20px rgba(0, 0, 0, 0.15);
+        z-index: 55;
+    }
+
+    .detail-word {
+        font-size: 1.25rem;
+    }
+
+    .detail-row {
+        padding: var(--space-xs) 0;
+    }
+
+    /* Info bar more compact */
+    #word-info {
+        padding: var(--space-xs) var(--space-sm);
+        gap: var(--space-xs) var(--space-sm);
+        margin-top: var(--space-sm);
+    }
+
+    #current-word {
+        font-size: 1rem;
+    }
+
+    #lang-breakdown {
+        font-size: 0.7rem;
+    }
+
+    .lang-chip {
+        padding: 1px 6px;
+    }
+
+    /* Stats panel on mobile */
+    .stats-grid {
+        gap: var(--space-md);
+    }
+
+    .stat-value {
+        font-size: 1rem;
+    }
+
+    .stat-label {
+        font-size: 0.6rem;
+    }
+
+    .stats-toggle {
+        font-size: 0.7rem;
+        padding: 2px 6px;
+    }
+
+    /* Modal adjustments */
+    .modal-content {
+        padding: var(--space-md);
+        max-height: 90vh;
+    }
+
+    .tab-content h2 {
+        font-size: 1.25rem;
+    }
+
+    footer {
+        padding: var(--space-sm);
+        font-size: 0.75rem;
+    }
+
+    .mobile-menu-wrapper.mobile-only {
+        display: block;
+    }
+}

pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "etymology-for-all"
+version = "0.11.0"
+description = "Backend API for the Etymology Graph Explorer"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "aiohttp>=3.13.2",
+    "altair>=6.0.0",
+    "duckdb>=1.4.0",
+    "fastapi>=0.116.2",
+    "httpx>=0.28.1",
+    "polars>=1.36.1",
+    "pyarrow>=22.0.0",
+    "slowapi>=0.1.9",
+    "uvicorn>=0.35.0",
+]
+
+[dependency-groups]
+dev = [
+    "huggingface-hub>=1.2.3",
+    "locust>=2.42.6",
+    "marimo>=0.18.4",
+    "prek>=0.2.22",
+    "pytest>=8.4.2",
+    "ruff>=0.8.0",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.format]
+quote-style = "double"