letfixit 0.1.0

package/server/device_review.js

@@ -0,0 +1,146 @@
+// ── Connected Device Performance Test ────────────────────────────────────────
+// Platform-agnostic runner for any mobile plugged into the laptop — Android
+// (adb) or iOS (xctrace/simctl/devicectl). Same flow for both: pick a device →
+// enter bundle id + module name → run N iterations where the app is launched,
+// the user performs the flow, metrics are captured, and the app is restarted →
+// score in code → AI suggestions (only if issues) → HTML report.
+const fs = require('fs');
+const path = require('path');
+const adb = require('./adb_bridge');
+const ios = require('./ios_bridge');
+const { aggregate, score, detectIssues } = require('./adb_score');
+const { getDeviceSuggestions } = require('./ai_proxy');
+const { buildReport } = require('./report_template');
+
+const REPORTS_DIR = path.join(__dirname, 'reports');
+const DEFAULT_ITERATIONS = 8;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'module';
+
+// Uniform capture interface over the two low-level bridges.
+function adapterFor(platform) {
+  if (platform === 'android') {
+    return {
+      deviceInfo:  (dev) => adb.deviceInfo(dev.id),
+      isInstalled: (dev, pkg) => adb.isInstalled(dev.id, pkg),
+      async begin(dev, pkg) { await adb.launch(dev.id, pkg); await sleep(1500); await adb.resetGfx(dev.id, pkg); return {}; },
+      capture:     (dev, pkg) => adb.collect(dev.id, pkg),
+      stop:        (dev, pkg) => adb.forceStop(dev.id, pkg),
+    };
+  }
+  return { // ios
+    deviceInfo:  (dev) => ios.deviceInfo(dev),
+    isInstalled: (dev, pkg) => ios.isInstalled(dev, pkg),
+    begin:       (dev, pkg) => ios.beginCapture(dev, pkg), // launches app + starts trace
+    capture:     (dev, pkg, ctx) => ios.endCapture(dev, pkg, ctx),
+    stop:        (dev, pkg) => ios.terminate(dev, pkg),
+  };
+}
+
+async function collectAllDevices() {
+  const list = [];
+  if (await adb.isAvailable()) {
+    for (const d of await adb.listDevices()) list.push({ platform: 'android', id: d.serial, model: d.model, kind: 'device' });
+  }
+  if (await ios.isAvailable()) {
+    for (const d of await ios.listDevices()) list.push(d); // already {platform:'ios', id, model, kind, osVersion}
+  }
+  return list;
+}
+
+/**
+ * @param ask   async (question) => answer
+ * @param opts  { port }
+ */
+async function run(ask, opts = {}) {
+  const port = opts.port || process.env.DASHBOARD_PORT || 8081;
+
+  // ── Device discovery across both platforms ──────────────────────────────────
+  const devices = await collectAllDevices();
+  if (devices.length === 0) {
+    console.log('\n  ⚠️  No connected devices found.');
+    console.log('     Android: enable USB debugging + authorize the adb prompt.');
+    console.log('     iOS:     pair the device in Xcode, or boot a Simulator. Needs Xcode command-line tools.\n');
+    return;
+  }
+
+  let device = devices[0];
+  if (devices.length > 1) {
+    console.log('\n  Connected devices:');
+    devices.forEach((d, i) => console.log(`    ${i + 1}) [${d.platform === 'ios' ? 'iOS' : 'Android'}] ${d.model}${d.kind === 'simulator' ? ' (Simulator)' : ''} — ${d.id}`));
+    const pick = parseInt(await ask(`  → Select device [1-${devices.length}]: `), 10);
+    device = devices[pick - 1] || devices[0];
+  }
+  const bridge = adapterFor(device.platform);
+  const info = await bridge.deviceInfo(device);
+  console.log(`  📱 Using [${info.os}] ${info.brand} ${info.model}${device.kind === 'simulator' ? ' (Simulator)' : ''} · ${info.os} ${info.osVersion}`);
+
+  // ── Bundle id + module name ──────────────────────────────────────────────────
+  const idHint = device.platform === 'ios' ? 'com.example.MyApp' : 'com.example.app';
+  const bundleId = (await ask(`  📦 App bundle id (e.g. ${idHint}): `)).trim();
+  if (!bundleId) { console.log('  ⚠️  No bundle id — cancelled.'); return; }
+  if (!(await bridge.isInstalled(device, bundleId))) {
+    const cont = (await ask(`  ⚠️  "${bundleId}" not detected on the device. Continue anyway? [y/N]: `)).trim().toLowerCase();
+    if (cont !== 'y') return;
+  }
+  const moduleName = (await ask('  📝 Module / flow name (e.g. Login Flow): ')).trim() || 'App Flow';
+  const iterInput = parseInt(await ask(`  🔁 Iterations [${DEFAULT_ITERATIONS}]: `), 10);
+  const iterations = Number.isFinite(iterInput) && iterInput > 0 ? iterInput : DEFAULT_ITERATIONS;
+
+  console.log(`\n  ▶ Reviewing "${moduleName}" on ${bundleId} — ${iterations} iterations.`);
+  console.log('    Each run: the app launches, you perform the flow, then press Enter to capture.');
+  if (device.platform === 'ios') console.log('    (iOS captures an Instruments trace per run — allow a couple of seconds after Enter.)');
+  console.log('');
+
+  // ── Iteration loop ───────────────────────────────────────────────────────────
+  const samples = [];
+  for (let i = 1; i <= iterations; i++) {
+    console.log(`  ── Iteration ${i}/${iterations} ─────────────────────────────`);
+    let ctx = {};
+    try { ctx = await bridge.begin(device, bundleId); }
+    catch (e) { console.log(`    ⚠️  launch/prepare failed: ${e.message}`); }
+
+    await ask(`    ▶ Perform the "${moduleName}" flow now, then press Enter to capture… `);
+
+    let metrics = {};
+    try { metrics = await bridge.capture(device, bundleId, ctx); }
+    catch (e) { console.log(`    ⚠️  capture failed: ${e.message}`); }
+    try { await bridge.stop(device, bundleId); } catch (_) {}
+
+    samples.push(metrics);
+    console.log(`    ✓ captured — jank ${fmt(metrics.jankPct, '%')} · p90 ${fmt(metrics.p90, 'ms')} · PSS ${fmt(metrics.pssMb, 'MB')} · CPU ${fmt(metrics.cpuPct, '%')}`);
+  }
+
+  // ── Analyze (code) → suggestions (smart LLM) ─────────────────────────────────
+  console.log('\n  🧮 Aggregating metrics & scoring…');
+  const metrics = aggregate(samples);
+  const scored = score(metrics);
+  const issues = detectIssues(metrics);
+  console.log(`  📊 Score: ${scored.overall}/100 (${scored.grade}) · ${issues.length} issue(s) detected`);
+
+  console.log(issues.length ? '  🤖 Asking local LLM for fixes…' : '  ✓ No issues — skipping LLM.');
+  const ai = await getDeviceSuggestions({ app: bundleId, module: moduleName, deviceInfo: info, metrics, issues });
+
+  // ── Report ───────────────────────────────────────────────────────────────────
+  const html = buildReport({
+    app: bundleId, module: moduleName, deviceInfo: info,
+    iterations: samples, metrics, score: scored, issues,
+    suggestions: ai.suggestions, generatedAt: new Date().toString(),
+  });
+
+  fs.mkdirSync(REPORTS_DIR, { recursive: true });
+  const fileName = `${slug(moduleName)}-${Date.now()}.html`;
+  const filePath = path.join(REPORTS_DIR, fileName);
+  fs.writeFileSync(filePath, html, 'utf8');
+
+  console.log(`\n  ✅ Report saved: ${filePath}`);
+  console.log(`     Served at:    http://localhost:${port}/reports/${fileName}`);
+  console.log('     Opening in your browser…\n');
+  adb.openFile(filePath); // openFile is OS-generic (open / xdg-open / start)
+
+  return { filePath, fileName, url: `http://localhost:${port}/reports/${fileName}`, score: scored };
+}
+
+const fmt = (v, unit) => (v == null ? '—' : `${v}${unit}`);
+
+module.exports = { run, REPORTS_DIR };

package/server/finding_generator.js

@@ -0,0 +1,56 @@
+const { classifyWidget } = require('./widget_gpu_classifier');
+
+function generatePrompt(finding) {
+  const exceededBy = finding.metric.exceededBy != null ? finding.metric.exceededBy : 'N/A';
+  const widgetName = finding.widget || 'N/A';
+
+  // Enrich with GPU cost context for widget-related findings
+  const gpuInfo  = widgetName !== 'N/A' ? classifyWidget(widgetName) : null;
+  const gpuBlock = gpuInfo && gpuInfo.cost !== 'unknown'
+    ? `Widget GPU cost: ${gpuInfo.cost}\nRisky on GPU tiers: ${gpuInfo.risky.join(', ') || 'none (safe on all tiers)'}\nGPU note: ${gpuInfo.note}`
+    : '';
+
+  // Device context — populated when analysis engine receives device metadata
+  const deviceBlock = finding.deviceContext
+    ? `Device: ${finding.deviceContext.model || 'unknown'}\nGPU tier: ${finding.deviceContext.gpuTier || 'unknown'}\nArchitecture: ${finding.deviceContext.arch || 'unknown'}\nAndroid API: ${finding.deviceContext.api || 'N/A'}`
+    : '';
+
+  const contextLines = [gpuBlock, deviceBlock].filter(Boolean).join('\n');
+
+  return `You are a Flutter performance expert. Analyze this finding and respond strictly in the format below.
+
+Widget: ${widgetName}
+Issue: ${finding.title}
+Metric: ${finding.metric.value} ${finding.metric.unit}
+Budget: ${finding.metric.budget != null ? finding.metric.budget + ' ' + finding.metric.unit : 'N/A'}
+Exceeded by: ${exceededBy}
+Hypothesis: ${finding.hypothesis}
+${contextLines ? '\n' + contextLines : ''}
+
+Respond with EXACTLY these fields, nothing else:
+SEVERITY: critical|high|medium|low
+CAUSE: one sentence — why this widget causes the performance issue
+FIX: one sentence — the specific code change to fix it
+CODE: Flutter/Dart snippet (max 5 lines) that implements the fix
+GAIN: expected improvement e.g. +15 FPS or -30ms build time`;
+}
+
+function parseAIResponse(text) {
+  if (!text) return null;
+  const get = (key) => {
+    const match = text.match(new RegExp(`${key}:\\s*(.+?)(?=\\n[A-Z]+:|$)`, 's'));
+    return match ? match[1].trim() : null;
+  };
+  const result = {
+    severity: get('SEVERITY'),
+    cause:    get('CAUSE'),
+    fix:      get('FIX'),
+    code:     get('CODE'),
+    gain:     get('GAIN'),
+  };
+  // At least one field must be present for a valid parse
+  if (!result.cause && !result.fix && !result.gain) return null;
+  return result;
+}
+
+module.exports = { generatePrompt, parseAIResponse };

package/server/flutter_bridge.js

@@ -0,0 +1,414 @@
+require('dotenv').config();
+const WebSocket = require('ws');
+const { EventEmitter } = require('events');
+
+const RECONNECT_DELAY = 3000;
+
+// Read lazily at connect() time so a readline prompt in index.js can set
+// process.env.FLUTTER_VM_URL before the first connection attempt.
+function getVMUrl() {
+  return process.env.FLUTTER_VM_URL || 'ws://127.0.0.1:8181/ws';
+}
+
+class FlutterBridge extends EventEmitter {
+  constructor() {
+    super();
+    this._ws = null;
+    this._reconnecting = false;
+    this._pendingRequests = new Map();
+    this._reqId = 1;
+    this._connected = false;
+    this._buildStack = [];
+    this._isolateId = null;
+    this._memoryTimer = null;
+    this._recentErrors = [];
+  }
+
+  connect() {
+    if (this._ws) return;
+    this._reconnecting = false;
+
+    const url = getVMUrl();
+    const ws = new WebSocket(url);
+    this._ws = ws;
+
+    ws.on('open', () => {
+      this._connected = true;
+      console.log(`  ✅ Flutter VM Service connected (${url})`);
+      this._emitStatus(true);
+      this._subscribeToStreams();
+    });
+
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw);
+        if (msg.id && this._pendingRequests.has(msg.id)) {
+          this._pendingRequests.get(msg.id)(msg.result);
+          this._pendingRequests.delete(msg.id);
+        } else if (msg.method === 'streamNotify') {
+          this._handleStreamEvent(msg.params);
+        }
+      } catch (_) {}
+    });
+
+    ws.on('close', () => {
+      if (this._connected) {
+        this._connected = false;
+        console.log('  ⚠️  Flutter VM Service disconnected — retrying...');
+        this._emitStatus(false);
+      }
+      if (this._memoryTimer) { clearInterval(this._memoryTimer); this._memoryTimer = null; }
+      this._isolateId = null;
+      this._ws = null;
+      if (!this._reconnecting) {
+        this._reconnecting = true;
+        setTimeout(() => this.connect(), RECONNECT_DELAY);
+      }
+    });
+
+    ws.on('error', (err) => {
+      // Suppress noisy ECONNREFUSED spam while Flutter isn't running yet
+      if (err.code !== 'ECONNREFUSED') {
+        console.log(`  ⚠️  Flutter VM bridge error: ${err.message}`);
+      }
+      ws.terminate();
+    });
+  }
+
+  get isConnected() { return this._connected; }
+  get vmUrl() { return getVMUrl(); }
+
+  _emitStatus(connected) {
+    this.emit('status', { bridge: 'flutter', connected, url: getVMUrl() });
+  }
+
+  _send(method, params = {}) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+    const id = this._reqId++;
+    return new Promise((resolve) => {
+      this._pendingRequests.set(id, resolve);
+      this._ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+      setTimeout(() => {
+        if (this._pendingRequests.has(id)) {
+          this._pendingRequests.delete(id);
+          resolve(null);
+        }
+      }, 5000);
+    });
+  }
+
+  async _subscribeToStreams() {
+    await this._send('streamListen', { streamId: 'Extension' });
+    await this._send('streamListen', { streamId: 'Timeline' });
+    await this._send('streamListen', { streamId: 'Isolate' });
+    // Error sources: structured framework errors arrive on Extension as
+    // 'Flutter.Error'; dev.log / logger output arrives on Logging; uncaught
+    // zone errors and stack dumps arrive on Stderr.
+    await this._send('streamListen', { streamId: 'Logging' });
+    await this._send('streamListen', { streamId: 'Stderr' });
+    // Enable Flutter timeline events so build/raster data flows
+    await this._send('setVMTimelineFlags', { recordedStreams: ['GC', 'Dart', 'Embedder'] });
+    // Auto-detect the running device's OS/arch (best-effort). Precise GPU/RAM
+    // comes from the user picking a target device in the dashboard.
+    this._detectDevice();
+    this._startMemoryPolling();
+  }
+
+  async _detectDevice() {
+    const vm = await this._send('getVM', {});
+    if (!vm) return;
+    this._isolateId = vm.isolates?.[0]?.id || null;
+    this.emit('device', {
+      os:        vm.operatingSystem || null,   // 'android' | 'ios' | 'macos' ...
+      arch:      vm.hostCPU || null,           // e.g. 'arm64'
+      bits:      vm.architectureBits || null,
+      version:   vm.version || null,
+    });
+  }
+
+  /**
+   * Fetch the live widget tree via the Flutter widget inspector service
+   * extension. Returns the raw DiagnosticsNode root (normalization happens in
+   * index.js), or null if the inspector isn't available.
+   */
+  async getWidgetTree() {
+    if (!this._connected) return null;
+    let isolateId = this._isolateId;
+    if (!isolateId) {
+      const vm = await this._send('getVM', {});
+      isolateId = vm?.isolates?.[0]?.id || null;
+      this._isolateId = isolateId;
+    }
+    if (!isolateId) return null;
+
+    const groupName = 'perf-analyzer';
+    // Newer Flutter exposes ...WithPreviews; older exposes the plain variant.
+    const methods = [
+      'ext.flutter.inspector.getRootWidgetSummaryTreeWithPreviews',
+      'ext.flutter.inspector.getRootWidgetSummaryTree',
+      'ext.flutter.inspector.getRootWidget',
+    ];
+    for (const method of methods) {
+      const res = await this._send(method, { isolateId, groupName, objectGroup: groupName });
+      // Service-extension payloads may be double-wrapped: { result: <node> }.
+      const node = res?.result ?? res;
+      if (node && (node.description || node.children || node.widgetRuntimeType)) {
+        return node;
+      }
+    }
+    return null;
+  }
+
+  _handleStreamEvent(params) {
+    const { streamId, event } = params;
+
+    // Flutter.Frame — fires on every rendered frame with timing breakdown
+    if (streamId === 'Extension' && event.extensionKind === 'Flutter.Frame') {
+      this._handleFlutterFrame(event);
+    } else if (streamId === 'Extension' && event.extensionKind === 'Flutter.Error') {
+      this._handleFlutterError(event);
+    } else if (streamId === 'Timeline' && event.timelineEvents) {
+      this._handleTimelineEvents(event.timelineEvents);
+    } else if (streamId === 'Logging' && event.logRecord) {
+      this._handleLogRecord(event.logRecord);
+    } else if (streamId === 'Stderr' && event.bytes) {
+      this._handleStderr(event.bytes);
+    }
+  }
+
+  // Normalize a widget/type name to the SAME short form the widget tree uses
+  // (index.js normalizeTreeNode), so a widget named in an error/finding lines up
+  // with its node in the tree. Strips "-[GlobalKey#..]", generics, args, etc.
+  _shortWidgetName(raw) {
+    if (!raw) return null;
+    const s = String(raw).trim().split(/[\s(<[#]/)[0];
+    return s || null;
+  }
+
+  // Strip ANSI colors, box-drawing decoration, and leading frame markers so the
+  // message that reaches the feed is the actual human-readable error text.
+  _cleanErrorMessage(raw) {
+    // NB: leave "#12 " frame markers intact so _isMetaLine can still detect and
+    // drop standalone stack frames — stripping them here would let a bare frame
+    // masquerade as a real message.
+    return String(raw || '')
+      .replace(/\x1B\[[0-9;]*m/g, '')                    // ANSI color codes
+      .replace(/[═╡╞╪║╔╗╚╝╬╣╠─│┌┐└┘├┤┬┴┼]+/g, ' ')       // box-drawing chars
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  // Meta/decoration lines that are never the actual error message.
+  _isMetaLine(l) {
+    return !l || l.length < 3 ||
+      /^#\d+\s/.test(l) ||
+      /EXCEPTION CAUGHT|error-causing widget|When the exception was thrown|stack trace|^Another exception|^The following .* was thrown|^═|^╞|^╡/i.test(l);
+  }
+
+  // Pull the meaningful message + offending widget out of a Flutter error dump.
+  _parseErrorDump(text) {
+    const lines = text.split('\n').map((l) => this._cleanErrorMessage(l)).filter(Boolean);
+    let message = '', widget = null;
+
+    for (let i = 0; i < lines.length; i++) {
+      const l = lines[i];
+      // "... was thrown building Foo:" → Foo is the widget
+      const built = l.match(/thrown building ([A-Za-z_$][\w$]*)/);
+      if (built) widget = this._shortWidgetName(built[1]);
+      // Message: the content right after "was thrown[...]:" or "Unhandled exception:"
+      if (!message && /was thrown/i.test(l)) {
+        const after = l.split(/:\s*/).slice(1).join(': ').trim();
+        message = (after && !/^building/i.test(after)) ? after
+          : (lines[i + 1] && !this._isMetaLine(lines[i + 1]) ? lines[i + 1] : '');
+        continue;
+      }
+      if (!message && /^Unhandled exception/i.test(l)) {
+        message = lines[i + 1] && !this._isMetaLine(lines[i + 1]) ? lines[i + 1] : '';
+        continue;
+      }
+      // "The relevant error-causing widget was: Row Row:file://…"
+      const rel = l.match(/error-causing widget was:?\s*(.*)/i);
+      if (rel) {
+        const cand = (rel[1] || lines[i + 1] || '').trim();
+        if (cand) widget = this._shortWidgetName(cand);
+      }
+    }
+    if (!message) message = lines.find((l) => !this._isMetaLine(l)) || '';
+    return { message, widget };
+  }
+
+  // Emit a normalized error event. Message is cleaned; widget is short-form so it
+  // matches the widget tree. Deduped against a short rolling window so a single
+  // crash dumped across multiple stream lines doesn't spam the feed.
+  _emitError(message, { widget = null, severity = 'high', stack = null } = {}) {
+    const msg = this._cleanErrorMessage(message);
+    if (!msg || msg.length < 3) return;
+    const shortWidget = this._shortWidgetName(widget);
+    const now = Date.now();
+    this._recentErrors = (this._recentErrors || []).filter((e) => now - e.ts < 2000);
+    if (this._recentErrors.some((e) => e.msg === msg)) return;
+    this._recentErrors.push({ msg, ts: now });
+
+    this.emit('event', {
+      platform: 'flutter',
+      event: 'error',
+      timestamp: now,
+      severity,
+      widget: shortWidget,
+      title: msg.length > 120 ? msg.slice(0, 117) + '…' : msg,
+      metric: { message: msg, unit: 'error', stack: stack || null },
+      context: {},
+    });
+  }
+
+  // Structured Flutter framework error (FlutterErrorDetails). extensionData.data
+  // is a DiagnosticsNode tree; pull the most useful human-readable summary.
+  _handleFlutterError(event) {
+    const d = event.extensionData?.data ?? event.extensionData ?? {};
+    const summary =
+      d.errorSummary?.description ||
+      (Array.isArray(d.properties) && d.properties.find((p) => p.description)?.description) ||
+      d.description ||
+      d.renderedErrorText ||
+      'Flutter framework error';
+    const widget = d.errorSummary?.widgetRuntimeType || d.context?.description || null;
+    this._emitError(summary, { widget, severity: 'critical' });
+  }
+
+  // dev.log() / package:logging records. Only surface warnings and above so
+  // routine info/debug logs don't flood the error feed.
+  _handleLogRecord(rec) {
+    const level = Number(rec.level) || 0; // package:logging: WARNING=900, SEVERE=1000
+    if (level < 900) return;
+    const msg = this._decodeInstance(rec.message) || this._decodeInstance(rec.error);
+    if (!msg) return;
+    this._emitError(msg, {
+      widget: this._decodeInstance(rec.loggerName) || null,
+      severity: level >= 1000 ? 'critical' : 'medium',
+    });
+  }
+
+  // Uncaught errors / stack dumps written to stderr (base64 in the event).
+  _handleStderr(b64) {
+    let text = '';
+    try { text = Buffer.from(b64, 'base64').toString('utf8'); } catch { return; }
+    text = text.trim();
+    if (!text) return;
+    const { message, widget } = this._parseErrorDump(text);
+    if (!message) return; // pure stack/decoration with no headline — skip
+    this._emitError(message, { widget, severity: 'critical', stack: text.slice(0, 2000) });
+  }
+
+  // VM Service string values may arrive as {type:'@Instance', valueAsString}.
+  _decodeInstance(v) {
+    if (v == null) return '';
+    if (typeof v === 'string') return v;
+    return v.valueAsString || v.value || '';
+  }
+
+  // Flutter.Frame extensionData fields (all microseconds):
+  //   elapsed  — total frame duration
+  //   build    — Dart/widget build phase
+  //   raster   — GPU raster phase
+  //   vsyncOverhead — time from vsync to build start
+  _handleFlutterFrame(event) {
+    const d = event.extensionData?.data ?? event.extensionData ?? {};
+    const buildUs  = Number(d.build)  || 0;
+    const rasterUs = Number(d.raster) || 0;
+    const elapsedUs = Number(d.elapsed) || (buildUs + rasterUs);
+    const totalMs  = elapsedUs / 1000;
+
+    // Instantaneous FPS: a frame that took `totalMs` sustains 1000/totalMs fps,
+    // capped at the 60Hz display refresh. Sub-16.6ms frames all read as 60.
+    const fps = totalMs > 0 ? Math.min(60, Math.round(1000 / totalMs)) : 60;
+
+    this.emit('event', {
+      platform: 'flutter',
+      event: 'frame',
+      timestamp: Date.now(),
+      severity: totalMs > 33 ? 'critical' : totalMs > 16.6 ? 'high' : 'low',
+      widget: null,
+      metric: {
+        value:      parseFloat(totalMs.toFixed(2)),
+        unit:       'ms',
+        fps,
+        budget:     16.6,
+        exceededBy: totalMs > 16.6 ? parseFloat((totalMs - 16.6).toFixed(2)) : 0,
+        build:      parseFloat((buildUs  / 1000).toFixed(2)),
+        raster:     parseFloat((rasterUs / 1000).toFixed(2)),
+        frameNumber: d.number ?? null,
+      },
+      context: {},
+      raw: d,
+    });
+  }
+
+  // Poll the isolate's heap usage every 2s and emit a memory event. This is the
+  // only source of live memory data — Flutter doesn't push it as a stream.
+  _startMemoryPolling() {
+    if (this._memoryTimer) return;
+    this._memoryTimer = setInterval(async () => {
+      if (!this._connected) return;
+      let isolateId = this._isolateId;
+      if (!isolateId) {
+        const vm = await this._send('getVM', {});
+        isolateId = vm?.isolates?.[0]?.id || null;
+        this._isolateId = isolateId;
+      }
+      if (!isolateId) return;
+      const usage = await this._send('getMemoryUsage', { isolateId });
+      if (!usage) return;
+      const bytes = (Number(usage.heapUsage) || 0) + (Number(usage.externalUsage) || 0);
+      if (bytes <= 0) return;
+      this.emit('event', {
+        platform: 'flutter',
+        event: 'memory',
+        timestamp: Date.now(),
+        severity: 'low',
+        widget: null,
+        metric: {
+          value: bytes,
+          unit: 'bytes',
+          heapUsage: Number(usage.heapUsage) || 0,
+          heapCapacity: Number(usage.heapCapacity) || 0,
+          externalUsage: Number(usage.externalUsage) || 0,
+        },
+        context: {},
+      });
+    }, 2000);
+    this._memoryTimer.unref?.();
+  }
+
+  // BUILD timeline events are nested (a widget's build contains its children's
+  // builds), arriving as begin ('B') / end ('E') pairs with microsecond `ts`.
+  // We pair them with a stack to recover each widget's own build duration.
+  _handleTimelineEvents(events) {
+    for (const e of events) {
+      const name  = e.name ?? '';
+      const phase = e.ph   ?? '';
+      if (name !== 'BUILD') continue;
+
+      if (phase === 'B') {
+        // Short-form name so rebuilds line up with the widget tree + findings.
+        const widgetName = this._shortWidgetName(e.args?.type ?? e.args?.name ?? '');
+        this._buildStack.push({ widget: widgetName, ts: Number(e.ts) || 0 });
+      } else if (phase === 'E') {
+        const open = this._buildStack.pop();
+        if (!open || !open.widget) continue;
+        const durMs = ((Number(e.ts) || 0) - open.ts) / 1000;
+        this.emit('event', {
+          platform:  'flutter',
+          event:     'rebuild',
+          timestamp: Date.now(),
+          severity:  durMs > 8 ? 'high' : durMs > 4 ? 'medium' : 'low',
+          widget:    open.widget,
+          metric:    { value: 1, unit: 'rebuild', budget: 10, buildMs: parseFloat(durMs.toFixed(3)) },
+          context:   {},
+          raw:       e,
+        });
+      }
+    }
+  }
+}
+
+module.exports = new FlutterBridge();