nuxt-devtools-observatory 0.1.30 → 0.1.32

package/README.md

@@ -2,13 +2,17 @@
 
 # Nuxt DevTools Observatory
 
-Nuxt DevTools module providing five missing observability features:
+> [!WARNING]
+> **Performance note:** Instrumentation wraps every useFetch, composable, and lifecycle hook. In large apps this can slow down the DevTools UI or increase memory usage. Disable unused features via the observatory config.
+
+Nuxt DevTools module providing six missing observability features:
 
 - **useFetch Dashboard** — central view of all async data calls, cache keys, waterfall timeline
 - **provide/inject Graph** — interactive tree showing the full injection topology, value inspection, scope labels, shadow detection, and missing-provider warnings
 - **Composable Tracker** — live view of active composables, reactive state, change history, leak detection, inline value editing, and reverse lookup
 - **Render Heatmap** — component tree colour-coded by render frequency and duration, with per-render timeline, route filtering, and persistent-component accuracy fixes
 - **Transition Tracker** — live timeline of every `<Transition>` lifecycle event with phase, duration, and cancellation state
+- **Trace Viewer** — per-route span traces capturing component mount order, real render durations, fetch timing, composable setup, and navigation events in a unified Flamegraph and Waterfall view
 
 ## Documentation website
 
@@ -40,7 +44,8 @@ Options set in `nuxt.config.ts` take precedence over environment variables.
 - `provideInjectGraph` (boolean) — Enable provide/inject graph
 - `composableTracker` (boolean) — Enable composable tracker
 - `renderHeatmap` (boolean) — Enable render heatmap
-- `transitionTracker` (boolean) — Enable transition tracker
+- `transitionTracker` (boolean) — Enable transition tracker (set via `OBSERVATORY_TRANSITION_TRACKER`)
+- `traceViewer` (boolean) — Enable trace viewer tab with per-route Flamegraph and Waterfall (set via `OBSERVATORY_TRACE_VIEWER`)
 - `composableNavigationMode` (string, 'route' | 'session') — Composable tracker mode: 'route' clears entries on page navigation (default), 'session' persists entries across navigation for historical inspection (`OBSERVATORY_COMPOSABLE_NAVIGATION_MODE`)
 - `heatmapThresholdCount` (number) — Highlight components with N+ renders in heatmap
 - `heatmapThresholdTime` (number) — Highlight components with render time above this (ms)
@@ -68,6 +73,7 @@ export default defineNuxtConfig({
         composableTracker: true, // Enable composable tracker
         renderHeatmap: true, // Enable render heatmap
         transitionTracker: true, // Enable transition tracker
+        traceViewer: true, // Enable trace viewer
         composableNavigationMode: 'route', // 'route' clears entries on navigation (default), 'session' persists across navigation
         heatmapThresholdCount: 5, // Highlight components with 5+ renders
         heatmapThresholdTime: 1600, // Highlight components with render time above this (ms)
@@ -85,7 +91,7 @@ export default defineNuxtConfig({
 })
 ```
 
-Open the Nuxt DevTools panel — five new tabs will appear.
+Open the Nuxt DevTools panel — six new tabs will appear.
 
 The DevTools client SPA is served same-origin via the Nuxt dev server at `/__observatory/`.
 
@@ -159,27 +165,22 @@ wraps them with a tracking shim (`__trackComposable`) that:
 The panel provides:
 
 - **Navigation mode toggle** — switch between 'route' mode (clears entries on navigation) and 'session' mode (persists entries across pages). In session mode, a "clear session" button appears to manually reset the history
-- **Filtering** by status (all / mounted / unmounted / leaks only) and free-text search across composable name, source file, ref key names, and ref values
+- **Filtering** by status (all / mounted / unmounted / leaks only) and free-text search across composable name, source file, ref key names, ref values, and nested reactive object properties
 - **Recency-first ordering** — newest entries appear first, with layout-level composables pinned to the top (layout composables persist across page navigation)
 - **Inline ref chip preview** — up to three reactive values shown on the card without expanding, with distinct styling for `ref`, `computed`, and `reactive` types
 - **Collapsible ref values** — long objects and arrays automatically collapse with a chevron toggle to expand them inline in the detail view with full pretty-printed JSON
 - **Global state badges** — keys shared across instances are highlighted in amber with a `global` badge and an explanatory banner when expanded
 - **Change history** — a scrollable log of the last 50 value mutations with key, new value, and relative timestamp
 - **Lifecycle summary** — shows whether `onMounted`/`onUnmounted` were registered and whether watchers and intervals were properly cleaned up
-- **Reverse lookup** — clicking any ref key opens a panel listing every other composable instance that exposes a key with the same name, with its composable name, file, and route
+- **Reverse lookup** — clicking any ref key opens a panel listing related composable instances. For shared/global refs it matches by shared object identity; otherwise it falls back to key-name matching
 - **Inline value editing** — writable `ref` values have an `edit` button; clicking opens a JSON textarea that applies the new value directly to the live ref in the running app
 - **Jump to editor** — an `open ↗` button in the context section opens the composable's source file in the configured editor
 
-**Known gaps:**
-
-- Reverse lookup matches by key name only, not by object identity
-- Search does not look inside nested `reactive` object properties
-
 ### Render Heatmap
 
 [![Render Heatmap](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/render-heatmap.png)](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/render-heatmap.png)
 
-Uses Vue's built-in `renderTriggered` mixin hook and `app.config.performance = true`.
+Uses Vue lifecycle instrumentation with `app.config.performance = true`.
 Accurate duration is measured by bracketing each `beforeMount`/`mounted` and
 `beforeUpdate`/`updated` cycle with `performance.now()` timestamps.
 Component bounding boxes are captured via `$el.getBoundingClientRect()` for the DOM
@@ -191,8 +192,7 @@ last). Every mount and update cycle appends an event recording:
 - `kind` — `mount` or `update`
 - `t` — `performance.now()` timestamp
 - `durationMs` — measured render duration
-- `triggerKey` — the reactive dep that caused the update (when `renderTriggered` fired
-  before `updated`), formatted as `type: key`
+- `triggerKey` — optional reactive dep label for the update (when available)
 - `route` — the route path at the time of the render
 
 A `route` field on each entry records which route the component was first seen on.
@@ -221,12 +221,70 @@ The panel provides:
   panel's identity section has an `open ↗` button; both call Vite's built-in
   `/__open-in-editor` endpoint to open the component's source file in the configured
   editor
+- **Export / Import** — `↓ export` downloads the current render data (live or frozen
+  snapshot) as a `.json` file; `↑ import` loads a previously exported file and
+  automatically enters freeze mode so the imported snapshot is displayed in place of
+  live data; the freeze button label changes to `unfreeze (imported)` to signal the
+  import state
 
 **Known gaps:**
 
 - The route filter shows components active on a route but cannot hide persistent
   components (they appear on every route by definition)
 
+### Trace Viewer
+
+[![Trace Viewer](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/trace-viewer.png)](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/trace-viewer.png)
+
+The Trace Viewer automatically collects per-route traces that span the full lifecycle of
+each page visit. Every significant event is recorded as a typed span and grouped into a
+single `TraceEntry` per navigation, so you can see everything that happened — in order —
+after a route change.
+
+**Span types collected:**
+
+| Type         | Emitted by                        | What it measures                                       |
+| ------------ | --------------------------------- | ------------------------------------------------------ |
+| `navigation` | `router.afterEach` hook           | Route change from → to, duration                       |
+| `component`  | Vue mixin lifecycle hooks         | Exact `mounted` / `updated` hook cost                  |
+| `render`     | `beforeMount` → `mounted` bracket | Real DOM-patching time per component mount/update      |
+| `fetch`      | `useFetch` / `useAsyncData` shim  | Network request start, server/client origin, latency   |
+| `server`     | Nitro SSR lifecycle hooks         | Server-side phase timing (e.g. `render:html`)          |
+| `composable` | `__trackComposable` shim          | Setup phase of tracked `useXxx()` calls (client + SSR) |
+| `transition` | `<Transition>` wrapper            | Full enter/leave lifecycle phase                       |
+
+**Render span tracking:**
+Real render time is measured by storing `performance.now()` in a `WeakMap<ComponentPublicInstance, number>` inside `beforeMount` / `beforeUpdate`, then reading it back in the corresponding `mounted` / `updated` hooks. This produces a `type: 'render'` span whose duration is the actual DOM-patching cost, separately from the `component:mounted` hook span (which only measures the hook body itself).
+
+**Trace anchoring:**
+Each `TraceEntry` is anchored to the `startTime` of its first span, so bar positions in the timeline are always relative to the first event in the trace rather than the time the trace object was created.
+
+The panel provides:
+
+- **Trace list** — every captured route visit shown with name, total duration, and span count; click to open
+- **Flamegraph tab** — collapsible span tree with horizontal duration bars, depth-based indentation, parent–child nesting, and a selected-span highlight (purple tint)
+- **Waterfall tab** — spans grouped by type with a shared horizontal timeline, group headers, and status badges
+- **Span inspector** — clicking any span opens a detail panel showing type, status, duration, start offset, and all metadata fields
+- **Filter panel** — filter by span type and free-text search across span names and metadata
+- **Duration labels** — spans narrower than 5 % of the timeline render their label outside the bar for readability
+- **In-progress traces** — active traces show `~Xms` (computed from the latest span end offset) rather than a hard "in progress" label
+- **Export / Import** — `↓ export` downloads all captured traces as a `.json` file
+  (always exports the full unfiltered dataset); `↑ import` loads a previously exported
+  file and freezes the view on the imported data; a `← live` button returns to the
+  live stream; the trace count label shows `(imported)` while viewing imported data
+- **Cross-trace render comparison** — compares render behavior across filtered traces,
+  with per-component average re-renders per trace, selected-trace value, and delta
+  versus baseline; includes sortable columns, quick filters (regressions/comparable),
+  in-table search, and condensed mobile columns
+
+**What it tells you:**
+
+- Mount order and render cost of every component on the route
+- Whether render time is dominated by the component `setup()` / lifecycle hooks or by actual DOM patching
+- Which `useFetch` calls are in the critical path and how long each took
+- Whether composable setup is adding meaningful latency
+- Which components are slow to mount and might benefit from `<Suspense>` or lazy loading
+
 ### Transition Tracker
 
 [![Transition Tracker](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/transition-tracker.png)](https://github.com/victorlmneves/nuxt-devtools-observatory/blob/main/docs/screenshots/transition-tracker.png)
@@ -272,10 +330,7 @@ const result = useMyComposable()
 
 ## Roadmap
 
-### Composable Tracker
-
-- [ ] Reverse lookup by object identity rather than key name only
-- [ ] Deep search inside nested `reactive` object properties
+- [x] Dedicated cross-trace comparison UI polish (sorting, stronger visual deltas, and quick filtering)
 
 ## Development
 
@@ -315,16 +370,26 @@ src/
 │   ├── provide-inject-transform.ts     ← AST wraps provide/inject
 │   ├── composable-transform.ts         ← AST wraps useX() composables
 │   └── transition-transform.ts         ← Virtual vue proxy — overrides Transition export
-├── runtime/
-│   ├── plugin.ts                       ← Client runtime bootstrap + RPC/Vite WS bridge
-│   └── composables/
-│       ├── fetch-registry.ts           ← Fetch tracking store + __devFetch shim
-│       ├── provide-inject-registry.ts  ← Injection tracking + __devProvide/__devInject
-│       ├── composable-registry.ts      ← Composable tracking + __trackComposable + leak detection
-│       ├── render-registry.ts          ← Render performance data via PerformanceObserver
-│       └── transition-registry.ts      ← Transition lifecycle store
-└── nitro/
-    └── fetch-capture.ts                ← SSR-side fetch timing
+└── runtime/
+    ├── plugin.ts                       ← Client runtime bootstrap + RPC/Vite WS bridge
+    ├── composables/
+    │   ├── fetch-registry.ts           ← Fetch tracking store + __devFetch shim
+    │   ├── provide-inject-registry.ts  ← Injection tracking + __devProvide/__devInject
+    │   ├── composable-registry.ts      ← Composable tracking + __trackComposable + leak detection
+    │   ├── render-registry.ts          ← Render registry (timeline, route attribution, bbox snapshots)
+    │   └── transition-registry.ts      ← Transition lifecycle store
+    ├── instrumentation/
+    │   ├── route.ts                    ← router.afterEach hook — opens/closes traces per navigation
+    │   ├── component.ts                ← Vue mixin lifecycle hooks — component + render spans
+    │   ├── fetch.ts                    ← useFetch/useAsyncData span recording
+    │   └── asyncData.ts                ← useAsyncData-specific span handling
+    ├── tracing/
+    │   ├── trace.ts                    ← Span + Trace types (server-side internal)
+    │   ├── traceStore.ts               ← In-memory Map<string, Trace> store
+    │   ├── tracing.ts                  ← Span open/close helpers
+    │   └── context.ts                  ← Current-trace context (per async task)
+    └── nitro/
+      └── fetch-capture.ts            ← SSR request tracing bridge (fetch + server phases + context)
 
 client/
 ├── index.html
@@ -335,30 +400,52 @@ client/
     ├── main.ts
     ├── style.css                       ← Design system
     ├── components/
+    ├── composables/
+    │   ├── composable-search.ts        ← Deep nested composable search matching utilities
+    │   ├── trace-render-aggregation.ts ← Per-trace and cross-trace render aggregation helpers
+    │   ├── useExportImport.ts          ← JSON export (download) and import (file picker) utilities
+    │   ├── useResizablePane.ts         ← Resizable split-pane drag handle
+    │   └── useTraceFilter.ts           ← Trace filter state and filtering logic
     ├── stores/
     └── views/
         ├── FetchDashboard.vue          ← useFetch tab UI
         ├── ProvideInjectGraph.vue      ← provide/inject tab UI
         ├── ComposableTracker.vue       ← Composable tab UI
+        ├── ComponentBlock.vue          ← Shared component detail block
+        ├── ValueInspector.vue          ← Inline JSON value inspector
         ├── RenderHeatmap.vue           ← Heatmap tab UI
-        └── TransitionTimeline.vue      ← Transition tracker tab UI
+        ├── TransitionTimeline.vue      ← Transition tracker tab UI
+        └── TraceViewer.vue             ← Trace viewer tab UI (Overview + Flamegraph + Waterfall + Inspector + cross-trace comparison)
 
 playground/
 ├── app.vue                             ← Demo app shell used during local development
 ├── nuxt.config.ts
 ├── composables/
 │   ├── useCounter.ts                   ← Clean composable (properly cleaned up)
-│   └── useLeakyPoller.ts               ← Intentionally leaky (for demo)
+│   ├── useLeakyPoller.ts               ← Intentionally leaky (for demo)
+│   ├── useCart.ts                      ← Cart state composable
+│   ├── useDashboard.ts                 ← Dashboard data composable
+│   ├── useLeakyCartAudit.ts            ← Leaky audit poller (for demo)
+│   ├── usePersistentCartSummary.ts     ← Cart summary across navigations
+│   ├── useProductFilter.ts             ← Product search/filter state
+│   └── useUserPreferences.ts           ← User preferences store
 ├── components/
 │   ├── ThemeConsumer.vue               ← Successfully injects 'theme'
 │   ├── MissingProviderConsumer.vue     ← Injects 'cartContext' (no provider — red node)
 │   ├── LeakyComponent.vue              ← Mounts useLeakyPoller
+│   ├── LeakyCartMonitor.vue            ← Mounts useLeakyCartAudit
 │   ├── HeavyList.vue                   ← Re-renders on every shuffle (heatmap demo)
 │   ├── PriceDisplay.vue                ← Leaf component with high render count
+│   ├── CartDrawer.vue                  ← Cart sidebar
+│   ├── CartItem.vue                    ← Individual cart item row
+│   ├── DataTable.vue                   ← Generic sortable table
+│   ├── SettingsPanel.vue               ← Settings form panel
+│   ├── StatsCard.vue                   ← Stat metric card
 │   └── transitions/
 │       ├── FadeBox.vue                 ← Healthy enter/leave transition
 │       ├── BrokenTransition.vue        ← Missing CSS classes (enter fires but stays in entering)
-│       └── CancelledTransition.vue     ← Rapid toggle triggers enter-cancelled / leave-cancelled
+│       ├── CancelledTransition.vue     ← Rapid toggle triggers enter-cancelled / leave-cancelled
+│       └── InterruptedTransition.vue   ← Back-to-back transitions trigger interrupted phase
 └── server/api/
     └── product.ts                      ← Mock API endpoint
 

package/client/.env.example

@@ -1,9 +1,10 @@
-# Observatory registry/configurable limits
+# VITE_Observatory registry/configurable limits
 VITE_OBSERVATORY_FETCH_DASHBOARD=true
 VITE_OBSERVATORY_PROVIDE_INJECT_GRAPH=true
 VITE_OBSERVATORY_COMPOSABLE_TRACKER=true
 VITE_OBSERVATORY_RENDER_HEATMAP=true
 VITE_OBSERVATORY_TRANSITION_TRACKER=true
+VITE_OBSERVATORY_TRACE_VIEWER=true
 VITE_OBSERVATORY_MAX_FETCH_ENTRIES=200
 VITE_OBSERVATORY_MAX_PAYLOAD_BYTES=10000
 VITE_OBSERVATORY_MAX_TRANSITIONS=500