letfixit 0.1.0

package/server/adb_bridge.js

@@ -0,0 +1,201 @@
+// ── ADB bridge ────────────────────────────────────────────────────────────────
+// Drives performance data collection on a physically-connected Android device
+// through `adb`. Works on ANY installed app — no debuggable build required —
+// because it reads the OS-side dumpsys counters (gfxinfo/meminfo/cpuinfo) that
+// the framework maintains for every process.
+//
+// The parse* functions are pure and exported so they can be unit-tested against
+// captured dumpsys output without a device attached.
+const { execFile, spawn } = require('child_process');
+
+const ADB = process.env.ADB_PATH || 'adb';
+
+function sh(args, { timeout = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(ADB, args, { timeout, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error((stderr || err.message || '').toString().trim()));
+      resolve(stdout || '');
+    });
+  });
+}
+
+const target = (serial) => (serial ? ['-s', serial] : []);
+
+/** Run an arbitrary `adb shell` command on a device. */
+function shell(serial, cmd) {
+  return sh([...target(serial), 'shell', ...(Array.isArray(cmd) ? cmd : [cmd])]);
+}
+
+/** Is the adb binary reachable at all? */
+async function isAvailable() {
+  try { await sh(['version']); return true; } catch { return false; }
+}
+
+/** PID of a running package (or null if not running). */
+async function pidOf(serial, pkg) {
+  try {
+    const out = (await shell(serial, ['pidof', pkg])).trim();
+    const pid = parseInt(out.split(/\s+/)[0], 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch { return null; }
+}
+
+/** Package of the currently-focused/resumed activity (best-effort). */
+async function foregroundPackage(serial) {
+  try {
+    const out = await shell(serial, ['dumpsys', 'activity', 'activities']).catch(() => '');
+    const m = out.match(/mResumedActivity[^\n]*\s([a-zA-Z][\w.]+)\/[\w.$]+/) ||
+              out.match(/topResumedActivity[^\n]*\s([a-zA-Z][\w.]+)\/[\w.$]+/);
+    if (m) return m[1];
+    const w = (await shell(serial, ['dumpsys', 'window']).catch(() => '')).match(/mCurrentFocus=[^\s]*\s([a-zA-Z][\w.]+)\//);
+    return w ? w[1] : null;
+  } catch { return null; }
+}
+
+/** Connected devices in state `device` → [{ serial, model }]. */
+async function listDevices() {
+  const out = await sh(['devices', '-l']);
+  const devices = [];
+  for (const line of out.split('\n').slice(1)) {
+    const m = line.trim().match(/^(\S+)\s+device\b(.*)$/);
+    if (!m) continue;
+    const model = (m[2].match(/model:(\S+)/) || [])[1] || m[1];
+    devices.push({ serial: m[1], model: model.replace(/_/g, ' ') });
+  }
+  return devices;
+}
+
+async function deviceInfo(serial) {
+  const g = async (prop) => {
+    try { return (await sh([...target(serial), 'shell', 'getprop', prop])).trim(); }
+    catch { return ''; }
+  };
+  return {
+    brand:     await g('ro.product.brand'),
+    model:     await g('ro.product.model'),
+    os:        'Android',                       // generic OS label used by report/AI
+    osVersion: await g('ro.build.version.release'),
+    sdk:       await g('ro.build.version.sdk'),
+    abi:       await g('ro.product.cpu.abi'),
+  };
+}
+
+/** True if the package is installed on the device. */
+async function isInstalled(serial, pkg) {
+  try {
+    const out = await sh([...target(serial), 'shell', 'pm', 'list', 'packages', pkg]);
+    return out.split('\n').some((l) => l.trim() === `package:${pkg}`);
+  } catch { return false; }
+}
+
+/** Launch the app's main LAUNCHER activity without needing its activity name. */
+function launch(serial, pkg) {
+  return sh([...target(serial), 'shell', 'monkey', '-p', pkg, '-c', 'android.intent.category.LAUNCHER', '1']);
+}
+function forceStop(serial, pkg) {
+  return sh([...target(serial), 'shell', 'am', 'force-stop', pkg]);
+}
+/** Clear the running gfxinfo frame stats so the next capture is fresh. */
+function resetGfx(serial, pkg) {
+  return sh([...target(serial), 'shell', 'dumpsys', 'gfxinfo', pkg, 'reset']);
+}
+
+/** Snapshot render / memory / cpu counters for the package right now. */
+async function collect(serial, pkg) {
+  const [gfx, mem, cpu] = await Promise.all([
+    sh([...target(serial), 'shell', 'dumpsys', 'gfxinfo', pkg]).catch(() => ''),
+    sh([...target(serial), 'shell', 'dumpsys', 'meminfo', pkg]).catch(() => ''),
+    sh([...target(serial), 'shell', 'dumpsys', 'cpuinfo']).catch(() => ''),
+  ]);
+  return { ...parseGfxinfo(gfx), ...parseMeminfo(mem), cpuPct: parseCpu(cpu, pkg) };
+}
+
+// ── Pure parsers ───────────────────────────────────────────────────────────────
+function parseGfxinfo(text) {
+  const num = (re) => { const m = text.match(re); return m ? parseFloat(m[1]) : null; };
+  const jank = text.match(/Janky frames:\s*(\d+)\s*\(([\d.]+)%\)/);
+  const gpuMem = text.match(/Total GPU memory usage:\s*\d+\s*bytes?,\s*([\d.]+)\s*MB/i);
+  return {
+    totalFrames:  num(/Total frames rendered:\s*(\d+)/),
+    jankyFrames:  jank ? parseInt(jank[1], 10) : null,
+    jankPct:      jank ? parseFloat(jank[2]) : null,
+    p50:          num(/50th percentile:\s*(\d+)ms/),
+    p90:          num(/90th percentile:\s*(\d+)ms/),
+    p95:          num(/95th percentile:\s*(\d+)ms/),
+    p99:          num(/99th percentile:\s*(\d+)ms/),
+    slowUiThread: num(/Number Slow UI thread:\s*(\d+)/),
+    missedVsync:  num(/Number Missed Vsync:\s*(\d+)/),
+    gpuMemMb:     gpuMem ? parseFloat(gpuMem[1]) : null,
+  };
+}
+
+function parseMeminfo(text) {
+  // Android 8+: "TOTAL PSS:  123456   TOTAL RSS: ..."; older: "TOTAL   123456 ..."
+  const m = text.match(/TOTAL PSS:\s*(\d+)/i) || text.match(/^\s*TOTAL\s+(\d+)/im);
+  const pssKb = m ? parseInt(m[1], 10) : null;
+  const native = (text.match(/Native Heap\s+(\d+)/) || [])[1];
+  const dalvik = (text.match(/Dalvik Heap\s+(\d+)/) || [])[1];
+  return {
+    pssMb:        pssKb != null ? parseFloat((pssKb / 1024).toFixed(1)) : null,
+    nativeHeapMb: native ? parseFloat((+native / 1024).toFixed(1)) : null,
+    dalvikHeapMb: dalvik ? parseFloat((+dalvik / 1024).toFixed(1)) : null,
+  };
+}
+
+// Per-frame timings from `dumpsys gfxinfo <pkg> framestats`. The PROFILEDATA
+// blocks are CSV rows of nanosecond timestamps; we recover each frame's total,
+// UI-thread (build) and GPU (raster) durations. `intendedVsync` is a monotonic
+// key the live monitor uses to emit only frames it hasn't seen yet.
+//   cols: 0 Flags, 1 IntendedVsync, ... 11 IssueDrawCommandsStart, 13 FrameCompleted
+function parseFramestats(text) {
+  const round = (n) => Math.round(n * 100) / 100;
+  const out = [];
+  for (const line of text.split('\n')) {
+    const l = line.trim();
+    if (!l || l.indexOf(',') === -1) continue;
+    const c = l.split(',');
+    if (c.length < 14) continue;
+    const n = c.map(Number);
+    if (n.some((x) => !Number.isFinite(x))) continue;   // header / non-data row
+    const flags = n[0];
+    if (flags !== 0) continue;                            // skip layout-change / first-draw frames
+    const intendedVsync = n[1], issueDraw = n[11], frameCompleted = n[13];
+    if (!intendedVsync || !frameCompleted || frameCompleted <= intendedVsync) continue;
+    const totalMs = (frameCompleted - intendedVsync) / 1e6;
+    if (totalMs <= 0 || totalMs > 5000) continue;         // sanity guard
+    out.push({
+      intendedVsync,
+      totalMs:  round(totalMs),
+      buildMs:  round(Math.max(0, (issueDraw - intendedVsync) / 1e6)),
+      rasterMs: round(Math.max(0, (frameCompleted - issueDraw) / 1e6)),
+    });
+  }
+  // Chronological by vsync so the live monitor's "last seen" cursor advances cleanly.
+  return out.sort((a, b) => a.intendedVsync - b.intendedVsync);
+}
+
+function parseCpu(text, pkg) {
+  // e.g. "  12% 3456/com.example.app: 8% user + 4% kernel"
+  for (const line of text.split('\n')) {
+    if (pkg && line.includes(pkg)) {
+      const m = line.trim().match(/([\d.]+)%/);
+      if (m) return parseFloat(m[1]);
+    }
+  }
+  return null;
+}
+
+/** Open a file with the OS default handler (used to pop the HTML report). */
+function openFile(filePath) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', filePath] : [filePath];
+  try { spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref(); } catch (_) {}
+}
+
+module.exports = {
+  ADB, exec: sh, shell, target,
+  isAvailable, listDevices, deviceInfo, isInstalled, pidOf, foregroundPackage,
+  launch, forceStop, resetGfx, collect, openFile,
+  parseGfxinfo, parseMeminfo, parseCpu, parseFramestats,
+};

package/server/adb_score.js

@@ -0,0 +1,77 @@
+// ── Deterministic scoring for an ADB performance review ──────────────────────
+// Aggregates per-iteration metrics into sub-scores and an overall 0–100 rank,
+// entirely in code (no LLM). The LLM only layers improvement suggestions on top
+// of the issues detected here — same "compute in code, escalate only what needs
+// judgement" philosophy as the Flutter module test.
+const clamp = (n, lo = 0, hi = 100) => Math.max(lo, Math.min(hi, n));
+const round = (n) => Math.round(n * 10) / 10;
+const avg = (arr) => (arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0);
+
+const FRAME_BUDGET_MS = 16.6;
+
+// Missing metrics stay `null` (not 0) so a platform that doesn't capture a
+// parameter — e.g. iOS render-only traces have no memory/CPU — is reported
+// honestly as "n/a" rather than a misleading perfect score.
+function aggregate(iterations) {
+  const col = (k) => iterations.map((i) => i[k]).filter((v) => v != null);
+  const orNull = (arr, f) => (arr.length ? f(arr) : null);
+  const mem = col('pssMb');
+  return {
+    jankPct:     orNull(col('jankPct'), (a) => round(avg(a))),
+    p50:         orNull(col('p50'), (a) => round(avg(a))),
+    p90:         orNull(col('p90'), (a) => round(avg(a))),
+    p99:         orNull(col('p99'), (a) => round(avg(a))),
+    peakMemMb:   orNull(mem, (a) => round(Math.max(...a))),
+    avgMemMb:    orNull(mem, (a) => round(avg(a))),
+    memGrowthMb: mem.length >= 2 ? round(mem[mem.length - 1] - mem[0]) : null,
+    cpuPct:      orNull(col('cpuPct'), (a) => round(avg(a))),
+    gpuMemMb:    orNull(col('gpuMemMb'), (a) => round(avg(a))),
+  };
+}
+
+// Each sub-score is only computed when its data is present; the overall is a
+// weight-renormalized average of the sub-scores that ARE available.
+function score(metrics) {
+  const m = metrics;
+  const has = (v) => v != null;
+
+  const parts = [];
+  if (has(m.jankPct) || has(m.p90) || has(m.p99)) {
+    const render = clamp(100 - (m.jankPct || 0) * 2 - Math.max(0, (m.p90 || 0) - FRAME_BUDGET_MS) * 3 - Math.max(0, (m.p99 || 0) - 32) * 1.2);
+    parts.push({ key: 'render', value: render, weight: 0.5 });
+  }
+  if (has(m.peakMemMb) || has(m.memGrowthMb)) {
+    const memory = clamp(100 - Math.max(0, (m.peakMemMb || 0) - 150) * 0.3 - Math.max(0, (m.memGrowthMb || 0)) * 2.5);
+    parts.push({ key: 'memory', value: memory, weight: 0.3 });
+  }
+  if (has(m.cpuPct)) {
+    const cpu = clamp(100 - Math.max(0, m.cpuPct - 30) * 1.6);
+    parts.push({ key: 'cpu', value: cpu, weight: 0.2 });
+  }
+
+  const totalW = parts.reduce((s, p) => s + p.weight, 0) || 1;
+  const overall = Math.round(parts.reduce((s, p) => s + p.value * p.weight, 0) / totalW);
+  const sub = (k) => { const p = parts.find((x) => x.key === k); return p ? Math.round(p.value) : null; };
+  return {
+    overall,
+    render: sub('render'),
+    memory: sub('memory'),
+    cpu: sub('cpu'),
+    grade: overall >= 85 ? 'excellent' : overall >= 70 ? 'good' : overall >= 50 ? 'fair' : 'poor',
+  };
+}
+
+// Guards use `> value`, which is false for null — a missing metric never
+// produces a false issue.
+function detectIssues(m) {
+  const issues = [];
+  if (m.jankPct > 5)      issues.push({ area: 'render', text: `Jank on ${m.jankPct}% of frames (target < 5%).` });
+  if (m.p90 > FRAME_BUDGET_MS) issues.push({ area: 'render', text: `p90 frame ${m.p90}ms exceeds the ${FRAME_BUDGET_MS}ms budget.` });
+  if (m.p99 > 40)         issues.push({ area: 'render', text: `p99 frame ${m.p99}ms — severe stalls on the worst frames.` });
+  if (m.memGrowthMb > 10) issues.push({ area: 'memory', text: `Memory grew ${m.memGrowthMb}MB across iterations — possible leak.` });
+  if (m.peakMemMb > 250)  issues.push({ area: 'memory', text: `Peak memory ${m.peakMemMb}MB is high for a single flow.` });
+  if (m.cpuPct > 40)      issues.push({ area: 'cpu', text: `CPU averaged ${m.cpuPct}% — likely background work or busy loops.` });
+  return issues;
+}
+
+module.exports = { aggregate, score, detectIssues, FRAME_BUDGET_MS };

package/server/ai_proxy.js

@@ -0,0 +1,373 @@
+require('dotenv').config();
+const fetch = require('node-fetch');
+const { generatePrompt, parseAIResponse } = require('./finding_generator');
+const { triage } = require('./widget_triage');
+
+const model = require('./model_config');
+
+const LOCAL_AI_PORT  = process.env.LOCAL_AI_PORT  || 8080;
+const GROQ_KEY       = process.env.GROQ_API_KEY;
+const GEMINI_KEY     = process.env.GEMINI_API_KEY;
+const CLAUDE_KEY     = process.env.CLAUDE_API_KEY;
+const ENABLE_LOCAL   = process.env.ENABLE_LOCAL_AI !== 'false';
+
+// AI availability summary — no longer auto-printed on require (the startup
+// sequence in index.js owns the branded "Ultron n0-beta initializing…" output).
+// Exposed for anything that still wants the detail.
+function aiStatus() {
+  return {
+    localReady: ENABLE_LOCAL && model.isReady(),
+    groq: !!GROQ_KEY, gemini: !!GEMINI_KEY, claude: !!CLAUDE_KEY,
+    anyAvailable: (ENABLE_LOCAL && model.isReady()) || !!GROQ_KEY || !!GEMINI_KEY || !!CLAUDE_KEY,
+  };
+}
+
+// ── Main routing: B → A (groq → gemini → claude) ───────────────────────────
+async function getAISuggestion(finding) {
+  const prompt = generatePrompt(finding);
+  const rule   = finding.rule || 'finding';
+
+  // ── B: Local SmolLM2 ──────────────────────────────────────────────────────
+  if (ENABLE_LOCAL) {
+    const local = await tryLocal(prompt);
+    if (local) {
+      console.log(`  🤖 [local]  AI suggestion for ${rule}`);
+      return local;
+    }
+  }
+
+  // ── A: Cloud fallbacks ────────────────────────────────────────────────────
+  if (GROQ_KEY) {
+    const groq = await tryGroq(prompt);
+    if (groq) {
+      console.log(`  🤖 [groq]   AI suggestion for ${rule}`);
+      return groq;
+    }
+  }
+
+  if (GEMINI_KEY) {
+    const gemini = await tryGemini(prompt);
+    if (gemini) {
+      console.log(`  🤖 [gemini] AI suggestion for ${rule}`);
+      return gemini;
+    }
+  }
+
+  if (CLAUDE_KEY) {
+    const claude = await tryClaude(prompt);
+    if (claude) {
+      console.log(`  🤖 [claude] AI suggestion for ${rule}`);
+      return claude;
+    }
+  }
+
+  // ── All providers failed or unconfigured ──────────────────────────────────
+  console.log(`  ⚠️  No AI available for ${rule} — configure a provider in .env`);
+  return null;
+}
+
+// ── Provider implementations ─────────────────────────────────────────────────
+
+async function tryLocal(prompt) {
+  try {
+    // Use the chat completions endpoint so the model's chat template is applied.
+    // Nemotron is a reasoning model — it uses ~300-500 tokens for internal thinking
+    // before outputting the structured answer, so max_tokens must be high enough.
+    const res = await fetch(`http://localhost:${LOCAL_AI_PORT}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: 'local',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 900,
+        temperature: 0.1,
+      }),
+      timeout: 45000,
+    });
+    if (!res.ok) { console.log(`  ↳ [local] HTTP ${res.status}`); return null; }
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content;
+    if (!text) { console.log('  ↳ [local] empty content (reasoning still in progress — increase max_tokens?)'); return null; }
+    const parsed = parseAIResponse(text);
+    if (!parsed) { console.log('  ↳ [local] parse failed'); return null; }
+    return { ...parsed, source: 'local', confidence: 0.75 };
+  } catch (err) {
+    if (err.code !== 'ECONNREFUSED') console.log(`  ↳ [local] ${err.message}`);
+    return null;
+  }
+}
+
+async function tryGroq(prompt) {
+  try {
+    const res = await fetch('https://api.groq.com/openai/v1/chat/completions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${GROQ_KEY}` },
+      body: JSON.stringify({
+        model: 'mixtral-8x7b-32768',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 200,
+        temperature: 0.1,
+      }),
+    });
+    if (!res.ok) { console.log(`  ↳ [groq] HTTP ${res.status}`); return null; }
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content;
+    const parsed = parseAIResponse(text);
+    if (!parsed) { console.log('  ↳ [groq] parse failed'); return null; }
+    return { ...parsed, source: 'groq', confidence: 0.9 };
+  } catch (err) {
+    console.log(`  ↳ [groq] ${err.message}`);
+    return null;
+  }
+}
+
+async function tryGemini(prompt) {
+  try {
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=${GEMINI_KEY}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contents: [{ parts: [{ text: prompt }] }],
+          generationConfig: { maxOutputTokens: 200, temperature: 0.1 },
+        }),
+      }
+    );
+    if (!res.ok) { console.log(`  ↳ [gemini] HTTP ${res.status}`); return null; }
+    const data = await res.json();
+    const text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+    const parsed = parseAIResponse(text);
+    if (!parsed) { console.log('  ↳ [gemini] parse failed'); return null; }
+    return { ...parsed, source: 'gemini', confidence: 0.9 };
+  } catch (err) {
+    console.log(`  ↳ [gemini] ${err.message}`);
+    return null;
+  }
+}
+
+async function tryClaude(prompt) {
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': CLAUDE_KEY,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: 'claude-sonnet-4-6',
+        max_tokens: 200,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    });
+    if (!res.ok) { console.log(`  ↳ [claude] HTTP ${res.status}`); return null; }
+    const data = await res.json();
+    const text = data.content?.[0]?.text;
+    const parsed = parseAIResponse(text);
+    if (!parsed) { console.log('  ↳ [claude] parse failed'); return null; }
+    return { ...parsed, source: 'claude', confidence: 0.95 };
+  } catch (err) {
+    console.log(`  ↳ [claude] ${err.message}`);
+    return null;
+  }
+}
+
+// ── Module Performance Test analysis (local Nemotron only) ────────────────────
+// Called ONCE, after the user completes ≥5 runs of a module flow. Sends the
+// aggregated widget table + per-device projection to the local model and asks
+// for concrete per-widget optimization advice.
+// `escalated` is the code-triaged shortlist — only these widgets reach the model.
+function buildModulePrompt(agg, escalated) {
+  const deviceLines = agg.devices.map((d) => {
+    const worst = d.widgetRatings.filter((w) => w.rating === 'bad' || w.rating === 'ok')
+      .map((w) => `${w.name} (~${w.projectedMs}ms, ${w.rating})`).join(', ') || 'none flagged';
+    const apiStr = d.api ? `Android API ${d.api}` : d.ios_min ? `iOS ${d.ios_min}+` : '';
+    return `- ${d.name}: ${d.gpu} (${d.gpu_tier} tier), ${d.ram_gb}GB RAM, ${d.arch}, ${apiStr}\n    Projected p90 frame: ${d.projectedP90}ms → overall "${d.overall}". Slow widgets: ${worst}`;
+  }).join('\n');
+
+  const widgetLines = escalated.map(({ widget: w, meta }) =>
+    `- ${w.name}: avg build ${w.avgBuildMs}ms, ${w.rebuilds} rebuilds, GPU cost ${w.gpuCost}${w.riskyTiers.length ? `, risky on [${w.riskyTiers.join(', ')}]` : ''}, worst projected ~${meta.worstProjected}ms${meta.worstDevice ? ` on ${meta.worstDevice.name}` : ''}`
+  ).join('\n');
+
+  return `You are a Flutter performance expert reviewing a module after ${agg.runsCompleted} profiled runs.
+
+MODULE: ${agg.module}
+Measured (on the connected device): median p90 frame ${agg.measured.p90FrameMs}ms, avg frame ${agg.measured.avgFrameMs}ms, jank ${agg.measured.jankPct}% of frames. Frame budget is 16.6ms (60Hz).
+
+FLAGGED WIDGETS (these were pre-selected in code as the expensive/ambiguous ones — focus only on these):
+${widgetLines}
+
+TARGET DEVICES (measurements projected onto each GPU tier):
+${deviceLines}
+
+For each flagged widget above, give concrete optimization advice. For EACH, respond in exactly this block format and nothing else:
+
+WIDGET: <widget name>
+ISSUE: <one sentence — why it is slow, referencing the device tier if relevant>
+FIX: <one sentence — the specific Flutter change>
+CODE: <dart snippet, max 5 lines>
+GAIN: <expected improvement, e.g. -8ms build or +12 FPS on low-tier devices>
+---`;
+}
+
+function parseModuleResponse(text) {
+  if (!text) return [];
+  // Strip <think> reasoning blocks if present
+  const clean = text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+  const blocks = clean.split(/\n-{3,}\n?/).map((b) => b.trim()).filter(Boolean);
+  const recs = [];
+  for (const b of blocks) {
+    const get = (k) => {
+      const m = b.match(new RegExp(`${k}:\\s*([\\s\\S]+?)(?=\\n[A-Z]+:|$)`));
+      return m ? m[1].trim() : null;
+    };
+    const widget = get('WIDGET');
+    const issue = get('ISSUE');
+    const fix = get('FIX');
+    if (!widget && !issue && !fix) continue;
+    recs.push({ widget, issue, fix, code: get('CODE'), gain: get('GAIN') });
+  }
+  return recs;
+}
+
+async function getModuleAnalysis(agg) {
+  // ── Step 1: code-first triage (no CPU, no model) ────────────────────────────
+  // Deterministically score every widget and split into "needs the LLM" vs
+  // "already explained in code". Cleared widgets never reach the model.
+  const { escalate, cleared } = triage(agg);
+  const clearedNotes = cleared.map((c) => ({
+    widget: c.widget,
+    issue: c.note,
+    fix: null, code: null, gain: null,
+    source: 'code', // rendered without an LLM badge
+  }));
+
+  console.log(`  🧮 [triage] "${agg.module}" — ${escalate.length} widget(s) escalated to LLM, ${cleared.length} auto-cleared in code`);
+
+  // ── Step 2: skip the model entirely when nothing is worth its time ──────────
+  if (escalate.length === 0) {
+    return {
+      ok: true, source: 'code', raw: '',
+      llmUsed: false,
+      recommendations: clearedNotes.slice(0, 8),
+      triage: { escalated: 0, cleared: cleared.length },
+    };
+  }
+
+  if (!ENABLE_LOCAL) {
+    return {
+      ok: true, source: 'code', raw: '', llmUsed: false,
+      recommendations: clearedNotes.slice(0, 8),
+      note: 'Local AI disabled (ENABLE_LOCAL_AI=false) — showing code-only triage.',
+      triage: { escalated: escalate.length, cleared: cleared.length },
+    };
+  }
+
+  // ── Step 3: only the flagged widgets go to the local model ──────────────────
+  const prompt = buildModulePrompt(agg, escalate);
+  try {
+    const res = await fetch(`http://localhost:${LOCAL_AI_PORT}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: 'local',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 1400,
+        temperature: 0.15,
+      }),
+      timeout: 90000,
+    });
+    if (!res.ok) {
+      return { ok: true, source: 'code', llmUsed: false, error: `Local model HTTP ${res.status}`,
+               recommendations: clearedNotes.slice(0, 8), triage: { escalated: escalate.length, cleared: cleared.length } };
+    }
+    const data = await res.json();
+    const raw = data.choices?.[0]?.message?.content || '';
+    const llmRecs = parseModuleResponse(raw).map((r) => ({ ...r, source: 'local' }));
+    // LLM advice first (the widgets that mattered), then the code-cleared notes.
+    const recommendations = [...llmRecs, ...clearedNotes].slice(0, 12);
+    console.log(`  🤖 [local] module analysis for "${agg.module}" → ${llmRecs.length} LLM rec(s) + ${clearedNotes.length} code note(s)`);
+    return { ok: true, source: 'local', raw, llmUsed: true, recommendations,
+             triage: { escalated: escalate.length, cleared: cleared.length } };
+  } catch (err) {
+    const msg = err.code === 'ECONNREFUSED'
+      ? 'Local model not running — showing code-only triage. Start it with ./setup.sh + npm start.'
+      : err.message;
+    console.log(`  ⚠️  module analysis LLM step failed: ${msg}`);
+    // Graceful degrade: still return the deterministic triage results.
+    return { ok: true, source: 'code', llmUsed: false, error: msg,
+             recommendations: clearedNotes.slice(0, 8), triage: { escalated: escalate.length, cleared: cleared.length } };
+  }
+}
+
+// ── Connected-device performance-review suggestions ──────────────────────────
+// Smart LLM use: the score + issues are already computed in code. We only call
+// the model to turn detected issues into concrete platform fixes. If there are
+// no issues, we skip the model entirely and return a code-only "all clear".
+function buildDevicePrompt({ app, module, deviceInfo, metrics, issues }) {
+  const issueLines = issues.map((i) => `- [${i.area}] ${i.text}`).join('\n');
+  const platform = deviceInfo.os || 'mobile';
+  return `You are a ${platform} performance expert reviewing the "${module}" flow of app ${app}.
+Device: ${deviceInfo.brand} ${deviceInfo.model}, ${deviceInfo.os} ${deviceInfo.osVersion} (${deviceInfo.abi}).
+
+Measured across the profiled iterations:
+- Jank: ${metrics.jankPct}% of frames | p90 frame ${metrics.p90}ms, p99 ${metrics.p99}ms (budget 16.6ms)
+- Memory: peak ${metrics.peakMemMb}MB, growth ${metrics.memGrowthMb}MB across runs
+- CPU: ${metrics.cpuPct}% average
+
+Detected issues:
+${issueLines}
+
+For each issue, give ONE concrete ${platform} optimization. Respond with blocks in EXACTLY this format, nothing else:
+
+TITLE: <short imperative fix, e.g. "Reduce overdraw in the list">
+DETAIL: <one or two sentences — the specific ${platform} change and why it helps>
+---`;
+}
+
+function parseAdbSuggestions(text) {
+  if (!text) return [];
+  const clean = text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+  return clean.split(/\n-{3,}\n?/).map((b) => b.trim()).filter(Boolean).map((b) => {
+    const t = b.match(/TITLE:\s*([\s\S]+?)(?=\nDETAIL:|$)/i);
+    const d = b.match(/DETAIL:\s*([\s\S]+?)$/i);
+    return { title: t ? t[1].trim() : null, detail: d ? d[1].trim() : b.trim() };
+  }).filter((s) => s.title || s.detail);
+}
+
+async function getDeviceSuggestions(ctx) {
+  const codeSuggestions = ctx.issues.map((i) => ({ title: i.text, detail: null, source: 'code' }));
+
+  if (ctx.issues.length === 0) {
+    return { ok: true, llmUsed: false, source: 'code',
+             suggestions: [{ title: 'Within budget on all measured parameters — no changes needed.', detail: null, source: 'code' }] };
+  }
+  if (!ENABLE_LOCAL) {
+    return { ok: true, llmUsed: false, source: 'code', suggestions: codeSuggestions,
+             note: 'Local AI disabled — showing code-detected issues only.' };
+  }
+
+  const prompt = buildDevicePrompt(ctx);
+  try {
+    const res = await fetch(`http://localhost:${LOCAL_AI_PORT}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: 'local', messages: [{ role: 'user', content: prompt }], max_tokens: 1200, temperature: 0.15 }),
+      timeout: 90000,
+    });
+    if (!res.ok) return { ok: true, llmUsed: false, source: 'code', suggestions: codeSuggestions, error: `Local model HTTP ${res.status}` };
+    const data = await res.json();
+    const raw = data.choices?.[0]?.message?.content || '';
+    const llm = parseAdbSuggestions(raw).map((s) => ({ ...s, source: 'local' }));
+    console.log(`  🤖 [local] device review "${ctx.module}" → ${llm.length} suggestion(s)`);
+    return { ok: true, llmUsed: llm.length > 0, source: llm.length ? 'local' : 'code',
+             suggestions: llm.length ? llm : codeSuggestions, raw };
+  } catch (err) {
+    const msg = err.code === 'ECONNREFUSED' ? 'Local model not running — showing code-detected issues only.' : err.message;
+    console.log(`  ⚠️  device review LLM step failed: ${msg}`);
+    return { ok: true, llmUsed: false, source: 'code', suggestions: codeSuggestions, error: msg };
+  }
+}
+
+module.exports = { getAISuggestion, getModuleAnalysis, getDeviceSuggestions, aiStatus };