feat: no head looks empty on the map; cap the shareable card at what fires

MAP (#233): the map colours each molecule by a single WINNING label, so a head could read
"(0)" in the legend while being trained on plenty of molecules — they were simply displayed
under a rarer co-occurring label. Highlighting matched that winner-take-all label, so those
heads lit up nothing and looked broken; it was the first thing that made the head roster look
untrustworthy.

New GET /api/map_members returns TRUE membership from the profile index — every molecule whose
head fires >= 0.5, not just where it wins. Verified on the heads that read zero: clarysage 25
members, violetleaf 21, blackpepper 14, juniper 13, freesia 12, rosemary 12. Shipping
8,834 x 175 scores to the browser was not viable; the endpoint keeps the payload small and is
cached. Zero-count legend entries are now clickable (with a tooltip explaining the distinction)
and highlighting routes through one mapHit() predicate applied consistently across the 2D,
properties and 3D views. Terms may be bare or dimension-qualified.

CARD (#236): the shareable PNG rendered ALL 164 aroma cells — 28 grid rows — and omitted
mouthfeel and safety entirely. A snapshot cannot scroll, so it now shows the 6 tastes ALWAYS
(a fixed row, comparable across cards) and only what FIRES for the rest: aroma capped at 18,
mouthfeel when a sensation fires, Tox21 only when flagged (warning red, caution-only wording).
Labels state the subset honestly — "AROMA MODEL · 12 of 164 heads firing" — so nobody mistakes
it for the whole model, and a molecule with nothing firing falls back to its strongest 3 rather
than printing a blank card. Layout is adaptive: verified vanillin 692px (aroma only), menthol
766px (+cooling), capsaicin 840px (+pungent/warming, +NR-Aromatase/SR-ARE).

Closes #233. Closes #236.

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

Author: rvnminers-A-and-N

training/app.py

@@ -583,9 +583,25 @@ def font(path, size):
                  "tasteless": out.get("tasteless")}
     taste_cells = sorted(((t, float(v) if isinstance(v, (int, float)) else 0.0)
                           for t, v in taste_src.items()), key=lambda kv: -kv[1])
+    # The card is a shareable SNAPSHOT — a PNG can't scroll, and there are 187 heads. So: the 6
+    # tastes ALWAYS render (a complete, fixed row you can compare across cards), while aroma,
+    # mouthfeel and safety show only what actually FIRES, capped. The labels say "N of M" so a
+    # reader knows they're seeing the firing subset, not the whole model.
+    AROMA_CAP = 18                                   # 3 rows of 6 — keeps the card readable
     pa = P.predict_aroma(smi)
-    aroma_cells = sorted(((d["odor"], d["score"]) for d in pa.get("descriptors", [])),
-                         key=lambda kv: -kv[1])
+    _all_aroma = sorted(((d["odor"], d["score"]) for d in pa.get("descriptors", [])),
+                        key=lambda kv: -kv[1])
+    _fired = [c for c in _all_aroma if c[1] >= 0.5]
+    aroma_cells = (_fired or _all_aroma[:3])[:AROMA_CAP]   # nothing firing -> top 3, never a blank card
+    aroma_total, aroma_fired = len(_all_aroma), len(_fired)
+
+    _mol = Chem.MolFromSmiles(smi)
+    mouth_cells = [(d["sensation"], d["score"])
+                   for d in (P.predict_mouthfeel(_mol).get("descriptors", []) if _mol else [])
+                   if d["score"] >= 0.5]
+    tox_cells = [(a["assay"], a["probability"])
+                 for a in ((out.get("safety") or {}).get("tox_screen") or {}).get("assays", [])
+                 if (a.get("probability") or 0) >= 0.5]
 
     pill_items = ([(fl, cream) for fl in tags.get("flavors", [])[:3]]
                   + [(t, _TASTE_RGB.get(t, teal)) for t in tags.get("tastes", [])]
@@ -611,6 +627,15 @@ def font(path, size):
     aroma_grid_y = aroma_label_y + 22
     aroma_rows = (len(aroma_cells) + COLS - 1) // COLS
     content_bottom = aroma_grid_y + aroma_rows * ROW_H
+    # mouthfeel + safety only take space when something actually fires
+    mouth_label_y = content_bottom + 12 if mouth_cells else None
+    mouth_row_y = (mouth_label_y + 22) if mouth_cells else None
+    if mouth_cells:
+        content_bottom = mouth_row_y + ((len(mouth_cells) + COLS - 1) // COLS) * ROW_H
+    tox_label_y = content_bottom + 12 if tox_cells else None
+    tox_row_y = (tox_label_y + 22) if tox_cells else None
+    if tox_cells:
+        content_bottom = tox_row_y + ((len(tox_cells) + COLS - 1) // COLS) * ROW_H
     H = max(560, content_bottom + 56)
 
     img = Image.new("RGB", (W, H), (15, 19, 25))
@@ -678,11 +703,29 @@ def cell(col, cy, label, v, color):
     for i, (t, v) in enumerate(taste_cells):
         cell(i, taste_row_y, t, v, _TASTE_RGB.get(t, teal))
 
-    # AROMA MODEL — all 24 heads in a 6-wide grid
-    dr.text((GX0, aroma_label_y), f"AROMA MODEL · all {len(aroma_cells)} heads", font=f_lab, fill=muted)
+    # AROMA MODEL — only the heads that fire, capped; label states the subset honestly
+    _shown = len(aroma_cells)
+    _alab = (f"AROMA MODEL · {_shown} of {aroma_total} heads firing"
+             + (f" (top {_shown} shown)" if aroma_fired > _shown else "")
+             if aroma_fired else f"AROMA MODEL · none of {aroma_total} heads firing · strongest {_shown}")
+    dr.text((GX0, aroma_label_y), _alab, font=f_lab, fill=muted)
     for i, (a, v) in enumerate(aroma_cells):
         cell(i % COLS, aroma_grid_y + (i // COLS) * ROW_H, a, v, teal)
 
+    # MOUTHFEEL — trigeminal sensations, only what fires
+    if mouth_cells:
+        dr.text((GX0, mouth_label_y), f"MOUTHFEEL · {len(mouth_cells)} of 5 sensations firing",
+                font=f_lab, fill=muted)
+        for i, (m, v) in enumerate(mouth_cells):
+            cell(i % COLS, mouth_row_y + (i // COLS) * ROW_H, m, v, cream)
+
+    # SAFETY — Tox21 assays, only when flagged; caution-only, never a determination
+    if tox_cells:
+        dr.text((GX0, tox_label_y), f"SAFETY · {len(tox_cells)} Tox21 assay(s) flagged — caution-only, "
+                "indicative in-vitro activity, NOT a toxicity determination", font=f_lab, fill=muted)
+        for i, (a, v) in enumerate(tox_cells):
+            cell(i % COLS, tox_row_y + (i // COLS) * ROW_H, a, v, (192, 85, 58))
+
     # footer
     fy = H - 54
     dr.line([40, fy, W - 40, fy], fill=(42, 50, 60), width=1)
@@ -1907,6 +1950,40 @@ def _svg_cell(smi):
     return _svg(smi, 104, 62)
 
 
+@app.get("/api/map_members")
+@lru_cache(maxsize=512)
+def api_map_members(term: str = "", threshold: float = 0.5):
+    """Every molecule whose head `term` fires >= threshold — not just the ones where it happens to
+    be the DOMINANT label.
+
+    The map colours each molecule by a single winning label, so a head can read "0" in the legend
+    while still being trained on plenty of molecules — they're simply displayed under a rarer
+    co-occurring label. Highlighting from the legend used to match that winner-take-all label, so
+    those heads lit up nothing and looked broken. This returns true membership from the profile
+    index (which carries every head score for every molecule), so no head can ever look empty.
+
+    `term` may be bare ("clarysage") or dimension-qualified ("aroma:clarysage", "mouthfeel:cooling")
+    — bare names resolve to aroma first, matching how the map legend labels them.
+    """
+    t = (term or "").strip().lower()
+    if not t:
+        return {"term": term, "smiles": [], "n": 0}
+    P._ensure_sub_index()
+    smis, profiles, dims = P._SUB_INDEX[1], P._SUB_INDEX[4], P._SUB_INDEX[5]
+    if profiles is None or not smis:
+        return {"term": term, "smiles": [], "n": 0, "note": "profile index not built"}
+    dims = [str(d) for d in dims]
+    col = None
+    for cand in ([t] if ":" in t else [f"aroma:{t}", f"taste:{t}", f"mouthfeel:{t}"]):
+        if cand in dims:
+            col = dims.index(cand)
+            break
+    if col is None:
+        return {"term": term, "smiles": [], "n": 0, "note": "no such head"}
+    hits = [smis[i] for i in range(len(smis)) if float(profiles[i][col]) >= threshold]
+    return {"term": term, "dim": dims[col], "threshold": threshold, "n": len(hits), "smiles": hits}
+
+
 @lru_cache(maxsize=8192)
 def _tox_flags(smiles):
     """Tox21 assays this molecule is predicted active in (>=0.5), as a tuple. Caution-only: assay

training/workbench.html

@@ -219,7 +219,9 @@
   .map-legend span{display:inline-flex;align-items:center;gap:5px;cursor:pointer;padding:2px 8px;border-radius:20px;border:1px solid transparent;transition:all .12s}
   .map-legend span:hover{border-color:var(--line)}
   .map-legend span.on{border-color:var(--brand-2);background:rgba(43,196,196,.10);color:var(--ink)}
-  .map-legend span.leg-zero{opacity:.42;cursor:default}
+  /* a (0) head is dimmed but still CLICKABLE — it has molecules, it just never wins the colour */
+  .map-legend span.leg-zero{opacity:.55;cursor:pointer}
+  .map-legend span.leg-zero:hover{opacity:.9}
   .map-legend span.leg-zero:hover{border-color:transparent}
   .map-legend i{width:10px;height:10px;border-radius:50%;display:inline-block}
   .map-controls{display:flex;flex-wrap:wrap;align-items:center;gap:12px;margin:10px 0 8px}
@@ -2086,6 +2088,15 @@ <h4>Software &amp; type</h4>
   mapLegendRender(); drawMap();
 }
 let _mapHi = new Set();  // classes highlighted from the legend (empty = show all evenly)
+const _mapMembers = new Map();  // class -> Set(smiles) of TRUE members (head >= 0.5), from /api/map_members
+// A point is spotlit if its dominant label is picked OR the head actually fires on it. Without the
+// second test, heads that never win the winner-take-all colour highlight nothing and look broken.
+function mapHit(p){
+  if(!_mapHi.size) return true;
+  if(_mapHi.has(mapLabel(p))) return true;
+  for(const l of _mapHi){ const m=_mapMembers.get(l); if(m && m.has(p.smiles)) return true; }
+  return false;
+}
 function mapLegendRender(){
   const counts={}; _mapPts.forEach(p=>counts[mapLabel(p)]=(counts[mapLabel(p)]||0)+1);
   // COMPLETE key: EVERY canonical class for the mode (all 6 taste heads / all 164 aroma heads /
@@ -2097,10 +2108,24 @@ <h4>Software &amp; type</h4>
   const labs=present.concat(empty); if(counts.other) labs.push('other');
   $('mapLegend').innerHTML=labs.map(l=>{
     const n=counts[l]||0, zero=n===0;
-    return `<span class="leg${_mapHi.has(l)?' on':''}${zero?' leg-zero':''}" data-l="${l.replace(/"/g,'&quot;')}"><i style="background:${legendColor(l)}"></i>${l} (${n})</span>`;
+    // A "(0)" head isn't empty — it just never WINS the winner-take-all colour. Clicking it
+    // fetches true membership (every molecule the head predicts >=0.5), so no head looks broken.
+    const t = zero ? `${l}: no molecule shows this as its dominant note — click to highlight every molecule the head predicts`
+                   : `${n} molecule${n===1?'':'s'} show ${l} as their dominant note — click to spotlight`;
+    return `<span class="leg${_mapHi.has(l)?' on':''}${zero?' leg-zero':''}" data-l="${l.replace(/"/g,'&quot;')}" title="${t.replace(/"/g,'&quot;')}"><i style="background:${legendColor(l)}"></i>${l} (${n})</span>`;
   }).join('');
-  $('mapLegend').querySelectorAll('.leg:not(.leg-zero)').forEach(s=> s.addEventListener('click', ()=>{
-    const l=s.dataset.l; if(_mapHi.has(l)) _mapHi.delete(l); else _mapHi.add(l); mapLegendRender(); drawMap();
+  $('mapLegend').querySelectorAll('.leg').forEach(s=> s.addEventListener('click', async ()=>{
+    const l=s.dataset.l;
+    if(_mapHi.has(l)){ _mapHi.delete(l); _mapMembers.delete(l); }
+    else {
+      _mapHi.add(l);
+      // pull true membership so a zero-count (or merely under-represented) head still lights up
+      if(l!=='other' && !_mapMembers.has(l)){
+        try{ const d=await getJSON('/api/map_members?term='+encodeURIComponent(l));
+             _mapMembers.set(l, new Set(d.smiles||[])); }catch(_){ _mapMembers.set(l, new Set()); }
+      }
+    }
+    mapLegendRender(); drawMap();
   }));
 }
 
@@ -2132,7 +2157,7 @@ <h4>Software &amp; type</h4>
   ctx.save(); ctx.globalCompositeOperation='lighter';
   for(const p of _mapPts){
     const l=mapLabel(p); if(!l||l==='other') continue;
-    if(hl && !_mapHi.has(l)) continue;
+    if(hl && !mapHit(p)) continue;
     const s=screenOf(p); if(!s||s.x<-9000||!isFinite(s.x)||!isFinite(s.y)) continue;
     ctx.fillStyle=mapColor(p); ctx.globalAlpha=A;
     ctx.beginPath(); ctx.arc(s.x,s.y,R,0,7); ctx.fill();
@@ -2172,10 +2197,10 @@ <h4>Software &amp; type</h4>
   drawDensity(ctx, p=>({x:px(p),y:py(p)}));
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';  // glow only on shown/highlighted points (subtle by default)
-  for(const p of _mapPts){ if(hl && !_mapHi.has(mapLabel(p))) continue; const x=px(p),y=py(p); ctx.fillStyle=mapColor(p);
+  for(const p of _mapPts){ if(hl && !mapHit(p)) continue; const x=px(p),y=py(p); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(x,y,hl?5.2:3.2,0,7); ctx.globalAlpha=hl?.16:.045; ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const p of _mapPts){ const on=!hl||_mapHi.has(mapLabel(p)),x=px(p),y=py(p);
+  for(const p of _mapPts){ const on=!hl||mapHit(p),x=px(p),y=py(p);
     ctx.fillStyle=on?mapColor(p):'#39424C'; ctx.beginPath(); ctx.arc(x,y,on?2.4:1.4,0,7); ctx.globalAlpha=on?(hl?.96:.82):.16; ctx.fill(); }
   ctx.globalAlpha=1;
   ctx.globalAlpha=1; _mapProj={px,py};
@@ -2221,10 +2246,10 @@ <h4>Software &amp; type</h4>
   // points
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';
-  for(const p of _mapPts){ if(p.mw==null||p.logp==null||(hl&&!_mapHi.has(mapLabel(p)))) continue; const x=bx(p.mw),y=by(p.logp); ctx.fillStyle=mapColor(p);
+  for(const p of _mapPts){ if(p.mw==null||p.logp==null||(hl&&!mapHit(p))) continue; const x=bx(p.mw),y=by(p.logp); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(x,y,hl?5:3,0,7); ctx.globalAlpha=hl?.15:.04; ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const p of _mapPts){ if(p.mw==null||p.logp==null) continue; const on=!hl||_mapHi.has(mapLabel(p)),x=bx(p.mw),y=by(p.logp);
+  for(const p of _mapPts){ if(p.mw==null||p.logp==null) continue; const on=!hl||mapHit(p),x=bx(p.mw),y=by(p.logp);
     ctx.fillStyle=on?mapColor(p):'#39424C'; ctx.beginPath(); ctx.arc(x,y,on?2.4:1.4,0,7); ctx.globalAlpha=on?(hl?.95:.8):.15; ctx.fill(); }
   ctx.globalAlpha=1;
   ctx.globalAlpha=1;
@@ -2283,10 +2308,10 @@ <h4>Software &amp; type</h4>
   drawDensity(ctx, p=>{ const s=proj(p); return {x:s.sx,y:s.sy}; });
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';  // glow with depth; subtle by default, strong when highlighting
-  for(const {p,pr} of all){ if(hl && !_mapHi.has(mapLabel(p))) continue; const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=mapColor(p);
+  for(const {p,pr} of all){ if(hl && !mapHit(p)) continue; const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(pr.sx,pr.sy,rr*(hl?2.1:1.5),0,7); ctx.globalAlpha=a*(hl?.2:.07); ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const {p,pr} of all){ const on=!hl||_mapHi.has(mapLabel(p)); const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=on?mapColor(p):'#39424C';
+  for(const {p,pr} of all){ const on=!hl||mapHit(p); const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=on?mapColor(p):'#39424C';
     ctx.beginPath(); ctx.arc(pr.sx,pr.sy,on?rr:rr*.7,0,7); ctx.globalAlpha=on?a:a*.28; ctx.fill(); }
   ctx.globalAlpha=1; _mapProj={px:p=>proj(p).sx, py:p=>proj(p).sy};
 }