feat(ui): mouthfeel as a target dimension in the studios (#245)

Mouthfeel shipped as a modality in #243 but wasn't selectable anywhere. _precompute_design now
tags the design pool with the mouthfeel heads (batched, like aroma and taste), /api/studio_terms
returns a third `mouthfeel` list, and both pickers gained a Mouthfeel group — the Studio chip rail
and the Formulation Studio target profile — styled with a dotted amber edge.

Two bugs caught by verifying against the live box rather than assuming:

1. tingling matched 0 molecules and astringent 1, because the design pool is built from the HSDB
   *odor* corpus which barely contains trigeminal agents (0 of 11 tingling, 1 of 11 astringent).
   Curated mouthfeel agents now fold into the pool via a dedicated _MOUTHFEEL_CARRIERS loader.

2. `pungent` under Mouthfeel returned acetic acid, acetone and ammonia — sharp-SMELLING molecules
   — because the aroma head and the sensation head shared a bare tag and aroma had far more
   corpus molecules. Mouthfeel tags are now namespaced (mouthfeel:pungent), matching how the
   profile index keys aroma:cooling vs mouthfeel:cooling.

Verified after deploy: mouthfeel:pungent -> allyl isothiocyanate, diallyl disulfide, capsaicin;
note:pungent -> acetic acid, acetaldehyde, acetone, ammonia. All five sensations return real
agents. Part of #240, which stays open for the broader chip-picker usability pass.

Author: rvnminers-A-and-N

training/app.py

@@ -1102,7 +1102,11 @@ def _resolve_one(it):
 def _load_note_carriers():
     """descriptor/note -> [(smiles, name)] of KNOWN character-impact molecules, from the curated
     flavors.csv + aroma_supplement.csv. The recipe designer prefers these (e.g. gamma-nonalactone
-    for coconut, maltol for caramel) over a generic palette match, which can surface poor carriers."""
+    for coconut, maltol for caramel) over a generic palette match, which can surface poor carriers.
+
+    Mouthfeel agents load separately (_load_mouthfeel_carriers) and are NOT merged here: both files
+    key on bare names, so aroma_supplement's `pungent` Piper amides and mouthfeel_supplement's
+    TRPV1 agents would collide under one key and lose their modality."""
     import csv
     m = {}
     for path in ("flavors.csv", "aroma_supplement.csv"):
@@ -1116,7 +1120,25 @@ def _load_note_carriers():
     return m
 
 
+def _load_mouthfeel_carriers():
+    """sensation -> [(smiles, name)] of curated trigeminal agents (mouthfeel_supplement.csv, same
+    schema as flavors.csv). Kept separate from _NOTE_CARRIERS so the modality survives: the design
+    pool is built from the HSDB *odor* corpus, which barely contains these (0 of 11 tingling agents,
+    1 of 11 astringent), so without folding them in those chips match nothing."""
+    import csv
+    m = {}
+    with contextlib.suppress(Exception), open("mouthfeel_supplement.csv", encoding="utf-8") as fh:
+        for r in csv.DictReader(fh):
+            note = (r.get("flavor") or "").strip().lower()
+            smi = (r.get("smiles") or "").strip()
+            nm = (r.get("molecule") or "").strip()
+            if note and smi:
+                m.setdefault(note, []).append((smi, nm or note))
+    return m
+
+
 _NOTE_CARRIERS = _load_note_carriers()
+_MOUTHFEEL_CARRIERS = _load_mouthfeel_carriers()
 
 
 class DesignRecipeQuery(BaseModel):
@@ -1435,6 +1457,7 @@ def api_map():
 # --- Flavor designer: reverse search (desired descriptors -> best food-safe molecules) ---
 _DESIGN = []          # [{smiles, name, tags:set, gras:bool}]
 _DESIGN_DESCS = []    # descriptors with enough molecules to offer as options
+_DESIGN_MOUTHFEEL = []  # trained mouthfeel/chemesthesis sensations, offered as their own pick-list
 
 
 def _precompute_design():
@@ -1469,6 +1492,13 @@ def _precompute_design():
             if clf is not None:
                 for i in np.where(clf.predict_proba(X)[:, 1] >= 0.5)[0]:
                     tagsets[i].add(t)
+        # Mouthfeel tags are NAMESPACED ("mouthfeel:pungent"), matching how the profile index keys
+        # its dims. Without this, picking `pungent` under Mouthfeel returned sharp-SMELLING
+        # molecules (acetic acid, ammonia, CO2) from the far larger aroma:pungent set instead of
+        # the TRPV1 burn agents — the two modalities share a name but not a meaning.
+        for name, clf in P._MOUTHFEEL_MODELS.items():             # mouthfeel / chemesthesis
+            for i in np.where(clf.predict_proba(X)[:, 1] >= 0.5)[0]:
+                tagsets[i].add(f"mouthfeel:{name}")
         cnt, pool = Counter(), []
         for (smi, nm, skel, _, _), tags in zip(rows, tagsets):
             if not tags:
@@ -1478,18 +1508,27 @@ def _precompute_design():
         # fold the curated character-impact molecules (supplement + flavors) into the index so
         # their descriptors (coconut, nutty, vanilla, cinnamon...) are searchable + offerable even
         # where the industrial-skewed odor corpus is thin on them
-        for note, carriers in _NOTE_CARRIERS.items():
+        # aroma/flavor carriers keep their bare note; mouthfeel carriers carry the namespaced tag
+        folds = [(n, c, n) for n, c in _NOTE_CARRIERS.items()]
+        folds += [(n, c, f"mouthfeel:{n}") for n, c in _MOUTHFEEL_CARRIERS.items()]
+        for _note, carriers, tag in folds:
             for csmi, cnm in carriers:
                 cm = Chem.MolFromSmiles(csmi)
                 if cm is None:
                     continue
-                pool.append({"smiles": csmi, "name": cnm or "", "tags": {note},
+                pool.append({"smiles": csmi, "name": cnm or "", "tags": {tag},
                              "gras": Chem.MolToInchiKey(cm).split("-")[0] in P._GRAS})
-                cnt.update([note])
+                cnt.update([tag])
         _DESIGN[:] = pool
         # Offer EVERY trained aroma head as a selectable note (even aroma-only ones with few
-        # food-safe carriers), plus any design note that has >=5 carriers.
-        _DESIGN_DESCS[:] = sorted({d for d, n in cnt.items() if n >= 5} | set(P._AROMA_MODELS))
+        # food-safe carriers), plus any design note with >=5 carriers. Namespaced mouthfeel tags
+        # are excluded — they're a separate modality with their own pick-list below.
+        _DESIGN_DESCS[:] = sorted(
+            {d for d, n in cnt.items() if n >= 5 and not d.startswith("mouthfeel:")}
+            | set(P._AROMA_MODELS))
+        # Mouthfeel terms stay namespaced ("mouthfeel:cooling") so picking `cooling` here matches
+        # the SENSATION, not the like-named odour note. The UI shows the bare label.
+        _DESIGN_MOUTHFEEL[:] = [f"mouthfeel:{m}" for m in sorted(P._MOUTHFEEL_MODELS)]
 
 
 def _fpvec(mol):
@@ -1666,8 +1705,9 @@ def _gras_subs(smi, k=3):
 
 @app.get("/api/studio_terms")
 def api_studio_terms():
-    """The unified pick-list: curated flavors (grouped by category) + matchable note descriptors."""
-    return {"flavors": _FLAVOR_CATS, "notes": _DESIGN_DESCS}
+    """The unified pick-list: curated flavors (grouped by category), matchable aroma-note
+    descriptors, and mouthfeel sensations — three modalities the studios can target."""
+    return {"flavors": _FLAVOR_CATS, "notes": _DESIGN_DESCS, "mouthfeel": _DESIGN_MOUTHFEEL}
 
 
 @app.get("/api/nl")

training/workbench.html

@@ -161,6 +161,9 @@
     border:1px solid var(--line);background:var(--surface)}
   .tox-code{font-size:9.5px;opacity:.62;letter-spacing:.02em}
   .chip[title]{cursor:help}
+  /* mouthfeel target chips: dotted amber edge, so the sensation modality reads apart from the
+     aroma-note chips beside it (cooling/pungent legitimately appear in both groups) */
+  .chip-mouth{border-style:dotted;border-color:var(--accent);color:var(--accent)}
   .chip.on{color:#fff;border-color:transparent}
   /* scroll the qualifying set (every match above the similarity floor) instead of a fixed few;
      ~5 rows tall, then scroll. A subtle fade at the bottom hints there's more below. */
@@ -501,6 +504,10 @@
   .schip{font:inherit;font-size:12px;padding:3px 11px;border:1px solid var(--line);border-radius:20px;background:var(--panel);color:var(--ink);cursor:pointer;text-transform:capitalize}
   .schip:hover{border-color:var(--brand-2)}
   .schip-note{border-style:dashed}
+  /* mouthfeel chips: a distinct dotted edge + amber cast so the sensation modality reads apart
+     from odour notes at a glance (cooling/pungent legitimately appear in both rows) */
+  .schip-mouth{border-style:dotted;border-color:var(--accent);color:var(--accent)}
+  .schip-mouth:hover{border-color:var(--brand-2)}
   .schip.on{background:var(--brand-grad);color:#08121A;border-color:transparent;font-weight:650;box-shadow:0 2px 12px rgba(43,196,196,.32);transform:translateY(-1px)}
   .schip{transition:all .13s ease}
   .design-grid .dcell{animation:fadeUp .3s ease both}
@@ -829,6 +836,7 @@ <h1>Flavormancer</h1>
         <div class="form-target-head">Target profile <span class="mapsub" style="text-transform:none;font-weight:600">— optional; pick the <b>flavors</b> and <b>notes</b> you're aiming for. <b>Analyze</b> (above) scores your rows against it; <b>Design</b> (below) proposes a recipe for it.</span></div>
         <div class="form-tgt-group"><span class="form-tgt-label"><svg class="ic"><use href="#ic-flavors"/></svg> Flavors</span><div id="formTargetFlavors" class="form-chips"></div></div>
         <div class="form-tgt-group"><span class="form-tgt-label"><svg class="ic"><use href="#ic-notes"/></svg> Notes</span><div id="formTargetChips" class="form-chips"></div></div>
+        <div class="form-tgt-group"><span class="form-tgt-label" title="Chemesthesis — how it feels in the mouth, not how it smells"><svg class="ic"><use href="#ic-notes"/></svg> Mouthfeel</span><div id="formTargetMouth" class="form-chips"></div></div>
         <button class="mix-btn" id="formDesign" title="Propose a starting recipe for your target flavors + notes" style="margin-top:4px">✨ Design a recipe for this target</button>
       </div>
       <div id="formResults"></div>
@@ -1236,6 +1244,16 @@ <h4>Software &amp; type</h4>
   salty:'small mineral (alkali) salts — paired with a cation rule',
   tasteless:'little or no basic taste expected from structure'
 };
+// per-sensation "what this feels like" — the mouthfeel parallel to AROMA_HELP/TASTE_HELP.
+// Mouthfeel is trigeminal (chemesthesis), a different modality from smell — cooling and pungent
+// exist as BOTH an aroma head and a mouthfeel head, so these blurbs stress the *sensation*.
+const MOUTHFEEL_HELP = {
+  cooling:'cooling — TRPM8 coolants (menthol, WS-agents); a physiological cool, not just a cool smell',
+  pungent:'pungent — TRPV1 / mustard-oil heat &amp; bite (capsaicinoids, isothiocyanates, allium sulfur)',
+  warming:'warming — capsaicinoid &amp; warm-spice heat (chili, pepper, ginger, cinnamon)',
+  astringent:'astringent — tannins &amp; polyphenols; the puckering, mouth-drying sensation',
+  tingling:'tingling — paresthesia alkylamides (Sichuan-pepper sanshools, jambu spilanthol)',
+};
 // per-descriptor "what this note smells like" — the aroma parallel to TASTE_HELP
 const AROMA_HELP = {
   neroli:'orange-blossom / neroli — anthranilates &amp; indole over a terpene-alcohol base',
@@ -2270,7 +2288,7 @@ <h4>Software &amp; type</h4>
 const STUDIO_EMPTY='<div class="empty">Pick one or more flavors or notes above, then “Find molecules”.</div>';
 async function initStudio(){
   try{
-    const d = await getJSON('/api/studio_terms'); const cats=d.flavors||[], notes=d.notes||[];
+    const d = await getJSON('/api/studio_terms'); const cats=d.flavors||[], notes=d.notes||[], mouth=d.mouthfeel||[];
     if(!cats.length && !notes.length){ setTimeout(initStudio, 4000); return; }
     const esc = s => s.replace(/"/g,'&quot;');
     // category -> icon-sprite id (custom SVG glyphs, no emoji). Extra synonyms map to the
@@ -2295,6 +2313,14 @@ <h4>Software &amp; type</h4>
         notes.map(n=>`<button type="button" class="schip schip-note" data-term="${esc(n)}">${n}</button>`).join('')+
         `</div></div></div>`;
     }
+    // Mouthfeel — trained trigeminal sensations (a different modality from taste and aroma)
+    if(mouth.length){
+      html += `<div class="studio-section"><div class="ss-head"><svg class="ic"><use href="#ic-notes"/></svg> Mouthfeel <span class="ss-sub">how it <b>feels</b> in the mouth — chemesthesis, not smell</span></div><div class="ss-body">`+
+        `<div class="studio-group studio-group-notes">`+
+        mouth.map(m=>{const lbl=m.replace(/^mouthfeel:/,'');  // term stays namespaced, label reads plain
+          return `<button type="button" class="schip schip-mouth" data-term="${esc(m)}" title="${esc(MOUTHFEEL_HELP[lbl]||lbl)}">${lbl}</button>`;}).join('')+
+        `</div></div></div>`;
+    }
     $('studioChips').innerHTML = html;
     $('studioChips').querySelectorAll('.schip').forEach(b=> b.addEventListener('click', ()=>{
       const t=b.dataset.term; if(_studioSel.has(t)){ _studioSel.delete(t); b.classList.remove('on'); } else { _studioSel.add(t); b.classList.add('on'); }
@@ -2561,6 +2587,15 @@ <h4>Software &amp; type</h4>
     b.onclick=()=>{ if(_formFlavors.has(fl)){ _formFlavors.delete(fl); b.classList.remove('on'); } else { _formFlavors.add(fl); b.classList.add('on'); } };
     box.appendChild(b);
   }));
+  // mouthfeel targets — the trigeminal sensations, aimed at like notes but a distinct modality
+  const mbox=$('formTargetMouth');
+  (d.mouthfeel||[]).forEach(m=>{
+    const lbl=m.replace(/^mouthfeel:/,'');   // term stays namespaced so it matches the sensation tag
+    const b=document.createElement('span'); b.className='chip chip-mouth'; b.textContent=lbl; b.dataset.term=m;
+    b.title=MOUTHFEEL_HELP[lbl]||lbl;
+    b.onclick=()=>{ if(_formTarget.has(m)){ _formTarget.delete(m); b.classList.remove('on'); } else { _formTarget.add(m); b.classList.add('on'); } };
+    mbox.appendChild(b);
+  });
 }).catch(()=>{});
 let _lastRecipe=[]; let _lastRecipeMeta={flavors:[],notes:[]};
 $('formDesign').addEventListener('click', async ()=>{
@@ -2732,8 +2767,10 @@ <h4>Software &amp; type</h4>
   $('formRows').innerHTML='';
   b.dataset.ings.split('|').forEach(s=>{ const i=s.indexOf(':'); formAddRow(i<0?s:s.slice(0,i), i<0?'':s.slice(i+1)); });
   _formTarget.clear(); $('formTargetChips').querySelectorAll('.chip.on').forEach(x=>x.classList.remove('on'));
+  $('formTargetMouth').querySelectorAll('.chip.on').forEach(x=>x.classList.remove('on'));  // mouthfeel shares _formTarget
   _formFlavors.clear(); $('formTargetFlavors').querySelectorAll('.chip.on').forEach(x=>x.classList.remove('on'));
-  (b.dataset.tgt||'').split(',').filter(Boolean).forEach(t=>{ _formTarget.add(t); const c=$('formTargetChips').querySelector(`.chip[data-term="${t}"]`); if(c) c.classList.add('on'); });
+  // a preset term may be an aroma note or a mouthfeel sensation — light whichever chip carries it
+  (b.dataset.tgt||'').split(',').filter(Boolean).forEach(t=>{ _formTarget.add(t); const c=$('formTargetChips').querySelector(`.chip[data-term="${t}"]`) || $('formTargetMouth').querySelector(`.chip[data-term="${t}"]`); if(c) c.classList.add('on'); });
   $('formGo').click();
 }));
 </script>