Initial commit

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+*.bak
+.claude/
+.env

CLAUDE.md

@@ -0,0 +1,252 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Running the app
+
+```bash
+# Start the backend (from WikiNav/)
+uvicorn main:app --reload --port 8000
+
+# The frontend is a single static page split across index.html / styles.css /
+# app.js — open index.html directly in a browser, or serve it alongside the
+# backend (FastAPI does not serve static files here; open file:// or use a
+# simple HTTP server on the same port via a proxy).
+```
+
+No external services are required at runtime. The embedding model
+(`sentence-transformers`, `all-MiniLM-L6-v2`) is loaded once, in-process,
+at FastAPI startup — there is no LLM, no Ollama, and no other network
+dependency besides the Wikipedia API itself.
+
+## Architecture
+
+Backend is split into focused modules; frontend is markup + CSS + JS in
+separate files.
+
+### Backend modules
+
+- **`main.py`** — thin entrypoint only: the Windows stdout/stderr UTF-8
+  reconfigure (must run before any import that logs non-ASCII arrows) and
+  the uvicorn launch. Reads `$PORT` for PaaS hosts (Render etc.), falls
+  back to 8000 locally.
+- **`config.py`** — every tunable constant, env-overridable where it
+  matters (embedding model/device/batch size). Single source of truth —
+  nothing in search/embedding/wiki should hardcode a magic number that
+  belongs here.
+- **`server.py`** — the FastAPI `app`: CORS, the startup handler
+  (`embedding.load_model()`), `GET /api/random`, `GET /api/health`, and the
+  `/ws` WebSocket endpoint. One `AStarNavigator` instance per connection. A
+  parallel `listen_controls()` coroutine on the same socket handles
+  `{control: "pause"}` / `{control: "resume"}` messages while the search
+  coroutine runs.
+- **`search.py`** — `AStarNavigator` + `SearchStats`: the whole search
+  pipeline (scoring, pruning, the meeting check, the regression fence).
+- **`wiki.py`** — all Wikipedia API access: `resolve_article_title`,
+  `get_all_links`, `get_backlinks`, `get_article_summary`,
+  `check_disambiguation`, junk/date filters, seed-list loading for the
+  Random button.
+- **`embedding.py`** — the `sentence-transformers` model singleton,
+  `batch_embed`, `cosine_similarity`, and the per-session caches
+  (`_emb_cache`, `_dead_ends`, reset via `reset_session_caches()`).
+
+**WebSocket `/ws`**: the frontend sends `{start, end}` once; the backend
+streams JSON events (`status`, `resolved`, `node_add`, `expand_node`,
+`node_state`, `neighbours`, `found`, `not_found`) as the search progresses.
+
+### `AStarNavigator` (search.py) — honest bidirectional meeting-check search
+
+Despite the class name it runs **greedy best-first search, not A***. Core
+pipeline per expansion:
+1. **Goal-zone expansion** (every `GOAL_ZONE_EXPAND_INTERVAL=10` steps):
+   expand `GOAL_ZONE_EXPAND_BATCH=5` unexpanded d1 members by fetching
+   their backlinks, creating a depth-2 goal zone (`_goal_zone_d2`) with
+   bridge bookkeeping (`d2_node → d1_bridge` mapping).
+2. Fetch all links from the current article (`get_all_links`, up to
+   `MAX_FETCH=500`, redirect-resolved to canonical titles via
+   `generator=links&redirects=1`). The same call also returns each linked
+   page's Wikidata short description (`pageprops=wikibase-shortdesc`,
+   bundled into the same request — no extra round-trip).
+3. **Immediate-win check**: if the target is directly in the link set,
+   emit `found` right away.
+4. **D1 meeting check**: if any neighbour is a member of the target's
+   depth-1 backlink set (`_goal_zone_d1`), that neighbour is a verified
+   bridge — `current → bridge → target` is a fully real two-edge path.
+5. **D2 meeting check**: if any neighbour is in `_goal_zone_d2`, then
+   `current → d2_node → d1_bridge → target` is a verified three-edge
+   path (d2_node links to d1_bridge by construction, d1_bridge links to
+   target by construction). All three edges recorded via `_link()`.
+6. **Stagnation detection**: if the best h-value hasn't improved by
+   `STAGNATION_DELTA=0.02` over a `STAGNATION_WINDOW=8`-step sliding
+   window, the search is stagnant. When stagnant: beam widens from 15 to
+   `PRUNE_TOP_K_STAGNANT=25`, and a diversity bonus
+   (`DIVERSITY_WEIGHT=0.10 × distance from cluster centroid`) is added to
+   each candidate's score to escape dense off-topic clusters.
+7. Batch-embed uncached candidates in one in-process `sentence-transformers`
+   call (`batch_embed`, run off the event loop via a thread executor).
+   Candidates are embedded as `"{title}. {wikidata_short_desc}"`, not a
+   bare title — see "Semantic drift" below for why.
+8. Score each candidate (`_rank_candidates`):
+   `cosine(candidate, target) + frontier_bonus + diversity_bonus`.
+9. Prune to the top `PRUNE_TOP_K=15` (or 25 when stagnant), dropping
+   anything below the raw-cosine floor `PRUNE_FLOOR=0.15` (goal-zone d1
+   and d2 members exempt).
+10. Push survivors to the heap.
+
+**Heap priority = `h + DEPTH_TIEBREAK_EPSILON * g`** (config.py,
+`DEPTH_TIEBREAK_EPSILON = 0.01`). This is a deliberate reversal of an
+earlier "pure-h, no g-cost" design — see "Semantic drift" below. The
+penalty is small (max 0.6 at `MAX_HOPS=60`); it only breaks ties/near-ties,
+it doesn't override a genuinely strong `h` advantage.
+
+**Disambiguation detection**: before the search begins, the resolved
+target is checked for `pageprops.disambiguation`. If it's a disambiguation
+page (e.g. "A*" with only 3 backlinks), its outbound links are embedded
+and compared against the user's query (with a title-prefix affinity bonus)
+to auto-redirect to the most relevant real article (e.g. "A* search
+algorithm" with 112 backlinks). Uses `check_disambiguation()` in wiki.py.
+
+**Scoring formula** (`_rank_candidates`, no LLM involved anywhere):
+- `cosine(candidate_embedding, target_embedding)` — primary signal, raw
+  value stashed for the prune floor
+- `+0.30` if the candidate is in `_goal_zone_d1` (`FRONTIER_D1_BONUS`)
+- `+0.15` if the candidate is in `_goal_zone_d2` (`FRONTIER_D2_BONUS`)
+- `+DIVERSITY_WEIGHT × (1 - cosine(candidate, centroid))` when stagnant
+
+**Target goal zone** (the "bidirectional" part): at search init, the
+target's depth-1 backlinks are fetched and stored as `_goal_zone_d1`.
+Every `GOAL_ZONE_EXPAND_INTERVAL` steps, `_expand_goal_zone()` fetches
+backlinks of unexpanded d1 members, populating `_goal_zone_d2` (a dict
+mapping `d2_node → d1_bridge`). This creates a growing catchment area
+that makes the meeting check increasingly likely to fire, especially for
+targets with few initial backlinks.
+
+**Regression fence**: every `came_from` pointer is recorded through
+`_link()`, which also adds the edge to `self._real_edges`. `_emit_found()`
+calls `_validate_path()` before ever sending a `found` event, refusing to
+emit any path containing an edge that wasn't observed as a real Wikipedia
+link. This guards against ever again fabricating a path (see "History"
+below).
+
+**Session caches** (`_emb_cache`, `_dead_ends`) are module-level dicts in
+`embedding.py`, reset at the start of each search via
+`reset_session_caches()`. `search.py` accesses them as
+`_embedding_mod._emb_cache` / `_embedding_mod._dead_ends` (module-qualified,
+never imported by name) since `reset_session_caches()` rebinds both names
+to fresh objects every search — a `from embedding import _emb_cache` would
+capture the old object and go stale after the first reset.
+
+**REST endpoints**:
+- `GET /api/random` — random pair from `common_wiki_searches.txt`, used by
+  the "Random" button
+- `GET /api/health` — polled by the frontend's loading screen; a successful
+  response implies the embedding model finished loading at startup
+
+Autocomplete has no backend involvement — the frontend calls Wikipedia's
+`opensearch` API directly.
+
+### Frontend: `index.html` + `styles.css` + `app.js`
+
+`index.html` is markup only; all CSS lives in `styles.css`, all JS in
+`app.js` (single non-module `<script src>`, so handlers referenced by
+inline `onclick=` attributes must stay plain function declarations on
+`window`, not module exports).
+
+Key `app.js` globals:
+- `AC_DEBOUNCE_MS = 80` — autocomplete debounce
+- `triggerAutocomplete()` — calls Wikipedia's opensearch API directly (CORS-enabled, no backend round-trip)
+- `renderAcDropdown()` — builds the suggestion list; uses inline SVG icons (not emoji)
+- `connectWS()` — opens the WebSocket, sends `{start, end}`, dispatches incoming events to render functions
+- `playHeroEntrance()` — shared landing-page entrance sequence, called from both the initial load and `resetAll()`
+- About modal opened by `openAboutModal()` / closed by `closeAboutModal()`
+
+**Title entrance animation** (`#hero-title.entrance`, `styles.css`): a
+single CSS keyframe animation (`@keyframes title-entrance`) takes the title
+from its landing position, grows it to viewport center, holds, then
+returns it to the landing position as the rest of the hero fades in.
+Total duration and the hold length are both encoded in the keyframe
+percentages — to change the hold duration, adjust both the animation
+duration on `#hero-title.entrance` and the keyframe percentages together
+(they're coupled: a percentage is a fraction of the total duration).
+
+**Fonts**: Cinzel (Google Fonts, for "AURELIUS" title and topbar) + Outfit (body) + DM Mono (data/scores). All loaded via `<link>` in `<head>`.
+
+## Key constants (config.py)
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_HOPS` | 60 | Expansion-count cap |
+| `PRUNE_TOP_K` | 15 | Candidates kept per expansion after scoring |
+| `PRUNE_FLOOR` | 0.15 | Soft floor on raw cosine-to-target (top-5 + goal-zone members exempt) |
+| `PRUNE_MIN_SURVIVORS` | 5 | Always keep at least this many top-ranked candidates even below floor |
+| `FRONTIER_D1_BONUS` | 0.30 | Score bonus for depth-1 goal-zone membership |
+| `FRONTIER_D2_BONUS` | 0.15 | Score bonus for depth-2 goal-zone membership |
+| `DEPTH_TIEBREAK_EPSILON` | 0.01 | Heap priority = h + this × g (see "Semantic drift" below) |
+| `GOAL_ZONE_EXPAND_INTERVAL` | 10 | Expand goal zone every N steps |
+| `GOAL_ZONE_EXPAND_BATCH` | 5 | D1 members expanded per interval |
+| `GOAL_ZONE_D2_BACKLINK_LIMIT` | 100 | Max backlinks fetched per d1 member |
+| `STAGNATION_WINDOW` | 8 | Sliding window for h-improvement tracking |
+| `STAGNATION_DELTA` | 0.02 | Min improvement to count as progress |
+| `PRUNE_TOP_K_STAGNANT` | 25 | Widened beam when stagnant |
+| `DIVERSITY_WEIGHT` | 0.10 | Centroid-distance diversity bonus when stagnant |
+| `EMBED_BATCH_SIZE` | 64 | Titles per in-process `model.encode()` batch |
+| `MAX_FETCH` | 500 | Max links fetched per article |
+| `MAX_PAGES` | 6 | Safety cap on pagination pages when hunting a specific goal link |
+
+## Things to know
+
+- `_is_junk()` / `_JUNK_TITLES` (wiki.py) filter Wikipedia maintenance articles, citation-identifier stubs, disambiguation pages, date articles, and list articles before they enter the heap.
+- The embedding model (`all-MiniLM-L6-v2`, 384-dim) is loaded once at startup and reused for every embed call. There is no separate autocomplete model and no HNSW index.
+- `WIKI_HEADERS["User-Agent"]` must include contact info or Wikimedia's robot policy 403s the request — see config.py.
+- `mainpybackup.txt`, `htmlbackup.txt`, `main.py.bak`, `index.html.bak` are manual snapshots — not used by the app.
+
+## History: incidents worth knowing about
+
+- **Fabricated-path bug (fixed)**: an earlier stagnation-detection +
+  frontier-jump escape valve set `came_from` pointers with no real
+  Wikipedia link behind them (verified live: the jump target had no real
+  link from the node it claimed to jump from). Removed entirely and
+  replaced with the meeting-check architecture described above, plus the
+  permanent `_real_edges` / `_validate_path` regression fence.
+- **Semantic drift ("Anu → Iteration" investigation, fixed)**: a path
+  through several Egyptian/Mesopotamian deity pages looked fabricated —
+  `Anu`'s rendered page has no visible link reading "Iteration" — but
+  verified real against the live API: it's a piped wikilink
+  `[[Iteration|iterative]]` in a sentence about deity-name etymology,
+  invisible to a manual Ctrl+F but a genuine edge. The actual problem was
+  the search wandering through several pages with no real relevance to the
+  target before reaching it. Root cause: candidates were embedded as bare
+  titles, giving the model no domain signal for short/ambiguous proper
+  nouns. Fixed by (1) embedding `"{title}. {wikidata_short_desc}"` instead
+  of a bare title (the short description is fetched for free, bundled into
+  the existing `get_all_links` request via `pageprops=wikibase-shortdesc`),
+  and (2) adding `DEPTH_TIEBREAK_EPSILON` to heap priority so one noisy
+  candidate can't drag the search arbitrarily deep into an irrelevant
+  cluster with no incentive to prefer a shallower alternative. This is a
+  deliberate, intentional reversal of the original "heap priority = h only,
+  no g-cost" design — if you're tempted to "simplify" the heap key back to
+  pure `h`, don't; that's what caused the drift.
+- **"A\*" disambiguation failure (fixed, v3)**: searching for "A*" as a
+  target resolved to a Wikipedia disambiguation page with only 3 backlinks,
+  making it nearly unreachable (60 steps, NOT_FOUND). The real algorithm
+  article "A* search algorithm" has 112 backlinks. Fixed by adding
+  disambiguation detection (`check_disambiguation` in wiki.py) + automatic
+  redirect to the best semantic match among the disambig page's outbound
+  links (with a title-prefix affinity bonus for short queries). Also added
+  active backward expansion (depth-2 goal zone with bridge bookkeeping) and
+  stagnation-based cluster escape (beam widening + diversity bonus) to
+  prevent similar structural failures.
+- **Prune-floor total wipe-out (fixed, "Cleopatra → Time complexity"
+  incident)**: the search expanded Cleopatra once (step 1), pruned ALL
+  500 candidates below `PRUNE_FLOOR=0.15` (raw cosine of ancient-history
+  links against a CS target is ~0.05–0.12), the heap went empty, and the
+  search reported NOT_FOUND after 1 step. Root cause: `PRUNE_FLOOR` was a
+  hard kill switch with no safety net — if *every* candidate from an
+  expansion fell below the floor, zero survivors meant immediate death
+  regardless of `MAX_HOPS`. The same bug class existed for the earlier
+  0.22 threshold (documented in config.py), but at 0.15 it only surfaced
+  for maximally distant topic pairs. Fixed by adding
+  `PRUNE_MIN_SURVIVORS=5`: the top 5 candidates by combined score always
+  survive regardless of the floor, so the search can always make progress.
+  The floor still filters positions 6+ in the ranked list, keeping its
+  original role of trimming low-quality noise.

app.js

@@ -0,0 +1,1344 @@
+// ── State ────────────────────────────────────────────────────────────────────
+let ws = null;
+let nodes = {};
+let edges = [];
+let centreNode = null;
+let pathNodes = new Set();
+let simulation = null;
+let svgEl, gEl;
+let width, height;
+let running = false;
+let _searchGen = 0;
+let scoreCards = {};
+let heroDismissed = false;
+let paused = false;
+let foundPath = [];
+let _lastElapsedS = 0;
+
+// ── NEW: autocomplete state (vector search) ───────────────────────────────────
+let acDebounceTimers = { start: null, end: null };   // per-field debounce handles
+let acActiveIndex = { start: -1, end: -1 };    // keyboard-highlighted row
+let acLastResults = { start: [], end: [] };    // last suggestions per field
+const AC_DEBOUNCE_MS = 80;    // tight debounce — feel instant, but avoid a request on every single keypress
+
+// ── Rotating placeholder examples (hero inputs) ────────────────────────────────
+// Nagpur → Mars is first (shown on launch) and held for 2s; every other pair
+// uses the default 1.3s. Per-pair `duration` overrides DEFAULT_PLACEHOLDER_MS;
+// a setTimeout chain (not setInterval) is what makes a per-pair duration
+// possible — a single fixed-rate interval couldn't give one entry a different
+// dwell time than the rest.
+const PLACEHOLDER_PAIRS = [
+  { pair: ['Nagpur', 'Mars'], duration: 2000 },
+  { pair: ['Alexander the Great', 'Jazz music'] },
+  { pair: ['Pizza', 'Mount Everest'] },
+  { pair: ['Albert Einstein', 'Coffee'] },
+  { pair: ['Leonardo da Vinci', 'The Internet'] },
+  { pair: ['Cleopatra', 'Bitcoin'] },
+  { pair: ['Shakespeare', 'Video games'] },
+  { pair: ['Mahatma Gandhi', 'Formula 1'] },
+  { pair: ['Vincent van Gogh', 'Climate change'] },
+  { pair: ['Genghis Khan', 'Sushi'] },
+  { pair: ['The Moon', 'Chess'] },
+];
+const DEFAULT_PLACEHOLDER_MS = 1300;
+let _placeholderIdx = 0;
+let _placeholderTimer = null;
+
+function _applyPlaceholder() {
+  const startEl = document.getElementById('hero-inp-start');
+  const endEl = document.getElementById('hero-inp-end');
+  if (!startEl || !endEl) return;
+  const [s, e] = PLACEHOLDER_PAIRS[_placeholderIdx].pair;
+  startEl.placeholder = `e.g. ${s}`;
+  endEl.placeholder = `e.g. ${e}`;
+}
+
+function _scheduleNextPlaceholder() {
+  const duration = PLACEHOLDER_PAIRS[_placeholderIdx].duration || DEFAULT_PLACEHOLDER_MS;
+  _placeholderTimer = setTimeout(() => {
+    const startEl = document.getElementById('hero-inp-start');
+    const endEl = document.getElementById('hero-inp-end');
+    // Don't fight the user — only advance while both fields are empty, so
+    // cycling text never replaces something they've actually typed. Focus
+    // alone does NOT block rotation: boot() auto-focuses hero-inp-start on
+    // every load, so gating on activeElement here would freeze rotation at
+    // the first pair for any visitor who hasn't yet clicked away — there's
+    // no real cursor/typed content to interrupt in an empty, placeholder-only
+    // field regardless of focus.
+    const canAdvance = startEl && endEl && !startEl.value && !endEl.value;
+    if (canAdvance) {
+      _placeholderIdx = (_placeholderIdx + 1) % PLACEHOLDER_PAIRS.length;
+      _applyPlaceholder();
+    }
+    _scheduleNextPlaceholder();
+  }, duration);
+}
+
+function startPlaceholderRotation() {
+  if (_placeholderTimer) return;
+  _placeholderIdx = 0;   // Nagpur → Mars first, every time rotation (re)starts
+  _applyPlaceholder();
+  _scheduleNextPlaceholder();
+}
+
+function stopPlaceholderRotation() {
+  clearTimeout(_placeholderTimer);
+  _placeholderTimer = null;
+}
+
+// ── Hero input logic ──────────────────────────────────────────────────────────
+function heroInputChanged() {
+  const s = document.getElementById('hero-inp-start').value.trim();
+  const e = document.getElementById('hero-inp-end').value.trim();
+
+  // Labels light up when filled
+  document.getElementById('lbl-start').classList.toggle('filled', s.length > 0);
+  document.getElementById('lbl-end').classList.toggle('filled', e.length > 0);
+
+  // Inputs get filled style
+  document.getElementById('hero-inp-start').classList.toggle('filled', s.length > 0);
+  document.getElementById('hero-inp-end').classList.toggle('filled', e.length > 0);
+
+  // Arrow lights up when both filled
+  document.getElementById('hero-arrow').classList.toggle('lit', s.length > 0 && e.length > 0);
+
+  // Button and hint appear when both filled
+  const ready = s.length > 0 && e.length > 0;
+  document.getElementById('hero-btn').classList.toggle('ready', ready);
+  document.getElementById('hero-hint').classList.toggle('visible', ready);
+}
+// NOTE: autocomplete (vector search) is wired separately via addEventListener
+// in the NEW block below — heroInputChanged() above is the original,
+// untouched function and does not need to know about autocomplete at all.
+
+function heroKeyDown(e) {
+  // NEW: if an autocomplete dropdown is open for this field, arrow keys /
+  // Enter operate on the dropdown first. This is purely additive — if no
+  // dropdown is open, every branch below falls through to the exact
+  // original behaviour at the bottom of this function, untouched.
+  const fieldName = e.target.id === 'hero-inp-start' ? 'start' : 'end';
+  const dropdown = document.getElementById('ac-dropdown-' + fieldName);
+  const isOpen = dropdown && dropdown.classList.contains('visible');
+
+  if (isOpen && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+    e.preventDefault();
+    const items = acLastResults[fieldName];
+    if (items.length === 0) return;
+    const delta = e.key === 'ArrowDown' ? 1 : -1;
+    acActiveIndex[fieldName] = (acActiveIndex[fieldName] + delta + items.length) % items.length;
+    renderAcDropdown(fieldName);
+    return;
+  }
+  if (isOpen && e.key === 'Enter' && acActiveIndex[fieldName] >= 0) {
+    e.preventDefault();
+    selectAcSuggestion(fieldName, acLastResults[fieldName][acActiveIndex[fieldName]]);
+    return;
+  }
+  if (isOpen && e.key === 'Escape') {
+    closeAcDropdown(fieldName);
+    return;
+  }
+
+  // ── Original behaviour (unchanged) ──────────────────────────────────────
+  if (e.key === 'Enter') {
+    const s = document.getElementById('hero-inp-start').value.trim();
+    const en = document.getElementById('hero-inp-end').value.trim();
+    if (s && en) startSearch();
+    else if (!s) document.getElementById('hero-inp-start').focus();
+    else document.getElementById('hero-inp-end').focus();
+  }
+}
+
+// ── Wikipedia URL extractor ───────────────────────────────────────────────────
+function extractTitleFromWikiUrl(input) {
+  const match = input.match(/wikipedia\.org\/wiki\/([^#?]+)/);
+  if (match) return decodeURIComponent(match[1]).replace(/_/g, ' ');
+  return input;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// NEW: Vector-search autocomplete (hooks into the existing hero inputs via
+// addEventListener below — does not modify heroInputChanged/heroKeyDown's
+// original bodies, see the dedicated NOTE comments near those functions).
+// ════════════════════════════════════════════════════════════════════════════
+
+// Single source of truth for the backend origin. Derived from whatever host
+// the page itself was loaded from (not hardcoded to 'localhost') so this
+// works unmodified whether you open it as localhost, as a LAN IP from
+// another device on the same network (backend already binds 0.0.0.0 — see
+// main.py), or any other dev hostname — as long as the backend listens on
+// the same host, just port 8000. After deploying to separate frontend/
+// backend hosts (e.g. Render), replace this line with the fixed backend URL
+// (e.g. 'https://aurelius-backend.onrender.com') — the WebSocket URL below
+// is derived from it automatically (http→ws, https→wss), so nothing else in
+// this file needs to change.
+// window.location.hostname is '' when the page is opened as a local file
+// (file://index.html, which is how this app is normally launched per
+// CLAUDE.md) rather than served over http(s) — fall back to 'localhost' for
+// that case so AC_BACKEND never becomes the invalid 'http://:8000'.
+const AC_BACKEND = `http://${window.location.hostname || 'localhost'}:8000`;
+const AC_BACKEND_WS = AC_BACKEND.replace(/^http/, 'ws');
+const WIKI_OPENSEARCH = 'https://en.wikipedia.org/w/api.php';
+
+/**
+ * Debounced fetch directly to Wikipedia's opensearch API. Called on every
+ * keystroke in a hero input field, but the actual network request is
+ * delayed by AC_DEBOUNCE_MS so rapid typing doesn't spam the API. No
+ * backend involved — CORS-enabled, instant, and accurate for any article
+ * (not limited to a curated seed list).
+ */
+function triggerAutocomplete(fieldName) {
+  const inputId = fieldName === 'start' ? 'hero-inp-start' : 'hero-inp-end';
+  const query = document.getElementById(inputId).value.trim();
+
+  if (acDebounceTimers[fieldName]) clearTimeout(acDebounceTimers[fieldName]);
+
+  if (query.length < 2) {
+    closeAcDropdown(fieldName);
+    return;
+  }
+
+  acDebounceTimers[fieldName] = setTimeout(async () => {
+    try {
+      const params = new URLSearchParams({
+        action: 'opensearch', search: query, limit: '5',
+        namespace: '0', format: 'json', origin: '*',
+      });
+      const res = await fetch(`${WIKI_OPENSEARCH}?${params}`);
+      if (!res.ok) { closeAcDropdown(fieldName); return; }
+      const data = await res.json();
+      const suggestions = Array.isArray(data) && data.length > 1 ? data[1] : [];
+
+      // The user may have kept typing while this request was in flight —
+      // if the field no longer matches what we searched for, drop the
+      // (now-stale) result instead of flashing an outdated dropdown.
+      const currentValue = document.getElementById(inputId).value.trim();
+      if (currentValue !== query) return;
+
+      acLastResults[fieldName] = suggestions;
+      acActiveIndex[fieldName] = -1;
+      renderAcDropdown(fieldName);
+    } catch (err) {
+      // Network hiccup — fail silently, autocomplete is a nice-to-have
+      // and must never block the user from just typing a title and
+      // pressing Enter as before.
+      closeAcDropdown(fieldName);
+    }
+  }, AC_DEBOUNCE_MS);
+}
+
+/** Render the top-5 suggestions below the given hero field. */
+function renderAcDropdown(fieldName) {
+  const dropdown = document.getElementById('ac-dropdown-' + fieldName);
+  const items = acLastResults[fieldName];
+
+  if (!items || items.length === 0) {
+    closeAcDropdown(fieldName);
+    return;
+  }
+
+  dropdown.innerHTML = items.map((title, i) => `
+    <div class="ac-item${i === acActiveIndex[fieldName] ? ' ac-active' : ''}"
+         data-idx="${i}" data-title="${title.replace(/"/g, '&quot;')}">
+      <svg class="ac-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" width="14" height="14"><path d="M4 2h6l3 3v9H4V2z"/><path d="M10 2v3h3"/><line x1="6" y1="7" x2="11" y2="7"/><line x1="6" y1="10" x2="10" y2="10"/></svg>${title}
+    </div>
+  `).join('');
+  dropdown.classList.add('visible');
+  // BUGFIX: previously used inline onclick="selectAcSuggestion('${fieldName}', ${JSON.stringify(title)})"
+  // which broke because JSON.stringify's double-quotes collided with the outer HTML
+  // attribute's double-quotes, corrupting the attribute and silently failing on click.
+  // Event delegation with data-title avoids the quote-collision entirely.
+  dropdown.querySelectorAll('.ac-item').forEach(el => {
+    el.addEventListener('click', () => selectAcSuggestion(fieldName, el.dataset.title));
+  });
+}
+
+function closeAcDropdown(fieldName) {
+  const dropdown = document.getElementById('ac-dropdown-' + fieldName);
+  if (dropdown) {
+    dropdown.classList.remove('visible');
+    dropdown.innerHTML = '';
+  }
+  acLastResults[fieldName] = [];
+  acActiveIndex[fieldName] = -1;
+}
+
+/** Called when the user clicks (or presses Enter on) a suggestion row. */
+function selectAcSuggestion(fieldName, title) {
+  const inputId = fieldName === 'start' ? 'hero-inp-start' : 'hero-inp-end';
+  document.getElementById(inputId).value = title;
+  closeAcDropdown(fieldName);
+  // Re-run the existing, untouched hero validation logic (lights up the
+  // label/arrow/button exactly as if the user had typed this themselves).
+  heroInputChanged();
+}
+
+// Close dropdowns when clicking anywhere outside them (standard
+// autocomplete UX) — purely additive, does not interfere with any
+// existing click handlers elsewhere in the app.
+document.addEventListener('click', (e) => {
+  if (!e.target.closest('.hero-field')) {
+    closeAcDropdown('start');
+    closeAcDropdown('end');
+  }
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// NEW: Random button — picks two curated topics via /api/random, then
+// reuses the EXISTING startSearch() pipeline untouched (same WebSocket
+// flow, same A* navigator on the backend, same rendering code).
+// ════════════════════════════════════════════════════════════════════════════
+async function useRandomPair() {
+  // Per the requirements: only auto-fill if the user hasn't already typed
+  // a query themselves — we don't want to clobber a half-typed search.
+  const sVal = document.getElementById('hero-inp-start').value.trim();
+  const eVal = document.getElementById('hero-inp-end').value.trim();
+  if (sVal || eVal) {
+    // BUGFIX: setStatus() alone is invisible here — #status-bar lives inside
+    // #topbar, which has opacity:0 until the hero is dismissed. Surface the
+    // message on the button itself too, since that's always visible.
+    setStatus('Clear both fields first to use Random.');
+    btn_guard_msg(document.getElementById('hero-random-btn'), 'Clear fields first');
+    return;
+  }
+
+  const btn = document.getElementById('hero-random-btn');
+  btn.classList.add('loading');
+  btn.textContent = 'Picking...';
+
+  try {
+    const res = await fetch(`${AC_BACKEND}/api/random`);
+    if (!res.ok) throw new Error('Random pick failed');
+    const data = await res.json();
+
+    document.getElementById('hero-inp-start').value = data.start;
+    document.getElementById('hero-inp-end').value = data.end;
+    heroInputChanged();   // existing function — lights up labels/arrow/button
+
+    btn.classList.remove('loading');
+    btn.textContent = 'Random';
+
+    // Small delay so the user can actually see which two topics were
+    // picked before the hero screen animates away.
+    setTimeout(() => startSearch(), 600);
+  } catch (err) {
+    btn.classList.remove('loading');
+    setStatus('Could not reach backend for Random pick.');
+    // BUGFIX: status bar is invisible on hero screen — show error on button too.
+    btn_guard_msg(btn, '⚠️ Backend offline');
+  }
+}
+
+// Small helper for useRandomPair(): briefly shows an error message directly
+// on the button (always visible on hero screen), then restores its label.
+function btn_guard_msg(btn, msg) {
+  const original = 'Random';
+  btn.textContent = msg;
+  setTimeout(() => { btn.textContent = original; }, 1800);
+}
+
+// ── Dismiss hero, show app ────────────────────────────────────────────────────
+function dismissHero(start, end) {
+  if (heroDismissed) return;
+  heroDismissed = true;
+  stopPlaceholderRotation();
+
+  // Copy values to topbar inputs
+  document.getElementById('inp-start').value = start;
+  document.getElementById('inp-end').value = end;
+
+  // Animate hero out
+  const hero = document.getElementById('hero');
+  hero.classList.add('hiding');
+  setTimeout(() => hero.classList.add('hidden'), 500);
+
+  // Animate topbar in
+  document.getElementById('topbar').classList.add('visible');
+
+  // On phones/narrow tablets, default the search-controls topbar and the
+  // path/scores/log panel to collapsed the moment the main view opens, so
+  // what you see first is the live graph forming the path, not a wall of
+  // chrome. Both are reachable again via their handle bars. No-op on
+  // desktop/tablet — the CSS that makes .mobile-collapsed do anything only
+  // exists under the same max-width:820px breakpoint this check mirrors.
+  if (isMobileLayout()) {
+    document.getElementById('topbar').classList.add('mobile-collapsed');
+    document.getElementById('panel').classList.add('mobile-collapsed');
+    _syncMobileHandles();
+  }
+}
+
+// ── Mobile topbar/panel collapse ──────────────────────────────────────────────
+function isMobileLayout() {
+  return window.matchMedia('(max-width: 820px)').matches;
+}
+
+function toggleMobileTopbar() {
+  document.getElementById('topbar').classList.toggle('mobile-collapsed');
+  _syncMobileHandles();
+}
+
+function toggleMobilePanel() {
+  document.getElementById('panel').classList.toggle('mobile-collapsed');
+  _syncMobileHandles();
+}
+
+// Keeps each handle's chevron direction (and its own .is-collapsed state,
+// used purely for the CSS rotate transform) matching what it actually
+// controls, since the two can change independently of each other.
+function _syncMobileHandles() {
+  const topbarCollapsed = document.getElementById('topbar').classList.contains('mobile-collapsed');
+  const panelCollapsed = document.getElementById('panel').classList.contains('mobile-collapsed');
+  const th = document.getElementById('mobile-topbar-handle');
+  const ph = document.getElementById('mobile-panel-handle');
+  if (th) th.classList.toggle('is-collapsed', topbarCollapsed);
+  if (ph) ph.classList.toggle('is-collapsed', panelCollapsed);
+
+  // Collapsing/expanding either bar resizes #canvas-wrap via CSS transition,
+  // but that's an internal layout change, not a viewport resize — it never
+  // fires the `resize` listener that normally keeps the d3 force simulation
+  // centered. Re-measure once the 0.32s transition (styles.css) finishes, or
+  // the graph stays centered on the stale pre-toggle canvas size.
+  setTimeout(_resyncCanvasSize, 340);
+}
+
+function _resyncCanvasSize() {
+  if (!simulation) return;
+  const cw = document.getElementById('canvas-wrap');
+  if (!cw) return;
+  width = cw.clientWidth;
+  height = cw.clientHeight;
+  simulation.force('center', d3.forceCenter(width / 2, height / 2));
+  simulation.alpha(0.3).restart();
+}
+
+// ── Search ────────────────────────────────────────────────────────────────────
+function startSearch() {
+  // Pull from whichever screen is active
+  let rawStart, rawEnd;
+  if (!heroDismissed) {
+    rawStart = document.getElementById('hero-inp-start').value.trim();
+    rawEnd = document.getElementById('hero-inp-end').value.trim();
+  } else {
+    rawStart = document.getElementById('inp-start').value.trim();
+    rawEnd = document.getElementById('inp-end').value.trim();
+  }
+
+  if (!rawStart || !rawEnd) {
+    setStatus('Please enter both a start and end article.');
+    return;
+  }
+  if (running) return;
+
+  const start = extractTitleFromWikiUrl(rawStart);
+  const end = extractTitleFromWikiUrl(rawEnd);
+
+  dismissHero(rawStart, rawEnd);
+  resetAll(false);
+  running = true;
+  document.getElementById('btn-search').disabled = true;
+  switchTab('log');
+  document.getElementById('stats-bar').classList.add('visible');
+  document.getElementById('btn-pause-bar').classList.add('visible');
+  const stepsLive = document.getElementById('sv-steps-live');
+  if (stepsLive) { document.getElementById('sv-steps-count').textContent = '0'; stepsLive.classList.add('visible'); }
+  paused = false;
+  foundPath = [];
+
+  addLog(`Starting: "${start}" → "${end}"`, 'highlight');
+  setStatus('Connecting...');
+
+  const gen = ++_searchGen;
+  ws = new WebSocket(`${AC_BACKEND_WS}/ws`);
+
+  ws.onopen = () => {
+    if (gen !== _searchGen) return;
+    ws.send(JSON.stringify({ start, end }));
+    setStatus('Connected. Running A*...');
+  };
+
+  ws.onmessage = e => {
+    if (gen !== _searchGen) return;
+    try { handleMessage(JSON.parse(e.data)); }
+    catch (err) { console.error('Parse error:', err); }
+  };
+
+  ws.onerror = () => {
+    if (gen !== _searchGen) return;
+    // Only a connection error mid-search is a real problem. When the search
+    // finishes, the backend returns from the WS handler and closes the
+    // socket — mobile browsers (Safari/Chrome on iOS especially) surface
+    // that normal teardown as an `error` event, which would otherwise fire
+    // this scary "is the backend running?" message even though the path was
+    // found seconds earlier. `running` is false once found/not_found/error
+    // has been handled, so bail out — there's nothing wrong to report.
+    if (!running) return;
+    setStatus('⚠️  Cannot connect to backend. Is main.py running?');
+    addLog('WebSocket error — is the backend running? (python main.py)', 'error');
+    document.getElementById('btn-search').disabled = false;
+    running = false;
+  };
+
+  ws.onclose = () => {
+    if (gen !== _searchGen) return;
+    if (running) {
+      setStatus('Connection closed.');
+      running = false;
+      document.getElementById('btn-search').disabled = false;
+    }
+  };
+}
+
+function resetAll(showHero = true) {
+  if (ws) { ws.close(); ws = null; }
+  nodes = {}; edges = []; centreNode = null;
+  pathNodes = new Set(); scoreCards = {};
+  running = false;
+  // BUGFIX: "New Search" lives inside #success-modal itself and calls
+  // resetAll(true) directly — without this, the stale "Path Discovered"
+  // modal stays visible on top of the freshly-reset hero screen,
+  // permanently blocking it until the next search happens to find a path.
+  document.getElementById('success-modal').classList.remove('visible');
+  document.getElementById('btn-search').disabled = false;
+  document.getElementById('path-banner').classList.remove('visible');
+  document.getElementById('path-display').innerHTML = '<p style="font-size:13px;color:var(--text2)">Path will appear here as A* explores.</p>';
+  document.getElementById('scores-list').innerHTML = '';
+  document.getElementById('log').innerHTML = '';
+  setStatus('Enter two Wikipedia topics and hit Find Path.');
+  document.getElementById('stats-bar').classList.remove('visible');
+  _hidePauseBtn();
+  document.getElementById('btn-export').classList.remove('visible');
+  paused = false;
+  foundPath = [];
+
+  if (showHero) {
+    heroDismissed = false;
+    document.getElementById('topbar').classList.remove('visible');
+    document.getElementById('topbar').classList.remove('mobile-collapsed');
+    document.getElementById('panel').classList.remove('mobile-collapsed');
+    const hero = document.getElementById('hero');
+    hero.classList.remove('hiding', 'hidden');
+    document.getElementById('hero-inp-start').value = '';
+    document.getElementById('hero-inp-end').value = '';
+    heroInputChanged();
+    resetHeroDisplay();
+  }
+
+  initSVG();
+}
+
+// ── Init SVG ──────────────────────────────────────────────────────────────────
+function initSVG() {
+  svgEl = d3.select('#graph');
+  width = document.getElementById('canvas-wrap').clientWidth;
+  height = document.getElementById('canvas-wrap').clientHeight;
+
+  svgEl.selectAll('*').remove();
+
+  // Define glow filter
+  const defs = svgEl.append('defs');
+  const glow = defs.append('filter')
+    .attr('id', 'glow')
+    .attr('x', '-30%')
+    .attr('y', '-30%')
+    .attr('width', '160%')
+    .attr('height', '160%');
+  glow.append('feGaussianBlur')
+    .attr('stdDeviation', '6')
+    .attr('result', 'blur');
+  glow.append('feMerge')
+    .append('feMergeNode').attr('in', 'blur');
+  glow.select('feMerge')
+    .append('feMergeNode').attr('in', 'SourceGraphic');
+
+  const zoom = d3.zoom()
+    .scaleExtent([0.2, 4])
+    .on('zoom', e => gEl.attr('transform', e.transform));
+  svgEl.call(zoom);
+
+  gEl = svgEl.append('g').attr('id', 'main-g');
+  gEl.append('g').attr('id', 'edge-layer');
+  gEl.append('g').attr('id', 'node-layer');
+  gEl.append('g').attr('id', 'label-layer');
+
+  simulation = d3.forceSimulation()
+    .force('link', d3.forceLink().id(d => d.id).distance(120).strength(0.4))
+    // distanceMax caps how far the mutual-repulsion force reaches between any
+    // two nodes. Without it, a long-running search (up to 60 expansions, 25
+    // new nodes per step) keeps accumulating cumulative repulsion across the
+    // WHOLE graph — every node keeps pushing every other node apart forever,
+    // so the cluster's total footprint grows without bound as more nodes
+    // appear, even though the camera's own zoom level never changes. That
+    // unbounded sprawl is what reads as "the page automatically zooms out" —
+    // capping the repulsion's reach keeps the graph's footprint roughly
+    // stable once nodes are a few hundred px apart, instead of ballooning.
+    .force('charge', d3.forceManyBody().strength(-300).distanceMax(420))
+    .force('center', d3.forceCenter(width / 2, height / 2))
+    .force('collide', d3.forceCollide(44))
+    .alphaDecay(0.02)
+    .on('tick', ticked);
+}
+
+// ── D3 tick ───────────────────────────────────────────────────────────────────
+function ticked() {
+  d3.selectAll('.edge-line')
+    .attr('x1', d => (nodes[d.from] || {}).x || 0)
+    .attr('y1', d => (nodes[d.from] || {}).y || 0)
+    .attr('x2', d => (nodes[d.to] || {}).x || 0)
+    .attr('y2', d => (nodes[d.to] || {}).y || 0);
+
+  d3.selectAll('.node-circle')
+    .attr('cx', d => d.x)
+    .attr('cy', d => d.y);
+
+  d3.selectAll('.node-label-el')
+    .attr('x', d => d.x)
+    .attr('y', d => d.y + nodeRadius(d) + 15);
+}
+
+function nodeRadius(d) {
+  if (d.state === 'centre') return 22;
+  if (d.state === 'target') return 18;
+  if (pathNodes.has(d.id)) return 15;
+  return 12;
+}
+
+function nodeColor(d) {
+  const s = getComputedStyle(document.documentElement);
+  if (d.state === 'centre') return s.getPropertyValue('--node-centre').trim();
+  if (d.state === 'target') return s.getPropertyValue('--node-target').trim();
+  if (d.state === 'closed') return '#374151';
+  if (d.state === 'gated') return '#4b2020';
+  if (pathNodes.has(d.id)) return foundPath.length ? '#34d399' : s.getPropertyValue('--node-path').trim();
+  return s.getPropertyValue('--node-open').trim();
+}
+
+function edgeColor(d) {
+  if (d.isPath) return foundPath.length ? 'rgba(52,211,153,0.9)' : 'rgba(249,115,22,0.85)';
+  const fromNode = nodes[d.from];
+  if (fromNode && fromNode.state === 'closed') return 'rgba(124,106,247,0.18)';
+  return 'rgba(124,106,247,0.38)';
+}
+function edgeWidth(d) { return d.isPath ? 3 : 1.2; }
+
+// ── Render ────────────────────────────────────────────────────────────────────
+function render() {
+  const nodeArr = Object.values(nodes);
+
+  const edgeSel = d3.select('#edge-layer')
+    .selectAll('.edge-line')
+    .data(edges, d => d.from + '→' + d.to);
+
+  edgeSel.enter().append('line')
+    .attr('class', 'edge-line')
+    .attr('stroke-opacity', 0)
+    .attr('stroke-linecap', 'round')
+    .transition().duration(400)
+    .attr('stroke-opacity', 1);
+
+  edgeSel.exit().remove();
+
+  d3.selectAll('.edge-line')
+    .attr('stroke', edgeColor)
+    .attr('stroke-width', edgeWidth)
+    .attr('class', d => d.isPath && foundPath.length ? 'edge-line edge-path-found' : 'edge-line');
+
+  const circSel = d3.select('#node-layer')
+    .selectAll('.node-circle')
+    .data(nodeArr, d => d.id);
+
+  circSel.enter().append('circle')
+    .attr('class', 'node-circle')
+    .attr('r', 0)
+    .attr('fill', nodeColor)
+    .attr('stroke', '#0a0a0f')
+    .attr('stroke-width', 2.5)
+    .style('cursor', 'pointer')
+    .on('mouseover', onNodeHover)
+    .on('mouseout', onNodeOut)
+    .on('click', onNodeClick)
+    .call(d3.drag()
+      .on('start', dragStart)
+      .on('drag', dragged)
+      .on('end', dragEnd))
+    .transition().duration(350)
+    .attr('r', nodeRadius);
+
+  d3.selectAll('.node-circle')
+    .attr('class', 'node-circle')
+    .attr('fill', nodeColor)
+    .style('filter', d => {
+      if (d.state === 'centre' || d.state === 'target' || pathNodes.has(d.id)) {
+        return 'url(#glow)';
+      }
+      return 'none';
+    })
+    .transition().duration(200)
+    .attr('r', nodeRadius);
+
+  circSel.exit().transition().duration(200).attr('r', 0).remove();
+
+  const lblSel = d3.select('#label-layer')
+    .selectAll('.node-label-el')
+    .data(nodeArr, d => d.id);
+
+  lblSel.enter().append('text')
+    .attr('class', d => 'node-label-el ' + (d.state === 'centre' ? 'centre-label' : 'node-label'))
+    .attr('opacity', 0)
+    .transition().duration(400)
+    .attr('opacity', d => {
+      if (d.state === 'centre' || d.state === 'target') return 1;
+      if (pathNodes.has(d.id)) return 0.9;
+      return 0.45;
+    });
+
+  d3.selectAll('.node-label-el')
+    .text(d => truncate(d.id, d.state === 'centre' ? 24 : 18))
+    .attr('class', d => 'node-label-el ' + (d.state === 'centre' ? 'centre-label' : 'node-label'))
+    .attr('fill', d =>
+      d.state === 'centre' ? 'var(--text)' :
+        d.state === 'target' ? 'var(--green)' : 'var(--text2)')
+    .transition().duration(300)
+    .attr('opacity', d => {
+      if (d.state === 'centre' || d.state === 'target') return 1;
+      if (pathNodes.has(d.id)) return 0.9;
+      return 0.42;
+    });
+
+  lblSel.exit().remove();
+
+  simulation.nodes(nodeArr);
+  simulation.force('link').links(edges.map(e => ({
+    source: e.from, target: e.to, isPath: e.isPath
+  })));
+  simulation.alpha(0.3).restart();
+}
+
+// ── Pan to node ───────────────────────────────────────────────────────────────
+function panToNode(nodeId) {
+  const n = nodes[nodeId];
+  if (!n || !n.x) return;
+  const cw = document.getElementById('canvas-wrap').clientWidth;
+  const ch = document.getElementById('canvas-wrap').clientHeight;
+  const t = d3.zoomTransform(svgEl.node());
+  const tx = cw / 2 - t.k * n.x;
+  const ty = ch / 2 - t.k * n.y;
+  svgEl.transition().duration(600).ease(d3.easeCubicInOut)
+    .call(d3.zoom().transform, d3.zoomIdentity.translate(tx, ty).scale(t.k));
+}
+
+// ── Drag ──────────────────────────────────────────────────────────────────────
+function dragStart(e, d) { if (!e.active) simulation.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; }
+function dragged(e, d) { d.fx = e.x; d.fy = e.y; }
+function dragEnd(e, d) { if (!e.active) simulation.alphaTarget(0); d.fx = null; d.fy = null; }
+
+// ── Tooltip ───────────────────────────────────────────────────────────────────
+function onNodeHover(e, d) {
+  const tip = document.getElementById('tooltip');
+  document.getElementById('tt-title').textContent = d.id;
+  const scores = [];
+  if (d.g != null) scores.push(`g(n) = ${d.g}  hops from start`);
+  if (d.h != null) scores.push(`h(n) = ${d.h}  heuristic`);
+  if (d.f != null) scores.push(`f(n) = ${d.f}  total`);
+  document.getElementById('tt-scores').innerHTML = scores.join('<br>');
+  tip.style.left = (e.pageX + 14) + 'px';
+  tip.style.top = (e.pageY - 32) + 'px';
+  tip.classList.add('visible');
+}
+function onNodeOut() { document.getElementById('tooltip').classList.remove('visible'); }
+function onNodeClick(e, d) { panToNode(d.id); }
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function truncate(s, n) { return s.length > n ? s.slice(0, n - 1) + '…' : s; }
+function setStatus(msg) { document.getElementById('status-bar').textContent = msg; }
+
+function addLog(msg, type = '') {
+  const log = document.getElementById('log');
+  const entry = document.createElement('div');
+  entry.className = 'log-entry ' + type;
+  const time = new Date().toLocaleTimeString('en', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+  entry.textContent = `[${time}] ${msg}`;
+  log.insertBefore(entry, log.firstChild);
+}
+
+function switchTab(name) {
+  document.querySelectorAll('.tab').forEach((t, i) => {
+    const names = ['path', 'scores', 'log', 'legend'];
+    t.classList.toggle('active', names[i] === name);
+  });
+  document.querySelectorAll('.tab-content').forEach(c => {
+    c.classList.toggle('active', c.id === 'tab-' + name);
+  });
+}
+
+function updatePathPanel(pathArr) {
+  const div = document.getElementById('path-display');
+  if (!pathArr || pathArr.length === 0) return;
+  div.innerHTML = '';
+  pathArr.forEach((p, i) => {
+    const row = document.createElement('div');
+    row.className = 'path-step';
+    const dot = document.createElement('div');
+    dot.className = 'dot' + (i === 0 ? ' start' : i === pathArr.length - 1 ? ' end' : '');
+
+    const btn = document.createElement('a');
+    btn.className = 'hop-btn-link' + (i === 0 ? ' start-hop' : i === pathArr.length - 1 ? ' end-hop' : '');
+    btn.href = 'https://en.wikipedia.org/wiki/' + encodeURIComponent(p.replace(/ /g, '_'));
+    btn.target = '_blank';
+    btn.textContent = p;
+
+    row.appendChild(dot);
+    row.appendChild(btn);
+    div.appendChild(row);
+    if (i < pathArr.length - 1) {
+      const arr = document.createElement('div');
+      arr.className = 'path-step';
+      arr.style.margin = '2px 0 2px 4px';
+      arr.innerHTML = '<span class="arrow">↓</span>';
+      div.appendChild(arr);
+    }
+  });
+}
+
+function updateScores(nodeData) {
+  scoreCards[nodeData.id] = nodeData;
+  const list = document.getElementById('scores-list');
+  list.innerHTML = '';
+  const sorted = Object.values(scoreCards)
+    .filter(n => n.f != null)
+    .sort((a, b) => a.f - b.f)
+    .slice(0, 30);
+  sorted.forEach(n => {
+    const card = document.createElement('div');
+    card.className = 'score-card';
+    card.innerHTML = `
+      <div class="title">${n.id}</div>
+      <div class="score-row"><span>f(n)</span><span>${n.f}</span></div>
+      <div class="score-row"><span>g(n)</span><span>${n.g ?? '—'}</span></div>
+      <div class="score-row"><span>h(n)</span><span>${n.h ?? '—'}</span></div>
+    `;
+    list.appendChild(card);
+  });
+}
+
+function showPathBanner(pathArr) {
+  const banner = document.getElementById('path-banner');
+  banner.innerHTML = '';
+  banner.classList.add('visible');
+  const lbl = document.createElement('span');
+  lbl.style.cssText = 'font-size:13px;color:var(--text2);margin-right:12px;white-space:nowrap;font-weight:600';
+  lbl.textContent = `✓ Path (${pathArr.length - 1} hops):`;
+  banner.appendChild(lbl);
+  pathArr.forEach((p, i) => {
+    const btn = document.createElement('a');
+    btn.className = 'hop-btn-link' + (i === 0 ? ' start-hop' : i === pathArr.length - 1 ? ' end-hop' : '');
+    btn.style.flex = 'none';
+    btn.href = 'https://en.wikipedia.org/wiki/' + encodeURIComponent(p.replace(/ /g, '_'));
+    btn.target = '_blank';
+    btn.textContent = p;
+    banner.appendChild(btn);
+    if (i < pathArr.length - 1) {
+      const arr = document.createElement('span');
+      arr.className = 'banner-arrow';
+      arr.textContent = '→';
+      banner.appendChild(arr);
+    }
+  });
+}
+
+// ── WebSocket message handler ─────────────────────────────────────────────────
+function handleMessage(msg) {
+  switch (msg.event) {
+
+    case 'status':
+      setStatus(msg.message);
+      addLog(msg.message);
+      break;
+
+    case 'resolved':
+      addLog(`Resolved: "${msg.start}" → "${msg.end}"`, 'highlight');
+      setStatus(`Navigating: ${msg.start} → ${msg.end}`);
+      break;
+
+    case 'node_add': {
+      nodes[msg.id] = {
+        id: msg.id, g: msg.g, h: msg.h, f: msg.f,
+        state: msg.state,
+        x: width / 2 + (Math.random() - .5) * 120,
+        y: height / 2 + (Math.random() - .5) * 120,
+        vx: 0, vy: 0,
+      };
+      updateScores(msg);
+      render();
+      break;
+    }
+
+    case 'expand_node': {
+      if (centreNode && centreNode !== msg.id) {
+        if (nodes[centreNode]) nodes[centreNode].state = 'open';
+      }
+      centreNode = msg.id;
+      if (nodes[msg.id]) {
+        nodes[msg.id].state = 'centre';
+        nodes[msg.id].g = msg.g;
+        nodes[msg.id].h = msg.h;
+        nodes[msg.id].f = msg.f;
+      }
+
+      pathNodes = new Set(msg.path_so_far || []);
+      edges.forEach(e => {
+        const pArr = msg.path_so_far || [];
+        e.isPath = false;
+        for (let i = 0; i < pArr.length - 1; i++) {
+          if ((e.from === pArr[i] && e.to === pArr[i + 1]) ||
+            (e.to === pArr[i] && e.from === pArr[i + 1])) {
+            e.isPath = true;
+          }
+        }
+      });
+
+      updatePathPanel(msg.path_so_far);
+      updateScores(msg);
+      addLog(`Expanding: ${msg.id}  f=${msg.f}`, 'highlight');
+      if (msg.stats) _updateStats(msg.stats);
+      render();
+      setTimeout(() => panToNode(msg.id), 200);
+      break;
+    }
+
+    case 'node_state': {
+      if (nodes[msg.id]) nodes[msg.id].state = msg.state;
+      render();
+      break;
+    }
+
+    case 'neighbours': {
+      msg.nodes.forEach(n => {
+        if (!nodes[n.id]) {
+          const cn = nodes[msg.centre] || { x: width / 2, y: height / 2 };
+          const angle = Math.random() * 2 * Math.PI;
+          const dist = 90 + Math.random() * 70;
+          nodes[n.id] = {
+            id: n.id, g: n.g, h: n.h, f: n.f,
+            state: n.state,
+            x: cn.x + Math.cos(angle) * dist,
+            y: cn.y + Math.sin(angle) * dist,
+            vx: 0, vy: 0,
+          };
+        } else {
+          nodes[n.id].g = n.g;
+          nodes[n.id].h = n.h;
+          nodes[n.id].f = n.f;
+          if (nodes[n.id].state !== 'target' && nodes[n.id].state !== 'centre') {
+            nodes[n.id].state = n.state;
+          }
+        }
+        updateScores(n);
+      });
+
+      msg.edges.forEach(e => {
+        const exists = edges.find(ex => ex.from === e.from && ex.to === e.to);
+        if (!exists) edges.push({ from: e.from, to: e.to, isPath: false });
+      });
+
+      render();
+      break;
+    }
+
+    case 'found': {
+      const path = msg.path;
+      pathNodes = new Set(path);
+
+      // Synthesize missing nodes: the meeting check (d1/d2) skips the
+      // neighbours event, so bridge nodes may not exist in the frontend.
+      path.forEach((id, i) => {
+        if (!nodes[id]) {
+          const prev = i > 0 ? nodes[path[i - 1]] : null;
+          nodes[id] = {
+            id, g: i, h: 0, f: i,
+            state: 'path',
+            x: (prev ? prev.x : width / 2) + (Math.random() - .5) * 100,
+            y: (prev ? prev.y : height / 2) + (Math.random() - .5) * 100,
+            vx: 0, vy: 0,
+          };
+        }
+      });
+
+      path.forEach(id => { if (nodes[id]) nodes[id].state = 'path'; });
+      if (nodes[path[0]]) nodes[path[0]].state = 'start';
+      if (nodes[path[path.length - 1]]) nodes[path[path.length - 1]].state = 'target';
+      edges.forEach(e => {
+        e.isPath = false;
+        for (let i = 0; i < path.length - 1; i++) {
+          if ((e.from === path[i] && e.to === path[i + 1]) ||
+            (e.to === path[i] && e.from === path[i + 1])) {
+            e.isPath = true;
+          }
+        }
+      });
+      for (let i = 0; i < path.length - 1; i++) {
+        const a = path[i], b = path[i + 1];
+        const exists = edges.find(e =>
+          (e.from === a && e.to === b) || (e.from === b && e.to === a));
+        if (exists) {
+          exists.isPath = true;
+        } else {
+          edges.push({ from: a, to: b, isPath: true });
+        }
+      }
+      updatePathPanel(path);
+      showPathBanner(path);
+      addLog(`✓ Found! ${path.join(' → ')}  (${msg.total_hops} hops, ${msg.steps} steps)`, 'success');
+      setStatus(`Done! Path found in ${msg.total_hops} hops.`);
+      render();
+      document.getElementById('btn-search').disabled = false;
+      running = false;
+      foundPath = path;
+      _hidePauseBtn();
+      document.getElementById('btn-export').classList.add('visible');
+      if (msg.stats) _updateStats(msg.stats);
+      animatePath(path, msg.steps, msg.total_hops, msg.display_texts);
+      break;
+    }
+
+    case 'not_found': {
+      addLog(`✗ ${msg.message}`, 'error');
+      setStatus(msg.message);
+      document.getElementById('btn-search').disabled = false;
+      running = false;
+      _hidePauseBtn();
+      if (msg.stats) _updateStats(msg.stats);
+      break;
+    }
+
+    case 'stats': {
+      _updateStats(msg);
+      break;
+    }
+
+
+    case 'error': {
+      addLog(`Error: ${msg.message}`, 'error');
+      setStatus(`Error: ${msg.message}`);
+      document.getElementById('btn-search').disabled = false;
+      running = false;
+      _hidePauseBtn();
+      break;
+    }
+  }
+}
+
+
+// ── Stats update ─────────────────────────────────────────────────────────────
+function _updateStats(s) {
+  if (!s) return;
+  _lastElapsedS = s.elapsed_s ?? 0;
+  const cnt = document.getElementById('sv-steps-count');
+  if (cnt) cnt.textContent = (s.nodes_visited ?? 0).toLocaleString();
+}
+
+// ── Pause / Resume ────────────────────────────────────────────────────────────
+function togglePause() {
+  paused = !paused;
+  const btn = document.getElementById('btn-pause-bar');
+  if (paused) {
+    btn.textContent = '▶ Resume';
+    btn.classList.add('paused');
+    if (ws && ws.readyState === 1) ws.send(JSON.stringify({ control: 'pause' }));
+  } else {
+    btn.textContent = '⏸ Pause';
+    btn.classList.remove('paused');
+    if (ws && ws.readyState === 1) ws.send(JSON.stringify({ control: 'resume' }));
+  }
+}
+
+function _hidePauseBtn() {
+  paused = false;
+  const btn = document.getElementById('btn-pause-bar');
+  btn.classList.remove('visible', 'paused');
+  btn.textContent = '⏸ Pause';
+  const sl = document.getElementById('sv-steps-live');
+  if (sl) sl.classList.remove('visible');
+}
+
+// ── Export path ───────────────────────────────────────────────────────────────
+function exportPath() {
+  if (!foundPath.length) return;
+  const lines = [
+    'Aurelius — Path Export',
+    '='.repeat(50),
+    '',
+    `Path (${foundPath.length - 1} hops):`,
+    '',
+    ...foundPath.map((p, i) => {
+      const url = 'https://en.wikipedia.org/wiki/' + encodeURIComponent(p.replace(/ /g, '_'));
+      return `${i + 1}. ${p}\n   ${url}`;
+    }),
+    '',
+    `Exported: ${new Date().toLocaleString()}`,
+  ];
+  const blob = new Blob([lines.join('\n')], { type: 'text/plain' });
+  const a = document.createElement('a');
+  a.href = URL.createObjectURL(blob);
+  a.download = 'aurelius-path.txt';
+  a.click();
+}
+
+// ── Keyboard shortcuts ────────────────────────────────────────────────────────
+document.addEventListener('keydown', e => {
+  if (e.target.tagName === 'INPUT') return;
+  if (e.code === 'Space') { e.preventDefault(); if (running) togglePause(); }
+  if (e.code === 'KeyR') { resetAll(); }
+  if (e.code === 'KeyE') { exportPath(); }
+  if (e.key === '?') { openAboutModal(); }
+});
+
+function swapInputs() {
+  const s = document.getElementById('inp-start');
+  const en = document.getElementById('inp-end');
+  if (!s || !en) return;
+  [s.value, en.value] = [en.value, s.value];
+}
+
+function logoClick() {
+  resetAll(true);
+}
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+window.addEventListener('load', () => {
+  initSVG();
+  // Focus first hero input
+  document.getElementById('hero-inp-start').focus();
+
+  window.addEventListener('resize', () => {
+    width = document.getElementById('canvas-wrap').clientWidth;
+    height = document.getElementById('canvas-wrap').clientHeight;
+    if (simulation) simulation.force('center', d3.forceCenter(width / 2, height / 2));
+  });
+
+  // NEW: wire vector-search autocomplete onto the two hero inputs. This is
+  // a separate addEventListener (not the existing oninput="heroInputChanged()"
+  // attribute already on these elements) so both the original validation
+  // logic and the new autocomplete logic run independently, side by side,
+  // every time the user types — neither one touches or depends on the other.
+  document.getElementById('hero-inp-start')
+    .addEventListener('input', () => triggerAutocomplete('start'));
+  document.getElementById('hero-inp-end')
+    .addEventListener('input', () => triggerAutocomplete('end'));
+});
+
+function animatePath(path, steps, hops, displayTexts) {
+  const delay = 160;
+  path.forEach((nodeId, i) => {
+    setTimeout(() => {
+      d3.selectAll('.node-circle')
+        .filter(d => d.id === nodeId)
+        .transition().duration(120)
+        .attr('r', d => nodeRadius(d) * 1.7)
+        .attr('fill', '#34d399')
+        .transition().duration(260)
+        .attr('r', d => nodeRadius(d))
+        .attr('fill', nodeColor);
+    }, i * delay);
+  });
+  setTimeout(() => openSuccessModal(path, steps, hops, displayTexts), path.length * delay + 480);
+}
+
+function openSuccessModal(path, steps, hops, displayTexts) {
+  document.getElementById('modal-hops').textContent = hops;
+  document.getElementById('modal-steps').textContent = steps;
+  const elapsed = _lastElapsedS;
+  document.getElementById('modal-elapsed').textContent = elapsed >= 60
+    ? Math.floor(elapsed / 60) + 'm ' + (elapsed % 60) + 's'
+    : elapsed + 's';
+
+  const container = document.getElementById('modal-path-container');
+  container.innerHTML = '';
+  path.forEach((p, i) => {
+    const btn = document.createElement('a');
+    btn.className = 'hop-btn' + (i === 0 ? ' start-hop' : i === path.length - 1 ? ' end-hop' : '');
+    btn.href = 'https://en.wikipedia.org/wiki/' + encodeURIComponent(p.replace(/ /g, '_'));
+    btn.target = '_blank';
+    btn.innerHTML = `
+      <span>${p}</span>
+      <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" style="margin-left:4px;opacity:0.7">
+        <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path>
+        <polyline points="15 3 21 3 21 9"></polyline>
+        <line x1="10" y1="14" x2="21" y2="3"></line>
+      </svg>`;
+    container.appendChild(btn);
+    if (i < path.length - 1) {
+      const arr = document.createElement('span');
+      arr.className = 'modal-arrow';
+      arr.textContent = '→';
+      const piped = displayTexts && displayTexts[i];
+      if (piped) {
+        arr.classList.add('piped-edge');
+        arr.title = `Shown as "${piped}" in the article text`;
+        const note = document.createElement('span');
+        note.className = 'modal-piped-note';
+        note.textContent = `"${piped}"`;
+        arr.appendChild(note);
+      }
+      container.appendChild(arr);
+    }
+  });
+
+  document.getElementById('modal-copy-btn').textContent = 'Copy Path';
+  document.getElementById('success-modal').classList.add('visible');
+}
+
+function closeSuccessModal(e) {
+  if (!e || e.target === document.getElementById('success-modal') || e.target.tagName === 'BUTTON') {
+    document.getElementById('success-modal').classList.remove('visible');
+  }
+}
+
+function copyPath() {
+  if (!foundPath.length) return;
+  const text = foundPath.join(' → ');
+  const btn = document.getElementById('modal-copy-btn');
+  navigator.clipboard.writeText(text).then(() => {
+    if (btn) { btn.textContent = 'Copied!'; setTimeout(() => { btn.textContent = 'Copy Path'; }, 1600); }
+  }).catch(() => {
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed'; ta.style.opacity = '0';
+    document.body.appendChild(ta);
+    ta.select();
+    document.execCommand('copy');
+    document.body.removeChild(ta);
+    if (btn) { btn.textContent = 'Copied!'; setTimeout(() => { btn.textContent = 'Copy Path'; }, 1600); }
+  });
+}
+
+function openAboutModal() {
+  document.getElementById('about-modal').classList.add('visible');
+}
+
+function closeAboutModal(e) {
+  if (!e || e.target === document.getElementById('about-modal') || e.target.tagName === 'BUTTON') {
+    document.getElementById('about-modal').classList.remove('visible');
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Loading screen + landing entrance sequence.
+// Polls /api/health until the backend's embedding model is ready (the
+// server doesn't accept connections until startup finishes loading it, so
+// a single successful response already means "ready" — no extra check
+// needed). Once ready: fade out the loading screen and trigger the title's
+// 3-stage entrance animation — landing position -> grow to viewport center
+// -> hold -> return to landing position. The rest of the hero
+// (.hero-reveal elements) and the hero background (#hero-bg-mask) fade in
+// together exactly when that animation finishes, driven by the
+// animationend event rather than a magic setTimeout that would drift out
+// of sync if the CSS timing is ever tuned.
+// ════════════════════════════════════════════════════════════════════════════
+const HEALTH_POLL_MS = 350;
+
+async function initLoadingSequence() {
+  const loadingScreen = document.getElementById('loading-screen');
+
+  while (true) {
+    try {
+      const res = await fetch(`${AC_BACKEND}/api/health`);
+      if (res.ok) break;
+    } catch (err) {
+      // Backend not reachable yet — keep polling silently.
+    }
+    await new Promise(r => setTimeout(r, HEALTH_POLL_MS));
+  }
+
+  loadingScreen.classList.add('fade-out');
+  setTimeout(() => loadingScreen.classList.add('hidden'), 550);
+
+  playHeroEntrance();
+}
+
+// Drives the hero title's 3-stage entrance animation. Called ONLY on first
+// load (initLoadingSequence(), below) — this is a one-time first-impression
+// flourish, not something to replay on every return to the hero screen.
+//
+// BUGFIX: this used to also run from resetAll() on every Reset/"New Search",
+// per its own now-removed claim that doing so kept the experience
+// "consistent." It didn't — the function re-opaques the full-screen
+// #hero-bg-mask and re-hides every .hero-reveal element (inputs, tagline,
+// random button) for the FULL ~4.3s animation duration before its
+// `animationend` handler reveals them again. Replaying that on every reset
+// meant the entire screen went solid-background with nothing visible or
+// interactive for several seconds — reported as "the page going blank" when
+// tapping New Search, especially noticeable on mobile. resetAll() now calls
+// the lightweight resetHeroDisplay() below instead, which shows everything
+// immediately with no replay.
+// Each call:
+//   1. Re-hides the rest of the hero (.hero-reveal) and re-opaques the
+//      background mask (#hero-bg-mask) — necessary since this is the very
+//      first paint and both start in their "revealed" CSS state otherwise.
+//   2. Measures the title's actual landing position and computes the
+//      exact pixel offset needed to land it on the true viewport center
+//      (a fixed vh value over/undershoots depending on monitor height —
+//      the title's landing position is a fixed-px distance from center,
+//      not a viewport-relative one).
+//   3. Forces a reflow and re-adds the `entrance` class so the CSS
+//      animation restarts cleanly even if it was already played once.
+function playHeroEntrance() {
+  const heroTitle = document.getElementById('hero-title');
+  const mask = document.getElementById('hero-bg-mask');
+
+  document.querySelectorAll('.hero-reveal').forEach(el => el.classList.remove('show'));
+  if (mask) mask.classList.remove('hide');
+
+  heroTitle.classList.remove('entrance');
+  const rect = heroTitle.getBoundingClientRect();
+  const dy = window.innerHeight / 2 - (rect.top + rect.height / 2);
+  // The grown stage's transform is `scale(ENTRANCE_SCALE) translateY(...)` —
+  // translateY is applied first and then amplified by the scale that wraps
+  // it, so the on-screen displacement ends up as dy * ENTRANCE_SCALE, not
+  // dy. Pre-dividing here is what makes the title land exactly on center
+  // instead of overshooting by 45%. Must match the scale() value in the
+  // title-entrance keyframes (styles.css).
+  const ENTRANCE_SCALE = 1.45;
+  heroTitle.style.setProperty('--center-dy', `${Math.round(dy / ENTRANCE_SCALE)}px`);
+
+  void heroTitle.offsetWidth; // force reflow so the animation restarts from 0%
+
+  heroTitle.classList.add('entrance');
+  heroTitle.addEventListener('animationend', () => {
+    document.querySelectorAll('.hero-reveal').forEach(el => el.classList.add('show'));
+    if (mask) mask.classList.add('hide');
+    startPlaceholderRotation();
+    // Show onboarding on first visit only
+    if (!localStorage.getItem('aurelius_seen_onboarding')) {
+      showOnboarding();
+    }
+  }, { once: true });
+}
+
+// Lightweight hero reset for return visits (Reset / New Search) — shows
+// everything immediately instead of replaying playHeroEntrance()'s ~4.3s
+// title-grow-to-center-and-back sequence with its full-screen mask. See the
+// BUGFIX note on playHeroEntrance() above for why that replay was wrong here.
+function resetHeroDisplay() {
+  const heroTitle = document.getElementById('hero-title');
+  const mask = document.getElementById('hero-bg-mask');
+  heroTitle.classList.remove('entrance');
+  heroTitle.style.opacity = '1';
+  heroTitle.style.transform = 'scale(1)';
+  if (mask) mask.classList.add('hide');
+  document.querySelectorAll('.hero-reveal').forEach(el => el.classList.add('show'));
+  startPlaceholderRotation();
+}
+
+function showOnboarding() {
+  const modal = document.getElementById('onboarding-modal');
+  modal.classList.add('visible');
+}
+
+function closeOnboarding() {
+  const modal = document.getElementById('onboarding-modal');
+  modal.classList.remove('visible');
+  localStorage.setItem('aurelius_seen_onboarding', 'true');
+}
+
+initLoadingSequence();

common_wiki_searches.txt

@@ -0,0 +1,556 @@
+Albert Einstein
+Isaac Newton
+Charles Darwin
+Marie Curie
+Nikola Tesla
+Leonardo da Vinci
+William Shakespeare
+Wolfgang Amadeus Mozart
+Ludwig van Beethoven
+Vincent van Gogh
+Pablo Picasso
+Sigmund Freud
+Karl Marx
+Adolf Hitler
+Winston Churchill
+Abraham Lincoln
+George Washington
+Napoleon
+Julius Caesar
+Cleopatra
+Alexander the Great
+Genghis Khan
+Mahatma Gandhi
+Nelson Mandela
+Martin Luther King Jr.
+Barack Obama
+Donald Trump
+Elon Musk
+Bill Gates
+Steve Jobs
+Mark Zuckerberg
+Jeff Bezos
+Warren Buffett
+Stephen Hawking
+Carl Sagan
+Richard Feynman
+Alan Turing
+John von Neumann
+Ada Lovelace
+Tim Berners-Lee
+Linus Torvalds
+World War I
+World War II
+Cold War
+French Revolution
+American Revolution
+Russian Revolution
+Industrial Revolution
+Renaissance
+Roman Empire
+Byzantine Empire
+Ottoman Empire
+British Empire
+Ancient Egypt
+Ancient Greece
+Ancient Rome
+Holocaust
+September 11 attacks
+Cuban Missile Crisis
+Vietnam War
+Korean War
+Apollo 11
+Moon landing
+Big Bang
+Solar System
+Earth
+Sun
+Moon
+Mars
+Jupiter
+Saturn
+Black hole
+Galaxy
+Universe
+Quantum mechanics
+Theory of relativity
+Evolution
+DNA
+Human genome
+Photosynthesis
+Gravity
+Electricity
+Magnetism
+Periodic table
+Chemical element
+Atom
+Molecule
+Climate change
+Global warming
+Renewable energy
+Solar power
+Nuclear power
+Artificial intelligence
+Machine learning
+Deep learning
+Neural network
+Internet
+World Wide Web
+Computer
+Smartphone
+Programming language
+Python (programming language)
+JavaScript
+Java (programming language)
+C++
+Linux
+Microsoft Windows
+Android (operating system)
+iOS
+Google
+Apple Inc.
+Microsoft
+Amazon (company)
+Facebook
+Meta Platforms
+Twitter
+Tesla, Inc.
+SpaceX
+OpenAI
+Wikipedia
+YouTube
+Netflix
+Spotify
+United States
+United Kingdom
+France
+Germany
+Italy
+Spain
+Russia
+China
+Japan
+India
+Pakistan
+Bangladesh
+Brazil
+Mexico
+Canada
+Australia
+South Africa
+Egypt
+Nigeria
+Saudi Arabia
+Israel
+Iran
+Iraq
+Turkey
+Greece
+Poland
+Ukraine
+Sweden
+Norway
+Finland
+Switzerland
+Netherlands
+Belgium
+Portugal
+South Korea
+North Korea
+Vietnam
+Thailand
+Indonesia
+Philippines
+Malaysia
+Singapore
+New Zealand
+Argentina
+Chile
+Colombia
+Peru
+Venezuela
+Cuba
+New York City
+Los Angeles
+London
+Paris
+Tokyo
+Beijing
+Mumbai
+Delhi
+Moscow
+Berlin
+Rome
+Madrid
+Sydney
+Toronto
+Dubai
+Singapore (city)
+Hong Kong
+Shanghai
+Cairo
+Istanbul
+Bangkok
+Seoul
+Mohali
+Chandigarh
+Punjab, India
+Maharashtra
+Bangalore
+Chennai
+Kolkata
+Hyderabad
+Pune
+Ahmedabad
+Jaipur
+Lucknow
+Nagpur
+Football
+Basketball
+Cricket
+Tennis
+Baseball
+Olympic Games
+FIFA World Cup
+Cricket World Cup
+National Basketball Association
+Premier League
+UEFA Champions League
+Lionel Messi
+Cristiano Ronaldo
+Michael Jordan
+LeBron James
+Usain Bolt
+Serena Williams
+Roger Federer
+Muhammad Ali
+Pelé
+Diego Maradona
+Music
+Rock music
+Pop music
+Hip hop music
+Jazz
+Classical music
+The Beatles
+Elvis Presley
+Michael Jackson
+Bob Dylan
+Taylor Swift
+Beyoncé
+Film
+Hollywood
+Bollywood
+Academy Awards
+Star Wars
+The Lord of the Rings (film series)
+Harry Potter
+Marvel Cinematic Universe
+Television
+Streaming media
+Video game
+Minecraft
+Fortnite (video game)
+Chess
+Literature
+Novel
+Poetry
+The Bible
+Quran
+Religion
+Christianity
+Islam
+Hinduism
+Buddhism
+Judaism
+Sikhism
+Atheism
+Philosophy
+Plato
+Aristotle
+Socrates
+Immanuel Kant
+Friedrich Nietzsche
+Confucius
+Logic
+Ethics
+Mathematics
+Algebra
+Geometry
+Calculus
+Statistics
+Probability
+Number theory
+Physics
+Chemistry
+Biology
+Astronomy
+Geology
+Psychology
+Sociology
+Economics
+Capitalism
+Socialism
+Communism
+Democracy
+Government
+United Nations
+World Health Organization
+NASA
+European Union
+NATO
+World Bank
+International Monetary Fund
+Stock market
+Cryptocurrency
+Bitcoin
+Ethereum
+Inflation
+Recession
+Great Depression
+2008 financial crisis
+COVID-19 pandemic
+Vaccine
+Antibiotic
+Cancer
+Heart disease
+Diabetes
+Mental health
+Depression (mood)
+Anxiety
+Nutrition
+Exercise
+Sleep
+Human body
+Brain
+Heart
+Immune system
+Bacteria
+Virus
+Medicine
+Surgery
+Hospital
+Doctor of Medicine
+Nursing
+Pharmacy
+Veterinary medicine
+Agriculture
+Food
+Water
+Air pollution
+Plastic pollution
+Deforestation
+Biodiversity
+Endangered species
+Tiger
+Lion
+Elephant
+Whale
+Shark
+Dolphin
+Dog
+Cat
+Horse
+Bird
+Dinosaur
+Fossil
+Evolutionary biology
+Natural selection
+Ecosystem
+Rainforest
+Desert
+Ocean
+Mountain
+River
+Volcano
+Earthquake
+Tsunami
+Hurricane
+Tornado
+Weather
+Climate
+Season
+Time zone
+Calendar
+History of the world
+Prehistory
+Stone Age
+Bronze Age
+Iron Age
+Middle Ages
+Crusades
+Black Death
+Silk Road
+Colonialism
+Slavery
+Civil rights movement
+Feminism
+LGBT rights
+Human rights
+United States Constitution
+Declaration of Independence
+Magna Carta
+Law
+Crime
+Police
+Prison
+Supreme Court of the United States
+United States Congress
+President of the United States
+Prime Minister
+Monarchy
+Dictatorship
+Election
+Voting
+Political party
+Nationalism
+Globalization
+Trade
+Tariff
+Currency
+United States dollar
+Euro
+Gold
+Oil
+Coal
+Natural gas
+Electric vehicle
+Automobile
+Aircraft
+Airplane
+Boeing
+Airbus
+Ship
+Train
+Bicycle
+Bridge
+Skyscraper
+Architecture
+Eiffel Tower
+Statue of Liberty
+Great Wall of China
+Taj Mahal
+Pyramids of Giza
+Colosseum
+Stonehenge
+Machu Picchu
+Petra
+Angkor Wat
+Mount Everest
+Amazon rainforest
+Sahara
+Antarctica
+Arctic
+Pacific Ocean
+Atlantic Ocean
+Mediterranean Sea
+Nile
+Amazon River
+Yangtze
+Himalayas
+Andes
+Alps
+Grand Canyon
+Niagara Falls
+Yellowstone National Park
+Education
+University
+Harvard University
+Stanford University
+Massachusetts Institute of Technology
+Oxford University
+Cambridge University
+Library
+School
+Language
+English language
+Spanish language
+Mandarin Chinese
+Arabic
+Hindi
+French language
+German language
+Translation
+Linguistics
+Alphabet
+Writing system
+Printing press
+Photography
+Telephone
+Radio
+Television (technology)
+Satellite
+GPS
+Robot
+Automation
+3D printing
+Biotechnology
+Genetic engineering
+CRISPR
+Stem cell
+Cloning
+Space exploration
+International Space Station
+Hubble Space Telescope
+Mars rover
+Asteroid
+Comet
+Meteor
+Exoplanet
+Astrobiology
+String theory
+Dark matter
+Dark energy
+Higgs boson
+Large Hadron Collider
+Periodic table of elements
+Hydrogen
+Oxygen
+Carbon
+Gold (element)
+Iron
+Uranium
+Plutonium
+Nuclear weapon
+World population
+Urbanization
+Migration
+Refugee
+Poverty
+Famine
+War
+Terrorism
+Genocide
+Nuclear weapons testing
+Space Race
+Berlin Wall
+Iron Curtain
+Apartheid
+Tiananmen Square protests
+Arab Spring
+Brexit
+European migrant crisis
+Russian invasion of Ukraine
+Israeli–Palestinian conflict
+Climate justice
+Sustainable development
+United Nations Sustainable Development Goals
+Renewable resource
+Fossil fuel
+Carbon footprint
+Recycling
+Plastic
+Pandemic
+Epidemiology
+Public health
+Mental illness
+Autism
+ADHD
+Alzheimer's disease
+Parkinson's disease
+HIV/AIDS
+Tuberculosis
+Malaria
+Smallpox
+Influenza
+Spanish flu

config.py

@@ -0,0 +1,94 @@
+"""
+Aurelius — central configuration.
+
+All tunables live here so they can be adjusted (or env-overridden) without
+touching the search/embedding/wiki/server logic. See CLAUDE.md and the
+architect plan (Production Refactor + Algorithm + UI Pass, §2) for context.
+"""
+
+import os
+from pathlib import Path
+
+# ── Embedding model ──────────────────────────────────────────────────────
+# Default is all-MiniLM-L6-v2: 80 MB / 384-dim, fits free-tier deployment
+# (Render free web service) without OOMing or blowing the cold-start budget.
+# Qwen/Qwen3-Embedding-0.6B (plan §3) is a better-quality drop-in if you're
+# running on a host with more RAM — set AURELIUS_EMBED_MODEL to switch.
+EMBED_MODEL_NAME    = os.getenv("AURELIUS_EMBED_MODEL", "all-MiniLM-L6-v2")
+EMBED_DEVICE        = os.getenv("AURELIUS_EMBED_DEVICE", "cpu")
+EMBED_BATCH_SIZE    = int(os.getenv("AURELIUS_EMBED_BATCH", "64"))   # smaller for 0.6B vs 128 for MiniLM
+
+# ── Wikipedia ────────────────────────────────────────────────────────────
+WIKI_API            = "https://en.wikipedia.org/w/api.php"
+MAX_FETCH           = 500   # max links fetched from Wikipedia (paginated)
+MAX_PAGES           = 6     # safety cap on pagination pages when hunting for a specific goal link
+# Wikimedia's robot policy (https://w.wiki/4wJS) 403s requests whose
+# User-Agent has no contact info — this was dropped during the module split
+# and the bare "Aurelius-WikiNavigator/7.0" string started getting blocked.
+WIKI_HEADERS = {
+    "User-Agent": "Aurelius-WikiNavigator/7.0 (educational project; contact: murtaza.vali.ug25@plaksha.edu.in)",
+    "Accept": "application/json",
+}
+
+# ── Search ───────────────────────────────────────────────────────────────
+MAX_HOPS            = 60    # enforced as expansion-count cap, not path-length cap (see search.py)
+TOP_DISPLAY         = 25    # max neighbours sent to frontend per step
+
+# ── Scoring ──────────────────────────────────────────────────────────────
+# Architect plan (Honest Bidirectional Meeting-Check Rewrite): the target's
+# backlinks (depth-1) are now the actual goal zone, not just a score hint —
+# see search.py's meeting check. Depth-2 frontier, its bonus, and the
+# category bonus were removed: none of them could contribute a real,
+# verifiable edge, and depth-2 specifically could not be stitched into a
+# real path without bridge bookkeeping it never had. The stagnation/
+# frontier-jump escape valve was removed entirely — it fabricated a
+# came_from pointer with no corresponding Wikipedia link (see the Marcus
+# Aurelius -> A* search algorithm incident), which is no longer needed now
+# that the meeting check gives the search an honest way to converge.
+PRUNE_TOP_K         = 15    # keep this many candidates per expansion after scoring
+# NOTE: tried raising this to 0.22 as part of the Semantic Drift fix (see
+# search.py docstring) on the theory that richer "{title}. {short_desc}"
+# embeddings would make raw cosine trustworthy enough to support a higher
+# floor. Verified live against Marcus Aurelius -> A* search algorithm: the
+# best of Marcus Aurelius's 500 direct links scores only ~0.186 raw cosine
+# to the (also-enriched) target embedding — there is no semantically close
+# 1-hop neighbour for a niche CS topic from a Roman-emperor article, full
+# stop, regardless of embedding quality. 0.22 killed the search at step 1
+# (0/500 candidates survived). Kept at 0.15. The actual drift fix is the
+# embedding enrichment improving *relative* ranking among survivors, plus
+# DEPTH_TIEBREAK_EPSILON preventing runaway commitment to one irrelevant
+# cluster — not an absolute floor, which hard multi-hop cases can't clear
+# early on by construction.
+PRUNE_FLOOR         = 0.15  # soft floor on raw cosine-to-target; frontier members exempt
+PRUNE_MIN_SURVIVORS = 5     # ALWAYS keep at least this many top-ranked candidates per step,
+                            # even if they fall below PRUNE_FLOOR — prevents the search from
+                            # killing itself at step 1 for semantically distant pairs
+                            # (Cleopatra → Time complexity: 0/500 candidates cleared 0.15,
+                            # search died immediately)
+FRONTIER_D1_BONUS   = 0.30  # candidate is a direct backlink of the target (goal-zone member)
+
+# Depth tie-breaker (Semantic Drift fix): heap priority is h + DEPTH_EPSILON*g
+# instead of pure h. This is a deliberate, documented reversal of the prior
+# "heap priority = h only, no g-cost" design (see CLAUDE.md) — pure-greedy
+# let one noisy high-scoring title (e.g. a proper noun with no domain
+# context) drag the search arbitrarily deep into its cluster with nothing
+# to prefer a shallower, more recently-improving alternative. 0.01 is small
+# enough that it only breaks ties/near-ties; it doesn't override a genuinely
+# strong h advantage at any reasonable depth (60 hops -> max 0.6 penalty).
+DEPTH_TIEBREAK_EPSILON = 0.01
+
+# ── Active Backward Expansion (goal-zone depth-2) ───────────────────────
+GOAL_ZONE_EXPAND_INTERVAL   = 10    # expand goal zone every N steps
+GOAL_ZONE_EXPAND_BATCH      = 5     # d1 members to expand per interval
+GOAL_ZONE_D2_BACKLINK_LIMIT = 100   # max backlinks fetched per d1 member
+FRONTIER_D2_BONUS           = 0.15  # score bonus for d2 goal-zone members (half of d1's 0.30)
+
+# ── Stagnation Detection / Cluster Escape ────────────────────────────────
+STAGNATION_WINDOW       = 8     # sliding window size for h-improvement tracking
+STAGNATION_DELTA        = 0.02  # min improvement over window to count as progress
+PRUNE_TOP_K_STAGNANT    = 25    # widened beam when stagnant (vs 15 normal)
+DIVERSITY_WEIGHT        = 0.10  # weight for centroid-distance diversity bonus
+
+# ── Files ────────────────────────────────────────────────────────────────
+_THIS_DIR           = Path(__file__).resolve().parent
+SEED_FILE           = _THIS_DIR / "common_wiki_searches.txt"

embedding.py

@@ -0,0 +1,138 @@
+"""
+Aurelius — embedding model singleton, batch_embed, cosine, session caches.
+
+Implements architect plan §3 (embedding swap to Qwen3-Embedding-0.6B) and
+part of §1 (module split: model singleton + caches live here, owned by the
+module that uses them, per the plan's "Module-level globals ... follow
+their owning module" instruction).
+"""
+
+import asyncio
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+# Once the model has been downloaded once, sentence-transformers/huggingface_hub
+# still spend 1-3s on every startup doing a network round-trip to check for
+# updates. These must be set before `sentence_transformers` is imported, and
+# only skip the check if the model is already cached locally (first run still
+# goes online to fetch it).
+#
+# Architect plan §3: widen the glob from "models--sentence-transformers--*"
+# to "models--*" so this still kicks in for the new Qwen3 model (whose cache
+# dir is "models--Qwen--Qwen3-Embedding-0.6B", not "models--sentence-transformers--*").
+# Still safe — it only activates when *any* cached model exists locally.
+_hf_cache = Path.home() / ".cache" / "huggingface" / "hub"
+if _hf_cache.exists() and any(_hf_cache.glob("models--*")):
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from config import EMBED_MODEL_NAME, EMBED_DEVICE, EMBED_BATCH_SIZE
+
+# ══════════════════════════════════════════════════════════════
+# MODEL SINGLETON — loaded once at startup, in-process
+# ══════════════════════════════════════════════════════════════
+
+_EMBED_MODEL: Optional[SentenceTransformer] = None
+
+
+async def load_model():
+    """
+    Startup handler: loads the embedding model once, in-process.
+
+    device="cpu" skips torch's CUDA-availability probe (driver/nvidia-smi
+    calls), which otherwise adds 1-2s on machines without a fast GPU setup.
+
+    No silent fallback to MiniLM on failure (architect plan §3) — if the
+    download or load fails, this re-raises so FastAPI refuses connections
+    rather than degrading silently.
+    """
+    global _EMBED_MODEL
+    print(f"[Embed] Loading sentence-transformers model '{EMBED_MODEL_NAME}'...")
+    t0 = time.time()
+    _EMBED_MODEL = SentenceTransformer(EMBED_MODEL_NAME, device=EMBED_DEVICE)
+    print(f"[Embed] {EMBED_MODEL_NAME} ready "
+          f"(dim={_EMBED_MODEL.get_embedding_dimension()}, {time.time()-t0:.1f}s)")
+
+
+# ══════════════════════════════════════════════════════════════
+# SESSION CACHES  (reset each search)
+# ══════════════════════════════════════════════════════════════
+
+_emb_cache: dict[str, np.ndarray] = {}   # title → embedding vector
+_dead_ends: set[str]              = set() # articles with 0 links
+
+
+def reset_session_caches():
+    global _emb_cache, _dead_ends
+    _emb_cache = {}
+    _dead_ends = set()
+
+
+# ══════════════════════════════════════════════════════════════
+# VECTOR MATH
+# ══════════════════════════════════════════════════════════════
+
+def cosine_similarity(a, b) -> float:
+    if a is None or b is None:
+        return 0.0
+    a = np.asarray(a, dtype=np.float32)
+    b = np.asarray(b, dtype=np.float32)
+    if a.size == 0 or b.size == 0:
+        return 0.0
+    na = np.linalg.norm(a)
+    nb = np.linalg.norm(b)
+    if na == 0 or nb == 0:
+        return 0.0
+    return float(np.dot(a, b) / (na * nb))
+
+
+# ══════════════════════════════════════════════════════════════
+# EMBEDDING  (in-process sentence-transformers, no network calls)
+# ══════════════════════════════════════════════════════════════
+
+async def batch_embed(texts: list[str], stats,
+                       embed_texts: list[str] | None = None) -> list[np.ndarray]:
+    """
+    Embed texts via the in-process sentence-transformers model.
+    Results are cached per title across the session. Runs the (CPU-bound,
+    synchronous) encode call in a thread executor so it never blocks the
+    event loop — keeps pause/resume and other WS traffic responsive.
+
+    `embed_texts`, if given, is what actually gets encoded (parallel to
+    `texts`, which remains the cache key). Lets callers embed a richer
+    string — e.g. "Anu. Mesopotamian sky-god" — while still caching and
+    looking up by the bare title "Anu". Bare-title-only embedding can't
+    tell a proper noun's actual subject apart from the target's, which is
+    what let semantically unrelated link-adjacent pages (mythology,
+    scripture, etc.) survive scoring on noisy title-only cosine alone.
+
+    `stats` is a SearchStats instance (search.py); only its embed_calls
+    counter is touched here, so no import of search.py is needed (keeps
+    embedding.py free of any dependency on search.py).
+    """
+    if not texts or _EMBED_MODEL is None:
+        return [np.array([]) for _ in texts]
+    if embed_texts is None:
+        embed_texts = texts
+
+    uncached_idx  = [i for i, t in enumerate(texts) if t not in _emb_cache]
+    uncached_text = [embed_texts[i] for i in uncached_idx]
+    if uncached_text:
+        loop = asyncio.get_running_loop()
+        embs = await loop.run_in_executor(
+            None,
+            lambda: _EMBED_MODEL.encode(
+                uncached_text, convert_to_numpy=True,
+                batch_size=EMBED_BATCH_SIZE, show_progress_bar=False,
+            ),
+        )
+        stats.embed_calls += 1
+        for orig_i, emb in zip(uncached_idx, embs):
+            _emb_cache[texts[orig_i]] = emb
+
+    return [_emb_cache.get(t, np.array([])) for t in texts]

index.html

@@ -0,0 +1,498 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Aurelius</title>
+  <link rel="icon" type="image/png"
+    href="data:image/png;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAAAAAAAABimQAAt4UAABjaWFlaIAAAAAAAACSgAAAPhAAAts9YWVogAAAAAAAA9tYAAQAAAADTLXBhcmEAAAAAAAQAAAACZmYAAPKnAAANWQAAE9AAAApbAAAAAAAAAABtbHVjAAAAAAAAAAEAAAAMZW5VUwAAACAAAAAcAEcAbwBvAGcAbABlACAASQBuAGMALgAgADIAMAAxADb/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEPERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh7/wAARCAH0AfQDASIAAhEBAxEB/8QAHQABAAICAwEBAAAAAAAAAAAAAAYHBAgBAwUCCf/EAEsQAAIBAwIEAwQGBwQHBwUBAAABAgMEBQYRByExQRJRYQgTcYEUIjKRobEVI0JSksHTM1Vi8SRjcnWisvAXNEZTgsLRFjVDs9Lh/8QAGwEBAAIDAQEAAAAAAAAAAAAAAAEDAgQFBgf/xAAuEQEAAgIBAgMHBQEAAwAAAAAAAQIDEQQFMRMhQQYSUXGBobEyM1Jh0SIVkfD/2gAMAwEAAhEDEQA/ANMgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALS4Q8HsrrSMMpkZzx2E35Vdv1tfb/AMtNbbf4ny9GVZs1MNJvknUQuwYMnIvGPHG5lVoN49L8N9FadtoUrHT1jUqRW30i5pRq1ZPz8Uk9vlsj2rrT+BvKLo3eExtxSa2cKtrCa2+aOHb2j48W1WszD0FPZfkzXc2iJaBA2q4i8BNPZehWu9MJYjIbNxpbv6NN+TXN…[truncated base64 icon]">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.js"></script>
+  <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=Cinzel:wght@700;900&family=Outfit:wght@300;400;500;600;700&family=DM+Mono:ital,wght@0,400;0,500;1,400&display=swap"
+    rel="stylesheet">
+  <link rel="stylesheet" href="styles.css">
+</head>
+
+<body>
+
+  <!-- ═══════════════════ LOADING SCREEN ═══════════════════ -->
+  <div id="loading-screen">
+    <div id="loading-logo">Aurelius</div>
+    <div id="loading-spinner"></div>
+  </div>
+
+  <!-- ═══════════════════ HERO LANDING ═══════════════════ -->
+  <div id="hero">
+    <div id="hero-watermark">
+      <svg class="aurelius-logo-hero" viewBox="0 0 200 200" aria-hidden="true">
+        <defs>
+          <radialGradient id="wm-glow" cx="50%" cy="50%" r="50%">
+            <stop offset="0%" stop-color="rgba(201,138,46,0.10)" />
+            <stop offset="100%" stop-color="rgba(201,138,46,0)" />
+          </radialGradient>
+        </defs>
+        <circle cx="100" cy="100" r="90" fill="url(#wm-glow)" />
+        <g class="wm-edges">
+          <line x1="100" y1="28" x2="158" y2="52" />
+          <line x1="158" y1="52" x2="172" y2="108" />
+          <line x1="172" y1="108" x2="142" y2="158" />
+          <line x1="142" y1="158" x2="100" y2="176" />
+          <line x1="100" y1="176" x2="58" y2="158" />
+          <line x1="58" y1="158" x2="28" y2="108" />
+          <line x1="28" y1="108" x2="42" y2="52" />
+          <line x1="42" y1="52" x2="100" y2="28" />
+          <line x1="100" y1="28" x2="100" y2="100" />
+          <line x1="158" y1="52" x2="100" y2="100" />
+          <line x1="172" y1="108" x2="100" y2="100" />
+          <line x1="58" y1="158" x2="100" y2="100" />
+          <line x1="42" y1="52" x2="100" y2="100" />
+          <line x1="28" y1="108" x2="58" y2="158" />
+          <line x1="42" y1="52" x2="158" y2="52" />
+          <line x1="142" y1="158" x2="58" y2="158" />
+          <line x1="100" y1="28" x2="142" y2="158" />
+          <line x1="42" y1="52" x2="172" y2="108" />
+        </g>
+        <polyline class="wm-path-trace" points="42,52 100,100 158,52 172,108 142,158" />
+        <polyline class="wm-path-trace wm-trace-2" points="100,28 100,100 58,158 100,176" />
+        <g class="wm-nodes">
+          <circle cx="100" cy="28" r="4.5" />
+          <circle cx="158" cy="52" r="4.5" />
+          <circle cx="172" cy="108" r="4.5" />
+          <circle cx="142" cy="158" r="4.5" />
+          <circle cx="100" cy="176" r="4.5" />
+          <circle cx="58" cy="158" r="4.5" />
+          <circle cx="28" cy="108" r="4.5" />
+          <circle cx="42" cy="52" r="4.5" />
+        </g>
+        <circle class="wm-hub" cx="100" cy="100" r="6.5" />
+        <circle class="wm-particle wm-p1" r="1.5" />
+        <circle class="wm-particle wm-p2" r="1.2" />
+        <circle class="wm-particle wm-p3" r="1.8" />
+        <circle class="wm-particle wm-p4" r="1" />
+      </svg>
+    </div>
+    <div id="hero-bg-mask"></div>
+    <button id="hero-about-btn" class="hero-reveal" onclick="openAboutModal()">About</button>
+    <div id="hero-title" style="font-family: Cinzel">Aurelius</div>
+    <div id="hero-tagline" class="hero-reveal">Navigate the Knowledge Graph</div>
+    <div id="hero-rest" class="hero-reveal">
+      <div id="hero-sub">Find the hidden path between any two Wikipedia articles.<br>Watch Aurelius navigate the world's
+        largest knowledge graph in real time.</div>
+
+      <div id="hero-inputs">
+        <div class="hero-field">
+          <label id="lbl-start" for="hero-inp-start">From</label>
+          <input id="hero-inp-start" class="hero-input" type="text" autocomplete="on"
+            placeholder="e.g. Nagpur" autocomplete="off" oninput="heroInputChanged()" onkeydown="heroKeyDown(event)" />
+          <div id="ac-dropdown-start" class="ac-dropdown"></div>
+        </div>
+
+        <div id="hero-arrow">→</div>
+
+        <div class="hero-field">
+          <label id="lbl-end" for="hero-inp-end">To</label>
+          <input id="hero-inp-end" class="hero-input" type="text" autocomplete="off" placeholder="e.g. Mars"
+            oninput="heroInputChanged()" onkeydown="heroKeyDown(event)" />
+          <div id="ac-dropdown-end" class="ac-dropdown"></div>
+        </div>
+      </div>
+
+      <button id="hero-btn" onclick="startSearch()">Find Path</button>
+      <div id="hero-hint">Press Enter to search</div>
+
+      <button id="hero-random-btn" onclick="useRandomPair()" title="Pick two random topics and find a path">
+        Random
+      </button>
+    </div>
+  </div>
+
+  <!-- ═══════════════════ TOP BAR (post-search) ═══════════════════ -->
+  <div id="topbar">
+    <h1 id="topbar-logo" onclick="logoClick()" title="Return to home">
+      <svg class="topbar-logo-img aurelius-logo" viewBox="0 0 100 100" aria-hidden="true">
+        <g class="alogo-edges" opacity="0.5">
+          <line x1="50" y1="14" x2="79" y2="26" />
+          <line x1="79" y1="26" x2="86" y2="54" />
+          <line x1="86" y1="54" x2="71" y2="79" />
+          <line x1="71" y1="79" x2="50" y2="88" />
+          <line x1="50" y1="88" x2="29" y2="79" />
+          <line x1="29" y1="79" x2="14" y2="54" />
+          <line x1="14" y1="54" x2="21" y2="26" />
+          <line x1="21" y1="26" x2="50" y2="14" />
+          <line x1="50" y1="14" x2="50" y2="50" />
+          <line x1="79" y1="26" x2="50" y2="50" />
+          <line x1="21" y1="26" x2="50" y2="50" />
+          <line x1="86" y1="54" x2="50" y2="50" />
+          <line x1="29" y1="79" x2="50" y2="50" />
+        </g>
+        <polyline class="alogo-trace" points="21,26 50,50 79,26 86,54 71,79" />
+        <g class="alogo-nodes">
+          <circle cx="50" cy="14" r="5" />
+          <circle cx="79" cy="26" r="5" />
+          <circle cx="86" cy="54" r="5" />
+          <circle cx="71" cy="79" r="5" />
+          <circle cx="50" cy="88" r="5" />
+          <circle cx="29" cy="79" r="5" />
+          <circle cx="14" cy="54" r="5" />
+          <circle cx="21" cy="26" r="5" />
+        </g>
+        <circle class="alogo-hub" cx="50" cy="50" r="7" />
+      </svg>
+      Aurelius
+    </h1>
+    <div class="input-wrap">
+      <span>FROM</span>
+      <input id="inp-start" type="text" placeholder="Article or Wikipedia URL" />
+    </div>
+    <button id="btn-swap" onclick="swapInputs()" title="Swap start and end">⇅</button>
+    <div class="input-wrap">
+      <span>TO</span>
+      <input id="inp-end" type="text" placeholder="Article or Wikipedia URL" />
+    </div>
+    <button id="btn-search" onclick="startSearch()">Find Path</button>
+    <button id="btn-reset" onclick="resetAll()">Reset</button>
+    <button id="btn-about" onclick="openAboutModal()">About</button>
+    <span id="status-bar">Ready.</span>
+  </div>
+
+  <!-- Mobile-only: collapses #topbar above to keep the search-controls
+       chrome out of the way by default, so a phone screen opens on the
+       live graph instead of a cluttered stack. Hidden entirely on
+       desktop/tablet (styles.css), where the topbar is always visible. -->
+  <div id="mobile-topbar-handle" class="mobile-handle" onclick="toggleMobileTopbar()">
+    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="11" height="11"><polyline points="4 6 8 10 12 6"/></svg>
+    <span>Search</span>
+  </div>
+
+  <!-- ═══ STATS BAR (pause/export only — timer shown on completion) ═══ -->
+  <div id="stats-bar">
+    <div id="sv-steps-live" class="sstat">
+      <span class="sstat-val" id="sv-steps-count">0</span> explored
+    </div>
+    <div class="stats-spacer"></div>
+    <button id="btn-export" onclick="exportPath()" title="Export path [E]">↓ Export</button>
+    <button id="btn-pause-bar" onclick="togglePause()" title="Pause/Resume [Space]">⏸ Pause</button>
+  </div>
+
+  <!-- ═══════════════════ MAIN CONTENT ═══════════════════ -->
+  <div id="main">
+    <!-- Graph -->
+    <div id="canvas-wrap">
+      <svg id="graph"></svg>
+      <div id="tooltip">
+        <div class="tt-title" id="tt-title"></div>
+        <div class="tt-scores" id="tt-scores"></div>
+      </div>
+    </div>
+
+    <!-- Mobile-only: toggles the panel below open/closed. Lives OUTSIDE
+         #panel (not inside it) so it stays visible and tappable even while
+         #panel itself is collapsed to zero height — see styles.css. Hidden
+         entirely on desktop/tablet, where the panel is always visible. -->
+    <div id="mobile-panel-handle" class="mobile-handle" onclick="toggleMobilePanel()">
+      <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="11" height="11"><polyline points="4 6 8 10 12 6"/></svg>
+      <span>Path &amp; Details</span>
+    </div>
+
+    <!-- Panel -->
+    <div id="panel">
+      <div id="panel-tabs">
+        <div class="tab active" onclick="switchTab('path')">Path</div>
+        <div class="tab" onclick="switchTab('scores')">Scores</div>
+        <div class="tab" onclick="switchTab('log')">Log</div>
+        <div class="tab" onclick="switchTab('legend')">Key</div>
+      </div>
+      <div id="tab-path" class="tab-content active">
+        <div id="path-display">
+          <p style="font-size:13px;color:var(--text2)">Path will appear here as A* explores.</p>
+        </div>
+      </div>
+      <div id="tab-scores" class="tab-content">
+        <div id="scores-list"></div>
+      </div>
+      <div id="tab-log" class="tab-content">
+        <div id="log"></div>
+      </div>
+      <div id="tab-legend" class="tab-content">
+        <div style="display:flex;flex-direction:column;gap:12px;margin-top:4px">
+          <div class="legend-row">
+            <div class="legend-dot" style="background:var(--amber)"></div>Current centre (being expanded)
+          </div>
+          <div class="legend-row">
+            <div class="legend-dot" style="background:var(--accent)"></div>Open — in A* queue
+          </div>
+          <div class="legend-row">
+            <div class="legend-dot" style="background:#374151;border:1px solid #555"></div>Closed — already explored
+          </div>
+          <div class="legend-row">
+            <div class="legend-dot" style="background:var(--green)"></div>Target article
+          </div>
+          <div class="legend-row">
+            <div class="legend-dot" style="background:var(--node-path)"></div>On current best path
+          </div>
+          <hr style="border-color:var(--border)" />
+          <div style="font-size:13px;color:var(--text2);line-height:1.8">
+            <b style="color:var(--text)">f(n)</b> = total estimated cost<br>
+            <b style="color:var(--text)">g(n)</b> = hops from start<br>
+            <b style="color:var(--text)">h(n)</b> = Wikipedia relevance heuristic<br>
+            <br>A* always expands the node with <b style="color:var(--accent2)">lowest f(n)</b> next.
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Path banner -->
+  <div id="path-banner"></div>
+
+  <!-- Centered Success Modal -->
+  <div id="success-modal" class="modal-backdrop" onclick="closeSuccessModal(event)">
+    <div class="modal-card">
+      <button class="modal-corner-close" onclick="closeSuccessModal()" aria-label="Close">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="3" x2="13" y2="13"/><line x1="13" y1="3" x2="3" y2="13"/></svg>
+      </button>
+      <svg class="modal-success-icon" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="2"
+        stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="6" cy="26" r="3" />
+        <circle cx="26" cy="6" r="3" />
+        <path d="M8.4 24 C8.4 16 12 16 16 16 C20 16 23.6 16 23.6 8" />
+      </svg>
+      <h2 class="modal-title">Path Discovered!</h2>
+      <div class="modal-stat-row">
+        <div class="modal-stat">
+          <span class="modal-stat-val" id="modal-hops">—</span>
+          <span class="modal-stat-lbl">Hops</span>
+        </div>
+        <div class="modal-stat">
+          <span class="modal-stat-val" id="modal-steps">—</span>
+          <span class="modal-stat-lbl">Steps</span>
+        </div>
+        <div class="modal-stat">
+          <span class="modal-stat-val" id="modal-elapsed">—</span>
+          <span class="modal-stat-lbl">Time</span>
+        </div>
+      </div>
+      <div id="modal-path-container" class="modal-path"></div>
+      <p class="modal-disclaimer">
+        Every link above is real, but the wording shown on a page isn't always
+        the link's title — e.g. a page may display "iterative" while the link
+        actually points to "Iteration", or show "AI" linking to
+        "Artificial intelligence". Wikipedia links can be piped like that, so
+        the visible text and the article it leads to can differ.
+      </p>
+      <div style="display:flex; justify-content:center; gap:12px; flex-wrap:wrap;">
+        <button class="modal-close-btn" onclick="closeSuccessModal()">Explore Graph</button>
+        <button class="modal-copy-btn" id="modal-copy-btn" onclick="copyPath()">Copy Path</button>
+        <button class="modal-close-btn"
+          style="background:transparent; border:1px solid var(--border); color:var(--text2);"
+          onclick="resetAll(true)">New Search</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- About Modal -->
+  <div id="about-modal" class="modal-backdrop" onclick="closeAboutModal(event)">
+    <div class="modal-card about-card">
+
+      <!-- Header -->
+      <div style="display:flex;align-items:center;gap:16px;margin-bottom:28px;">
+        <svg class="aurelius-logo" viewBox="0 0 100 100" aria-hidden="true"
+          style="height:42px;width:42px;opacity:0.92;flex-shrink:0;overflow:visible;filter:drop-shadow(0 0 14px rgba(124,106,247,0.45));">
+          <g class="alogo-edges" opacity="0.5">
+            <line x1="50" y1="14" x2="79" y2="26" />
+            <line x1="79" y1="26" x2="86" y2="54" />
+            <line x1="86" y1="54" x2="71" y2="79" />
+            <line x1="71" y1="79" x2="50" y2="88" />
+            <line x1="50" y1="88" x2="29" y2="79" />
+            <line x1="29" y1="79" x2="14" y2="54" />
+            <line x1="14" y1="54" x2="21" y2="26" />
+            <line x1="21" y1="26" x2="50" y2="14" />
+            <line x1="50" y1="14" x2="50" y2="50" />
+            <line x1="79" y1="26" x2="50" y2="50" />
+            <line x1="21" y1="26" x2="50" y2="50" />
+            <line x1="86" y1="54" x2="50" y2="50" />
+            <line x1="29" y1="79" x2="50" y2="50" />
+          </g>
+          <polyline class="alogo-trace" points="21,26 50,50 79,26 86,54 71,79" />
+          <g class="alogo-nodes">
+            <circle cx="50" cy="14" r="5" />
+            <circle cx="79" cy="26" r="5" />
+            <circle cx="86" cy="54" r="5" />
+            <circle cx="71" cy="79" r="5" />
+            <circle cx="50" cy="88" r="5" />
+            <circle cx="29" cy="79" r="5" />
+            <circle cx="14" cy="54" r="5" />
+            <circle cx="21" cy="26" r="5" />
+          </g>
+          <circle class="alogo-hub" cx="50" cy="50" r="7" />
+        </svg>
+        <div>
+          <h2
+            style="font-family:'Cinzel',serif;font-size:22px;font-weight:900;color:#fff;letter-spacing:3px;text-transform:uppercase;line-height:1">
+            AURELIUS</h2>
+          <p style="font-size:12px;color:var(--text2);margin-top:6px;letter-spacing:0.2px">Wikipedia path explorer</p>
+        </div>
+      </div>
+
+      <!-- Quote -->
+      <div class="about-quote-block">
+        <span class="about-quote-mark">"</span>
+        <p class="about-quote-text">The universe is change, our life is what our thoughts make it.</p>
+        <p class="about-quote-attr">Marcus Aurelius — Meditations</p>
+      </div>
+
+      <p class="about-prose">Named after the Stoic emperor who wrote that every idea connects to the next. Wikipedia is
+        proof of that — millions of articles linked by shared meaning. Aurelius makes those connections visible by
+        finding the path between any two articles, however unrelated they seem.</p>
+
+      <hr class="about-divider" />
+      <span class="about-section-label">How it works</span>
+      <p style="font-size:11px;color:var(--text2);opacity:0.6;font-style:italic;margin:-8px 0 16px;">
+        Works best on desktop — the live graph and side panel are easiest to read on a larger screen.
+      </p>
+      <div class="about-tech-grid">
+        <div class="about-tech-card">
+          <svg class="tech-icon" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.8"
+            stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="6" cy="26" r="3" />
+            <circle cx="16" cy="6" r="3" />
+            <circle cx="26" cy="20" r="3" />
+            <path d="M8.2 24 L14 8.5" />
+            <path d="M18 7.8 L24 18.2" />
+            <circle cx="16" cy="16" r="1.8" fill="currentColor" stroke="none" />
+          </svg>
+          <div class="tech-name">A8 Search</div>
+          <div class="tech-desc">Built for meaning, not distance. Each candidate's priority blends three signals:
+            semantic closeness, a <em>verified</em> backlink bridge to the destination, and category alignment into a
+            single score. There is no depth penalty. A8 commits fully to whichever lead looks strongest at that moment
+            instead of spreading thin.</div>
+        </div>
+        <div class="about-tech-card">
+          <svg class="tech-icon" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.8"
+            stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="7" cy="25" r="2.5" />
+            <circle cx="16" cy="7" r="2.5" />
+            <circle cx="26" cy="22" r="2.5" />
+            <circle cx="13" cy="18" r="2.5" />
+            <circle cx="22" cy="13" r="2.5" />
+            <line x1="9" y1="23.5" x2="11.5" y2="19.5" />
+            <line x1="14.8" y1="9.2" x2="13.6" y2="15.5" />
+            <line x1="23.5" y1="14.8" x2="24.5" y2="19.5" />
+            <line x1="15.4" y1="17.8" x2="20" y2="14.2" />
+          </svg>
+          <div class="tech-name">Semantic Embeddings</div>
+          <div class="tech-desc">Titles become high-dimensional vectors, computed instantly on-device. Cosine similarity
+            tells the search how close any candidate is to the target, not through keywords, but through
+            <em>meaning</em>.
+          </div>
+        </div>
+        <div class="about-tech-card">
+          <svg class="tech-icon" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.8"
+            stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="27" cy="16" r="4" />
+            <circle cx="16" cy="16" r="2.2" fill="currentColor" stroke="none" />
+            <path d="M3 16 H13.8" />
+            <path d="M10.5 12.5 L13.8 16 L10.5 19.5" />
+            <path d="M23 16 H18.2" />
+          </svg>
+          <div class="tech-name">Bidirectional Target Frontier</div>
+          <div class="tech-desc">Before searching, Aurelius maps every article one and two links away from the target.
+            Candidates inside that zone receive a strong score boost. The search aims at a wide net, not a single point.
+          </div>
+        </div>
+        <div class="about-tech-card">
+          <svg class="tech-icon" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.8"
+            stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="16" cy="16" r="11" />
+            <path d="M10 16 L14 20 L22 12" />
+            <path d="M16 5 V8" />
+            <path d="M16 24 V27" />
+            <path d="M5 16 H8" />
+            <path d="M24 16 H27" />
+          </svg>
+          <div class="tech-name">Stagnation Escape</div>
+          <div class="tech-desc">If the search stalls in a dense off-topic cluster, Aurelius detects the plateau,
+            widens the beam, and adds a <em>diversity bonus</em> to candidates far from the cluster centroid.
+            No fabricated edges, just smarter pruning to break free.</div>
+        </div>
+      </div>
+
+      <hr class="about-divider" />
+      <span class="about-section-label">What makes it different</span>
+      <div class="about-compare">
+        <div class="about-compare-head">Traditional Wiki Solver</div>
+        <div class="about-compare-head accent">Aurelius</div>
+
+        <div class="about-compare-cell">Blind to meaning. "Film" and "Film noir" count the same</div>
+        <div class="about-compare-cell accent">Ranks every candidate by semantic similarity</div>
+
+        <div class="about-compare-cell">Treats every link as equally promising</div>
+        <div class="about-compare-cell accent">Boosts verified backlink bridges and goal-zone members</div>
+
+        <div class="about-compare-cell">Expands breadth-first until both frontiers meet</div>
+        <div class="about-compare-cell accent">Commits fully to the strongest lead, with no wasted breadth</div>
+
+        <div class="about-compare-cell">No model of meaning at all, just raw links</div>
+        <div class="about-compare-cell accent">Embeddings + graph search, zero language models</div>
+      </div>
+
+      <hr class="about-divider" />
+      <span class="about-section-label">Built by</span>
+      <p style="font-size:16px;font-weight:800;color:#fff;margin-bottom:6px">Murtaza Vali</p>
+      <p class="about-prose" style="margin-bottom:18px">CS student who got curious about A* pathfinding and ended up
+        building something with embeddings, a verified backlink graph, and a live force-directed visualization. This is
+        what happens when you keep adding "just one more thing."</p>
+      <a href="https://www.linkedin.com/in/murtaza-vali-741835274/" target="_blank" rel="noopener"
+        class="about-linkedin-btn">LinkedIn ↗</a>
+
+      <div style="margin-top:28px;text-align:right;">
+        <button class="modal-close-btn" onclick="closeAboutModal()">Close</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- Onboarding Modal (first-time users) -->
+  <div id="onboarding-modal" class="modal-backdrop">
+    <div class="modal-card onboarding-card">
+      <button class="modal-corner-close" onclick="closeOnboarding()" aria-label="Close">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="3" x2="13" y2="13"/><line x1="13" y1="3" x2="3" y2="13"/></svg>
+      </button>
+      <h2 class="onboarding-title">Welcome to Aurelius</h2>
+      <p class="onboarding-tagline">Navigate the Knowledge Graph</p>
+      <div class="onboarding-steps">
+        <div class="onboarding-step">
+          <div class="onboarding-icon">1</div>
+          <div>
+            <strong>Pick two Wikipedia articles</strong>
+            <p>Type any topic in the From and To fields, or hit Random for a surprise pair.</p>
+          </div>
+        </div>
+        <div class="onboarding-step">
+          <div class="onboarding-icon">2</div>
+          <div>
+            <strong>Watch the search unfold</strong>
+            <p>Aurelius explores Wikipedia links in real time. Nodes glow as they're visited.</p>
+          </div>
+        </div>
+        <div class="onboarding-step">
+          <div class="onboarding-icon">3</div>
+          <div>
+            <strong>Discover the path</strong>
+            <p>The orange trail is the shortest chain of real Wikipedia links connecting your articles.</p>
+          </div>
+        </div>
+      </div>
+      <p class="onboarding-tip">
+        Tip: try two completely random, unrelated things — that's usually where the most surprising connections show up.
+      </p>
+      <button class="modal-close-btn onboarding-go-btn" onclick="closeOnboarding()">Let's Go</button>
+    </div>
+  </div>
+
+  <script src="app.js"></script>
+</body>
+
+</html>

main.py

@@ -0,0 +1,34 @@
+"""
+Aurelius — Wikipedia Rabbit-Hole Navigator Backend
+Architecture: embeddings + graph search only. No LLM, no external services.
+
+Thin entrypoint per architect plan §1 — everything else lives in
+config.py, embedding.py, wiki.py, search.py, server.py. This file keeps
+only the Windows stdout encoding fix (must run before any import that
+might log non-ASCII, e.g. the arrow characters in search.py's log lines)
+and the uvicorn launch.
+"""
+
+import sys
+
+# Windows redirects stdout to cp1252 when it's not an interactive console
+# (e.g. piped to a log file), which raises on the arrow/emoji characters
+# used in log lines below and would otherwise crash mid-search.
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except Exception:
+    pass
+
+import os  # noqa: E402
+
+from server import app  # noqa: E402 (must follow the stdout fix above)
+
+if __name__ == "__main__":
+    import uvicorn
+    # Render (and most PaaS hosts) inject a dynamic $PORT and require the
+    # app to bind to it; 8000 is just the local-dev fallback.
+    port = int(os.getenv("PORT", "8000"))
+    print(f"\n🌐 Aurelius backend → http://localhost:{port}")
+    print("   Open index.html in your browser\n")
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="info")

mainpybackup.txt

@@ -0,0 +1,799 @@
+"""
+Aurelius — Wikipedia Rabbit-Hole Navigator Backend
+Architecture: embeddings + graph search only. No LLM, no external services.
+
+Per-expansion pipeline:
+  1. Fetch ALL links from article (paginated, up to MAX_FETCH)
+  2. Batch-embed ALL uncached links in one in-process sentence-transformers call
+  3. Score each candidate: cosine-to-target + frontier bonus + category bonus
+  4. Prune to top PRUNE_TOP_K, dropping anything below the raw-cosine floor
+  5. Push survivors to heap (greedy best-first: heap key = h only)
+
+The only external dependency at runtime is the Wikipedia API itself. The
+embedding model (sentence-transformers, all-MiniLM-L6-v2) is loaded once,
+in-process, at startup — no network calls, no LLM, no failure mode where
+the search degrades silently.
+"""
+
+import asyncio
+import heapq
+import json
+import math
+import random
+import re
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+from typing import Optional
+from urllib.parse import unquote
+
+import httpx
+import numpy as np
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from sentence_transformers import SentenceTransformer
+
+# Windows redirects stdout to cp1252 when it's not an interactive console
+# (e.g. piped to a log file), which raises on the arrow/emoji characters
+# used in log lines below and would otherwise crash mid-search.
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except Exception:
+    pass
+
+app = FastAPI()
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+# ── Embedding model: loaded once at startup, in-process ─────────────────────
+EMBED_MODEL_NAME = "all-MiniLM-L6-v2"
+_EMBED_MODEL: Optional[SentenceTransformer] = None
+
+@app.on_event("startup")
+async def _startup_embed_model():
+    global _EMBED_MODEL
+    print(f"[Embed] Loading sentence-transformers model '{EMBED_MODEL_NAME}'...")
+    _EMBED_MODEL = SentenceTransformer(EMBED_MODEL_NAME)
+    print(f"[Embed] Ready (dim={_EMBED_MODEL.get_embedding_dimension()})")
+
+WIKI_API = "https://en.wikipedia.org/w/api.php"
+
+MAX_FETCH          = 500   # max links fetched from Wikipedia (paginated)
+MAX_PAGES          = 6     # safety cap on pagination pages when hunting for a specific goal link
+MAX_HOPS           = 60    # search iteration limit
+TOP_DISPLAY        = 25    # max neighbours sent to frontend per step
+FRONTIER_DEPTH_2_K = 16    # how many depth-1 target neighbours to expand for depth-2 frontier
+
+EMBED_BATCH_SIZE   = 128   # in-process model batch size (no HTTP token limits to worry about)
+
+PRUNE_TOP_K        = 15    # keep this many candidates per expansion after scoring
+PRUNE_FLOOR        = 0.15  # hard floor on raw cosine-to-target; frontier members exempt
+
+FRONTIER_D1_BONUS  = 0.30  # candidate is a direct link of the target
+FRONTIER_D2_BONUS  = 0.10  # candidate is 2 hops from the target
+CAT_BONUS_WEIGHT   = 0.10  # max bonus for category-embedding alignment
+
+_THIS_DIR = Path(__file__).resolve().parent
+SEED_FILE = _THIS_DIR / "common_wiki_searches.txt"
+
+WIKI_HEADERS = {
+    "User-Agent": "Aurelius-WikiNavigator/6.0 (educational; contact@example.com)",
+    "Accept": "application/json",
+}
+
+def make_wiki_client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(headers=WIKI_HEADERS, follow_redirects=True,
+                             timeout=httpx.Timeout(25.0))
+
+
+# ══════════════════════════════════════════════════════════════
+# SEARCH STATS
+# ══════════════════════════════════════════════════════════════
+
+class SearchStats:
+    def __init__(self):
+        self.t0            = time.time()
+        self.nodes_visited = 0
+        self.nodes_pruned  = 0
+        self.embed_calls   = 0
+
+    def elapsed(self) -> float:
+        return round(time.time() - self.t0, 1)
+
+    def to_dict(self) -> dict:
+        return {
+            "nodes_visited": self.nodes_visited,
+            "nodes_pruned":  self.nodes_pruned,
+            "embed_calls":   self.embed_calls,
+            "elapsed_s":     self.elapsed(),
+        }
+
+
+# ══════════════════════════════════════════════════════════════
+# SESSION CACHES  (reset each search)
+# ══════════════════════════════════════════════════════════════
+
+_emb_cache: dict[str, np.ndarray] = {}   # title → embedding vector
+_dead_ends: set[str]              = set() # articles with 0 links
+
+def reset_session_caches():
+    global _emb_cache, _dead_ends
+    _emb_cache = {}
+    _dead_ends = set()
+
+
+# ══════════════════════════════════════════════════════════════
+# VECTOR MATH
+# ══════════════════════════════════════════════════════════════
+
+def cosine_similarity(a, b) -> float:
+    if a is None or b is None:
+        return 0.0
+    a = np.asarray(a, dtype=np.float32)
+    b = np.asarray(b, dtype=np.float32)
+    if a.size == 0 or b.size == 0:
+        return 0.0
+    na = np.linalg.norm(a)
+    nb = np.linalg.norm(b)
+    if na == 0 or nb == 0:
+        return 0.0
+    return float(np.dot(a, b) / (na * nb))
+
+
+# ══════════════════════════════════════════════════════════════
+# EMBEDDING  (in-process sentence-transformers, no network calls)
+# ══════════════════════════════════════════════════════════════
+
+async def batch_embed(texts: list[str], stats: SearchStats) -> list[np.ndarray]:
+    """
+    Embed texts via the in-process sentence-transformers model.
+    Results are cached per title across the session. Runs the (CPU-bound,
+    synchronous) encode call in a thread executor so it never blocks the
+    event loop — keeps pause/resume and other WS traffic responsive.
+    """
+    if not texts or _EMBED_MODEL is None:
+        return [np.array([]) for _ in texts]
+
+    uncached_idx  = [i for i, t in enumerate(texts) if t not in _emb_cache]
+    uncached_text = [texts[i] for i in uncached_idx]
+    if uncached_text:
+        loop = asyncio.get_event_loop()
+        embs = await loop.run_in_executor(
+            None,
+            lambda: _EMBED_MODEL.encode(
+                uncached_text, convert_to_numpy=True,
+                batch_size=EMBED_BATCH_SIZE, show_progress_bar=False,
+            ),
+        )
+        stats.embed_calls += 1
+        for orig_i, emb in zip(uncached_idx, embs):
+            _emb_cache[texts[orig_i]] = emb
+
+    return [_emb_cache.get(t, np.array([])) for t in texts]
+
+
+async def wiki_get(client: httpx.AsyncClient, params: dict, retries: int = 3) -> dict:
+    for attempt in range(retries + 1):
+        try:
+            r = await client.get(WIKI_API, params=params)
+            if r.status_code == 429:
+                await asyncio.sleep(min(2 ** attempt, 8)); continue
+            if r.status_code != 200:
+                return {}
+            return r.json()
+        except httpx.TimeoutException:
+            if attempt < retries: await asyncio.sleep(1)
+        except Exception as e:
+            print(f"[wiki] {e}"); return {}
+    return {}
+
+def extract_title_from_url(query: str) -> Optional[str]:
+    """If query is a Wikipedia URL, extract and decode the article title; else None."""
+    m = re.search(r'wikipedia\.org/wiki/([^#?\s]+)', query.strip())
+    if not m:
+        return None
+    return unquote(m.group(1)).replace('_', ' ').strip()
+
+async def resolve_article_title(client: httpx.AsyncClient, query: str) -> Optional[str]:
+    query = query.strip()
+    url_t = extract_title_from_url(query)
+    if url_t: query = url_t
+
+    data = await wiki_get(client, {"action":"query","titles":query,
+                                   "redirects":1,"format":"json","utf8":1})
+    for pid, page in data.get("query",{}).get("pages",{}).items():
+        if pid != "-1":
+            print(f"[resolve] Exact ✓ '{page['title']}'")
+            return page["title"]
+
+    data = await wiki_get(client, {"action":"opensearch","search":query,
+                                   "limit":10,"namespace":0,"format":"json","utf8":1})
+    titles = data[1] if isinstance(data, list) and len(data) > 1 else []
+    if titles:
+        for t in titles:
+            if t.lower() == query.lower(): return t
+        return titles[0]
+
+    data = await wiki_get(client, {"action":"query","list":"search","srsearch":query,
+                                   "srlimit":5,"srprop":"title","format":"json","utf8":1})
+    results = data.get("query",{}).get("search",[])
+    if results:
+        return results[0]["title"]
+    return None
+
+_DATE_RE = re.compile(
+    r'^\d{1,2} \w+$|^\w+ \d{1,2}$|^\d{4}$|^\d{4} in '
+    r'|^\d{1,2}\w* century'
+    r'|^(January|February|March|April|May|June|July|August|'
+    r'September|October|November|December)$'
+    r'|^\d{4}[-–]\d{2,4}$', re.IGNORECASE
+)
+def _is_date(t: str) -> bool:
+    return bool(_DATE_RE.search(t))
+
+_JUNK_TITLES = frozenset({
+    "Wayback Machine", "OCLC", "Digital object identifier", "CrossRef",
+    "JSTOR", "PubMed", "PubMed Central", "Semantic Scholar", "ArXiv",
+    "Bibcode", "CiteSeerX", "S2CID", "Zbl", "MR", "PMC",
+})
+def _is_junk(t: str) -> bool:
+    """Bibliographic citation artifacts: dead ends with 1-3 links each."""
+    return t.endswith("(identifier)") or t in _JUNK_TITLES
+
+async def get_all_links(client: httpx.AsyncClient, title: str,
+                        end_title: str = "",
+                        target_neighbours: set | None = None) -> list[str]:
+    """
+    Fetch ALL links via pagination (up to MAX_FETCH).
+    Goal link is always included first if found.
+    Target neighbours always get priority slots.
+    Date/year stubs filtered unless list would be empty.
+
+    BUGFIX: when hunting for end_title, the old exit condition
+    (len(all_links) >= MAX_FETCH) stopped pagination after roughly the
+    first alphabetical page of a large article, so a goal link sorting
+    late in the alphabet (e.g. "Pakistan" on India's 1000+-link page)
+    was never found even though it's a direct 1-hop link. We now keep
+    paginating past MAX_FETCH while specifically searching for a goal,
+    bounded by MAX_PAGES as a safety cap. Calls with no end_title (e.g.
+    pre-seeding target neighbours) are unaffected — same stop condition
+    as before.
+    """
+    all_links:  list[str] = []
+    date_links: list[str] = []
+    goal_link:  str | None = None
+    end_lower = end_title.lower() if end_title else ""
+    params = {
+        "action": "query", "titles": title, "prop": "links",
+        "pllimit": 500, "plnamespace": 0, "format": "json", "utf8": 1,
+    }
+    pages_fetched = 0
+    while True:
+        data = await wiki_get(client, params)
+        pages_fetched += 1
+        for page in data.get("query", {}).get("pages", {}).values():
+            for link in page.get("links", []):
+                t = link["title"]
+                if end_lower and t.lower() == end_lower:
+                    goal_link = t; continue
+                if _is_junk(t):
+                    continue
+                if _is_date(t):
+                    date_links.append(t)
+                else:
+                    all_links.append(t)
+        cont = data.get("continue", {})
+        if "plcontinue" not in cont:
+            break
+        if goal_link:
+            break   # found it — no need to keep paginating
+        if end_lower:
+            # Actively hunting a specific goal: keep going past MAX_FETCH,
+            # bounded only by MAX_PAGES (safety cap on API calls).
+            if pages_fetched >= MAX_PAGES:
+                break
+        else:
+            # No specific goal (e.g. pre-seeding neighbours): original behavior.
+            if len(all_links) + len(date_links) >= MAX_FETCH:
+                break
+        params["plcontinue"] = cont["plcontinue"]
+
+    result: list[str] = []
+    if goal_link:
+        result.append(goal_link)
+
+    tn = target_neighbours or set()
+    bridges = [l for l in all_links if l in tn]
+    rest    = [l for l in all_links if l not in tn]
+    result += bridges
+    result += rest
+    if len(result) < 5:
+        result += date_links[:max(0, 5 - len(result))]
+
+    return result[:MAX_FETCH]
+
+async def get_backlinks(client: httpx.AsyncClient, title: str,
+                        limit: int = MAX_FETCH) -> list[str]:
+    """
+    Fetch articles that link TO `title` (Wikipedia prop=linkshere) — the
+    correct direction for a forward-search bridge set.
+
+    get_all_links() returns what `title` points to. That is NOT useful as
+    a "one hop from target" bridge set, because Wikipedia links are not
+    reciprocal: target -> A does not imply A -> target. A backlink (B ->
+    target) is a guaranteed bridge — if the forward search ever reaches B,
+    expanding it is certain to find `target` in B's own outbound links.
+    Using outbound links here was sending the search on real-but-useless
+    detours (e.g. the "Star Wars" article links to "Star Destroyer", which
+    in turn links to real-world "Capital ship"/"Destroyer" articles for
+    etymology — those score high on the old outbound-based frontier but
+    don't link back to anything Star Wars-related themselves).
+    """
+    all_links:  list[str] = []
+    date_links: list[str] = []
+    params = {
+        "action": "query", "titles": title, "prop": "linkshere",
+        "lhlimit": 500, "lhnamespace": 0, "format": "json", "utf8": 1,
+    }
+    pages_fetched = 0
+    while True:
+        data = await wiki_get(client, params)
+        pages_fetched += 1
+        for page in data.get("query", {}).get("pages", {}).values():
+            for link in page.get("linkshere", []):
+                t = link["title"]
+                if _is_junk(t):
+                    continue
+                if _is_date(t):
+                    date_links.append(t)
+                else:
+                    all_links.append(t)
+        cont = data.get("continue", {})
+        if "lhcontinue" not in cont:
+            break
+        if len(all_links) + len(date_links) >= limit or pages_fetched >= MAX_PAGES:
+            break
+        params["lhcontinue"] = cont["lhcontinue"]
+    return (all_links + date_links)[:limit]
+
+async def get_article_summary(client: httpx.AsyncClient, title: str) -> str:
+    data = await wiki_get(client, {"action":"query","titles":title,"prop":"extracts",
+                                   "exintro":True,"explaintext":True,
+                                   "exsentences":2,"format":"json","utf8":1})
+    for page in data.get("query",{}).get("pages",{}).values():
+        return page.get("extract","")[:220]
+    return ""
+
+async def get_target_categories(client: httpx.AsyncClient, title: str) -> list[str]:
+    """Fetch human-readable categories for the target article."""
+    data = await wiki_get(client, {
+        "action": "query", "titles": title, "prop": "categories",
+        "cllimit": 20, "clshow": "!hidden", "format": "json", "utf8": 1,
+    })
+    cats = []
+    for page in data.get("query", {}).get("pages", {}).values():
+        for c in page.get("categories", []):
+            # Strip "Category:" prefix
+            name = re.sub(r"^Category:", "", c["title"]).strip()
+            cats.append(name)
+    return cats
+
+
+def _load_seed_titles() -> list[str]:
+    """Read the curated topic list used by the Random button, one title per line."""
+    if not SEED_FILE.exists():
+        return []
+    with open(SEED_FILE, "r", encoding="utf-8") as f:
+        return [line.strip() for line in f if line.strip()]
+
+
+# ══════════════════════════════════════════════════════════════
+# SEARCH ENGINE — greedy best-first, embeddings + graph only
+# ══════════════════════════════════════════════════════════════
+
+class AStarNavigator:
+    def __init__(self, start: str, end: str, ws: WebSocket):
+        self.start   = start
+        self.end     = end
+        self.ws      = ws
+        self.stats   = SearchStats()
+        self._paused = False
+
+        self.g_score:   dict[str, float]         = defaultdict(lambda: math.inf)
+        self.came_from: dict[str, Optional[str]] = {}
+        self.h_cache:   dict[str, float]         = {}
+        self.open_heap: list[tuple]              = []
+        self.open_set:  set[str]                = set()
+        self.closed_set:set[str]                = set()
+
+        self.cats_target:        list[str]        = []
+        self.cat_embeddings:     list[np.ndarray]  = []
+        self._target_neighbours: set[str]         = set()
+        self._frontier: dict[str, int]           = {}  # title → distance from target (1 or 2)
+        self.target_embedding:   Optional[np.ndarray] = None
+        self._target_cosine:     dict[str, float]      = {}  # raw cosine-to-target, used by prune floor
+
+
+    async def send(self, event: str, data: dict):
+        try:
+            await self.ws.send_text(json.dumps({"event": event, **data}))
+        except Exception:
+            pass
+
+    def reconstruct_path(self, current: str) -> list[str]:
+        path = [current]
+        while current in self.came_from and self.came_from[current] is not None:
+            current = self.came_from[current]
+            path.append(current)
+        return list(reversed(path))
+
+    # ── CORE SCORING PIPELINE ─────────────────────────────────────────────────
+    async def _rank_candidates(self, candidates: list[str]) -> dict[str, float]:
+        """
+        score(candidate) =
+              cosine(candidate_emb, target_emb)              # primary signal
+            + 0.30 if candidate backlinks the target directly else 0
+            + 0.10 if candidate is one hop further out (depth-2) else 0
+            + 0.10 * max(cosine(candidate_emb, category_emb_i))
+
+        Raw target cosine is stashed in self._target_cosine for the prune
+        floor — bonuses should not be able to rescue a semantically
+        unrelated candidate, only break ties among related ones.
+        """
+        if not candidates:
+            return {}
+
+        need_embed = [t for t in candidates if t not in _emb_cache]
+        if need_embed:
+            await batch_embed(need_embed, self.stats)
+
+        combined: dict[str, float] = {}
+        for t in candidates:
+            emb = _emb_cache.get(t)
+            s_target = cosine_similarity(emb, self.target_embedding)
+            self._target_cosine[t] = s_target
+
+            fd = self._frontier.get(t)
+            frontier_bonus = FRONTIER_D1_BONUS if fd == 1 else FRONTIER_D2_BONUS if fd == 2 else 0.0
+
+            cat_bonus = 0.0
+            if self.cat_embeddings and emb is not None and emb.size:
+                cat_sim = max(cosine_similarity(emb, ce) for ce in self.cat_embeddings)
+                cat_bonus = cat_sim * CAT_BONUS_WEIGHT
+
+            combined[t] = min(0.99, s_target + frontier_bonus + cat_bonus)
+
+        return combined
+
+    async def _prune(self, pool: list[str],
+                     scores: dict[str, float]) -> tuple[list[str], int]:
+        """
+        Sort by combined score, keep the top PRUNE_TOP_K, then drop any of
+        those below the raw-cosine floor (frontier members exempt — being
+        one or two links from the target is itself strong evidence).
+        """
+        if not scores:
+            return pool, 0
+
+        ranked = sorted(pool, key=lambda t: -scores.get(t, 0.0))
+        top    = ranked[:PRUNE_TOP_K]
+
+        survivors: list[str] = []
+        for t in top:
+            raw = self._target_cosine.get(t, 0.0)
+            if t in self._frontier or raw >= PRUNE_FLOOR:
+                survivors.append(t)
+            else:
+                self.h_cache[t] = 0.95
+
+        pruned = len(pool) - len(survivors)
+        self.stats.nodes_pruned += pruned
+        print(f"[Prune] {pruned}/{len(pool)} pruned, {len(survivors)} kept")
+        return survivors, pruned
+
+    # ── RUN ───────────────────────────────────────────────────────────────────
+    async def run(self):
+        reset_session_caches()
+
+        async with make_wiki_client() as client:
+
+            # ── 1. Resolve titles ─────────────────────────────────────────
+            await self.send("status", {"message": f"Resolving '{self.start}'..."})
+            start_title = await resolve_article_title(client, self.start)
+            if not start_title:
+                await self.send("error", {"message": f"Cannot find: '{self.start}'"}); return
+
+            await self.send("status", {"message": f"Resolving '{self.end}'..."})
+            end_title = await resolve_article_title(client, self.end)
+            if not end_title:
+                await self.send("error", {"message": f"Cannot find: '{self.end}'"}); return
+
+            await self.send("resolved", {"start": start_title, "end": end_title})
+            self.end = end_title
+
+            # ── 2. Target embedding  ──────────────────────────────────────
+            await self.send("status", {"message": "Embedding target article..."})
+            te = await batch_embed([end_title], self.stats)
+            if te and te[0] is not None and te[0].size:
+                self.target_embedding = te[0]
+                _emb_cache[end_title] = te[0]
+                print(f"[Embed] Target dim={te[0].shape[0]}")
+
+            # ── 3. Target categories + their embeddings ───────────────────
+            await self.send("status", {"message": "Fetching target article categories..."})
+            self.cats_target = await get_target_categories(client, end_title)
+            print(f"[init] Target categories: {self.cats_target[:6]}")
+            if self.cats_target:
+                cat_embs = await batch_embed(self.cats_target, self.stats)
+                self.cat_embeddings = [e for e in cat_embs if e is not None and e.size]
+
+            # ── 4. Pre-seed: target frontier depth-1 ───────────────────────
+            # Backlinks (who links TO the target), not outbound links — see
+            # get_backlinks() docstring for why this direction matters.
+            await self.send("status", {"message": "Pre-loading target backlinks..."})
+            target_nb = await get_backlinks(client, end_title)
+            self._target_neighbours = set(target_nb)
+            for tn in self._target_neighbours:
+                self._frontier[tn] = 1
+            print(f"[init] Target has {len(self._target_neighbours)} backlinks")
+
+            # ── 4b. Bidirectional-style frontier: depth-2 expansion ────────
+            # For a sample of depth-1 bridges, fetch THEIR backlinks too:
+            # X -> A -> target, where A is a depth-1 bridge. Reaching X
+            # guarantees a path through A to the target.
+            await self.send("status", {"message": "Expanding target frontier (depth 2)..."})
+            d2_sample = [t for t in target_nb if not _is_date(t)][:FRONTIER_DEPTH_2_K]
+            d2_results = await asyncio.gather(
+                *[get_backlinks(client, nb_title) for nb_title in d2_sample]
+            )
+            d2_count = 0
+            for nb_links in d2_results:
+                for t in nb_links:
+                    if t not in self._frontier and not _is_date(t):
+                        self._frontier[t] = 2
+                        d2_count += 1
+            print(f"[Frontier] Total: {len(self._frontier)} "
+                  f"(depth-1: {len(self._target_neighbours)}, depth-2: {d2_count})")
+
+            # ── 5. Init search ────────────────────────────────────────────
+            self.g_score[start_title] = 0
+            se = await batch_embed([start_title], self.stats)
+            if se and se[0] is not None and se[0].size and self.target_embedding is not None:
+                h0 = max(0.01, 1.0 - cosine_similarity(se[0], self.target_embedding))
+            else:
+                h0 = 0.9
+            self.h_cache[start_title] = h0
+            heapq.heappush(self.open_heap, (h0, 0, start_title))
+            self.open_set.add(start_title)
+
+            summary = await get_article_summary(client, start_title)
+            await self.send("node_add", {
+                "id": start_title, "g": 0, "h": round(h0,3), "f": round(h0,3),
+                "summary": summary, "state": "open",
+                "is_start": True, "is_end": False,
+            })
+            await self.send("node_add", {
+                "id": end_title, "g": None, "h": 0.0, "f": None,
+                "summary": "", "state": "target",
+                "is_start": False, "is_end": True,
+            })
+
+            step = 0
+
+            # ── 6. Greedy best-first search loop ─────────────────────────
+            while self.open_heap and step < MAX_HOPS * 30:
+
+                while self._paused:
+                    await asyncio.sleep(0.3)
+
+                if not self.open_heap:
+                    break
+                h_curr, g_curr, current = heapq.heappop(self.open_heap)
+                f_curr = g_curr + h_curr  # for display only
+                self.open_set.discard(current)
+
+                if current in self.closed_set:
+                    continue
+
+                step += 1
+                self.stats.nodes_visited += 1
+
+                await self.send("expand_node", {
+                    "id":          current,
+                    "g":           g_curr,
+                    "h":           round(h_curr, 3),
+                    "f":           round(f_curr, 3),
+                    "path_so_far": self.reconstruct_path(current),
+                    "step":        step,
+                    "stats":       self.stats.to_dict(),
+                })
+
+                # Goal check
+                if current.lower() == end_title.lower():
+                    path = self.reconstruct_path(current)
+                    await self.send("found", {
+                        "path": path, "steps": step,
+                        "total_hops": len(path)-1,
+                        "stats": self.stats.to_dict(),
+                    })
+                    return
+
+                self.closed_set.add(current)
+                await self.send("node_state", {"id": current, "state": "closed"})
+
+                # ── Fetch ALL links ───────────────────────────────────────
+                await self.send("status", {"message": f"Fetching links: '{current}'..."})
+                neighbours = await get_all_links(
+                    client, current,
+                    end_title=end_title,
+                    target_neighbours=self._target_neighbours,
+                )
+                print(f"[Search] step {step}: '{current}' → {len(neighbours)} links")
+
+                if not neighbours:
+                    _dead_ends.add(current)
+                    continue
+
+                # Immediate win
+                if end_title in neighbours:
+                    self.came_from[end_title] = current
+                    self.g_score[end_title]   = g_curr + 1
+                    path = self.reconstruct_path(end_title)
+                    print(f"[Search] Direct hit: '{current}' → '{end_title}'")
+                    await self.send("found", {
+                        "path": path, "steps": step,
+                        "total_hops": len(path)-1,
+                        "stats": self.stats.to_dict(),
+                    })
+                    return
+
+                # Filter closed + dead-ends
+                candidates = [
+                    nb for nb in neighbours
+                    if nb not in self.closed_set and nb not in _dead_ends
+                ]
+
+                # ── Embed + score pipeline ────────────────────────────────
+                await self.send("status", {"message": f"Ranking links for '{current}'..."})
+                scores = await self._rank_candidates(candidates)
+
+                # ── Prune ─────────────────────────────────────────────────
+                pool = list(scores.keys())
+                survivors, _ = await self._prune(pool, scores)
+
+                # ── Push to heap ──────────────────────────────────────────
+                new_nodes = []
+                for nb in survivors:
+                    if nb in self.closed_set:
+                        continue
+                    sc      = scores.get(nb, 0.05)
+                    h_nb    = max(0.01, 1.0 - sc)
+                    self.h_cache[nb] = h_nb
+                    tent_g  = g_curr + 1
+                    if tent_g < self.g_score[nb]:
+                        self.came_from[nb] = current
+                        self.g_score[nb]   = tent_g
+                        # Greedy best-first: heap priority = h only (not g+h).
+                        # This commits to the most promising direction without
+                        # penalising depth — Wikipedia paths are short (3-7
+                        # hops) and depth is not a useful cost signal here.
+                        heapq.heappush(self.open_heap, (h_nb, tent_g, nb))
+                        self.open_set.add(nb)
+                        is_end = nb.lower() == end_title.lower()
+                        new_nodes.append({
+                            "id": nb, "g": tent_g,
+                            "h": round(h_nb, 3), "f": round(tent_g + h_nb, 3),
+                            "state": "target" if is_end else "open",
+                            "is_end": is_end, "parent": current,
+                        })
+
+                display_nodes = new_nodes[:TOP_DISPLAY]
+                display_edges = [{"from": current, "to": n["id"]} for n in display_nodes]
+                if display_nodes:
+                    await self.send("neighbours", {
+                        "centre": current,
+                        "nodes":  display_nodes,
+                        "edges":  display_edges,
+                    })
+                    await asyncio.sleep(0.01)
+
+            await self.send("not_found", {
+                "message": f"No path found within {MAX_HOPS} hops.",
+                "visited": list(self.closed_set),
+                "stats":   self.stats.to_dict(),
+            })
+
+
+# ══════════════════════════════════════════════════════════════
+# REST endpoints (autocomplete lives entirely on the frontend now —
+# it calls Wikipedia's opensearch API directly)
+# ══════════════════════════════════════════════════════════════
+
+@app.get("/api/random")
+async def api_random():
+    """
+    Powers the "Random" button on the start screen. Picks two distinct
+    topics from the curated seed list (common_wiki_searches.txt) — NOT a
+    fully random Wikipedia page — so the search always gets a
+    well-connected pair of articles to find a path between.
+    """
+    titles = _load_seed_titles()
+    if len(titles) < 2:
+        return {"start": "Google", "end": "Mohali"}
+    start, end = random.sample(titles, 2)
+    return {"start": start, "end": end}
+
+
+@app.get("/api/health")
+async def api_health():
+    """
+    Polled by the frontend's loading screen on first load. Since FastAPI
+    does not accept connections until the startup handler (which loads the
+    embedding model) finishes, a successful response here already implies
+    the model is ready — there is nothing further to check.
+    """
+    return {"status": "ready"}
+
+
+# ══════════════════════════════════════════════════════════════
+# WebSocket endpoint
+# ══════════════════════════════════════════════════════════════
+
+@app.websocket("/ws")
+async def websocket_endpoint(ws: WebSocket):
+    await ws.accept()
+    navigator: Optional[AStarNavigator] = None
+    try:
+        raw  = await ws.receive_text()
+        data = json.loads(raw)
+        if "control" in data:
+            return
+
+        start = data.get("start", "").strip()
+        end   = data.get("end",   "").strip()
+        print(f"\n{'='*60}\n[WS] '{start}' → '{end}'\n{'='*60}")
+        if not start or not end:
+            await ws.send_text(json.dumps({"event":"error","message":"Need start and end."}))
+            return
+
+        navigator = AStarNavigator(start, end, ws)
+
+        async def listen_controls():
+            while True:
+                try:
+                    msg  = await asyncio.wait_for(ws.receive_text(), timeout=0.5)
+                    ctrl = json.loads(msg)
+                    if navigator:
+                        if ctrl.get("control") == "pause":
+                            navigator._paused = True;  print("[WS] Paused")
+                        elif ctrl.get("control") == "resume":
+                            navigator._paused = False; print("[WS] Resumed")
+                except asyncio.TimeoutError:
+                    pass
+                except Exception:
+                    break
+
+        ctrl_task   = asyncio.create_task(listen_controls())
+        search_task = asyncio.create_task(navigator.run())
+        done, pending = await asyncio.wait(
+            [ctrl_task, search_task], return_when=asyncio.FIRST_COMPLETED
+        )
+        for t in pending:
+            t.cancel()
+
+    except WebSocketDisconnect:
+        print("[WS] disconnected")
+    except Exception as e:
+        print(f"[WS] {e}")
+        try:
+            await ws.send_text(json.dumps({"event":"error","message":str(e)}))
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("\n🌐 Aurelius backend → http://localhost:8000")
+    print("   Open index.html in your browser\n")
+    uvicorn.run(app, host="0.0.0.0", port=8000, log_level="warning")

requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.110
+uvicorn[standard]>=0.29
+httpx>=0.27
+numpy>=1.26
+sentence-transformers>=3.0

search.py

@@ -0,0 +1,569 @@
+"""
+Aurelius — search engine: greedy best-first, embeddings + graph only.
+
+Architect plan: Honest Bidirectional Meeting-Check Rewrite. Replaces the
+prior stagnation-detection + frontier-jump escape valve (which fabricated
+a came_from pointer with no real Wikipedia link behind it — see the
+Marcus Aurelius -> A* search algorithm incident, where the jump landed on
+a node that doesn't even link to the target) with an honest mechanism:
+
+  The target's backlinks (depth-1) are real reverse edges: for every
+  F in that set, F -> target exists by construction (Wikipedia's own
+  linkshere index). The forward search now treats this set as its actual
+  goal zone (~100+ members, not one node) instead of just a score hint.
+  The moment the forward search expands a node whose real neighbour set
+  intersects this zone, current -> F -> target is a fully real two-edge
+  bridge — no teleportation, no invented edges.
+
+  A permanent regression fence (_real_edges / _validate_path /
+  _emit_found) refuses to emit any path containing an edge that wasn't
+  observed as a real Wikipedia link, so a future change can't silently
+  reintroduce a fabricated path.
+
+  Removed entirely: stagnation detection, frontier-jump, the depth-2
+  frontier (couldn't be stitched into a real path without bridge
+  bookkeeping it never had), and the category-embedding bonus (capped at
+  +0.10, applied weakly everywhere, did not prevent the failure case that
+  motivated the jump in the first place).
+
+Semantic Drift fix: a later investigation found a path that LOOKED
+fabricated ('Anu' -> 'Iteration' with no visible link on the rendered
+page) but verified real against the live API — it's a piped wikilink
+[[Iteration|iterative]] in a sentence about deity-name etymology, invisible
+to a manual page read but a genuine edge. The actual problem was that the
+search wandered through several pages (Egyptian/Mesopotamian deities) with
+no real relevance to the target before reaching it. Root cause: candidates
+were embedded as bare titles, and a short ambiguous proper noun carries no
+domain signal for the model to score against. Fixed two ways: (1) every
+candidate is now embedded as "{title}. {wikidata_short_desc}" instead of a
+bare title — see wiki.py's get_all_links() and _rank_candidates() below —
+so "Anu. Mesopotamian sky-god" scores clearly far from the target instead
+of landing in noisy title-only cosine; (2) heap priority is now
+h + DEPTH_TIEBREAK_EPSILON*g instead of pure h (config.py), a deliberate,
+documented reversal of the original no-g-cost design — pure-greedy let one
+noisy candidate drag the search arbitrarily deep into its cluster with no
+incentive to prefer a shallower alternative. The depth penalty is small
+enough (max 0.6 at MAX_HOPS=60) that it only breaks ties/near-ties.
+"""
+
+import asyncio
+import heapq
+import json
+import math
+import time
+from collections import defaultdict
+from typing import Optional
+
+import httpx
+import numpy as np
+from fastapi import WebSocket
+
+from config import (
+    MAX_HOPS, TOP_DISPLAY,
+    PRUNE_TOP_K, PRUNE_FLOOR, PRUNE_MIN_SURVIVORS,
+    FRONTIER_D1_BONUS, FRONTIER_D2_BONUS,
+    DEPTH_TIEBREAK_EPSILON,
+    GOAL_ZONE_EXPAND_INTERVAL, GOAL_ZONE_EXPAND_BATCH,
+    GOAL_ZONE_D2_BACKLINK_LIMIT,
+    STAGNATION_WINDOW, STAGNATION_DELTA, PRUNE_TOP_K_STAGNANT,
+    DIVERSITY_WEIGHT,
+)
+from embedding import batch_embed, cosine_similarity, reset_session_caches
+import embedding as _embedding_mod
+# NOTE: the embedding cache and dead-ends set are accessed as
+# _embedding_mod._emb_cache / _embedding_mod._dead_ends (module-qualified),
+# never imported by name. reset_session_caches() REBINDS both names inside
+# the embedding module to fresh dict/set objects on every search — a
+# `from embedding import _emb_cache` here would capture the OLD object at
+# import time and silently go stale after the first reset.
+from wiki import (
+    make_wiki_client, resolve_article_title, get_all_links, get_backlinks,
+    get_article_summary, check_disambiguation, get_link_display_text, _is_date,
+)
+
+
+# ══════════════════════════════════════════════════════════════
+# SEARCH STATS
+# ══════════════════════════════════════════════════════════════
+
+class SearchStats:
+    def __init__(self):
+        self.t0            = time.time()
+        self.nodes_visited = 0
+        self.nodes_pruned  = 0
+        self.embed_calls   = 0
+
+    def elapsed(self) -> float:
+        return round(time.time() - self.t0, 1)
+
+    def to_dict(self) -> dict:
+        return {
+            "nodes_visited": self.nodes_visited,
+            "nodes_pruned":  self.nodes_pruned,
+            "embed_calls":   self.embed_calls,
+            "elapsed_s":     self.elapsed(),
+        }
+
+
+# ═════════════════��════════════════════════════════════════════
+# SEARCH ENGINE — greedy best-first, embeddings + graph only
+# ══════════════════════════════════════════════════════════════
+
+class AStarNavigator:
+    def __init__(self, start: str, end: str, ws: WebSocket):
+        self.start   = start
+        self.end     = end
+        self.ws      = ws
+        self.stats   = SearchStats()
+        self._paused = False
+
+        self.g_score:   dict[str, float]         = defaultdict(lambda: math.inf)
+        self.came_from: dict[str, Optional[str]] = {}
+        self.h_cache:   dict[str, float]         = {}
+        self.open_heap: list[tuple]              = []
+        self.open_set:  set[str]                = set()
+        self.closed_set:set[str]                = set()
+
+        # Goal zone: depth-1 and depth-2 backlinks of the target.
+        # d1: F -> target is a real edge (Wikipedia's linkshere index).
+        # d2: d2_node -> d1_bridge is a real edge, so
+        #     current -> d2_node -> d1_bridge -> target is a 3-edge path.
+        self._goal_zone_d1: set[str]        = set()
+        self._goal_zone_d2: dict[str, str]  = {}   # d2_node -> d1_bridge
+        self._d1_expanded:  set[str]        = set()
+
+        self.target_embedding:   Optional[np.ndarray] = None
+        self._target_cosine:     dict[str, float]     = {}
+
+        self._short_desc: dict[str, str] = {}
+
+        # Stagnation detection / cluster escape
+        self._h_history: list[float] = []
+        self._recent_embeddings: list[np.ndarray] = []
+
+        # Permanent regression fence
+        self._real_edges: set[tuple[str, str]] = set()
+
+
+    async def send(self, event: str, data: dict):
+        try:
+            await self.ws.send_text(json.dumps({"event": event, **data}))
+        except Exception:
+            pass
+
+    def reconstruct_path(self, current: str) -> list[str]:
+        path = [current]
+        while current in self.came_from and self.came_from[current] is not None:
+            current = self.came_from[current]
+            path.append(current)
+        return list(reversed(path))
+
+    def _link(self, parent: str, child: str, g: float):
+        """
+        Record a came_from pointer AND the real edge backing it. This is
+        the only place came_from should ever be assigned — routing every
+        assignment through here is what makes _validate_path() a genuine
+        regression fence instead of a no-op.
+        """
+        self.came_from[child] = parent
+        self.g_score[child]   = g
+        self._real_edges.add((parent, child))
+
+    def _validate_path(self, path: list[str]) -> bool:
+        """
+        Regression fence: refuse to treat a path as valid unless every
+        consecutive pair was recorded by _link() as a real, observed
+        Wikipedia link. Guards against ever again emitting a path like
+        the Marcus Aurelius -> A* search algorithm one, where a removed
+        feature (frontier-jump) fabricated a came_from pointer with no
+        corresponding link.
+        """
+        return all(
+            (path[i], path[i + 1]) in self._real_edges
+            for i in range(len(path) - 1)
+        )
+
+    async def _emit_found(self, client: httpx.AsyncClient, end_node: str, step: int):
+        path = self.reconstruct_path(end_node)
+        if not self._validate_path(path):
+            print(f"[Guard] Rejected a path with a fabricated edge: {path}")
+            await self.send("not_found", {
+                "message": "Internal error: candidate path failed validation.",
+                "visited": list(self.closed_set),
+                "stats": self.stats.to_dict(),
+            })
+            return
+
+        # Best-effort: surface the actual piped display text per hop so a
+        # genuine-but-piped edge (e.g. "Western world" -[[Amber Road|routes]]->
+        # "Amber Road") doesn't look fabricated to someone Ctrl+F-ing the
+        # rendered page for the target's title. None entries (not piped, or
+        # not found in raw wikitext) are simply omitted by the frontend.
+        display_texts = await asyncio.gather(*(
+            get_link_display_text(client, path[i], path[i + 1])
+            for i in range(len(path) - 1)
+        ))
+
+        await self.send("found", {
+            "path": path, "steps": step,
+            "total_hops": len(path) - 1,
+            "stats": self.stats.to_dict(),
+            "display_texts": display_texts,
+        })
+
+    def _is_goal_zone(self, title: str) -> bool:
+        return title in self._goal_zone_d1 or title in self._goal_zone_d2
+
+    # ── CORE SCORING PIPELINE ─────────────────────────────────────────────────
+    async def _rank_candidates(self, candidates: list[str],
+                               is_stagnant: bool = False) -> dict[str, float]:
+        if not candidates:
+            return {}
+
+        need_embed = [t for t in candidates if t not in _embedding_mod._emb_cache]
+        if need_embed:
+            embed_texts = [
+                f"{t}. {self._short_desc[t]}" if t in self._short_desc else t
+                for t in need_embed
+            ]
+            await batch_embed(need_embed, self.stats, embed_texts=embed_texts)
+
+        centroid = None
+        if is_stagnant and self._recent_embeddings:
+            centroid = np.mean(self._recent_embeddings, axis=0)
+
+        combined: dict[str, float] = {}
+        for t in candidates:
+            emb = _embedding_mod._emb_cache.get(t)
+            s_target = cosine_similarity(emb, self.target_embedding)
+            self._target_cosine[t] = s_target
+
+            if t in self._goal_zone_d1:
+                frontier_bonus = FRONTIER_D1_BONUS
+            elif t in self._goal_zone_d2:
+                frontier_bonus = FRONTIER_D2_BONUS
+            else:
+                frontier_bonus = 0.0
+
+            diversity_bonus = 0.0
+            if is_stagnant and centroid is not None and emb is not None:
+                diversity_bonus = DIVERSITY_WEIGHT * (1.0 - cosine_similarity(emb, centroid))
+
+            combined[t] = min(0.99, s_target + frontier_bonus + diversity_bonus)
+
+        return combined
+
+    async def _prune(self, pool: list[str],
+                     scores: dict[str, float],
+                     is_stagnant: bool = False) -> tuple[list[str], int]:
+        if not scores:
+            return pool, 0
+
+        top_k = PRUNE_TOP_K_STAGNANT if is_stagnant else PRUNE_TOP_K
+        ranked = sorted(pool, key=lambda t: -scores.get(t, 0.0))
+        top    = ranked[:top_k]
+
+        survivors: list[str] = []
+        for i, t in enumerate(top):
+            raw = self._target_cosine.get(t, 0.0)
+            if i < PRUNE_MIN_SURVIVORS or self._is_goal_zone(t) or raw >= PRUNE_FLOOR:
+                survivors.append(t)
+            else:
+                self.h_cache[t] = 0.95
+
+        pruned = len(pool) - len(survivors)
+        self.stats.nodes_pruned += pruned
+        print(f"[Prune] {pruned}/{len(pool)} pruned, {len(survivors)} kept"
+              + (" (stagnant beam)" if is_stagnant else ""))
+        return survivors, pruned
+
+    # ── GOAL ZONE EXPANSION ─────────────────────────────────────────────────
+    async def _expand_goal_zone(self, client, end_title: str):
+        unexpanded = [m for m in self._goal_zone_d1 if m not in self._d1_expanded]
+        batch = unexpanded[:GOAL_ZONE_EXPAND_BATCH]
+        for d1_member in batch:
+            self._d1_expanded.add(d1_member)
+            d2_backlinks = await get_backlinks(client, d1_member,
+                                               limit=GOAL_ZONE_D2_BACKLINK_LIMIT)
+            for d2 in d2_backlinks:
+                if d2 not in self._goal_zone_d2 and d2 not in self._goal_zone_d1:
+                    self._goal_zone_d2[d2] = d1_member
+        if batch:
+            print(f"[GoalZone] Expanded: {len(self._goal_zone_d1)} d1 + "
+                  f"{len(self._goal_zone_d2)} d2 nodes")
+
+    # ── RUN ───────────────────────────────────────────────────────────────────
+    async def run(self):
+        reset_session_caches()
+
+        async with make_wiki_client() as client:
+
+            # ── 1. Resolve titles ─────────────────────────────────────────
+            await self.send("status", {"message": f"Resolving '{self.start}'..."})
+            start_title = await resolve_article_title(client, self.start)
+            if not start_title:
+                await self.send("error", {"message": f"Cannot find: '{self.start}'"}); return
+
+            await self.send("status", {"message": f"Resolving '{self.end}'..."})
+            end_title = await resolve_article_title(client, self.end)
+            if not end_title:
+                await self.send("error", {"message": f"Cannot find: '{self.end}'"}); return
+
+            await self.send("resolved", {"start": start_title, "end": end_title})
+            self.end = end_title
+
+            # ── 1b. Disambiguation redirect ──────────────────────────────
+            is_disambig = await check_disambiguation(client, end_title)
+            if is_disambig:
+                await self.send("status", {"message": f"'{end_title}' is a disambiguation page, finding best match..."})
+                disambig_links, disambig_descs = await get_all_links(client, end_title)
+                if disambig_links:
+                    self._short_desc.update(disambig_descs)
+                    embed_texts_d = [
+                        f"{t}. {disambig_descs[t]}" if t in disambig_descs else t
+                        for t in disambig_links
+                    ]
+                    query_embs = await batch_embed(
+                        [self.end], self.stats,
+                        embed_texts=[self.end],
+                    )
+                    cand_embs = await batch_embed(
+                        disambig_links, self.stats,
+                        embed_texts=embed_texts_d,
+                    )
+                    if query_embs and query_embs[0] is not None:
+                        query_emb = query_embs[0]
+                        best_title, best_score = None, -1.0
+                        end_lower = self.end.lower()
+                        for i, t in enumerate(disambig_links):
+                            if cand_embs[i] is not None:
+                                sc = cosine_similarity(cand_embs[i], query_emb)
+                                if t.lower().startswith(end_lower):
+                                    sc += 0.25
+                                if sc > best_score:
+                                    best_score, best_title = sc, t
+                        if best_title:
+                            print(f"[Disambig] '{end_title}' → '{best_title}' (score={best_score:.3f})")
+                            end_title = best_title
+                            self.end = end_title
+                            await self.send("resolved", {"start": start_title, "end": end_title})
+
+            # ── 2. Target embedding  ──────────────────────────────────────
+            # Enriched with the article's lead extract (Semantic Drift fix):
+            # the target embedding is the cosine anchor for every score in
+            # the search, so its quality matters more than any single
+            # candidate's. A bare title gives the model nothing to work
+            # with for ambiguous/short titles; the extract gives it the
+            # actual subject matter.
+            await self.send("status", {"message": "Embedding target article..."})
+            target_extract = await get_article_summary(client, end_title)
+            te = await batch_embed(
+                [end_title], self.stats,
+                embed_texts=[f"{end_title}. {target_extract}" if target_extract else end_title],
+            )
+            if te and te[0] is not None and te[0].size:
+                self.target_embedding = te[0]
+                _embedding_mod._emb_cache[end_title] = te[0]
+                print(f"[Embed] Target dim={te[0].shape[0]}")
+
+            # ── 3. Pre-seed: target backlinks = the goal zone ──────────────
+            await self.send("status", {"message": "Pre-loading target backlinks..."})
+            target_nb = await get_backlinks(client, end_title)
+            self._goal_zone_d1 = set(target_nb)
+            print(f"[init] Target goal zone: {len(self._goal_zone_d1)} d1 backlinks")
+
+            # ── 4. Init search ────────────────────────────────────────────
+            # Same extract-enrichment as the target embedding above — the
+            # start node's h0 anchors every depth-tiebreak comparison for
+            # the rest of the search.
+            self.g_score[start_title] = 0
+            summary = await get_article_summary(client, start_title)
+            se = await batch_embed(
+                [start_title], self.stats,
+                embed_texts=[f"{start_title}. {summary}" if summary else start_title],
+            )
+            if se and se[0] is not None and se[0].size and self.target_embedding is not None:
+                h0 = max(0.01, 1.0 - cosine_similarity(se[0], self.target_embedding))
+            else:
+                h0 = 0.9
+            self.h_cache[start_title] = h0
+            heapq.heappush(self.open_heap, (h0, h0, 0, start_title))
+            self.open_set.add(start_title)
+
+            await self.send("node_add", {
+                "id": start_title, "g": 0, "h": round(h0,3), "f": round(h0,3),
+                "summary": summary, "state": "open",
+                "is_start": True, "is_end": False,
+            })
+            await self.send("node_add", {
+                "id": end_title, "g": None, "h": 0.0, "f": None,
+                "summary": "", "state": "target",
+                "is_start": False, "is_end": True,
+            })
+
+            step = 0
+
+            # ── 5. Greedy best-first search loop ─────────────────────────
+            while self.open_heap and step < MAX_HOPS:
+
+                while self._paused:
+                    await asyncio.sleep(0.3)
+
+                if not self.open_heap:
+                    break
+                _priority, h_curr, g_curr, current = heapq.heappop(self.open_heap)
+                f_curr = g_curr + h_curr  # for display only
+                self.open_set.discard(current)
+
+                if current in self.closed_set:
+                    continue
+
+                step += 1
+                self.stats.nodes_visited += 1
+
+                await self.send("expand_node", {
+                    "id":          current,
+                    "g":           g_curr,
+                    "h":           round(h_curr, 3),
+                    "f":           round(f_curr, 3),
+                    "path_so_far": self.reconstruct_path(current),
+                    "step":        step,
+                    "stats":       self.stats.to_dict(),
+                })
+
+                # Goal check
+                if current.lower() == end_title.lower():
+                    await self._emit_found(client, current, step)
+                    return
+
+                self.closed_set.add(current)
+                await self.send("node_state", {"id": current, "state": "closed"})
+
+                # ── Periodic goal-zone expansion ──────────────────────────
+                if step > 0 and step % GOAL_ZONE_EXPAND_INTERVAL == 0:
+                    await self._expand_goal_zone(client, end_title)
+
+                # ── Fetch ALL links ───────────────────────────────────────
+                await self.send("status", {"message": f"Fetching links: '{current}'..."})
+                neighbours, short_desc = await get_all_links(
+                    client, current,
+                    end_title=end_title,
+                    target_neighbours=self._goal_zone_d1,
+                )
+                self._short_desc.update(short_desc)
+                print(f"[Search] step {step}: '{current}' → {len(neighbours)} links")
+
+                if not neighbours:
+                    _embedding_mod._dead_ends.add(current)
+                    continue
+
+                # Immediate win: current links directly to the target.
+                if end_title in neighbours:
+                    self._link(current, end_title, g_curr + 1)
+                    print(f"[Search] Direct hit: '{current}' → '{end_title}'")
+                    await self._emit_found(client, end_title, step)
+                    return
+
+                # D1 meeting check
+                bridge = next(
+                    (nb for nb in neighbours if nb in self._goal_zone_d1), None
+                )
+                if bridge:
+                    self._link(current, bridge, g_curr + 1)
+                    self._link(bridge, end_title, g_curr + 2)
+                    print(f"[Search] Meeting d1: '{current}' → '{bridge}' → '{end_title}'")
+                    await self._emit_found(client, end_title, step)
+                    return
+
+                # D2 meeting check
+                d2_bridge = next(
+                    (nb for nb in neighbours if nb in self._goal_zone_d2), None
+                )
+                if d2_bridge:
+                    d1_bridge = self._goal_zone_d2[d2_bridge]
+                    self._link(current, d2_bridge, g_curr + 1)
+                    self._link(d2_bridge, d1_bridge, g_curr + 2)
+                    self._link(d1_bridge, end_title, g_curr + 3)
+                    print(f"[Search] Meeting d2: '{current}' → '{d2_bridge}' → '{d1_bridge}' → '{end_title}'")
+                    await self._emit_found(client, end_title, step)
+                    return
+
+                # Filter closed + dead-ends
+                candidates = [
+                    nb for nb in neighbours
+                    if nb not in self.closed_set and nb not in _embedding_mod._dead_ends
+                ]
+
+                # ── Stagnation detection ──────────────────────────────────
+                is_stagnant = False
+                if len(self._h_history) >= 2 * STAGNATION_WINDOW:
+                    recent_best = min(self._h_history[-STAGNATION_WINDOW:])
+                    prev_best = min(self._h_history[-2*STAGNATION_WINDOW:-STAGNATION_WINDOW])
+                    is_stagnant = (prev_best - recent_best) < STAGNATION_DELTA
+                    if is_stagnant:
+                        print(f"[Stagnation] Detected at step {step}, widening beam")
+
+                # ── Embed + score pipeline ────────────────────────────────
+                await self.send("status", {"message": f"Ranking links for '{current}'..."})
+                scores = await self._rank_candidates(candidates, is_stagnant=is_stagnant)
+
+                # Track h-history and cluster centroid
+                if scores:
+                    best_h = min(max(0.01, 1.0 - sc) for sc in scores.values())
+                    self._h_history.append(best_h)
+                current_emb = _embedding_mod._emb_cache.get(current)
+                if current_emb is not None:
+                    self._recent_embeddings.append(current_emb)
+                    if len(self._recent_embeddings) > STAGNATION_WINDOW:
+                        self._recent_embeddings.pop(0)
+
+                # ── Prune ─────────────────────────────────────────────────
+                pool = list(scores.keys())
+                survivors, _ = await self._prune(pool, scores, is_stagnant=is_stagnant)
+
+                # ── Push to heap ──────────────────────────────────────────
+                new_nodes = []
+                for nb in survivors:
+                    if nb in self.closed_set:
+                        continue
+                    sc      = scores.get(nb, 0.05)
+                    h_nb    = max(0.01, 1.0 - sc)
+                    self.h_cache[nb] = h_nb
+                    tent_g  = g_curr + 1
+                    if tent_g < self.g_score[nb]:
+                        self._link(current, nb, tent_g)
+                        # Greedy best-first with a small depth tie-breaker
+                        # (Semantic Drift fix — deliberate reversal of the
+                        # prior "heap priority = h only" design, see
+                        # config.py's DEPTH_TIEBREAK_EPSILON and CLAUDE.md):
+                        # pure-h let one noisy high-scoring proper noun drag
+                        # the search arbitrarily deep into its cluster, with
+                        # nothing to prefer a shallower alternative once it
+                        # committed. h_nb is still kept as the true heuristic
+                        # for display/h_cache — only heap ordering changes.
+                        priority = h_nb + DEPTH_TIEBREAK_EPSILON * tent_g
+                        heapq.heappush(self.open_heap, (priority, h_nb, tent_g, nb))
+                        self.open_set.add(nb)
+                        is_end = nb.lower() == end_title.lower()
+                        new_nodes.append({
+                            "id": nb, "g": tent_g,
+                            "h": round(h_nb, 3), "f": round(tent_g + h_nb, 3),
+                            "state": "target" if is_end else "open",
+                            "is_end": is_end, "parent": current,
+                        })
+
+                display_nodes = new_nodes[:TOP_DISPLAY]
+                display_edges = [{"from": current, "to": n["id"]} for n in display_nodes]
+                if display_nodes:
+                    await self.send("neighbours", {
+                        "centre": current,
+                        "nodes":  display_nodes,
+                        "edges":  display_edges,
+                    })
+                    await asyncio.sleep(0.01)
+
+            await self.send("not_found", {
+                "message": f"No path found within {MAX_HOPS} hops.",
+                "visited": list(self.closed_set),
+                "stats":   self.stats.to_dict(),
+            })

server.py

@@ -0,0 +1,126 @@
+"""
+Aurelius — FastAPI app: /api/random, /api/health, /ws handler.
+
+Module split per architect plan §1. Owns the FastAPI app instance, CORS
+middleware, the startup handler (now delegating model loading to
+embedding.load_model() per plan §3), and the WebSocket endpoint that drives
+one AStarNavigator session per connection.
+"""
+
+import asyncio
+import json
+import random
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+
+import embedding
+from search import AStarNavigator
+from wiki import _load_seed_titles
+
+app = FastAPI()
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+
+@app.on_event("startup")
+async def _startup_embed_model():
+    await embedding.load_model()
+
+
+# ══════════════════════════════════════════════════════════════
+# REST endpoints (autocomplete lives entirely on the frontend now —
+# it calls Wikipedia's opensearch API directly)
+# ══════════════════════════════════════════════════════════════
+
+@app.get("/")
+async def api_root():
+    """
+    This backend never serves the frontend (no static files here — see
+    CLAUDE.md). Visiting this URL directly is a normal thing for a human
+    to try, so return a clear message instead of a bare 404 — the actual
+    app is index.html, opened directly or served alongside this on its
+    own port.
+    """
+    return {"status": "Aurelius backend is running.", "frontend": "Open index.html directly in your browser."}
+
+
+@app.get("/api/random")
+async def api_random():
+    """
+    Powers the "Random" button on the start screen. Picks two distinct
+    topics from the curated seed list (common_wiki_searches.txt) — NOT a
+    fully random Wikipedia page — so the search always gets a
+    well-connected pair of articles to find a path between.
+    """
+    titles = _load_seed_titles()
+    if len(titles) < 2:
+        return {"start": "Google", "end": "Mohali"}
+    start, end = random.sample(titles, 2)
+    return {"start": start, "end": end}
+
+
+@app.get("/api/health")
+async def api_health():
+    """
+    Polled by the frontend's loading screen on first load. Since FastAPI
+    does not accept connections until the startup handler (which loads the
+    embedding model) finishes, a successful response here already implies
+    the model is ready — there is nothing further to check.
+    """
+    return {"status": "ready"}
+
+
+# ══════════════════════════════════════════════════════════════
+# WebSocket endpoint
+# ══════════════════════════════════════════════════════════════
+
+@app.websocket("/ws")
+async def websocket_endpoint(ws: WebSocket):
+    await ws.accept()
+    navigator: AStarNavigator | None = None
+    try:
+        raw  = await ws.receive_text()
+        data = json.loads(raw)
+        if "control" in data:
+            return
+
+        start = data.get("start", "").strip()
+        end   = data.get("end",   "").strip()
+        print(f"\n{'='*60}\n[WS] '{start}' → '{end}'\n{'='*60}")
+        if not start or not end:
+            await ws.send_text(json.dumps({"event":"error","message":"Need start and end."}))
+            return
+
+        navigator = AStarNavigator(start, end, ws)
+
+        async def listen_controls():
+            while True:
+                try:
+                    msg  = await asyncio.wait_for(ws.receive_text(), timeout=0.5)
+                    ctrl = json.loads(msg)
+                    if navigator:
+                        if ctrl.get("control") == "pause":
+                            navigator._paused = True;  print("[WS] Paused")
+                        elif ctrl.get("control") == "resume":
+                            navigator._paused = False; print("[WS] Resumed")
+                except asyncio.TimeoutError:
+                    pass
+                except Exception:
+                    break
+
+        ctrl_task   = asyncio.create_task(listen_controls())
+        search_task = asyncio.create_task(navigator.run())
+        done, pending = await asyncio.wait(
+            [ctrl_task, search_task], return_when=asyncio.FIRST_COMPLETED
+        )
+        for t in pending:
+            t.cancel()
+
+    except WebSocketDisconnect:
+        print("[WS] disconnected")
+    except Exception as e:
+        print(f"[WS] {e}")
+        try:
+            await ws.send_text(json.dumps({"event":"error","message":str(e)}))
+        except Exception:
+            pass

styles.css

@@ -0,0 +1,2358 @@
+/* ============================================================
+   AURELIUS — styles.css
+   Redesign: warm editorial / knowledge explorer aesthetic
+   Amber-gold palette · Outfit body · DM Mono for data
+   ============================================================ */
+
+:root {
+  /* ─── Warm dark palette ─── */
+  --bg: #0d0c08;
+  --bg2: #141209;
+  --bg3: #1e1b10;
+  --border: rgba(255, 243, 210, 0.08);
+  --border-bright: rgba(201, 138, 46, 0.45);
+  --text: #ede8d4;
+  --text2: #7d7562;
+  --accent: #c98a2e;
+  --accent2: #e4b254;
+  --green: #4aab79;
+  --amber: #e07d2c;
+  --red: #cb4c3a;
+  --cyan: #3aa4be;
+
+  /* ─── Graph tokens ─── */
+  --node-open: #c98a2e;
+  --node-closed: #2a261a;
+  --node-centre: #e07d2c;
+  --node-target: #4aab79;
+  --node-path: #e56c2a;
+  --edge-faint: rgba(201, 138, 46, 0.08);
+  --path-edge: rgba(229, 108, 42, 0.9);
+
+  /* ─── Shadow system ─── */
+  --shadow-rgb: 0, 0, 0;
+  --shadow-accent-rgb: 201, 138, 46;
+  --shadow-sm: 0 1px 4px rgba(0, 0, 0, .32);
+  --shadow-md: 0 4px 16px rgba(0, 0, 0, .44);
+  --shadow-lg: 0 12px 40px rgba(0, 0, 0, .56);
+  --shadow-xl: 0 24px 64px rgba(0, 0, 0, .72);
+  --shadow-glow: 0 0 20px rgba(201, 138, 46, .20);
+  --shadow-glow-strong: 0 0 32px rgba(201, 138, 46, .36);
+}
+
+/* ─── Reset ─── */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  font-family: 'Outfit', sans-serif;
+}
+
+body {
+  background: var(--bg);
+  color: var(--text);
+  height: 100vh;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+}
+
+body::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background:
+    radial-gradient(ellipse at 25% 0%, rgba(201, 138, 46, .04) 0%, transparent 55%),
+    radial-gradient(ellipse at 80% 100%, rgba(74, 171, 121, .03) 0%, transparent 50%);
+  pointer-events: none;
+  z-index: -1;
+}
+
+/* ─── Scrollbars ─── */
+::-webkit-scrollbar {
+  width: 4px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(255, 243, 210, .1);
+  border-radius: 2px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(255, 243, 210, .18);
+}
+
+/* ══════════════════════════════════════════════════════════
+   LOADING SCREEN
+══════════════════════════════════════════════════════════ */
+#loading-screen {
+  position: fixed;
+  inset: 0;
+  z-index: 500;
+  background: var(--bg);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  transition: opacity 0.5s ease;
+}
+
+#loading-screen.fade-out {
+  opacity: 0;
+  pointer-events: none;
+}
+
+#loading-screen.hidden {
+  display: none;
+}
+
+#loading-logo {
+  font-family: 'Cinzel', serif;
+  font-size: 17px;
+  font-weight: 700;
+  letter-spacing: 7px;
+  text-transform: uppercase;
+  color: var(--text);
+  opacity: 0.5;
+  margin-bottom: 28px;
+}
+
+#loading-spinner {
+  width: 22px;
+  height: 22px;
+  border-radius: 50%;
+  border: 1.5px solid rgba(255, 243, 210, .1);
+  border-top-color: var(--accent2);
+  animation: loading-spin 0.85s linear infinite;
+}
+
+@keyframes loading-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ══════════════════════════════════════════════════════════
+   HERO LANDING SCREEN
+══════════════════════════════════════════════════════════ */
+#hero {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  background: var(--bg);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0;
+  transition: all 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+#hero.hiding {
+  opacity: 0;
+  transform: translateY(-28px) scale(0.99);
+  pointer-events: none;
+}
+
+#hero.hidden {
+  display: none;
+}
+
+/* Title — keep animation intact, app.js sets --center-dy and adds .entrance */
+#hero-title {
+  font-family: 'Cinzel', serif;
+  font-size: 66px;
+  font-weight: 900;
+  letter-spacing: 10px;
+  margin-bottom: 14px;
+  text-align: center;
+  text-transform: uppercase;
+  color: var(--text);
+  --center-dy: 38vh;
+  opacity: 0;
+  transform: scale(1);
+}
+
+#hero-title.entrance {
+  animation: title-entrance 4.3s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+
+@keyframes title-entrance {
+  0% {
+    opacity: 0;
+    transform: scale(1) translateY(0);
+  }
+
+  14% {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+
+  53% {
+    opacity: 1;
+    transform: scale(1.45) translateY(var(--center-dy));
+  }
+
+  88% {
+    opacity: 1;
+    transform: scale(1.45) translateY(var(--center-dy));
+  }
+
+  100% {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+/* Solid mask — same role as before, warm bg */
+#hero-bg-mask {
+  position: absolute;
+  inset: 0;
+  background: var(--bg);
+  opacity: 1;
+  pointer-events: none;
+  transition: opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+#hero-bg-mask.hide {
+  opacity: 0;
+}
+
+/* Reveal group — same semantics */
+.hero-reveal {
+  opacity: 0;
+  transform: translateY(8px);
+  transition: opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1),
+    transform 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.hero-reveal.show {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Hero rest container */
+#hero-rest {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  width: 100%;
+}
+
+/* Tagline */
+#hero-tagline {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 4.5px;
+  text-transform: uppercase;
+  color: var(--accent);
+  opacity: 0;
+  margin-top: 0;
+  margin-bottom: 52px;
+  text-align: center;
+  transition: opacity 0.5s ease;
+}
+
+/* ID selector wins over .hero-reveal.show, keeping tagline at 75% opacity */
+#hero-tagline.show {
+  opacity: 0.75;
+}
+
+#hero-sub {
+  font-size: 14px;
+  color: var(--text2);
+  margin-bottom: 44px;
+  text-align: center;
+  font-weight: 400;
+  letter-spacing: 0.1px;
+  max-width: 430px;
+  line-height: 1.8;
+}
+
+/* ─── Hero inputs ─── */
+#hero-inputs {
+  display: flex;
+  align-items: flex-start;
+  gap: 16px;
+  width: 100%;
+  max-width: 800px;
+  padding: 0 24px;
+}
+
+.hero-field {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  position: relative;
+}
+
+.hero-field label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 2.5px;
+  text-transform: uppercase;
+  color: var(--text2);
+  padding-left: 2px;
+  transition: color 0.25s;
+}
+
+.hero-field label.filled {
+  color: var(--accent2);
+}
+
+.hero-input {
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 14px 16px;
+  font-size: 15px;
+  font-weight: 500;
+  color: var(--text);
+  width: 100%;
+  outline: none;
+  transition: border-color 0.2s, box-shadow 0.2s;
+  caret-color: var(--accent2);
+  font-family: 'Outfit', sans-serif;
+}
+
+.hero-input::placeholder {
+  color: rgba(255, 243, 210, .2);
+  font-weight: 400;
+  font-size: 13px;
+}
+
+.hero-input:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(201, 138, 46, .11);
+}
+
+.hero-input.filled {
+  border-color: rgba(201, 138, 46, .28);
+}
+
+#hero-arrow {
+  font-size: 22px;
+  color: rgba(255, 243, 210, .14);
+  flex-shrink: 0;
+  margin-top: 38px;
+  transition: color 0.3s ease;
+}
+
+#hero-arrow.lit {
+  color: var(--accent2);
+}
+
+/* ─── Find Path button ─── */
+#hero-btn {
+  margin-top: 32px;
+  background: var(--accent);
+  color: #0d0c08;
+  border: none;
+  border-radius: 6px;
+  padding: 13px 52px;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 2px;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition: background 0.18s, transform 0.15s;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(8px);
+  font-family: 'Outfit', sans-serif;
+}
+
+#hero-btn.ready {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateY(0);
+}
+
+#hero-btn:hover {
+  background: var(--accent2);
+  transform: translateY(-1px);
+}
+
+#hero-btn:active {
+  transform: scale(0.98);
+}
+
+/* Hint */
+#hero-hint {
+  margin-top: 14px;
+  font-size: 11px;
+  color: var(--text2);
+  opacity: 0;
+  transition: opacity 0.3s;
+  letter-spacing: 0.3px;
+  font-family: 'DM Mono', monospace;
+}
+
+#hero-hint.visible {
+  opacity: 0.5;
+}
+
+/* ─── Random button ─── */
+#hero-random-btn {
+  margin: 16px auto 0;
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 8px 22px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  position: static;
+  font-family: 'Outfit', sans-serif;
+}
+
+#hero-random-btn:hover {
+  border-color: rgba(201, 138, 46, .28);
+  color: var(--text);
+}
+
+#hero-random-btn:active {
+  transform: scale(0.97);
+}
+
+#hero-random-btn.loading {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+/* ─── About button (hero) ─── */
+#hero-about-btn {
+  position: absolute;
+  top: 20px;
+  right: 20px;
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 7px 16px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  font-family: 'Outfit', sans-serif;
+  z-index: 10;
+  letter-spacing: 0.4px;
+  animation: about-pulse 3.5s ease-in-out infinite;
+}
+
+#hero-about-btn:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .3);
+  animation: none;
+}
+
+@keyframes about-pulse {
+
+  0%,
+  100% {
+    border-color: rgba(255, 243, 210, .08);
+  }
+
+  50% {
+    border-color: rgba(201, 138, 46, .22);
+  }
+}
+
+/* ─── Watermark ─── */
+#hero-watermark {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -52%);
+  width: 820px;
+  height: 820px;
+  opacity: 0.05;
+  pointer-events: none;
+}
+
+/* z-index stack — same logic as original, just re-declared for specificity */
+#hero>* {
+  position: relative;
+  z-index: 1;
+}
+
+#hero-watermark {
+  position: absolute;
+  z-index: 0;
+}
+
+#hero-bg-mask {
+  position: absolute;
+  z-index: 1;
+}
+
+/* #hero-about-btn shares #hero-about-btn's own rule's specificity (1,0,0)
+   with #hero>* above, so the later rule in the file wins and silently
+   knocked the button out of its absolute corner position into normal
+   flow — same collision already fixed for #hero-watermark/#hero-bg-mask
+   above. Re-assert here, after #hero>*, to pin it back to the corner. */
+#hero-about-btn {
+  position: absolute;
+  top: 20px;
+  right: 20px;
+  z-index: 10;
+}
+
+/* ══════════════════════════════════════════════════════════
+   TOP BAR (post-search)
+══════════════════════════════════════════════════════════ */
+#topbar {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 0 20px;
+  height: 52px;
+  background: var(--bg2);
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+  opacity: 0;
+  transform: translateY(-6px);
+  transition: opacity 0.35s ease 0.1s, transform 0.35s ease 0.1s;
+}
+
+#topbar.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+#topbar h1 {
+  font-family: 'Cinzel', serif;
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text);
+  white-space: nowrap;
+  letter-spacing: 3.5px;
+  text-transform: uppercase;
+}
+
+#topbar-logo {
+  cursor: pointer;
+  user-select: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.topbar-logo-img {
+  height: 20px;
+  width: 20px;
+  opacity: 0.72;
+  transition: opacity 0.2s;
+}
+
+#topbar-logo:hover .topbar-logo-img {
+  opacity: 1;
+}
+
+/* Input wrappers */
+.input-wrap {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 6px 12px;
+  flex: 1;
+  min-width: 160px;
+  max-width: 340px;
+  transition: border-color 0.2s;
+  position: relative;
+}
+
+.input-wrap:focus-within {
+  border-color: rgba(201, 138, 46, .35);
+}
+
+.input-wrap span {
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 2px;
+  text-transform: uppercase;
+  color: var(--accent);
+  white-space: nowrap;
+}
+
+.input-wrap input {
+  background: transparent;
+  border: none;
+  outline: none;
+  color: var(--text);
+  font-size: 13px;
+  font-weight: 500;
+  width: 100%;
+  font-family: 'Outfit', sans-serif;
+}
+
+/* Topbar buttons */
+#btn-swap {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 6px 10px;
+  font-size: 14px;
+  cursor: pointer;
+  transition: all 0.2s;
+  flex-shrink: 0;
+  line-height: 1;
+}
+
+#btn-swap:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .25);
+}
+
+#btn-search {
+  background: var(--accent);
+  color: #0d0c08;
+  border: none;
+  border-radius: 5px;
+  padding: 8px 18px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 1.2px;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition: background 0.18s;
+  white-space: nowrap;
+  font-family: 'Outfit', sans-serif;
+  flex-shrink: 0;
+}
+
+#btn-search:hover {
+  background: var(--accent2);
+}
+
+#btn-search:disabled {
+  opacity: .35;
+  cursor: default;
+}
+
+#btn-reset {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 7px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s;
+  font-family: 'Outfit', sans-serif;
+  flex-shrink: 0;
+}
+
+#btn-reset:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .25);
+}
+
+#btn-about {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 7px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s;
+  font-family: 'Outfit', sans-serif;
+  flex-shrink: 0;
+}
+
+#btn-about:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .25);
+}
+
+#status-bar {
+  font-size: 11px;
+  color: var(--text2);
+  flex: 1;
+  min-width: 80px;
+  font-weight: 400;
+  font-family: 'DM Mono', monospace;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  padding-left: 4px;
+}
+
+/* ══════════════════════════════════════════════════════════
+   STATS BAR
+══════════════════════════��═══════════════════════════════ */
+#stats-bar {
+  display: none;
+  align-items: center;
+  gap: 16px;
+  padding: 5px 20px;
+  background: var(--bg2);
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+#stats-bar.visible {
+  display: flex;
+}
+
+.sstat {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--text2);
+  font-weight: 400;
+  font-family: 'DM Mono', monospace;
+}
+
+.sstat-val {
+  color: var(--accent2);
+  font-weight: 500;
+  font-size: 11px;
+  min-width: 22px;
+}
+
+.sstat-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.stats-spacer {
+  flex: 1;
+}
+
+#btn-pause-bar {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 4px 14px;
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s;
+  display: none;
+  font-family: 'Outfit', sans-serif;
+}
+
+#btn-pause-bar:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .25);
+}
+
+#btn-pause-bar.visible {
+  display: inline-block;
+}
+
+#btn-pause-bar.paused {
+  color: var(--amber);
+  border-color: var(--amber);
+}
+
+#btn-export {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 4px 12px;
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s;
+  display: none;
+  font-family: 'Outfit', sans-serif;
+}
+
+#btn-export:hover {
+  color: var(--green);
+  border-color: var(--green);
+}
+
+#btn-export.visible {
+  display: inline-block;
+}
+
+/* ══════════════════════════════════════════════════════════
+   MAIN LAYOUT
+══════════════════════════════════════════════════════════ */
+#main {
+  display: flex;
+  flex: 1;
+  overflow: hidden;
+}
+
+#canvas-wrap {
+  flex: 1;
+  position: relative;
+  overflow: hidden;
+  background: var(--bg);
+}
+
+svg#graph {
+  width: 100%;
+  height: 100%;
+}
+
+/* ─── Tooltip ─── */
+#tooltip {
+  position: absolute;
+  pointer-events: none;
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-top: 1px solid rgba(255, 243, 210, .1);
+  box-shadow: var(--shadow-md);
+  border-radius: 6px;
+  padding: 10px 14px;
+  font-size: 12px;
+  color: var(--text);
+  max-width: 220px;
+  opacity: 0;
+  transition: opacity .12s;
+  z-index: 100;
+}
+
+#tooltip.visible {
+  opacity: 1;
+}
+
+#tooltip .tt-title {
+  font-weight: 600;
+  margin-bottom: 6px;
+  color: var(--accent2);
+  font-size: 13px;
+  font-family: 'Outfit', sans-serif;
+}
+
+#tooltip .tt-scores {
+  color: var(--text2);
+  font-size: 11px;
+  line-height: 1.55;
+  font-family: 'DM Mono', monospace;
+}
+
+/* ─── Node labels ─── */
+.node-label {
+  font-size: 10px;
+  fill: var(--text2);
+  pointer-events: none;
+  text-anchor: middle;
+  font-weight: 500;
+  font-family: 'Outfit', sans-serif;
+}
+
+.node-label.centre-label {
+  font-size: 12px;
+  fill: var(--text);
+  font-weight: 700;
+}
+
+/* ══════════════════════════════════════════════════════════
+   SIDE PANEL
+══════════════════════════════════════════════════════════ */
+#panel {
+  width: 300px;
+  background: var(--bg2);
+  border-left: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+#panel-tabs {
+  display: flex;
+  border-bottom: 1px solid var(--border);
+}
+
+.tab {
+  flex: 1;
+  text-align: center;
+  padding: 12px 0;
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 1.8px;
+  text-transform: uppercase;
+  color: var(--text2);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  transition: all 0.18s ease;
+}
+
+.tab:hover {
+  color: var(--text);
+}
+
+.tab.active {
+  color: var(--accent2);
+  border-bottom-color: var(--accent);
+}
+
+.tab-content {
+  display: none;
+  flex: 1;
+  overflow-y: auto;
+  padding: 14px;
+}
+
+.tab-content.active {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+/* ─── Path steps ─── */
+#path-display {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.path-step {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+}
+
+.path-step .dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  background: var(--node-path);
+}
+
+.path-step .dot.start {
+  background: var(--accent);
+}
+
+.path-step .dot.end {
+  background: var(--green);
+}
+
+.path-step .arrow {
+  color: var(--text2);
+  font-size: 12px;
+}
+
+.hop-btn-link {
+  display: inline-flex;
+  align-items: center;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  color: var(--text);
+  padding: 5px 10px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  text-decoration: none;
+  transition: all 0.15s;
+  margin-left: 6px;
+  flex: 1;
+  cursor: pointer;
+}
+
+.hop-btn-link:hover {
+  border-color: rgba(201, 138, 46, .3);
+  color: var(--accent2);
+}
+
+.hop-btn-link.start-hop {
+  border-color: rgba(201, 138, 46, .22);
+}
+
+.hop-btn-link.end-hop {
+  border-color: rgba(74, 171, 121, .22);
+}
+
+.hop-btn-link.end-hop:hover {
+  border-color: var(--green);
+  color: var(--green);
+}
+
+/* ─── Score cards ─── */
+.score-card {
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 11px 12px;
+  transition: border-color 0.15s;
+}
+
+.score-card:hover {
+  border-color: rgba(201, 138, 46, .2);
+}
+
+.score-card .title {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text);
+  margin-bottom: 7px;
+  word-break: break-word;
+  line-height: 1.3;
+}
+
+.score-row {
+  display: flex;
+  justify-content: space-between;
+  font-size: 11px;
+  color: var(--text2);
+  margin-top: 3px;
+  font-family: 'DM Mono', monospace;
+}
+
+.score-row span:last-child {
+  color: var(--accent2);
+  font-weight: 500;
+}
+
+/* ─── Log ─── */
+#log {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+.log-entry {
+  font-family: 'DM Mono', monospace;
+  font-size: 11px;
+  color: var(--text2);
+  padding: 5px 0;
+  border-bottom: 1px solid var(--border);
+  line-height: 1.55;
+}
+
+.log-entry.highlight {
+  color: var(--amber);
+}
+
+.log-entry.success {
+  color: var(--green);
+}
+
+.log-entry.error {
+  color: var(--red);
+}
+
+/* ─── Legend ─── */
+.legend-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--text2);
+  line-height: 1.4;
+}
+
+.legend-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+/* ─── Path banner ─── */
+#path-banner {
+  display: none;
+  background: var(--bg2);
+  border-top: 1px solid var(--border);
+  padding: 10px 20px;
+  flex-shrink: 0;
+}
+
+#path-banner.visible {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+.banner-arrow {
+  color: var(--accent);
+  font-size: 13px;
+  font-weight: 700;
+}
+
+/* ══════════════════════════════════════════════════════════
+   AUTOCOMPLETE DROPDOWN
+══════════════════════════════════════════════════════════ */
+.hero-field {
+  position: relative;
+}
+
+.ac-dropdown {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  right: 0;
+  background: var(--bg2);
+  border: 1px solid var(--border-bright);
+  border-radius: 6px;
+  overflow: hidden;
+  z-index: 50;
+  box-shadow: var(--shadow-lg);
+  display: none;
+}
+
+.ac-dropdown.visible {
+  display: block;
+}
+
+.ac-item {
+  padding: 10px 14px;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text);
+  cursor: pointer;
+  transition: background 0.1s;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.ac-item:last-child {
+  border-bottom: none;
+}
+
+.ac-item:hover,
+.ac-item.ac-active {
+  background: rgba(201, 138, 46, .08);
+  color: var(--accent2);
+}
+
+.ac-item .ac-icon {
+  opacity: 0.38;
+  flex-shrink: 0;
+}
+
+.input-wrap {
+  position: relative;
+}
+
+/* ══════════════════════════════════════════════════════════
+   MODALS
+══════════════════════════════════════════════════════════ */
+.modal-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(13, 12, 8, .84);
+  backdrop-filter: blur(6px);
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+}
+
+.modal-backdrop.visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.modal-card {
+  position: relative;
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-top: 1px solid rgba(255, 243, 210, .12);
+  box-shadow: var(--shadow-xl);
+  border-radius: 10px;
+  padding: 40px;
+  max-width: 860px;
+  width: 90%;
+  transform: scale(0.96) translateY(10px);
+  transition: transform 0.38s cubic-bezier(0.34, 1.56, 0.64, 1);
+  text-align: center;
+}
+
+/* ─── Corner close (×) — onboarding + success modals ─── */
+.modal-corner-close {
+  position: absolute;
+  top: 14px;
+  right: 14px;
+  width: 28px;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 50%;
+  color: var(--text2);
+  cursor: pointer;
+  transition: all 0.18s ease;
+  padding: 0;
+  z-index: 2;
+}
+
+.modal-corner-close svg {
+  width: 12px;
+  height: 12px;
+}
+
+.modal-corner-close:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .35);
+  background: rgba(201, 138, 46, .06);
+}
+
+.modal-backdrop.visible .modal-card {
+  transform: scale(1) translateY(0);
+}
+
+.modal-success-icon {
+  width: 40px;
+  height: 40px;
+  color: var(--green);
+  margin-bottom: 10px;
+}
+
+.modal-title {
+  font-family: 'Cinzel', serif;
+  font-size: 26px;
+  font-weight: 700;
+  color: var(--green);
+  margin-bottom: 6px;
+  letter-spacing: 1px;
+}
+
+.modal-subtitle {
+  font-size: 14px;
+  color: var(--text2);
+  margin-bottom: 32px;
+}
+
+.modal-subtitle span {
+  font-weight: 700;
+  color: var(--text);
+}
+
+.modal-stat-row {
+  display: flex;
+  justify-content: center;
+  gap: 44px;
+  margin: 18px 0 24px;
+}
+
+.modal-stat {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 5px;
+}
+
+.modal-stat-val {
+  font-size: 34px;
+  font-weight: 500;
+  color: var(--text);
+  font-family: 'DM Mono', monospace;
+  line-height: 1;
+}
+
+.modal-stat-lbl {
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 2.5px;
+  text-transform: uppercase;
+  color: var(--text2);
+}
+
+.modal-path {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  margin: 0 0 28px;
+  padding: 20px 24px;
+  background: var(--bg3);
+  border-radius: 6px;
+  border: 1px solid var(--border);
+}
+
+.modal-arrow {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--text2);
+  position: relative;
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  cursor: default;
+}
+
+.modal-piped-note {
+  font-size: 9px;
+  font-weight: 600;
+  font-style: italic;
+  color: var(--amber);
+  white-space: nowrap;
+  letter-spacing: 0.2px;
+}
+
+.modal-disclaimer {
+  font-size: 11px;
+  line-height: 1.65;
+  color: var(--text2);
+  opacity: 0.55;
+  text-align: center;
+  max-width: 460px;
+  margin: -8px auto 24px;
+}
+
+.modal-close-btn {
+  background: var(--accent);
+  color: #0d0c08;
+  border: none;
+  padding: 12px 30px;
+  border-radius: 5px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 1.2px;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition: background 0.18s;
+  font-family: 'Outfit', sans-serif;
+}
+
+.modal-close-btn:hover {
+  background: var(--accent2);
+}
+
+.modal-copy-btn {
+  background: transparent;
+  color: var(--text2);
+  border: 1px solid var(--border);
+  padding: 12px 30px;
+  border-radius: 5px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.5px;
+  cursor: pointer;
+  transition: all 0.18s;
+  font-family: 'Outfit', sans-serif;
+}
+
+.modal-copy-btn:hover {
+  color: var(--text);
+  border-color: rgba(201, 138, 46, .3);
+}
+
+.hop-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  color: var(--text);
+  padding: 9px 16px;
+  border-radius: 5px;
+  font-size: 13px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: all 0.15s;
+  cursor: pointer;
+}
+
+.hop-btn:hover {
+  border-color: rgba(201, 138, 46, .35);
+  color: var(--accent2);
+}
+
+.hop-btn.start-hop {
+  border-color: rgba(201, 138, 46, .28);
+}
+
+.hop-btn.end-hop {
+  border-color: rgba(74, 171, 121, .28);
+}
+
+.hop-btn.end-hop:hover {
+  border-color: var(--green);
+  color: var(--green);
+}
+
+/* ══════════════════════════════════════════════════════════
+   PATH FOUND ANIMATION
+══════════════════════════════════════════════════════════ */
+@keyframes pathEdgePulse {
+
+  0%,
+  100% {
+    stroke-opacity: 0.8;
+  }
+
+  50% {
+    stroke-opacity: 1.0;
+  }
+}
+
+.edge-path-found {
+  animation: pathEdgePulse 1.6s ease-in-out infinite;
+}
+
+@keyframes modalEnter {
+  0% {
+    opacity: 0;
+    transform: scale(0.92) translateY(14px);
+  }
+
+  60% {
+    opacity: 1;
+    transform: scale(1.01) translateY(-2px);
+  }
+
+  100% {
+    transform: scale(1) translateY(0);
+  }
+}
+
+.modal-backdrop.visible .modal-card {
+  animation: modalEnter 0.45s cubic-bezier(0.22, 1, 0.36, 1) forwards !important;
+}
+
+/* ══════════════════════════════════════════════════════════
+   ONBOARDING MODAL
+══════════════════════════════════════════════════════════ */
+#onboarding-modal {
+  z-index: 600;
+  display: none;
+}
+
+#onboarding-modal.visible {
+  display: flex;
+}
+
+.onboarding-card {
+  max-width: 460px;
+  text-align: center;
+  padding: 44px 40px 36px;
+}
+
+.onboarding-title {
+  font-family: 'Cinzel', serif;
+  font-size: 22px;
+  font-weight: 900;
+  letter-spacing: 4px;
+  text-transform: uppercase;
+  color: var(--text);
+  margin-bottom: 6px;
+}
+
+.onboarding-tagline {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 3px;
+  text-transform: uppercase;
+  color: var(--accent);
+  opacity: 0.75;
+  margin-bottom: 32px;
+}
+
+.onboarding-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  text-align: left;
+  margin-bottom: 32px;
+}
+
+.onboarding-step {
+  display: flex;
+  gap: 14px;
+  align-items: flex-start;
+}
+
+.onboarding-icon {
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background: var(--bg3);
+  border: 1px solid rgba(201, 138, 46, .3);
+  color: var(--accent2);
+  font-weight: 700;
+  font-size: 13px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.onboarding-step strong {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text);
+  display: block;
+  margin-bottom: 3px;
+}
+
+.onboarding-step p {
+  font-size: 12px;
+  color: var(--text2);
+  line-height: 1.6;
+  margin: 0;
+}
+
+.onboarding-go-btn {
+  font-size: 13px;
+  padding: 11px 36px;
+}
+
+.onboarding-tip {
+  font-size: 11.5px;
+  font-style: italic;
+  color: var(--text2);
+  opacity: 0.7;
+  line-height: 1.6;
+  margin: -6px 0 22px;
+}
+
+/* ══════════════════════════════════════════════════════════
+   ABOUT MODAL
+══════════════════════════════════════════════════════════ */
+.about-card {
+  max-width: 720px;
+  text-align: left;
+  max-height: 88vh;
+  overflow-y: auto;
+  padding: 44px 48px;
+  scrollbar-width: thin;
+}
+
+.about-card::-webkit-scrollbar {
+  width: 4px;
+}
+
+.about-card::-webkit-scrollbar-thumb {
+  background: rgba(255, 243, 210, .1);
+  border-radius: 2px;
+}
+
+.about-section-label {
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 3.5px;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-bottom: 16px;
+  display: block;
+}
+
+.about-quote-block {
+  text-align: center;
+  padding: 28px 24px;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-left: 2px solid var(--accent);
+  border-radius: 2px 8px 8px 2px;
+  margin-bottom: 28px;
+}
+
+.about-quote-mark {
+  font-family: 'Cinzel', serif;
+  font-size: 44px;
+  line-height: 0.6;
+  color: var(--accent);
+  opacity: 0.28;
+  display: block;
+  margin-bottom: 14px;
+  user-select: none;
+}
+
+.about-quote-text {
+  font-size: 15px;
+  font-style: italic;
+  color: var(--text);
+  font-weight: 400;
+  line-height: 1.8;
+  margin-bottom: 12px;
+}
+
+.about-quote-attr {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 2px;
+  text-transform: uppercase;
+  color: var(--accent2);
+  opacity: 0.65;
+}
+
+.about-tech-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+  margin-bottom: 28px;
+}
+
+.about-tech-card {
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 16px 18px;
+  transition: border-color 0.18s;
+}
+
+.about-tech-card:hover {
+  border-color: rgba(201, 138, 46, .22);
+}
+
+.tech-icon {
+  width: 26px;
+  height: 26px;
+  margin-bottom: 10px;
+  color: var(--accent2);
+  opacity: 0.7;
+}
+
+.about-tech-card .tech-name {
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--text);
+  margin-bottom: 6px;
+}
+
+.about-tech-card .tech-desc {
+  font-size: 11.5px;
+  color: var(--text2);
+  line-height: 1.7;
+}
+
+.about-tech-card .tech-desc em {
+  color: var(--text);
+  font-style: normal;
+  font-weight: 600;
+}
+
+.about-compare {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 4px;
+}
+
+.about-compare-head {
+  padding: 10px 14px;
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 2.5px;
+  text-transform: uppercase;
+  color: var(--text2);
+  background: var(--bg3);
+  border-bottom: 1px solid var(--border);
+}
+
+.about-compare-head.accent {
+  color: var(--accent2);
+}
+
+.about-compare-cell {
+  padding: 10px 14px;
+  font-size: 12px;
+  color: var(--text2);
+  background: var(--bg2);
+  line-height: 1.5;
+  border-bottom: 1px solid var(--border);
+}
+
+.about-compare-cell.accent {
+  color: var(--text);
+  background: rgba(201, 138, 46, .025);
+}
+
+.about-prose {
+  font-size: 13px;
+  color: var(--text2);
+  line-height: 1.85;
+  margin-bottom: 14px;
+}
+
+.about-prose b {
+  color: var(--text);
+}
+
+.about-divider {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 24px 0;
+}
+
+.about-linkedin-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--accent2);
+  font-size: 12px;
+  font-weight: 700;
+  text-decoration: none;
+  border: 1px solid rgba(201, 138, 46, .28);
+  padding: 8px 16px;
+  border-radius: 5px;
+  transition: all 0.2s;
+  font-family: 'Outfit', sans-serif;
+}
+
+.about-linkedin-btn:hover {
+  background: rgba(201, 138, 46, .06);
+  border-color: rgba(201, 138, 46, .48);
+}
+
+.about-callout {
+  background: var(--bg3);
+  border-left: 2px solid var(--accent);
+  padding: 16px 20px;
+  margin-bottom: 4px;
+}
+
+.about-callout-quote {
+  font-size: 14px;
+  font-style: italic;
+  color: var(--text);
+  font-weight: 400;
+  line-height: 1.65;
+  margin-bottom: 8px;
+}
+
+.about-callout-attr {
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 2px;
+  text-transform: uppercase;
+  color: var(--accent2);
+}
+
+/* ══════════════════════════════════════════════════════════
+   ANIMATED BRAND MARK — constellation graph logo
+══════════════════════════════════════════════════════════ */
+.aurelius-logo {
+  overflow: visible;
+}
+
+.alogo-edges line {
+  stroke: var(--accent);
+  stroke-width: 1.5;
+  stroke-linecap: round;
+}
+
+.alogo-nodes circle {
+  fill: var(--accent);
+  stroke: rgba(255, 243, 210, .15);
+  stroke-width: 0.8;
+}
+
+.alogo-hub {
+  fill: var(--node-path);
+  stroke: rgba(255, 243, 210, .2);
+  stroke-width: 1;
+}
+
+.alogo-trace {
+  fill: none;
+  stroke: var(--node-path);
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-dasharray: 200;
+  animation: trace-draw 4s ease-in-out infinite;
+}
+
+@keyframes trace-draw {
+  0% {
+    stroke-dashoffset: 200;
+    opacity: 0;
+  }
+
+  10% {
+    opacity: 1;
+  }
+
+  50% {
+    stroke-dashoffset: 0;
+    opacity: 1;
+  }
+
+  80% {
+    stroke-dashoffset: 0;
+    opacity: 0.3;
+  }
+
+  100% {
+    stroke-dashoffset: -200;
+    opacity: 0;
+  }
+}
+
+/* ─── Hero watermark version ─── */
+.aurelius-logo-hero {
+  overflow: visible;
+}
+
+.wm-edges line {
+  stroke: var(--accent);
+  stroke-width: 0.8;
+  stroke-linecap: round;
+  opacity: 0.6;
+}
+
+.wm-nodes circle {
+  fill: var(--accent);
+  stroke: rgba(255, 243, 210, .08);
+  stroke-width: 0.5;
+  opacity: 0.6;
+}
+
+.wm-hub {
+  fill: var(--node-path);
+  stroke: rgba(255, 243, 210, .15);
+  stroke-width: 0.7;
+  animation: wm-hub-pulse 4s ease-in-out infinite;
+}
+
+@keyframes wm-hub-pulse {
+
+  0%,
+  100% {
+    r: 6.5;
+  }
+
+  50% {
+    r: 8;
+  }
+}
+
+.wm-path-trace {
+  fill: none;
+  stroke: var(--node-path);
+  stroke-width: 1.2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-dasharray: 300;
+  animation: wm-trace 6s ease-in-out infinite;
+}
+
+.wm-trace-2 {
+  animation-delay: -3s;
+  stroke: var(--accent2);
+}
+
+@keyframes wm-trace {
+  0% {
+    stroke-dashoffset: 300;
+    opacity: 0;
+  }
+
+  8% {
+    opacity: 0.7;
+  }
+
+  50% {
+    stroke-dashoffset: 0;
+    opacity: 0.7;
+  }
+
+  85% {
+    stroke-dashoffset: 0;
+    opacity: 0;
+  }
+
+  100% {
+    stroke-dashoffset: -300;
+    opacity: 0;
+  }
+}
+
+.wm-particle {
+  fill: var(--accent2);
+  opacity: 0;
+}
+
+.wm-p1 {
+  animation: wm-float-1 6s linear infinite;
+}
+
+.wm-p2 {
+  animation: wm-float-2 8s linear infinite 1s;
+}
+
+.wm-p3 {
+  animation: wm-float-3 7s linear infinite 2.5s;
+}
+
+.wm-p4 {
+  animation: wm-float-4 9s linear infinite 4s;
+}
+
+@keyframes wm-float-1 {
+  0% {
+    cx: 42;
+    cy: 52;
+    opacity: 0;
+  }
+
+  10% {
+    opacity: 0.7;
+  }
+
+  33% {
+    cx: 100;
+    cy: 100;
+  }
+
+  66% {
+    cx: 158;
+    cy: 52;
+  }
+
+  90% {
+    opacity: 0.7;
+  }
+
+  100% {
+    cx: 172;
+    cy: 108;
+    opacity: 0;
+  }
+}
+
+@keyframes wm-float-2 {
+  0% {
+    cx: 100;
+    cy: 28;
+    opacity: 0;
+  }
+
+  10% {
+    opacity: 0.5;
+  }
+
+  50% {
+    cx: 100;
+    cy: 100;
+  }
+
+  90% {
+    opacity: 0.5;
+  }
+
+  100% {
+    cx: 58;
+    cy: 158;
+    opacity: 0;
+  }
+}
+
+@keyframes wm-float-3 {
+  0% {
+    cx: 172;
+    cy: 108;
+    opacity: 0;
+  }
+
+  10% {
+    opacity: 0.6;
+  }
+
+  50% {
+    cx: 100;
+    cy: 100;
+  }
+
+  90% {
+    opacity: 0.6;
+  }
+
+  100% {
+    cx: 28;
+    cy: 108;
+    opacity: 0;
+  }
+}
+
+@keyframes wm-float-4 {
+  0% {
+    cx: 58;
+    cy: 158;
+    opacity: 0;
+  }
+
+  10% {
+    opacity: 0.4;
+  }
+
+  33% {
+    cx: 100;
+    cy: 100;
+  }
+
+  66% {
+    cx: 100;
+    cy: 28;
+  }
+
+  90% {
+    opacity: 0.4;
+  }
+
+  100% {
+    cx: 158;
+    cy: 52;
+    opacity: 0;
+  }
+}
+
+/* ══════════════════════════════════════════════════════════
+   RESPONSIVE — TV · desktop · tablet · phone
+   The base styles above are tuned for a ~1280–1680px desktop.
+   Everything below adapts that single layout to other form
+   factors. Guiding rule for small screens (per product intent):
+   it's fine if the graph and side panel aren't visible at the
+   SAME time on a phone — what matters is that every device can
+   open the app and clearly see the logo, run a search, and read
+   the resulting path (the success modal + the Path tab both show
+   the full path, so the path is legible even when the graph
+   itself is small).
+══════════════════════════════════════════════════════════ */
+
+/* ─── Large displays / TVs (1080p+ , couch viewing distance) ───
+   Bump the things that are otherwise too small to read from across
+   a room: the side panel, its text, status line, and graph labels. */
+@media (min-width: 1800px) {
+  #panel { width: 380px; }
+  .tab { font-size: 12px; padding: 16px 0; }
+  .score-card .title { font-size: 14px; }
+  .score-row { font-size: 13px; }
+  .log-entry { font-size: 13px; }
+  .legend-row { font-size: 14px; }
+  #status-bar { font-size: 13px; }
+  .sstat, .sstat-val { font-size: 13px; }
+  .hop-btn-link { font-size: 13px; }
+  #hero-title { font-size: 84px; }
+  #hero-sub { font-size: 16px; max-width: 520px; }
+  .node-label { font-size: 13px; }
+  .node-label.centre-label { font-size: 15px; }
+}
+
+/* ─── Tablets (landscape + large portrait) ─── */
+@media (max-width: 1024px) {
+  #panel { width: 264px; }
+  #hero-title { font-size: 54px; letter-spacing: 8px; }
+  #hero-inputs { max-width: 680px; }
+  .modal-card { padding: 32px; }
+  .about-card { padding: 36px 36px; }
+}
+
+/* ─── Stacked layout: graph on top, panel below ───
+   Kicks in for narrow tablets / large phones. The single biggest
+   change — the desktop side-by-side (#main is a flex ROW) becomes
+   a vertical stack so neither the graph nor the panel is crushed
+   into a sliver. */
+@media (max-width: 820px) {
+  #main {
+    flex-direction: column;
+  }
+
+  #canvas-wrap {
+    flex: 1 1 0;
+    min-height: 200px;
+  }
+
+  #panel {
+    width: 100%;
+    flex: 1 1 0;
+    min-height: 180px;
+    border-left: none;
+    border-top: 1px solid var(--border);
+  }
+
+  /* Topbar wraps instead of overflowing horizontally. The two
+     article inputs share the first row; buttons + status flow
+     onto following rows as needed. */
+  #topbar {
+    flex-wrap: wrap;
+    height: auto;
+    min-height: 52px;
+    padding: 8px 12px;
+    row-gap: 8px;
+  }
+
+  .input-wrap {
+    flex: 1 1 140px;
+    min-width: 0;
+    max-width: none;
+  }
+
+  #status-bar {
+    flex: 1 1 100%;
+    order: 10;
+    white-space: normal;
+  }
+}
+
+/* ─── Mobile collapse/expand: topbar + panel ───
+   On phones/narrow tablets, the search-controls topbar and the path/
+   scores/log panel default to collapsed right when the hero is dismissed
+   (see app.js dismissHero()), so the first thing a mobile visitor sees is
+   the live graph, not a wall of chrome. Each section's handle bar stays
+   OUTSIDE the collapsing element (siblings in index.html) specifically so
+   it's always visible/tappable even while its target is collapsed to zero
+   height — collapsing the handle along with its target would make it
+   impossible to reopen.
+   Both handles are display:none above this breakpoint — on desktop/tablet
+   the topbar and panel are simply always visible, full stop, and these
+   elements have zero effect on that layout. */
+.mobile-handle {
+  display: none;
+}
+
+@media (max-width: 820px) {
+  .mobile-handle {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    height: 24px;
+    flex-shrink: 0;
+    background: var(--bg2);
+    border-bottom: 1px solid var(--border);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.6px;
+    text-transform: uppercase;
+    color: var(--text2);
+    cursor: pointer;
+    transition: background 0.15s, color 0.15s;
+  }
+
+  .mobile-handle:hover,
+  .mobile-handle:active {
+    color: var(--text);
+    background: var(--bg3);
+  }
+
+  .mobile-handle svg {
+    transition: transform 0.25s ease;
+    flex-shrink: 0;
+  }
+
+  /* Chevron points down (expand me) when the target is collapsed, up
+     (collapse me) when it's open — toggled by app.js alongside the
+     target's own .mobile-collapsed class. */
+  .mobile-handle.is-collapsed svg {
+    transform: rotate(-90deg);
+  }
+
+  #mobile-panel-handle {
+    border-top: 1px solid var(--border);
+    border-bottom: none;
+  }
+
+  /* #topbar: animate via max-height (height:auto can't be transitioned
+     directly) — generous enough to fit the wrapped multi-row mobile
+     topbar without clipping while expanded. */
+  #topbar {
+    max-height: 300px;
+    overflow: hidden;
+    transition: max-height 0.32s cubic-bezier(0.16, 1, 0.3, 1),
+      opacity 0.25s ease, padding 0.32s ease;
+  }
+
+  #topbar.mobile-collapsed {
+    max-height: 0;
+    min-height: 0;
+    opacity: 0;
+    padding-top: 0;
+    padding-bottom: 0;
+    border-bottom: none;
+    pointer-events: none;
+  }
+
+  /* #panel: min-height (not max-height) is what's actually holding the
+     stacked layout open at 180px — flex-grow:1 with min-height:0 here
+     collapses cleanly to nothing, and #canvas-wrap's own flex-grow:1
+     smoothly reclaims the freed space as this animates, growing the
+     graph to fill the screen exactly as it does when the panel is
+     genuinely empty. */
+  #panel {
+    transition: min-height 0.32s cubic-bezier(0.16, 1, 0.3, 1),
+      opacity 0.25s ease;
+  }
+
+  #panel.mobile-collapsed {
+    flex-grow: 0;
+    min-height: 0;
+    opacity: 0;
+    overflow: hidden;
+    pointer-events: none;
+  }
+}
+
+/* ─── Phones ─── */
+@media (max-width: 560px) {
+  /* Hero / landing */
+  #hero-title {
+    font-size: 38px;
+    letter-spacing: 4px;
+    margin-bottom: 10px;
+  }
+
+  #hero-tagline {
+    font-size: 9px;
+    letter-spacing: 3px;
+    margin-bottom: 30px;
+  }
+
+  #hero-sub {
+    font-size: 13px;
+    line-height: 1.7;
+    margin-bottom: 28px;
+    padding: 0 6px;
+  }
+
+  /* Inputs stack vertically; the arrow turns to point downward
+     and loses the desktop top-margin that aligned it beside the
+     labelled fields. align-items:stretch overrides the desktop
+     flex-start — without it, each .hero-field shrinks to its own
+     content width instead of spanning the column, so the FROM/TO
+     boxes end up narrower than the container and visibly off-centre
+     instead of forming one centred block. */
+  #hero-inputs {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 8px;
+    padding: 0 22px;
+    max-width: 420px;
+  }
+
+  .hero-field {
+    width: 100%;
+  }
+
+  .hero-field label {
+    text-align: center;
+  }
+
+  #hero-arrow {
+    margin: 2px 0 0;
+    align-self: center;
+    transform: rotate(90deg);
+  }
+
+  #hero-about-btn {
+    top: 12px;
+    right: 12px;
+    padding: 6px 13px;
+    font-size: 11px;
+  }
+
+  #hero-btn {
+    padding: 13px 44px;
+  }
+
+  /* Topbar logo wordmark is redundant next to the mark on a phone
+     — keep the icon, drop the text to save a lot of horizontal room. */
+  #topbar h1 {
+    font-size: 0;
+  }
+
+  #topbar h1 .topbar-logo-img {
+    height: 24px;
+    width: 24px;
+  }
+
+  /* Modals */
+  .modal-card {
+    padding: 24px 18px;
+    width: 94%;
+    max-height: 90vh;
+    overflow-y: auto;
+  }
+
+  .about-card {
+    padding: 26px 20px;
+  }
+
+  .modal-title {
+    font-size: 21px;
+  }
+
+  .modal-subtitle {
+    font-size: 13px;
+    margin-bottom: 22px;
+  }
+
+  .modal-stat-row {
+    gap: 22px;
+    margin: 14px 0 20px;
+  }
+
+  .modal-stat-val {
+    font-size: 26px;
+  }
+
+  .modal-path {
+    padding: 14px 14px;
+    gap: 6px;
+  }
+
+  /* About modal: tech cards go single-column; the comparison
+     table stays two columns but with tighter type so it still fits. */
+  .about-tech-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .about-compare-cell {
+    font-size: 11px;
+    padding: 8px 10px;
+  }
+
+  .about-compare-head {
+    font-size: 8px;
+    letter-spacing: 1.8px;
+    padding: 8px 10px;
+  }
+
+  .about-quote-text {
+    font-size: 14px;
+  }
+
+  .onboarding-card {
+    padding: 32px 24px 28px;
+  }
+}
+
+/* ─── Short / landscape phones: prefer dynamic viewport height so
+   mobile browser chrome (URL bar) doesn't clip the bottom of the
+   app. 100dvh is ignored by browsers that don't support it, falling
+   back to the 100vh set on body above. ─── */
+@media (max-width: 820px) {
+  body {
+    height: 100dvh;
+  }
+}

wiki.py

@@ -0,0 +1,313 @@
+"""
+Aurelius — Wikipedia API client: resolve, links, backlinks, summary,
+categories, and junk/date filters.
+
+Module split per architect plan §1. This is a literal relocation of the
+Wikipedia-facing functions previously in main.py (lines 99-103, 190-394,
+397-402 in the pre-split file) — no behavioral changes.
+"""
+
+import asyncio
+import re
+from typing import Optional
+from urllib.parse import unquote
+
+import httpx
+
+from config import WIKI_API, WIKI_HEADERS, MAX_FETCH, MAX_PAGES, SEED_FILE
+
+
+def make_wiki_client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(headers=WIKI_HEADERS, follow_redirects=True,
+                             timeout=httpx.Timeout(25.0))
+
+
+async def wiki_get(client: httpx.AsyncClient, params: dict, retries: int = 3) -> dict:
+    for attempt in range(retries + 1):
+        try:
+            r = await client.get(WIKI_API, params=params)
+            if r.status_code == 429:
+                await asyncio.sleep(min(2 ** attempt, 8)); continue
+            if r.status_code != 200:
+                return {}
+            return r.json()
+        except httpx.TimeoutException:
+            if attempt < retries: await asyncio.sleep(1)
+        except Exception as e:
+            print(f"[wiki] {e}"); return {}
+    return {}
+
+
+def extract_title_from_url(query: str) -> Optional[str]:
+    """If query is a Wikipedia URL, extract and decode the article title; else None."""
+    m = re.search(r'wikipedia\.org/wiki/([^#?\s]+)', query.strip())
+    if not m:
+        return None
+    return unquote(m.group(1)).replace('_', ' ').strip()
+
+
+async def resolve_article_title(client: httpx.AsyncClient, query: str) -> Optional[str]:
+    query = query.strip()
+    url_t = extract_title_from_url(query)
+    if url_t: query = url_t
+
+    data = await wiki_get(client, {"action":"query","titles":query,
+                                   "redirects":1,"format":"json","utf8":1})
+    for pid, page in data.get("query",{}).get("pages",{}).items():
+        if pid != "-1":
+            print(f"[resolve] Exact ✓ '{page['title']}'")
+            return page["title"]
+
+    data = await wiki_get(client, {"action":"opensearch","search":query,
+                                   "limit":10,"namespace":0,"format":"json","utf8":1})
+    titles = data[1] if isinstance(data, list) and len(data) > 1 else []
+    if titles:
+        for t in titles:
+            if t.lower() == query.lower(): return t
+        return titles[0]
+
+    data = await wiki_get(client, {"action":"query","list":"search","srsearch":query,
+                                   "srlimit":5,"srprop":"title","format":"json","utf8":1})
+    results = data.get("query",{}).get("search",[])
+    if results:
+        return results[0]["title"]
+    return None
+
+
+_DATE_RE = re.compile(
+    r'^\d{1,2} \w+$|^\w+ \d{1,2}$|^\d{4}$|^\d{4} in '
+    r'|^\d{1,2}\w* century'
+    r'|^(January|February|March|April|May|June|July|August|'
+    r'September|October|November|December)$'
+    r'|^\d{4}[-–]\d{2,4}$', re.IGNORECASE
+)
+def _is_date(t: str) -> bool:
+    return bool(_DATE_RE.search(t))
+
+_JUNK_TITLES = frozenset({
+    "Wayback Machine", "OCLC", "Digital object identifier", "CrossRef",
+    "JSTOR", "PubMed", "PubMed Central", "Semantic Scholar", "ArXiv",
+    "Bibcode", "CiteSeerX", "S2CID", "Zbl", "MR", "PMC",
+})
+def _is_junk(t: str) -> bool:
+    """Bibliographic citation artifacts: dead ends with 1-3 links each."""
+    return t.endswith("(identifier)") or t in _JUNK_TITLES
+
+async def get_all_links(client: httpx.AsyncClient, title: str,
+                        end_title: str = "",
+                        target_neighbours: set | None = None
+                        ) -> tuple[list[str], dict[str, str]]:
+    """
+    Fetch ALL links via pagination (up to MAX_FETCH), redirect-resolved to
+    canonical titles. Returns (links, short_descriptions).
+
+    Uses generator=links (not prop=links) + redirects=1 so that a link
+    written as e.g. "A* algorithm" in the wikitext comes back as its
+    canonical target "A* search algorithm" — MediaWiki's `redirects`
+    parameter resolves redirects in generator output, not just in the
+    `titles` input. Without this, the search graph carries raw,
+    possibly-redirect link titles, which silently breaks every canonical-
+    title comparison downstream (direct-hit check, the target-frontier
+    meeting check, de-duplication) — e.g. a redirect that happens to read
+    as semantically close to the target can look like a near-miss "hit"
+    when it never actually appears in the target's real backlink set.
+
+    Also requests prop=pageprops with ppprop=wikibase-shortdesc in the SAME
+    call (no extra round-trip) — Wikidata's one-line human-curated short
+    description (e.g. "Mesopotamian sky-god" for Anu). Bare-title embeddings
+    can't distinguish a proper noun's domain, which let semantically
+    unrelated but link-adjacent pages (Egyptian/Mesopotamian deities,
+    surahs) survive the prune floor on noisy title-only cosine. Embedding
+    "{title}. {short_desc}" instead gives the model the actual subject
+    matter to score against — see search.py's _rank_candidates.
+
+    Goal link is always included first if found.
+    Target neighbours always get priority slots.
+    Date/year stubs filtered unless list would be empty.
+
+    BUGFIX: when hunting for end_title, the old exit condition
+    (len(all_links) >= MAX_FETCH) stopped pagination after roughly the
+    first alphabetical page of a large article, so a goal link sorting
+    late in the alphabet (e.g. "Pakistan" on India's 1000+-link page)
+    was never found even though it's a direct 1-hop link. We now keep
+    paginating past MAX_FETCH while specifically searching for a goal,
+    bounded by MAX_PAGES as a safety cap. Calls with no end_title (e.g.
+    pre-seeding target neighbours) are unaffected — same stop condition
+    as before.
+    """
+    all_links:  list[str] = []
+    date_links: list[str] = []
+    goal_link:  str | None = None
+    short_desc: dict[str, str] = {}
+    end_lower = end_title.lower() if end_title else ""
+    params = {
+        "action": "query", "generator": "links", "redirects": 1,
+        "titles": title, "prop": "info|pageprops", "ppprop": "wikibase-shortdesc",
+        "gpllimit": 500, "gplnamespace": 0, "format": "json", "utf8": 1,
+    }
+    pages_fetched = 0
+    while True:
+        data = await wiki_get(client, params)
+        pages_fetched += 1
+        for page in data.get("query", {}).get("pages", {}).values():
+            if "missing" in page:
+                continue   # link target doesn't exist (red link)
+            t = page["title"]
+            sd = page.get("pageprops", {}).get("wikibase-shortdesc")
+            if sd:
+                short_desc[t] = sd
+            if end_lower and t.lower() == end_lower:
+                goal_link = t; continue
+            if _is_junk(t):
+                continue
+            if _is_date(t):
+                date_links.append(t)
+            else:
+                all_links.append(t)
+        cont = data.get("continue", {})
+        if "gplcontinue" not in cont:
+            break
+        if goal_link:
+            break   # found it — no need to keep paginating
+        if end_lower:
+            # Actively hunting a specific goal: keep going past MAX_FETCH,
+            # bounded only by MAX_PAGES (safety cap on API calls).
+            if pages_fetched >= MAX_PAGES:
+                break
+        else:
+            # No specific goal (e.g. pre-seeding neighbours): original behavior.
+            if len(all_links) + len(date_links) >= MAX_FETCH:
+                break
+        params["gplcontinue"] = cont["gplcontinue"]
+
+    result: list[str] = []
+    if goal_link:
+        result.append(goal_link)
+
+    tn = target_neighbours or set()
+    bridges = [l for l in all_links if l in tn]
+    rest    = [l for l in all_links if l not in tn]
+    result += bridges
+    result += rest
+    if len(result) < 5:
+        result += date_links[:max(0, 5 - len(result))]
+
+    return result[:MAX_FETCH], short_desc
+
+async def get_backlinks(client: httpx.AsyncClient, title: str,
+                        limit: int = MAX_FETCH) -> list[str]:
+    """
+    Fetch articles that link TO `title` (Wikipedia prop=linkshere) — the
+    correct direction for a forward-search bridge set.
+
+    get_all_links() returns what `title` points to. That is NOT useful as
+    a "one hop from target" bridge set, because Wikipedia links are not
+    reciprocal: target -> A does not imply A -> target. A backlink (B ->
+    target) is a guaranteed bridge — if the forward search ever reaches B,
+    expanding it is certain to find `target` in B's own outbound links.
+    Using outbound links here was sending the search on real-but-useless
+    detours (e.g. the "Star Wars" article links to "Star Destroyer", which
+    in turn links to real-world "Capital ship"/"Destroyer" articles for
+    etymology — those score high on the old outbound-based frontier but
+    don't link back to anything Star Wars-related themselves).
+    """
+    all_links:  list[str] = []
+    date_links: list[str] = []
+    params = {
+        "action": "query", "titles": title, "prop": "linkshere",
+        "lhlimit": 500, "lhnamespace": 0, "format": "json", "utf8": 1,
+    }
+    pages_fetched = 0
+    while True:
+        data = await wiki_get(client, params)
+        pages_fetched += 1
+        for page in data.get("query", {}).get("pages", {}).values():
+            for link in page.get("linkshere", []):
+                t = link["title"]
+                if _is_junk(t):
+                    continue
+                if _is_date(t):
+                    date_links.append(t)
+                else:
+                    all_links.append(t)
+        cont = data.get("continue", {})
+        if "lhcontinue" not in cont:
+            break
+        if len(all_links) + len(date_links) >= limit or pages_fetched >= MAX_PAGES:
+            break
+        params["lhcontinue"] = cont["lhcontinue"]
+    return (all_links + date_links)[:limit]
+
+async def check_disambiguation(client: httpx.AsyncClient, title: str) -> bool:
+    data = await wiki_get(client, {
+        "action": "query", "titles": title,
+        "prop": "pageprops", "ppprop": "disambiguation",
+        "format": "json", "utf8": 1,
+    })
+    for page in data.get("query", {}).get("pages", {}).values():
+        if "disambiguation" in page.get("pageprops", {}):
+            return True
+    return False
+
+
+async def get_link_display_text(client: httpx.AsyncClient, source_title: str,
+                                  target_title: str) -> Optional[str]:
+    """
+    Best-effort lookup of the visible text a wikilink uses on `source_title`
+    when it points to `target_title`, e.g. `[[Amber Road|routes]]` -> "routes".
+
+    Exists because get_all_links() (and therefore every edge in the search
+    graph) is built from MediaWiki's `links` API, which returns the
+    canonical link TARGET, never the piped display text. That's correct for
+    graph traversal, but it means a perfectly real edge can look fabricated
+    to a human skimming the rendered page for the target's title (e.g.
+    "Western world" -> "Amber Road": the link is real, but the article
+    displays it as "routes", so Ctrl+F for "Amber Road" finds nothing). See
+    CLAUDE.md's "Semantic drift" history entry for the earlier instance of
+    this same confusion ('Anu' -> 'Iteration').
+
+    Returns None if the link isn't piped, the display text matches the
+    title anyway, or the link couldn't be located in raw wikitext (e.g. it
+    comes from a transcluded template) — callers should treat None as
+    "nothing extra to show," not an error.
+    """
+    data = await wiki_get(client, {
+        "action": "parse", "page": source_title, "prop": "wikitext",
+        "format": "json", "utf8": 1,
+    })
+    wikitext = data.get("parse", {}).get("wikitext", {}).get("*", "")
+    if not wikitext:
+        return None
+
+    # Build the pattern from escaped words joined by a flexible separator —
+    # escaping the title whole and then substituting spaces for [ _]+
+    # doesn't work because re.escape() itself backslash-escapes the space,
+    # leaving a stray "\" that turns the substituted "[ _]+" into a literal
+    # bracket. Escaping word-by-word and joining avoids that entirely.
+    words = re.split(r"[ _]+", target_title)
+    target_pattern = r"[ _]+".join(re.escape(w) for w in words)
+    regex = re.compile(r"\[\[\s*" + target_pattern + r"\s*(?:\|([^\]]+))?\]\]", re.IGNORECASE)
+    match = regex.search(wikitext)
+    if not match or not match.group(1):
+        return None
+
+    display = re.sub(r"'{2,}", "", match.group(1)).strip()
+    if not display or display.lower().replace("_", " ") == target_title.lower().replace("_", " "):
+        return None
+    return display
+
+
+async def get_article_summary(client: httpx.AsyncClient, title: str) -> str:
+    data = await wiki_get(client, {"action":"query","titles":title,"prop":"extracts",
+                                   "exintro":True,"explaintext":True,
+                                   "exsentences":2,"format":"json","utf8":1})
+    for page in data.get("query",{}).get("pages",{}).values():
+        return page.get("extract","")[:220]
+    return ""
+
+def _load_seed_titles() -> list[str]:
+    """Read the curated topic list used by the Random button, one title per line."""
+    if not SEED_FILE.exists():
+        return []
+    with open(SEED_FILE, "r", encoding="utf-8") as f:
+        return [line.strip() for line in f if line.strip()]