zeitzeuge 0.9.0 → 0.10.0

package/dist/cli.js

@@ -747,7 +747,7 @@ When your analysis is complete, you MUST write ALL findings to a JSON file using
 
 1. Call write_file with path: \`/findings/<YOUR_AGENT_NAME>.json\`
    Use your agent name as the filename (e.g. memory-heap, page-load, runtime-blocking,
-   code-pattern, cpu-hotspot, listener-leak, memory-closure).
+   code-pattern, rendering-fcp, cpu-hotspot, listener-leak, memory-closure).
 
 2. The file content MUST be a JSON object with this exact structure:
    { "findings": [ { "severity": "...", "title": "...", ... }, ... ] }
@@ -766,7 +766,9 @@ var STRUCTURED_OUTPUT_FIELDS = `## Structured output fields — REQUIRED for eve
 
 Every finding MUST include ALL of these fields:
 
-- \`sourceFile\` — (REQUIRED) the workspace path (e.g. src/utils/parser.ts or scripts/app.js)
+- \`sourceFile\` — (REQUIRED) the EXACT workspace path you used with read_file
+  (e.g. /scripts/app.js, /styles/theme.css, /html/index).
+  NEVER use bare filenames, original URLs, or paths you did not read.
 - \`lineNumber\` — (REQUIRED) the 1-based line number, verified by reading the file
 - \`confidence\` — \`high\` if you read the source, \`medium\` if strongly suggested,
   \`low\` if inferred
@@ -2734,6 +2736,9 @@ function generateMarkdown(options) {
   const reqCount = trace.networkRequests.length;
   sections.push(`**Page load** ${loadSec}s · **FCP** ${fcpSec}s · **TBT** ${tbt}ms · ` + `**Heap** ${heapSize} · **${reqCount} requests** (${formatBytes(totalTransfer)} transferred)`);
   sections.push("");
+  if (trace.renderingDiagnostic) {
+    sections.push(...generateFilmstripSection(trace.renderingDiagnostic, trace.screencastFrames ?? []));
+  }
   const counts = {
     critical: findings.filter((f) => f.severity === "critical").length,
     warning: findings.filter((f) => f.severity === "warning").length,
@@ -2819,6 +2824,78 @@ function generateMarkdown(options) {
   return sections.join(`
 `);
 }
+var MAX_FILMSTRIP_FRAMES = 10;
+function selectKeyFrames(diagnostic, frames) {
+  if (frames.length === 0)
+    return [];
+  const changeIndices = new Set(diagnostic.visualChanges.map((vc) => vc.frameIndex));
+  changeIndices.add(0);
+  changeIndices.add(frames.length - 1);
+  const selected = [...changeIndices].sort((a, b) => a - b).filter((i) => i >= 0 && i < frames.length).map((i) => frames[i]);
+  if (selected.length <= MAX_FILMSTRIP_FRAMES)
+    return selected;
+  const step = Math.ceil(selected.length / MAX_FILMSTRIP_FRAMES);
+  const sampled = [];
+  for (let i = 0;i < selected.length; i += step) {
+    sampled.push(selected[i]);
+  }
+  if (sampled[sampled.length - 1] !== selected[selected.length - 1]) {
+    sampled.push(selected[selected.length - 1]);
+  }
+  return sampled.slice(0, MAX_FILMSTRIP_FRAMES);
+}
+function generateFilmstripSection(diagnostic, frames) {
+  const sections = [];
+  sections.push(`## Rendering Filmstrip`);
+  sections.push("");
+  const speedIdx = diagnostic.speedIndex;
+  const fcpTs = diagnostic.fcpCorrelation.fcpTimestamp;
+  sections.push(`**Speed Index** ${speedIdx}ms · **FCP** ${fcpTs}ms`);
+  sections.push("");
+  const keyFrames = selectKeyFrames(diagnostic, frames);
+  if (keyFrames.length > 0) {
+    const headerCells = keyFrames.map((f) => `${Math.round(f.timestamp)}ms`).join(" | ");
+    const separatorCells = keyFrames.map(() => ":---:").join(" | ");
+    const imageCells = keyFrames.map((f) => `<img src="data:image/jpeg;base64,${f.data}" width="120" alt="${Math.round(f.timestamp)}ms" />`).join(" | ");
+    sections.push(`| ${headerCells} |`);
+    sections.push(`| ${separatorCells} |`);
+    sections.push(`| ${imageCells} |`);
+    sections.push("");
+  }
+  if (diagnostic.visualChanges.length > 0) {
+    sections.push(`### Visual Progress`);
+    sections.push("");
+    sections.push(`| Time | Visual Completeness |`);
+    sections.push(`|------|:-------------------:|`);
+    for (const vc of diagnostic.visualChanges) {
+      const bar = "█".repeat(Math.round(vc.visualCompleteness / 5)) + "░".repeat(20 - Math.round(vc.visualCompleteness / 5));
+      sections.push(`| ${Math.round(vc.timestamp)}ms | ${bar} ${vc.visualCompleteness}% |`);
+    }
+    sections.push("");
+  }
+  if (diagnostic.renderingPhases.length > 0) {
+    sections.push(`### Rendering Phases`);
+    sections.push("");
+    sections.push(`| Phase | Duration | Description |`);
+    sections.push(`|-------|----------|-------------|`);
+    for (const phase of diagnostic.renderingPhases) {
+      sections.push(`| ${phase.name} | ${phase.duration}ms | ${phase.description} |`);
+    }
+    sections.push("");
+  }
+  if (diagnostic.fcpBottlenecks.length > 0) {
+    sections.push(`### FCP Bottlenecks`);
+    sections.push("");
+    sections.push(`| Type | Estimated Delay | Description |`);
+    sections.push(`|------|:---------------:|-------------|`);
+    for (const b of diagnostic.fcpBottlenecks) {
+      const typeLabel = b.type.replace(/-/g, " ");
+      sections.push(`| ${typeLabel} | ${b.estimatedDelayMs}ms | ${b.description} |`);
+    }
+    sections.push("");
+  }
+  return sections;
+}
 // src/analysis/agent.ts
 import { createDeepAgent as createDeepAgent2 } from "deepagents";
 
@@ -2832,7 +2909,7 @@ skill. Do NOT read data JSON files directly with read_file.
 
 After your analysis scripts identify specific issues, read at most 1-3
 source files that are directly implicated. Derive paths from script URLs
-in the data (e.g. a URL ending in "abc123.js" → scripts/abc123.js).
+in the data (e.g. a URL ending in "abc123.js" → /scripts/abc123.js).
 
 PREFERRED actions:
 - execute_command with pre-built helper scripts or custom Node.js scripts
@@ -2843,7 +2920,22 @@ FORBIDDEN actions:
 - glob — NEVER call glob.
 - read_file on data JSON files — use scripts to extract what you need.
 - Reading ALL source files — only read the specific ones your scripts point to.
-- Reading more than 3 source files — focus on the most impactful issues.`;
+- Reading more than 3 source files — focus on the most impactful issues.
+
+## CRITICAL: sourceFile path format
+
+When setting \`sourceFile\` in a finding, use the EXACT WORKSPACE PATH you
+used when calling read_file. Workspace paths start with a leading slash:
+- \`/scripts/App.tsx\` — JavaScript/TypeScript source files
+- \`/styles/theme.css\` — CSS source files
+- \`/html/index\` — HTML document
+
+If you read a file at path \`/scripts/App.tsx\`, set \`sourceFile\` to exactly
+\`/scripts/App.tsx\`. Do NOT use bare filenames like \`App.tsx\`, original
+URLs like \`http://localhost:.../src/components/App.tsx\`, or made-up paths.
+
+NEVER reference a file you did not actually read — only files you verified
+with read_file should appear in sourceFile.`;
 var MINIFIED_SOURCE_HANDLING = `## Handling minified / compiled source files
 
 The JavaScript files in scripts/ are captured from a PRODUCTION page. They are
@@ -3452,6 +3544,140 @@ Images without explicit width/height that cause Cumulative Layout Shift (CLS).
 Check HTML and CSS completely. For scripts, focus on the ones that HTML/CSS
 point to as potentially problematic. A typical page has 3-8 issues.
 
+${BROWSER_TOOL_CALL_STRATEGY}
+${VERIFICATION_RULES}
+${SEVERITY_RULES2}
+${FINDING_CATEGORIES}
+${OUTPUT_FORMAT}
+${STRUCTURED_OUTPUT_FIELDS}
+${MINIFIED_SOURCE_HANDLING}
+${IMPACT_ESTIMATION}
+${WRITE_FINDINGS_REQUIREMENT}`;
+// src/analysis/prompts/rendering-fcp.ts
+var RENDERING_FCP_PROMPT = `You are a specialist in analyzing rendering performance and First Contentful Paint (FCP) behavior.
+
+You have access to a workspace with rendering diagnostic data captured via Chrome DevTools screencast, along with trace, network, and source files from a real page load.
+
+## Your focus areas
+
+### 1. FCP Bottleneck Analysis (HIGHEST PRIORITY)
+
+Identify what delays First Contentful Paint — the moment the browser renders the first piece of DOM content (text, image, SVG, or non-white canvas).
+
+\`\`\`html
+<!-- BAD: synchronous script in <head> blocks FCP -->
+<head>
+  <script src="/heavy-analytics.js"></script>
+  <link rel="stylesheet" href="/all-styles.css">
+</head>
+
+<!-- GOOD: defer non-critical scripts, inline critical CSS -->
+<head>
+  <style>/* critical above-fold CSS only */</style>
+  <script src="/heavy-analytics.js" defer></script>
+  <link rel="stylesheet" href="/all-styles.css" media="print" onload="this.media='all'">
+</head>
+\`\`\`
+
+**How to detect:** Read /trace/rendering/fcp-diagnostic.json for pre-computed FCP bottlenecks with estimated delay times. Cross-reference with the render-blocking chain and main-thread blockers. For each bottleneck, read the corresponding source file to verify the root cause and propose a fix.
+
+### 2. Rendering Order & Visual Progress
+
+Analyze the order in which content appears on screen during page load. Identify elements that render late but should appear early (e.g. hero content, navigation, above-the-fold text).
+
+\`\`\`javascript
+// BAD: hero image loaded lazily despite being above the fold
+<img src="hero.jpg" loading="lazy">
+
+// GOOD: eager-load above-fold content, lazy-load below-fold
+<img src="hero.jpg" fetchpriority="high">
+<img src="below-fold.jpg" loading="lazy">
+\`\`\`
+
+**How to detect:** Read /trace/rendering/visual-progress.json for the visual change timeline. Each visual change point shows when new content appeared and the estimated visual completeness. Correlate visual change timestamps with network-waterfall.json to identify which resources trigger which visual changes.
+
+### 3. Render-Blocking Resource Chains
+
+Sequential chains of render-blocking resources that compound FCP delay. Each resource in the chain must complete before the next starts, creating a waterfall that delays first render.
+
+\`\`\`html
+<!-- BAD: CSS imports create sequential chains -->
+<!-- main.css: @import url('reset.css'); @import url('theme.css'); -->
+<link rel="stylesheet" href="/main.css">
+
+<!-- GOOD: flatten CSS imports into parallel <link> tags -->
+<link rel="stylesheet" href="/reset.css">
+<link rel="stylesheet" href="/theme.css">
+<link rel="stylesheet" href="/main.css">
+\`\`\`
+
+**How to detect:** The fcp-diagnostic.json file lists sequential resource chains. Read the CSS files to check for @import chains. Check HTML for script/stylesheet ordering that creates unnecessary serialization.
+
+### 4. Speed Index & Visual Completeness
+
+Speed Index measures how quickly the visible page area is filled with content. A high Speed Index means content renders slowly or in large bursts rather than progressively.
+
+**How to detect:** Read /trace/rendering/visual-progress.json for the speedIndex value and the rendering phases. Identify phases with disproportionately long duration. Compare visual change frequency — long gaps between changes indicate rendering stalls.
+
+### 5. Layout Thrashing Before FCP
+
+Excessive layout recalculations during the critical rendering path that delay first paint.
+
+\`\`\`javascript
+// BAD: script in <head> forces layout before FCP
+document.querySelectorAll('.hero').forEach(el => {
+  el.style.height = el.offsetHeight * 2 + 'px'; // forced layout
+});
+
+// GOOD: defer DOM manipulation to after DOMContentLoaded
+document.addEventListener('DOMContentLoaded', () => {
+  requestAnimationFrame(() => {
+    document.querySelectorAll('.hero').forEach(el => {
+      el.style.height = el.offsetHeight * 2 + 'px';
+    });
+  });
+});
+\`\`\`
+
+**How to detect:** The fcp-diagnostic.json includes layoutTimeBeforeFCP. If significant (>100ms), check trace/runtime/blocking-functions.json for Layout events before FCP and read the triggering scripts.
+
+## Your workflow
+
+1. In your FIRST turn, run BOTH of these:
+   a. Run the workspace overview:
+      execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+   b. Read the FCP diagnostic:
+      read_file: /trace/rendering/fcp-diagnostic.json
+   c. Read the visual progress:
+      read_file: /trace/rendering/visual-progress.json
+2. From the FCP diagnostic, identify bottlenecks sorted by estimated delay.
+3. For each bottleneck, determine the root cause:
+   - Render-blocking resources → read the source file and HTML
+   - Long tasks before FCP → read the blocking script
+   - Sequential chains → check CSS for @import and HTML for script ordering
+   - Slow server response → note in finding, suggest CDN/caching
+4. Cross-reference visual progress with network waterfall to explain
+   rendering order and identify missed optimization opportunities.
+5. Report each bottleneck and improvement opportunity as a separate finding.
+
+### Source file path mapping
+
+The FCP diagnostic data contains resource URLs (e.g. http://localhost:.../src/utils/foo.js).
+To read the actual source, map the URL's last path segment to its workspace path:
+- Scripts: URL ending in \`foo.js\` → workspace path \`/scripts/foo.js\`
+- Stylesheets: URL ending in \`bar.css\` → workspace path \`/styles/bar.css\`
+- HTML document: \`/html/index\`
+
+Always use the WORKSPACE PATH (with leading /) in your finding's \`sourceFile\` field.
+
+### CRITICAL: Report EACH issue as a SEPARATE finding
+
+- Each render-blocking resource → separate finding
+- Each sequential resource chain → separate finding
+- Each long task before FCP → separate finding
+- Slow server response → separate finding
+- Poor visual progress pattern → separate finding
+
 ${BROWSER_TOOL_CALL_STRATEGY}
 ${VERIFICATION_RULES}
 ${SEVERITY_RULES2}
@@ -3467,12 +3693,12 @@ var BROWSER_ORCHESTRATOR_PROMPT = `You are a performance analysis orchestrator.
 
 ## Instructions
 
-1. Read the user message — it contains exactly 4 task descriptions.
-2. In your FIRST response, call the \`task\` tool exactly 4 times.
+1. Read the user message — it contains task descriptions (4 or 5 depending on available data).
+2. In your FIRST response, call the \`task\` tool once per task description.
    For each, set subagent_type and description EXACTLY as written in the
    user message. Copy the FULL multi-line description verbatim, including
    every file path listed.
-3. After all 4 subagents return, respond with: "All subagents complete."
+3. After all subagents return, respond with: "All subagents complete."
 
 ## CRITICAL rules
 
@@ -3536,6 +3762,22 @@ function buildAgentFileListSection(agentName, ctx) {
         ...files.styles.map((f) => ({ path: f, description: "(CSS source — check first)" }))
       ];
       break;
+    case "rendering-fcp":
+      dataFiles = [
+        {
+          path: "/trace/rendering/fcp-diagnostic.json",
+          description: "(FCP bottlenecks and correlation data — your PRIMARY data)"
+        },
+        {
+          path: "/trace/rendering/visual-progress.json",
+          description: "(visual change timeline, speed index, rendering phases)"
+        },
+        {
+          path: "/trace/rendering/filmstrip.json",
+          description: "(frame-by-frame rendering progress)"
+        }
+      ];
+      break;
   }
   const additionalSections = [];
   if (agentName === "code-pattern") {
@@ -3553,6 +3795,14 @@ function buildAgentFileListSection(agentName, ctx) {
         files: allSource
       });
     }
+  } else if (agentName === "rendering-fcp") {
+    const allSource = [...files.scripts, ...files.styles, ...files.html];
+    if (allSource.length > 0) {
+      additionalSections.push({
+        title: "Available source files — read ONLY the ones implicated in FCP bottlenecks or visual delays",
+        files: allSource
+      });
+    }
   }
   return buildFileListPromptSection({
     dataFiles,
@@ -3566,13 +3816,28 @@ function buildBrowserUserMessage(ctx) {
   const renderBlocking = traceResult.networkRequests.filter((r) => r.isRenderBlocking).length;
   const totalTransfer = traceResult.networkRequests.reduce((s, r) => s + r.encodedSize, 0);
   const hasRuntime = !!traceResult.runtimeTrace;
+  const hasRendering = !!traceResult.renderingDiagnostic;
   let runtimeInfo = "";
   if (hasRuntime) {
     const rt = traceResult.runtimeTrace;
     runtimeInfo = `
 Runtime trace: ${rt.blockingFunctions.length} blocking functions, ${rt.gcEvents.length} GC events (${Math.round(rt.gcEvents.reduce((s, e) => s + e.duration, 0))}ms total)`;
   }
-  return `Dispatch all 4 subagent tasks NOW in a single response.
+  let renderingInfo = "";
+  if (hasRendering) {
+    const rd = traceResult.renderingDiagnostic;
+    renderingInfo = `
+Rendering: Speed Index ${rd.speedIndex}ms, ${rd.fcpBottlenecks.length} FCP bottlenecks, ${rd.visualChanges.length} visual changes detected`;
+  }
+  const taskCount = hasRendering ? 5 : 4;
+  let renderingTask = "";
+  if (hasRendering) {
+    renderingTask = `
+
+TASK 5 — subagent_type: "rendering-fcp"
+description: "Analyze rendering speed and FCP behavior. Read /trace/rendering/fcp-diagnostic.json, /trace/rendering/visual-progress.json, and /trace/rendering/filmstrip.json FIRST. Identify FCP bottlenecks (render-blocking resources, long tasks before FCP, sequential resource chains, excessive layout). Cross-reference with network waterfall and source files. For each bottleneck, verify root cause and estimate delay. Report each bottleneck and rendering improvement as a separate finding. Do NOT suggest code fixes for minified/compiled JS."`;
+  }
+  return `Dispatch all ${taskCount} subagent tasks NOW in a single response.
 Use these EXACT descriptions (copy them verbatim):
 
 TASK 1 — subagent_type: "memory-heap"
@@ -3585,14 +3850,15 @@ TASK 3 — subagent_type: "runtime-blocking"
 description: "Find runtime issues: main-thread blocking functions, event listener imbalances, GC pressure, layout thrashing, and unthrottled event handlers. Read /trace/runtime/ data files FIRST (do NOT read source files yet). Analyze blocking-functions.json for functions >50ms, event-listeners.json for add/remove imbalances. Then read ONLY the source files at the reported locations. Check for compound blockers (A calls blocking B — report BOTH). Report each distinct issue as a separate finding. Do NOT suggest code fixes for minified/compiled JS."
 
 TASK 4 — subagent_type: "code-pattern"
-description: "Find frontend code anti-patterns: inline scripts, DOM manipulation in loops, missing event delegation, synchronous XHR, non-passive listeners, CSS issues, and missing image dimensions. Read HTML and CSS files FIRST. Check for inline <script> blocks, <img> without width/height, CSS @import. Then read ONLY the script files referenced by issues found. Report each pattern as a separate finding. Do NOT suggest code fixes for minified/compiled JS."
+description: "Find frontend code anti-patterns: inline scripts, DOM manipulation in loops, missing event delegation, synchronous XHR, non-passive listeners, CSS issues, and missing image dimensions. Read HTML and CSS files FIRST. Check for inline <script> blocks, <img> without width/height, CSS @import. Then read ONLY the script files referenced by issues found. Report each pattern as a separate finding. Do NOT suggest code fixes for minified/compiled JS."${renderingTask}
 
 URL: ${url}
 Page load: ${Math.round(m.loadComplete)}ms | FCP: ${Math.round(m.firstContentfulPaint)}ms | LCP: ${Math.round(m.largestContentfulPaint)}ms | TBT: ${Math.round(m.totalBlockingTime)}ms
 Heap: ${formatBytes(heapSummary.metadata.totalSize)} total, ${heapSummary.metadata.nodeCount.toLocaleString()} nodes, ${heapSummary.detachedNodes.count} detached DOM nodes
-Network: ${reqCount} requests, ${formatBytes(totalTransfer)} transferred, ${renderBlocking} render-blocking${runtimeInfo}`;
+Network: ${reqCount} requests, ${formatBytes(totalTransfer)} transferred, ${renderBlocking} render-blocking${runtimeInfo}${renderingInfo}`;
 }
 function buildSubagents(ctx) {
+  const hasRendering = !!ctx?.traceResult?.renderingDiagnostic;
   const agentDefs = [
     {
       name: "memory-heap",
@@ -3613,7 +3879,14 @@ function buildSubagents(ctx) {
       name: "code-pattern",
       description: "Detects frontend code anti-patterns: inline scripts, DOM manipulation in loops, missing event delegation, non-passive listeners.",
       prompt: CODE_PATTERN_PROMPT2
-    }
+    },
+    ...hasRendering ? [
+      {
+        name: "rendering-fcp",
+        description: "Analyzes rendering speed and FCP behavior: identifies bottlenecks delaying first contentful paint, analyzes visual rendering order, and suggests rendering optimizations.",
+        prompt: RENDERING_FCP_PROMPT
+      }
+    ] : []
   ];
   return agentDefs.map(({ name, description, prompt }) => {
     const fileSection = ctx ? buildAgentFileListSection(name, ctx) : "";
@@ -3912,6 +4185,363 @@ function emptyRuntimeTrace() {
   };
 }
 
+// src/browser/screencast.ts
+var VISUAL_CHANGE_THRESHOLD = 0.1;
+var MAX_FRAMES = 200;
+async function startScreencast(cdpSession, navigationStartTs) {
+  const frames = [];
+  cdpSession.on("Page.screencastFrame", (params) => {
+    if (frames.length >= MAX_FRAMES)
+      return;
+    const dataLength = Math.ceil((params.data?.length ?? 0) * 0.75);
+    frames.push({
+      timestamp: params.metadata?.timestamp ? params.metadata.timestamp * 1000 - navigationStartTs : Date.now() - navigationStartTs,
+      data: params.data ?? "",
+      sessionId: params.sessionId ?? 0,
+      dataLength
+    });
+    try {
+      cdpSession.send("Page.screencastFrameAck", {
+        sessionId: params.sessionId
+      });
+    } catch {}
+  });
+  try {
+    await cdpSession.send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 40,
+      maxWidth: 800,
+      maxHeight: 600,
+      everyNthFrame: 1
+    });
+  } catch {
+    return { stop: async () => [] };
+  }
+  return {
+    async stop() {
+      try {
+        await cdpSession.send("Page.stopScreencast");
+      } catch {}
+      return frames;
+    }
+  };
+}
+function detectVisualChanges(frames) {
+  if (frames.length === 0)
+    return [];
+  const changes = [];
+  const finalSize = frames[frames.length - 1].dataLength;
+  if (finalSize === 0)
+    return [];
+  let prevSize = 0;
+  for (let i = 0;i < frames.length; i++) {
+    const frame = frames[i];
+    const sizeDiff = Math.abs(frame.dataLength - prevSize);
+    const relativeChange = prevSize > 0 ? sizeDiff / prevSize : frame.dataLength > 0 ? 1 : 0;
+    if (relativeChange >= VISUAL_CHANGE_THRESHOLD || i === 0 && frame.dataLength > 0) {
+      changes.push({
+        timestamp: frame.timestamp,
+        frameIndex: i,
+        visualCompleteness: Math.min(100, Math.round(frame.dataLength / finalSize * 100)),
+        changeMagnitude: Math.min(1, relativeChange)
+      });
+    }
+    prevSize = frame.dataLength;
+  }
+  return changes;
+}
+function buildFilmstrip(frames, visualChanges) {
+  const changeIndices = new Set(visualChanges.map((vc) => vc.frameIndex));
+  return frames.map((frame, i) => ({
+    index: i,
+    timestamp: Math.round(frame.timestamp),
+    dataLength: frame.dataLength,
+    isVisualChange: changeIndices.has(i)
+  }));
+}
+function approximateSpeedIndex(visualChanges) {
+  if (visualChanges.length === 0)
+    return 0;
+  const sorted = [...visualChanges].sort((a, b) => a.timestamp - b.timestamp);
+  const lastChange = sorted[sorted.length - 1];
+  const totalTime = lastChange.timestamp;
+  if (totalTime <= 0)
+    return 0;
+  let speedIndex = 0;
+  let prevTimestamp = 0;
+  let prevCompleteness = 0;
+  for (const change of sorted) {
+    const duration = change.timestamp - prevTimestamp;
+    speedIndex += duration * (1 - prevCompleteness / 100);
+    prevTimestamp = change.timestamp;
+    prevCompleteness = change.visualCompleteness;
+  }
+  if (prevCompleteness < 100) {
+    speedIndex += (totalTime - prevTimestamp) * (1 - prevCompleteness / 100);
+  }
+  return Math.round(speedIndex);
+}
+
+// src/browser/fcp-analysis.ts
+function buildRenderingDiagnostic(traceResult, frames) {
+  const { metrics, runtimeTrace, rawTraceEvents } = traceResult;
+  const fcpTs = metrics.firstContentfulPaint;
+  const visualChanges = detectVisualChanges(frames);
+  const filmstrip = buildFilmstrip(frames, visualChanges);
+  const speedIndex = approximateSpeedIndex(visualChanges);
+  const fcpCorrelation = buildFCPCorrelation(traceResult, frames, fcpTs);
+  const renderingPhases = buildRenderingPhases(metrics, rawTraceEvents ?? [], runtimeTrace?.mainThreadId ?? 0);
+  const fcpBottlenecks = identifyFCPBottlenecks(fcpCorrelation, traceResult);
+  return {
+    filmstrip,
+    visualChanges,
+    fcpCorrelation,
+    renderingPhases,
+    speedIndex,
+    fcpBottlenecks
+  };
+}
+function buildFCPCorrelation(traceResult, frames, fcpTs) {
+  const { networkRequests, runtimeTrace } = traceResult;
+  let nearestFrameIndex = 0;
+  let minDelta = Infinity;
+  for (let i = 0;i < frames.length; i++) {
+    const delta = Math.abs(frames[i].timestamp - fcpTs);
+    if (delta < minDelta) {
+      minDelta = delta;
+      nearestFrameIndex = i;
+    }
+  }
+  const resourcesLoadedBeforeFCP = networkRequests.filter((r) => r.endTime > 0 && r.endTime <= fcpTs).sort((a, b) => a.endTime - b.endTime).map((r) => ({
+    url: r.url,
+    resourceType: r.resourceType,
+    duration: Math.round(r.duration),
+    isRenderBlocking: r.isRenderBlocking,
+    endTime: Math.round(r.endTime)
+  }));
+  const resourcesLoadingAtFCP = networkRequests.filter((r) => r.startTime <= fcpTs && (r.endTime === 0 || r.endTime > fcpTs)).map((r) => ({
+    url: r.url,
+    resourceType: r.resourceType,
+    startTime: Math.round(r.startTime)
+  }));
+  const renderBlockingChain = networkRequests.filter((r) => r.isRenderBlocking && r.endTime > 0 && r.endTime <= fcpTs).sort((a, b) => a.startTime - b.startTime).map((r) => ({
+    url: r.url,
+    resourceType: r.resourceType,
+    duration: Math.round(r.duration),
+    size: r.decodedSize
+  }));
+  const mainThreadBlockersBeforeFCP = (runtimeTrace?.blockingFunctions ?? []).filter((bf) => bf.startTime + bf.duration <= fcpTs).map((bf) => ({
+    functionName: bf.functionName,
+    scriptUrl: bf.scriptUrl,
+    duration: Math.round(bf.duration),
+    startTime: Math.round(bf.startTime)
+  }));
+  const totalBlockingTimeBeforeFCP = mainThreadBlockersBeforeFCP.reduce((sum, bf) => sum + Math.max(0, bf.duration - 50), 0);
+  const layoutTimeBeforeFCP = computeLayoutTimeBeforeFCP(traceResult, fcpTs);
+  return {
+    fcpTimestamp: Math.round(fcpTs),
+    nearestFrameIndex,
+    resourcesLoadedBeforeFCP,
+    resourcesLoadingAtFCP,
+    renderBlockingChain,
+    mainThreadBlockersBeforeFCP,
+    totalBlockingTimeBeforeFCP: Math.round(totalBlockingTimeBeforeFCP),
+    layoutTimeBeforeFCP: Math.round(layoutTimeBeforeFCP)
+  };
+}
+function computeLayoutTimeBeforeFCP(traceResult, fcpTs) {
+  const { rawTraceEvents, runtimeTrace } = traceResult;
+  if (!rawTraceEvents || rawTraceEvents.length === 0)
+    return 0;
+  const mainTid = runtimeTrace?.mainThreadId ?? 0;
+  const navEvent = rawTraceEvents.find((e) => e.name === "navigationStart" || e.name === "NavigationStart");
+  const navTs = navEvent?.ts ?? rawTraceEvents[0]?.ts ?? 0;
+  const fcpUs = fcpTs * 1000 + navTs;
+  const layoutEvents = new Set(["Layout", "UpdateLayoutTree", "RecalculateStyles"]);
+  let layoutTime = 0;
+  for (const e of rawTraceEvents) {
+    if (e.tid !== mainTid || e.ph !== "X" || !e.dur)
+      continue;
+    if (!layoutEvents.has(e.name))
+      continue;
+    if (e.ts + e.dur <= fcpUs) {
+      layoutTime += e.dur / 1000;
+    }
+  }
+  return layoutTime;
+}
+function buildRenderingPhases(metrics, rawTraceEvents, mainThreadId) {
+  const phases = [];
+  const fp = metrics.firstPaint;
+  const fcp = metrics.firstContentfulPaint;
+  const dcl = metrics.domContentLoaded;
+  const load = metrics.loadComplete;
+  if (fp > 0) {
+    phases.push({
+      name: "Server & Network",
+      startTime: 0,
+      endTime: Math.round(fp),
+      duration: Math.round(fp),
+      description: "Time from navigation start to first paint — includes DNS, TCP, TLS, server response, and HTML parsing."
+    });
+  }
+  if (fcp > fp && fp > 0) {
+    phases.push({
+      name: "First Paint to FCP",
+      startTime: Math.round(fp),
+      endTime: Math.round(fcp),
+      duration: Math.round(fcp - fp),
+      description: "Time between first paint (background/border) and first contentful paint (text/image). Render-blocking resources and large DOM delay this phase."
+    });
+  } else if (fcp > 0) {
+    phases.push({
+      name: "Navigation to FCP",
+      startTime: 0,
+      endTime: Math.round(fcp),
+      duration: Math.round(fcp),
+      description: "Time from navigation start to first contentful paint. Includes all network, parsing, and rendering work."
+    });
+  }
+  if (dcl > fcp && fcp > 0) {
+    phases.push({
+      name: "FCP to DOMContentLoaded",
+      startTime: Math.round(fcp),
+      endTime: Math.round(dcl),
+      duration: Math.round(dcl - fcp),
+      description: "Time between FCP and DOMContentLoaded. Deferred scripts execute during this phase."
+    });
+  }
+  if (load > dcl && dcl > 0) {
+    phases.push({
+      name: "DOMContentLoaded to Load",
+      startTime: Math.round(dcl),
+      endTime: Math.round(load),
+      duration: Math.round(load - dcl),
+      description: "Time between DOMContentLoaded and load event. Images, fonts, and async resources finish loading."
+    });
+  }
+  if (rawTraceEvents.length > 0) {
+    annotatePhaseActivity(phases, rawTraceEvents, mainThreadId);
+  }
+  return phases;
+}
+function annotatePhaseActivity(phases, rawTraceEvents, mainThreadId) {
+  const navEvent = rawTraceEvents.find((e) => e.name === "navigationStart" || e.name === "NavigationStart");
+  const navTs = navEvent?.ts ?? rawTraceEvents[0]?.ts ?? 0;
+  const scriptingEvents = new Set([
+    "FunctionCall",
+    "EvaluateScript",
+    "TimerFire",
+    "RequestAnimationFrame"
+  ]);
+  const layoutEvts = new Set(["Layout", "UpdateLayoutTree", "RecalculateStyles"]);
+  for (const phase of phases) {
+    const startUs = phase.startTime * 1000 + navTs;
+    const endUs = phase.endTime * 1000 + navTs;
+    let scripting = 0;
+    let layout = 0;
+    let painting = 0;
+    for (const e of rawTraceEvents) {
+      if (e.tid !== mainThreadId || e.ph !== "X" || !e.dur)
+        continue;
+      if (e.ts >= endUs || e.ts + e.dur <= startUs)
+        continue;
+      const overlapStart = Math.max(e.ts, startUs);
+      const overlapEnd = Math.min(e.ts + e.dur, endUs);
+      const overlapMs = (overlapEnd - overlapStart) / 1000;
+      if (scriptingEvents.has(e.name))
+        scripting += overlapMs;
+      else if (layoutEvts.has(e.name))
+        layout += overlapMs;
+      else if (e.name === "Paint" || e.name === "CompositeLayers")
+        painting += overlapMs;
+    }
+    if (scripting > 0 || layout > 0 || painting > 0) {
+      const parts = [];
+      if (scripting > 0)
+        parts.push(`${Math.round(scripting)}ms scripting`);
+      if (layout > 0)
+        parts.push(`${Math.round(layout)}ms layout`);
+      if (painting > 0)
+        parts.push(`${Math.round(painting)}ms painting`);
+      phase.description += ` Main-thread breakdown: ${parts.join(", ")}.`;
+    }
+  }
+}
+function identifyFCPBottlenecks(correlation, traceResult) {
+  const bottlenecks = [];
+  for (const rb of correlation.renderBlockingChain) {
+    bottlenecks.push({
+      type: "render-blocking-resource",
+      description: `Render-blocking ${rb.resourceType.toLowerCase()} (${formatSize(rb.size)}) delayed FCP by ~${rb.duration}ms. Consider async/defer loading or inlining critical content.`,
+      estimatedDelayMs: rb.duration,
+      source: rb.url
+    });
+  }
+  for (const bf of correlation.mainThreadBlockersBeforeFCP) {
+    if (bf.duration >= 50) {
+      bottlenecks.push({
+        type: "long-task-before-fcp",
+        description: `Long task "${bf.functionName}" blocked the main thread for ${bf.duration}ms before FCP. This prevents the browser from rendering content.`,
+        estimatedDelayMs: bf.duration - 50,
+        source: bf.scriptUrl || bf.functionName
+      });
+    }
+  }
+  const docRequest = traceResult.networkRequests.find((r) => r.resourceType === "Document");
+  if (docRequest && docRequest.duration > 600) {
+    bottlenecks.push({
+      type: "slow-server-response",
+      description: `Server took ${Math.round(docRequest.duration)}ms to respond with the HTML document. Consider server-side caching, CDN, or SSR optimization.`,
+      estimatedDelayMs: Math.round(docRequest.duration - 200),
+      source: docRequest.url
+    });
+  }
+  const renderBlockingRequests = traceResult.networkRequests.filter((r) => r.isRenderBlocking).sort((a, b) => a.startTime - b.startTime);
+  for (let i = 1;i < renderBlockingRequests.length; i++) {
+    const prev = renderBlockingRequests[i - 1];
+    const curr = renderBlockingRequests[i];
+    const gap = curr.startTime - prev.endTime;
+    if (gap < 50 && prev.endTime > 0 && curr.startTime > prev.endTime - 10) {
+      const chainDelay = curr.endTime - prev.startTime;
+      const parallelTime = Math.max(prev.duration, curr.duration);
+      const savings = chainDelay - parallelTime;
+      if (savings > 50) {
+        bottlenecks.push({
+          type: "sequential-resource-chain",
+          description: `Sequential render-blocking chain: "${basename(prev.url)}" → "${basename(curr.url)}" adds ~${Math.round(savings)}ms. Preloading or parallelizing would reduce FCP.`,
+          estimatedDelayMs: Math.round(savings),
+          source: curr.url
+        });
+      }
+    }
+  }
+  if (correlation.layoutTimeBeforeFCP > 100) {
+    bottlenecks.push({
+      type: "excessive-layout",
+      description: `${Math.round(correlation.layoutTimeBeforeFCP)}ms spent in layout/style recalculation before FCP. Reduce CSS complexity or DOM size for the initial render.`,
+      estimatedDelayMs: Math.round(correlation.layoutTimeBeforeFCP * 0.5),
+      source: "layout/style-recalculation"
+    });
+  }
+  bottlenecks.sort((a, b) => b.estimatedDelayMs - a.estimatedDelayMs);
+  return bottlenecks;
+}
+function formatSize(bytes) {
+  if (bytes < 1024)
+    return `${bytes}B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function basename(url) {
+  try {
+    return new URL(url).pathname.split("/").pop() || url;
+  } catch {
+    return url;
+  }
+}
+
 // src/browser/trace.ts
 var TEXT_RESOURCE_TYPES = new Set(["Script", "Stylesheet", "Document", "XHR", "Fetch"]);
 var MAX_BODY_SIZE = 2 * 1024 * 1024;
@@ -3927,6 +4557,7 @@ var TRACING_COMPLETE_TIMEOUT = 1e4;
 async function tracePageLoad(cdpSession, _options = {}) {
   const requests = new Map;
   const finishedIds = new Set;
+  const enableScreencast = _options.screencast !== false;
   const traceEvents = [];
   let tracingStarted = false;
   try {
@@ -3944,6 +4575,13 @@ async function tracePageLoad(cdpSession, _options = {}) {
     });
     tracingStarted = true;
   } catch {}
+  let screencastHandle;
+  const navigationStartMs = Date.now();
+  if (enableScreencast) {
+    try {
+      screencastHandle = await startScreencast(cdpSession, navigationStartMs);
+    } catch {}
+  }
   await cdpSession.send("Network.enable");
   cdpSession.on("Network.requestWillBeSent", (params) => {
     requests.set(params.requestId, {
@@ -4069,6 +4707,12 @@ async function tracePageLoad(cdpSession, _options = {}) {
       } catch {}
       const fp = paintEntries.find((e) => e.name === "first-paint");
       const fcp = paintEntries.find((e) => e.name === "first-contentful-paint");
+      let screencastFrames = [];
+      if (screencastHandle) {
+        try {
+          screencastFrames = await screencastHandle.stop();
+        } catch {}
+      }
       await cdpSession.send("Network.disable");
       const metrics = {
         navigationStart: perfMetrics.navigationStart ?? 0,
@@ -4080,12 +4724,19 @@ async function tracePageLoad(cdpSession, _options = {}) {
         totalBlockingTime: longTasks.reduce((sum, t) => sum + Math.max(0, t.duration - 50), 0),
         longTasks
       };
-      return {
+      const traceResult = {
         networkRequests,
         metrics,
         runtimeTrace,
         rawTraceEvents: tracingStarted ? traceEvents : undefined
       };
+      if (screencastFrames.length > 0) {
+        try {
+          traceResult.renderingDiagnostic = buildRenderingDiagnostic(traceResult, screencastFrames);
+        } catch {}
+        traceResult.screencastFrames = screencastFrames;
+      }
+      return traceResult;
     }
   };
 }
@@ -4463,6 +5114,27 @@ async function createWorkspace(options) {
     files["/trace/runtime/event-listeners.json"] = JSON.stringify(rt.eventListeners.filter((l) => l.addCount > 0), null, 2);
     files["/trace/runtime/frame-breakdown.json"] = JSON.stringify(rt.frameBreakdown, null, 2);
   }
+  if (traceResult.renderingDiagnostic) {
+    const rd = traceResult.renderingDiagnostic;
+    files["/trace/rendering/fcp-diagnostic.json"] = JSON.stringify({
+      fcpTimestamp: rd.fcpCorrelation.fcpTimestamp,
+      speedIndex: rd.speedIndex,
+      bottleneckCount: rd.fcpBottlenecks.length,
+      totalEstimatedDelay: rd.fcpBottlenecks.reduce((s, b) => s + b.estimatedDelayMs, 0),
+      fcpCorrelation: rd.fcpCorrelation,
+      fcpBottlenecks: rd.fcpBottlenecks
+    }, null, 2);
+    files["/trace/rendering/filmstrip.json"] = JSON.stringify({
+      frameCount: rd.filmstrip.length,
+      visualChangeCount: rd.visualChanges.length,
+      frames: rd.filmstrip
+    }, null, 2);
+    files["/trace/rendering/visual-progress.json"] = JSON.stringify({
+      speedIndex: rd.speedIndex,
+      visualChanges: rd.visualChanges,
+      renderingPhases: rd.renderingPhases
+    }, null, 2);
+  }
   if (traceResult.rawTraceEvents && traceResult.rawTraceEvents.length > 0) {
     const rawJson = JSON.stringify(traceResult.rawTraceEvents);
     if (rawJson.length < 5 * 1024 * 1024) {
@@ -4616,10 +5288,12 @@ async function main() {
       const longTaskCount = captureResult.trace.metrics.longTasks.length;
       const runtimeTraceInfo = captureResult.trace.runtimeTrace ? `
    Runtime trace: ${captureResult.trace.runtimeTrace.totalEvents.toLocaleString()} events captured` : "";
+      const renderingInfo = captureResult.trace.renderingDiagnostic ? `
+   Rendering: FCP ${Math.round(captureResult.trace.metrics.firstContentfulPaint)}ms, Speed Index ${captureResult.trace.renderingDiagnostic.speedIndex}ms, ${captureResult.trace.renderingDiagnostic.fcpBottlenecks.length} bottlenecks, ${captureResult.trace.renderingDiagnostic.filmstrip.length} frames` : "";
       captureSpinner.succeed(`Page loaded in ${(captureResult.trace.metrics.loadComplete / 1000).toFixed(1)}s
 ` + `   Heap snapshot: ${heapSizeMB} MB
 ` + `   Network requests: ${reqCount} captured
-` + `   Long tasks: ${longTaskCount} detected` + runtimeTraceInfo);
+` + `   Long tasks: ${longTaskCount} detected` + runtimeTraceInfo + renderingInfo);
     } catch (err) {
       captureSpinner.fail("Failed to capture page data");
       throw new Error(`Failed to capture data from ${url}.
@@ -4641,7 +5315,9 @@ async function main() {
       const totalSize = captureResult.trace.networkRequests.filter((r) => r.responseBody).reduce((sum, r) => sum + (r.responseBody?.length ?? 0), 0);
       const runtimeWorkspaceInfo = captureResult.trace.runtimeTrace ? `
    Runtime trace: summaries + raw events` : "";
-      workspaceSpinner.succeed(`${storedCount} assets stored in workspace (${formatBytes(totalSize)} total)` + runtimeWorkspaceInfo);
+      const renderingWorkspaceInfo = captureResult.trace.renderingDiagnostic ? `
+   Rendering diagnostics: FCP correlation + visual progress + filmstrip` : "";
+      workspaceSpinner.succeed(`${storedCount} assets stored in workspace (${formatBytes(totalSize)} total)` + runtimeWorkspaceInfo + renderingWorkspaceInfo);
     } catch (err) {
       workspaceSpinner.fail("Failed to build workspace");
       throw new Error(`Failed to create workspace.
@@ -4683,7 +5359,12 @@ async function main() {
           heapNodeCount: heapSummary.metadata.nodeCount,
           detachedDomNodes: heapSummary.detachedNodes.count,
           networkRequests: captureResult.trace.networkRequests.length,
-          totalTransferSize: captureResult.trace.networkRequests.reduce((s, r) => s + r.encodedSize, 0)
+          totalTransferSize: captureResult.trace.networkRequests.reduce((s, r) => s + r.encodedSize, 0),
+          ...captureResult.trace.renderingDiagnostic ? {
+            speedIndex: captureResult.trace.renderingDiagnostic.speedIndex,
+            fcpBottlenecks: captureResult.trace.renderingDiagnostic.fcpBottlenecks.length,
+            renderingPhases: captureResult.trace.renderingDiagnostic.renderingPhases.length
+          } : {}
         }
       };
       const { writeFileSync: writeFileSync2 } = await import("node:fs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitzeuge",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A deepagent to witnessing slowdowns in your test runs.",
   "keywords": [
     "analysis",