Merge feature/umap-scatter into feat/folding-3d (local-only)

Combines the §6 UMAP scatter and §5 Folding work into one branch for
end-to-end local testing. To be split back into two separate PRs.

demo.html conflict resolution: kept §6 UMAP IIFE from umap-scatter,
kept the Canvas 2D banner comment from folding-3d (perf branch
already merged into main). No code changes, just a comment block.

Co-authored-by: Cursor <cursoragent@cursor.com>

app.py

@@ -4,6 +4,7 @@ import os
 
 import httpx
 from fastapi import FastAPI, Request
+from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.responses import FileResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from openai import OpenAI
@@ -69,6 +70,11 @@ def left_pad_to_six(seq: str) -> tuple[str, int]:
 
 
 app = FastAPI()
+# Compress responses >= 1 KB. Mostly aimed at /umap (~4 MB binary blob
+# → ~2 MB on the wire) and the JSON gene/variant/species catalogs.
+# compresslevel=6 is the gzip(1) system default — within ~3% of level 9
+# in ratio but ~5x cheaper in CPU. Worth it on every request.
+app.add_middleware(GZipMiddleware, minimum_size=1024, compresslevel=6)
 app.mount("/img", StaticFiles(directory=os.path.join(HERE, "img")), name="img")
 
 
@@ -108,6 +114,28 @@ def species():
     return FileResponse(os.path.join(HERE, "data", "species.json"), media_type="application/json")
 
 
+@app.get("/umap")
+def umap():
+    """Binary packed scatter (int16 positions + uint8 categories) for §6.
+
+    The §6 frontend fetches this as an ArrayBuffer and feeds it straight
+    into WebGL — no JSON parse, no per-point allocations. See
+    scripts/gen_fake_umap.py for the binary layout.
+    """
+    return FileResponse(
+        os.path.join(HERE, "data", "umap.bin"),
+        media_type="application/octet-stream",
+    )
+
+
+@app.get("/umap_labels")
+def umap_labels():
+    return FileResponse(
+        os.path.join(HERE, "data", "umap_labels.json"),
+        media_type="application/json",
+    )
+
+
 @app.post("/score")
 async def score(request: Request):
     """Return per-token logprobs over a (forced) sequence using echo=True.

data/umap.bin

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

data/umap_labels.json

@@ -0,0 +1,84 @@
+{
+  "species": [
+    "human",
+    "mouse",
+    "rat",
+    "chicken",
+    "zebrafish",
+    "xenopus",
+    "dog",
+    "cow",
+    "pig",
+    "fly",
+    "worm",
+    "mosquito",
+    "honeybee",
+    "sea_urchin",
+    "arabidopsis",
+    "rice",
+    "maize",
+    "wheat",
+    "soybean",
+    "yeast",
+    "neurospora",
+    "candida",
+    "plasmodium",
+    "trypanosoma"
+  ],
+  "biotypes": [
+    "protein_coding",
+    "lncRNA",
+    "miRNA",
+    "pseudogene"
+  ],
+  "strands": [
+    "+",
+    "-"
+  ],
+  "phases": [
+    "0",
+    "1",
+    "2"
+  ],
+  "species_kingdom": {
+    "human": "vertebrates",
+    "mouse": "vertebrates",
+    "rat": "vertebrates",
+    "chicken": "vertebrates",
+    "zebrafish": "vertebrates",
+    "xenopus": "vertebrates",
+    "dog": "vertebrates",
+    "cow": "vertebrates",
+    "pig": "vertebrates",
+    "fly": "invertebrates",
+    "worm": "invertebrates",
+    "mosquito": "invertebrates",
+    "honeybee": "invertebrates",
+    "sea_urchin": "invertebrates",
+    "arabidopsis": "plants",
+    "rice": "plants",
+    "maize": "plants",
+    "wheat": "plants",
+    "soybean": "plants",
+    "yeast": "fungi",
+    "neurospora": "fungi",
+    "candida": "fungi",
+    "plasmodium": "protozoa",
+    "trypanosoma": "protozoa"
+  },
+  "kingdoms": [
+    "vertebrates",
+    "invertebrates",
+    "plants",
+    "fungi",
+    "protozoa"
+  ],
+  "bounds": [
+    -19.07978630065918,
+    17.736162185668945,
+    -15.417572021484375,
+    16.83187484741211
+  ],
+  "n_points": 500000,
+  "fake": true
+}

demo.html

@@ -291,6 +291,77 @@
     font-size: 9px; color: #aaa; margin-bottom: 8px;
   }
 
+  /* --- UMAP scatter specifics (§6) --- */
+  .umap-frame {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 10;
+    background: #fff;
+    border: 1px solid #eee;
+    overflow: hidden;
+  }
+  .umap-canvas {
+    position: absolute; inset: 0;
+    width: 100%; height: 100%;
+    display: block;
+    cursor: grab;
+    touch-action: none;
+  }
+  .umap-canvas.panning { cursor: grabbing; }
+  .umap-tooltip {
+    position: absolute;
+    pointer-events: none;
+    background: #1f1f1d; color: #f7f5ee;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 10px; line-height: 1.4;
+    padding: 6px 9px;
+    border-radius: 2px;
+    white-space: nowrap;
+    opacity: 0;
+    transform: translate(8px, -100%);
+    transition: opacity 0.12s;
+    z-index: 4;
+  }
+  .umap-tooltip.visible { opacity: 0.96; }
+  .umap-tooltip .t-label {
+    color: #8c918b;
+    text-transform: uppercase; letter-spacing: 1px;
+    font-size: 8px;
+    margin-right: 4px;
+  }
+  .umap-status-overlay {
+    position: absolute; inset: 0;
+    display: flex; align-items: center; justify-content: center;
+    color: #aaa;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 11px; letter-spacing: 1.5px;
+    text-transform: uppercase;
+    background: rgba(247, 245, 238, 0.85);
+    pointer-events: none;
+    transition: opacity 0.2s;
+  }
+  .umap-status-overlay.hidden { opacity: 0; }
+  .umap-legend {
+    display: flex; flex-wrap: wrap;
+    gap: 6px 14px;
+    margin-top: 10px;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 10px;
+    color: #666;
+  }
+  .umap-legend .swatch {
+    display: inline-block;
+    width: 9px; height: 9px;
+    margin-right: 5px;
+    vertical-align: middle;
+    border-radius: 2px;
+  }
+  .umap-legend .item {
+    display: inline-flex;
+    align-items: center;
+    cursor: default;
+  }
+
   /* --- Gene-completion specifics (§1) --- */
   .gene-info {
     font-family: "JetBrains Mono", monospace;
@@ -1081,21 +1152,57 @@
 </section>
 
 <!-- ============================================================ -->
-<!-- §6 — UMAP (stub, coming soon)                                -->
+<!-- §6 — UMAP (interactive scatter)                              -->
 <!-- ============================================================ -->
 <section id="umap">
-  <div class="section-num">§6 · Coming soon</div>
+  <div class="section-num">§6 · Embedding space</div>
   <div class="section-title">The genome, organized</div>
   <p class="lede">
-    Embed every human gene with Carbon, project to 2D with UMAP, color by gene family, function,
-    or species. Genes the model never saw labeled cluster anyway — kinases with kinases,
-    histones with histones, mitochondrial DNA off in its own corner. The structure of biology
-    falls out of the structure of sequence.
+    Embed half a million sequences from 24 eukaryotes with Carbon, project to 2D
+    with UMAP, color by anything. Switch the coloring and a completely different
+    organization emerges from the same points — the model's embedding space
+    carries multiple axes of biology at once, none of which were ever labeled.
   </p>
 
-  <div class="stub" style="padding:64px 24px">
-    <div class="stub-tag">coming soon</div>
-    <div style="margin-top:6px">interactive UMAP of carbon embeddings · ~20k human genes</div>
+  <div class="demo" id="demoUmap">
+    <div class="demo-toolbar">
+      <span>color by</span>
+      <span id="dumap-color-pills" class="pills">
+        <button class="pill active" data-color="species">species</button>
+        <button class="pill" data-color="biotype">biotype</button>
+        <button class="pill" data-color="strand">strand</button>
+        <button class="pill" data-color="phase">codon phase</button>
+      </span>
+      <span class="spacer"></span>
+      <button id="dumap-reset" class="action">↺ reset view</button>
+      <span class="status" id="dumap-status"><span class="dot"></span><span>idle</span></span>
+    </div>
+
+    <div class="gene-info" id="dumap-info">scroll to zoom · drag to pan · hover for details</div>
+
+    <div class="umap-frame">
+      <canvas class="umap-canvas" id="dumap-canvas"></canvas>
+      <div class="umap-tooltip" id="dumap-tooltip"></div>
+      <div class="umap-status-overlay" id="dumap-overlay">loading 500K points · ~2 MB gzipped</div>
+    </div>
+
+    <div class="umap-legend" id="dumap-legend"></div>
+
+    <div class="stat-row" id="dumap-stats">
+      <div class="stat-pair"><span class="stat-pair-label">points</span><span class="stat-pair-val muted" id="dumap-n">—</span></div>
+      <div class="stat-pair"><span class="stat-pair-label">species</span><span class="stat-pair-val muted" id="dumap-nsp">—</span></div>
+      <div class="stat-pair"><span class="stat-pair-label">embedding dim</span><span class="stat-pair-val muted">3072</span></div>
+      <div class="stat-pair"><span class="stat-pair-label">render</span><span class="stat-pair-val muted" id="dumap-fps">—</span></div>
+    </div>
+  </div>
+
+  <div class="takeaway">
+    <strong>What to look for</strong>
+    Switch coloring from <em>species</em> to <em>biotype</em>: same points, completely
+    different organization emerges. The five rough macro-clusters trace the eukaryotic
+    kingdoms — vertebrates, invertebrates, plants, fungi, protozoa — discovered from
+    raw sequence alone. <em>The current 500K dataset is synthetic, awaiting the real
+    Carbon 3B embeddings.</em>
   </div>
 </section>
 
@@ -3880,6 +3987,507 @@ function loadGenes() {
   }
 })();
 
+// =========================================================================
+// §6 — UMAP scatter (WebGL, 500K points)
+//
+// Loads a binary-packed scatter (int16 quantized positions + 4 uint8 category
+// columns) and renders it via WebGL gl.POINTS with a 1D palette texture for
+// coloring. Toggle between coloring axes (species / biotype / strand / phase)
+// rebinds a single byte-attribute buffer and swaps the palette texture — no
+// re-upload of the 500K vertex stream. Hover lookup uses a flat grid index
+// so picking stays O(small) regardless of total point count.
+// =========================================================================
+(function initDemoUmap() {
+  const canvas = document.getElementById("dumap-canvas");
+  if (!canvas) return;
+  const tooltip = document.getElementById("dumap-tooltip");
+  const overlay = document.getElementById("dumap-overlay");
+  const info    = document.getElementById("dumap-info");
+  const legend  = document.getElementById("dumap-legend");
+  const resetBtn = document.getElementById("dumap-reset");
+  const status   = document.getElementById("dumap-status");
+  const statusText = status.querySelector("span:last-child");
+  const colorPills = document.querySelectorAll("#dumap-color-pills .pill");
+  const elN   = document.getElementById("dumap-n");
+  const elNsp = document.getElementById("dumap-nsp");
+  const elFps = document.getElementById("dumap-fps");
+
+  // ---- Palettes ----------------------------------------------------------
+  // 24 species are grouped into 5 kingdoms — each kingdom gets a hue band.
+  // Within a band, lightness varies to keep adjacent species distinguishable.
+  const SPECIES_PALETTE = [
+    // vertebrates (9) — blue/indigo band
+    [69,117,180],[97,144,200],[125,170,220],[153,194,240],
+    [120,90,170],[140,110,190],
+    [80,90,150],[100,110,170],[120,130,190],
+    // invertebrates (5) — orange band
+    [217,95,2],[230,120,30],[240,150,60],[250,180,90],[253,210,120],
+    // plants (5) — olive/lime band (intentionally different from Carbon's
+    // signal-green #317f3f so the UI chrome doesn't blend with the data)
+    [85,140,55],[115,165,75],[145,195,100],[175,220,135],[205,240,170],
+    // fungi (3) — magenta/rose band
+    [200,40,120],[220,80,140],[240,130,170],
+    // protozoa (2) — gold band
+    [200,150,30],[230,180,60],
+  ];
+  const BIOTYPE_PALETTE = [
+    [49,127,63],   // protein_coding — Carbon green
+    [188,46,37],   // lncRNA          — Carbon red
+    [70,90,140],   // miRNA           — slate blue
+    [170,170,170], // pseudogene      — neutral gray
+  ];
+  const STRAND_PALETTE = [
+    [49,127,63],   // + (forward)
+    [188,46,37],   // - (reverse)
+  ];
+  // 3-step ordinal palette (viridis-ish endpoints) — codon phase 0/1/2.
+  const PHASE_PALETTE = [
+    [68,1,84], [33,144,140], [253,231,37],
+  ];
+  const PALETTES = {
+    species: SPECIES_PALETTE,
+    biotype: BIOTYPE_PALETTE,
+    strand:  STRAND_PALETTE,
+    phase:   PHASE_PALETTE,
+  };
+
+  // ---- State -------------------------------------------------------------
+  let gl, program;
+  let posBuf;                          // int16 interleaved x,y
+  let catBufs = {};                    // { species|biotype|strand|phase: GLBuffer of uint8 }
+  let paletteTex;
+  let n = 0;
+  let labels = null;                   // { species:[], biotypes:[], strands:[], phases:[], bounds:[xmin,xmax,ymin,ymax] }
+  // Raw category bytes — kept on CPU side too for tooltip lookups.
+  let cats = { species: null, biotype: null, strand: null, phase: null };
+  // World bounds + current colorBy axis.
+  let bounds = [0,0,0,0];
+  let colorBy = "species";
+  // Viewport: translate (tx, ty) + scale around origin, in NDC space.
+  // The whole world is fit into [-0.95, 0.95]² at initial zoom.
+  let view = { tx: 0, ty: 0, scale: 1 };
+  let dpr = Math.max(1, window.devicePixelRatio || 1);
+  let needsRedraw = false;
+  // Spatial grid for hover (built once after data load, in normalized world space).
+  let grid = null;
+
+  function setStatus(state, text) {
+    status.classList.remove("streaming", "error");
+    if (state === "streaming") status.classList.add("streaming");
+    if (state === "error")     status.classList.add("error");
+    statusText.textContent = text;
+  }
+
+  // ---- WebGL setup -------------------------------------------------------
+  const VS = `
+    attribute vec2 a_pos;          // raw int16, normalized via attribPointer (-1..1)
+    attribute float a_cat;         // category index (uint8 -> float)
+    uniform vec3 u_xform;          // x: scale, y: tx, z: ty
+    uniform float u_pointSize;
+    varying float v_cat;
+    void main() {
+      vec2 world = a_pos * u_xform.x + vec2(u_xform.y, u_xform.z);
+      gl_Position = vec4(world, 0.0, 1.0);
+      gl_PointSize = u_pointSize;
+      v_cat = a_cat;
+    }
+  `;
+  const FS = `
+    precision mediump float;
+    varying float v_cat;
+    uniform sampler2D u_palette;
+    uniform float u_paletteN;
+    uniform float u_alpha;
+    void main() {
+      vec2 d = gl_PointCoord - 0.5;
+      float r = length(d);
+      float aa = smoothstep(0.50, 0.42, r);
+      if (aa <= 0.001) discard;
+      float t = (v_cat + 0.5) / u_paletteN;
+      vec3 color = texture2D(u_palette, vec2(t, 0.5)).rgb;
+      gl_FragColor = vec4(color, aa * u_alpha);
+    }
+  `;
+  function compile(type, src) {
+    const sh = gl.createShader(type);
+    gl.shaderSource(sh, src);
+    gl.compileShader(sh);
+    if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+      throw new Error("shader compile: " + gl.getShaderInfoLog(sh));
+    }
+    return sh;
+  }
+  function setupGL() {
+    gl = canvas.getContext("webgl", {
+      antialias: true, alpha: true, premultipliedAlpha: true,
+      preserveDrawingBuffer: false,
+    });
+    if (!gl) throw new Error("WebGL unavailable");
+    program = gl.createProgram();
+    gl.attachShader(program, compile(gl.VERTEX_SHADER, VS));
+    gl.attachShader(program, compile(gl.FRAGMENT_SHADER, FS));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      throw new Error("program link: " + gl.getProgramInfoLog(program));
+    }
+    gl.useProgram(program);
+
+    // Standard premultiplied-alpha additive-ish blending — points blend over
+    // the paper background and over each other cleanly at dense overlaps.
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+    gl.clearColor(1, 1, 1, 0);
+
+    paletteTex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, paletteTex);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  }
+
+  function uploadPalette(palette) {
+    const n = palette.length;
+    const buf = new Uint8Array(n * 3);
+    for (let i = 0; i < n; i++) {
+      buf[i*3]   = palette[i][0];
+      buf[i*3+1] = palette[i][1];
+      buf[i*3+2] = palette[i][2];
+    }
+    gl.bindTexture(gl.TEXTURE_2D, paletteTex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, n, 1, 0, gl.RGB, gl.UNSIGNED_BYTE, buf);
+    gl.uniform1f(gl.getUniformLocation(program, "u_paletteN"), n);
+  }
+
+  // ---- Data load ---------------------------------------------------------
+  async function loadData() {
+    setStatus("streaming", "loading…");
+    const t0 = performance.now();
+    const [binResp, labelsResp] = await Promise.all([
+      fetch("/umap"),
+      fetch("/umap_labels"),
+    ]);
+    if (!binResp.ok) throw new Error("fetch /umap failed: " + binResp.status);
+    const buf = await binResp.arrayBuffer();
+    labels = await labelsResp.json();
+
+    // Parse header (matches scripts/gen_fake_umap.py).
+    const hdrU32 = new Uint32Array(buf, 0, 6);
+    const magic = hdrU32[0];
+    if (magic !== 0xCAB0FA1D) throw new Error("bad magic: " + magic.toString(16));
+    n = hdrU32[1];
+    const nSp = hdrU32[2], nBt = hdrU32[3], nSt = hdrU32[4], nPh = hdrU32[5];
+    const hdrF32 = new Float32Array(buf, 24, 4);
+    bounds = [hdrF32[0], hdrF32[1], hdrF32[2], hdrF32[3]];
+
+    let off = 40;
+    const pos16 = new Int16Array(buf, off, n * 2);  off += n * 2 * 2;
+    cats.species = new Uint8Array(buf, off, n);     off += n;
+    cats.biotype = new Uint8Array(buf, off, n);     off += n;
+    cats.strand  = new Uint8Array(buf, off, n);     off += n;
+    cats.phase   = new Uint8Array(buf, off, n);     off += n;
+
+    // Upload to GPU.
+    posBuf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, posBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, pos16, gl.STATIC_DRAW);
+    for (const key of ["species", "biotype", "strand", "phase"]) {
+      const b = gl.createBuffer();
+      gl.bindBuffer(gl.ARRAY_BUFFER, b);
+      gl.bufferData(gl.ARRAY_BUFFER, cats[key], gl.STATIC_DRAW);
+      catBufs[key] = b;
+    }
+
+    // Wire attributes (position is constant; category attribute is rebound on toggle).
+    const posLoc = gl.getAttribLocation(program, "a_pos");
+    gl.bindBuffer(gl.ARRAY_BUFFER, posBuf);
+    gl.enableVertexAttribArray(posLoc);
+    // normalize=true → int16 mapped to [-1, 1] in shader — exactly the
+    // quantization we did in the Python packer.
+    gl.vertexAttribPointer(posLoc, 2, gl.SHORT, true, 0, 0);
+
+    // Build spatial grid (in [-1, 1]² normalized world space).
+    buildGrid(pos16);
+
+    elN.textContent   = n.toLocaleString("en-US");
+    elN.classList.remove("muted");
+    elNsp.textContent = labels.species.length;
+    elNsp.classList.remove("muted");
+
+    const ms = (performance.now() - t0) | 0;
+    setStatus("idle", `loaded ${(n/1000)|0}k pts · ${ms} ms`);
+    info.textContent = `${n.toLocaleString("en-US")} sequences · ${labels.species.length} eukaryotic species · drag to pan, wheel to zoom`;
+    overlay.classList.add("hidden");
+
+    return pos16;
+  }
+
+  // ---- Spatial grid (hover picking) --------------------------------------
+  // We store, per cell, a list of point indices whose normalized (x,y) falls
+  // in that cell. At hover, look up the cell under the cursor plus the 8
+  // neighbors, then scan for the nearest point within a screen-space radius.
+  const GRID_N = 128;
+  function buildGrid(pos16) {
+    const cells = new Array(GRID_N * GRID_N);
+    for (let i = 0; i < cells.length; i++) cells[i] = null;
+    for (let i = 0; i < n; i++) {
+      // pos16 entries are in [-32767, 32767] → normalize to [0, GRID_N).
+      const x = (pos16[2*i]     + 32767) / 65534;
+      const y = (pos16[2*i + 1] + 32767) / 65534;
+      const cx = Math.min(GRID_N - 1, Math.max(0, (x * GRID_N) | 0));
+      const cy = Math.min(GRID_N - 1, Math.max(0, (y * GRID_N) | 0));
+      const id = cy * GRID_N + cx;
+      const list = cells[id];
+      if (list === null) cells[id] = [i];
+      else list.push(i);
+    }
+    grid = cells;
+  }
+
+  // ---- Render ------------------------------------------------------------
+  function resize() {
+    const rect = canvas.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return false;
+    dpr = Math.max(1, window.devicePixelRatio || 1);
+    const w = Math.round(rect.width  * dpr);
+    const h = Math.round(rect.height * dpr);
+    if (canvas.width !== w || canvas.height !== h) {
+      canvas.width = w; canvas.height = h;
+    }
+    gl.viewport(0, 0, w, h);
+    return true;
+  }
+
+  let lastFrameTs = 0, frameCount = 0, fpsTs = 0;
+  function draw() {
+    needsRedraw = false;
+    if (!resize()) return;
+    gl.clear(gl.COLOR_BUFFER_BIT);
+
+    // The vertex shader does world = pos * scale + (tx, ty). We choose scale
+    // so the data (normalized to [-1, 1]) fits in [-0.92, 0.92] of NDC at
+    // zoom 1, with a tiny margin so points at the edge aren't clipped.
+    const baseScale = 0.92;
+    gl.uniform3f(gl.getUniformLocation(program, "u_xform"),
+                 baseScale * view.scale, view.tx, view.ty);
+    // Point size scales sub-linearly with zoom — denser areas stay readable
+    // but the dots get visibly bigger when you zoom in.
+    const ps = Math.min(8.0, Math.max(1.4, 1.4 + 0.6 * Math.log2(view.scale + 1))) * dpr;
+    gl.uniform1f(gl.getUniformLocation(program, "u_pointSize"), ps);
+    // Alpha falls off slightly with zoom-out so the dense cloud doesn't burn.
+    const alpha = Math.min(0.85, Math.max(0.35, 0.35 + 0.18 * Math.log2(view.scale + 1)));
+    gl.uniform1f(gl.getUniformLocation(program, "u_alpha"), alpha);
+
+    gl.drawArrays(gl.POINTS, 0, n);
+
+    // FPS counter — sampled, not per-frame.
+    const now = performance.now();
+    frameCount++;
+    if (now - fpsTs > 500) {
+      const fps = (frameCount * 1000) / (now - fpsTs);
+      elFps.textContent = `${fps.toFixed(0)} fps`;
+      elFps.classList.remove("muted");
+      fpsTs = now;
+      frameCount = 0;
+    }
+    lastFrameTs = now;
+  }
+  function requestRedraw() {
+    if (needsRedraw) return;
+    needsRedraw = true;
+    requestAnimationFrame(draw);
+  }
+
+  // ---- Color toggle ------------------------------------------------------
+  function setColorBy(key) {
+    colorBy = key;
+    const catLoc = gl.getAttribLocation(program, "a_cat");
+    gl.bindBuffer(gl.ARRAY_BUFFER, catBufs[key]);
+    gl.enableVertexAttribArray(catLoc);
+    // Unnormalized — we want the raw byte value in the shader.
+    gl.vertexAttribPointer(catLoc, 1, gl.UNSIGNED_BYTE, false, 0, 0);
+    uploadPalette(PALETTES[key]);
+    renderLegend();
+    requestRedraw();
+  }
+
+  // ---- Legend ------------------------------------------------------------
+  function renderLegend() {
+    if (!labels) return;
+    const palette = PALETTES[colorBy];
+    const itemLabels = (colorBy === "species") ? labels.species
+                     : (colorBy === "biotype") ? labels.biotypes
+                     : (colorBy === "strand")  ? labels.strands
+                     :                            labels.phases;
+    legend.innerHTML = itemLabels.map((name, i) => {
+      const [r, g, b] = palette[i % palette.length];
+      return `<span class="item"><span class="swatch" style="background:rgb(${r},${g},${b})"></span>${name}</span>`;
+    }).join("");
+  }
+
+  // ---- Pan / zoom / hover ------------------------------------------------
+  function resetView() { view = { tx: 0, ty: 0, scale: 1 }; requestRedraw(); }
+
+  // Convert a clientX/Y to NDC (-1..1) and to normalized data space ([-1, 1]).
+  function clientToNDC(e) {
+    const rect = canvas.getBoundingClientRect();
+    return {
+      x:  ((e.clientX - rect.left) / rect.width)  * 2 - 1,
+      y: -((e.clientY - rect.top)  / rect.height) * 2 + 1,
+    };
+  }
+  function ndcToData(ndc) {
+    const baseScale = 0.92;
+    return {
+      x: (ndc.x - view.tx) / (baseScale * view.scale),
+      y: (ndc.y - view.ty) / (baseScale * view.scale),
+    };
+  }
+
+  let panning = false, panLast = null;
+  canvas.addEventListener("pointerdown", e => {
+    canvas.setPointerCapture(e.pointerId);
+    panning = true;
+    panLast = { x: e.clientX, y: e.clientY };
+    canvas.classList.add("panning");
+    hideTooltip();
+  });
+  canvas.addEventListener("pointermove", e => {
+    if (panning) {
+      const rect = canvas.getBoundingClientRect();
+      const dx =  ((e.clientX - panLast.x) / rect.width)  * 2;
+      const dy = -((e.clientY - panLast.y) / rect.height) * 2;
+      view.tx += dx; view.ty += dy;
+      panLast = { x: e.clientX, y: e.clientY };
+      requestRedraw();
+    } else {
+      handleHover(e);
+    }
+  });
+  function endPan(e) {
+    if (!panning) return;
+    panning = false;
+    canvas.classList.remove("panning");
+    try { canvas.releasePointerCapture(e.pointerId); } catch {}
+  }
+  canvas.addEventListener("pointerup", endPan);
+  canvas.addEventListener("pointercancel", endPan);
+  canvas.addEventListener("pointerleave", () => hideTooltip());
+
+  canvas.addEventListener("wheel", e => {
+    e.preventDefault();
+    const ndc = clientToNDC(e);
+    // Zoom factor — natural feeling on both trackpad and mouse wheel.
+    const factor = Math.exp(-e.deltaY * 0.0018);
+    const newScale = Math.min(50, Math.max(0.5, view.scale * factor));
+    const k = newScale / view.scale;
+    // Zoom around the cursor: shift translate so the point under the cursor
+    // stays under the cursor.
+    view.tx = ndc.x - (ndc.x - view.tx) * k;
+    view.ty = ndc.y - (ndc.y - view.ty) * k;
+    view.scale = newScale;
+    requestRedraw();
+    hideTooltip();
+  }, { passive: false });
+
+  resetBtn.addEventListener("click", resetView);
+
+  // ---- Hover picking -----------------------------------------------------
+  function showTooltip(idx, x, y) {
+    const sp = labels.species[cats.species[idx]];
+    const bt = labels.biotypes[cats.biotype[idx]];
+    const st = labels.strands[cats.strand[idx]];
+    const ph = labels.phases[cats.phase[idx]];
+    tooltip.innerHTML =
+      `<div><span class="t-label">species</span>${sp}</div>` +
+      `<div><span class="t-label">biotype</span>${bt}</div>` +
+      `<div><span class="t-label">strand</span>${st} &nbsp; <span class="t-label">phase</span>${ph}</div>`;
+    tooltip.style.left = x + "px";
+    tooltip.style.top  = y + "px";
+    tooltip.classList.add("visible");
+  }
+  function hideTooltip() { tooltip.classList.remove("visible"); }
+
+  function handleHover(e) {
+    if (!grid) return;
+    const ndc = clientToNDC(e);
+    const data = ndcToData(ndc);
+    // Convert data-space (-1..1) into grid coords.
+    const gx = (data.x + 1) * 0.5 * GRID_N;
+    const gy = (data.y + 1) * 0.5 * GRID_N;
+    const cx = Math.floor(gx), cy = Math.floor(gy);
+    if (cx < -1 || cx > GRID_N || cy < -1 || cy > GRID_N) return hideTooltip();
+
+    // Adaptive search radius: at higher zoom, we want a tighter pick radius.
+    // ~8px screen radius converted to data space.
+    const rect = canvas.getBoundingClientRect();
+    const screenR = 8;
+    const dataR = (screenR / rect.width) * 2 / (0.92 * view.scale);
+    const dataR2 = dataR * dataR;
+
+    let best = -1, bestD2 = dataR2;
+    const cellSpan = Math.max(1, Math.ceil(dataR * GRID_N * 0.5) + 1);
+    for (let dy = -cellSpan; dy <= cellSpan; dy++) {
+      const yy = cy + dy;
+      if (yy < 0 || yy >= GRID_N) continue;
+      for (let dx = -cellSpan; dx <= cellSpan; dx++) {
+        const xx = cx + dx;
+        if (xx < 0 || xx >= GRID_N) continue;
+        const list = grid[yy * GRID_N + xx];
+        if (!list) continue;
+        for (let k = 0; k < list.length; k++) {
+          const idx = list[k];
+          // Recompute the point's normalized [-1, 1] position from posBuf16
+          // — we don't keep it on CPU, but we can re-derive from int16 cheaply.
+          const px = posSnapshot[2*idx]     / 32767;
+          const py = posSnapshot[2*idx + 1] / 32767;
+          const ex = px - data.x, ey = py - data.y;
+          const d2 = ex*ex + ey*ey;
+          if (d2 < bestD2) { bestD2 = d2; best = idx; }
+        }
+      }
+    }
+    if (best === -1) return hideTooltip();
+    // Place tooltip near cursor, offset to the right & above.
+    const relX = e.clientX - rect.left;
+    const relY = e.clientY - rect.top;
+    showTooltip(best, relX, relY);
+  }
+
+  // We need an unattached CPU-side copy of positions for hover hit-testing
+  // because WebGL buffers aren't readable from JS without a roundtrip.
+  let posSnapshot = null;
+
+  // ---- Bootstrap ---------------------------------------------------------
+  setupGL();
+
+  colorPills.forEach(p => {
+    p.addEventListener("click", () => {
+      colorPills.forEach(x => x.classList.toggle("active", x === p));
+      setColorBy(p.dataset.color);
+    });
+  });
+
+  // Defer loading until the umap section is near the viewport — 500K points
+  // doesn't need to fight for bandwidth on first paint.
+  const io = new IntersectionObserver(async (entries) => {
+    if (!entries[0].isIntersecting) return;
+    io.disconnect();
+    try {
+      const pos16 = await loadData();
+      posSnapshot = pos16;
+      setColorBy("species");  // initial coloring + first draw
+    } catch (err) {
+      console.error(err);
+      setStatus("error", "load failed");
+      overlay.textContent = "load failed · " + err.message;
+    }
+  }, { rootMargin: "400px" });
+  io.observe(canvas);
+
+  window.addEventListener("resize", () => requestRedraw());
+})();
+
 // =========================================================================
 // Carbon banner — animated DNA helix (Canvas 2D)
 //

scripts/gen_fake_umap.py

@@ -0,0 +1,219 @@
+"""Generate a fake UMAP scatter dataset for prototyping the §6 viewer.
+
+The real embedding-UMAP output (from Dana's Carbon 3B pipeline) will land
+in roughly the same shape. Until then, this gives us a 500K-point fixture
+to develop the WebGL frontend at target scale, so we don't discover
+performance cliffs later.
+
+Layout strategy:
+  - 24 eukaryotic species grouped into 5 kingdoms (vertebrates, invertebrates,
+    plants, fungi, protozoa). Kingdom centers are placed evenly around a
+    radius-12 circle in UMAP space, with species centers jittered nearby.
+  - Each point is drawn from a 2D Gaussian around its species center.
+  - Biotype, strand, and codon phase are roughly orthogonal axes — toggling
+    color in the UI reveals different organizations of the same points.
+  - Points are output sorted by species so gzip can RLE the category columns
+    aggressively (typically 90%+ compression on those bytes).
+
+Binary layout (little-endian, 40-byte header + ~4 MB payload for 500K pts):
+  uint32  magic        0xCAB0FA1D
+  uint32  n_points
+  uint32  n_species
+  uint32  n_biotypes
+  uint32  n_strands
+  uint32  n_phases
+  float32 x_min, x_max, y_min, y_max         (16 bytes — for de-quantization)
+  int16   positions[n_points * 2]            (interleaved x,y; quantized)
+  uint8   species[n_points]
+  uint8   biotype[n_points]
+  uint8   strand[n_points]
+  uint8   phase[n_points]
+
+Usage:
+    python scripts/gen_fake_umap.py
+"""
+import array
+import json
+import math
+import os
+import random
+import struct
+import sys
+import time
+
+# --- Dataset shape ---------------------------------------------------------
+
+N_POINTS = 500_000
+SEED = 42
+
+# 24 eukaryotic species — matches the rough scale of the real run (24 species
+# from Leandro's Gemini-annotated set, 500/species in Dana's first batch).
+SPECIES = [
+    # Vertebrates
+    "human", "mouse", "rat", "chicken", "zebrafish", "xenopus",
+    "dog", "cow", "pig",
+    # Invertebrates
+    "fly", "worm", "mosquito", "honeybee", "sea_urchin",
+    # Plants
+    "arabidopsis", "rice", "maize", "wheat", "soybean",
+    # Fungi
+    "yeast", "neurospora", "candida",
+    # Protozoa
+    "plasmodium", "trypanosoma",
+]
+
+KINGDOMS = {
+    "vertebrates":   ["human", "mouse", "rat", "chicken", "zebrafish", "xenopus",
+                      "dog", "cow", "pig"],
+    "invertebrates": ["fly", "worm", "mosquito", "honeybee", "sea_urchin"],
+    "plants":        ["arabidopsis", "rice", "maize", "wheat", "soybean"],
+    "fungi":         ["yeast", "neurospora", "candida"],
+    "protozoa":      ["plasmodium", "trypanosoma"],
+}
+
+BIOTYPES = ["protein_coding", "lncRNA", "miRNA", "pseudogene"]
+# Roughly realistic frequencies for a mixed eukaryote set.
+BIOTYPE_WEIGHTS = [0.70, 0.15, 0.08, 0.07]
+
+STRANDS = ["+", "-"]
+PHASES = ["0", "1", "2"]
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DATA = os.path.join(os.path.dirname(HERE), "data")
+
+# --- Generation ------------------------------------------------------------
+
+
+def species_centers():
+    """Pick a UMAP-space center for each species, kingdom by kingdom."""
+    centers = {}
+    kingdom_names = list(KINGDOMS.keys())
+    for i, kingdom in enumerate(kingdom_names):
+        # Kingdom center placed evenly around a circle.
+        cx = math.cos(2 * math.pi * i / len(kingdom_names)) * 12.0
+        cy = math.sin(2 * math.pi * i / len(kingdom_names)) * 12.0
+        for sp in KINGDOMS[kingdom]:
+            ox = random.gauss(0, 1.8)
+            oy = random.gauss(0, 1.8)
+            centers[sp] = (cx + ox, cy + oy)
+    return centers
+
+
+def weighted_choice_idx(weights):
+    """Faster than random.choices() for tight loops — returns the index."""
+    r = random.random()
+    acc = 0.0
+    for i, w in enumerate(weights):
+        acc += w
+        if r < acc:
+            return i
+    return len(weights) - 1
+
+
+def generate():
+    """Produce all per-point data as parallel arrays (sorted by species)."""
+    random.seed(SEED)
+    centers = species_centers()
+
+    xs = array.array("f")
+    ys = array.array("f")
+    sp_col = bytearray()
+    bt_col = bytearray()
+    st_col = bytearray()
+    ph_col = bytearray()
+
+    base = N_POINTS // len(SPECIES)
+    extra = N_POINTS - base * len(SPECIES)
+
+    for sp_idx, sp in enumerate(SPECIES):
+        n_this = base + (1 if sp_idx < extra else 0)
+        cx, cy = centers[sp]
+        # Sample n_this points around this species' center.
+        for _ in range(n_this):
+            xs.append(cx + random.gauss(0, 1.2))
+            ys.append(cy + random.gauss(0, 1.2))
+            sp_col.append(sp_idx)
+            bt_col.append(weighted_choice_idx(BIOTYPE_WEIGHTS))
+            st_col.append(random.randrange(2))
+            ph_col.append(random.randrange(3))
+
+    return xs, ys, sp_col, bt_col, st_col, ph_col
+
+
+def pack_binary(xs, ys, sp_col, bt_col, st_col, ph_col):
+    """Pack parallel arrays into the binary layout described in the docstring."""
+    n = len(xs)
+    x_min, x_max = min(xs), max(xs)
+    y_min, y_max = min(ys), max(ys)
+
+    # Map floats into int16 range [-32767, 32767] using the bounds (so the
+    # client can reconstitute float coords if it ever needs to).
+    qx = array.array("h")
+    qy = array.array("h")
+    rx = 65534.0 / (x_max - x_min)
+    ry = 65534.0 / (y_max - y_min)
+    for i in range(n):
+        qx.append(int(round((xs[i] - x_min) * rx - 32767)))
+        qy.append(int(round((ys[i] - y_min) * ry - 32767)))
+
+    # Interleave xy into a single int16 stream (WebGL friendly: stride 4 bytes).
+    pos = array.array("h", [0] * (2 * n))
+    for i in range(n):
+        pos[2 * i]     = qx[i]
+        pos[2 * i + 1] = qy[i]
+
+    buf = bytearray()
+    # Header — 40 bytes (6 uint32 + 4 float32).
+    buf += struct.pack("<6I",
+                       0xCAB0FA1D, n,
+                       len(SPECIES), len(BIOTYPES),
+                       len(STRANDS), len(PHASES))
+    buf += struct.pack("<4f", x_min, x_max, y_min, y_max)
+
+    buf += pos.tobytes()
+    buf += bytes(sp_col)
+    buf += bytes(bt_col)
+    buf += bytes(st_col)
+    buf += bytes(ph_col)
+
+    return buf, (x_min, x_max, y_min, y_max)
+
+
+def main():
+    os.makedirs(DATA, exist_ok=True)
+
+    t0 = time.time()
+    print(f"generating {N_POINTS:,} fake UMAP points ...", file=sys.stderr)
+    xs, ys, sp_col, bt_col, st_col, ph_col = generate()
+    print(f"  done in {time.time() - t0:.1f}s", file=sys.stderr)
+
+    t1 = time.time()
+    print("packing binary ...", file=sys.stderr)
+    buf, bounds = pack_binary(xs, ys, sp_col, bt_col, st_col, ph_col)
+    print(f"  done in {time.time() - t1:.1f}s", file=sys.stderr)
+
+    out_bin = os.path.join(DATA, "umap.bin")
+    with open(out_bin, "wb") as f:
+        f.write(buf)
+    print(f"  wrote {out_bin}  ({len(buf):,} bytes uncompressed)", file=sys.stderr)
+
+    out_labels = os.path.join(DATA, "umap_labels.json")
+    species_to_kingdom = {sp: kd for kd, members in KINGDOMS.items() for sp in members}
+    with open(out_labels, "w") as f:
+        json.dump({
+            "species":           SPECIES,
+            "biotypes":          BIOTYPES,
+            "strands":           STRANDS,
+            "phases":            PHASES,
+            "species_kingdom":   species_to_kingdom,
+            "kingdoms":          list(KINGDOMS.keys()),
+            "bounds":            list(bounds),
+            "n_points":          len(xs),
+            "fake":              True,
+        }, f, indent=2)
+    print(f"  wrote {out_labels}", file=sys.stderr)
+    print(f"total: {time.time() - t0:.1f}s", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()