linear-grab 0.20.1 → 0.21.0

package/README.md

@@ -26,7 +26,7 @@ export default function RootLayout({ children }) {
         {children}
         {process.env.NODE_ENV === "development" && (
           <Script
-            src="https://cdn.jsdelivr.net/gh/ahmedbanihanibh/linear-grab@v0.20.1/dist/index.global.js"
+            src="https://cdn.jsdelivr.net/gh/ahmedbanihanibh/linear-grab@v0.21.0/dist/index.global.js"
             crossOrigin="anonymous"
             strategy="afterInteractive"
           />

package/bin/linear-grab-bridge.mjs

@@ -16,7 +16,7 @@ import { createServer } from 'node:http';
 import { spawn, execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -28,7 +28,7 @@ const flag = (name, fallback) => {
 const PORT = Number(flag('--port', '4577'));
 const DIR = flag('--dir', process.cwd());
 const CLAUDE_BIN = flag('--claude', 'claude');
-const VERSION = '0.22.0';
+const VERSION = '0.24.1';
 
 /** Best-effort command runner (git/gh introspection). Never throws. */
 function run(cmd, args, cwd = DIR) {
@@ -629,6 +629,142 @@ createServer(async (req, res) => {
       );
       return json(res, 200, { statuses, previews });
     }
+    // ---- react-scan telemetry -------------------------------------------
+    // Browser pushes render/interaction events; they land in an append-only
+    // NDJSON file agents read directly (.lineargrab/scan.ndjson at the repo).
+    if (req.method === 'POST' && url.pathname === '/scan/events') {
+      const body = await readBody(req);
+      const events = Array.isArray(body.events) ? body.events : [body];
+      const dir = join(DIR, '.lineargrab');
+      try {
+        mkdirSync(dir, { recursive: true });
+        // Self-ignoring: telemetry must never pollute commits.
+        writeFileSync(join(dir, '.gitignore'), '*\n', { flag: 'wx' });
+      } catch {
+        /* exists */
+      }
+      const file = join(dir, 'scan.ndjson');
+      const lines =
+        events
+          .slice(0, 200)
+          .map((e) => JSON.stringify({ at: Date.now(), ...e }))
+          .join('\n') + '\n';
+      try {
+        appendFileSync(file, lines);
+        // Rotation: cap ~2MB by keeping the newest half.
+        const size = statSync(file).size;
+        if (size > 2_000_000) {
+          const keep = readFileSync(file, 'utf8');
+          writeFileSync(file, keep.slice(Math.floor(keep.length / 2)).replace(/^[^\n]*\n/, ''));
+        }
+      } catch {
+        /* disk issues — telemetry must never error the page */
+      }
+      return json(res, 200, { ok: true });
+    }
+    // Aggregated "what's slow right now" — a convenience view over the file.
+    if (req.method === 'GET' && url.pathname === '/scan/report') {
+      const windowMs = Number(url.searchParams.get('window') ?? 120_000);
+      let raw = '';
+      try {
+        raw = readFileSync(join(DIR, '.lineargrab', 'scan.ndjson'), 'utf8');
+      } catch {
+        return json(res, 200, { report: 'No scan telemetry yet — is react-scan running with the bridge enabled?', components: [] });
+      }
+      const cutoff = Date.now() - windowMs;
+      const byComponent = new Map();
+      const interactions = [];
+      let bursts = 0;
+      let worstFps = 60;
+      const pages = new Set();
+      for (const line of raw.split('\n')) {
+        if (!line) continue;
+        let e;
+        try {
+          e = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if ((e.at ?? 0) < cutoff) continue;
+        if (e.page) pages.add(e.page);
+        if (e.kind === 'interaction') interactions.push(e);
+        if (e.kind === 'long-render') {
+          bursts += 1;
+          if (typeof e.fps === 'number' && e.fps > 0) worstFps = Math.min(worstFps, e.fps);
+        }
+        for (const c of e.components ?? []) {
+          const cur = byComponent.get(c.name) ?? {
+            name: c.name,
+            renders: 0,
+            selfTime: 0,
+            source: c.source ?? null,
+            element: c.element ?? null,
+            pages: new Set(),
+            memoizableRenders: 0,
+            changes: {},
+          };
+          cur.renders += c.renders ?? 1;
+          cur.selfTime += c.selfTime ?? 0;
+          cur.source ??= c.source ?? null;
+          cur.element ??= c.element ?? null;
+          if (e.page) cur.pages.add(e.page);
+          if (c.memoizable) cur.memoizableRenders += c.renders ?? 1;
+          for (const ch of c.changes ?? []) cur.changes[ch] = (cur.changes[ch] ?? 0) + 1;
+          byComponent.set(c.name, cur);
+        }
+      }
+      const components = [...byComponent.values()]
+        .sort((a, b) => b.selfTime - a.selfTime)
+        .slice(0, 25)
+        .map((c) => ({ ...c, pages: [...c.pages] }));
+      const md = [
+        `# react-scan report (last ${Math.round(windowMs / 1000)}s)`,
+        '',
+        `Target 60 FPS — worst observed: ${worstFps} FPS across ${bursts} slow-frame burst(s).` +
+          (pages.size ? ` Pages: ${[...pages].join(', ')}` : ''),
+        '',
+        '## Components (fix top-down; each line = who, where, and WHY it re-rendered)',
+        ...components.map(
+          (c) =>
+            `- **${c.name}** — ${c.renders} renders · ${c.selfTime.toFixed(1)}ms self` +
+            (c.memoizableRenders
+              ? ` · ${c.memoizableRenders} renders with ZERO changes (memo() candidate)`
+              : '') +
+            (c.source ? ` · src \`${c.source}\`` : '') +
+            (c.element ? ` · el \`${c.element}\`` : '') +
+            (c.pages.length ? ` · on ${c.pages.join(', ')}` : '') +
+            (Object.keys(c.changes).length
+              ? ` · causes: ${Object.entries(c.changes)
+                  .sort((a, b) => b[1] - a[1])
+                  .slice(0, 4)
+                  .map(([k, v]) => `${k}×${v}`)
+                  .join(', ')} — (fn)=unstable callback→useCallback, (ref)=new identity→useMemo/hoist`
+              : ''),
+        ),
+        '',
+        '## Recent interactions (what the user did → what re-rendered because of it)',
+        ...interactions.slice(-10).flatMap((i) => [
+          `- ${i.type ?? '?'} on **${i.target ?? '?'}**${i.page ? ` (${i.page})` : ''} — ${Math.round(i.duration ?? 0)}ms` +
+            (i.slow ? ' ⚠ SLOW (>150ms INP)' : ''),
+          ...(i.components ?? [])
+            .slice(0, 4)
+            .map(
+              (c) =>
+                `    ↳ ${c.name} ×${c.renders} · ${(c.selfTime ?? 0).toFixed(1)}ms` +
+                (c.changes?.length ? ` · ${c.changes.join(', ')}` : '') +
+                (c.source ? ` · \`${c.source}\`` : ''),
+            ),
+        ]),
+      ].join('\n');
+      return json(res, 200, {
+        report: md,
+        worstFps,
+        bursts,
+        pages: [...pages],
+        components,
+        interactions: interactions.slice(-20),
+      });
+    }
     // Reset the staging branch: delete + recreate from the default branch.
     if (req.method === 'POST' && url.pathname === '/branch/reset') {
       const body = await readBody(req);
@@ -780,9 +916,29 @@ createServer(async (req, res) => {
     json(res, 500, { error: err instanceof Error ? err.message : String(err) });
   }
 }).listen(PORT, '127.0.0.1', () => {
-  console.log(`linear-grab bridge v${VERSION}`);
-  console.log(`  repo:   ${DIR}`);
-  console.log(`  listen: http://127.0.0.1:${PORT}  (localhost only)`);
-  console.log(`  tasks run: ${CLAUDE_BIN} -p (interactive stream-json, acceptEdits)`);
+  const B = '\x1b[1m';
+  const D = '\x1b[2m';
+  const C = '\x1b[36m';
+  const G = '\x1b[32m';
+  const R = '\x1b[0m';
+  console.log('');
+  console.log(`${B}◆ linear-grab bridge${R} ${D}v${VERSION}${R}`);
+  console.log(`${D}──────────────────────────────────────────────────${R}`);
+  console.log(`  repo    ${C}${DIR}${R}`);
+  console.log(`  listen  ${C}http://127.0.0.1:${PORT}${R} ${D}(localhost only)${R}`);
+  console.log(`  agent   ${C}${CLAUDE_BIN} -p${R} ${D}(interactive stream-json)${R}`);
+  console.log('');
+  console.log(`${B}react-scan telemetry${R} ${D}(when the app loads react-scan-banihani)${R}`);
+  console.log(`  events  ${G}.lineargrab/scan.ndjson${R} ${D}— newest last, gitignored${R}`);
+  console.log(`  report  ${G}curl -s http://127.0.0.1:${PORT}/scan/report${R}`);
+  console.log('');
+  console.log(`${B}point Claude Code at the render logs${R} — paste one of these:`);
+  console.log(`  ${D}»${R} Check the live render telemetry: read the newest lines of`);
+  console.log(`    .lineargrab/scan.ndjson and summarize the slow components.`);
+  console.log(`  ${D}»${R} curl -s http://127.0.0.1:${PORT}/scan/report ${D}(aggregated view)${R}`);
+  console.log(`  ${D}tip: add a line to your repo's AGENTS.md/CLAUDE.md so agents find it`);
+  console.log(`  on their own: "Live render telemetry: .lineargrab/scan.ndjson`);
+  console.log(`  (react-scan via linear-grab bridge); aggregate: GET /scan/report"${R}`);
+  console.log(`${D}──────────────────────────────────────────────────${R}`);
   loadHistory();
 });