docs(discovery): add useNavigation composable and step ID debug display

- Extract drawer state from AppStore into useNavigation composable
- Add SSR guard to prevent state pollution across server renders
- Add navigation context to Discovery tour handlers
- Display current step ID in DiscoveryContent (DEV only)

Author: johnleider

apps/docs/src/components/app/AppBar.vue

@@ -6,6 +6,7 @@
   import { Discovery } from '@/components/discovery'
 
   // Composables
+  import { useNavigation } from '@/composables/useNavigation'
   import { useSearch } from '@/composables/useSearch'
   import { useSettings } from '@/composables/useSettings'
 
@@ -16,12 +17,9 @@
   // Types
   import type { AtomProps } from '@vuetify/v0'
 
-  // Stores
-  import { useAppStore } from '@/stores/app'
-
   const { as = 'header' } = defineProps<AtomProps>()
 
-  const app = useAppStore()
+  const navigation = useNavigation()
   const storage = useStorage()
   const route = useRoute()
 
@@ -64,13 +62,13 @@
 
       <button
         v-if="!isHomePage"
-        :aria-expanded="app.drawer"
-        :aria-label="app.drawer ? 'Close navigation' : 'Open navigation'"
+        :aria-expanded="navigation.isOpen.value"
+        :aria-label="navigation.isOpen.value ? 'Close navigation' : 'Open navigation'"
         class="pa-1 cursor-pointer md:hidden bg-transparent border-0 inline-flex align-center"
         type="button"
-        @click="app.drawer = !app.drawer"
+        @click="navigation.toggle()"
       >
-        <AppIcon :icon="app.drawer ? 'close' : 'menu'" />
+        <AppIcon :icon="navigation.isOpen.value ? 'close' : 'menu'" />
       </button>
 
       <Discovery.Activator class="rounded-2xl" step="search">

apps/docs/src/components/app/AppNav.vue

@@ -8,6 +8,7 @@
   // Composables
   import { useLevelFilterContext } from '@/composables/useLevelFilter'
   import { useNavConfigContext } from '@/composables/useNavConfig'
+  import { useNavigation } from '@/composables/useNavigation'
   import { createNavNested } from '@/composables/useNavNested'
   import { useSettings } from '@/composables/useSettings'
 
@@ -26,6 +27,7 @@
   const devmode = useFeatures().get('devmode')!
 
   const app = useAppStore()
+  const navigation = useNavigation()
   const { selectedLevels } = useLevelFilterContext()
   const { configuredNav, activeFeatures, clearFilter } = useNavConfigContext()
   const route = useRoute()
@@ -116,16 +118,16 @@
   useClickOutside(
     () => navRef.value,
     () => {
-      if (app.drawer && isMobile.value) {
-        app.drawer = false
+      if (navigation.isOpen.value && isMobile.value) {
+        navigation.close()
       }
     },
     { ignore: ['[data-app-bar]'] },
   )
 
   watch(route, () => {
-    if (app.drawer && isMobile.value) {
-      app.drawer = false
+    if (navigation.isOpen.value && isMobile.value) {
+      navigation.close()
     }
   }, { immediate: true })
 </script>
@@ -141,10 +143,10 @@
     :class="[
       'flex flex-col fixed w-[230px] overflow-y-auto py-4 top-0 md:top-[72px] bottom-0 translate-x-[-100%] md:translate-x-0 border-r border-solid border-divider z-10',
       showBgGlass ? 'bg-glass-surface' : 'bg-surface',
-      app.drawer && '!translate-x-0',
+      navigation.isOpen.value && '!translate-x-0',
       !prefersReducedMotion && 'transition-transform duration-200 ease-in-out',
     ]"
-    :inert="!app.drawer && isMobile ? true : undefined"
+    :inert="!navigation.isOpen.value && isMobile ? true : undefined"
     step="navigation"
   >
 

apps/docs/src/components/discovery/DiscoveryContent.vue

@@ -35,6 +35,7 @@
   const root = useDiscoveryRootContext('v0:discovery')
   const discovery = useDiscovery()
   const isReady = shallowRef(false)
+  const isDev = import.meta.env.DEV
 
   // Check for CSS Anchor Positioning support
   // Safari/iOS don't support anchor positioning - check for the specific property
@@ -153,6 +154,10 @@
         zIndex: 9999,
       }"
     >
+      <div v-if="isDev" class="font-mono text-xs text-on-surface-variant/50 mb-1">
+        {{ root.step }}
+      </div>
+
       <slot />
     </div>
   </Teleport>

apps/docs/src/components/docs/DocsAskInput.vue

@@ -9,10 +9,7 @@
   import { useAsk } from '@/composables/useAsk'
 
   // Utilities
-  import { computed, onMounted, shallowRef, useTemplateRef, nextTick, watch } from 'vue'
-
-  // Stores
-  import { useAppStore } from '@/stores/app'
+  import { onMounted, shallowRef, useTemplateRef, nextTick, watch } from 'vue'
 
   const props = defineProps<{
     hasMessages?: boolean
@@ -23,7 +20,6 @@
     reopen: []
   }>()
 
-  const app = useAppStore()
   const ask = useAsk()
 
   watch(ask.focusTrigger, () => {
@@ -34,10 +30,6 @@
 
   const formRef = useTemplateRef<{ focus: () => void }>('form')
   const isNearBottom = shallowRef(false)
-  const isMobile = shallowRef(true)
-
-  // Hide when near bottom, or when drawer is open on mobile (< 768px)
-  const isHidden = computed(() => isNearBottom.value || (app.drawer && isMobile.value))
 
   function onSubmit (question: string) {
     emit('submit', question)
@@ -61,17 +53,10 @@
     isNearBottom.value = distanceFromBottom < 200
   }
 
-  function updateMobile () {
-    if (!IN_BROWSER) return
-    isMobile.value = window.innerWidth < 768
-  }
-
   useWindowEventListener('scroll', onScroll, { passive: true })
-  useWindowEventListener('resize', updateMobile, { passive: true })
 
   onMounted(() => {
     onScroll()
-    updateMobile()
   })
 
   defineExpose({ focus })
@@ -80,7 +65,7 @@
 <template>
   <Transition name="fade">
     <div
-      v-show="!isHidden"
+      v-show="!isNearBottom"
       class="fixed bottom-4 inset-x-0 mx-auto z-40 w-full max-w-sm px-4"
     >
       <Discovery.Activator class="rounded-2xl" step="ask-ai">

apps/docs/src/composables/useNavigation.ts

@@ -0,0 +1,83 @@
+/**
+ * @module useNavigation
+ *
+ * @remarks
+ * Controls the main navigation drawer open/close state.
+ * Module-level singleton state shared across all useNavigation calls.
+ */
+
+// Framework
+import { IN_BROWSER } from '@vuetify/v0'
+
+// Utilities
+import { readonly, shallowRef } from 'vue'
+
+// Types
+import type { ShallowRef } from 'vue'
+
+export interface NavigationContext {
+  /** Whether the drawer is open */
+  isOpen: Readonly<ShallowRef<boolean>>
+  /** Open the drawer */
+  open: () => void
+  /** Close the drawer */
+  close: () => void
+  /** Toggle the drawer */
+  toggle: () => void
+}
+
+let context: NavigationContext | null = null
+
+/**
+ * Controls the navigation drawer state.
+ *
+ * @returns Navigation state and controls
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ *   import { useNavigation } from '@/composables/useNavigation'
+ *
+ *   const navigation = useNavigation()
+ *
+ *   // Open the drawer
+ *   navigation.open()
+ * </script>
+ * ```
+ */
+export function useNavigation (): NavigationContext {
+  // SSR: return fresh noop context for each server render
+  if (!IN_BROWSER) {
+    return {
+      isOpen: readonly(shallowRef(false)),
+      open: () => {},
+      close: () => {},
+      toggle: () => {},
+    }
+  }
+
+  if (context) return context
+
+  const isOpen = shallowRef(false)
+
+  function open () {
+    isOpen.value = true
+  }
+
+  function close () {
+    isOpen.value = false
+  }
+
+  function toggle () {
+    isOpen.value = !isOpen.value
+  }
+
+  context = {
+    isOpen: readonly(isOpen),
+    open,
+    close,
+    toggle,
+  }
+
+  return context
+}

apps/docs/src/layouts/default.vue

@@ -7,6 +7,7 @@
   import { useDiscovery } from '@/composables/useDiscovery'
   import { createLevelFilter } from '@/composables/useLevelFilter'
   import { createNavConfig } from '@/composables/useNavConfig'
+  import { useNavigation } from '@/composables/useNavigation'
   import { useScrollLock } from '@/composables/useScrollLock'
   import { useSearch } from '@/composables/useSearch'
   import { useSettings } from '@/composables/useSettings'
@@ -32,6 +33,7 @@
   const breakpoints = useBreakpoints()
   const discovery = useDiscovery()
   const ask = useAsk()
+  const navigation = useNavigation()
   const { isOpen: isSearchOpen } = useSearch()
   const { isOpen: isSettingsOpen, close: closeSettings, prefersReducedMotion, forceReducedMotion } = useSettings()
 
@@ -50,7 +52,7 @@
     return false
   })
 
-  const isMobileNavOpen = toRef(() => app.drawer && !breakpoints.mdAndUp.value)
+  const isMobileNavOpen = toRef(() => navigation.isOpen.value && !breakpoints.mdAndUp.value)
 
   useScrollLock(isSettingsOpen)
   useScrollLock(isMobileNavOpen)
@@ -82,7 +84,7 @@
       <div
         v-if="isMobileNavOpen"
         class="fixed inset-0 bg-black/30 z-9"
-        @click="app.drawer = false"
+        @click="navigation.close()"
       />
     </Transition>
 

apps/docs/src/pages/skillz.[id].vue

@@ -8,6 +8,7 @@
   // Composables
   import { useAsk } from '@/composables/useAsk'
   import { useDiscovery } from '@/composables/useDiscovery'
+  import { useNavigation } from '@/composables/useNavigation'
   import { useParams } from '@/composables/useRoute'
   import { useSettings } from '@/composables/useSettings'
 
@@ -25,6 +26,7 @@
   const params = useParams<{ id: string }>()
   const discovery = useDiscovery()
   const ask = useAsk()
+  const navigation = useNavigation()
   const router = useRouter()
   const tour = discovery.tours.get(params.value.id)
 
@@ -41,7 +43,7 @@
     if (!tour) return
 
     await router.push(tour.startRoute)
-    discovery.start(tour.id, { stepId, context: { ask, settings } })
+    discovery.start(tour.id, { stepId, context: { ask, navigation, settings } })
   }
 </script>
 

apps/docs/src/skillz/tours/beginner/using-the-docs/index.ts

@@ -1,27 +1,31 @@
 // Types
 import type { UseAskReturn } from '@/composables/useAsk'
+import type { NavigationContext } from '@/composables/useNavigation'
 import type { SettingsContext } from '@/composables/useSettings'
 
 interface TourContext {
   ask: UseAskReturn
+  navigation: NavigationContext
   settings: SettingsContext
 }
 
 /**
  * Returns tour definition for registration by the store.
  * Guided mode: handlers set up UI state to show features, users just click next.
  */
-export function defineTour ({ ask, settings }: TourContext) {
+export function defineTour ({ ask, navigation, settings }: TourContext) {
   return {
     handlers: {
       'ask-ai': {
+        enter: () => ask.close(),
         leave: () => ask.close(),
         back: () => ask.close(),
       },
       'ask-ai-panel': {
         enter: () => ask.open(),
       },
       'ask-ai-features': {
+        enter: () => ask.open(),
         back: () => ask.open(),
       },
       'settings': {
@@ -30,15 +34,16 @@ export function defineTour ({ ask, settings }: TourContext) {
       },
       'skill-level': {
         enter: () => settings.open(),
+        back: () => settings.close(),
         leave: () => settings.close(),
       },
       'navigation': {
         enter: () => {
           settings.close()
-          // TODO: app().drawer = true - needs app store in context
+          navigation.open()
         },
-        leave: () => {
-          // TODO: app().drawer = false - needs app store in context
+        back: () => {
+          navigation.close()
         },
       },
     },

apps/docs/src/stores/app.ts

@@ -35,7 +35,6 @@ function flattenRoutes (nav: NavItem): string[] {
 
 export const useAppStore = defineStore('app', {
   state: () => ({
-    drawer: false,
     nav: navData as NavItem[],
     stats: {
       commit: null as Commit | null,