nuxt-devtools-observatory 0.1.28 → 0.1.31

package/README.md

@@ -2,22 +2,26 @@
 
 # Nuxt DevTools Observatory
 
-Nuxt DevTools module providing five missing observability features:
+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
 
-An in-repo docs site is available in `docs/` (Docus + Nuxt Content).
+An in-repo documentation site lives in `docs/`. It is a custom Nuxt app built with
+Nuxt Content and Nuxt UI.
 
 - Run locally from repo root: `pnpm docs:dev`
 - Production build: `pnpm docs:build`
+- Generate a static build: `pnpm docs:generate`
+- Preview the generated output: `pnpm docs:preview`
 
-Vercel deployment is configured to use `docs/` as the project root directory.
+For Vercel deployment, set `docs/` as the project root directory.
 
 ## Installation
 
@@ -25,17 +29,21 @@ Vercel deployment is configured to use `docs/` as the project root directory.
 pnpm add nuxt-devtools-observatory
 ```
 
-You can configure all observability features and limits from your consuming project's `nuxt.config.ts` or `.env` file. All options in `.env.example` are supported as either environment variables or as properties under the `observatory` key in your Nuxt config. Options set in `nuxt.config.ts` take precedence over `.env` values.
+You can configure all observability features and limits from your consuming project's
+`nuxt.config.ts` under the `observatory` key. Common environment variables are listed
+in `.env.example`; use the `OBSERVATORY_*` names when configuring through `.env`.
+Options set in `nuxt.config.ts` take precedence over environment variables.
 
 **Available options:**
 
-- `instrumentServer` (boolean) — Instrument the server for SSR/Nitro fetch and composable tracking (set via `OBSERVATORY_INSTRUMENT_SERVER` or `VITE_OBSERVATORY_INSTRUMENT_SERVER`)
+- `instrumentServer` (boolean) — Instrument the server for SSR/Nitro fetch and composable tracking (set via `OBSERVATORY_INSTRUMENT_SERVER`)
 - `fetchDashboard` (boolean) — Enable useFetch dashboard
 - `provideInjectGraph` (boolean) — Enable provide/inject graph
 - `composableTracker` (boolean) — Enable composable tracker
 - `renderHeatmap` (boolean) — Enable render heatmap
-- `transitionTracker` (boolean) — Enable transition tracker
-- `composableNavigationMode` (string, 'route' | 'session') — Composable tracker mode: 'route' clears entries on page navigation (default), 'session' persists entries across navigation for historical inspection
+- `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)
 - `heatmapHideInternals` (boolean) — Hide node_modules and internal components in the render heatmap for a cleaner view
@@ -47,7 +55,8 @@ You can configure all observability features and limits from your consuming proj
 - `maxComposableEntries` (number) — Max composable entries to keep in memory
 - `maxRenderTimeline` (number) — Max render timeline events per entry
 
-See `.env.example` for all environment variable names.
+Feature tabs are enabled by default in development. `instrumentServer` defaults to
+`true` for SSR apps and `false` for SPA apps.
 
 ```ts
 // nuxt.config.ts
@@ -61,6 +70,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)
@@ -78,7 +88,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/`.
 
@@ -220,6 +230,55 @@ The panel provides:
 - 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 |
+| `composable` | `__trackComposable` shim          | Setup phase of every tracked `useXxx()` call         |
+| `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
+
+**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
+
+**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)
@@ -270,6 +329,12 @@ const result = useMyComposable()
 - [ ] 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
+
 ## Development
 
 ```bash
@@ -279,9 +344,18 @@ pnpm install
 # Run the playground
 pnpm dev
 
+# Run the docs site
+pnpm docs:dev
+
 # Run tests
 pnpm test
 
+# Run end-to-end checks
+pnpm test:e2e
+
+# Update screenshot fixtures
+pnpm capture:screenshots
+
 # Format + lint fixes
 pnpm format
 
@@ -325,10 +399,11 @@ client/
         ├── ProvideInjectGraph.vue      ← provide/inject tab UI
         ├── ComposableTracker.vue       ← Composable tab UI
         ├── RenderHeatmap.vue           ← Heatmap tab UI
-        └── TransitionTimeline.vue      ← Transition tracker tab UI
+        ├── TransitionTimeline.vue      ← Transition tracker tab UI
+        └── TraceViewer.vue             ← Trace viewer tab UI (Flamegraph + Waterfall + Inspector)
 
 playground/
-├── app.vue                             ← Demo app exercising all five features
+├── app.vue                             ← Demo app shell used during local development
 ├── nuxt.config.ts
 ├── composables/
 │   ├── useCounter.ts                   ← Clean composable (properly cleaned up)
@@ -345,6 +420,13 @@ playground/
 │       └── CancelledTransition.vue     ← Rapid toggle triggers enter-cancelled / leave-cancelled
 └── server/api/
     └── product.ts                      ← Mock API endpoint
+
+docs/
+├── app.vue                             ← Docs app shell
+├── content/                            ← Versioned guides and API pages
+├── layouts/                            ← Docs layouts
+├── pages/                              ← Landing page + content catch-all route
+└── server/api/                         ← Docs-specific API handlers
 ```
 
 ## License

package/client/.env

@@ -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

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