@buoy-gg/highlight-updates 3.0.1 → 3.0.2

package/lib/module/highlight-updates/utils/rendersExportFormatter.js

@@ -1 +1,478 @@
-"use strict";function buildReport(e,n){let t=e.filter(e=>e.renderCount>=n.minRenders);if(n.filterCauses.length>0){const e=new Set(n.filterCauses);t=t.filter(n=>e.has(n.lastRenderCause?.type??"unknown"))}const o=e.flatMap(e=>[e.firstRenderTime,e.lastRenderTime]).filter(e=>Number.isFinite(e)),r=o.length>0?Math.max(...o)-Math.min(...o):0,a=Math.max(.001,r/1e3),s=(n.groupByName?groupByComponentName(t):t.map(e=>[e])).map(e=>processGroup(e,n,a));sortRows(s,n.sortBy);const u=-1===n.topN?0:Math.max(0,s.length-n.topN),p=-1===n.topN?s:s.slice(0,n.topN),i=e.reduce((e,n)=>e+n.renderCount,0),c=aggregateCauseBreakdown(e);let d=0,m=!1;for(const n of e)n.lastRenderCause||(d+=n.renderCount),n.renderHistory&&n.renderHistory.length>0&&(m=!0);return{totalUniqueComponents:t.length,totalRenders:i,windowMs:r,causeBreakdown:c,rows:p,truncated:u,dataGaps:{historyOff:!m,propsCaptureOff:!e.some(e=>e.renderHistory?.some(e=>void 0!==e.capturedProps)),stateCaptureOff:!e.some(e=>e.renderHistory?.some(e=>void 0!==e.capturedState)),rendersWithoutCause:d}}}function groupByComponentName(e){const n=new Map;for(const t of e){const e=t.componentName||t.displayName||t.viewType,o=n.get(e);o?o.push(t):n.set(e,[t])}return Array.from(n.values())}function processGroup(e,n,t){const o=e[0],r=o.componentName||o.displayName||o.viewType;let a=0;const s={},u=new Map,p=new Map,i=new Map;let c=0,d=0,m=0;for(const t of e){a+=t.renderCount;const e=t.lastRenderCause;if(!e)continue;const o=e.type;s[o]=(s[o]??0)+t.renderCount;const r=(e.hookChanges?.length??0)>0,h=(e.changedKeys?.length??0)>0;if("parent"===o&&("state"===e.componentCause||"props"===e.componentCause||r||h?d+=t.renderCount:m+=t.renderCount),"props"!==o||h||(c+=t.renderCount),e.parentComponentName&&i.set(e.parentComponentName,(i.get(e.parentComponentName)??0)+1),n.aggregateCauses&&e.hookChanges)for(const n of e.hookChanges){const e=`${n.type}[${n.index}]`,t=u.get(e);t?t.count+=1:u.set(e,{count:1,sample:formatHookSample(n)})}if(e.changedKeys)for(const n of e.changedKeys)n.includes("(ref only)")||p.set(n,(p.get(n)??0)+1)}const h=Array.from(u.entries()).sort((e,n)=>n[1].count-e[1].count).slice(0,3).map(([e,n])=>({hook:e,count:n.count,sample:n.sample})),l=Array.from(p.entries()).sort((e,n)=>n[1]-e[1]).slice(0,5).map(([e])=>e);let f,C="unknown",g=-1;for(const[e,n]of Object.entries(s))(n??0)>g&&(g=n??0,C=e);let y=0;for(const[e,n]of i)n>y&&(y=n,f=e);const w=e.map(e=>e.renderCount).sort((e,n)=>n-e),$=a/t;return{name:r,viewType:o.viewType,instances:e.length,renders:a,causeMix:s,dominantCause:C,hookCauses:h,changedKeys:l,unknownPropsCount:c,parentWithOwnChange:d,parentNoChange:m,parentName:f,instanceCounts:w,rate:$,source:e}}function aggregateCauseBreakdown(e){const n={};for(const t of e){const e=t.lastRenderCause?.type??"unknown";n[e]=(n[e]??0)+t.renderCount}return n}function sortRows(e,n){switch(n){case"renderCount":e.sort((e,n)=>n.renders-e.renders);break;case"rate":e.sort((e,n)=>n.rate-e.rate);break;case"name":e.sort((e,n)=>e.name.localeCompare(n.name))}}const VALUE_MAX_LEN=32;function truncateValue(e){if(null===e)return"null";if(void 0===e)return"undefined";if("function"==typeof e)return"[Fn]";if("object"==typeof e)return Array.isArray(e)?`[Array(${e.length})]`:"[Obj]";const n=String(e);return n.length>32?n.slice(0,31)+"…":n}function formatHookSample(e){return void 0===e.previousValue&&void 0===e.currentValue?e.description:`${truncateValue(e.previousValue)} → ${truncateValue(e.currentValue)}`}function formatWindow(e){return e<1e3?`${e}ms`:`${(e/1e3).toFixed(1)}s`}function formatRate(e){return e>=100?`${e.toFixed(0)}/s`:e>=10?`${e.toFixed(1)}/s`:`${e.toFixed(2)}/s`}function causeBreakdownLine(e){const n=Object.entries(e).sort((e,n)=>(n[1]??0)-(e[1]??0));return 0===n.length?"(no causes recorded)":n.map(([e,n])=>`${e} ${n}`).join(" · ")}function describeCause(e){const n=[],t=Object.entries(e.causeMix).filter(([,e])=>(e??0)>0).sort((e,n)=>(n[1]??0)-(e[1]??0)),o=t.length>=2&&(t[1]?.[1]??0)>=.1*e.renders;if("hooks"===e.dominantCause&&e.hookCauses.length>0){const t=e.hookCauses[0];t.sample?n.push(`hooks ×${t.count} ${t.hook}: ${t.sample}`):n.push(`hooks ×${t.count} ${t.hook}`)}else if("props"===e.dominantCause){if(e.changedKeys.length>0){const t=e.changedKeys.slice(0,3).join(", ");n.push(`props (${t})`)}else n.push("props (keys not captured)");e.unknownPropsCount>0&&e.changedKeys.length>0&&n.push(`[${e.unknownPropsCount} unidentified]`)}else if("parent"===e.dominantCause){let t="parent cascade";e.parentNoChange>0&&0===e.parentWithOwnChange&&(t="parent cascade, no own change"),e.parentName&&(t+=` ← ${e.parentName}`),n.push(t)}else"mount"===e.dominantCause?n.push("mount"):"state"===e.dominantCause?n.push("state"):"context"===e.dominantCause?n.push("context"):n.push("unknown");if(o){const e=t.map(([e,n])=>`${e}:${n}`).join(" + ");n.push(`(${e})`)}return n.join(" ")}function describeInstances(e){if(e.instances<=1)return e.name;const n=e.instanceCounts,t=n[0]??0;if(t-(n[n.length-1]??0)<=1)return`${e.name} ×${e.instances} (${t} each)`;const o=n.slice(1),r=o.reduce((e,n)=>e+n,0),a=o.length>0?r/o.length:0;return`${e.name} ×${e.instances} (top ${t}, others ~${Math.round(a)})`}const LLM_PREAMBLE="React Native render report — review the data and identify why components are re-rendering.";function generateSummary(e,n){const t=[];t.push(LLM_PREAMBLE),t.push(""),t.push(`Window: ${formatWindow(e.windowMs)} · ${e.totalUniqueComponents} components · ${e.totalRenders} renders`),t.push(`Cause mix: ${causeBreakdownLine(e.causeBreakdown)}`),t.push(""),t.push("Top offenders (count · rate · component · cause):"),t.push("");const o=e.rows.map(describeInstances),r=Math.min(36,Math.max(8,...o.map(e=>e.length))),a=Math.max(3,...e.rows.map(e=>`×${e.renders}`.length)),s=Math.max(5,...e.rows.map(e=>formatRate(e.rate).length));for(let n=0;n<e.rows.length;n++){const u=e.rows[n],p=(o[n]??u.name).padEnd(r),i=`×${u.renders}`.padStart(a),c=formatRate(u.rate).padStart(s),d=describeCause(u);t.push(`  ${i}  ${c}  ${p}  ${d}`)}e.truncated>0&&(t.push(""),t.push(`... ${e.truncated} more (set topN=-1 to expand)`));const u=buildDataFooter(e);if(u.length>0){t.push(""),t.push("Data availability:");for(const e of u)t.push(`  · ${e}`)}return t.join("\n")}function buildDataFooter(e){const n=[];return e.dataGaps.rendersWithoutCause>0&&n.push(`${e.dataGaps.rendersWithoutCause} renders had no cause info (enable trackRenderCauses for more detail)`),e.dataGaps.propsCaptureOff&&n.push("prop snapshots not captured (enable capturePropsOnRender to see prop diffs for 'props (keys not captured)' rows)"),e.dataGaps.stateCaptureOff&&n.push("state snapshots not captured (enable captureStateOnRender)"),e.dataGaps.historyOff&&n.push("render history off (enable enableRenderHistory for per-render timeline)"),n}function generateMarkdownTable(e,n){const t=[];t.push("# React Render Report"),t.push(""),t.push(`**Window:** ${formatWindow(e.windowMs)} · **Components:** ${e.totalUniqueComponents} · **Renders:** ${e.totalRenders}`),t.push(`**Cause mix:** ${causeBreakdownLine(e.causeBreakdown)}`),t.push(""),t.push("| Component | Renders | Rate | Cause |"),t.push("|---|---:|---:|---|");for(const n of e.rows){const e=describeInstances(n),o=describeCause(n).replace(/\|/g,"\\|");t.push(`| ${e} | ${n.renders} | ${formatRate(n.rate)} | ${o} |`)}e.truncated>0&&(t.push(""),t.push(`_... ${e.truncated} more rows_`));const o=buildDataFooter(e);if(o.length>0){t.push(""),t.push("**Data availability:**");for(const e of o)t.push(`- ${e}`)}return t.join("\n")}function generateJson(e,n,t){const o={exportedAt:(new Date).toISOString(),summary:{windowMs:n.windowMs,totalComponents:n.totalUniqueComponents,totalRenders:n.totalRenders,causeBreakdown:n.causeBreakdown,truncated:n.truncated,dataGaps:n.dataGaps},components:n.rows.map(e=>({name:e.name,viewType:e.viewType,instances:e.instances,instanceCounts:e.instances>1?e.instanceCounts:void 0,renders:e.renders,ratePerSec:Number(e.rate.toFixed(3)),dominantCause:e.dominantCause,causeMix:e.causeMix,hookCauses:e.hookCauses,changedKeys:e.changedKeys,unknownPropsCount:e.unknownPropsCount||void 0,parentName:e.parentName,parentWithOwnChange:e.parentWithOwnChange||void 0,parentNoChange:e.parentNoChange||void 0,...t.includeHistory?{history:extractHistory(e.source)}:{}}))};return t.includeHistory?JSON.stringify(o,null,2):JSON.stringify(o)}function extractHistory(e){return e.map(e=>({name:e.componentName||e.displayName,nativeTag:e.nativeTag,renderCount:e.renderCount,history:e.renderHistory?.map(e=>({n:e.renderNumber,t:e.timestamp,cause:{type:e.cause.type,componentCause:e.cause.componentCause,changedKeys:e.cause.changedKeys,parentComponentName:e.cause.parentComponentName,hookChanges:e.cause.hookChanges?.map(e=>({type:e.type,index:e.index,desc:e.description}))}}))}))}export function generateExport(e,n){const t=buildReport(e,n);switch(n.format){case"summary":default:return generateSummary(t,n);case"markdown-table":return generateMarkdownTable(t,n);case"json":return generateJson(e,t,n)}}export function estimateExportSize(e,n){return generateExport(e,n).length}export function getExportSummary(e){return{totalComponents:e.length,totalRenders:e.reduce((e,n)=>e+n.renderCount,0)}}export function generateSingleComponentExport(e){return generateExport([e],{format:"summary",topN:-1,minRenders:1,filterCauses:[],groupByName:!1,aggregateCauses:!0,sortBy:"renderCount",includeHistory:!1})}
+"use strict";
+
+/**
+ * Renders Export Formatter
+ *
+ * Pipeline: TrackedRender[] -> filter -> group -> aggregate -> sort -> format.
+ * Goal: compact, debug-focused output. Reports facts, not opinions.
+ */
+
+// =============================================================================
+// Internal types
+// =============================================================================
+
+// =============================================================================
+// Pipeline
+// =============================================================================
+
+function buildReport(renders, settings) {
+  let working = renders.filter(r => r.renderCount >= settings.minRenders);
+  if (settings.filterCauses.length > 0) {
+    const allowed = new Set(settings.filterCauses);
+    working = working.filter(r => allowed.has(r.lastRenderCause?.type ?? "unknown"));
+  }
+
+  // Window — computed from the original render list, not after topN
+  const allTimes = renders.flatMap(r => [r.firstRenderTime, r.lastRenderTime]).filter(t => Number.isFinite(t));
+  const windowMs = allTimes.length > 0 ? Math.max(...allTimes) - Math.min(...allTimes) : 0;
+  const windowSec = Math.max(0.001, windowMs / 1000);
+  const groups = settings.groupByName ? groupByComponentName(working) : working.map(r => [r]);
+  const processed = groups.map(group => processGroup(group, settings, windowSec));
+  sortRows(processed, settings.sortBy);
+  const truncated = settings.topN === -1 ? 0 : Math.max(0, processed.length - settings.topN);
+  const rows = settings.topN === -1 ? processed : processed.slice(0, settings.topN);
+  const totalRenders = renders.reduce((sum, r) => sum + r.renderCount, 0);
+  const causeBreakdown = aggregateCauseBreakdown(renders);
+
+  // Data-gap detection from the source renders (not after filtering)
+  let rendersWithoutCause = 0;
+  let historyPresent = false;
+  for (const r of renders) {
+    if (!r.lastRenderCause) rendersWithoutCause += r.renderCount;
+    if (r.renderHistory && r.renderHistory.length > 0) historyPresent = true;
+  }
+  return {
+    totalUniqueComponents: working.length,
+    totalRenders,
+    windowMs,
+    causeBreakdown,
+    rows,
+    truncated,
+    dataGaps: {
+      historyOff: !historyPresent,
+      // We can't directly observe whether the capture settings are on,
+      // but we can detect their effects: capturedProps/capturedState in events.
+      propsCaptureOff: !renders.some(r => r.renderHistory?.some(e => e.capturedProps !== undefined)),
+      stateCaptureOff: !renders.some(r => r.renderHistory?.some(e => e.capturedState !== undefined)),
+      rendersWithoutCause
+    }
+  };
+}
+function groupByComponentName(renders) {
+  const map = new Map();
+  for (const r of renders) {
+    const key = r.componentName || r.displayName || r.viewType;
+    const existing = map.get(key);
+    if (existing) {
+      existing.push(r);
+    } else {
+      map.set(key, [r]);
+    }
+  }
+  return Array.from(map.values());
+}
+function processGroup(group, settings, windowSec) {
+  const first = group[0];
+  const name = first.componentName || first.displayName || first.viewType;
+  let renders = 0;
+  const causeMix = {};
+  const hookCounter = new Map();
+  const changedKeyCounter = new Map();
+  const parentNameCounter = new Map();
+  let unknownPropsCount = 0;
+  let parentWithOwnChange = 0;
+  let parentNoChange = 0;
+  for (const r of group) {
+    renders += r.renderCount;
+    const cause = r.lastRenderCause;
+    if (!cause) continue;
+    const causeType = cause.type;
+    causeMix[causeType] = (causeMix[causeType] ?? 0) + r.renderCount;
+
+    // Track parent-cascade subtypes
+    const hadHookChange = (cause.hookChanges?.length ?? 0) > 0;
+    const hadKeyChange = (cause.changedKeys?.length ?? 0) > 0;
+    if (causeType === "parent") {
+      const ownChange = cause.componentCause === "state" || cause.componentCause === "props" || hadHookChange || hadKeyChange;
+      if (ownChange) parentWithOwnChange += r.renderCount;else parentNoChange += r.renderCount;
+    }
+
+    // Track props with no key info (cause detector saw a change but couldn't identify which)
+    if (causeType === "props" && !hadKeyChange) {
+      unknownPropsCount += r.renderCount;
+    }
+
+    // Parent name observation
+    if (cause.parentComponentName) {
+      parentNameCounter.set(cause.parentComponentName, (parentNameCounter.get(cause.parentComponentName) ?? 0) + 1);
+    }
+
+    // Aggregate hook causes
+    if (settings.aggregateCauses && cause.hookChanges) {
+      for (const hc of cause.hookChanges) {
+        const key = `${hc.type}[${hc.index}]`;
+        const existing = hookCounter.get(key);
+        if (existing) {
+          existing.count += 1;
+        } else {
+          hookCounter.set(key, {
+            count: 1,
+            sample: formatHookSample(hc)
+          });
+        }
+      }
+    }
+
+    // Aggregate changed keys (skip ref-only marks)
+    if (cause.changedKeys) {
+      for (const key of cause.changedKeys) {
+        if (key.includes("(ref only)")) continue;
+        changedKeyCounter.set(key, (changedKeyCounter.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  const hookCauses = Array.from(hookCounter.entries()).sort((a, b) => b[1].count - a[1].count).slice(0, 3).map(([hook, info]) => ({
+    hook,
+    count: info.count,
+    sample: info.sample
+  }));
+  const changedKeys = Array.from(changedKeyCounter.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([k]) => k);
+  let dominantCause = "unknown";
+  let max = -1;
+  for (const [cause, count] of Object.entries(causeMix)) {
+    if ((count ?? 0) > max) {
+      max = count ?? 0;
+      dominantCause = cause;
+    }
+  }
+
+  // Pick the most-observed parent name
+  let parentName;
+  let parentMax = 0;
+  for (const [n, c] of parentNameCounter) {
+    if (c > parentMax) {
+      parentMax = c;
+      parentName = n;
+    }
+  }
+  const instanceCounts = group.map(r => r.renderCount).sort((a, b) => b - a);
+  const rate = renders / windowSec;
+  return {
+    name,
+    viewType: first.viewType,
+    instances: group.length,
+    renders,
+    causeMix,
+    dominantCause,
+    hookCauses,
+    changedKeys,
+    unknownPropsCount,
+    parentWithOwnChange,
+    parentNoChange,
+    parentName,
+    instanceCounts,
+    rate,
+    source: group
+  };
+}
+function aggregateCauseBreakdown(renders) {
+  const out = {};
+  for (const r of renders) {
+    const t = r.lastRenderCause?.type ?? "unknown";
+    out[t] = (out[t] ?? 0) + r.renderCount;
+  }
+  return out;
+}
+function sortRows(rows, sortBy) {
+  switch (sortBy) {
+    case "renderCount":
+      rows.sort((a, b) => b.renders - a.renders);
+      break;
+    case "rate":
+      rows.sort((a, b) => b.rate - a.rate);
+      break;
+    case "name":
+      rows.sort((a, b) => a.name.localeCompare(b.name));
+      break;
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const VALUE_MAX_LEN = 32;
+function truncateValue(v) {
+  if (v === null) return "null";
+  if (v === undefined) return "undefined";
+  if (typeof v === "function") return "[Fn]";
+  if (typeof v === "object") {
+    if (Array.isArray(v)) return `[Array(${v.length})]`;
+    return "[Obj]";
+  }
+  const s = String(v);
+  return s.length > VALUE_MAX_LEN ? s.slice(0, VALUE_MAX_LEN - 1) + "…" : s;
+}
+function formatHookSample(hc) {
+  if (hc.previousValue === undefined && hc.currentValue === undefined) {
+    return hc.description;
+  }
+  return `${truncateValue(hc.previousValue)} → ${truncateValue(hc.currentValue)}`;
+}
+function formatWindow(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+function formatRate(rate) {
+  if (rate >= 100) return `${rate.toFixed(0)}/s`;
+  if (rate >= 10) return `${rate.toFixed(1)}/s`;
+  return `${rate.toFixed(2)}/s`;
+}
+function causeBreakdownLine(breakdown) {
+  const entries = Object.entries(breakdown).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0));
+  if (entries.length === 0) return "(no causes recorded)";
+  return entries.map(([k, v]) => `${k} ${v}`).join(" · ");
+}
+function describeCause(row) {
+  const parts = [];
+
+  // Per-row cause mix when at least 2 causes contribute (≥10% each)
+  const mixEntries = Object.entries(row.causeMix).filter(([, v]) => (v ?? 0) > 0).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0));
+  const showMix = mixEntries.length >= 2 && (mixEntries[1]?.[1] ?? 0) >= row.renders * 0.1;
+  if (row.dominantCause === "hooks" && row.hookCauses.length > 0) {
+    const top = row.hookCauses[0];
+    if (top.sample) {
+      parts.push(`hooks ×${top.count} ${top.hook}: ${top.sample}`);
+    } else {
+      parts.push(`hooks ×${top.count} ${top.hook}`);
+    }
+  } else if (row.dominantCause === "props") {
+    if (row.changedKeys.length > 0) {
+      const keys = row.changedKeys.slice(0, 3).join(", ");
+      parts.push(`props (${keys})`);
+    } else {
+      parts.push(`props (keys not captured)`);
+    }
+    if (row.unknownPropsCount > 0 && row.changedKeys.length > 0) {
+      parts.push(`[${row.unknownPropsCount} unidentified]`);
+    }
+  } else if (row.dominantCause === "parent") {
+    let label = "parent cascade";
+    if (row.parentNoChange > 0 && row.parentWithOwnChange === 0) {
+      label = "parent cascade, no own change";
+    }
+    if (row.parentName) label += ` ← ${row.parentName}`;
+    parts.push(label);
+  } else if (row.dominantCause === "mount") {
+    parts.push("mount");
+  } else if (row.dominantCause === "state") {
+    parts.push("state");
+  } else if (row.dominantCause === "context") {
+    parts.push("context");
+  } else {
+    parts.push("unknown");
+  }
+  if (showMix) {
+    const mixStr = mixEntries.map(([k, v]) => `${k}:${v}`).join(" + ");
+    parts.push(`(${mixStr})`);
+  }
+  return parts.join(" ");
+}
+function describeInstances(row) {
+  if (row.instances <= 1) return row.name;
+  const counts = row.instanceCounts;
+  const max = counts[0] ?? 0;
+  const min = counts[counts.length - 1] ?? 0;
+  const evenly = max - min <= 1;
+  if (evenly) {
+    return `${row.name} ×${row.instances} (${max} each)`;
+  }
+  // Uneven — show top instance vs others
+  const others = counts.slice(1);
+  const othersSum = others.reduce((s, n) => s + n, 0);
+  const othersAvg = others.length > 0 ? othersSum / others.length : 0;
+  return `${row.name} ×${row.instances} (top ${max}, others ~${Math.round(othersAvg)})`;
+}
+
+// =============================================================================
+// Format generators
+// =============================================================================
+
+const LLM_PREAMBLE = "React Native render report — review the data and identify why components are re-rendering.";
+function generateSummary(report, _settings) {
+  const lines = [];
+  lines.push(LLM_PREAMBLE);
+  lines.push("");
+  lines.push(`Window: ${formatWindow(report.windowMs)} · ${report.totalUniqueComponents} components · ${report.totalRenders} renders`);
+  lines.push(`Cause mix: ${causeBreakdownLine(report.causeBreakdown)}`);
+  lines.push("");
+  lines.push("Top offenders (count · rate · component · cause):");
+  lines.push("");
+  const nameStrings = report.rows.map(describeInstances);
+  const nameWidth = Math.min(36, Math.max(8, ...nameStrings.map(n => n.length)));
+  const countWidth = Math.max(3, ...report.rows.map(r => `×${r.renders}`.length));
+  const rateWidth = Math.max(5, ...report.rows.map(r => formatRate(r.rate).length));
+  for (let i = 0; i < report.rows.length; i++) {
+    const row = report.rows[i];
+    const name = (nameStrings[i] ?? row.name).padEnd(nameWidth);
+    const count = `×${row.renders}`.padStart(countWidth);
+    const rate = formatRate(row.rate).padStart(rateWidth);
+    const reason = describeCause(row);
+    lines.push(`  ${count}  ${rate}  ${name}  ${reason}`);
+  }
+  if (report.truncated > 0) {
+    lines.push("");
+    lines.push(`... ${report.truncated} more (set topN=-1 to expand)`);
+  }
+
+  // Data-availability footer
+  const footer = buildDataFooter(report);
+  if (footer.length > 0) {
+    lines.push("");
+    lines.push("Data availability:");
+    for (const line of footer) lines.push(`  · ${line}`);
+  }
+  return lines.join("\n");
+}
+function buildDataFooter(report) {
+  const out = [];
+  if (report.dataGaps.rendersWithoutCause > 0) {
+    out.push(`${report.dataGaps.rendersWithoutCause} renders had no cause info (enable trackRenderCauses for more detail)`);
+  }
+  if (report.dataGaps.propsCaptureOff) {
+    out.push("prop snapshots not captured (enable capturePropsOnRender to see prop diffs for 'props (keys not captured)' rows)");
+  }
+  if (report.dataGaps.stateCaptureOff) {
+    out.push("state snapshots not captured (enable captureStateOnRender)");
+  }
+  if (report.dataGaps.historyOff) {
+    out.push("render history off (enable enableRenderHistory for per-render timeline)");
+  }
+  return out;
+}
+function generateMarkdownTable(report, _settings) {
+  const lines = [];
+  lines.push(`# React Render Report`);
+  lines.push("");
+  lines.push(`**Window:** ${formatWindow(report.windowMs)} · **Components:** ${report.totalUniqueComponents} · **Renders:** ${report.totalRenders}`);
+  lines.push(`**Cause mix:** ${causeBreakdownLine(report.causeBreakdown)}`);
+  lines.push("");
+  lines.push("| Component | Renders | Rate | Cause |");
+  lines.push("|---|---:|---:|---|");
+  for (const row of report.rows) {
+    const name = describeInstances(row);
+    const reason = describeCause(row).replace(/\|/g, "\\|");
+    lines.push(`| ${name} | ${row.renders} | ${formatRate(row.rate)} | ${reason} |`);
+  }
+  if (report.truncated > 0) {
+    lines.push("");
+    lines.push(`_... ${report.truncated} more rows_`);
+  }
+  const footer = buildDataFooter(report);
+  if (footer.length > 0) {
+    lines.push("");
+    lines.push("**Data availability:**");
+    for (const line of footer) lines.push(`- ${line}`);
+  }
+  return lines.join("\n");
+}
+function generateJson(_renders, report, settings) {
+  const exportData = {
+    exportedAt: new Date().toISOString(),
+    summary: {
+      windowMs: report.windowMs,
+      totalComponents: report.totalUniqueComponents,
+      totalRenders: report.totalRenders,
+      causeBreakdown: report.causeBreakdown,
+      truncated: report.truncated,
+      dataGaps: report.dataGaps
+    },
+    components: report.rows.map(row => ({
+      name: row.name,
+      viewType: row.viewType,
+      instances: row.instances,
+      instanceCounts: row.instances > 1 ? row.instanceCounts : undefined,
+      renders: row.renders,
+      ratePerSec: Number(row.rate.toFixed(3)),
+      dominantCause: row.dominantCause,
+      causeMix: row.causeMix,
+      hookCauses: row.hookCauses,
+      changedKeys: row.changedKeys,
+      unknownPropsCount: row.unknownPropsCount || undefined,
+      parentName: row.parentName,
+      parentWithOwnChange: row.parentWithOwnChange || undefined,
+      parentNoChange: row.parentNoChange || undefined,
+      ...(settings.includeHistory ? {
+        history: extractHistory(row.source)
+      } : {})
+    }))
+  };
+  return settings.includeHistory ? JSON.stringify(exportData, null, 2) : JSON.stringify(exportData);
+}
+function extractHistory(source) {
+  return source.map(r => ({
+    name: r.componentName || r.displayName,
+    nativeTag: r.nativeTag,
+    renderCount: r.renderCount,
+    history: r.renderHistory?.map(e => ({
+      n: e.renderNumber,
+      t: e.timestamp,
+      cause: {
+        type: e.cause.type,
+        componentCause: e.cause.componentCause,
+        changedKeys: e.cause.changedKeys,
+        parentComponentName: e.cause.parentComponentName,
+        hookChanges: e.cause.hookChanges?.map(h => ({
+          type: h.type,
+          index: h.index,
+          desc: h.description
+        }))
+      }
+    }))
+  }));
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export function generateExport(renders, settings) {
+  const report = buildReport(renders, settings);
+  switch (settings.format) {
+    case "summary":
+      return generateSummary(report, settings);
+    case "markdown-table":
+      return generateMarkdownTable(report, settings);
+    case "json":
+      return generateJson(renders, report, settings);
+    default:
+      return generateSummary(report, settings);
+  }
+}
+export function estimateExportSize(renders, settings) {
+  return generateExport(renders, settings).length;
+}
+export function getExportSummary(renders) {
+  return {
+    totalComponents: renders.length,
+    totalRenders: renders.reduce((sum, r) => sum + r.renderCount, 0)
+  };
+}
+
+/**
+ * Export a single component's detail (used by RenderDetailView copy button).
+ * Always uses the summary format since detail copies are inherently small.
+ */
+export function generateSingleComponentExport(render) {
+  const settings = {
+    format: "summary",
+    topN: -1,
+    minRenders: 1,
+    filterCauses: [],
+    groupByName: false,
+    aggregateCauses: true,
+    sortBy: "renderCount",
+    includeHistory: false
+  };
+  return generateExport([render], settings);
+}

package/lib/module/index.js

@@ -1 +1,74 @@
-"use strict";export{highlightUpdatesPreset,createHighlightUpdatesTool,highlightUpdatesModalPreset,createHighlightUpdatesModalTool}from"./preset";export{default as HighlightUpdatesController}from"./highlight-updates/utils/HighlightUpdatesController";export{HighlightUpdatesOverlay}from"./highlight-updates/HighlightUpdatesOverlay";export{installProfilerInterceptor,uninstallProfilerInterceptor,setComparisonCallback,isInterceptorInstalled,enableProfilerLogging,disableProfilerLogging,isLoggingEnabled}from"./highlight-updates/utils/ProfilerInterceptor";export{RenderTracker}from"./highlight-updates/utils/RenderTracker";export const onRenderEvent=e=>{const{RenderTracker:t}=require("./highlight-updates/utils/RenderTracker");return t.onRenderEvent(e)};export{detectRenderCause,clearRenderCauseState,removeRenderCauseState,getRenderCauseStats,safeCloneForHistory,capturePropsSnapshot,captureStateSnapshot}from"./highlight-updates/utils/RenderCauseDetector";export{PerformanceLogger}from"./highlight-updates/utils/PerformanceLogger";export{VIEW_TYPE_MAP,getComponentDisplayName,getNativeViewType,isKnownViewType,getAllNativeViewTypes,getAllComponentNames}from"./highlight-updates/utils/ViewTypeMapper";export{HighlightUpdatesModal}from"./highlight-updates/components/HighlightUpdatesModal";export{RenderListItem}from"./highlight-updates/components/RenderListItem";export{RenderDetailView}from"./highlight-updates/components/RenderDetailView";export{HighlightFilterView}from"./highlight-updates/components/HighlightFilterView";export{RenderCauseBadge,TwoLevelCauseBadge,CAUSE_CONFIG,COMPONENT_CAUSE_CONFIG}from"./highlight-updates/components/RenderCauseBadge";export{RenderHistoryViewer,RenderHistoryFooter}from"./highlight-updates/components/RenderHistoryViewer";export{generateRendersJson}from"./highlight-updates/utils/renderExportFormatter";
+"use strict";
+
+/**
+ * @buoy-gg/highlight-updates
+ *
+ * Standalone implementation of React DevTools' "Highlight updates when components
+ * render" feature. Works without requiring DevTools to be connected.
+ *
+ * @example
+ * ```tsx
+ * // Toggle-only preset - tap to enable/disable highlights
+ * import { highlightUpdatesPreset } from '@buoy-gg/highlight-updates';
+ *
+ * <FloatingDevTools apps={[highlightUpdatesPreset]} />
+ *
+ * // Modal preset - full interface with filters and render list
+ * import { highlightUpdatesModalPreset } from '@buoy-gg/highlight-updates';
+ *
+ * <FloatingDevTools apps={[highlightUpdatesModalPreset]} />
+ *
+ * // Or use the standalone controller programmatically
+ * import { HighlightUpdatesController } from '@buoy-gg/highlight-updates';
+ *
+ * HighlightUpdatesController.toggle();
+ * HighlightUpdatesController.enable();
+ * HighlightUpdatesController.disable();
+ * ```
+ */
+
+// Preset exports for FloatingDevTools integration
+export { highlightUpdatesPreset, createHighlightUpdatesTool, highlightUpdatesModalPreset, createHighlightUpdatesModalTool } from "./preset";
+
+// Controller export for standalone usage
+export { default as HighlightUpdatesController } from "./highlight-updates/utils/HighlightUpdatesController";
+
+// External sync (adapter for @buoy-gg/external-sync's useExternalSync)
+export { highlightUpdatesSyncAdapter } from "./sync/highlightUpdatesSyncAdapter";
+
+// Overlay component - auto-rendered by FloatingDevTools, but exported for manual usage
+export { HighlightUpdatesOverlay } from "./highlight-updates/HighlightUpdatesOverlay";
+
+// Profiler interceptor for debugging - captures what DevTools detects
+export { installProfilerInterceptor, uninstallProfilerInterceptor, setComparisonCallback, isInterceptorInstalled, enableProfilerLogging, disableProfilerLogging, isLoggingEnabled } from "./highlight-updates/utils/ProfilerInterceptor";
+
+// RenderTracker singleton for tracking render history
+export { RenderTracker } from "./highlight-updates/utils/RenderTracker";
+// Convenience export for unified events integration
+export const onRenderEvent = callback => {
+  const {
+    RenderTracker
+  } = require("./highlight-updates/utils/RenderTracker");
+  return RenderTracker.onRenderEvent(callback);
+};
+
+// RenderCauseDetector for detecting why components rendered
+export { detectRenderCause, clearRenderCauseState, removeRenderCauseState, getRenderCauseStats,
+// Snapshot capture for render history
+safeCloneForHistory, capturePropsSnapshot, captureStateSnapshot } from "./highlight-updates/utils/RenderCauseDetector";
+
+// PerformanceLogger for performance measurement and debugging
+export { PerformanceLogger } from "./highlight-updates/utils/PerformanceLogger";
+// ViewTypeMapper for translating native view names to component names
+export { VIEW_TYPE_MAP, getComponentDisplayName, getNativeViewType, isKnownViewType, getAllNativeViewTypes, getAllComponentNames } from "./highlight-updates/utils/ViewTypeMapper";
+
+// Modal components for custom integrations
+export { HighlightUpdatesModal } from "./highlight-updates/components/HighlightUpdatesModal";
+export { RenderListItem } from "./highlight-updates/components/RenderListItem";
+export { RenderDetailView } from "./highlight-updates/components/RenderDetailView";
+export { HighlightFilterView } from "./highlight-updates/components/HighlightFilterView";
+export { RenderCauseBadge, TwoLevelCauseBadge, CAUSE_CONFIG, COMPONENT_CAUSE_CONFIG } from "./highlight-updates/components/RenderCauseBadge";
+export { RenderHistoryViewer, RenderHistoryFooter } from "./highlight-updates/components/RenderHistoryViewer";
+
+// Simple JSON export for renders
+export { generateRendersJson } from "./highlight-updates/utils/renderExportFormatter";