nuxt-devtools-observatory 0.1.31 → 0.1.32

package/README.md

@@ -2,6 +2,9 @@
 
 # Nuxt DevTools Observatory
 
+> [!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
@@ -162,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
@@ -194,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.
@@ -224,6 +221,11 @@ 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:**
 
@@ -241,14 +243,15 @@ 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 |
-| `composable` | `__trackComposable` shim          | Setup phase of every tracked `useXxx()` call         |
-| `transition` | `<Transition>` wrapper            | Full enter/leave lifecycle phase                     |
+| 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).
@@ -265,6 +268,14 @@ The panel provides:
 - **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:**
 
@@ -274,11 +285,6 @@ The panel provides:
 - Whether composable setup is adding meaningful latency
 - Which components are slow to mount and might benefit from `<Suspense>` or lazy loading
 
-**Known gaps:**
-
-- SSR spans are not yet captured — only client-side navigation traces are collected
-- Re-render counts are tracked by Render Heatmap; the Trace Viewer records individual render events but does not aggregate them
-
 ### 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)
@@ -324,16 +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
-
-### Trace Viewer
-
-- [ ] SSR span collection (server-side navigation and composable setup)
-- [ ] Cross-trace comparison view
-- [ ] Export traces as JSON
+- [x] Dedicated cross-trace comparison UI polish (sorting, stronger visual deltas, and quick filtering)
 
 ## Development
 
@@ -373,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
@@ -393,31 +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
-        └── TraceViewer.vue             ← Trace viewer tab UI (Flamegraph + Waterfall + Inspector)
+        └── 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