formlab-mcp 0.6.34 → 0.6.36

package/README.md

@@ -52,7 +52,7 @@ Ask Claude (or another MCP client) things like:
 | `get_batch_pivot` | Production analytics — aggregate batches by `group_by` (formula / status / month / prepared_by / project) × `metric` (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests), with share + total for additive metrics. Optional `batch_uids` scope + `status` filter |
 | `get_project_pivot` | Portfolio analytics — aggregate projects by `group_by` (status / phase / priority / business_unit / site / customer / lead, or `cf:<custom field>`) × `metric` (count, total_formulas / batches / samples, total_cost, avg_formulas / batches / cost_per_batch), rolling child activity + cost up by any project attribute. Optional `project_uids` scope |
 | `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), all on **one point per test date per run condition** (replicates averaged, never separate time points), split by storage condition |
-| `get_design_space` | COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
+| `get_design_space` | COMPOSITION design space for one project, several (`projects`) or any formula list (`formulas`, across projects — like the app's Scope → DOE Matrix): which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Optional `axes` (choose the 2–3 axes), `by_role` (map ingredients summed by primary Function, e.g. Pigment / Solvent / Film Former — no gap, roles aren't DOE factors) and `property` (highest / lowest formula plus the ingredients whose level tracks it, Spearman ρ). Reports formulas that aren't on the map and the spread on it. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES; peptides that only store a sequence are searched with the structure derived from it, as the app draws them (`smilesDerived: true`). Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab \u2014 lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only MCP for FormLab — let Claude query your formulation lab. Free reads a local export; Pro connects to your live cloud workspace with a dedicated read-only token.",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.34",
+      "version": "0.6.36",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -226,7 +226,7 @@ const get_test_result = {
 const get_doe_matrix = {
   definition: {
     name: 'get_doe_matrix',
-    description: 'Build a Design-of-Experiments style pivot matrix: rows = formulations (or samples / batches / tests), columns = composition wt-% per ingredient + aggregated test-parameter values. Same shape as the FormLab DOE Matrix view. A parameter measured under two or more RUN CONDITIONS (e.g. storage 25 °C vs 40 °C) is one column per condition — "pH · 40 °C" — and the bare parameter column is the base arm (readings with no condition, else the condition with the most readings); they are different responses, never averaged together. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
+    description: 'Build a Design-of-Experiments style pivot matrix: rows = formulations (or samples / batches / tests), columns = composition wt-% per ingredient + aggregated test-parameter values. Same shape as the FormLab DOE Matrix view. A parameter measured under two or more RUN CONDITIONS (e.g. storage 25 °C vs 40 °C) is one column per condition — "pH · 40 °C" — and the bare parameter column is the base arm (readings with no condition, else the condition with the most readings, on a tie the one declared as the default on the Test Method / Test Panel); they are different responses, never averaged together. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -453,7 +453,34 @@ function _mcpCondTags(conds) {
   const lead = tags.map(t => t.split(/\s+[\/·]\s+/)[0]);
   return (new Set(lead).size === lead.length) ? lead : tags;
 }
-// items: [{ parameter, m }] → Map(parameter → Map(condSig → column name)),
+// Is this reading taken under the DEFAULT run condition its Test Method or
+// Test Panel declares? Port of the app's flCondDefaultScore (js/utils.js):
+// the tiebreak for the primary arm when two arms have equally long records,
+// instead of the condition's name ("25 °C" sorting before "40 °C").
+function _mcpCondDefaultScore(m, t, db) {
+  const c = m && m.conditions;
+  if (!c || typeof c !== 'object') return 0;
+  const decls = [];
+  const ps = db.parameters || [];
+  const nm = String(m.parameter || '').trim().toLowerCase();
+  const method = (m.parameterId && ps.find(p => p && p.id === m.parameterId)) || (nm ? ps.find(p => p && String(p.name || '').trim().toLowerCase() === nm) : null);
+  if (method && Array.isArray(method.conditions)) decls.push(...method.conditions);
+  const tmpl = t && t.templateId ? (db.templates || []).find(x => x && x.id === t.templateId) : null;
+  if (tmpl && Array.isArray(tmpl.conditions)) decls.push(...tmpl.conditions);
+  const lc = {};
+  Object.keys(c).forEach(k => { lc[k.toLowerCase()] = c[k]; });
+  let matched = 0;
+  for (const d of decls) {
+    if (!d || !d.key || d.default == null || d.default === '') continue;
+    const v = lc[String(d.key).toLowerCase()];
+    if (v == null || v === '') continue;
+    if (String(v).trim() !== String(d.default).trim()) return 0;
+    matched++;
+  }
+  return matched ? 1 : 0;
+}
+
+// items: [{ parameter, m, test? }] → Map(parameter → Map(condSig → column name)),
 // only for parameters with two or more arms.
 function _mcpArmNames(items) {
   const arms = new Map();
@@ -461,14 +488,26 @@ function _mcpArmNames(items) {
     const sig = _mcpCondSig(it.m);
     if (!arms.has(it.parameter)) arms.set(it.parameter, new Map());
     const a = arms.get(it.parameter);
-    const cur = a.get(sig) || { n: 0, m: it.m };
+    const cur = a.get(sig) || { n: 0, m: it.m, t: it.test || null };
     cur.n++; a.set(sig, cur);
   }
   const out = new Map();
+  let testOf = null;   // measurement → its report, built only if a tie needs a panel default
+  const score = (arm) => {
+    const { db } = getStore();
+    let t = arm.t;
+    if (!t) {
+      if (!testOf) { testOf = new Map(); (db.testResults || []).forEach(r => (r.measurements || []).forEach(x => testOf.set(x, r))); }
+      t = testOf.get(arm.m) || null;
+    }
+    return _mcpCondDefaultScore(arm.m, t, db);
+  };
   arms.forEach((a, param) => {
     if (a.size < 2) return;
     const keys = [...a.keys()];
-    const base = a.has('') ? '' : keys.slice().sort((x, y) => (a.get(y).n - a.get(x).n) || x.localeCompare(y))[0];
+    // No condition wins outright; among conditioned arms, most readings, then
+    // the declared default condition, then by name — as in the app.
+    const base = a.has('') ? '' : keys.slice().sort((x, y) => (a.get(y).n - a.get(x).n) || (score(a.get(y)) - score(a.get(x))) || x.localeCompare(y))[0];
     const ordered = [base, ...keys.filter(k => k !== base).sort((x, y) => x.localeCompare(y))];
     const tags = _mcpCondTags(ordered.map(k => k ? _mcpCondLabel(a.get(k).m) : ''));
     out.set(param, new Map(ordered.map((k, i) => [k, i === 0 ? param : `${param} · ${tags[i]}`])));
@@ -1243,7 +1282,7 @@ const get_stability = {
   },
 };
 
-export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames };
+export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/designspace.js

@@ -292,14 +292,87 @@ function _eligibleProjects(db) {
   return out;
 }
 
+// ---- scope, roles, property insights (ports of the app's build 26p–26s) -----
+
+// Resolve a list of formula ids / UIDs / names (exact name first, then substring).
+function _resolveFormulas(list, db) {
+  const norm = (s) => String(s || '').toLowerCase();
+  const out = [], missing = [];
+  (list || []).forEach(q => {
+    const f = resolveById('formulations', q)
+      || (db.formulations || []).find(x => x && norm(x.name) === norm(q))
+      || (db.formulations || []).find(x => x && norm(x.name).includes(norm(q)));
+    if (f && !f._trashed) { if (!out.includes(f)) out.push(f); } else missing.push(q);
+  });
+  return { forms: out, missing };
+}
+function _resolveProject(q, db) {
+  const norm = (s) => String(s || '').toLowerCase();
+  return resolveById('projects', q)
+    || (db.projects || []).find(p => norm(p.name) === norm(q))
+    || (db.projects || []).find(p => norm(p.name).includes(norm(q)));
+}
+// Primary Function role per ingredient ("Pigment|Opacifier" → "Pigment").
+function _roleMap(db) {
+  const m = new Map();
+  (db.ingredients || []).forEach(i => { const r = i && i.function ? String(i.function).split('|')[0].trim() : ''; if (r) m.set(i.id, r); });
+  return m;
+}
+// Per-formula role totals (wt% summed by role), as a map shaped like the
+// ingredient maps so the same geometry helpers work on it (keys 'role:<name>').
+function _roleMaps(forms, mapsByForm, db) {
+  const rm = _roleMap(db), out = new Map();
+  forms.forEach(f => {
+    const m = mapsByForm.get(f.id) || new Map(), t = new Map();
+    m.forEach((v, id) => { const r = rm.get(id); if (r && Number.isFinite(v)) t.set('role:' + r, (t.get('role:' + r) || 0) + v); });
+    out.set(f.id, t);
+  });
+  return out;
+}
+// Roles that vary, ranked by ABSOLUTE spread (the app's _asmDsRoleCands) — the
+// big building blocks first, not a small role that swings a lot relatively.
+function _roleCandidates(forms, roleMaps) {
+  const by = new Map();
+  forms.forEach(f => (roleMaps.get(f.id) || new Map()).forEach((v, id) => { if (!by.has(id)) by.set(id, []); by.get(id).push(v); }));
+  const out = [];
+  by.forEach((a, id) => {
+    if (a.length < 2) return;
+    const min = Math.min(...a), max = Math.max(...a), spread = max - min;
+    if (spread <= 0.01) return;
+    const mean = a.reduce((x, y) => x + y, 0) / a.length;
+    out.push({ id, name: id.slice(5), role: true, obs: { min, max, mean, n: a.length }, spread, rel: mean > 0 ? spread / mean : 0, score: spread });
+  });
+  return out.sort((a, b) => b.score - a.score);
+}
+// A formula's value for a measured parameter: the mean of every numeric
+// reading of it across the formula's samples (the app's _asmFormulaValueForCol).
+function _paramValue(f, param, db) {
+  const sids = new Set((db.samples || []).filter(s => s.formulationId === f.id).map(s => s.id));
+  const vals = [];
+  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) { const v = parseFloat(m.value); if (!isNaN(v)) vals.push(v); } }); });
+  return vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : null;
+}
+function _spearman(xs, ys) {
+  const rank = (a) => { const idx = a.map((v, i) => [v, i]).sort((p, q) => p[0] - q[0]); const r = new Array(a.length); let i = 0; while (i < idx.length) { let j = i; while (j + 1 < idx.length && idx[j + 1][0] === idx[i][0]) j++; const avg = (i + j) / 2 + 1; for (let k = i; k <= j; k++) r[idx[k][1]] = avg; i = j + 1; } return r; };
+  const rx = rank(xs), ry = rank(ys), n = xs.length;
+  const mx = rx.reduce((a, b) => a + b, 0) / n, my = ry.reduce((a, b) => a + b, 0) / n;
+  let sxx = 0, syy = 0, sxy = 0; for (let i = 0; i < n; i++) { const dx = rx[i] - mx, dy = ry[i] - my; sxx += dx * dx; syy += dy * dy; sxy += dx * dy; }
+  return (sxx && syy) ? sxy / Math.sqrt(sxx * syy) : null;
+}
+
 const get_design_space = {
   definition: {
     name: 'get_design_space',
-    description: 'Map a project\'s COMPOSITION design space (the descriptive mirror of the DOE designer, and the composition-space counterpart to get_coverage_matrix\'s TEST coverage). For one project it returns: the ingredients that actually VARY across its formulas + their observed wt-% ranges (ranked by proportional swing); an occupied-region summary ("where you\'ve been"); the biggest untested INTERIOR gap — a combination you could have made but skipped, kept inside the occupied cloud — expressed as ready-to-seed DOE ingredient ranges (low/high %); and, when the project has ≥3 varying ingredients, a standardised 2-component PCA of ALL of them: per-axis ingredient loadings, variance-explained, a scree list, and a full-dimensional gap. Numbers match FormLab\'s in-app Design Space Viewer exactly. Use it to answer "where haven\'t I explored?" / "what should I formulate next?" and to hand a chemist an experiment target. Read-only.',
+    description: 'Map a project\'s COMPOSITION design space (the descriptive mirror of the DOE designer, and the composition-space counterpart to get_coverage_matrix\'s TEST coverage). For one project it returns: the ingredients that actually VARY across its formulas + their observed wt-% ranges (ranked by proportional swing); an occupied-region summary ("where you\'ve been"); the biggest untested INTERIOR gap — a combination you could have made but skipped, kept inside the occupied cloud — expressed as ready-to-seed DOE ingredient ranges (low/high %); and, when the project has ≥3 varying ingredients, a standardised 2-component PCA of ALL of them: per-axis ingredient loadings, variance-explained, a scree list, and a full-dimensional gap. Numbers match FormLab\'s in-app Design Space Viewer exactly. Scope can be one project, several (projects), or any formula list (formulas); axes can be chosen (axes) or mapped by ingredient role (by_role); property adds best/worst formula and the ingredient that tracks it. Use it to answer "where haven\'t I explored?" / "what should I formulate next?" and to hand a chemist an experiment target. Read-only.',
     inputSchema: {
       type: 'object',
       properties: {
-        project: { type: 'string', description: 'Project id, UID, or name (case-insensitive; substring allowed). Omit to auto-pick the most-populated eligible project (≥3 formulas).' },
+        project: { type: 'string', description: 'Project id, UID, or name (case-insensitive; substring allowed). Omit (and omit projects/formulas) to auto-pick the most-populated eligible project (≥3 formulas).' },
+        projects: { type: 'array', items: { type: 'string' }, description: 'Map several projects together (ids, UIDs or names) — the app\'s cross-project scope. Ingredients most of the formulas share are ranked first.' },
+        formulas: { type: 'array', items: { type: 'string' }, description: 'Map exactly these formulas (ids, UIDs or names), from any projects — like the app\'s "Scope → DOE Matrix". Overrides project/projects.' },
+        axes: { type: 'array', items: { type: 'string' }, description: 'Choose the 2 or 3 axes yourself (ingredient names/ids, or role names with by_role) instead of the most-varying ones. Each must vary in the scope.' },
+        by_role: { type: 'boolean', description: 'Map ROLES instead of single ingredients: each formula\'s ingredients summed by their primary Function (e.g. Pigment / Solvent / Film Former), ranked by absolute spread. No gap is reported (roles are not DOE factors).' },
+        property: { type: 'string', description: 'A measured parameter name (e.g. "Gloss @60°"). Adds insights over the formulas on the map: highest and lowest formula, and the varying ingredient whose level tracks it most (Spearman ρ; a correlation, not a cause).' },
         include_pca: { type: 'boolean', description: 'Include the "map everything" PCA of all varying ingredients (loadings + variance + full-dimensional gap). Default true. Needs ≥3 varying ingredients and ≥3 formulas.' },
         loadings_per_component: { type: 'number', description: 'How many top ingredient loadings to list per principal component. Default 5, max 20.' },
       },
@@ -309,34 +382,54 @@ const get_design_space = {
     const { db } = getStore();
     const norm = (s) => String(s || '').toLowerCase();
 
-    // Resolve the project (explicit pick, else the most-populated eligible one).
-    let proj = null;
-    if (args.project) {
-      proj = resolveById('projects', args.project)
-        || (db.projects || []).find(p => norm(p.name) === norm(args.project))
-        || (db.projects || []).find(p => norm(p.name).includes(norm(args.project)));
-      if (!proj) return { error: `No project matched "${args.project}".` };
+    // Resolve the scope: explicit formulas > several projects > one project >
+    // the most-populated eligible project.
+    let proj = null, forms, scope;
+    const notes = [];
+    if (Array.isArray(args.formulas) && args.formulas.length) {
+      const r = _resolveFormulas(args.formulas, db);
+      if (r.missing.length) notes.push(`No formula matched: ${r.missing.join(', ')}.`);
+      forms = r.forms;
+      scope = { kind: 'formulas' };
+    } else if (Array.isArray(args.projects) && args.projects.length) {
+      const ps = [];
+      for (const q of args.projects) { const p = _resolveProject(q, db); if (!p) return { error: `No project matched "${q}".` }; if (!ps.includes(p)) ps.push(p); }
+      const ids = new Set(ps.map(p => p.id));
+      forms = (db.formulations || []).filter(f => f && !f._trashed && ids.has(f.projectId));
+      scope = { kind: 'projects' };
+      if (ps.length === 1) proj = ps[0];
     } else {
-      const elig = _eligibleProjects(db);
-      if (!elig.length) return { error: 'No project has ≥3 formulas to map. Assign at least 3 formulas to a project first.' };
-      proj = (db.projects || []).find(p => p.id === elig[0].id);
+      if (args.project) {
+        proj = _resolveProject(args.project, db);
+        if (!proj) return { error: `No project matched "${args.project}".` };
+      } else {
+        const elig = _eligibleProjects(db);
+        if (!elig.length) return { error: 'No project has ≥3 formulas to map. Assign at least 3 formulas to a project first.' };
+        proj = (db.projects || []).find(p => p.id === elig[0].id);
+      }
+      forms = (db.formulations || []).filter(f => f && !f._trashed && f.projectId === proj.id);
+      scope = { kind: 'project' };
     }
-    const pid = proj.id;
-    const forms = (db.formulations || []).filter(f => f && !f._trashed && f.projectId === pid);
+    const projIds = [...new Set(forms.map(f => f.projectId || ''))];
+    scope.formulaCount = forms.length;
+    scope.projects = projIds.map(id => (((db.projects || []).find(p => p.id === id) || {}).name) || (id ? id : '(no project)'));
 
     // Precompute ingredient maps once (reused by ranking, gap, PCA, observed range).
     const mapsByForm = new Map(forms.map(f => [f.id, _ingredientPctMap(f)]));
 
-    const out = {
-      project: { id: pid, uid: proj.uid || null, name: proj.name || pid, formulaCount: forms.length },
-      notes: [],
-    };
+    const out = { scope, notes };
+    if (proj) out.project = { id: proj.id, uid: proj.uid || null, name: proj.name || proj.id, formulaCount: forms.length };
     if (forms.length < 3) {
-      out.notes.push('This project has fewer than 3 formulas — a design space is only coherent with at least 3 points. Results below are provisional.');
+      out.notes.push('The scope has fewer than 3 formulas — a design space is only coherent with at least 3 points. Results below are provisional.');
     }
 
-    // Varying ingredients + observed ranges (ranked).
-    const cand = _factorCandidates(forms, mapsByForm, db);
+    // Varying ingredients + observed ranges (ranked). A scope spanning projects
+    // ranks ingredients at least half its formulas SHARE first (the app's rule).
+    let cand = _factorCandidates(forms, mapsByForm, db);
+    if (projIds.length > 1) {
+      const half = forms.length / 2;
+      cand = cand.filter(c => c.obs.n >= half).concat(cand.filter(c => c.obs.n < half));
+    }
     out.varyingIngredientCount = cand.length;
     out.varyingIngredients = cand.map(c => ({
       ingredient: c.name,
@@ -354,31 +447,73 @@ const get_design_space = {
       return out;
     }
 
-    // Axes: top-3 ternary (relative proportions) or top-2 scatter (absolute %).
-    const mode = cand.length >= 3 ? 'ternary' : 'scatter';
-    const comps = cand.slice(0, mode === 'ternary' ? 3 : 2);
+    // Axes: by role (pseudo-components) or ingredients; auto (most varying) or
+    // chosen. Values for the geometry come from `vmaps` (ingredient or role maps).
+    const byRole = !!args.by_role;
+    let vmaps = mapsByForm, axCand = cand;
+    if (byRole) {
+      vmaps = _roleMaps(forms, mapsByForm, db);
+      axCand = _roleCandidates(forms, vmaps);
+      out.roles = axCand.map(c => ({ role: c.name, observedRange: { min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), unit: '%' }, usedInFormulas: c.obs.n }));
+      if (axCand.length < 2) { out.notes.push('Fewer than 2 ingredient roles vary (set ingredient Functions to use by_role).'); out.axes = null; return out; }
+    }
+    let comps = null, chosen = false;
+    if (Array.isArray(args.axes) && args.axes.length) {
+      const find = (q) => axCand.find(c => norm(c.id) === norm(q) || norm(c.name) === norm(q)) || axCand.find(c => norm(c.name).includes(norm(q)));
+      const picked = [];
+      args.axes.forEach(q => { const c = find(q); if (c && !picked.includes(c)) picked.push(c); });
+      if ((picked.length === 3 || picked.length === 2) && picked.length === args.axes.length) { comps = picked; chosen = true; }
+      else out.notes.push(`Could not use axes [${args.axes.join(', ')}] — each must be a distinct ${byRole ? 'role' : 'ingredient'} that varies in this scope (2 or 3). Using the most-varying instead.`);
+    }
+    if (!comps) comps = axCand.slice(0, axCand.length >= 3 ? 3 : 2);
+    const mode = comps.length === 3 ? 'ternary' : 'scatter';
+    const kind = byRole ? 'roles (ingredients summed by primary Function)' : 'ingredients';
     out.axes = {
       mode,
-      basis: mode === 'ternary'
-        ? 'Top 3 most-varying ingredients, as relative proportions (a ternary).'
-        : 'Top 2 most-varying ingredients, as absolute wt-%.',
-      ingredients: comps.map(c => c.name),
+      basis: `${chosen ? 'Chosen' : (mode === 'ternary' ? 'Top 3 most-varying' : 'Top 2 most-varying')} ${kind}, ${mode === 'ternary' ? 'as relative proportions (a ternary: each axis is its share of the three shown, not wt% of the recipe).' : 'as absolute wt-%.'}`,
+      [byRole ? 'roles' : 'ingredients']: comps.map(c => c.name),
     };
 
     // Occupied-region summary: the bounding envelope of the plotted axes + how
     // many formulas actually sit in the space. The app draws the convex hull of
     // these points; the per-axis min/max here is that hull's bounding box.
-    let inSpace = 0;
-    forms.forEach(f => { if (comps.some(c => _ingVal(mapsByForm, f, c.id) != null)) inSpace++; });
+    const onMap = forms.filter(f => comps.some(c => (_ingVal(vmaps, f, c.id) || 0) > 0));
+    const inSpace = onMap.length;
+    if (inSpace < forms.length) out.notes.push(`${forms.length - inSpace} of ${forms.length} formulas contain none of the axes and are not on the map.`);
+    const share = onMap.map(f => { const v = comps.map(c => _ingVal(vmaps, f, c.id) || 0); const t = v.reduce((a, b) => a + b, 0) || 1; return mode === 'ternary' ? v.map(x => 100 * x / t) : v; });
     out.occupiedRegion = {
       formulaPoints: inSpace,
+      spreadOnMap: comps.map((c, i) => { const vs = share.map(r => r[i]); return { axis: c.name, min: +Math.min(...vs).toFixed(2), max: +Math.max(...vs).toFixed(2), unit: mode === 'ternary' ? '% of the three' : '%' }; }),
       axisRanges: comps.map(c => ({ ingredient: c.name, id: c.id, min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), unit: '%' })),
       note: 'Bounding envelope of the observed compositions on the mapped axes. In the app this is the shaded convex hull ("where you\'ve been"); the untested gap below was found INSIDE that occupied cloud, not on its frontier.',
     };
 
-    // The top untested interior gap, as ready-to-seed DOE ranges.
-    const gap = _computeGap(mode, comps, forms, mapsByForm);
-    if (!gap) {
+    // Property insights over the formulas on the map.
+    if (args.property) {
+      const vals = onMap.map(f => ({ f, v: _paramValue(f, args.property, db) })).filter(x => x.v != null);
+      if (vals.length < 2) out.notes.push(`"${args.property}" is measured on ${vals.length} of the formulas on the map — need at least 2 for insights (check the exact parameter name).`);
+      else {
+        const hi = vals.reduce((a, b) => b.v > a.v ? b : a), lo = vals.reduce((a, b) => b.v < a.v ? b : a);
+        const pi = { property: args.property, basis: 'mean of every reading per formula', formulasMeasured: vals.length,
+          highest: { formula: hi.f.name, uid: hi.f.uid || null, value: +hi.v.toFixed(4) },
+          lowest: { formula: lo.f.name, uid: lo.f.uid || null, value: +lo.v.toFixed(4) } };
+        if (vals.length >= 4) {
+          const ranked = [];
+          cand.forEach(c => { const xs = vals.map(x => _ingVal(mapsByForm, x.f, c.id) || 0); if (new Set(xs).size < 2) return; const r = _spearman(xs, vals.map(x => x.v)); if (r != null) ranked.push({ ingredient: c.name, rho: +r.toFixed(3) }); });
+          ranked.sort((a, b) => Math.abs(b.rho) - Math.abs(a.rho));
+          pi.tracksMost = ranked.slice(0, 5);
+          pi.note = 'Spearman rank correlation across these formulas — a lead for what to vary, not proof of cause' + (vals.length < 8 ? '; few formulas, so treat it cautiously.' : '.');
+        }
+        out.propertyInsights = pi;
+      }
+    }
+
+    // The top untested interior gap, as ready-to-seed DOE ranges (not for roles:
+    // they aren't DOE factors).
+    const gap = byRole ? null : _computeGap(mode, comps, forms, mapsByForm);
+    if (byRole) {
+      out.gap = null;
+    } else if (!gap) {
       out.gap = null;
       out.notes.push('Too few distinct formula points (need ≥4 with these axes) to locate a trustworthy gap.');
     } else {