fix(showcase/shell-docs): eliminate URL flicker on unscoped navigation

SidebarLink now uses storedFramework as fallback so links on the
overview page go directly to /<framework>/<slug> without a RouterPivot
redirect. OverviewNavItem and section cards now use SidebarLink for the
same reason. FrameworkSelector "Clear selection" was navigating to
/docs/<slug> (broken); fixed to /<slug>. hrefFor now preserves the
current slug when switching frameworks from an unscoped page.

Author: samjulien

showcase/shell-docs/src/app/[[...slug]]/page.tsx

@@ -15,6 +15,7 @@ import {
   RouterPivot,
 } from "@/components/router-pivot";
 import { SidebarFrameworkSelector } from "@/components/sidebar-framework-selector";
+import { SidebarLink } from "@/components/sidebar-link";
 import { SidebarNav } from "@/components/sidebar-nav";
 import { StoredFrameworkHighlight } from "@/components/stored-framework-highlight";
 import {
@@ -264,9 +265,9 @@ function DocsOverview() {
               </div>
               <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
                 {sections.map((s) => (
-                  <Link
+                  <SidebarLink
                     key={s.href}
-                    href={s.href}
+                    slug={s.href.slice(1)}
                     className="group p-4 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] hover:border-[var(--accent)] transition-all"
                   >
                     <div className="text-sm font-semibold text-[var(--text)] group-hover:text-[var(--accent)] mb-1">
@@ -275,7 +276,7 @@ function DocsOverview() {
                     <div className="text-xs text-[var(--text-muted)] leading-relaxed">
                       {s.description}
                     </div>
-                  </Link>
+                  </SidebarLink>
                 ))}
               </div>
             </div>
@@ -315,13 +316,14 @@ function OverviewNavItem({
   }
   if (node.type === "page") {
     return (
-      <Link
-        href={`/${node.slug}`}
-        className="block py-[5px] text-[13px] text-[var(--text-muted)] hover:text-[var(--text-secondary)] transition-colors"
-        style={{ paddingLeft: `${indent}px` }}
-      >
-        {node.title}
-      </Link>
+      <div style={{ paddingLeft: `${indent}px` }}>
+        <SidebarLink
+          slug={node.slug}
+          className="block py-[5px] text-[13px] text-[var(--text-muted)] hover:text-[var(--text-secondary)] transition-colors"
+        >
+          {node.title}
+        </SidebarLink>
+      </div>
     );
   }
   return (

showcase/shell-docs/src/components/framework-selector.tsx

@@ -123,11 +123,17 @@ export function FrameworkSelector({
     if (frameworkTail !== null) {
       return frameworkTail ? `/${slug}/${frameworkTail}` : `/${slug}`;
     }
-    // Case 2: currently on /docs/<rest> — switch to framework-scoped
+    // Case 2: currently on /docs/<rest> — switch to framework-scoped (legacy)
     const docsTail = stripDocsPrefix(pathname);
     if (docsTail !== null && docsTail.length > 0) {
       return `/${slug}/${docsTail}`;
     }
+    // Case 3: currently on /<unscoped-slug> (e.g. /quickstart) — preserve the
+    // feature slug so switching frameworks keeps the user on the same topic.
+    const unscopedTail = pathname.split("/").filter(Boolean).join("/");
+    if (unscopedTail) {
+      return `/${slug}/${unscopedTail}`;
+    }
     // Fallback: framework landing page
     return `/${slug}`;
   }
@@ -275,9 +281,7 @@ export function FrameworkSelector({
                   knownFrameworks,
                 );
                 if (frameworkTail !== null) {
-                  router.replace(
-                    frameworkTail ? `/docs/${frameworkTail}` : "/docs",
-                  );
+                  router.replace(frameworkTail ? `/${frameworkTail}` : "/");
                 }
                 setOpen(false);
               }}

showcase/shell-docs/src/components/sidebar-link.tsx

@@ -29,11 +29,15 @@ export function SidebarLink({
   className,
   active,
 }: SidebarLinkProps) {
-  const { framework } = useFramework();
+  const { framework, storedFramework } = useFramework();
 
-  // Use the active framework when set, otherwise fall through to
-  // /<slug>.
-  const href = framework ? `/${framework}/${slug}` : `/${slug}`;
+  // Prefer URL-active framework, then stored preference, then bare slug.
+  // Using storedFramework here means sidebar links on unscoped pages (like
+  // the root overview) navigate directly to the framework-scoped URL —
+  // avoiding the visible RouterPivot redirect that would otherwise flicker
+  // in the URL bar.
+  const activeFramework = framework ?? storedFramework;
+  const href = activeFramework ? `/${activeFramework}/${slug}` : `/${slug}`;
 
   return (
     <Link