feat(vue): Vue Router performance tracing (#74)

* docs: vue-router performance tracing design spec

* refactor(js): shared insulate/safeInvoke instrumentation guards

* refactor(react): use shared insulate/safeInvoke in router integrations

* feat(vue): vue-router performance tracing (traceVueRouter)

* feat(vue): flareVue { router } option wires vue-router tracing

* feat(playgrounds): enable tracing + router option in vue playground

* test(e2e): vue-router pageload/navigation trace assertions

* docs: vue-router tracing spec — shared instrumentation guards + HMR dedup

* fix(vue): guard traceVueRouter cleanup + pin router-tracing edge cases

Guard the WeakMap delete in cleanup() so a stale HMR cleanup can't
disable dedup for the active guards. Add coverage for the onError
empty-name fallback and blocked-initial-navigation pageload naming,
and assert the settled route name (not just call count) on the
existing onError test.

* fix(vue): gate router tracing wiring on enableTracing

Skip traceVueRouter when enableTracing is off, so passing { router }
without tracing enabled no longer attaches no-op guards to the host's
router or registers a dead navigation source. Adds an entry test for
the gate and updates the design spec to match.

* fix(vue): type FlareErrorBoundary $router mock for active vue-router augmentation

Author: DriesH

docs/superpowers/specs/2026-07-14-performance-tracing-framework-router-vue-router-design.md

@@ -1,6 +1,7 @@
 import { testIds } from '../../playgrounds/shared/src';
 import { expect, test } from '../fixtures/fake-flare';
 import { logScenariosFor, runLogScenario } from './logShared';
+import { attr, hasSpanType, spansOf } from './otlp';
 import { runScenario, scenariosFor } from './shared';
 
 test.describe('vue playground', () => {
@@ -30,6 +31,57 @@ test.describe('vue playground', () => {
     });
 });
 
+test.describe('vue-router tracing', () => {
+    test('pageload root carries the parameterized route and route source', async ({ page, fakeFlare }) => {
+        await page.goto('/product/p01');
+        await page.waitForLoadState('networkidle');
+
+        const trace = await fakeFlare.waitForTrace({
+            timeout: 9000,
+            predicate: (r) => {
+                const pl = spansOf(r.bodyJson).find((s) => hasSpanType(s, 'browser_pageload'));
+                return !!pl && JSON.stringify(attr(pl, 'flare.route.source') ?? '').includes('route');
+            },
+        });
+        const pageload = spansOf(trace.bodyJson).find((s) => hasSpanType(s, 'browser_pageload'));
+        expect(pageload && attr(pageload, 'flare.entry_point.handler.identifier')).toEqual({
+            stringValue: '/product/:id',
+        });
+        expect(pageload && attr(pageload, 'flare.route.source')).toEqual({ stringValue: 'route' });
+    });
+
+    test('client navigation opens a parameterized browser_navigation root (exactly one)', async ({
+        page,
+        fakeFlare,
+    }) => {
+        await page.goto('/');
+        await page.waitForLoadState('networkidle');
+
+        await page.locator('a[href="/product/p01"]').first().click();
+
+        const trace = await fakeFlare.waitForTrace({
+            timeout: 9000,
+            predicate: (r) => {
+                const nav = spansOf(r.bodyJson).find((s) => hasSpanType(s, 'browser_navigation'));
+                return (
+                    !!nav &&
+                    JSON.stringify(attr(nav, 'flare.entry_point.handler.identifier') ?? '').includes('/product/:id')
+                );
+            },
+        });
+        const nav = spansOf(trace.bodyJson).find((s) => hasSpanType(s, 'browser_navigation'));
+        expect(nav && attr(nav, 'flare.entry_point.handler.identifier')).toEqual({ stringValue: '/product/:id' });
+        expect(nav && attr(nav, 'flare.route.source')).toEqual({ stringValue: 'route' });
+
+        // No-double-roots invariant: registerNavigationSource suppresses the History-based root, so this
+        // one click produces exactly ONE browser_navigation root across all traces.
+        const navSpans = (await fakeFlare.traces())
+            .flatMap((t) => spansOf(t.bodyJson))
+            .filter((s) => hasSpanType(s, 'browser_navigation'));
+        expect(navSpans).toHaveLength(1);
+    });
+});
+
 test.describe('vue logging', () => {
     for (const scenario of logScenariosFor('vue').filter((s) => s.flushOnTrigger)) {
         test(scenario.id, async ({ page, fakeFlare }) => {

e2e/specs/vue.spec.ts

@@ -58,6 +58,7 @@ export { collectBrowser } from './browser/context/collectBrowser';
 export { FetchFileReader } from './browser/FetchFileReader';
 export { BrowserFlushScheduler } from './browser/BrowserFlushScheduler';
 export { registerNavigationSource, type NavigationSource, type RouteName } from './tracing/browserTracing';
+export { insulate, safeInvoke } from './tracing/instrumentationGuard';
 export {
     activeComponentRoot,
     reserveSpanId,

packages/js/src/browser.ts

@@ -0,0 +1,24 @@
+// Pure, environment-agnostic guards shared by the framework router integrations. They encode the one
+// rule every host-invoked instrumentation callback must obey: a tracing throw can never escape into the
+// host's dispatch. Exported from the side-effect-free '@flareapp/js/browser' barrel.
+
+/** Wrap a host-invoked callback (router guard / store subscriber) so a tracing throw can never escape
+ *  into the host's dispatch. A thrown callback resolves to `undefined`. */
+export function insulate<A extends unknown[]>(fn: (...a: A) => void): (...a: A) => void {
+    return (...a: A): void => {
+        try {
+            fn(...a);
+        } catch {
+            // instrumentation never breaks the host
+        }
+    };
+}
+
+/** Invoke a teardown fn now (if present), swallowing any throw. For cleanup chains. */
+export function safeInvoke(fn: (() => void) | null | undefined): void {
+    try {
+        fn?.();
+    } catch {
+        // ignore
+    }
+}

packages/js/src/tracing/instrumentationGuard.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { insulate, safeInvoke } from '../src/tracing/instrumentationGuard';
+
+describe('insulate', () => {
+    it('forwards args to the wrapped fn', () => {
+        const fn = vi.fn();
+        insulate(fn)('a', 1);
+        expect(fn).toHaveBeenCalledWith('a', 1);
+    });
+
+    it('swallows a throw and returns undefined', () => {
+        const wrapped = insulate(() => {
+            throw new Error('boom');
+        });
+        expect(wrapped()).toBeUndefined();
+        expect(() => wrapped()).not.toThrow();
+    });
+});
+
+describe('safeInvoke', () => {
+    it('invokes the fn', () => {
+        const fn = vi.fn();
+        safeInvoke(fn);
+        expect(fn).toHaveBeenCalledOnce();
+    });
+
+    it('tolerates null / undefined', () => {
+        expect(() => safeInvoke(null)).not.toThrow();
+        expect(() => safeInvoke(undefined)).not.toThrow();
+    });
+
+    it('swallows a throw', () => {
+        expect(() =>
+            safeInvoke(() => {
+                throw new Error('boom');
+            }),
+        ).not.toThrow();
+    });
+});

packages/js/tests/instrumentationGuard.test.ts

@@ -1,7 +1,7 @@
 // Electron-safe entry: NO @flareapp/js root import. The navigation-source seam comes from
 // @flareapp/js/browser (side-effect-free). NO runtime dependency on react-router — the router is
 // consumed structurally (see ./vendor/reactRouterTypes).
-import { registerNavigationSource, type RouteName } from '@flareapp/js/browser';
+import { insulate, registerNavigationSource, safeInvoke, type RouteName } from '@flareapp/js/browser';
 
 import type { RRDataRouter, RRLocation, RRMatch, RRRouterState } from './vendor/reactRouterTypes';
 
@@ -123,24 +123,10 @@ export function traceReactRouter(router: RRDataRouter): () => void {
         // else (inFlight && non-idle): a redirect / superseding hop -> keep the single held root.
     };
 
-    const unsubscribe = router.subscribe((state) => {
-        try {
-            onState(state);
-        } catch {
-            // a tracing error must never escape into the router's state dispatch
-        }
-    });
+    const unsubscribe = router.subscribe(insulate(onState));
 
     return () => {
-        try {
-            unsubscribe();
-        } catch {
-            // ignore
-        }
-        try {
-            nav.unregister();
-        } catch {
-            // ignore
-        }
+        safeInvoke(unsubscribe);
+        safeInvoke(() => nav.unregister());
     };
 }

packages/react/src/react-router.ts

@@ -1,7 +1,7 @@
 // Electron-safe entry: NO @flareapp/js root import. The navigation-source seam
 // comes from @flareapp/js/browser (side-effect-free). NO runtime dependency on
 // @tanstack/react-router — the router is consumed structurally (see ./vendor).
-import { registerNavigationSource, type RouteName } from '@flareapp/js/browser';
+import { insulate, registerNavigationSource, safeInvoke, type RouteName } from '@flareapp/js/browser';
 
 import type { TsrLocation, TsrNavEvent, TsrRouter } from './vendor/tanstackRouterTypes';
 
@@ -27,17 +27,6 @@ export function traceTanStackRouter(router: TsrRouter): () => void {
         return { name: loc.pathname, source: 'url' };
     };
 
-    // A tracing error must never escape into the router's event dispatch.
-    const guard =
-        (fn: (event: TsrNavEvent) => void) =>
-        (event: TsrNavEvent): void => {
-            try {
-                fn(event);
-            } catch {
-                // swallow: instrumentation never breaks the host
-            }
-        };
-
     // Enrich the pageload root immediately from the current (already-resolved) location.
     try {
         nav.setActiveRouteName(routeNameFor(router.state.location));
@@ -49,7 +38,7 @@ export function traceTanStackRouter(router: TsrRouter): () => void {
 
     const offBeforeLoad = router.subscribe(
         'onBeforeLoad',
-        guard((e) => {
+        insulate((e: TsrNavEvent) => {
             if (e.fromLocation === undefined) return; // initial pageload (handled via onResolved)
             if (e.toLocation.state === e.fromLocation.state) return; // no-op reload (e.g. router.invalidate())
             if (!inFlight) {
@@ -62,7 +51,7 @@ export function traceTanStackRouter(router: TsrRouter): () => void {
 
     const offResolved = router.subscribe(
         'onResolved',
-        guard((e) => {
+        insulate((e: TsrNavEvent) => {
             if (e.fromLocation === undefined) {
                 nav.setActiveRouteName(routeNameFor(e.toLocation)); // one-shot pageload correction
                 return;
@@ -75,20 +64,8 @@ export function traceTanStackRouter(router: TsrRouter): () => void {
     );
 
     return () => {
-        try {
-            offBeforeLoad();
-        } catch {
-            // ignore
-        }
-        try {
-            offResolved();
-        } catch {
-            // ignore
-        }
-        try {
-            nav.unregister();
-        } catch {
-            // ignore
-        }
+        safeInvoke(offBeforeLoad);
+        safeInvoke(offResolved);
+        safeInvoke(() => nav.unregister());
     };
 }

packages/react/src/tanstack-router.ts

@@ -10,14 +10,22 @@ describe('@flareapp/react/react-router entry', () => {
     test('importing the entry does NOT evaluate the @flareapp/js root singleton', async () => {
         const rootFactory = vi.fn(() => ({ flare: {} }));
         vi.doMock('@flareapp/js', rootFactory);
-        vi.doMock('@flareapp/js/browser', () => ({ registerNavigationSource: () => ({}) }));
+        vi.doMock('@flareapp/js/browser', () => ({
+            registerNavigationSource: () => ({}),
+            insulate: (fn: (...a: unknown[]) => void) => fn,
+            safeInvoke: (fn?: () => void) => fn?.(),
+        }));
         await import('../src/react-router');
         expect(rootFactory).not.toHaveBeenCalled();
         expect((window as unknown as { flare?: unknown }).flare).toBeUndefined();
     });
 
     test('exports traceReactRouter', async () => {
-        vi.doMock('@flareapp/js/browser', () => ({ registerNavigationSource: () => ({}) }));
+        vi.doMock('@flareapp/js/browser', () => ({
+            registerNavigationSource: () => ({}),
+            insulate: (fn: (...a: unknown[]) => void) => fn,
+            safeInvoke: (fn?: () => void) => fn?.(),
+        }));
         const mod = await import('../src/react-router');
         expect(typeof mod.traceReactRouter).toBe('function');
     });

packages/react/tests/react-router.entry.test.ts

@@ -8,7 +8,25 @@ const nav = vi.hoisted(() => ({
     settleNavigation: vi.fn(),
     unregister: vi.fn(),
 }));
-vi.mock('@flareapp/js/browser', () => ({ registerNavigationSource: vi.fn(() => nav) }));
+vi.mock('@flareapp/js/browser', () => ({
+    registerNavigationSource: vi.fn(() => nav),
+    insulate:
+        (fn: (...a: unknown[]) => void) =>
+        (...a: unknown[]) => {
+            try {
+                fn(...a);
+            } catch {
+                /* swallow */
+            }
+        },
+    safeInvoke: (fn?: (() => void) | null) => {
+        try {
+            fn?.();
+        } catch {
+            /* swallow */
+        }
+    },
+}));
 
 import { traceReactRouter } from '../src/react-router';
 import type { RRDataRouter } from '../src/vendor/reactRouterTypes';

packages/react/tests/react-router.integration.test.ts

@@ -7,7 +7,25 @@ const nav = vi.hoisted(() => ({
     settleNavigation: vi.fn(),
     unregister: vi.fn(),
 }));
-vi.mock('@flareapp/js/browser', () => ({ registerNavigationSource: vi.fn(() => nav) }));
+vi.mock('@flareapp/js/browser', () => ({
+    registerNavigationSource: vi.fn(() => nav),
+    insulate:
+        (fn: (...a: unknown[]) => void) =>
+        (...a: unknown[]) => {
+            try {
+                fn(...a);
+            } catch {
+                /* swallow */
+            }
+        },
+    safeInvoke: (fn?: (() => void) | null) => {
+        try {
+            fn?.();
+        } catch {
+            /* swallow */
+        }
+    },
+}));
 
 import { routeNameFromMatches, traceReactRouter } from '../src/react-router';
 import type { RRMatch, RRRouterState } from '../src/vendor/reactRouterTypes';