@syntrologie/adapt-nav 2.8.0-canary.7 → 2.8.0-canary.71

package/dist/NavWidget.d.ts

@@ -25,7 +25,7 @@ export declare const NavMountableWidget: {
     mount(container: HTMLElement, config?: NavConfig & {
         runtime?: NavWidgetRuntime;
         instanceId?: string;
-    }): () => void;
+    }): (() => void) | undefined;
 };
 export default NavWidget;
 //# sourceMappingURL=NavWidget.d.ts.map

package/dist/NavWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavWidget.d.ts","sourceRoot":"","sources":["../src/NavWidget.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAgB,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA8PzF;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,cAAc,2CAmMxE;AAMD;;GAEG;AACH,eAAO,MAAM,kBAAkB;qBAEhB,WAAW,WACb,SAAS,GAAG;QAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CAiD3E,CAAC;AAEF,eAAe,SAAS,CAAC"}
+{"version":3,"file":"NavWidget.d.ts","sourceRoot":"","sources":["../src/NavWidget.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAgB,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAkVzF;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,cAAc,2CA8NxE;AAMD;;GAEG;AACH,eAAO,MAAM,kBAAkB;qBAEhB,WAAW,WACb,SAAS,GAAG;QAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CA2B3E,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/NavWidget.js

@@ -11,6 +11,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { purple, slateGrey } from '@syntro/design-system/tokens';
 import React, { useCallback, useEffect, useMemo, useReducer, useState } from 'react';
 import { createRoot } from 'react-dom/client';
+import { navigateWithFrameworkRouter } from './runtime';
+// ============================================================================
+// Emoji → Lucide SVG inline mapping (no lucide-react dependency)
+// ============================================================================
+const EMOJI_SVG_MAP = {
+    '💵': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="20" height="12" x="2" y="6" rx="2"/><circle cx="12" cy="12" r="2"/><path d="M6 12h.01M18 12h.01"/></svg>',
+    '🏛️': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="3" x2="21" y1="22" y2="22"/><line x1="6" x2="6" y1="18" y2="11"/><line x1="10" x2="10" y1="18" y2="11"/><line x1="14" x2="14" y1="18" y2="11"/><line x1="18" x2="18" y1="18" y2="11"/><polygon points="12 2 20 7 4 7"/></svg>',
+    '⏭️': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 4 15 12 5 20 5 4"/><line x1="19" x2="19" y1="5" y2="19"/></svg>',
+    '➡️': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg>',
+    '💡': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/></svg>',
+    '💰': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="20" height="12" x="2" y="6" rx="2"/><circle cx="12" cy="12" r="2"/><path d="M6 12h.01M18 12h.01"/></svg>',
+    '📋': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="8" height="4" x="8" y="2" rx="1" ry="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><path d="M12 11h4"/><path d="M12 16h4"/><path d="M8 11h.01"/><path d="M8 16h.01"/></svg>',
+    '✅': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/></svg>',
+    '⚠️': '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>',
+};
+function renderIcon(emoji) {
+    return EMOJI_SVG_MAP[emoji] ?? escapeHtml(emoji);
+}
 // ============================================================================
 // Sanitization
 // ============================================================================
@@ -127,7 +145,8 @@ const themeStyles = {
             color: 'var(--sc-content-text-secondary-color)',
         },
         linkButton: {
-            backgroundColor: 'var(--sc-color-primary, #6366f1)',
+            // purple[4] = #6a59ce — design system primary purple, used as fallback when --sc-color-primary is not set
+            backgroundColor: `var(--sc-color-primary, ${purple[4]})`,
             color: '#ffffff',
         },
         categoryHeader: {
@@ -160,7 +179,8 @@ const themeStyles = {
             color: 'var(--sc-content-text-secondary-color)',
         },
         linkButton: {
-            backgroundColor: 'var(--sc-color-primary, #6366f1)',
+            // purple[4] = #6a59ce — design system primary purple, used as fallback when --sc-color-primary is not set
+            backgroundColor: `var(--sc-color-primary, ${purple[4]})`,
             color: '#ffffff',
         },
         categoryHeader: {
@@ -171,10 +191,36 @@ const themeStyles = {
         },
     },
 };
-function NavTipItem({ item, isExpanded, isLast, onToggle, onNavigate, theme }) {
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Check if any of the given routes match the current page pathname */
+function routeMatchesCurrent(routes) {
+    if (typeof window === 'undefined')
+        return false;
+    const current = window.location.pathname;
+    return routes.some((route) => {
+        // Strip query/hash from route if present
+        const routePath = route.split('?')[0].split('#')[0];
+        // Exact match or glob pattern (** suffix)
+        if (routePath.endsWith('/**')) {
+            return current.startsWith(routePath.slice(0, -3));
+        }
+        return current === routePath;
+    });
+}
+/** Apply a brief pulse animation to an element, then remove it */
+function pulseElement(el) {
+    const keyframes = [
+        { boxShadow: '0 0 0 0 rgba(13, 148, 136, 0.5)' },
+        { boxShadow: '0 0 0 8px rgba(13, 148, 136, 0)' },
+    ];
+    el.animate(keyframes, { duration: 600, iterations: 3, easing: 'ease-out' });
+}
+function NavTipItem({ item, isExpanded, isLast, onToggle, onNavigate, onFocusAnchor, theme, }) {
     const [isHovered, setIsHovered] = useState(false);
     const colors = themeStyles[theme];
-    const { title, description, href, icon, external } = item.config;
+    const { title, description, href, icon, external, anchor } = item.config;
     const itemStyle = {
         ...baseStyles.item,
         ...colors.item,
@@ -196,14 +242,36 @@ function NavTipItem({ item, isExpanded, isLast, onToggle, onNavigate, theme }) {
         maxHeight: isExpanded ? '500px' : '0',
         paddingBottom: isExpanded ? '16px' : '0',
     };
+    // Determine the effective navigation target from anchor or legacy href
+    const effectiveHref = anchor
+        ? Array.isArray(anchor.route)
+            ? anchor.route[0]
+            : anchor.route
+        : href;
+    // Same-page check: anchor exists, selector is meaningful, and route matches current page
+    const isSamePage = anchor
+        ? routeMatchesCurrent(Array.isArray(anchor.route) ? anchor.route : [anchor.route])
+        : effectiveHref
+            ? routeMatchesCurrent([effectiveHref])
+            : false;
+    const hasSelector = anchor?.selector && anchor.selector !== '*';
+    const isFocusAction = isSamePage && hasSelector;
+    const hasAction = !!effectiveHref || isFocusAction;
     const handleLinkClick = (e) => {
         e.preventDefault();
         e.stopPropagation();
-        if (href) {
-            onNavigate(href, external ?? false);
+        if (isFocusAction && anchor) {
+            onFocusAnchor(anchor);
+        }
+        else if (effectiveHref) {
+            onNavigate(effectiveHref, external ?? false);
         }
     };
-    return (_jsxs("div", { style: itemStyle, "data-nav-tip-id": item.config.id, children: [_jsxs("button", { type: "button", style: headerStyle, onClick: onToggle, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), "aria-expanded": isExpanded, children: [icon && _jsx("span", { style: baseStyles.icon, children: icon }), _jsx("span", { children: title }), _jsx("span", { style: chevronStyle, children: '\u203A' })] }), _jsxs("div", { style: bodyStyle, "aria-hidden": !isExpanded, children: [_jsx("p", { style: baseStyles.description, children: description }), href && (_jsxs("a", { href: href, onClick: handleLinkClick, style: { ...baseStyles.linkButton, ...colors.linkButton }, target: external ? '_blank' : undefined, rel: external ? 'noopener noreferrer' : undefined, children: ["Go ", external ? '\u2197' : '\u2192'] }))] })] }));
+    // CTA label
+    const ctaLabel = isFocusAction ? `Focus \u2192` : external ? `Go \u2197` : `Go \u2192`;
+    return (_jsxs("div", { style: itemStyle, "data-nav-tip-id": item.config.id, children: [_jsxs("button", { type: "button", style: headerStyle, onClick: onToggle, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), "aria-expanded": isExpanded, children: [icon && (
+                    // biome-ignore lint/security/noDangerouslySetInnerHtml: renderIcon returns sanitized SVG from EMOJI_SVG_MAP or escapeHtml
+                    _jsx("span", { style: baseStyles.icon, dangerouslySetInnerHTML: { __html: renderIcon(icon) } })), _jsx("span", { children: title }), _jsx("span", { style: chevronStyle, children: '\u203A' })] }), _jsxs("div", { style: bodyStyle, "aria-hidden": !isExpanded, children: [_jsx("p", { style: baseStyles.description, children: description }), hasAction && (_jsx("a", { href: effectiveHref || '#', onClick: handleLinkClick, style: { ...baseStyles.linkButton, ...colors.linkButton }, target: external ? '_blank' : undefined, rel: external ? 'noopener noreferrer' : undefined, children: ctaLabel }))] })] }));
 }
 // ============================================================================
 // NavWidget Component
@@ -329,11 +397,32 @@ export function NavWidget({ config, runtime, instanceId }) {
             window.open(href, '_blank', 'noopener,noreferrer');
         }
         else {
+            // Try the host framework's native router first (Next.js, Nuxt, etc.)
+            // Falls back to pushState for vanilla SPAs.
             const url = new URL(href, window.location.origin);
             url.search = window.location.search;
-            window.location.href = url.toString();
+            if (!navigateWithFrameworkRouter(url.toString())) {
+                window.history.pushState(null, '', url.toString());
+                window.dispatchEvent(new PopStateEvent('popstate'));
+            }
         }
     }, [runtime.events, instanceId]);
+    // Handle same-page anchor focus: scroll + pulse + focus
+    const handleFocusAnchor = useCallback((anchor) => {
+        const el = document.querySelector(anchor.selector);
+        if (!(el instanceof HTMLElement))
+            return;
+        runtime.events.publish('nav:tip_focused', {
+            instanceId,
+            selector: anchor.selector,
+            route: anchor.route,
+            timestamp: Date.now(),
+        });
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        pulseElement(el);
+        // Focus after scroll completes
+        setTimeout(() => el.focus(), 400);
+    }, [runtime.events, instanceId]);
     // Compute container styles
     const containerStyle = {
         ...baseStyles.container,
@@ -348,7 +437,7 @@ export function NavWidget({ config, runtime, instanceId }) {
         ...themeStyles[resolvedTheme].emptyState,
     };
     // Render a list of nav tip items
-    const renderItems = (items) => items.map((tip, index) => (_jsx(NavTipItem, { item: tip, isExpanded: expandedIds.has(tip.config.id), isLast: index === items.length - 1, onToggle: () => handleToggle(tip.config.id), onNavigate: handleNavigate, theme: resolvedTheme }, tip.config.id)));
+    const renderItems = (items) => items.map((tip, index) => (_jsx(NavTipItem, { item: tip, isExpanded: expandedIds.has(tip.config.id), isLast: index === items.length - 1, onToggle: () => handleToggle(tip.config.id), onNavigate: handleNavigate, onFocusAnchor: handleFocusAnchor, theme: resolvedTheme }, tip.config.id)));
     // Empty state
     if (visibleTips.length === 0) {
         return (_jsx("div", { style: containerStyle, "data-adaptive-id": instanceId, "data-adaptive-type": "adaptive-nav", children: _jsx("div", { style: emptyStateStyle, children: "You're all set for now! We'll share helpful tips here when they're relevant to what you're doing." }) }));
@@ -382,24 +471,6 @@ export const NavMountableWidget = {
                 root.unmount();
             };
         }
-        // HTML fallback for non-React environments
-        const tips = navConfig.actions || [];
-        container.innerHTML = `
-      <div style="font-family: system-ui; max-width: 100%;">
-        ${tips
-            .map((tip) => `
-          <div style="margin-bottom: 4px; padding: 12px 16px; background: ${slateGrey[12]}; border-radius: 8px;">
-            ${tip.config.icon ? `<span>${escapeHtml(tip.config.icon)}</span> ` : ''}<strong>${escapeHtml(tip.config.title)}</strong>
-            <p style="margin-top: 8px; color: ${slateGrey[6]}; font-size: 13px;">${escapeHtml(tip.config.description)}</p>
-            ${tip.config.href ? `<a href="${escapeHtml(tip.config.href)}" style="color: ${purple[2]}; font-size: 13px;">Go &rarr;</a>` : ''}
-          </div>
-        `)
-            .join('')}
-      </div>
-    `;
-        return () => {
-            container.innerHTML = '';
-        };
     },
 };
 export default NavWidget;

package/dist/cdn.d.ts

@@ -25,7 +25,7 @@ export declare const manifest: {
                 mount(container: HTMLElement, config?: import("./types").NavConfig & {
                     runtime?: import("./types").NavWidgetRuntime;
                     instanceId?: string;
-                }): () => void;
+                }): (() => void) | undefined;
             };
             metadata: {
                 name: string;

package/dist/cdn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdn.d.ts","sourceRoot":"","sources":["../src/cdn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAA0B,MAAM,UAAU,CAAC;AAGlD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;2BAsCgpZ,CAAC;8BAA8B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAtB1qZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;CAQjD,CAAC;AAaF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"cdn.d.ts","sourceRoot":"","sources":["../src/cdn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAA0B,MAAM,UAAU,CAAC;AAGlD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;2BAsCmymB,CAAC;8BAA8B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAtB7zmB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;CAQjD,CAAC;AAaF,eAAe,QAAQ,CAAC"}

package/dist/runtime.d.ts

@@ -10,6 +10,16 @@ import type { ActionExecutor, NavigateAction, ScrollToAction } from './types';
  * Execute a scrollTo action
  */
 export declare const executeScrollTo: ActionExecutor<ScrollToAction>;
+/**
+ * Try to navigate using the host framework's native router.
+ * Returns true if a framework router handled the navigation,
+ * false if no framework was detected (caller should use pushState or location.href).
+ *
+ * Using the native router preserves SPA behavior (no full reload),
+ * layout state, scroll position, and framework-specific features
+ * (RSC streaming, view transitions, etc.).
+ */
+export declare function navigateWithFrameworkRouter(url: string): boolean;
 /**
  * Execute a navigate action
  */
@@ -56,7 +66,7 @@ export declare const runtime: {
             mount(container: HTMLElement, config?: import("./types").NavConfig & {
                 runtime?: import("./types").NavWidgetRuntime;
                 instanceId?: string;
-            }): () => void;
+            }): (() => void) | undefined;
         };
         metadata: {
             name: string;

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,cAAc,EAEd,cAAc,EAEd,cAAc,EACf,MAAM,SAAS,CAAC;AAMjB;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,cAAc,CA+B1D,CAAC;AAgBF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,cAAc,CAoC1D,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;EAGZ,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;IAMlB;;OAEG;;;;;;;;IAGH;;OAEG;;;;;uBAqCy8R,CAAC;0BAA8B,CAAC;;;;;;;;;IAxB5+R;;;;OAIG;0BACmB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;CAgB9C,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,cAAc,EAEd,cAAc,EAEd,cAAc,EACf,MAAM,SAAS,CAAC;AAMjB;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,cAAc,CA+B1D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAgDhE;AAgBD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,cAAc,CAuC1D,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;EAGZ,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;IAMlB;;OAEG;;;;;;;;IAGH;;OAEG;;;;;uBAqC6lb,CAAC;0BAA8B,CAAC;;;;;;;;;IAxBhob;;;;OAIG;0BACmB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;CAgB9C,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/runtime.js

@@ -36,6 +36,61 @@ export const executeScrollTo = async (action, context) => {
         },
     };
 };
+/**
+ * Try to navigate using the host framework's native router.
+ * Returns true if a framework router handled the navigation,
+ * false if no framework was detected (caller should use pushState or location.href).
+ *
+ * Using the native router preserves SPA behavior (no full reload),
+ * layout state, scroll position, and framework-specific features
+ * (RSC streaming, view transitions, etc.).
+ */
+export function navigateWithFrameworkRouter(url) {
+    if (typeof window === 'undefined')
+        return false;
+    const w = window;
+    // Next.js �� window.next.router.push() triggers App Router navigation
+    // with RSC fetch, layout preservation, and loading states
+    try {
+        const nextRouter = w.next?.router;
+        if (nextRouter?.push) {
+            nextRouter.push(url);
+            return true;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // Nuxt 3 — useRouter() isn't accessible from outside Vue, but
+    // $nuxt.$router (Nuxt 2) or window.__NUXT__?.hooks (Nuxt 3) + navigateTo
+    // aren't reliably exposed. Nuxt 2 exposes $nuxt.$router.push().
+    try {
+        if (w.$nuxt?.$router?.push) {
+            w.$nuxt.$router.push(url);
+            return true;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // Angular — Angular Router isn't exposed on window by default.
+    // The most reliable approach is to detect Angular and use location.href.
+    if (w.ng || w.getAllAngularRootElements || document.querySelector('[ng-version]')) {
+        window.location.href = url;
+        return true;
+    }
+    // SvelteKit — goto() isn't on window, but __SVELTEKIT_DATA__ confirms the framework.
+    if (w.__SVELTEKIT_DATA__ || document.body?.hasAttribute('data-sveltekit')) {
+        window.location.href = url;
+        return true;
+    }
+    // Astro (View Transitions) — no client-side router API exposed
+    if (document.querySelector('[data-astro-transition-fallback]')) {
+        window.location.href = url;
+        return true;
+    }
+    return false;
+}
 /**
  * Check if a URL is same-origin as the current page.
  * Relative URLs (e.g. "/dashboard") are always same-origin.
@@ -71,9 +126,12 @@ export const executeNavigate = async (action, context) => {
         window.open(url, '_blank', 'noopener,noreferrer');
     }
     else if (!action.forceFullNavigation && isSameOrigin(url)) {
-        // SPA-aware: use pushState for same-origin URLs to avoid full page reload
-        window.history.pushState(null, '', url);
-        window.dispatchEvent(new PopStateEvent('popstate'));
+        // Try the host framework's native router first (Next.js, Nuxt, Angular, etc.)
+        // Falls back to pushState for vanilla SPAs, or location.href as last resort.
+        if (!navigateWithFrameworkRouter(url)) {
+            window.history.pushState(null, '', url);
+            window.dispatchEvent(new PopStateEvent('popstate'));
+        }
     }
     else {
         // Full navigation for cross-origin URLs or when explicitly requested