nuxt-devtools-observatory 0.1.30 → 0.1.32

package/client/src/composables/trace-render-aggregation.ts

@@ -0,0 +1,254 @@
+import type { TraceEntry, TraceSpan } from '@observatory/types/snapshot'
+
+interface SpanMetadata {
+    uid?: string | number
+    componentName?: string
+    file?: string
+    lifecycle?: string
+}
+
+export interface TraceRenderStatsRow {
+    componentKey: string
+    componentName: string
+    file: string
+    uid: string | number
+    mountCount: number
+    rerenderCount: number
+    totalMs: number
+    avgMs: number
+}
+
+export interface CrossTraceRenderSummaryRow {
+    componentKey: string
+    componentName: string
+    file: string
+    tracesSeen: number
+    avgRerendersPerTrace: number
+    totalRerenders: number
+    totalMs: number
+    avgMsPerRender: number
+    selectedUid?: string | number
+    selectedRerenders?: number
+    baselineRerenders?: number
+    deltaVsBaseline?: number
+}
+
+function asMetadata(span: TraceSpan): SpanMetadata {
+    return ((span.metadata as Record<string, unknown> | undefined) ?? {}) as SpanMetadata
+}
+
+function normalizeMs(value?: number): number {
+    return Number.isFinite(value) ? (value as number) : 0
+}
+
+function getComponentIdentity(metadata: SpanMetadata, fallbackId: string): { key: string; name: string; file: string } {
+    const name = String(metadata.componentName ?? '').trim()
+    const file = String(metadata.file ?? '').trim()
+
+    if (name && file) {
+        return {
+            key: `${file}::${name}`,
+            name,
+            file,
+        }
+    }
+
+    if (name) {
+        return {
+            key: `name::${name}`,
+            name,
+            file,
+        }
+    }
+
+    return {
+        key: `unknown::${fallbackId}`,
+        name: fallbackId,
+        file,
+    }
+}
+
+/** Build per-trace render stats grouped by component UID. */
+export function buildRenderSummaryForTrace(trace?: TraceEntry): TraceRenderStatsRow[] {
+    if (!trace) {
+        return []
+    }
+
+    const byUid = new Map<string | number, { key: string; name: string; file: string; spans: TraceSpan[] }>()
+
+    for (const span of trace.spans) {
+        if (span.type !== 'render') {
+            continue
+        }
+
+        const metadata = asMetadata(span)
+        const uid = (metadata.uid as string | number | undefined) ?? span.id
+        const identity = getComponentIdentity(metadata, String(uid))
+
+        if (!byUid.has(uid)) {
+            byUid.set(uid, {
+                key: identity.key,
+                name: identity.name,
+                file: identity.file,
+                spans: [],
+            })
+        }
+
+        byUid.get(uid)!.spans.push(span)
+    }
+
+    const rows: TraceRenderStatsRow[] = []
+
+    for (const [uid, { key, name, file, spans }] of byUid) {
+        let mountCount = 0
+        let rerenderCount = 0
+        let totalMs = 0
+
+        for (const span of spans) {
+            const lifecycle = String(asMetadata(span).lifecycle ?? '')
+            const ms = normalizeMs(span.durationMs)
+
+            if (lifecycle === 'render:mount') {
+                mountCount++
+            } else {
+                rerenderCount++
+            }
+
+            totalMs += ms
+        }
+
+        const totalRenders = mountCount + rerenderCount
+        rows.push({
+            componentKey: key,
+            componentName: name || String(uid),
+            file,
+            uid,
+            mountCount,
+            rerenderCount,
+            totalMs,
+            avgMs: totalRenders > 0 ? totalMs / totalRenders : 0,
+        })
+    }
+
+    rows.sort((a, b) => b.rerenderCount - a.rerenderCount || b.totalMs - a.totalMs)
+
+    return rows
+}
+
+/** Build cross-trace render aggregation and comparison against a selected trace. */
+export function buildCrossTraceRenderSummary(traces: TraceEntry[], selectedTraceId?: string): CrossTraceRenderSummaryRow[] {
+    if (traces.length === 0) {
+        return []
+    }
+
+    const aggregate = new Map<
+        string,
+        {
+            componentName: string
+            file: string
+            tracesSeen: number
+            totalRerenders: number
+            totalRenders: number
+            totalMs: number
+            selectedUid?: string | number
+            selectedRerenders?: number
+        }
+    >()
+
+    for (const trace of traces) {
+        const rows = buildRenderSummaryForTrace(trace)
+
+        // Collapse multiple UIDs for the same component identity within one trace.
+        const perTrace = new Map<
+            string,
+            { name: string; file: string; rerenders: number; renders: number; ms: number; uid: string | number; peakUidRerenders: number }
+        >()
+
+        for (const row of rows) {
+            const existing = perTrace.get(row.componentKey)
+
+            if (!existing) {
+                perTrace.set(row.componentKey, {
+                    name: row.componentName,
+                    file: row.file,
+                    rerenders: row.rerenderCount,
+                    renders: row.mountCount + row.rerenderCount,
+                    ms: row.totalMs,
+                    uid: row.uid,
+                    peakUidRerenders: row.rerenderCount,
+                })
+                continue
+            }
+
+            existing.rerenders += row.rerenderCount
+            existing.renders += row.mountCount + row.rerenderCount
+            existing.ms += row.totalMs
+
+            // Keep the UID with higher re-render count for potential highlight mapping.
+            if (row.rerenderCount > existing.peakUidRerenders) {
+                existing.uid = row.uid
+                existing.peakUidRerenders = row.rerenderCount
+            }
+        }
+
+        for (const [componentKey, value] of perTrace) {
+            if (!aggregate.has(componentKey)) {
+                aggregate.set(componentKey, {
+                    componentName: value.name,
+                    file: value.file,
+                    tracesSeen: 0,
+                    totalRerenders: 0,
+                    totalRenders: 0,
+                    totalMs: 0,
+                })
+            }
+
+            const target = aggregate.get(componentKey)!
+            target.tracesSeen += 1
+            target.totalRerenders += value.rerenders
+            target.totalRenders += value.renders
+            target.totalMs += value.ms
+
+            if (selectedTraceId && trace.id === selectedTraceId) {
+                target.selectedUid = value.uid
+                target.selectedRerenders = value.rerenders
+            }
+        }
+    }
+
+    const rows: CrossTraceRenderSummaryRow[] = []
+
+    for (const [componentKey, value] of aggregate) {
+        const avgRerendersPerTrace = value.tracesSeen > 0 ? value.totalRerenders / value.tracesSeen : 0
+        const avgMsPerRender = value.totalRenders > 0 ? value.totalMs / value.totalRenders : 0
+
+        let baselineRerenders: number | undefined
+        let deltaVsBaseline: number | undefined
+
+        if (value.selectedRerenders !== undefined && value.tracesSeen > 1) {
+            const others = value.tracesSeen - 1
+            const othersTotal = value.totalRerenders - value.selectedRerenders
+            baselineRerenders = others > 0 ? othersTotal / others : 0
+            deltaVsBaseline = value.selectedRerenders - baselineRerenders
+        }
+
+        rows.push({
+            componentKey,
+            componentName: value.componentName,
+            file: value.file,
+            tracesSeen: value.tracesSeen,
+            avgRerendersPerTrace,
+            totalRerenders: value.totalRerenders,
+            totalMs: value.totalMs,
+            avgMsPerRender,
+            selectedUid: value.selectedUid,
+            selectedRerenders: value.selectedRerenders,
+            baselineRerenders,
+            deltaVsBaseline,
+        })
+    }
+
+    rows.sort((a, b) => b.avgRerendersPerTrace - a.avgRerendersPerTrace || b.totalMs - a.totalMs)
+
+    return rows
+}

package/client/src/composables/useExportImport.ts

@@ -0,0 +1,63 @@
+export interface ObservatoryExportFile<T> {
+    type: 'observatory-traces' | 'observatory-renders'
+    version: '1'
+    exportedAt: number
+    count: number
+    data: T[]
+}
+
+export function exportJson(filename: string, envelope: ObservatoryExportFile<unknown>): void {
+    const json = JSON.stringify(envelope, null, 2)
+    const blob = new Blob([json], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const anchor = document.createElement('a')
+    anchor.href = url
+    anchor.download = filename
+    anchor.click()
+    URL.revokeObjectURL(url)
+}
+
+export function importJson(): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+        const input = document.createElement('input')
+        input.type = 'file'
+        input.accept = '.json,application/json'
+
+        input.addEventListener('change', () => {
+            const file = input.files?.[0]
+
+            if (!file) {
+                reject(new Error('No file selected'))
+                return
+            }
+
+            const reader = new FileReader()
+
+            reader.addEventListener('load', () => {
+                try {
+                    resolve(JSON.parse(reader.result as string))
+                } catch {
+                    reject(new Error('Invalid JSON file'))
+                }
+            })
+
+            reader.addEventListener('error', () => reject(new Error('Failed to read file')))
+            reader.readAsText(file)
+        })
+
+        // Reject if the dialog is cancelled (focus returns without a change event)
+        window.addEventListener(
+            'focus',
+            () => {
+                setTimeout(() => {
+                    if (!input.files?.length) {
+                        reject(new Error('cancelled'))
+                    }
+                }, 300)
+            },
+            { once: true }
+        )
+
+        input.click()
+    })
+}

package/client/src/composables/useTraceFilter.ts

@@ -0,0 +1,160 @@
+import { computed, ref } from 'vue'
+import type { TraceEntry } from '@observatory/types/snapshot'
+
+export function getSpanTypesFromTraces(traces: TraceEntry[]): string[] {
+    const types = new Set<string>()
+
+    for (const trace of traces) {
+        for (const span of trace.spans) {
+            types.add(span.type)
+        }
+    }
+
+    return Array.from(types).sort()
+}
+
+export function useTraceFilter() {
+    const searchQuery = ref<string>('')
+    const selectedSpanTypes = ref<Set<string>>(new Set())
+    const minDuration = ref<number>(0)
+    const maxDuration = ref<number>(Infinity)
+    const routeFilter = ref<string>('')
+
+    function matchesSearch(trace: TraceEntry, query: string): boolean {
+        if (!query) {
+            return true
+        }
+
+        const lowerQuery = query.toLowerCase()
+
+        // Search in trace name
+        if (trace.name.toLowerCase().includes(lowerQuery)) {
+            return true
+        }
+
+        // Search in span names
+        for (const span of trace.spans) {
+            if (span.name.toLowerCase().includes(lowerQuery)) {
+                return true
+            }
+        }
+
+        // Search in metadata (e.g., route, URL endpoint)
+        for (const span of trace.spans) {
+            if (span.metadata) {
+                for (const value of Object.values(span.metadata)) {
+                    if (typeof value === 'string' && value.toLowerCase().includes(lowerQuery)) {
+                        return true
+                    }
+                }
+            }
+        }
+
+        return false
+    }
+
+    function matchesSpanTypeFilter(trace: TraceEntry, types: Set<string>): boolean {
+        if (types.size === 0) return true
+
+        for (const span of trace.spans) {
+            if (types.has(span.type)) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    function matchesDurationFilter(trace: TraceEntry, min: number, max: number): boolean {
+        const hasExplicitDurationFilter = min > 0 || max < Infinity
+
+        if (trace.durationMs === undefined) {
+            return !hasExplicitDurationFilter
+        }
+
+        return trace.durationMs >= min && trace.durationMs <= max
+    }
+
+    function matchesRouteFilter(trace: TraceEntry, route: string): boolean {
+        if (!route) {
+            return true
+        }
+
+        // Check trace metadata for route
+        if (trace.metadata?.route && typeof trace.metadata.route === 'string') {
+            if (trace.metadata.route.toLowerCase().includes(route.toLowerCase())) {
+                return true
+            }
+        }
+
+        // Check span metadata for route or path
+        for (const span of trace.spans) {
+            if (span.metadata?.route) {
+                const routeValue = String(span.metadata.route).toLowerCase()
+
+                if (routeValue.includes(route.toLowerCase())) {
+                    return true
+                }
+            }
+
+            if (span.metadata?.path) {
+                const pathValue = String(span.metadata.path).toLowerCase()
+
+                if (pathValue.includes(route.toLowerCase())) {
+                    return true
+                }
+            }
+        }
+
+        return false
+    }
+
+    function filterTraces(traces: TraceEntry[]): TraceEntry[] {
+        return traces.filter((trace) => {
+            return (
+                matchesSearch(trace, searchQuery.value) &&
+                matchesSpanTypeFilter(trace, selectedSpanTypes.value) &&
+                matchesDurationFilter(trace, minDuration.value, maxDuration.value) &&
+                matchesRouteFilter(trace, routeFilter.value)
+            )
+        })
+    }
+
+    function toggleSpanType(type: string) {
+        if (selectedSpanTypes.value.has(type)) {
+            selectedSpanTypes.value.delete(type)
+        } else {
+            selectedSpanTypes.value.add(type)
+        }
+    }
+
+    function clearFilters() {
+        searchQuery.value = ''
+        selectedSpanTypes.value.clear()
+        minDuration.value = 0
+        maxDuration.value = Infinity
+        routeFilter.value = ''
+    }
+
+    const hasActiveFilters = computed(() => {
+        return (
+            searchQuery.value.length > 0 ||
+            selectedSpanTypes.value.size > 0 ||
+            minDuration.value > 0 ||
+            maxDuration.value < Infinity ||
+            routeFilter.value.length > 0
+        )
+    })
+
+    return {
+        searchQuery,
+        selectedSpanTypes,
+        minDuration,
+        maxDuration,
+        routeFilter,
+        filterTraces,
+        toggleSpanType,
+        clearFilters,
+        hasActiveFilters,
+    }
+}

package/client/src/stores/observatory.ts

@@ -1,7 +1,15 @@
 import { ref } from 'vue'
 import { useDevtoolsClient, onDevtoolsClientConnected } from '@nuxt/devtools-kit/iframe-client'
 import type { ObservatorySnapshot, ObservatoryServerFunctions, ObservatoryClientFunctions } from '@observatory/types/rpc'
-import type { FetchEntry, ProvideEntry, InjectEntry, ComposableEntry, RenderEntry, TransitionEntry } from '@observatory/types/snapshot'
+import type {
+    FetchEntry,
+    ProvideEntry,
+    InjectEntry,
+    ComposableEntry,
+    RenderEntry,
+    TransitionEntry,
+    TraceEntry,
+} from '@observatory/types/snapshot'
 
 type ProvideInjectSnapshot = { provides: ProvideEntry[]; injects: InjectEntry[] }
 
@@ -10,6 +18,7 @@ const provideInject = ref<ProvideInjectSnapshot>({ provides: [], injects: [] })
 const composables = ref<ComposableEntry[]>([])
 const renders = ref<RenderEntry[]>([])
 const transitions = ref<TransitionEntry[]>([])
+const traces = ref<TraceEntry[]>([])
 const connected = ref(false)
 const features = ref<ObservatorySnapshot['features']>({})
 const debugRpc = typeof window !== 'undefined' && new URLSearchParams(window.location.search).has('debugRpc')
@@ -50,6 +59,7 @@ function applySnapshot(data: ObservatorySnapshot) {
     composables.value = cloneArray(data.composables as ComposableEntry[] | undefined)
     renders.value = normalizeRenderEntries(data.renders as RenderEntry[] | undefined)
     transitions.value = cloneArray(data.transitions as TransitionEntry[] | undefined)
+    traces.value = cloneArray(data.traces as TraceEntry[] | undefined)
     features.value = data.features || {}
 
     // If the server snapshot disagrees with the user's requested mode,
@@ -79,6 +89,7 @@ function applySnapshot(data: ObservatorySnapshot) {
             composables: composables.value.length,
             renders: renders.value.length,
             transitions: transitions.value.length,
+            traces: traces.value.length,
         })
     }
 }
@@ -224,6 +235,7 @@ export function useObservatoryData() {
         composables,
         renders,
         transitions,
+        traces,
         features,
         connected,
         refresh,

package/client/src/views/ComposableTracker.vue

@@ -6,6 +6,7 @@ import {
     editComposableValue,
     openInEditor as openInEditorFromStore,
 } from '@observatory-client/stores/observatory'
+import { matchesComposableEntryQuery } from '@observatory-client/composables/composable-search'
 import type { ComposableEntry as RuntimeComposableEntry } from '@observatory/types/snapshot'
 
 const { composables: rawEntries, connected, features, clearComposables } = useObservatoryData()
@@ -118,23 +119,8 @@ const filtered = computed(() => {
             return false
         }
 
-        const q = search.value.toLowerCase()
-
-        if (q) {
-            const matchesName = entry.name.toLowerCase().includes(q)
-            const matchesFile = entry.componentFile.toLowerCase().includes(q)
-            const matchesRef = Object.keys(entry.refs).some((k) => k.toLowerCase().includes(q))
-            const matchesVal = Object.values(entry.refs).some((v) => {
-                try {
-                    return String(JSON.stringify(v.value)).toLowerCase().includes(q)
-                } catch {
-                    return false
-                }
-            })
-
-            if (!matchesName && !matchesFile && !matchesRef && !matchesVal) {
-                return false
-            }
+        if (search.value.trim() && !matchesComposableEntryQuery(entry, search.value)) {
+            return false
         }
 
         return true
@@ -234,22 +220,67 @@ function toggleRefExpand(entryId: string, refKey: string) {
 }
 
 // ── Reverse lookup ────────────────────────────────────────────────────────
-// Clicking a ref key shows every mounted instance that exposes the same key.
+// Clicking a ref key prefers identity-based lookup for shared/global refs.
+// For non-shared keys, fallback to legacy key-name lookup.
 
-const lookupKey = ref<string | null>(null)
+interface LookupTarget {
+    key: string
+    composableName: string
+    identityGroup?: string
+}
+
+const lookupTarget = ref<LookupTarget | null>(null)
 
 const lookupResults = computed(() => {
-    if (!lookupKey.value) {
+    if (!lookupTarget.value) {
         return []
     }
 
-    const key = lookupKey.value
+    const target = lookupTarget.value
+
+    if (target.identityGroup) {
+        return entries.value.filter(
+            (entry) =>
+                entry.name === target.composableName &&
+                entry.sharedKeyGroups?.[target.key] === target.identityGroup &&
+                target.key in entry.refs
+        )
+    }
 
-    return entries.value.filter((e) => key in e.refs)
+    return entries.value.filter((entry) => target.key in entry.refs)
 })
 
-function openLookup(key: string) {
-    lookupKey.value = lookupKey.value === key ? null : key
+const lookupTitle = computed(() => {
+    if (!lookupTarget.value) {
+        return ''
+    }
+
+    if (lookupTarget.value.identityGroup) {
+        return `${lookupTarget.value.key} (shared identity)`
+    }
+
+    return lookupTarget.value.key
+})
+
+function openLookup(entry: RuntimeComposableEntry, key: string) {
+    const identityGroup = entry.sharedKeyGroups?.[key]
+    const next: LookupTarget = {
+        key,
+        composableName: entry.name,
+        identityGroup,
+    }
+
+    if (
+        lookupTarget.value?.key === next.key &&
+        lookupTarget.value?.composableName === next.composableName &&
+        lookupTarget.value?.identityGroup === next.identityGroup
+    ) {
+        lookupTarget.value = null
+
+        return
+    }
+
+    lookupTarget.value = next
 }
 
 // ── Inline editing ────────────────────────────────────────────────────────
@@ -408,8 +439,12 @@ function applyEdit() {
                     <div v-for="[k, v] in Object.entries(entry.refs)" :key="k" class="composable-tracker__ref-row">
                         <span
                             class="composable-tracker__ref-key composable-tracker__ref-key--clickable mono text-sm"
-                            :title="`click to see all instances exposing '${k}'`"
-                            @click.stop="openLookup(k)"
+                            :title="
+                                entry.sharedKeyGroups?.[k]
+                                    ? `click to see instances sharing this exact '${k}' state`
+                                    : `click to see all instances exposing '${k}'`
+                            "
+                            @click.stop="openLookup(entry, k)"
                         >
                             {{ k }}
                         </span>
@@ -530,14 +565,14 @@ function applyEdit() {
 
         <!-- ── Reverse lookup panel ──────────────────────────────────────── -->
         <Transition name="slide">
-            <div v-if="lookupKey" class="composable-tracker__lookup-panel">
+            <div v-if="lookupTarget" class="composable-tracker__lookup-panel">
                 <div class="composable-tracker__lookup-header">
-                    <span class="mono text-sm">{{ lookupKey }}</span>
+                    <span class="mono text-sm">{{ lookupTitle }}</span>
                     <span class="muted text-sm">— {{ lookupResults.length }} instance{{ lookupResults.length !== 1 ? 's' : '' }}</span>
-                    <button class="composable-tracker__clear-btn composable-tracker__lookup-close" @click="lookupKey = null">✕</button>
+                    <button class="composable-tracker__clear-btn composable-tracker__lookup-close" @click="lookupTarget = null">✕</button>
                 </div>
                 <div v-if="!lookupResults.length" class="composable-tracker__lookup-empty muted text-sm">
-                    No mounted instances expose this key.
+                    No instances matched this lookup.
                 </div>
                 <div v-for="r in lookupResults" :key="r.id" class="composable-tracker__lookup-row">
                     <span class="mono text-sm">{{ r.name }}</span>