perfgraph 0.1.0

package/dist/normalize/clock.js

@@ -0,0 +1,96 @@
+/**
+ * Clock domain normalization utilities.
+ *
+ * Raw data from different CDP domains arrives on different clock domains.
+ * This module converts all timestamps to a common epoch: milliseconds
+ * relative to the navigation start (navigationStart).
+ *
+ * Supported clock domains:
+ *   - cdp-monotonic-us  : Chromium Tracing microsecond monotonic clock
+ *   - cdp-monotonic-ms  : CDP millisecond monotonic clock
+ *   - epoch-ms          : Standard Unix epoch in milliseconds
+ *   - epoch-s           : Standard Unix epoch in seconds
+ *   - network-monotonic-s : Network domain monotonic seconds (with wall-time offset)
+ *   - lighthouse-ms     : Lighthouse-reported relative milliseconds
+ */
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+/**
+ * Convert a raw timestamp to milliseconds relative to navigationStart.
+ *
+ * NaN / Infinity guard: if the result is not a finite number, return 0.
+ */
+export function toRelativeMs(raw, domain, anchor) {
+    let result;
+    switch (domain) {
+        case 'cdp-monotonic-us':
+            // Chrome tracing timestamps are in microseconds from boot
+            result = raw / 1000 - anchor.navigationStart;
+            break;
+        case 'cdp-monotonic-ms':
+            // Some CDP APIs return ms-monotonic
+            result = raw - anchor.navigationStart;
+            break;
+        case 'epoch-ms':
+            // Standard epoch milliseconds
+            result = raw - anchor.navigationStart;
+            break;
+        case 'epoch-s':
+            // Epoch seconds → multiply to ms, then shift
+            result = raw * 1000 - anchor.navigationStart;
+            break;
+        case 'network-monotonic-s': {
+            // Network events use a monotonic seconds clock anchored to a wall time.
+            // The wall-time offset is derived from the first request's wallTime.
+            const wallOffset = anchor.firstRequestWallTime ?? 0;
+            result =
+                raw * 1000 + (anchor.navigationStart - wallOffset * 1000);
+            break;
+        }
+        case 'lighthouse-ms':
+            // Lighthouse already reports relative ms
+            result = raw;
+            break;
+        default: {
+            // Exhaustiveness check (should never reach here if domain union is complete)
+            const _exhaustive = domain;
+            result = 0;
+            break;
+        }
+    }
+    // NaN / Infinity guard
+    if (!Number.isFinite(result)) {
+        return 0;
+    }
+    return result;
+}
+/**
+ * Resolve a ClockAnchor from a RawDataBundle.
+ *
+ * navigationStart is extracted from the performance metrics (Timestamp metric)
+ * or falls back to 0. firstRequestWallTime is taken from the first network
+ * request's wallTime field if available.
+ */
+export function resolveClockAnchor(raw) {
+    // Extract navigation start from performance metrics
+    let navigationStart = 0;
+    const perfData = raw.performance;
+    if (perfData?.metrics) {
+        const navStartMetric = perfData.metrics.find((m) => m.name === 'NavigationStart');
+        if (navStartMetric) {
+            navigationStart = navStartMetric.value;
+        }
+    }
+    // Extract first request wall time from network data
+    let firstRequestWallTime;
+    const netData = raw.network;
+    if (netData?.requests && netData.requests.length > 0) {
+        const firstReq = netData.requests[0];
+        if (firstReq && typeof firstReq.wallTime === 'number') {
+            firstRequestWallTime = firstReq.wallTime;
+        }
+    }
+    return { navigationStart, firstRequestWallTime };
+}
+//# sourceMappingURL=clock.js.map

package/dist/normalize/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/normalize/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyBH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,MAAmB,EACnB,MAAmB;IAEnB,IAAI,MAAc,CAAC;IAEnB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,kBAAkB;YACrB,0DAA0D;YAC1D,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC,eAAe,CAAC;YAC7C,MAAM;QAER,KAAK,kBAAkB;YACrB,oCAAoC;YACpC,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC;YACtC,MAAM;QAER,KAAK,UAAU;YACb,8BAA8B;YAC9B,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC;YACtC,MAAM;QAER,KAAK,SAAS;YACZ,6CAA6C;YAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC,eAAe,CAAC;YAC7C,MAAM;QAER,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,wEAAwE;YACxE,qEAAqE;YACrE,MAAM,UAAU,GAAG,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC;YACpD,MAAM;gBACJ,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,eAAe,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;YAC5D,MAAM;QACR,CAAC;QAED,KAAK,eAAe;YAClB,yCAAyC;YACzC,MAAM,GAAG,GAAG,CAAC;YACb,MAAM;QAER,OAAO,CAAC,CAAC,CAAC;YACR,6EAA6E;YAC7E,MAAM,WAAW,GAAU,MAAM,CAAC;YAClC,MAAM,GAAG,CAAC,CAAC;YACX,MAAM;QACR,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,oDAAoD;IACpD,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,MAAM,QAAQ,GAAG,GAAG,CAAC,WAER,CAAC;IACd,IAAI,QAAQ,EAAE,OAAO,EAAE,CAAC;QACtB,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAC1C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,CACpC,CAAC;QACF,IAAI,cAAc,EAAE,CAAC;YACnB,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC;QACzC,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,IAAI,oBAAwC,CAAC;IAE7C,MAAM,OAAO,GAAG,GAAG,CAAC,OAEP,CAAC;IACd,IAAI,OAAO,EAAE,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,QAAQ,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACtD,oBAAoB,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,CAAC;AACnD,CAAC"}

package/dist/normalize/dom-ir.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DOMIR builder from DOM raw data.
+ *
+ * Converts CDP DOM snapshot data into a normalized DOMIR structure with
+ * stats, tag distribution, and layout shift candidate analysis.
+ */
+import type { DOMIR } from './types.js';
+import type { DomRawData } from '../collect/types.js';
+/**
+ * Build a complete DOMIR from DOM raw data.
+ *
+ * @param dom - Raw DOM data from the DOMCollector
+ * @returns A fully-constructed DOMIR
+ */
+export declare function buildDOMIR(dom: DomRawData): DOMIR;
+//# sourceMappingURL=dom-ir.d.ts.map

package/dist/normalize/dom-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-ir.d.ts","sourceRoot":"","sources":["../../src/normalize/dom-ir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,KAAK,EAA6C,MAAM,YAAY,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,KAAK,CAsCjD"}

package/dist/normalize/dom-ir.js

@@ -0,0 +1,48 @@
+/**
+ * DOMIR builder from DOM raw data.
+ *
+ * Converts CDP DOM snapshot data into a normalized DOMIR structure with
+ * stats, tag distribution, and layout shift candidate analysis.
+ */
+import { DOMIRSchema } from './types.js';
+// ---------------------------------------------------------------------------
+// Main builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a complete DOMIR from DOM raw data.
+ *
+ * @param dom - Raw DOM data from the DOMCollector
+ * @returns A fully-constructed DOMIR
+ */
+export function buildDOMIR(dom) {
+    // 1. Stats: pass through totalNodes, elementCount, maxDepth
+    //    maxChildren is derived from elementDistribution values (max count)
+    const elementCounts = Object.values(dom.elementDistribution);
+    const maxChildren = elementCounts.length > 0
+        ? Math.max(...elementCounts)
+        : 0;
+    const stats = {
+        totalNodes: dom.stats.totalNodes,
+        elementCount: dom.stats.elementCount,
+        maxDepth: dom.stats.maxDepth,
+        maxChildren,
+    };
+    // 2. Tag distribution: convert Record<string, number> → TagCount[]
+    const tagDistribution = Object.entries(dom.elementDistribution).map(([tag, count]) => ({ tag, count }));
+    // 3. Layout shift candidates
+    const highComplexitySubtrees = maxChildren >= 50
+        ? elementCounts.filter((count) => count > maxChildren / 2).length
+        : 0;
+    const deepNesting = dom.stats.maxDepth >= 15 ? 1 : 0;
+    const layoutShiftCandidates = {
+        highComplexitySubtrees,
+        deepNesting,
+    };
+    const result = {
+        stats,
+        tagDistribution,
+        layoutShiftCandidates,
+    };
+    return result;
+}
+//# sourceMappingURL=dom-ir.js.map

package/dist/normalize/dom-ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-ir.js","sourceRoot":"","sources":["../../src/normalize/dom-ir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIzC,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,4DAA4D;IAC5D,wEAAwE;IACxE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC;QAC1C,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;QAC5B,CAAC,CAAC,CAAC,CAAC;IAEN,MAAM,KAAK,GAAa;QACtB,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU;QAChC,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY;QACpC,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;QAC5B,WAAW;KACZ,CAAC;IAEF,mEAAmE;IACnE,MAAM,eAAe,GAAe,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAC7E,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CACnC,CAAC;IAEF,6BAA6B;IAC7B,MAAM,sBAAsB,GAAG,WAAW,IAAI,EAAE;QAC9C,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,MAAM;QACjE,CAAC,CAAC,CAAC,CAAC;IACN,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,MAAM,qBAAqB,GAA0B;QACnD,sBAAsB;QACtB,WAAW;KACZ,CAAC;IAEF,MAAM,MAAM,GAAU;QACpB,KAAK;QACL,eAAe;QACf,qBAAqB;KACtB,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/normalize/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalize orchestrator.
+ *
+ * Entry point for the normalization pipeline. Takes a RawDataBundle from
+ * collection and returns a validated IRBundle with all timestamps in ms
+ * relative to navigationStart.
+ */
+import type { RawDataBundle } from '../collect/types.js';
+import type { IRBundle } from './types.js';
+/**
+ * Normalize raw collected data into a validated Intermediate Representation
+ * bundle.
+ *
+ * Builds all domain IRs (performance, network, runtime, DOM, lighthouse)
+ * from their respective raw data sources and assembles them into a
+ * validated IRBundle.
+ *
+ * @param raw - Raw data bundle from a single collection run
+ * @returns Validated IRBundle
+ * @throws {Error} If the assembled bundle fails Zod validation
+ */
+export declare function normalize(raw: RawDataBundle): IRBundle;
+//# sourceMappingURL=index.d.ts.map

package/dist/normalize/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/normalize/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAA8C,MAAM,qBAAqB,CAAC;AACrG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU3C;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,QAAQ,CA8GtD"}

package/dist/normalize/index.js

@@ -0,0 +1,118 @@
+/**
+ * Normalize orchestrator.
+ *
+ * Entry point for the normalization pipeline. Takes a RawDataBundle from
+ * collection and returns a validated IRBundle with all timestamps in ms
+ * relative to navigationStart.
+ */
+import { IRBundleSchema } from './types.js';
+import { resolveClockAnchor } from './clock.js';
+import { buildPerformanceIR } from './trace-ir.js';
+import { buildNetworkIR } from './network-ir.js';
+import { buildRuntimeIR } from './runtime-ir.js';
+import { buildDOMIR } from './dom-ir.js';
+import { buildLighthouseIR } from './lighthouse-ir.js';
+/**
+ * Normalize raw collected data into a validated Intermediate Representation
+ * bundle.
+ *
+ * Builds all domain IRs (performance, network, runtime, DOM, lighthouse)
+ * from their respective raw data sources and assembles them into a
+ * validated IRBundle.
+ *
+ * @param raw - Raw data bundle from a single collection run
+ * @returns Validated IRBundle
+ * @throws {Error} If the assembled bundle fails Zod validation
+ */
+export function normalize(raw) {
+    // 1. Resolve the clock anchor (navigationStart time)
+    const anchor = resolveClockAnchor(raw);
+    // 2. Build PerformanceIR from trace + performance data
+    const traceData = raw.trace;
+    const perfData = raw.performance;
+    const performance = (traceData && perfData)
+        ? buildPerformanceIR(raw.trace, raw.performance, anchor)
+        : {
+            navigation: {
+                url: '',
+                navigationStart: 0,
+                domContentLoaded: 0,
+                domContentLoadedEventEnd: 0,
+                loadEventStart: 0,
+                loadEventEnd: 0,
+                domInteractive: 0,
+            },
+            coreWebVitals: {},
+            traceSummary: {
+                totalDuration: 0,
+                eventCount: 0,
+                categories: {},
+                threadActivity: { totalMs: 0, byCategory: {} },
+            },
+            mainThreadBusyness: 0,
+        };
+    // 3. Build domain IRs
+    const network = raw.network
+        ? buildNetworkIR(raw.network, anchor)
+        : {
+            requests: [],
+            summary: {
+                totalRequests: 0,
+                totalBytes: 0,
+                byType: {},
+                byPriority: {},
+                criticalPath: { tree: { url: '' }, depth: 0, urlsOnLongestPath: [] },
+                longestChain: { url: '', length: 0 },
+            },
+        };
+    const runtimeRaw = raw.runtime;
+    const consoleRaw = raw.consoleEntries;
+    const runtime = runtimeRaw
+        ? buildRuntimeIR(runtimeRaw, consoleRaw ?? { entries: [], counts: { log: 0, warn: 0, error: 0, info: 0, debug: 0, other: 0 }, warnings: [] })
+        : { executionContexts: [] };
+    const domRaw = raw.dom;
+    const dom = domRaw
+        ? buildDOMIR(domRaw)
+        : {
+            stats: { totalNodes: 0, elementCount: 0, maxDepth: 0, maxChildren: 0 },
+            tagDistribution: [],
+            layoutShiftCandidates: { highComplexitySubtrees: 0, deepNesting: 0 },
+        };
+    const lighthouse = raw.lighthouse
+        ? buildLighthouseIR(raw.lighthouse)
+        : {
+            categories: {},
+            failedAudits: [],
+            scores: {},
+        };
+    // 4. Extract URL from the first network request (most reliable source)
+    const networkRaw = raw.network;
+    const firstRequestUrl = networkRaw?.requests?.[0]?.url
+        ?? network.requests[0]?.url
+        ?? performance.navigation.url
+        ?? '';
+    // 5. Assemble IRMeta
+    const perfMetrics = perfData?.metrics;
+    const navStartMetric = perfMetrics?.find((m) => m.name === 'NavigationStart');
+    const meta = {
+        url: firstRequestUrl,
+        fetchedAt: new Date().toISOString(),
+        navigationStart: navStartMetric?.value ?? 0,
+        irVersion: '1.0.0',
+    };
+    // 6. Build and validate IRBundle
+    const bundle = {
+        meta,
+        performance,
+        network,
+        runtime,
+        dom,
+        lighthouse,
+    };
+    const parseResult = IRBundleSchema.safeParse(bundle);
+    if (!parseResult.success) {
+        throw new Error(`Error: IR validation failed: ${parseResult.error.message}`);
+    }
+    return parseResult.data;
+}
+//# sourceMappingURL=index.js.map

package/dist/normalize/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/normalize/index.ts"],"names":[],"mappings":"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"}

package/dist/normalize/lighthouse-insights.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Lighthouse Insights builder from Lighthouse v13+ insight audits.
+ *
+ * Extracts structured data from 3 specific Lighthouse insight audits:
+ *   - lcp-breakdown-insight
+ *   - render-blocking-insight
+ *   - network-dependency-tree-insight
+ *
+ * Each insight audit is parsed independently so partial data does not
+ * prevent the rest from being extracted.
+ */
+import type { LighthouseInsights } from './types.js';
+/**
+ * Build a structured LighthouseInsights object from raw Lighthouse data.
+ *
+ * Accepts raw Lighthouse data in either form:
+ *   - `{ lhr: { audits: {...} } }` — from LighthouseRawData
+ *   - `{ audits: {...} }` — from a plain Lighthouse Report
+ *
+ * Each insight audit is parsed independently. Missing or invalid audits
+ * simply result in that field being omitted from the result.
+ *
+ * @param rawLighthouse - Raw Lighthouse data (unknown shape, validated at parse time)
+ * @returns A partially-populated LighthouseInsights object
+ */
+export declare function buildLighthouseInsights(rawLighthouse: unknown): LighthouseInsights;
+//# sourceMappingURL=lighthouse-insights.d.ts.map

package/dist/normalize/lighthouse-insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighthouse-insights.d.ts","sourceRoot":"","sources":["../../src/normalize/lighthouse-insights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,YAAY,CAAC;AA+RpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,OAAO,GACrB,kBAAkB,CA2CpB"}

package/dist/normalize/lighthouse-insights.js

@@ -0,0 +1,318 @@
+/**
+ * Lighthouse Insights builder from Lighthouse v13+ insight audits.
+ *
+ * Extracts structured data from 3 specific Lighthouse insight audits:
+ *   - lcp-breakdown-insight
+ *   - render-blocking-insight
+ *   - network-dependency-tree-insight
+ *
+ * Each insight audit is parsed independently so partial data does not
+ * prevent the rest from being extracted.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers for safe access
+// ---------------------------------------------------------------------------
+/** Assert value is a plain object (record-like). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Safely coerce a value to a string. */
+function safeString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Safely coerce a value to a number. */
+function safeNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+/** Safely coerce a value to an array, filtering out non-record entries. */
+function safeRecordArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isRecord);
+}
+// ---------------------------------------------------------------------------
+// Insight audit parsers
+// ---------------------------------------------------------------------------
+/**
+ * Parse the lcp-breakdown-insight audit.
+ *
+ * Lighthouse v13+ structures this as a list containing:
+ *   - a table item with subpart rows (timeToFirstByte, elementRenderDelay,
+ *     resourceLoadDelay, resourceLoadTime)
+ *   - a node item with LCP element metadata (selector, snippet, nodeLabel)
+ */
+function parseLCPBreakdown(audit) {
+    const details = audit.details;
+    if (!isRecord(details))
+        return undefined;
+    const items = safeRecordArray(details.items);
+    if (items.length === 0)
+        return undefined;
+    let timeToFirstByte = 0;
+    let resourceLoadDelay;
+    let resourceLoadTime;
+    let elementRenderDelay = 0;
+    let lcpElementSelector;
+    let lcpElementSnippet;
+    let lcpElementNodeLabel;
+    for (const item of items) {
+        const itemType = safeString(item.type);
+        if (itemType === 'table') {
+            // Extract subpart durations from the table items
+            const subItems = safeRecordArray(item.items);
+            for (const sub of subItems) {
+                const subpart = safeString(sub.subpart);
+                const duration = safeNumber(sub.duration) ?? 0;
+                switch (subpart) {
+                    case 'timeToFirstByte':
+                        timeToFirstByte = duration;
+                        break;
+                    case 'elementRenderDelay':
+                        elementRenderDelay = duration;
+                        break;
+                    case 'resourceLoadDelay':
+                        resourceLoadDelay = duration;
+                        break;
+                    case 'resourceLoadTime':
+                        resourceLoadTime = duration;
+                        break;
+                }
+            }
+        }
+        if (itemType === 'node') {
+            lcpElementSelector = safeString(item.selector);
+            lcpElementSnippet = safeString(item.snippet);
+            lcpElementNodeLabel = safeString(item.nodeLabel);
+        }
+    }
+    // Determine source
+    const scoreDisplayMode = safeString(audit.scoreDisplayMode);
+    let source = 'lighthouse';
+    if (scoreDisplayMode === 'informative') {
+        // Insight audits with trace data combined are 'mixed'
+        source = 'mixed';
+    }
+    return {
+        timeToFirstByte,
+        elementRenderDelay,
+        resourceLoadDelay: resourceLoadDelay !== undefined ? resourceLoadDelay : undefined,
+        resourceLoadTime: resourceLoadTime !== undefined ? resourceLoadTime : undefined,
+        lcpElementSelector,
+        lcpElementSnippet,
+        lcpElementNodeLabel,
+        source,
+    };
+}
+/**
+ * Parse the render-blocking-insight audit.
+ *
+ * Lighthouse v13+ structures this as:
+ *   - metricSavings: { FCP: number, LCP: number }
+ *   - details.items: array of render-blocking resources
+ */
+function parseRenderBlocking(audit) {
+    const details = audit.details;
+    if (!isRecord(details))
+        return undefined;
+    // Extract metric savings from the audit level
+    const metricSavings = isRecord(audit.metricSavings) ? audit.metricSavings : undefined;
+    const fcpSavingsMs = safeNumber(metricSavings?.['FCP']);
+    const lcpSavingsMs = safeNumber(metricSavings?.['LCP']);
+    // Extract resource list from details.items
+    const items = safeRecordArray(details.items);
+    const resources = [];
+    for (const item of items) {
+        const url = safeString(item.url);
+        if (!url)
+            continue;
+        resources.push({
+            url,
+            totalBytes: safeNumber(item.totalBytes),
+            wastedMs: safeNumber(item.wastedMs),
+            resourceType: safeString(item.resourceType),
+        });
+    }
+    return {
+        fcpSavingsMs: fcpSavingsMs,
+        lcpSavingsMs: lcpSavingsMs,
+        resources,
+    };
+}
+/**
+ * Recursively walk a network chain subtree to collect all leaf URLs
+ * along the longest path (by navStartToEndTime).
+ */
+function walkLongestChain(node, path) {
+    let bestDuration = node.navStartToEndTime;
+    let bestUrls = [...path, node.url];
+    if (node.children) {
+        for (const childKey of Object.keys(node.children)) {
+            const child = node.children[childKey];
+            const result = walkLongestChain(child, [...path, node.url]);
+            const totalDuration = node.navStartToEndTime + result.duration;
+            if (totalDuration > bestDuration) {
+                bestDuration = totalDuration;
+                bestUrls = result.urls;
+            }
+        }
+    }
+    return { duration: bestDuration, urls: bestUrls };
+}
+/**
+ * Convert a raw chain record (unknown-shape) into a proper NetworkChainNode
+ * by recursively walking and casting each entry.
+ */
+function parseChainNode(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const url = safeString(raw.url);
+    if (!url)
+        return undefined;
+    const node = {
+        url,
+        navStartToEndTime: safeNumber(raw.navStartToEndTime) ?? 0,
+        transferSize: safeNumber(raw.transferSize),
+        isLongest: raw.isLongest === true,
+    };
+    if (raw.children && isRecord(raw.children)) {
+        const children = {};
+        for (const [key, childRaw] of Object.entries(raw.children)) {
+            const child = parseChainNode(childRaw);
+            if (child) {
+                children[key] = child;
+            }
+        }
+        if (Object.keys(children).length > 0) {
+            node.children = children;
+        }
+    }
+    return node;
+}
+/**
+ * Parse the network-dependency-tree-insight audit.
+ *
+ * Lighthouse v13+ structures this as a list containing:
+ *   - a network-tree item with chains and longestChain metadata
+ *   - a list-section item with preconnect candidates
+ */
+function parseNetworkDependencyTree(audit) {
+    const details = audit.details;
+    if (!isRecord(details))
+        return undefined;
+    const items = safeRecordArray(details.items);
+    if (items.length === 0)
+        return undefined;
+    let chains;
+    let longestChainDuration;
+    const longestChainUrls = [];
+    const preconnectCandidates = [];
+    for (const item of items) {
+        const itemType = safeString(item.type);
+        if (itemType === 'network-tree') {
+            // Parse chains
+            const rawChains = isRecord(item.chains) ? item.chains : undefined;
+            if (rawChains) {
+                const parsed = {};
+                for (const [key, rawNode] of Object.entries(rawChains)) {
+                    const node = parseChainNode(rawNode);
+                    if (node) {
+                        parsed[key] = node;
+                    }
+                }
+                if (Object.keys(parsed).length > 0) {
+                    chains = parsed;
+                    // Walk the longest chain to get URLs
+                    for (const rootNode of Object.values(parsed)) {
+                        const result = walkLongestChain(rootNode, []);
+                        if (result.duration > (longestChainDuration ?? 0)) {
+                            longestChainDuration = result.duration;
+                        }
+                        longestChainUrls.push(...result.urls);
+                    }
+                }
+            }
+            // Extract longestChain duration from the item-level metadata
+            const longestChain = isRecord(item.longestChain) ? item.longestChain : undefined;
+            if (longestChain) {
+                const duration = safeNumber(longestChain.duration);
+                if (duration !== undefined) {
+                    longestChainDuration = duration;
+                }
+            }
+        }
+        if (itemType === 'list-section') {
+            const title = safeString(item.title);
+            if (title === 'Preconnect candidates' || title?.toLowerCase().includes('preconnect')) {
+                const preconnectItems = safeRecordArray(item.items);
+                for (const pi of preconnectItems) {
+                    const url = safeString(pi.url);
+                    if (url) {
+                        preconnectCandidates.push(url);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        chains,
+        longestChainDuration: longestChainDuration,
+        longestChainUrls: longestChainUrls.length > 0 ? longestChainUrls : undefined,
+        preconnectCandidates: preconnectCandidates.length > 0 ? preconnectCandidates : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a structured LighthouseInsights object from raw Lighthouse data.
+ *
+ * Accepts raw Lighthouse data in either form:
+ *   - `{ lhr: { audits: {...} } }` — from LighthouseRawData
+ *   - `{ audits: {...} }` — from a plain Lighthouse Report
+ *
+ * Each insight audit is parsed independently. Missing or invalid audits
+ * simply result in that field being omitted from the result.
+ *
+ * @param rawLighthouse - Raw Lighthouse data (unknown shape, validated at parse time)
+ * @returns A partially-populated LighthouseInsights object
+ */
+export function buildLighthouseInsights(rawLighthouse) {
+    if (!isRecord(rawLighthouse))
+        return {};
+    // Handle both { lhr: { audits } } and { audits } formats
+    const root = isRecord(rawLighthouse.lhr) ? rawLighthouse.lhr : rawLighthouse;
+    const audits = isRecord(root.audits) ? root.audits : {};
+    const insights = {};
+    // 1. Parse lcp-breakdown-insight
+    const lcpAudit = isRecord(audits['lcp-breakdown-insight'])
+        ? audits['lcp-breakdown-insight']
+        : undefined;
+    if (lcpAudit) {
+        const parsed = parseLCPBreakdown(lcpAudit);
+        if (parsed) {
+            insights.lcpBreakdown = parsed;
+        }
+    }
+    // 2. Parse render-blocking-insight
+    const rbAudit = isRecord(audits['render-blocking-insight'])
+        ? audits['render-blocking-insight']
+        : undefined;
+    if (rbAudit) {
+        const parsed = parseRenderBlocking(rbAudit);
+        if (parsed) {
+            insights.renderBlocking = parsed;
+        }
+    }
+    // 3. Parse network-dependency-tree-insight
+    const netAudit = isRecord(audits['network-dependency-tree-insight'])
+        ? audits['network-dependency-tree-insight']
+        : undefined;
+    if (netAudit) {
+        const parsed = parseNetworkDependencyTree(netAudit);
+        if (parsed) {
+            insights.networkDependencyTree = parsed;
+        }
+    }
+    return insights;
+}
+//# sourceMappingURL=lighthouse-insights.js.map