letfixit 0.1.0

package/server/session_manager.js

@@ -0,0 +1,370 @@
+const { EventEmitter } = require('events');
+const { v4: uuidv4 } = require('uuid');
+const deviceDb = require('./device_db');
+const { classifyWidget } = require('./widget_gpu_classifier');
+
+const FRAME_BUDGET_MS = 16.6; // 60Hz
+const REQUIRED_RUNS   = 5;
+
+// Rough cost multiplier for projecting measurements (usually taken on a strong
+// simulator/device) onto weaker GPU tiers. Baseline is 'high'.
+const TIER_FACTOR = { flagship: 0.85, high: 1.0, mid: 1.5, low: 2.3, entry: 3.2 };
+
+// Extra penalty (ms) when a high-GPU-cost widget runs on a tier it's risky on.
+const RISK_PENALTY_MS = 6;
+
+function rate(projectedMs) {
+  if (projectedMs < 8)             return 'best';
+  if (projectedMs < 12)            return 'good';
+  if (projectedMs < FRAME_BUDGET_MS) return 'ok';
+  return 'bad';
+}
+
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[idx];
+}
+
+class SessionManager extends EventEmitter {
+  constructor() {
+    super();
+    this.session = null;
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+  start(module, targetDeviceIds = []) {
+    // No devices selected → evaluate against every unique device configuration
+    // by default (one representative per platform × GPU tier).
+    const targets = (Array.isArray(targetDeviceIds) && targetDeviceIds.length)
+      ? targetDeviceIds
+      : deviceDb.listUniqueConfigs().map((d) => d.id);
+
+    this.session = {
+      id: uuidv4(),
+      module: module || 'Unnamed module',
+      targetDeviceIds: targets,
+      requiredRuns: REQUIRED_RUNS,
+      status: 'recording',
+      runs: [],
+      current: this._newRun(0),
+      analysis: null,
+      startedAt: Date.now(),
+    };
+    this._emit();
+    return this.session;
+  }
+
+  /** Finalize the current run and begin the next (the "Restart / Next run" button). */
+  nextRun() {
+    if (!this.session || this.session.status !== 'recording') return this.session;
+    this._finalizeCurrent();
+    if (this.session.runs.length >= this.session.requiredRuns) {
+      this.session.status = 'ready'; // enough runs — analysis unlocked
+    }
+    this.session.current = this._newRun(this.session.runs.length);
+    this._emit();
+    return this.session;
+  }
+
+  /** Stop recording entirely (finalizes the in-progress run). */
+  stop() {
+    if (!this.session) return null;
+    if (this.session.current && this.session.current.frameCount > 0) {
+      this._finalizeCurrent();
+    } else {
+      this.session.current = null;
+    }
+    this.session.status = this.session.runs.length >= this.session.requiredRuns ? 'ready' : 'stopped';
+    this.session.current = null;
+    this._emit();
+    return this.session;
+  }
+
+  reset() {
+    this.session = null;
+    this._emit();
+  }
+
+  getState() {
+    return this.session;
+  }
+
+  // ── Event ingestion (called from index.js for every flutter event) ───────────
+  ingest(event) {
+    const s = this.session;
+    if (!s || s.status !== 'recording' || !s.current) return;
+    const run = s.current;
+
+    if (event.event === 'frame') {
+      const ms = event.metric.value;
+      run.frames.push(ms);
+      run.builds.push(event.metric.build || 0);
+      run.rasters.push(event.metric.raster || 0);
+      run.frameCount++;
+    } else if (event.event === 'rebuild' && event.widget) {
+      const w = run.widgets.get(event.widget) || { rebuilds: 0, totalBuildMs: 0, maxBuildMs: 0 };
+      w.rebuilds++;
+      const bms = event.metric.buildMs || 0;
+      w.totalBuildMs += bms;
+      if (bms > w.maxBuildMs) w.maxBuildMs = bms;
+      run.widgets.set(event.widget, w);
+    } else if (event.event === 'memory') {
+      run.memory.push(event.metric.value || 0);
+    } else if (event.event === 'api') {
+      const m = event.metric || {};
+      run.apis.push({
+        url: m.url || 'unknown', method: m.method || 'GET',
+        size: m.value || 0, durationMs: m.durationMs || 0, status: m.status || 0,
+      });
+    } else if (event.event === 'error') {
+      run.errors.push({ message: event.metric?.message || event.title || 'Error', widget: event.widget || null });
+    }
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────────────
+  _newRun(index) {
+    return { index, frames: [], builds: [], rasters: [], widgets: new Map(),
+             memory: [], apis: [], errors: [], frameCount: 0, startedAt: Date.now() };
+  }
+
+  _finalizeCurrent() {
+    const r = this.session.current;
+    if (!r) return;
+    const sortedFrames = [...r.frames].sort((a, b) => a - b);
+    const jank = r.frames.filter((ms) => ms > FRAME_BUDGET_MS).length;
+    const avg = (arr) => (arr.length ? arr.reduce((s, x) => s + x, 0) / arr.length : 0);
+
+    const widgets = [...r.widgets.entries()].map(([name, w]) => {
+      const info = classifyWidget(name);
+      return {
+        name,
+        rebuilds: w.rebuilds,
+        avgBuildMs: parseFloat((w.totalBuildMs / w.rebuilds).toFixed(3)),
+        maxBuildMs: parseFloat(w.maxBuildMs.toFixed(3)),
+        gpuCost: info.cost,
+        riskyTiers: info.risky,
+      };
+    }).sort((a, b) => (b.avgBuildMs * b.rebuilds) - (a.avgBuildMs * a.rebuilds));
+
+    const peakMemMb = r.memory.length ? Math.max(...r.memory) / (1024 * 1024) : 0;
+    const memGrowthMb = r.memory.length >= 2 ? (r.memory[r.memory.length - 1] - r.memory[0]) / (1024 * 1024) : 0;
+    const slowApis = r.apis.filter((a) => a.durationMs > 500).length;
+    const largeApis = r.apis.filter((a) => a.size > 512000).length;
+    const largestApiKb = r.apis.length ? Math.max(...r.apis.map((a) => a.size)) / 1024 : 0;
+
+    this.session.runs.push({
+      index: r.index,
+      durationMs: Date.now() - r.startedAt,
+      frameCount: r.frameCount,
+      jankFrames: jank,
+      jankPct: r.frameCount ? parseFloat(((jank / r.frameCount) * 100).toFixed(1)) : 0,
+      avgFrameMs: parseFloat(avg(r.frames).toFixed(2)),
+      p90FrameMs: parseFloat(percentile(sortedFrames, 90).toFixed(2)),
+      worstFrameMs: parseFloat((sortedFrames[sortedFrames.length - 1] || 0).toFixed(2)),
+      avgBuildMs: parseFloat(avg(r.builds).toFixed(2)),
+      avgRasterMs: parseFloat(avg(r.rasters).toFixed(2)),
+      widgets: widgets.slice(0, 20),
+      peakMemMb: parseFloat(peakMemMb.toFixed(1)),
+      memGrowthMb: parseFloat(memGrowthMb.toFixed(1)),
+      apiCount: r.apis.length,
+      slowApis, largeApis,
+      largestApiKb: parseFloat(largestApiKb.toFixed(1)),
+      errorCount: r.errors.length,
+      apis: r.apis.slice(0, 30),
+      errors: r.errors.slice(0, 20),
+    });
+  }
+
+  /**
+   * Aggregate all runs into a module-level summary and project onto each
+   * selected target device. Returns the aggregate WITHOUT calling AI —
+   * index.js triggers the single AI call separately.
+   */
+  aggregate() {
+    const s = this.session;
+    if (!s || s.runs.length === 0) return null;
+
+    const med = (arr) => {
+      const a = [...arr].sort((x, y) => x - y);
+      return a.length ? a[Math.floor(a.length / 2)] : 0;
+    };
+
+    const p90    = med(s.runs.map((r) => r.p90FrameMs));
+    const jankPct = med(s.runs.map((r) => r.jankPct));
+    const avgFrame = med(s.runs.map((r) => r.avgFrameMs));
+
+    // Merge widget stats across runs (avg the per-run averages, sum rebuilds).
+    const merged = new Map();
+    for (const run of s.runs) {
+      for (const w of run.widgets) {
+        const m = merged.get(w.name) || { name: w.name, rebuilds: 0, buildSum: 0, buildN: 0, maxBuildMs: 0, gpuCost: w.gpuCost, riskyTiers: w.riskyTiers };
+        m.rebuilds += w.rebuilds;
+        m.buildSum += w.avgBuildMs;
+        m.buildN += 1;
+        m.maxBuildMs = Math.max(m.maxBuildMs, w.maxBuildMs);
+        merged.set(w.name, m);
+      }
+    }
+    const widgets = [...merged.values()].map((m) => ({
+      name: m.name,
+      rebuilds: m.rebuilds,
+      avgBuildMs: parseFloat((m.buildSum / m.buildN).toFixed(3)),
+      maxBuildMs: parseFloat(m.maxBuildMs.toFixed(3)),
+      gpuCost: m.gpuCost,
+      riskyTiers: m.riskyTiers,
+    })).sort((a, b) => (b.avgBuildMs * Math.max(1, b.rebuilds)) - (a.avgBuildMs * Math.max(1, a.rebuilds)));
+
+    // Per-device projection
+    const devices = (s.targetDeviceIds.length ? s.targetDeviceIds : [])
+      .map((id) => deviceDb.getDevice(id))
+      .filter(Boolean)
+      .map((dev) => {
+        const factor = TIER_FACTOR[dev.gpu_tier] ?? 1.5;
+        const projectedFrameMs = parseFloat((avgFrame * factor).toFixed(2));
+        const projectedP90 = parseFloat((p90 * factor).toFixed(2));
+        const overall = rate(projectedP90);
+        const widgetRatings = widgets.slice(0, 12).map((w) => {
+          let projMs = w.avgBuildMs * factor;
+          if (w.gpuCost === 'high' && w.riskyTiers.includes(dev.gpu_tier)) projMs += RISK_PENALTY_MS;
+          return { name: w.name, projectedMs: parseFloat(projMs.toFixed(2)), rating: rate(projMs), gpuCost: w.gpuCost };
+        });
+        return {
+          id: dev.id, name: dev.name, platform: dev.platform,
+          gpu: dev.gpu, gpu_tier: dev.gpu_tier, ram_gb: dev.ram_gb,
+          arch: dev.arch, api: dev.api ?? null, ios_min: dev.ios_min ?? null,
+          projectedFrameMs, projectedP90, overall,
+          widgetRatings,
+        };
+      });
+
+    const measured = { p90FrameMs: p90, avgFrameMs: avgFrame, jankPct };
+    const report = this._buildReport(s.runs, widgets, devices, measured);
+
+    return {
+      module: s.module,
+      runsCompleted: s.runs.length,
+      measured,
+      widgets: widgets.slice(0, 20),
+      devices,
+      report,
+    };
+  }
+
+  /**
+   * Roll the runs + projections into a per-parameter report with a traffic-light
+   * status for each: performance, memory, API, and UI. Computed entirely in code
+   * (no LLM) — the AI advice is layered on separately by the analysis step.
+   */
+  _buildReport(runs, widgets, devices, measured) {
+    const med = (arr) => { const a = [...arr].sort((x, y) => x - y); return a.length ? a[Math.floor(a.length / 2)] : 0; };
+    const worst = (arr) => (arr.length ? Math.max(...arr) : 0);
+
+    // ── Performance ────────────────────────────────────────────────────────
+    const badDevices = devices.filter((d) => d.overall === 'bad');
+    const perfStatus = measured.p90FrameMs > FRAME_BUDGET_MS || badDevices.length
+      ? 'bad' : measured.p90FrameMs > 12 || measured.jankPct > 5 ? 'warn' : 'good';
+    const performance = {
+      status: perfStatus,
+      metrics: {
+        p90FrameMs: measured.p90FrameMs,
+        avgFrameMs: measured.avgFrameMs,
+        jankPct: measured.jankPct,
+        budgetMs: FRAME_BUDGET_MS,
+      },
+      failingDevices: badDevices.map((d) => `${d.name} (${d.projectedP90}ms)`),
+      note: perfStatus === 'good'
+        ? 'Frame times stay within the 16.6ms budget across target devices.'
+        : perfStatus === 'warn'
+          ? 'Frame times are close to budget — some jank on weaker tiers.'
+          : `p90 frame exceeds budget${badDevices.length ? ` on ${badDevices.length} device tier(s)` : ''}.`,
+    };
+
+    // ── Memory ─────────────────────────────────────────────────────────────
+    const peakMemMb = worst(runs.map((r) => r.peakMemMb || 0));
+    const growthMb = med(runs.map((r) => r.memGrowthMb || 0));
+    const memStatus = growthMb > 5 ? 'bad' : growthMb > 2 ? 'warn' : 'good';
+    const memory = {
+      status: memStatus,
+      metrics: { peakMb: parseFloat(peakMemMb.toFixed(1)), growthPerRunMb: parseFloat(growthMb.toFixed(1)) },
+      note: memStatus === 'good'
+        ? 'Heap is stable across runs — no growth trend detected.'
+        : memStatus === 'warn'
+          ? `Heap grows ~${growthMb.toFixed(1)}MB/run — watch for retained objects.`
+          : `Heap grows ~${growthMb.toFixed(1)}MB/run — likely a leak (unclosed streams, image cache, or Context retention).`,
+    };
+
+    // ── API ────────────────────────────────────────────────────────────────
+    const totalApis = runs.reduce((s, r) => s + (r.apiCount || 0), 0);
+    const totalSlow = runs.reduce((s, r) => s + (r.slowApis || 0), 0);
+    const totalLarge = runs.reduce((s, r) => s + (r.largeApis || 0), 0);
+    const largestKb = worst(runs.map((r) => r.largestApiKb || 0));
+    const apiStatus = totalLarge > 0 ? 'bad' : totalSlow > 0 ? 'warn' : 'good';
+    const api = {
+      status: totalApis === 0 ? 'good' : apiStatus,
+      metrics: { total: totalApis, slow: totalSlow, large: totalLarge, largestKb: parseFloat(largestKb.toFixed(1)) },
+      note: totalApis === 0
+        ? 'No API calls captured during the test (route calls through PerfHttpClient to track them).'
+        : apiStatus === 'good'
+          ? 'All responses are within the 500KB / 500ms budget.'
+          : apiStatus === 'warn'
+            ? `${totalSlow} slow call(s) (>500ms) — consider pagination or caching.`
+            : `${totalLarge} oversized payload(s) (>500KB) block parsing on the main thread.`,
+    };
+
+    // ── UI issues (high/medium GPU widgets landing on risky target tiers) ────
+    const targetTiers = new Set(devices.map((d) => d.gpu_tier));
+    const uiIssues = widgets
+      .filter((w) => w.gpuCost === 'high' || w.gpuCost === 'medium')
+      .map((w) => {
+        const riskyOnTarget = (w.riskyTiers || []).filter((t) => targetTiers.has(t));
+        return {
+          widget: w.name,
+          gpuCost: w.gpuCost,
+          rebuilds: w.rebuilds,
+          avgBuildMs: w.avgBuildMs,
+          riskyOnTarget,
+          note: classifyWidget(w.name).note,
+        };
+      })
+      .filter((w) => w.gpuCost === 'high' || w.riskyOnTarget.length || w.rebuilds > 30)
+      .slice(0, 12);
+    const highRisk = uiIssues.filter((w) => w.gpuCost === 'high' && w.riskyOnTarget.length);
+    const uiStatus = highRisk.length ? 'bad' : uiIssues.length ? 'warn' : 'good';
+    const ui = {
+      status: uiStatus,
+      issues: uiIssues,
+      note: uiStatus === 'good'
+        ? 'No GPU-expensive widgets on risky device tiers.'
+        : uiStatus === 'warn'
+          ? `${uiIssues.length} widget(s) worth reviewing on weaker tiers.`
+          : `${highRisk.length} high-GPU widget(s) on device tiers they're risky on.`,
+    };
+
+    // Overall status = worst of the four.
+    const rank = { good: 0, warn: 1, bad: 2 };
+    const overall = [performance, memory, api, ui].reduce(
+      (acc, sec) => (rank[sec.status] > rank[acc] ? sec.status : acc), 'good');
+
+    return { overall, performance, memory, api, ui };
+  }
+
+  /** Serializable snapshot (Maps stripped) for the dashboard / REST responses. */
+  snapshot() {
+    const s = this.session;
+    if (!s) return null;
+    return {
+      id: s.id, module: s.module, targetDeviceIds: s.targetDeviceIds,
+      requiredRuns: s.requiredRuns, status: s.status,
+      runs: s.runs, analysis: s.analysis,
+      currentRunFrames: s.current ? s.current.frameCount : 0,
+      runsCompleted: s.runs.length,
+    };
+  }
+
+  _emit() {
+    this.emit('update', this.snapshot());
+  }
+}
+
+module.exports = new SessionManager();

package/server/widget_gpu_classifier.js

@@ -0,0 +1,77 @@
+// Static GPU cost classification for Flutter widgets.
+// Cost is based on whether the widget forces an offscreen compositing pass
+// (saveLayer) or executes custom GPU shader work per frame.
+const GPU_COSTS = {
+  // ── High GPU cost (offscreen compositing / custom shaders) ──────────────
+  BackdropFilter:   { cost: 'high', risky: ['entry', 'low'],      note: 'Full offscreen compositing pass — avoid in scrollable lists' },
+  ShaderMask:       { cost: 'high', risky: ['entry', 'low'],      note: 'Custom shader evaluation per pixel — use pre-rendered assets on low-end devices' },
+  ImageFiltered:    { cost: 'high', risky: ['entry', 'low', 'mid'], note: 'Per-frame image processing — cache with RepaintBoundary' },
+  ColorFiltered:    { cost: 'high', risky: ['entry', 'low'],      note: 'Fragment shader per frame — consider pre-composited assets' },
+  PhysicalModel:    { cost: 'high', risky: ['entry', 'low'],      note: 'Box shadow triggers saveLayer — use pre-baked shadows on low-end devices' },
+
+  // ── Medium GPU cost (conditional saveLayer / unbounded paint) ────────────
+  Opacity:          { cost: 'medium', risky: ['entry'],            note: 'Values 0<x<1 force saveLayer. Prefer AnimatedOpacity or FadeTransition' },
+  AnimatedOpacity:  { cost: 'medium', risky: ['entry'],            note: 'Avoid driving with non-0/1 values on entry-tier devices' },
+  FadeTransition:   { cost: 'medium', risky: ['entry'],            note: 'Avoid stacking multiple FadeTransitions on entry-tier GPUs' },
+  CustomPaint:      { cost: 'medium', risky: ['entry', 'low'],    note: 'Unbounded GPU cost — profile shouldRepaint() and use RepaintBoundary' },
+  ClipPath:         { cost: 'medium', risky: ['entry', 'low'],    note: 'Anti-aliased clip is GPU-expensive — prefer ClipRRect with simple radii' },
+  ClipOval:         { cost: 'medium', risky: ['entry'],            note: 'Rounded clip — acceptable on low/mid, avoid animating on entry-tier' },
+  DecoratedBox:     { cost: 'medium', risky: ['entry'],            note: 'boxShadow triggers saveLayer on ARM Cortex-A53 class GPUs' },
+  Card:             { cost: 'medium', risky: ['entry'],            note: 'Shadow compositing — raise elevation only when needed' },
+  Material:         { cost: 'medium', risky: ['entry'],            note: 'Ink splash layer compositing — avoid inside tight list items on entry-tier' },
+  BoxShadow:        { cost: 'medium', risky: ['entry', 'low'],    note: 'Shadow compositing forces saveLayer — pre-bake on low-end devices' },
+  InkWell:          { cost: 'medium', risky: ['entry'],            note: 'Ink ripple compositing — consider InkResponse or custom hit-test shapes' },
+  Ink:              { cost: 'medium', risky: ['entry'],            note: 'Material ink compositing — watch rebuild count on entry-tier' },
+  AnimatedContainer:{ cost: 'medium', risky: ['entry'],            note: 'Per-frame layout + paint during animation — use AnimationController manually' },
+  AnimatedCrossFade:{ cost: 'medium', risky: ['entry', 'low'],    note: 'Dual subtree + CrossFadeState compositing — avoid inside ListView' },
+  Hero:             { cost: 'medium', risky: ['entry', 'low'],    note: 'Overlay layer during transition — heavy when source widget is complex' },
+  Draggable:        { cost: 'medium', risky: ['entry'],            note: 'Drag overlay compositing — keep dragged widget simple on entry-tier' },
+
+  // ── Low GPU cost (standard layout/paint — safe on all tiers) ────────────
+  Container:        { cost: 'low', risky: [],  note: 'Safe. Add RepaintBoundary around frequently-rebuilding subtrees.' },
+  Row:              { cost: 'low', risky: [],  note: 'Layout only — safe on all tiers' },
+  Column:           { cost: 'low', risky: [],  note: 'Layout only — safe on all tiers' },
+  Stack:            { cost: 'low', risky: [],  note: 'Adds compositing if children overflow — keep depth ≤ 8 on entry-tier' },
+  Text:             { cost: 'low', risky: [],  note: 'Safe. Watch font fallback chains on entry-tier (slow glyph load)' },
+  RichText:         { cost: 'low', risky: [],  note: 'Safe. Complex InlineSpan trees may slow text layout' },
+  Padding:          { cost: 'low', risky: [],  note: 'Layout pass only — safe on all tiers' },
+  Align:            { cost: 'low', risky: [],  note: 'Layout pass only — safe on all tiers' },
+  Center:           { cost: 'low', risky: [],  note: 'Alias of Align — safe on all tiers' },
+  Expanded:         { cost: 'low', risky: [],  note: 'Flex child — safe on all tiers' },
+  Flexible:         { cost: 'low', risky: [],  note: 'Flex child — safe on all tiers' },
+  SizedBox:         { cost: 'low', risky: [],  note: 'Constraint box — safe on all tiers' },
+  ConstrainedBox:   { cost: 'low', risky: [],  note: 'Constraint box — safe on all tiers' },
+  ListView:         { cost: 'low', risky: [],  note: 'Safe when using ListView.builder. Avoid ListView with non-lazy children.' },
+  GridView:         { cost: 'low', risky: [],  note: 'Use GridView.builder. Avoid fixed child arrays >20 items.' },
+  SingleChildScrollView:{ cost: 'low', risky: [],  note: 'Safe but entire subtree paints at once — prefer ListView.builder for long content' },
+  CustomScrollView: { cost: 'low', risky: [],  note: 'Sliver-based — safe. Avoid SliverFillRemaining with complex children.' },
+  Image:            { cost: 'low', risky: [],  note: 'Decoded image upload is GPU-cheap. Watch resolution scaling on entry-tier.' },
+  Icon:             { cost: 'low', risky: [],  note: 'Safe on all tiers' },
+  RepaintBoundary:  { cost: 'low', risky: [],  note: 'Isolates repaints — always beneficial around frequently-updating subtrees' },
+  GestureDetector:  { cost: 'low', risky: [],  note: 'Hit-test only — safe on all tiers' },
+  Navigator:        { cost: 'low', risky: [],  note: 'Overlay management — safe' },
+  Scaffold:         { cost: 'low', risky: [],  note: 'Safe on all tiers' },
+  AppBar:           { cost: 'low', risky: [],  note: 'Safe. Avoid elevation > 0 in scrollable app bars on entry-tier.' },
+  BottomNavigationBar:{ cost: 'low', risky: [], note: 'Safe. Avoid AnimatedIcons on entry-tier.' },
+  TextField:        { cost: 'low', risky: [],  note: 'Safe. Watch InputDecoration with boxShadow on entry-tier.' },
+};
+
+const UNKNOWN = { cost: 'unknown', risky: [], note: 'No data — profile on target device' };
+
+function classifyWidget(widgetName) {
+  if (!widgetName) return UNKNOWN;
+  // Direct match
+  if (GPU_COSTS[widgetName]) return GPU_COSTS[widgetName];
+  // Prefix match for generated widget names like _MyHomePageState → State rebuild
+  for (const [key, val] of Object.entries(GPU_COSTS)) {
+    if (widgetName.startsWith(key)) return val;
+  }
+  return UNKNOWN;
+}
+
+function isRiskyOn(widgetName, gpuTier) {
+  const info = classifyWidget(widgetName);
+  return info.risky.includes(gpuTier);
+}
+
+module.exports = { classifyWidget, isRiskyOn };

package/server/widget_triage.js

@@ -0,0 +1,78 @@
+// ── Code-first widget triage ─────────────────────────────────────────────────
+// The local LLM is expensive on CPU, so we do NOT ask it about every widget.
+// Instead we score each widget deterministically in JavaScript and only escalate
+// the genuinely expensive / ambiguous ones to the model. Cheap, clearly-safe
+// widgets are "auto-cleared" here with a code-generated note — the LLM never sees
+// them. This keeps prompts short (fewer tokens = far less CPU) and often skips the
+// model call entirely when a module is clean.
+
+const FRAME_BUDGET_MS = 16.6;
+
+// A widget is worth the LLM's time only if code can't already explain it.
+// Score components (higher = more worth escalating):
+//   • build cost      — avgBuildMs weighted by how often it rebuilds
+//   • budget pressure — how far its worst projected frame pushes past 16.6ms
+//   • gpu risk        — high/medium GPU cost widget landing on a risky target tier
+function scoreWidget(widget, devices) {
+  const rebuilds = Math.max(1, widget.rebuilds || 0);
+  const buildCost = (widget.avgBuildMs || 0) * Math.min(rebuilds, 60); // cap rebuild weight
+
+  // Worst projected ms for this widget across all selected target devices.
+  let worstProjected = widget.avgBuildMs || 0;
+  let worstDevice = null;
+  let riskyHit = false;
+  for (const d of devices) {
+    const wr = (d.widgetRatings || []).find((w) => w.name === widget.name);
+    if (!wr) continue;
+    if (wr.projectedMs > worstProjected) { worstProjected = wr.projectedMs; worstDevice = d; }
+    if ((wr.rating === 'bad' || wr.rating === 'ok') && wr.gpuCost === 'high') riskyHit = true;
+  }
+
+  const budgetPressure = Math.max(0, worstProjected - FRAME_BUDGET_MS);
+  const gpuRisk = (widget.gpuCost === 'high' ? 8 : widget.gpuCost === 'medium' ? 3 : 0)
+                  * (widget.riskyTiers?.length ? 1 : 0.4);
+
+  const score = buildCost * 1.5 + budgetPressure * 4 + gpuRisk + (riskyHit ? 6 : 0);
+  return { score, worstProjected: parseFloat(worstProjected.toFixed(2)), worstDevice, riskyHit };
+}
+
+// A deterministic, no-LLM note for widgets that don't clear the escalation bar.
+function autoNote(widget, meta) {
+  if (widget.gpuCost === 'high') {
+    return `High GPU-cost widget but projected within budget (worst ~${meta.worstProjected}ms). Keep it out of long scrollable lists and wrap in RepaintBoundary.`;
+  }
+  if (meta.worstProjected >= FRAME_BUDGET_MS * 0.75) {
+    return `Approaching frame budget (worst ~${meta.worstProjected}ms). Watch rebuild count; add const constructors where possible.`;
+  }
+  return `Cheap on all target tiers (worst ~${meta.worstProjected}ms, ${widget.rebuilds} rebuilds). No action needed.`;
+}
+
+/**
+ * Split widgets into { escalate, cleared } using code-computed scores.
+ * @param agg           aggregate from session_manager.aggregate()
+ * @param maxEscalate   hard cap on how many widgets we let reach the LLM
+ * @param minScore      escalation threshold
+ */
+function triage(agg, { maxEscalate = 5, minScore = 6 } = {}) {
+  const devices = agg.devices || [];
+  const scored = (agg.widgets || []).map((w) => ({ widget: w, meta: scoreWidget(w, devices) }));
+  scored.sort((a, b) => b.meta.score - a.meta.score);
+
+  const escalate = [];
+  const cleared = [];
+  for (const s of scored) {
+    if (escalate.length < maxEscalate && s.meta.score >= minScore) {
+      escalate.push(s);
+    } else {
+      cleared.push({
+        widget: s.widget.name,
+        gpuCost: s.widget.gpuCost,
+        worstProjectedMs: s.meta.worstProjected,
+        note: autoNote(s.widget, s.meta),
+      });
+    }
+  }
+  return { escalate, cleared };
+}
+
+module.exports = { triage, scoreWidget, FRAME_BUDGET_MS };